Merge pull request #371 from hugsy/dev

w00t w00t

.github/CONTRIBUTING.md

@@ -18,7 +18,7 @@ to release the code written by you under the said license.
     * Comment your code
     * If you add a new feature/GDB command, also write the adequate
       documentation (in [`docs/`](https://github.com/hugsy/gef/docs))
-1. Submit a pull request.
+1. Submit a pull request, **make sure it is made against the `dev` branch (not `master`, which only contains tested and stable features)**
 1. The contributors will review your patch. If it is approved, the change will
    be merged via the GitHub, and you will be seen as contributors. If it needs
    additional work, the repo owner will respond with useful comments.

docs/commands.md

@@ -21,6 +21,7 @@ improve it.
 |elf-info                  | Display ELF header informations.|
 |entry-break               | Tries to find best entry point and sets a temporary breakpoint on it. (alias: start-break)|
 |format-string-helper      | Exploitable format-string helper: this command will set up specific breakpoints at well-known dangerous functions (printf, snprintf, etc.), and check if the pointer holding the format string is writable, and  susceptible to format string attacks if an attacker can control its content. (alias: fmtstr-helper)|
+|functions                 | List the convenience functions provided by GEF.|
 |gef-remote                | gef wrapper for the `target remote` command. This command will automatically download the target binary in the local temporary directory (defaut /tmp) and then source it. Additionally, it will fetch all the /proc/PID/maps and loads all its information.|
 |heap                      | Base command to get information about the Glibc heap structure.|
 |heap-analysis-helper      | Tracks dynamic heap allocation through malloc/free to try to detect heap vulnerabilities.|
@@ -40,6 +41,7 @@ improve it.
 |registers                 | Display full details on one, many or all registers value from current architecture.|
 |reset-cache               | Reset cache of all stored data.|
 |ropper                    | Ropper (http://scoding.de/ropper) plugin|
+|scan                      | Search for addresses that are located in a memory mapping (haystack) that belonging to another (needle). (alias: lookup)|
 |search-pattern            | SearchPatternCommand: search a pattern in memory. (alias: grep)|
 |set-permission            | Change a page permission. By default, it will change it to RWX. (alias: mprotect)|
 |shellcode                 | ShellcodeCommand uses @JonathanSalwan simple-yet-awesome shellcode API to download shellcodes.|

docs/commands/functions.md

@@ -0,0 +1,25 @@
+## Command functions ##
+
+The `functions` command will list all of the [convenience functions](https://sourceware.org/gdb/onlinedocs/gdb/Convenience-Funs.html) provided by GEF.
+
+* `$_bss([offset])`    -- Return the current bss base address plus the given offset.
+* `$_got([offset])`    -- Return the current bss base address plus the given offset.
+* `$_heap([offset])`   -- Return the current heap base address plus an optional offset.
+* `$_pie([offset])`    -- Return the current pie base address plus an optional offset.
+* `$_stack([offset])`  -- Return the current stack base address plus an optional offset.
+
+
+These functions can be used as arguments to other commands to dynamically calculate values.
+
+```
+gef➤  deref $_heap() l4
+0x0000000000602000│+0x00: 0x0000000000000000	 ← $r8
+0x0000000000602008│+0x08: 0x0000000000000021 ("!"?)
+0x0000000000602010│+0x10: 0x0000000000000000	 ← $rax, $rdx
+0x0000000000602018│+0x18: 0x0000000000000000
+gef➤  deref $_heap(0x20) l4
+0x0000000000602020│+0x00: 0x0000000000000000	 ← $rsi
+0x0000000000602028│+0x08: 0x0000000000020fe1
+0x0000000000602030│+0x10: 0x0000000000000000
+0x0000000000602038│+0x18: 0x0000000000000000
+```

docs/commands/scan.md

@@ -0,0 +1,11 @@
+## Command scan ##
+
+`scan` Search for addresses that are located in a memory mapping (haystack) that
+belonging to another (needle).
+
+![scan-example](https://i.imgur.com/Ua0VXRY.png)
+
+`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](docs/commands/vmmap.md)
+to determine the memory ranges to search.

docs/index.md

@@ -2,15 +2,12 @@
 
 [![ReadTheDocs](https://readthedocs.org/projects/gef/badge/?version=master)](https://gef.readthedocs.org/en/master/) [![MIT](https://img.shields.io/packagist/l/doctrine/orm.svg?maxAge=2592000?style=plastic)](https://github.com/hugsy/gef/blob/master/LICENSE) [![Python 2 & 3](https://img.shields.io/badge/Python-2%20%26%203-green.svg)](https://github.com/hugsy/gef/) [![IRC](https://img.shields.io/badge/freenode-%23%23gef-yellowgreen.svg)](https://webchat.freenode.net/?channels=##gef) [![CircleCI status](https://circleci.com/gh/hugsy/gef/tree/master.svg?style=shield)](https://circleci.com/gh/hugsy/gef/tree/master)
 
-`GEF` is a kick-ass set of commands for X86, ARM, MIPS, PowerPC and SPARC to
-make GDB cool again for exploit dev. It is aimed to be used mostly by exploiters
-and reverse-engineers, to provide additional features to GDB using the Python
-API to assist during the process of dynamic analysis and exploit development.
+`GEF` (pronounced ʤɛf - "Jeff") is a kick-ass set of commands for X86, ARM, MIPS, PowerPC and SPARC to make GDB cool again for exploit dev. It is aimed to be used mostly by exploit developers and reverse-engineers, to provide additional features to GDB using the Python API to assist during the process of dynamic analysis and exploit development.
 
 It has full support for both Python2 and Python3 indifferently (as more and more
 distros start pushing `gdb` compiled with Python3 support).
 
-![gef-context](https://i.imgur.com/i0Hkw2C.png)
+![gef-context](https://i.imgur.com/E3EuQPs.png)
 
 
 *Some* of `GEF` features include:
@@ -166,7 +163,7 @@ There, you're now fully equipped epic pwnage with **all** GEF's goodness!!
 To discuss `gef`, `gdb`, exploitation or other topics, feel free to join the
 `##gef` channel on the Freenode IRC network. You can also talk to me (`hugsy`) on the
 channel. For those who do not have an IRC client (like `weechat` or `irssi`),
-simply [click here](https://webchat.freenode.net/?channels=##gef). 
+simply [click here](https://webchat.freenode.net/?channels=##gef).
 
 For bugs or feature requests, just
 go [here](https://github.com/hugsy/gef/issues) and provide a thorough description

docs/screenshots.md

@@ -1,34 +1,81 @@
-# GEF show cases #
+# Screenshots
 
-This shows a few examples of new features available to you when installing
-`GEF`, with the supported architecture.
+<!-- @import "[TOC]" {cmd="toc" depthFrom=1 depthTo=6 orderedList=false} -->
 
 
-#### Heap analysis ####
+This page illustrates a few of the possibilities available to you when using `GEF`.
 
-![heap-chunks](https://i.imgur.com/2Ew2fA6.png)
-![uaf](https://i.imgur.com/NfV5Cu9.png)
+## Multi-architecture support
 
-#### Automatic vulnerable string detection ####
+`GEF` was designed to support any architecture supported by GDB via an easily extensible architecture API.
 
-![fmtstr-helper-example](https://i.imgur.com/INU3KGn.png)
+Currently `GEF` supports the following architectures:
 
-#### Code emulation with Unicorn-Engine (x86-64) ####
+ - Intel x86 (32b & 64b)
+ - ARM (v6/v7)
+ - AARCH64
+ - MIPS/MIPS64
+ - PowerPC
+ - SPARC/SPARCv9
 
-![gef-x86](https://i.imgur.com/emhEsol.png)
 
-#### ELF information, memory mapping and code disassembly with Capstone/Keystone integration (ARM v6) ####
+## Features
 
-![gef-arm](http://i.imgur.com/qOL8CnL.png)
+### Embedded hexdump view
 
-#### Automatic dereferencing of registers values and identifying binary protections (PowerPC) ####
+To this day, GDB doesn't come with a hexdump-like view. Well `GEF` fixes that for you via the `hexdump` command:
 
-![gef-ppc](https://i.imgur.com/IN6x6lw.png)
+![hexdump](https://i.imgur.com/mJUq6T2.png)
 
-#### Context display on MIPS ####
 
-![gef-mips](https://i.imgur.com/dBaB9os.png)
+### Dereferencing data or registers
 
-#### Capstone-Engine disassembly on SPARC v9 ####
+No more endless manual pointer dereferencing `x/x` style. Just use `dereference` for that. Or for a comprehensive view of the registers, `registers` might become your best friend:
 
-![gef-sparc](https://i.imgur.com/VD2FpDt.png)
+![mipsel-deref-regs](https://i.imgur.com/f5ZaWDC.png)
+
+
+### Heap analysis
+
+#### Detailed view of Glibc Chunks
+
+![x86-heap-chunks](https://i.imgur.com/zBSTUHb.png)
+
+
+#### Automatic detection of UaF during runtime
+
+![x86-heap-helper-uaf](https://i.imgur.com/NfV5Cu9.png)
+
+
+### Display ELF information
+
+#### ELF structure
+
+![arm-elf-info](https://i.imgur.com/qOL8CnL.png)
+
+
+#### Security settings
+
+![mips-elf-checksec](https://i.imgur.com/aanY2uK.png)
+
+
+### Automatic vulnerable string detection
+
+![aarch64-fmtstr](https://i.imgur.com/iF4l1R5.png)
+
+
+### Code emulation with Unicorn-Engine (x86-64)
+
+![x86-unicorn](https://i.imgur.com/emhEsol.png)
+
+
+
+### Comprehensive address space layout display
+
+![mips-vmmap](https://i.imgur.com/TbC1kNa.png)
+
+
+
+### Defining arbitrary custom structures
+
+![sparc-arb-struct](https://i.imgur.com/dEMUuP7.png)