Update docs for several commands (#703)

docs/commands/elf-info.md

@@ -20,3 +20,10 @@ ELF Version           : 0x1
 Header size           : 0 (0x0)
 Entry point           : 0x0000000000400460
 ```
+
+Optionally a filepath to another ELF binary can be provided to view the basic
+information for that binary instead.
+
+```
+gef➤ elf-info /path/to/elf/executable
+```

docs/commands/heap-analysis-helper.md

@@ -1,5 +1,7 @@
 ## Command heap-analysis-helper ##
 
+Please note: This feature is still under development, expect bugs and unstability.
+
 `heap-analysis-helper` command aims to help the process of idenfitying Glibc
 heap inconsistencies by tracking and analyzing allocations and deallocations of
 chunks of memory.

docs/commands/help.md

@@ -1,5 +1,7 @@
-## Command help ##
+## Command gef help ##
 
-Displays the help menu for the commands loaded.
+Displays the help menu for the loaded GEF commands.
 
-![help](https://i.imgur.com/cvMoI3P.png)
+```
+gef➤ gef help
+```

docs/commands/hexdump.md

@@ -4,56 +4,52 @@ Imitation of the WinDBG command.
 
 This command takes 4 optional arguments:
 
-  - The format for representing the data (by default, byte)
-  - A value/address/symbol used as the location to print the hexdump from (by default, $sp)
-  - The number of qword/dword/word/bytes to display (by default, 64 if the format is byte, 16 otherwise)
-  - The direction of output lines (by default, from low to high addresses)
-
-The command provides WinDBG compatible aliases by default:
-
-  - `hexdump qword` -> `dq`
-  - `hexdump dword` -> `dd`
-  - `hexdump word` -> `dw`
-  - `hexdump byte` -> `db`
+- The format for representing the data (by default, byte)
+- A value/address/symbol used as the location to print the hexdump from (by
+  default, $sp)
+- The number of qword/dword/word/bytes to display (by default, 64 if the format
+  is byte, 16 otherwise)
+- The direction of output lines (by default, from low to high addresses)
 
 `hexdump byte` will also try to display the ASCII character values if the byte
 is printable (similarly to the `hexdump -C` command on Linux).
 
 The syntax is as following:
 
 ```
-hexdump (qword|dword|word|byte) [LOCATION] [--size SIZE] [--reverse]
+hexdump (qword|dword|word|byte) [-h] [--reverse] [--size SIZE] [address]
 ```
 
 Examples:
 
-   * Display 4 QWORD from `$pc`:
+- Display 4 QWORDs from `$pc`:
 
 ```
-gef➤  dq $pc --size 4
+gef➤  hexdump qword $pc --size 4
 0x7ffff7a5c1c0+0000 │ 0x4855544155415641
 0x7ffff7a5c1c0+0008 │ 0x0090ec814853cd89
 0x7ffff7a5c1c0+0010 │ 0x377d6f058b480000
 0x7ffff7a5c1c0+0018 │ 0x748918247c894800
 ```
 
-  * Display 32 bytes from a location in the stack:
+- Display 32 bytes from a location in the stack:
 
 ```
-gef➤  db 0x00007fffffffe5e5 --size 32
+gef➤  hexdump byte 0x00007fffffffe5e5 --size 32
 0x00007fffffffe5e5     2f 68 6f 6d 65 2f 68 75 67 73 79 2f 63 6f 64 65     /home/hugsy/code
 0x00007fffffffe5f5     2f 67 65 66 2f 74 65 73 74 73 2f 77 69 6e 00 41     /gef/tests/win.A
 ```
 
-  * Display 8 WORD from `$sp` in reverse order:
+- Display 8 WORDs from `$sp` in reverse order:
+
 ```
-gef➤  dw 8 --reverse
-0x00007fffffffe0ee│+0x000e   0x0000   
-0x00007fffffffe0ec│+0x000c   0x7fff   
-0x00007fffffffe0ea│+0x000a   0xffff   
-0x00007fffffffe0e8│+0x0008   0xe3f5   
-0x00007fffffffe0e6│+0x0006   0x0000   
-0x00007fffffffe0e4│+0x0004   0x0000   
-0x00007fffffffe0e2│+0x0002   0x0000   
+gef➤  hexdump word 8 --reverse
+0x00007fffffffe0ee│+0x000e   0x0000
+0x00007fffffffe0ec│+0x000c   0x7fff
+0x00007fffffffe0ea│+0x000a   0xffff
+0x00007fffffffe0e8│+0x0008   0xe3f5
+0x00007fffffffe0e6│+0x0006   0x0000
+0x00007fffffffe0e4│+0x0004   0x0000
+0x00007fffffffe0e2│+0x0002   0x0000
 0x00007fffffffe0e0│+0x0000   0x0001
 ```

docs/commands/process-search.md

@@ -1,11 +1,12 @@
-## Command process-search
+## Command process-search ##
 
 `process-search` (aka `ps`) is a convenience command to list and filter process
 on the host. It is aimed at making the debugging process a little easier when
-targeting forking process (such as tcp/listening daemon that would fork upon new
-connection).
+targeting forking process (such as tcp/listening daemon that would fork upon
+`accept()`).
 
 Without argument, it will return all processes reachable by user:
+
 ```
 gef➤  ps
 1               root            0.0             0.4             ?           /sbin/init
@@ -23,27 +24,31 @@ gef➤  ps
 ```
 
 Or to filter with pattern:
+
 ```
 gef➤  ps bash
 22590           vagrant         0.0             0.8             pts/0       -bash
 ```
 
+Note: Use "\\" for escaping and "\\\\" for a literal backslash" in the pattern.
+
 `ps` also accepts options:
 
-   * `-s` (for `smart`) will discard a number of process (belonging to different
-     user, pattern used as an argument and not command, etc.)
-   * `-a` (for `attach`) will automatically attach to the first process found
+* `--smart-scan` will filter out probably less relevant processes (belonging to
+  different users, pattern matched to arguments instead of the commands
+  themselves, etc.)
+* `--attach` will automatically attach to the first process found
 
-So, for example, if your targeted process is called `/home/foobar/plop`, but the
-existing instance is used through `socat`, like
+So, for example, if your targeted process is called `/home/foobar/plop`, but
+the existing instance is used through `socat`, like
 
 ```
 $ socat tcp-l:1234,fork,reuseaddr exec:/home/foobar/plop
 ```
 
-Every time a new connection is opened to tcp/1234, `plop` will be forked, and
-`gef` can easily attach to it with the command
+Then every time a new connection is opened to tcp/1234, `plop` will be forked,
+and GEF can easily attach to it with the command
 
 ```
-gef➤  ps -as plop
+gef➤  ps --attach --smart-scan plop
 ```

docs/commands/process-status.md

@@ -7,7 +7,7 @@ process, by extending the information provided by GDB `info proc` command, with
 all the information from the `procfs` structure.
 
 ```
-gef➤ ps -s zsh
+gef➤ ps --smart-scan zsh
 22879
 gef➤ attach 22879
 [...]

docs/commands/registers.md

@@ -1,12 +1,12 @@
-## Command registers
+## Command registers ##
 
 The `registers` command will print all the registers and dereference any
-pointers. It does not take any argument.
-
+pointers.
 
 Example on a MIPS host:
+
 ```
-gef> reg
+gef➤ reg
 $zero     : 0x00000000
 $at       : 0x00000001
 $v0       : 0x7fff6cd8 -> 0x77e5e7f8 -> <__libc_start_main+200>: bnez v0,0x77e5e8a8
@@ -48,3 +48,15 @@ $fcsr     : 0x00000000
 $ra       : 0x77e5e834 -> <__libc_start_main+260>: lw gp,16(sp)
 $gp       : 0x00418b20
 ```
+
+### Filtering registers ###
+
+If one or more register names are passed to the `registers` command as optional
+arguments, then only those will be shown:
+
+```
+gef➤ reg $rax $rip $rsp
+$rax   : 0x0000555555555169  →  <main+0> endbr64
+$rsp   : 0x00007fffffffe3e8  →  0x00007ffff7df40b3  →  <__libc_start_main+243> mov edi, eax
+$rip   : 0x0000555555555169  →  <main+0> endbr64
+```

docs/commands/scan.md

@@ -1,7 +1,18 @@
 ## Command scan ##
 
-`scan` Search for addresses that are located in a memory mapping (haystack) that
-belonging to another (needle).
+`scan` searches for addresses of one memory region (needle) inside another
+region (haystack) and lists all results.
+
+Usage:
+
+```
+gef➤  scan NEEDLE HAYSTACK
+```
+
+`scan` requires two arguments, the first is the memory section that will be
+searched and the second is what will be searched for. The arguments are grepped
+against the process's memory mappings (just like [vmmap](./vmmap.md)) to
+determine the memory ranges to search.
 
 ```
 gef➤  scan stack libc
@@ -14,12 +25,10 @@ gef➤  scan stack libc
 [...]
 ```
 
+### Advanced Needle/Haystack syntax ###
 
-`scan` requires two arguments, the first is the memory section that will be
-searched and the second is what will be searched for. The arguments are grepped
-against the processes memory mappings (just like [vmmap](./vmmap.md)
-to determine the memory ranges to search.
+To check mappings without a path associated, an address range (start-end) can
+be used. Note that ranges don't include whitespaces.
 
-To check mappings without a path associated, an address range (start-end) can be used.
+![scan-address](https://i.imgur.com/ExJC2p7.png)
 
-![scan-address](https://i.imgur.com/ExJC2p7.png)

docs/commands/set-permission.md

@@ -1,11 +1,10 @@
 ## Command set-permission ##
 
-
 This command was added to facilitate the exploitation process, by changing the
-permission rights on a specific page directly from the debugger.
+permissions on a specific memory page directly from the debugger.
 
-By default, `GDB` does not allow you to do that, so the command will modify a
-code section of the binary being debugged, and add a native mprotect syscall
+By default, GDB does not allow you to do that, so the command will modify a
+code section of the binary being debugged, and add a native `mprotect` syscall
 stub. For example, for x86, the following stub will be inserted:
 
 ```
@@ -21,8 +20,18 @@ popad
 A breakpoint is added following this stub, which when hit will restore the
 original context, allowing you to resume execution.
 
-`mprotect` is an alias for `set-permission`. As an example, to set the `stack` as
-READ|WRITE|EXECUTE on this binary,
+The usage is
+
+```
+gef➤ set-permission address [permission]
+```
+
+The `permission` can be set using a bitmask as integer with read (1), write (2)
+and execute (4). For combinations of these permissions they can just be added:
+Read and Execute permission would be 1 + 4 = 5.
+
+`mprotect` is an alias for `set-permission`. As an example, to set the `stack`
+as READ|WRITE|EXECUTE on this binary,
 
 ![mprotect-before](https://i.imgur.com/RRYHxzW.png)
 
@@ -32,8 +41,8 @@ Simply run
 gef➤ mprotect 0xfffdd000
 ```
 
-Et voilà ! `gef` will use the memory runtime information to correctly adjust the protection
-of the entire section.
+Et voilà! GEF will use the memory runtime information to correctly adjust the
+permissions of the entire section.
 
 ![mprotect-after](https://i.imgur.com/9MvyQi8.png)
 

docs/commands/tmux-setup.md

@@ -1,10 +1,10 @@
-## Command tmux-setup
+## Command tmux-setup ##
 
 In the purpose of always making debugging sessions easier while being more
 effective, `GEF` integrates two commands:
 
-  * `tmux-setup`
-  * `screen-setup`
+* `tmux-setup`
+* `screen-setup`
 
 Those commands will check whether GDB is being spawn from inside a `tmux`
 (resp. `screen`) session, and if so, will split the pane vertically, and
@@ -13,10 +13,20 @@ configure the context to be redirected to the new pane, looking something like:
 ![](https://i.imgur.com/Khk3xGl.png)
 
 To set it up, simply enter
+
 ```
 gef➤ tmux-setup
 ```
 
 **Note**: Although `screen-setup` provides a similar setup, the structure of
 `screen` does not allow a very clean way to do this. Therefore, if possible, it
 would be recommended to use the `tmux-setup` command instead.
+
+### Possible color issues with tmux ###
+
+On Linux tmux only supports 8 colors with some terminal capabilities (`$TERM`
+environment variable). This can mess up your color themes when using GEF with
+tmux. To remedy this if your terminal supports more colors you can either set
+the variable to something like `TERM=screen-256color` or if you don't want or
+can't change that variable you can start `tmux` with the `-2` flag to force
+tmux to use 256 colors.

docs/commands/version.md

@@ -19,16 +19,18 @@ Otherwise the command shows the `standalone` information:
 ```
 gef➤  version
 GEF: (Standalone)
-Blob Hash(/gef/rules/gef.py): 2939fbc037bca090422e12cf1b555bd58223dccb
-SHA1(/gef/rules/gef.py): 6e6bfd03282a0d5b1eec5276fa57af0ccbac31c6
+Blob Hash(/gef/rules/gef.py): f0aef0f481e8157006b26690bd121585d3befee0
+SHA1(/gef/rules/gef.py): 4b26a1175abcd8314d4816f97fdf908b3837c779
 GDB: 9.2
 GDB-Python: 3.8
 ```
 
 The `Blob Hash` can be used to easily find the git commit(s) matching
-this file revision (or whether it has been modified and does not match
-any revision):
+this file revision.
 
 ```
 git log --oneline --find-object <BLOB_HASH>
 ```
+
+If this command does not return anything then the file was most likely
+modified and cannot be matched to a specific git commit.