Initial projects chapter

src/SUMMARY.md

@@ -69,20 +69,24 @@
   * [Comparing Bytes](commandline/comparing_bytes.md)
     * [Watching for Changes](commandline/cmp_watchers.md)
   * [SDB](commandline/sdb.md)
-* [Visual mode](visual/intro.md)
+* [Visual Mode](visual/intro.md)
   * [Visual Disassembly](visual/visual_disassembly.md)
   * [Visual Assembler](visual/visual_assembler.md)
   * [Visual Configuration Editor](visual/visual_configuration_editor.md)
   * [Visual Menus](visual/visual_menus.md)
   * [Visual Panels](visual/visual_panels.md)
-* [Searching data](search/intro.md)
+* [Searching](search/intro.md)
   * [Basic Searches](search/basic_searches.md)
   * [Configurating the Search](search/configurating_the_search.md)
   * [Pattern Search](search/pattern_search.md)
   * [Automation](search/automation.md)
   * [Backward Search](search/backward_search.md)
   * [Search in Assembly](search/search_in_assembly.md)
   * [Cryptographic Materials](search/searching_crypto.md)
+* [Projects](projects/intro.md)
+  * [Usage](projects/usage.md)
+  * [Annotations](projects/annotations.md)
+  * [Handmade Setup](projects/handmade.md)
 * [Disassembling](arch/intro.md)
   * [Decompilers](arch/decompile.md)
   * [Metadata](arch/metadata.md)

src/projects/annotations.md

@@ -0,0 +1,22 @@
+## Annotations
+
+Comment annotations (See the `ano` command) it's a cross-project metadata feature introduced in radare2 5.9.6.
+
+```console
+[0x00000000]> ano?
+Usage: ano  [*] # function anotations
+| ano            show or edit annotations for the current function
+| ano-*          remove all annotations of current file
+| ano*           dump all annotations in ano= commands
+| ano=[b64text]  set anotation text in base64 for current function
+| anoe           edit annotation
+| anos           show annotation
+| anol           show first line of function annotation if any
+[0x00000000]>
+```
+
+The annotations are not tied to projects or sessions. They are stored in your home as separate files, and they are associated with each function.
+
+This is useful because you can have a multiline comment for each function where you drop some notes, paste the decompilation output, etc and you can leave the shell without worrying about saving it later.
+
+These files are stored in the cache subdirectory of the radare2 datadir: `~/.local/share/radare2/cache`.

src/projects/handmade.md

@@ -0,0 +1,60 @@
+## Handmade Projects
+
+When you need full control and complete flexibility about your project metadata you can opt out to create a set of scripts that load the binary, setting the base address, setup the memory layout, run the analysis commands of interest, create flags, add comments, run other scripts autogenerated from SVD or other files with just one entrypoint.
+
+The main inconvenience of these projects is that comments, flags or function names won't be saved to disk when leaving the session. We will need to manually type them into the scripts everytime we find them necessary.
+
+This setup requires some level of consistency from the users and also must get used to the workflow to avoid
+
+As long as handmade projects are organized in directories and files it is ideal to use it with git, allowing other people to jump into the same files and have a proper versioned.
+
+### Setup the files
+
+First of all we will create a directory to contain the binar(y/ies) you want to work on. Then you can create a **Makefile** or a shellscript with the commands to run like this:
+
+```console
+$ mkdir project/bins
+$ cd project
+
+$ cp /bin/ls bins/ls
+$ echo r2 -s main -i script.r2 bins/ls > main.sh
+$ chmod +x main.sh
+```
+
+Now you can run edit `script.r2` with the commands you like:
+
+```
+aaa
+CC good boy @ sym.success
+```
+
+You can just run `./main.sh` everytime you want to open the handmade project. Note that you can create custom memory maps. Load the contents of ram from a file, enable cache, patch instructions, etc..
+
+### Primitives
+
+Most of the radare2 environment is built on top of the shell, and as you may know many commands handle the `*` suffix/subcommand which lists the data in r2 commands.
+
+For example, if you want to save the flags you can do this:
+
+```console
+> f* > flags.r2
+```
+
+Then reload them like this:
+
+```console
+> . flags.r2
+```
+
+Same thing happens for comments `CC*`, function names `afn*@@F`, etc..
+
+### Default Script
+
+If you save an `.r2` file next to the file you are opening, r2 will prompt the user to run it when starting. This way you don't need to use the `-i` flag by yourself.
+
+```bash
+$ echo '?e hello world' > ls.r2
+$ cp /bin/ls .
+$ r2 ls
+Do you want to run the 'ls.r2' script? (y/N)
+```

