diff --git a/FEATURES.md b/FEATURES.md deleted file mode 100644 index efe86242f..000000000 --- a/FEATURES.md +++ /dev/null @@ -1,321 +0,0 @@ -# pwndbg - -Pwndbg has a great deal of useful features. You can a list all available commands at any time by typing the `pwndbg` command. It can also be configured: see `config` and `theme` commands. Below is a subset of them which are easy to capture in screenshots. - -## GDB vs LLDB -| **Functionality** | **GDB Command** | **LLDB Command** | -|-----------------------------------------------|----------------------------------------|-------------------------------------------------------------| -| **Start Debugging Program** | `gdb ./your-program` | `lldb ./your-program` | -| **Set a Breakpoint** | `break ` | `breakpoint set --name ` | -| **Set Breakpoint on Address** | `break *
` | `breakpoint set --address
` | -| **Set Breakpoint at Line** | `break :` | `breakpoint set --file --line ` | -| **Set Hardware Breakpoint** | `hbreak ` | `breakpoint set --hardware --name ` | -| **Set Hardware Breakpoint at Memory** | `hbreak *` | `breakpoint set --hardware --address ` | -| **List All Breakpoints** | `info breakpoints` | `breakpoint list` | -| **Delete Breakpoints** | `delete ` | `breakpoint delete ` | -| **Set Watchpoint** | `watch ` | `watchpoint set variable ` | -| **Set Conditional Breakpoint** | `break if ` | `breakpoint set --condition ""` | -| **Continue Execution** | `continue` | `process continue` | -| **Next Instruction** | `next` | `thread step-over` | -| **Step into a Function** | `step` | `thread step-in` | -| **Step out of a Function** | `finish` | `thread step-out` | -| **Print Threads** | `info threads` | `thread list` | -| **Select Thread** | `thread ` | `thread select ` | -| **Print Register Values** | `info registers` | `register read -a` | -| **Print a Variable** | `print ` | `print ` | -| **Display Variable on Every Stop** | `display ` | `expression --watch ` | -| **Examine Memory (Hex)** | `x/x ` | `memory read --format x --count ` | -| **Examine Memory (Integer)** | `x/d ` | `memory read --format d --count ` | -| **Inspect Stack Trace** | `backtrace` | `thread backtrace` | -| **Change Register Value** | `set $ = ` | `register write ` | -| **Check Program Status** | `info locals` | `frame variable` | -| **Check Program Info** | `info functions` | `image lookup --functions` | -| **Show Disassembly of Function** | `disas ` | `disassemble ` | -| **Memory Dump (Hex)** | `x/xh ` | `memory read --format x --count ` | -| **Memory Dump (Bytes)** | `x/bx ` | `memory read --format b --count ` | -| **Show Process Information** | `info process` | `process status` | -| **Quit Debugging** | `quit` | `quit` | -| **Run Program with Arguments** | `run ...` | `process launch -- ...` | -| **Show Current Function** | `info frame` | `frame info` | -| **Set Sysroot** | `set sysroot ` | `settings set target.sysroot ` | -| **Set Source Directory** | `directory ` | `settings set target.source-map ` | -| **Set Architecture** | `set architecture ` | `target create --arch ` | -| **Show Settings** | `show ` | `settings show ` | -| **Set File for Debugging** | `file ` | `target create ` | -| **Start the Program and Run One Instruction** | `starti` | `process launch --stop-at-entry` | -| **Enable ASLR** | `set disable-randomization off` | `settings set target.disable-aslr false` | - -## Arguments - -All function call sites are annotated with the arguments to those functions. This works best with debugging symbols, but also works in the most common case where an imported function (e.g. libc function via GOT or PLT) is used. - -![](caps/arguments_getenv.png) -![](caps/arguments_memcpy.png) -![](caps/arguments_sigsetjmp.png) -![](caps/arguments_strcpy.png) -![](caps/arguments_syscall.png) -![](caps/arguments_xtrace_init.png) - -## Context - -A useful summary of the current execution context is printed every time GDB stops (e.g. breakpoint or single-step), displaying all registers, the stack, call frames, disassembly, and additionally recursively dereferencing all pointers. All memory addresses are color-coded to the type of memory they represent. - -The output of the context may be redirected to a file (including other tty) by using `set context-output /path/to/file` while leaving other output in place. - -![](caps/context.png) - -A history of previous context output is kept which can be accessed using the `contextprev` and `contextnext` commands. - -### Splitting / Layouting Context - -The context sections can be distributed among different tty by using the `contextoutput` command. -Example: `contextoutput stack /path/to/tty true` - -Python can be used to create a tmux layout when starting pwndbg and distributing the context among -the splits. -```python -python -import atexit -import os -from pwndbg.commands.context import contextoutput, output, clear_screen -bt = os.popen('tmux split-window -P -F "#{pane_id}:#{pane_tty}" -d "cat -"').read().strip().split(":") -st = os.popen(F'tmux split-window -h -t {bt[0]} -P -F '+'"#{pane_id}:#{pane_tty}" -d "cat -"').read().strip().split(":") -re = os.popen(F'tmux split-window -h -t {st[0]} -P -F '+'"#{pane_id}:#{pane_tty}" -d "cat -"').read().strip().split(":") -di = os.popen('tmux split-window -h -P -F "#{pane_id}:#{pane_tty}" -d "cat -"').read().strip().split(":") -panes = dict(backtrace=bt, stack=st, regs=re, disasm=di) -for sec, p in panes.items(): - contextoutput(sec, p[1], True) -contextoutput("legend", di[1], True) -atexit.register(lambda: [os.popen(F"tmux kill-pane -t {p[0]}").read() for p in panes.values()]) -end -``` -If you like it simple, try configuration with [splitmind](https://github.com/jerdna-regeiz/splitmind) - -![](caps/context_splitting.png) - -Note above example uses splitmind and following configuration: - -```python -python -import splitmind -(splitmind.Mind() - .tell_splitter(show_titles=True) - .tell_splitter(set_title="Main") - .right(display="backtrace", size="25%") - .above(of="main", display="disasm", size="80%", banner="top") - .show("code", on="disasm", banner="none") - .right(cmd='tty; tail -f /dev/null', size="65%", clearing=False) - .tell_splitter(set_title='Input / Output') - .above(display="stack", size="75%") - .above(display="legend", size="25") - .show("regs", on="legend") - .below(of="backtrace", cmd="ipython", size="30%") -).build(nobanner=True) -end -``` - -#### GDB TUI -The context sections are available as native [GDB TUI](https://sourceware.org/gdb/current/onlinedocs/gdb.html/TUI.html) windows named `pwndbg_[sectionname]`. - -There are some predefined layouts coming with pwndbg which you can select using `layout pwndbg` or `layout pwndbg_code`. - -To create [your own layout](https://sourceware.org/gdb/current/onlinedocs/gdb.html/TUI-Commands.html) and selecting it use normal `tui new-layout` syntax like: -``` -tui new-layout pwndbg_custom {-horizontal { { -horizontal { pwndbg_code 1 pwndbg_disasm 1 } 2 { {-horizontal pwndbg_legend 8 pwndbg_control 2 } 1 pwndbg_regs 6 pwndbg_stack 6 } 3 } 7 cmd 3 } 3 { pwndbg_backtrace 2 pwndbg_threads 1 pwndbg_expressions 2 } 1 } 1 status 1 -layout pwndbg_custom -``` - -![](caps/context_tui.png) - -Use `focus cmd` to focus the command window and have the arrow keys scroll through the command history again. `tui disable` to disable TUI mode and go back to CLI mode when running commands with longer output. `ctrl-x + a` toggles between TUI and CLI mode quickly. Hold shift to ignore the TUI mouse integration and use the mouse normally to select text or copy data. - -### Watch Expressions - -You can add expressions to be watched by the context. -Those expressions are evaluated and shown on every context refresh. - -An expression can be added via the `contextwatch` command (aliased `ctx-watch` and `cwatch`). - -Per default an expression is parsed and evaluated in the debugged language and can be added with: -``` -contextwatch BUF -ctx-watch ITEMS[0] -``` - -Alternatively one can provide an arbitrary gdb command to be executed and the result printed in the -context by using the optional `cmd` parameter with the value `execute`: -``` -contextwatch execute "ds BUF" -cwatch execute "x/20x $rsp" -``` - -### Ghidra - -With the help of [radare2](https://github.com/radareorg/radare2) or [rizin](https://github.com/rizinorg/rizin) it is possible to show the -decompiled source code of the ghidra decompiler. - -However, this comes with some prerequisites. -* First: you have to have installed radare2 or rizin and it must be found by gdb (within path) -* Second: you have to install the ghidra plugin for radare2 - [r2ghidra](https://github.com/radareorg/r2ghidra) or install the ghidra plugin for rizin [rz-ghidra](https://github.com/rizinorg/rz-ghidra) - -* Third: r2pipe has to be installed in the python-context gdb is using (or if you are using rizin, install rzpipe instead) - -The decompiled source be shown as part of the context by adding `ghidra` to `set context-sections` -or by calling `ctx-ghidra [function]` manually. - -Be warned, the first call to both radare2/r2ghidra and rizin/rz-ghidra are rather slow! Subsequent requests for decompiled -source will be faster. And it does take up some resources as the radare2/rizin instance is kept by r2pipe/rzpipe -to enable faster subsequent analysis. - -With those performance penalties it is reasonable to not have it launch always. Therefore it includes -an option to only start it when required with `set context-ghidra`: -* `set context-ghidra always`: always trigger the ghidra context -* `set context-ghidra never`: never trigger the ghidra context except when called manually -* `set context-ghidra if-no-source`: invoke ghidra if no source code is available - -Remark: the plugin tries to guess the correct current line and mark it with "-->", but it might -get it wrong. - -## Disassembly - -Pwndbg uses Capstone Engine to display disassembled instructions, but also leverages its introspection into the instruction to extract memory targets and condition codes. - -All absolute jumps are folded away, only displaying relevant instructions. - -![](caps/disasm_taken_folded.png) - -Additionally, if the current instruction is conditional, Pwndbg displays whether or not it is evaluated with a green check or a red X, and folds away instructions as necessary. - -![](caps/disasm_taken_after.png) -![](caps/disasm_taken_before.png) -![](caps/disasn_taken_false.png) - -## Emulation - -Pwndbg leverages Unicorn Engine in order to only show instructions which will actually be emulated. At each debugger stop (e.g. breakpoint or single-step) the next few instructions are silently emulated, and only instructions which will actually be executed are displayed. - -This is incredibly useful when stepping through jump tables, PLT entries, and even while ROPping! - -![](caps/emulate_vs_disasm.png) -![](caps/emulation_plt.png) -![](caps/emulation_rop.png) - -## Heap Inspection - -Pwndbg enables introspection of the glibc allocator, ptmalloc2, via a handful of introspection functions. - -![](caps/heap_arena.png) -![](caps/heap_mp.png) -![](caps/heap_bins.png) -![](caps/heap_fastbins.png) -![](caps/heap_unsorted.png) -![](caps/heap_smallbins.png) -![](caps/heap_largebins.png) -![](caps/heap_heap.png) -![](caps/heap_heap2.png) -![](caps/heap_mallocchunk.png) -![](caps/heap_topchunk.png) -![](caps/heap_fake_fast.png) -![](caps/heap_try_free.png) - -## IDA Pro/Binary Ninja Integration - -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, symbols, and synchronized debugging (single-steps update the cursor in the decompiler). - -![](caps/ida_comments.png) -![](caps/ida_function.png) -![](caps/ida_integration.png) - -See the [Binary Ninja integration guide](docs/binja_integration.md) for setup information. - -## 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 - -There are two commands to set various options: - -* `theme` - to set particular output color/style -![](caps/theme.png) - -* `config` - to set parameters like whether to emulate code near current instruction, ida rpc connection info, hexdump bytes/width (and more) -![](caps/config.png) - -Of course you can generate and put it in `.gdbinit` after pwndbg initialization to keep it persistent between pwngdb sessions. - -This can be seen and achieved by `configfile`/`themefile` commands. - -## QEMU Compatibility - -Pwndbg is designed to work with minimally-implemented or otherwise debugger-hostile implementations of the GDB Serial Protocol. One such implementation is that used by QEMU User-Mode Emulation (`qemu-user`) which is frequently used by CTF players to execute and debug cross-architecture binaries. - -Vanilla GDB, PEDA, and GEF all fail terribly in this scenario. - -#### GEF - -![](caps/qemu_gef.png) - -#### PEDA - -![](caps/qemu_peda.png) - -#### Vanilla GDB - -![](caps/qemu_vanilla.png) - -#### Pwndbg - -However, Pwndbg works around the limitations of the GDB stub to give you the best debugger environment possible. - -![](caps/qemu_pwndbg.png) - -## Process State Inspection - -Use the `procinfo` command in order to inspect the current process state, like UID, GID, Groups, SELinux context, and open file descriptors! Pwndbg works particularly well with remote GDB debugging like with Android phones, which PEDA, GEF, and vanilla GDB choke on. - -![](caps/procinfo.png) - -## ROP Gadgets - -Pwndbg makes using ROPGadget easy with the actual addresses in the process. - -Just use the `rop` command! - -![](caps/rop_grep.png) - -## Search - -Pwndbg makes searching the target memory space easy, with a complete and easy-to-use interface. Whether you're searching for bytes, strings, or various sizes of integer values or pointers, it's a simple command away. - -![](caps/search.png) - -## Finding Leaks -![](caps/leakfind.png) -Finding leak chains can be done using the `leakfind` command. It recursively inspects address ranges for pointers, and reports on all pointers found. - - -## Telescope - -Inspecting memory dumps is easy with the `telescope` command. It recursively dereferences a range of memory, letting you see everything at once. As an added bonus, Pwndbg checks all of the available registers to see if they point into the memory range. - -## Virtual Memory Maps - -Pwndbg enhances the standard memory map listing, and allows easy searching. - -![](caps/vmmap.png) -![](caps/vmmap2.png) -![](caps/vmmap_pc.png) -![](caps/vmmap_register.png) -![](caps/vmmap_stack.png) - -## Windbg Compatibility - -Pwndbg has a complete windbg compatibility layer. You can `dd`, `dps`, `eq`, and even `eb eip 90` to your heart's content. - -![](caps/windbg.png) diff --git a/README.md b/README.md index 4b7e55e20..bf9f18ed3 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ with a focus on features needed by low-level software developers, hardware hackers, reverse-engineers and exploit developers. -It has a boatload of features, see [FEATURES.md](https://github.com/pwndbg/pwndbg/blob/dev/FEATURES.md) +It has a boatload of features, see our [Features page](https://pwndbg.re/pwndbg/latest/features/) and [CHEATSHEET][CHEATSHEET] (feel free to print it!). If you have any questions you may read the [documentation](https://pwndbg.re/pwndbg/latest/) or asks us in our [Discord server](https://discord.gg/x47DssnGwm). diff --git a/caps/.DS_Store b/caps/.DS_Store deleted file mode 100644 index 5008ddfcf..000000000 Binary files a/caps/.DS_Store and /dev/null differ diff --git a/caps/arguments_getenv.png b/caps/arguments_getenv.png deleted file mode 100644 index 97088e9e7..000000000 Binary files a/caps/arguments_getenv.png and /dev/null differ diff --git a/caps/arguments_memcpy.png b/caps/arguments_memcpy.png deleted file mode 100644 index f17212f5f..000000000 Binary files a/caps/arguments_memcpy.png and /dev/null differ diff --git a/caps/arguments_sigsetjmp.png b/caps/arguments_sigsetjmp.png deleted file mode 100644 index 63b196454..000000000 Binary files a/caps/arguments_sigsetjmp.png and /dev/null differ diff --git a/caps/arguments_strcpy.png b/caps/arguments_strcpy.png deleted file mode 100644 index 67d817bfc..000000000 Binary files a/caps/arguments_strcpy.png and /dev/null differ diff --git a/caps/arguments_syscall.png b/caps/arguments_syscall.png deleted file mode 100644 index 353f492ea..000000000 Binary files a/caps/arguments_syscall.png and /dev/null differ diff --git a/caps/arguments_xtrace_init.png b/caps/arguments_xtrace_init.png deleted file mode 100644 index 1a1da16be..000000000 Binary files a/caps/arguments_xtrace_init.png and /dev/null differ diff --git a/caps/config.png b/caps/config.png deleted file mode 100644 index 622681921..000000000 Binary files a/caps/config.png and /dev/null differ diff --git a/caps/context.png b/caps/context.png deleted file mode 100644 index 9538f8136..000000000 Binary files a/caps/context.png and /dev/null differ diff --git a/caps/disasm_taken_after.png b/caps/disasm_taken_after.png deleted file mode 100644 index c9a264aed..000000000 Binary files a/caps/disasm_taken_after.png and /dev/null differ diff --git a/caps/disasm_taken_before.png b/caps/disasm_taken_before.png deleted file mode 100644 index 14988f8a7..000000000 Binary files a/caps/disasm_taken_before.png and /dev/null differ diff --git a/caps/disasm_taken_folded.png b/caps/disasm_taken_folded.png deleted file mode 100644 index 7fadae493..000000000 Binary files a/caps/disasm_taken_folded.png and /dev/null differ diff --git a/caps/disasn_taken_false.png b/caps/disasn_taken_false.png deleted file mode 100644 index 0b23df9df..000000000 Binary files a/caps/disasn_taken_false.png and /dev/null differ diff --git a/caps/emulate_vs_disasm.png b/caps/emulate_vs_disasm.png deleted file mode 100644 index db3e4e871..000000000 Binary files a/caps/emulate_vs_disasm.png and /dev/null differ diff --git a/caps/emulation_plt.png b/caps/emulation_plt.png deleted file mode 100644 index 5e5bcd61c..000000000 Binary files a/caps/emulation_plt.png and /dev/null differ diff --git a/caps/emulation_rop.png b/caps/emulation_rop.png deleted file mode 100644 index 52dc26714..000000000 Binary files a/caps/emulation_rop.png and /dev/null differ diff --git a/caps/heap_arena.png b/caps/heap_arena.png deleted file mode 100644 index 894b011c6..000000000 Binary files a/caps/heap_arena.png and /dev/null differ diff --git a/caps/heap_bins.png b/caps/heap_bins.png deleted file mode 100644 index 027e6560b..000000000 Binary files a/caps/heap_bins.png and /dev/null differ diff --git a/caps/heap_fake_fast.png b/caps/heap_fake_fast.png deleted file mode 100644 index ce1e6e380..000000000 Binary files a/caps/heap_fake_fast.png and /dev/null differ diff --git a/caps/heap_fastbins.png b/caps/heap_fastbins.png deleted file mode 100644 index 38776b016..000000000 Binary files a/caps/heap_fastbins.png and /dev/null differ diff --git a/caps/heap_heap.png b/caps/heap_heap.png deleted file mode 100644 index 4cdb9ef66..000000000 Binary files a/caps/heap_heap.png and /dev/null differ diff --git a/caps/heap_heap2.png b/caps/heap_heap2.png deleted file mode 100644 index c59a90f31..000000000 Binary files a/caps/heap_heap2.png and /dev/null differ diff --git a/caps/heap_largebins.png b/caps/heap_largebins.png deleted file mode 100644 index 383befdc5..000000000 Binary files a/caps/heap_largebins.png and /dev/null differ diff --git a/caps/heap_mallocchunk.png b/caps/heap_mallocchunk.png deleted file mode 100644 index 1ab0d5236..000000000 Binary files a/caps/heap_mallocchunk.png and /dev/null differ diff --git a/caps/heap_mp.png b/caps/heap_mp.png deleted file mode 100644 index 0395e5d15..000000000 Binary files a/caps/heap_mp.png and /dev/null differ diff --git a/caps/heap_smallbins.png b/caps/heap_smallbins.png deleted file mode 100644 index dcf3d5a72..000000000 Binary files a/caps/heap_smallbins.png and /dev/null differ diff --git a/caps/heap_topchunk.png b/caps/heap_topchunk.png deleted file mode 100644 index 87250a9bc..000000000 Binary files a/caps/heap_topchunk.png and /dev/null differ diff --git a/caps/heap_try_free.png b/caps/heap_try_free.png deleted file mode 100644 index c5f4816ab..000000000 Binary files a/caps/heap_try_free.png and /dev/null differ diff --git a/caps/heap_unsorted.png b/caps/heap_unsorted.png deleted file mode 100644 index 3ee6072fd..000000000 Binary files a/caps/heap_unsorted.png and /dev/null differ diff --git a/caps/ida_comments.png b/caps/ida_comments.png deleted file mode 100644 index 8d39de322..000000000 Binary files a/caps/ida_comments.png and /dev/null differ diff --git a/caps/ida_function.png b/caps/ida_function.png deleted file mode 100644 index 103c9d6be..000000000 Binary files a/caps/ida_function.png and /dev/null differ diff --git a/caps/ida_integration.png b/caps/ida_integration.png deleted file mode 100644 index d54107783..000000000 Binary files a/caps/ida_integration.png and /dev/null differ diff --git a/caps/qemu_gef.png b/caps/qemu_gef.png deleted file mode 100644 index 5e119f2f8..000000000 Binary files a/caps/qemu_gef.png and /dev/null differ diff --git a/caps/qemu_peda.png b/caps/qemu_peda.png deleted file mode 100644 index 9850ae550..000000000 Binary files a/caps/qemu_peda.png and /dev/null differ diff --git a/caps/qemu_pwndbg.png b/caps/qemu_pwndbg.png deleted file mode 100644 index b62436a4b..000000000 Binary files a/caps/qemu_pwndbg.png and /dev/null differ diff --git a/caps/qemu_vanilla.png b/caps/qemu_vanilla.png deleted file mode 100644 index a68882ecb..000000000 Binary files a/caps/qemu_vanilla.png and /dev/null differ diff --git a/caps/rop_grep.png b/caps/rop_grep.png deleted file mode 100644 index 9a35500a4..000000000 Binary files a/caps/rop_grep.png and /dev/null differ diff --git a/caps/search.png b/caps/search.png deleted file mode 100644 index 172c8bd47..000000000 Binary files a/caps/search.png and /dev/null differ diff --git a/caps/telescope.png b/caps/telescope.png deleted file mode 100644 index ab6663cd7..000000000 Binary files a/caps/telescope.png and /dev/null differ diff --git a/caps/telescope_collapsed.png b/caps/telescope_collapsed.png deleted file mode 100644 index 1f533e098..000000000 Binary files a/caps/telescope_collapsed.png and /dev/null differ diff --git a/caps/theme.png b/caps/theme.png deleted file mode 100644 index df4cc1868..000000000 Binary files a/caps/theme.png and /dev/null differ diff --git a/caps/vmmap.png b/caps/vmmap.png deleted file mode 100644 index ae177051d..000000000 Binary files a/caps/vmmap.png and /dev/null differ diff --git a/caps/vmmap2.png b/caps/vmmap2.png deleted file mode 100644 index b12ae2fc5..000000000 Binary files a/caps/vmmap2.png and /dev/null differ diff --git a/caps/vmmap_pc.png b/caps/vmmap_pc.png deleted file mode 100644 index 10f9464dc..000000000 Binary files a/caps/vmmap_pc.png and /dev/null differ diff --git a/caps/vmmap_register.png b/caps/vmmap_register.png deleted file mode 100644 index ed301d0a4..000000000 Binary files a/caps/vmmap_register.png and /dev/null differ diff --git a/caps/vmmap_stack.png b/caps/vmmap_stack.png deleted file mode 100644 index b909faddc..000000000 Binary files a/caps/vmmap_stack.png and /dev/null differ diff --git a/caps/windbg.png b/caps/windbg.png deleted file mode 100644 index cbfc2ec8e..000000000 Binary files a/caps/windbg.png and /dev/null differ diff --git a/docs/.nav.yml b/docs/.nav.yml index 5705ba2ef..0aad7a0f0 100644 --- a/docs/.nav.yml +++ b/docs/.nav.yml @@ -5,6 +5,7 @@ nav: - index.md - setup.md + - features.md - commands - functions - configuration diff --git a/docs/assets/caps/arguments_getenv.png b/docs/assets/caps/arguments_getenv.png new file mode 100644 index 000000000..5f87851d9 Binary files /dev/null and b/docs/assets/caps/arguments_getenv.png differ diff --git a/docs/assets/caps/arguments_memcpy.png b/docs/assets/caps/arguments_memcpy.png new file mode 100644 index 000000000..b056ed0cf Binary files /dev/null and b/docs/assets/caps/arguments_memcpy.png differ diff --git a/docs/assets/caps/arguments_sigsetjmp.png b/docs/assets/caps/arguments_sigsetjmp.png new file mode 100644 index 000000000..6c16411be Binary files /dev/null and b/docs/assets/caps/arguments_sigsetjmp.png differ diff --git a/docs/assets/caps/arguments_strcpy.png b/docs/assets/caps/arguments_strcpy.png new file mode 100644 index 000000000..32c05d803 Binary files /dev/null and b/docs/assets/caps/arguments_strcpy.png differ diff --git a/docs/assets/caps/arguments_syscall.png b/docs/assets/caps/arguments_syscall.png new file mode 100644 index 000000000..5fa55edfd Binary files /dev/null and b/docs/assets/caps/arguments_syscall.png differ diff --git a/docs/assets/caps/arguments_xtraceinit.png b/docs/assets/caps/arguments_xtraceinit.png new file mode 100644 index 000000000..1c4c177e4 Binary files /dev/null and b/docs/assets/caps/arguments_xtraceinit.png differ diff --git a/caps/best.png b/docs/assets/caps/best.png similarity index 100% rename from caps/best.png rename to docs/assets/caps/best.png diff --git a/docs/assets/caps/context.png b/docs/assets/caps/context.png new file mode 100644 index 000000000..a2c332bf0 Binary files /dev/null and b/docs/assets/caps/context.png differ diff --git a/caps/context_splitting.png b/docs/assets/caps/context_splitting.png similarity index 100% rename from caps/context_splitting.png rename to docs/assets/caps/context_splitting.png diff --git a/caps/context_tui.png b/docs/assets/caps/context_tui.png similarity index 100% rename from caps/context_tui.png rename to docs/assets/caps/context_tui.png diff --git a/docs/assets/caps/cwatch_infoargs.png b/docs/assets/caps/cwatch_infoargs.png new file mode 100644 index 000000000..83a6b6d6e Binary files /dev/null and b/docs/assets/caps/cwatch_infoargs.png differ diff --git a/docs/assets/caps/disasm_example.png b/docs/assets/caps/disasm_example.png new file mode 100644 index 000000000..b45d9fc54 Binary files /dev/null and b/docs/assets/caps/disasm_example.png differ diff --git a/docs/assets/caps/emulation_rop.png b/docs/assets/caps/emulation_rop.png new file mode 100644 index 000000000..bc1893328 Binary files /dev/null and b/docs/assets/caps/emulation_rop.png differ diff --git a/docs/assets/caps/heap_find_fake_fast.png b/docs/assets/caps/heap_find_fake_fast.png new file mode 100644 index 000000000..7370fed02 Binary files /dev/null and b/docs/assets/caps/heap_find_fake_fast.png differ diff --git a/docs/assets/caps/heap_hi_bins.png b/docs/assets/caps/heap_hi_bins.png new file mode 100644 index 000000000..16bacbb51 Binary files /dev/null and b/docs/assets/caps/heap_hi_bins.png differ diff --git a/docs/assets/caps/heap_try_free.png b/docs/assets/caps/heap_try_free.png new file mode 100644 index 000000000..2ba49d312 Binary files /dev/null and b/docs/assets/caps/heap_try_free.png differ diff --git a/docs/assets/caps/heap_vis.png b/docs/assets/caps/heap_vis.png new file mode 100644 index 000000000..59ef80b5e Binary files /dev/null and b/docs/assets/caps/heap_vis.png differ diff --git a/docs/assets/caps/ida_context.png b/docs/assets/caps/ida_context.png new file mode 100644 index 000000000..40358e408 Binary files /dev/null and b/docs/assets/caps/ida_context.png differ diff --git a/caps/leakfind.png b/docs/assets/caps/leakfind.png similarity index 100% rename from caps/leakfind.png rename to docs/assets/caps/leakfind.png diff --git a/docs/assets/caps/lldb.png b/docs/assets/caps/lldb.png new file mode 100644 index 000000000..a3bd6a2b6 Binary files /dev/null and b/docs/assets/caps/lldb.png differ diff --git a/caps/procinfo.png b/docs/assets/caps/procinfo.png similarity index 100% rename from caps/procinfo.png rename to docs/assets/caps/procinfo.png diff --git a/docs/assets/caps/rop_grep.png b/docs/assets/caps/rop_grep.png new file mode 100644 index 000000000..47ae72c1c Binary files /dev/null and b/docs/assets/caps/rop_grep.png differ diff --git a/docs/assets/caps/search.png b/docs/assets/caps/search.png new file mode 100644 index 000000000..a578be064 Binary files /dev/null and b/docs/assets/caps/search.png differ diff --git a/docs/assets/caps/telescope.png b/docs/assets/caps/telescope.png new file mode 100644 index 000000000..95e5339a8 Binary files /dev/null and b/docs/assets/caps/telescope.png differ diff --git a/docs/assets/caps/vmmap.png b/docs/assets/caps/vmmap.png new file mode 100644 index 000000000..19a62fa2f Binary files /dev/null and b/docs/assets/caps/vmmap.png differ diff --git a/docs/assets/caps/vmmap_rip.png b/docs/assets/caps/vmmap_rip.png new file mode 100644 index 000000000..de47e45f4 Binary files /dev/null and b/docs/assets/caps/vmmap_rip.png differ diff --git a/docs/assets/caps/windbg.png b/docs/assets/caps/windbg.png new file mode 100644 index 000000000..a9eeee7f8 Binary files /dev/null and b/docs/assets/caps/windbg.png differ diff --git a/docs/commands/context/contextwatch.md b/docs/commands/context/contextwatch.md index 1c9c07f1e..6459c4aa1 100644 --- a/docs/commands/context/contextwatch.md +++ b/docs/commands/context/contextwatch.md @@ -24,5 +24,17 @@ To remove an expression, see `cunwatch`. | :--- | :--- | :--- | |-h|--help|show this help message and exit| +### Examples +```text +For watching variables/expressions: + cwatch BUF + cwatch ITEMS[0] + +For running commands: + cwatch execute "ds BUF" + cwatch execute "x/20x $rsp" + cwatch execute "info args" +``` + diff --git a/docs/commands/index.md b/docs/commands/index.md index c7ea8a875..2d523340b 100644 --- a/docs/commands/index.md +++ b/docs/commands/index.md @@ -86,7 +86,7 @@ - [knft-list-tables](kernel/knft-list-tables.md) - Dump netfliter tables from a specific network namespace - [kversion](kernel/kversion.md) - Outputs the kernel version (/proc/version). - [msr](kernel/msr.md) - Read or write to Model Specific Register (MSR) -- [slab](kernel/slab.md) - Prints information about the slab allocator +- [slab](kernel/slab.md) - Prints information about the linux kernel's slab allocator SLUB. ## Linux/libc/ELF @@ -143,7 +143,7 @@ - [cymbol](misc/cymbol.md) - Add, show, load, edit, or delete custom structures in plain C. - [down](misc/down.md) - Select and print stack frame called by this one. - [dt](misc/dt.md) - Dump out information on a type (e.g. ucontext_t). -- [dumpargs](misc/dumpargs.md) - Prints determined arguments for call instruction. +- [dumpargs](misc/dumpargs.md) - Prints determined arguments for call/syscall instruction. - [getfile](misc/getfile.md) - Gets the current file. - [hex2ptr](misc/hex2ptr.md) - Converts a space-separated hex string to a little-endian address. - [hijack-fd](misc/hijack-fd.md) - Replace a file descriptor of a debugged process. diff --git a/docs/commands/kernel/slab.md b/docs/commands/kernel/slab.md index 6b63cbbda..de9d5e4f3 100644 --- a/docs/commands/kernel/slab.md +++ b/docs/commands/kernel/slab.md @@ -6,7 +6,7 @@ usage: slab [-h] {list,info,contains} ... ``` -Prints information about the slab allocator +Prints information about the linux kernel's slab allocator SLUB. ### Positional arguments |Positional Argument|Help| diff --git a/docs/commands/misc/dumpargs.md b/docs/commands/misc/dumpargs.md index 6a6bb8657..74017e0ca 100644 --- a/docs/commands/misc/dumpargs.md +++ b/docs/commands/misc/dumpargs.md @@ -6,7 +6,7 @@ usage: dumpargs [-h] [-f] ``` -Prints determined arguments for call instruction. +Prints determined arguments for call/syscall instruction. **Alias:** args ### Optional arguments diff --git a/docs/configuration/index.md b/docs/configuration/index.md index 93448bda1..c0873be1b 100644 --- a/docs/configuration/index.md +++ b/docs/configuration/index.md @@ -9,3 +9,5 @@ There are three "scopes" of configuration parameters currently: To see the parameters belonging to these scopes, use the [`config`](../commands/pwndbg/config.md), [`heap-config`](../commands/pwndbg/heap-config.md), and [`theme`](../commands/pwndbg/theme.md) commands respectively. You can also use the [`configfile`](../commands/pwndbg/configfile.md) and [`themefile`](../commands/pwndbg/themefile.md) commands to save your live configuration to a file which you can then load in your `~/.(gdb/lldb)init` file (after sourcing pwndbg!). To see the value of any parameter, use `show param-name`. To set the value, use `set param-name param-value`. To see a more detailed description of the parameter use `help set param-name`. + +If you wish to use a theme different from the default one, check out [pwndbg/pwndbg-themes](https://github.com/pwndbg/pwndbg-themes). If you made a theme yourself, feel free to open a PR! diff --git a/docs/features.md b/docs/features.md new file mode 100644 index 000000000..f7f373194 --- /dev/null +++ b/docs/features.md @@ -0,0 +1,158 @@ +--- +hide: + - navigation +--- + + + +# Features + +Pwndbg has a great deal of useful features. You can a see all available commands at any time by typing the `pwndbg` command or by checking the [Commands section](commands/index.md) of the documentation. For configuration and theming see the [Configuration section](configuration/index.md). Below is a subset of commands which are easy to capture in screenshots. + +## Disassembly and Emulation + +Pwndbg leverages the [capstone](https://github.com/capstone-engine/capstone) and [unicorn](https://github.com/unicorn-engine/unicorn) engines, along with its own instrospection, to display, annotate and emulate instructions. + +Operands of instructions are resolved, conditions evaluated, and only the instructions that will actually be executed are shown. + +![](assets/caps/disasm_example.png) + +This is incredibly useful when stepping through jump tables, PLT entries, and ROPping. + +![](assets/caps/emulation_rop.png) + +## Context + +A useful summary of the current execution context is printed every time the debugger stops (e.g. breakpoint or single-step), displaying all registers, the stack, call frames, disassembly, and additionally recursively dereferencing all pointers. All memory addresses are color-coded to the type of memory they represent. + +![](assets/caps/context.png) + +A history of previous context output is kept which can be accessed using the `contextprev` and `contextnext` commands. + +### Arguments + +All function call sites are annotated with the arguments to those functions. This works best with debugging symbols, but also works in the most common case where an imported function (e.g. libc function via GOT or PLT) is used. + +![](assets/caps/arguments_getenv.png) +![](assets/caps/arguments_memcpy.png) +![](assets/caps/arguments_sigsetjmp.png) +![](assets/caps/arguments_strcpy.png) +![](assets/caps/arguments_syscall.png) +![](assets/caps/arguments_xtraceinit.png) + +### Splitting / Layouting Context + +The context sections can be distributed among different tty by using the `contextoutput` command. Thus, if you want to make better use of some of the empty space in the default Pwndbg output, you can split the panes in your terminal and redirect the various contexts among them. + +![](assets/caps/context_splitting.png) + +See [Splitting the Context](misc/splitting-the-context.md) for more information. + +### GDB TUI +The context sections are available as native [GDB TUI](https://sourceware.org/gdb/current/onlinedocs/gdb.html/TUI.html) windows named `pwndbg_[sectionname]`. There are some predefined layouts coming with Pwndbg which you can select using `layout pwndbg` or `layout pwndbg_code`. + +![](assets/caps/context_tui.png) + +See [GDB TUI](misc/gdb-tui.md) for more information. + +### Watch Expressions + +You can add expressions to be watched by the context. Those expressions are evaluated and shown on every context refresh. For instance by doing `contextwatch execute "info args"` we can see the arguments of every function we are in (here we are in `mmap`): + +![](assets/caps/cwatch_infoargs.png) + +See [`contextwatch`](commands/context/contextwatch.md) for more information. + +## Integrations + +### Ghidra + +With the help of [radare2](https://github.com/radareorg/radare2) or [rizin](https://github.com/rizinorg/rizin) it is possible to show the decompiled source code of the ghidra decompiler. + +See [Ghidra Integration](misc/ghidra-integration.md) for more information. + +### IDA Pro/Binary Ninja + +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, symbols, and synchronized debugging (single-steps update the cursor in the decompiler). + +![](assets/caps/ida_context.png){ style="width: 70%;" } + +See the [Binary Ninja integration guide](misc/binja-integration.md) for setup information. + +## Heap Inspection + +Pwndbg provides commands for inspecting the heap and the allocator's state. Currently supported are: + ++ [glibc malloc](commands/index.md#glibc-ptmalloc2-heap) ++ [jemalloc](commands/index.md#jemalloc-heap) ++ [linux's buddy allocator](commands/kernel/buddydump.md) ++ [linux's SLUB allocator](commands/kernel/slab.md) + +See *some* of the commands for glibc malloc: +![](assets/caps/heap_vis.png){ style="width: 70%;" } +![](assets/caps/heap_hi_bins.png){ style="width: 70%;" } +![](assets/caps/heap_try_free.png) +![](assets/caps/heap_find_fake_fast.png){ style="width: 70%;" } + +## LLDB + +While most other GDB plugins are well *GDB plugins*, Pwndbg's implementation is debugger-agnostic. You can use Pwndbg with LLDB! + +![](assets/caps/lldb.png){ style="width: 70%;" } + +## Windbg Compatibility + +For those coming from a Windows background, Pwndbg has a complete Windbg compatibility layer. You can `dd`, `dps`, `eq`, and even `eb $rip 90` to your heart's content. + +![](assets/caps/windbg.png){ style="width: 70%;" } + +## 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](misc/go-debugging.md) for more information. + +## So many commands + +Go take a look at [Commands](commands/index.md)! Here is some cool stuff you can do to get you started. + +### Process State Inspection + +Use the [`procinfo`](commands/process/procinfo.md) command in order to inspect the current process state, like UID, GID, Groups, SELinux context, and open file descriptors! Pwndbg works particularly well with remote GDB debugging like with Android phones. + +![](assets/caps/procinfo.png) + +### ROP Gadgets + +Tools for finding rop gadgets statically don't know about everything that will be loaded into the address space and they can make mistakes about which addresses will actually end up executable. You can now rop at runtime with Pwndbg's [`rop`](commands/integrations/rop.md) and [`ropper`](commands/integrations/ropper.md). + +![](assets/caps/rop_grep.png){ style="width: 70%;" } + +### Search + +Pwndbg makes [`search`](commands/memory/search.md)ing the target memory space easy, with a complete and easy-to-use interface. Whether you're searching for bytes, strings, or various sizes of integer values or pointers, it's a simple command away. + +![](assets/caps/search.png) + +### Finding Leaks +Finding leak chains can be done using the [`leakfind`](commands/memory/leakfind.md) command. It recursively inspects address ranges for pointers, and reports on all pointers found. + +![](assets/caps/leakfind.png) + +### Telescope +Inspecting memory dumps is easy with the [`telescope`](commands/memory/telescope.md) command. It recursively dereferences a range of memory, letting you see everything at once. As an added bonus, Pwndbg checks all of the available registers to see if they point into the memory range. + +![](assets/caps/telescope.png){ style="width: 70%;" } + +### Virtual Memory Maps +Pwndbg enhances the standard memory map listing and allows easy searching with [`vmmap`](commands/memory/vmmap.md). + +![](assets/caps/vmmap.png){ style="width: 70%;" } +![](assets/caps/vmmap_rip.png){ style="width: 70%;" } diff --git a/docs/misc/binja_integration.md b/docs/misc/binja-integration.md similarity index 100% rename from docs/misc/binja_integration.md rename to docs/misc/binja-integration.md diff --git a/docs/misc/env_vars.md b/docs/misc/env-vars.md similarity index 100% rename from docs/misc/env_vars.md rename to docs/misc/env-vars.md diff --git a/docs/misc/gdb-lldb-commands.md b/docs/misc/gdb-lldb-commands.md new file mode 100644 index 000000000..579659f42 --- /dev/null +++ b/docs/misc/gdb-lldb-commands.md @@ -0,0 +1,45 @@ +# GDB vs LLDB + +For users who are migrating from one debugger to another, here is a table comparison of some of the most common actions and how to do them in GDB and LLDB. Note that both debuggers offer shorthands for typing these commands. + +| **Functionality** | **GDB Command** | **LLDB Command** | +|-----------------------------------------------|----------------------------------------|-------------------------------------------------------------| +| **Start Debugging Program** | `gdb ./your-program` | `lldb ./your-program` | +| **Set a Breakpoint** | `break ` | `breakpoint set --name ` | +| **Set Breakpoint on Address** | `break *
` | `breakpoint set --address
` | +| **Set Breakpoint at Line** | `break :` | `breakpoint set --file --line ` | +| **Set Hardware Breakpoint** | `hbreak ` | `breakpoint set --hardware --name ` | +| **Set Hardware Breakpoint at Memory** | `hbreak *` | `breakpoint set --hardware --address ` | +| **List All Breakpoints** | `info breakpoints` | `breakpoint list` | +| **Delete Breakpoints** | `delete ` | `breakpoint delete ` | +| **Set Watchpoint** | `watch ` | `watchpoint set variable ` | +| **Set Conditional Breakpoint** | `break if ` | `breakpoint set --condition ""` | +| **Continue Execution** | `continue` | `process continue` | +| **Next Instruction** | `next` | `thread step-over` | +| **Step into a Function** | `step` | `thread step-in` | +| **Step out of a Function** | `finish` | `thread step-out` | +| **Print Threads** | `info threads` | `thread list` | +| **Select Thread** | `thread ` | `thread select ` | +| **Print Register Values** | `info registers` | `register read -a` | +| **Print a Variable** | `print ` | `print ` | +| **Display Variable on Every Stop** | `display ` | `expression --watch ` | +| **Examine Memory (Hex)** | `x/x ` | `memory read --format x --count ` | +| **Examine Memory (Integer)** | `x/d ` | `memory read --format d --count ` | +| **Inspect Stack Trace** | `backtrace` | `thread backtrace` | +| **Change Register Value** | `set $ = ` | `register write ` | +| **Check Program Status** | `info locals` | `frame variable` | +| **Check Program Info** | `info functions` | `image lookup --functions` | +| **Show Disassembly of Function** | `disas ` | `disassemble ` | +| **Memory Dump (Hex)** | `x/xh ` | `memory read --format x --count ` | +| **Memory Dump (Bytes)** | `x/bx ` | `memory read --format b --count ` | +| **Show Process Information** | `info process` | `process status` | +| **Quit Debugging** | `quit` | `quit` | +| **Run Program with Arguments** | `run ...` | `process launch -- ...` | +| **Show Current Function** | `info frame` | `frame info` | +| **Set Sysroot** | `set sysroot ` | `settings set target.sysroot ` | +| **Set Source Directory** | `directory ` | `settings set target.source-map ` | +| **Set Architecture** | `set architecture ` | `target create --arch ` | +| **Show Settings** | `show ` | `settings show ` | +| **Set File for Debugging** | `file ` | `target create ` | +| **Start the Program and Run One Instruction** | `starti` | `process launch --stop-at-entry` | +| **Enable ASLR** | `set disable-randomization off` | `settings set target.disable-aslr false` | diff --git a/docs/misc/gdb-tui.md b/docs/misc/gdb-tui.md new file mode 100644 index 000000000..e88e74c86 --- /dev/null +++ b/docs/misc/gdb-tui.md @@ -0,0 +1,13 @@ +# GDB TUI + +![](../assets/caps/context_tui.png) + +The context sections are available as native [GDB TUI](https://sourceware.org/gdb/current/onlinedocs/gdb.html/TUI.html) windows named `pwndbg_[sectionname]`. There are some predefined layouts coming with pwndbg which you can select using `layout pwndbg` or `layout pwndbg_code`. + +Use `focus cmd` to focus the command window and have the arrow keys scroll through the command history again. `tui disable` to disable TUI mode and go back to CLI mode when running commands with longer output. `ctrl-x + a` toggles between TUI and CLI mode quickly. Hold shift to ignore the TUI mouse integration and use the mouse normally to select text or copy data. + +To create [your own layout](https://sourceware.org/gdb/current/onlinedocs/gdb.html/TUI-Commands.html) and selecting it use normal `tui new-layout` syntax like: +``` +tui new-layout pwndbg_custom {-horizontal { { -horizontal { pwndbg_code 1 pwndbg_disasm 1 } 2 { {-horizontal pwndbg_legend 8 pwndbg_control 2 } 1 pwndbg_regs 6 pwndbg_stack 6 } 3 } 7 cmd 3 } 3 { pwndbg_backtrace 2 pwndbg_threads 1 pwndbg_expressions 2 } 1 } 1 status 1 +layout pwndbg_custom +``` diff --git a/docs/misc/ghidra-integration.md b/docs/misc/ghidra-integration.md new file mode 100644 index 000000000..b11c4b764 --- /dev/null +++ b/docs/misc/ghidra-integration.md @@ -0,0 +1,27 @@ +# Ghidra Integration + +With the help of [radare2](https://github.com/radareorg/radare2) or [rizin](https://github.com/rizinorg/rizin) it is possible to show the decompiled source code of the ghidra decompiler. + +However, this comes with some prerequisites. + +* First: you have to have installed radare2 or rizin and it must be found by gdb (within path) +* Second: you have to install the ghidra plugin for radare2 + [r2ghidra](https://github.com/radareorg/r2ghidra) or install the ghidra plugin for rizin [rz-ghidra](https://github.com/rizinorg/rz-ghidra) +* Third: r2pipe has to be installed in the python-context gdb is using (or if you are using rizin, install rzpipe instead) + +The decompiled source be shown as part of the context by adding `ghidra` to `set context-sections` +or by calling `ctx-ghidra [function]` manually. + +Be warned, the first call to both radare2/r2ghidra and rizin/rz-ghidra are rather slow! Subsequent requests for decompiled +source will be faster. And it does take up some resources as the radare2/rizin instance is kept by r2pipe/rzpipe +to enable faster subsequent analysis. + +With those performance penalties it is reasonable to not have it launch always. Therefore it includes +an option to only start it when required with `set context-ghidra`: + +* `set context-ghidra always`: always trigger the ghidra context +* `set context-ghidra never`: never trigger the ghidra context except when called manually +* `set context-ghidra if-no-source`: invoke ghidra if no source code is available + +Remark: the plugin tries to guess the correct current line and mark it with "-->", but it might +get it wrong. diff --git a/docs/misc/go_debugging.md b/docs/misc/go-debugging.md similarity index 100% rename from docs/misc/go_debugging.md rename to docs/misc/go-debugging.md diff --git a/docs/misc/pwndbg_users.md b/docs/misc/pwndbg-users.md similarity index 100% rename from docs/misc/pwndbg_users.md rename to docs/misc/pwndbg-users.md diff --git a/docs/misc/pycharm_debugging.md b/docs/misc/pycharm-debugging.md similarity index 100% rename from docs/misc/pycharm_debugging.md rename to docs/misc/pycharm-debugging.md diff --git a/docs/misc/splitting-the-context.md b/docs/misc/splitting-the-context.md new file mode 100644 index 000000000..3fb6c489d --- /dev/null +++ b/docs/misc/splitting-the-context.md @@ -0,0 +1,54 @@ +# Splitting / Layouting Context + +i.e. doing this: +![](../assets/caps/context_splitting.png) + +In Pwndbg, the context sections can be distributed among different tty by using the [`contextoutput`](../commands/context/contextoutput.md) command. Example: +``` +contextoutput stack /path/to/tty true +``` + +If you use a terminal or multiplexer that supports scripted pane splitting, you can write a Python script that will create the panes and distribute them to your liking whenever you start pwndbg. + +For instance, for tmux, you could write something like this: +```python +python +import atexit +import os +from pwndbg.commands.context import contextoutput, output, clear_screen +bt = os.popen('tmux split-window -P -F "#{pane_id}:#{pane_tty}" -d "cat -"').read().strip().split(":") +st = os.popen(F'tmux split-window -h -t {bt[0]} -P -F '+'"#{pane_id}:#{pane_tty}" -d "cat -"').read().strip().split(":") +re = os.popen(F'tmux split-window -h -t {st[0]} -P -F '+'"#{pane_id}:#{pane_tty}" -d "cat -"').read().strip().split(":") +di = os.popen('tmux split-window -h -P -F "#{pane_id}:#{pane_tty}" -d "cat -"').read().strip().split(":") +panes = dict(backtrace=bt, stack=st, regs=re, disasm=di) +for sec, p in panes.items(): + contextoutput(sec, p[1], True) +contextoutput("legend", di[1], True) +atexit.register(lambda: [os.popen(F"tmux kill-pane -t {p[0]}").read() for p in panes.values()]) +end +``` +If you're using tmux specifically, you can use [pwnmux](https://github.com/joaogodinho/pwnmux) as a prebuilt layout or [splitmind](https://github.com/jerdna-regeiz/splitmind) to easily configure the layout you want. + +!!! example + + The above example uses splitmind and following configuration: + ```python + python + import splitmind + (splitmind.Mind() + .tell_splitter(show_titles=True) + .tell_splitter(set_title="Main") + .right(display="backtrace", size="25%") + .above(of="main", display="disasm", size="80%", banner="top") + .show("code", on="disasm", banner="none") + .right(cmd='tty; tail -f /dev/null', size="65%", clearing=False) + .tell_splitter(set_title='Input / Output') + .above(display="stack", size="75%") + .above(display="legend", size="25") + .show("regs", on="legend") + .below(of="backtrace", cmd="ipython", size="30%") + ).build(nobanner=True) + end + ``` + +If you're using kitty, you may check out [kittydbg](https://github.com/k4lizen/kittydbg) for a prebuilt layout. diff --git a/pwndbg/commands/context.py b/pwndbg/commands/context.py index e3f58fa2c..1b3bc2590 100644 --- a/pwndbg/commands/context.py +++ b/pwndbg/commands/context.py @@ -564,7 +564,21 @@ parser.add_argument( ) -@pwndbg.commands.Command(parser, aliases=["ctx-watch", "cwatch"], category=CommandCategory.CONTEXT) +@pwndbg.commands.Command( + parser, + aliases=["ctx-watch", "cwatch"], + category=CommandCategory.CONTEXT, + examples=""" +For watching variables/expressions: + cwatch BUF + cwatch ITEMS[0] + +For running commands: + cwatch execute "ds BUF" + cwatch execute "x/20x $rsp" + cwatch execute "info args" + """, +) def contextwatch(expression, cmd) -> None: expressions.append((expression, cmd)) diff --git a/pwndbg/commands/dumpargs.py b/pwndbg/commands/dumpargs.py index 277f54942..c38de9a5c 100644 --- a/pwndbg/commands/dumpargs.py +++ b/pwndbg/commands/dumpargs.py @@ -11,7 +11,9 @@ import pwndbg.commands import pwndbg.commands.telescope from pwndbg.commands import CommandCategory -parser = argparse.ArgumentParser(description="Prints determined arguments for call instruction.") +parser = argparse.ArgumentParser( + description="Prints determined arguments for call/syscall instruction." +) parser.add_argument("-f", "--force", action="store_true", help="Force displaying of all arguments.") diff --git a/pwndbg/commands/slab.py b/pwndbg/commands/slab.py index 1b1816833..2b059cc22 100644 --- a/pwndbg/commands/slab.py +++ b/pwndbg/commands/slab.py @@ -25,7 +25,9 @@ from pwndbg.aglib.kernel.slab import find_containing_slab_cache from pwndbg.commands import CommandCategory from pwndbg.lib.exception import IndentContextManager -parser = argparse.ArgumentParser(description="Prints information about the slab allocator") +parser = argparse.ArgumentParser( + description="Prints information about the linux kernel's slab allocator SLUB." +) subparsers = parser.add_subparsers(dest="command") # The command will still work on 3.6 and earlier, but the help won't be shown