Update docs for binja integration and go debugging (#2370)

* Update docs for binja integration and go debugging

* add section to FEATURES.md

FEATURES.md

@@ -159,21 +159,23 @@ Pwndbg enables introspection of the glibc allocator, ptmalloc2, via a handful of
 ![](caps/heap_fake_fast.png)
 ![](caps/heap_try_free.png)
 
-## IDA Pro Integration
+## IDA Pro/Binary Ninja Integration
 
-Pwndbg flips traditional IDA Pro integration on its head.  Rather than sticking code inside of IDA that you need to interact with, by installing a small [XMLRPC server](ida_script.py) inside of IDA, Pwndbg has full access to everything IDA knows.
+Pwndbg is capable of integrating with IDA Pro or Binary Ninja by installing an XMLRPC server in the decompiler as a plugin, and then querying it for information.
 
-This allows extraction of comments, decompiled lines of source, breakpoints, and synchronized debugging (single-steps update the cursor in IDA).
+This allows extraction of comments, decompiled lines of source, breakpoints, symbols, and synchronized debugging (single-steps update the cursor in the decompiler).
 
 ![](caps/ida_comments.png)
 ![](caps/ida_function.png)
 ![](caps/ida_integration.png)
 
-Since the complete IDA API is exposed, new tools can be built on this functionality to further enhance Pwndbg's usefulness.
+See the [Binary Ninja integration guide](docs/binja_integration.md) for setup information.
 
-You can also connect to Ida Pro XMLRPC server hosted on different machine. In order to achieve it, you need to change:
-* Ida Pro XMLRPC server host (in [ida_script](ida_script.py); as by default it binds to localhost)
-* The config parameters responsible for connection (see `config` command)
+## Go Debugging
+
+Pwndbg has support for dumping complex Go values like maps and slices, including automatically parsing out type layouts in certain cases.
+
+See the [Go debugging guide](docs/go_debugging.md) for more information.
 
 ## Configuration, customization
 

docs/binja_integration.md

@@ -0,0 +1,24 @@
+# Integrating Binary Ninja with pwndbg
+## Requirements
+You need at least the personal edition of Binary Ninja (only tested on version 4.0+) that runs at least Python 3.8 for plugins.
+
+## Setup
+Copy (or symlink) [`binja_script.py`](binja_script.py) to your [plugins directory](https://docs.binary.ninja/guide/plugins.html).
+
+## Usage
+To start the Binary Ninja integration, open the binary you want to debug in Binary Ninja, then go to `Plugins > pwndbg > Start integration on current view`. This will start the XMLRPC server that pwndbg queries for information.
+
+Then, inside GDB, run `set integration-provider binja`, which will start the integration. You can run `set integration-provider none` to disable it again.
+
+## Features
+The integration currently syncs symbol names, comments, decompilation, function type signatures, and stack variables.
+
+## Commands
+- `bn-sync`: Navigate the Binary Ninja view to the current instruction
+- `decomp ADDR NLINES`: Displays the decompilation for `NLINES` lines at address `ADDR`. 
+
+## Config Options
+- `bn-autosync`: If set to `yes`, every step will automatically run `bn-sync`
+- `bn-il-level`: Sets the IL level to use for decompilation. Valid values are: `disasm`, `llil`, `mlil`, `hlil`
+- `bn-rpc-host`/`bn-rpc-port`: The host and port to connect to for the XMLRPC server
+- `bn-timeout`: The amount, in seconds, to wait for the XMLRPC server to connect

docs/go_debugging.md

@@ -0,0 +1,56 @@
+# Debugging Go with pwndbg
+## Basics
+The `go-dump` command can be used to dump Go values during debugging. It takes the form `go-dump type address_expression`, and supports many different types with the same syntax as Go:
+- Integer types: `int`, `int8`, `int16`, `int32`, `int64`, `int128`, and their `uint` counterparts
+- Misc types: `bool`, `rune`, `uintptr`, `string`
+- Floating point types: `float32`, `float64`
+- Complex numbers: `complex64`, `complex128`
+- Interface types: `any` for `interface{}` (the empty interface), and `interface` for all non-empty interfaces
+- Function types: `funcptr` for all function types
+- Pointers: `*ELEM`
+- Slices: `[]ELEM`
+- Arrays: `[LEN]ELEM`
+- Maps: `map[KEY][VAL]` (note that maps in Go are actually pointers to the map, whereas this map is the inner map, so you may need to use `*map[KEY]VAL` to dump a map)
+
+Struct types are also supported, but the syntax is slightly different from Go in order to avoid having to compute offsets (and also to support only having partial field information on structs). Struct types are notated as `OFFSET:FIELD_NAME:TYPE` triples separated by semicolons then enclosed with `struct(SIZE){}`, e.g. `struct(24){0:foo:string;16:bar:int64}` to represent the 24-byte Go struct `struct { foo string; bar int64 }`.
+
+Example:
+```
+pwndbg> go-dump map[string]int 0xc0000b20f0
+{"a": 1, "b": 2, "c": 3}
+
+pwndbg> go-dump any 0xc0000ace40
+([]struct { a int; b string }) [struct {a: 1, b: "first"}, struct {a: 2, b: "second"}]
+
+pwndbg> go-dump struct(24){0:a:int;8:b:string} 0xc000108120
+struct {a: 1, b: "first"}
+```
+
+Some notable flags include `-p` to enable pretty printing, `-x` to display integers in hex, `-f DECIMALS` to set the number of decimals used to display floats, `-d` to enable debug printing, which displays memory addresses of everything shown in the dump.
+
+## Runtime Type Parsing
+Go's compiler emits type objects for every single type used by the program. This is what enables dumping interface values with `go-dump` without having to specify any additional type information, and can also be leveraged to dump non-interface values if the type can be located. A good way to locate types is by finding the type pointer passed into heap allocation functions like `runtime.newobject` or `runtime.makeslice`.
+
+After finding the type pointer, the `go-type` command can be used to inspect a type:
+```
+pwndbg> go-type 0x49fbc0
+ Name: struct { a int; b string }
+ Kind: STRUCT
+ Size: 24 (0x18)
+Align: 8
+Parse: struct(24){0:a:int;8:b:string}
+Field a:
+    Offset: 0 (0x0)
+    Type name: int
+    Type addr: 0x498ce0
+Field b:
+    Offset: 8 (0x8)
+    Type name: string
+    Type addr: 0x498aa0
+```
+
+The `go-dump` command can also take an address to a type instead of the name of a type:
+```
+pwndbg> go-dump 0x49fbc0 0xc000108120
+struct {a: 1, b: "first"}
+```