src/projects/intro.md

@@ -0,0 +1,26 @@
+# Projects
+
+There are some scenarios where you need to work for a long period of time on a single or a set of binaries.
+
+Sometimes when working with large binaries or even if it's small you want to store and keep your progress, the comments, function names, and other metadata so you don't have to handle it when loading the binary again.
+
+This chapter will cover all these needs by exposing the challenges and limitations because, despite looking like a simple problem, projects is one of the hardest issues to cope, and first we need to understand why.
+
+## Challenges
+
+Metadata associated with a binary analysis is an important feature to support for all reverse engineering tools for several reasons, let's explore some of them:
+
+* There's no standard format for saving or sharing it.
+* Tools change over time, its analysis and metadata too.
+* Metadata storage order matters, you can't name a function if its not analyzed
+* Analysis order and steps can affect the final result
+* Projects can be versioned, rebasing it can result on unexpected results
+* Syncing metadata in realtime between different clients can cause conflicts
+* Amount of data tends to be large, storing/loading is slower than keeping it in memory
+* Binaries can be loaded in different addresses, aslr when debugging
+* User settings affect analysis and metadata registration
+* Incremental metadata patches must be stacked up properly
+
+After checking this list we observe how difficult the problem is, and how many of the solutions don't fit in all the possible environments and use cases users will face.
+
+In the case of **radare2**, as long as the tool permits creating so many different configuration paths it is harder to find a way to serialize project information into a file and restoring it back compared to other tools which are tied to much less options.

src/projects/usage.md

@@ -0,0 +1,52 @@
+## Using projects
+
+Projects are the way metadata of your session is saved and restored. All that stuff is stored in a directory. You can open a file, start working on it and then use the `P` command to name the project.
+
+At this moment, an .r2 script is created in the projects directory containing all the commands needed to recreate the state.
+
+```
+[0x00000000]> P?
+Usage: P[?.+-*cdilnsS] [file]  Project management
+| P [file]          open project (formerly Po)
+| P.                show current loaded project (see prj.name)
+| P+ [name]         save project (same as Ps, but doesnt checks for changes)
+| P- [name]         delete project
+| P*                printn project script as r2 commands
+| P!([cmd])         open a shell or run command in the project directory
+| Pc                close current project
+| Pd [N]            diff Nth commit
+| Pi [file]         show project information
+| Pl                list all projects
+| Pn -              edit current loaded project notes using cfg.editor
+| Pn[j]             manage notes associated with the project
+| Ps [file]         save project (see dir.projects)
+| PS [file]         save script file
+| PS* [name]        print the project script file (Like P*, but requires a project)
+| Pz[ie] [zipfile]  import/export r2 project in zip form (.zrp extension)
+| NOTE:             the 'e prj.name' evar can save/open/rename/list projects.
+| NOTE:             see the other 'e??prj.' evars for more options.
+| NOTE:             project are stored in dir.projects
+[0x00000000]>
+```
+
+When leaving, if you want to reopen the project just run it like this: `r2 -p prjname`. No need to specify the file name associated.
+
+```
+ -p [prj]     use project, list if no arg, load if no file
+```
+
+Projects work in `iaito` too and there are several options that may help you tweak the information you want to store. But also, how you want it to be stored.
+
+```
+[0x00000000]> e prj.
+prj.alwasyprompt = false
+prj.files = false
+prj.gpg = false
+prj.history = false
+prj.name =
+prj.sandbox = false
+prj.vc = true
+prj.vc.message =
+prj.vc.type = git
+prj.zip = false
+```

src/projects/version.md

@@ -0,0 +1,7 @@
+# Project Versioning
+
+Radare2 have its own versioning control system. It's like a simple `git`. But also acts as a way to wrap the use of **git** under the same API.
+
+Using the `ravc2` command or its `rvc` counterpart API you can see the project history, revert to previous versions, clone a repository, etc
+
+The benefit of using a version control system for projects is clear when you work with more people, and this is useful too because r2 projects are basically r2 scripts that are easy to read, compare and review.

src/r2fwrev/setup.md

@@ -11,6 +11,7 @@ $ cat Makefile
 BADDR=0x8000000
 all:
     r2 -i script.r2 -m $BADDR dump.bin
+
 $ cat script.r2
 f entry0=0x8005320
 s entry0