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 customised 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:
The author's setup looks something like this:
Any debugger command can be split off into a view and highlighted with a specified Pygments lexer:
More screenshots are here.
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:
The Voltron package and its dependencies must be installed somewhere the Python interpreter embedded in the debugger can find them. Voltron includes an install script which will attempt to detect the supported debuggers that are installed on the system, and will install Voltron and its Python dependencies using the appropriate version of Python for each debugger.
To install with the install script, download the source and run it from the root level of the source tree:
If you'd rather install to the system
site-packages directory, pass the
$ ./install.sh -s
You can also install into a Python virtual environment for LLDB:
$ ./install.sh -v /path/to/venv -b lldb
This install script should cover the vast majority of use cases, but if it fails to install properly on your system (or you'd rather install manually) the following instructions are provided for each platform.
On macOS, LLDB (installed by Xcode) and GDB (installed by Homebrew) are both linked against the system's default version of Python, so Voltron must be installed using this version of Python. On systems without any other Python installation, you can just go ahead and install with
pip as above.
On systems with other versions of Python installed (via Homebrew, MacPorts or other methods), you may need to explicitly specify the system version of Python:
$ /usr/bin/python -m pip install voltron [ --user ]
Other installations of LLDB or GDB (manually compiled or installed with MacPorts) may be linked with other Python installations, so you'll need to install Voltron with whichever the debugger is linked against.
You can find out which version of Python your debugger is linked against with
$ otool -L /usr/local/bin/gdb|grep -i python /System/Library/Frameworks/Python.framework/Versions/2.7/Python (compatibility version 2.7.0, current version 2.7.5)
This version of GDB above is installed with Homebrew, so it's linked against the system Python. You'll have to figure out which installation of Python your debugger is linked with and where the
python binary is on your own, but when you do you can install Voltron with:
$ /path/to/python -m pip install voltron [ --user ]
Ubuntu (at least 14.04) comes with Python versions 2 and 3. GDB is linked with Python 3, but
/usr/bin/python is Python 2. In order to get Voltron to work you'll need to install Voltron into the Python 3 site-packages.
First, install some dependencies:
$ sudo apt-get install libreadline6-dev python3-dev python3-setuptools python3-yaml
Then install Voltron:
$ pip3 install voltron
You're mostly on your own here. You can figure out which version of Python the debugger is linked with using
$ readelf -d `which gdb`|grep python 0x0000000000000001 (NEEDED) Shared library: [libpython3.4m.so.1.0]
Then you'll need to install Voltron using that version of Python, wherever it lives:
$ /path/to/python -m pip install voltron [ --user ]
Voltron support for WinDbg is implemented by way of the PyKD module.
- Install WinDbg via Windows SDK for your Windows version
- Download the zip of the latest release of PyKD
- Install the PyKD module. If you know how to do this properly (install it to the WinDbg extensions dir, which I gave up on because it didn't want to work on my system), then do it. I just load it in WinDbg by absolute path.
- Install the PyKD Python wheel with pip:
$ pip install pykd-0.3.0.38-py2-none-win_amd64.whl
- Install the curses Python wheel:
$ pip install curses-2.2-cp27-none-win_amd64.whl
- Make sure you have the same bitness versions of Python and PyKD (possibly WinDbg but I don't think there's an option).
Voltron can be installed into a Python virtual environment if you'd rather not install it (and all its dependencies) into your Python
site-packages directory. You'll need to make sure you're using the correct installation of Python per the installation instructions above.
Create a virtual environment:
$ virtualenv voltron_venv
Or, if you're using a Python installation that the
virtualenv executable in your path does not belong to:
$ /path/to/python -m virtualenv voltron_venv
Install Voltron into the virtual environment:
$ voltron_venv/bin/pip install voltron
Now when you launch the debugger, you'll need to set your
PYTHONPATH environment variable:
$ PYTHONPATH=voltron_venv/lib/python2.7/site-packages lldb
Note the Python version in the path there - that will need to reflect whatever the actual path to the
site-packages dir inside the virtual environment is. You could also set and export this variable in your shell init.
When you launch the views, you'll need to call the
voltron executable inside the virtual environment:
$ voltron_venv/bin/voltron view reg
You could also add the venv to your
PATH environment variable.
Please see the manual installation documentation.
- If your debugger has an init script (
.lldbinitfor LLDB or
.gdbinitfor GDB) configure it to load Voltron when it starts by sourcing the
entry.pyentry point script. The full path will be inside the
voltronpackage. For example, on macOS it might be /Library/Python/2.7/site-packages/voltron/entry.py. The
install.shscript will add this to your
.lldbinitfile automatically if it detects GDB or LLDB in your path.LLDB:
command script import /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 initafter you load the inferior:
$ lldb target_binary (lldb) voltron init
$ gdb target_binary
$ ./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.
See the wiki on github.
Q. Why am I getting an
ImportError loading Voltron?
A. You might have multiple versions of Python installed and have installed Voltron using the wrong one. See the more detailed installation instructions.
Q. GEF? PEDA? PwnDbg? fG's gdbinit?
A. All super great extensions for GDB. These tools primarily provide sets of additional commands for exploitation tasks, but each also provides a "context" display with a view of registers, stack, code, etc, like Voltron. These tools print their context display in the debugger console each time the debugger stops. Voltron takes a different approach by embedding an RPC server implant in the debugger and enabling the attachment of views from other terminals (or even web browsers, or now synchronising with Binary Ninja), which allows the user to build a cleaner multi-window interface to their debugger. Voltron works great alongside all of these tools. You can just disable the context display in your GDB extension of choice and hook up some Voltron views, while still getting all the benefits of the useful commands added by these tools.
Bugs and Errata
See the issue tracker on github for more information or to submit issues.
If you're experiencing an
ImportError loading Voltron, please ensure you've followed the installation instructions for your platform.
On older versions of LLDB, the
voltron init command must be run manually after loading the debug target, as a target must be loaded before Voltron's hooks can be installed. Voltron will attempt to automatically register its event handler, and it will inform the user if
voltron init is required.
More information about WinDbg/CDB support here.
The authors primarily use Voltron with the most recent version of LLDB on macOS. We will try to test everything on as many platforms and architectures as possible before releases, but LLDB/macOS/x64 is going to be by far the most frequently-used combination. Hopefully Voltron doesn't set your pets on fire, but YMMV.
See the LICENSE file.
If you use this and don't hate it, buy me a beer at a conference some time. This license also extends to other contributors - richo definitely deserves a few beers for his contributions.
Thanks to my former employers Assurance and Azimuth Security for giving me time to spend working on this.
Props to richo for all his contributions to Voltron.
fG!'s gdbinit was the original inspiration for this project.
Thanks to Willi for implementing the VDB support.
Voltron now uses Capstone for disassembly as well as the debugger hosts' internal disassembly mechanism. Capstone is a powerful, open source, multi-architecture disassembler upon which the next generation of reverse engineering and debugging tools are being built. Check it out.
Thanks to grazfather for ongoing contributions.
- Hakin9 is a monthly magazine dedicated to hacking and cybersecurity. In every edition, we try to focus on different approaches to show various techniques - defensive and offensive. This knowledge will help you understand how most popular attacks are performed and how to protect your data from them. Our tutorials, case studies and online courses will prepare you for the upcoming, potential threats in the cyber security world. We collaborate with many individuals and universities and public institutions, but also with companies such as Xento Systems, CATO Networks, EY, CIPHER Intelligence LAB, redBorder, TSG, and others.
- Blog2022.12.13What are the Common Security Weaknesses of Cloud Based Networks?
- Blog2022.10.12Vulnerability management with Wazuh open source XDR
- Blog2022.08.29Deception Technologies: Improving Incident Detection and Response by Alex Vakulov
- Blog2022.08.25Exploring the Heightened Importance of Cybersecurity in Mobile App Development by Jeff Kalwerisky