Voltron is an extensible debugger UI toolkit written in Python. It aims to improve the user experience of various debuggers (LLDB, GDB, VDB and WinDbg) by enabling the attachment of utility views that can retrieve and display data from the debugger host. By running these views in other TTYs, you can build a customized debugger user interface to suit your needs.

Voltron does not aim to be everything to everyone. It’s not a wholesale replacement for your debugger’s CLI. Rather, it aims to complement your existing setup and allow you to extend your CLI debugger as much or as little as you like. If you just want a view of the register contents in a window alongside your debugger, you can do that. If you want to go all out and have something that looks more like OllyDbg, you can do that too.

Built-in views are provided for:

  • Registers
  • Disassembly
  • Stack
  • Memory
  • Breakpoints
  • Backtrace

Support

Voltron supports LLDB, GDB, VDB and WinDbg/CDB (via PyKD) and runs on macOS, Linux and Windows.

WinDbg support is still fairly new, please open an issue if you have problems.

The following architectures are supported:

lldbgdbvdbwindbg
x86
x86_64
arm
arm64
powerpc

Installation

Note: Only macOS and Debian derivatives are fully supported by the install script. It should hopefully not fail on other Linux distros, but it won’t try to install package dependencies. If you’re using another distro, have a look at install.sh to work out what dependencies you might need to install before running it.

Download the source and run the install script:

$ git clone https://github.com/snare/voltron
$ cd voltron
$ ./install.sh

By default, the install script will install into the user’s site-packages directory. If you want to install into the system site-packages, use the -s flag:

$ ./install.sh -s

You can also install into a virtual environment (for LLDB only) like this:

$ ./install.sh -v /path/to/venv -b lldb

Quick Start

  • If your debugger has an init script (.lldbinit for LLDB or .gdbinit for GDB) configure it to load Voltron when it starts by sourcing the entry.py entry point script. The full path will be inside the voltron package. For example, on macOS it might be /Library/Python/2.7/site-packages/voltron/entry.py. The install.sh script will add this to your .gdbinit or .lldbinit file automatically if it detects GDB or LLDB in your path.LLDB:

command script import /path/to/voltron/entry.py

GDB:

source /path/to/voltron/entry.py

  • Start your debugger and initialise Voltron manually if necessary.

On recent versions of LLDB you do not need to initialise Voltron manually:

$ lldb target_binary

  • On older versions of LLDB you need to call voltron init after you load the inferior:

$ lldb target_binary
(lldb) voltron init

GDB:

$ gdb target_binary

VDB:

$ ./vdbbin target_binary

script /path/to/voltron/entry.py

WinDbg/CDB is only supported run via Bash with a Linux userland. The author tests with Git Bash and ConEmu. PyKD and Voltron can be loaded in one command when launching the debugger:

$ cdb -c ‘.load C:\path\to\pykd.pyd ; !py –global C:\path\to\voltron\entry.py’ target_binary

In another terminal (I use iTerm panes) start one of the UI views. On LLDB, WinDbg and GDB the views will update immediately. On VDB they will not update until the inferior stops (at a breakpoint, after a step, etc):

$ voltron view register
$ voltron view stack
$ voltron view disasm
$ voltron view backtrace

Set a breakpoint and run your inferior.

(*db) b main
(*db) run

When the debugger hits the breakpoint, the views will be updated to reflect the current state of registers, stack, memory, etc. Views are updated after each command is executed in the debugger CLI, using the debugger’s “stop hook” mechanism. So each time you step, or continue and hit a breakpoint, the views will update.