Convert Figma logo to code with AI

snare logovoltron

A hacky debugger UI for hackers

6,149
412
6,149
86
View on GitHub

Top Related Projects

cs01's avatar

gdbgui

9,846

Browser-based frontend to gdb (gnu debugger). Add breakpoints, view the stack, visualize data structures, and more in C, C++, Go, Rust, and Fortran. Run gdbgui from the terminal and a new tab will open in your browser.

hugsy's avatar

gef

6,807

GEF (GDB Enhanced Features) - a modern experience for GDB with advanced debugging capabilities for exploit devs & reverse engineers on Linux

pwndbg's avatar

pwndbg

7,268

Exploit Development and Reverse Engineering with GDB Made Easy

longld's avatar

peda

5,843

PEDA - Python Exploit Development Assistance for GDB

cyrus-and's avatar

gdb-dashboard

10,951

Modular visual interface for GDB in Python

Quick Overview

Voltron is a debugger UI toolkit written in Python. It aims to improve the user experience of various debuggers (GDB, LLDB, WinDbg, VDB, and others) by providing a modular, customizable interface that can be used standalone or integrated into other tools.

Pros

  • Highly customizable and extensible UI for debugging
  • Supports multiple debuggers across different platforms
  • Can be used as a standalone tool or integrated into other applications
  • Provides a consistent interface across different debugging environments

Cons

  • Requires Python knowledge for advanced customization
  • May have a steeper learning curve compared to built-in debugger interfaces
  • Documentation could be more comprehensive for some advanced features
  • Dependent on external debuggers, which may have their own limitations

Code Examples

  1. Registering a new command:
import voltron

@voltron.command()
def my_command(args):
    """My custom command"""
    # Command implementation here
    return "Command executed successfully"
  1. Creating a custom view:
from voltron.view import TerminalView

class MyCustomView(TerminalView):
    def render(self):
        # Custom rendering logic here
        return self.proc.format_disasm()
  1. Interacting with the debugger:
from voltron import debugger

# Get current instruction pointer
ip = debugger.program_counter()

# Read memory at address
data = debugger.read_memory(ip, 16)

# Set a breakpoint
debugger.set_breakpoint('main')

Getting Started

  1. Install Voltron:

    pip install voltron

  2. Initialize Voltron in your debugger:

    • For GDB: Add source /path/to/voltron/entry.py to your .gdbinit
    • For LLDB: Add command script import /path/to/voltron/entry.py to your .lldbinit

  3. Start your debugger and run Voltron:

    $ gdb ./my_program
(gdb) voltron init

  4. Open Voltron views in separate terminal windows:

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

Competitor Comparisons

cs01 logo

gdbgui

9,846

Browser-based frontend to gdb (gnu debugger). Add breakpoints, view the stack, visualize data structures, and more in C, C++, Go, Rust, and Fortran. Run gdbgui from the terminal and a new tab will open in your browser.

Pros of gdbgui

  • Web-based interface, accessible through a browser
  • More user-friendly for those new to debugging
  • Actively maintained with regular updates

Cons of gdbgui

  • Requires a web browser to operate
  • May have a steeper learning curve for experienced GDB users
  • Limited customization options compared to Voltron

Code Comparison

gdbgui (Python):

@app.route('/gdbgui')
def gdbgui_page():
    return render_template('gdbgui.pug',
        debug=app.debug,
        interpreter=sys.executable,
        initial_data=initial_data,
        themes=THEMES,
    )

Voltron (Python):

def register_command_handler(self, name, handler):
    if name not in self.command_handlers:
        self.command_handlers[name] = []
    self.command_handlers[name].append(handler)

Both projects are written in Python and aim to enhance the GDB debugging experience. gdbgui focuses on providing a web-based interface, making it more accessible to users who prefer graphical interfaces. Voltron, on the other hand, offers a more customizable and extensible approach, allowing users to create their own views and integrate with various debuggers and front-ends.

hugsy logo

gef

6,807

GEF (GDB Enhanced Features) - a modern experience for GDB with advanced debugging capabilities for exploit devs & reverse engineers on Linux

Pros of GEF

  • More actively maintained with frequent updates
  • Broader feature set including exploit development tools
  • Better integration with GDB, providing a more seamless debugging experience

Cons of GEF

  • Steeper learning curve due to more complex features
  • Potentially slower performance on large binaries
  • Less cross-platform compatibility compared to Voltron

Code Comparison

GEF command example:

gef> checksec
[+] checksec for '/bin/ls'
Canary                        : ✓
NX                            : ✓
PIE                           : ✓
Fortify                       : ✓
RelRO                         : Full

Voltron command example:

(lldb) voltron view stack
0x7fff5fbff6d0│+0x0000: 0x00007fff5fbff6e0  →  0x00007fff5fbff730  →  0x0000000000000001
0x7fff5fbff6d8│+0x0008: 0x0000000100000f40  →  0x0000000100000f40  →  <main+0> push rbp
0x7fff5fbff6e0│+0x0010: 0x00007fff5fbff730  →  0x0000000000000001
0x7fff5fbff6e8│+0x0018: 0x0000000100000f22  →  <start+34> hlt

Both tools enhance debugging capabilities, but GEF offers more advanced features at the cost of complexity, while Voltron focuses on simplicity and cross-platform support.

pwndbg logo

pwndbg

7,268

Exploit Development and Reverse Engineering with GDB Made Easy

Pros of pwndbg

  • More actively maintained with frequent updates
  • Tighter integration with GDB, offering seamless debugging experience
  • Extensive set of commands tailored for exploit development and reverse engineering

Cons of pwndbg

  • Steeper learning curve due to more complex features
  • Can be slower to load and initialize compared to Voltron

Code Comparison

pwndbg:

from pwndbg.commands import Command
from pwndbg.commands import cmdwrapper

@Command
def example_command(address):
    print(f"Examining address: {address}")

Voltron:

from voltron.plugin import api
from voltron.api import APIResponse

class ExampleAPI(api.APIPlugin):
    def example_command(self, address):
        return APIResponse({"address": address})

Key Differences

  • pwndbg focuses on enhancing GDB for exploit development, while Voltron aims to provide a unified debugging interface across multiple debuggers
  • pwndbg offers more built-in commands and features specific to binary analysis, whereas Voltron provides a more flexible, modular approach
  • pwndbg is primarily used within GDB, while Voltron supports multiple debuggers and can be used as a standalone tool

Both tools are valuable for different use cases, with pwndbg being more specialized for exploit development and Voltron offering greater flexibility across debugging environments.

longld logo

peda

5,843

PEDA - Python Exploit Development Assistance for GDB

Pros of PEDA

  • Lightweight and easy to set up, requiring minimal configuration
  • Provides colorized and enhanced GDB output for better readability
  • Includes useful commands for memory analysis and exploit development

Cons of PEDA

  • Limited to GDB and x86/x64 architectures
  • Less extensive debugging features compared to Voltron's multi-debugger support
  • May not be as actively maintained as Voltron

Code Comparison

PEDA command example:

gdb-peda$ checksec
CANARY    : disabled
FORTIFY   : disabled
NX        : ENABLED
PIE       : disabled
RELRO     : Partial

Voltron command example:

(gdb) voltron view stack
0x7fffffffdf78│+0x00: 0x00000000004005b0  →  <main+0> push rbp
0x7fffffffdf80│+0x08: 0x00007ffff7a2d830  →  <__libc_start_main+240> mov edi, eax
0x7fffffffdf88│+0x10: 0x0000000000000001
0x7fffffffdf90│+0x18: 0x00007fffffffdfb8  →  0x00007fffffffe2ed  →  "/home/user/example"
0x7fffffffdf98│+0x20: 0x0000000100000000

Both tools enhance GDB functionality, but Voltron offers a more flexible and extensible framework for debugging across multiple platforms and debuggers, while PEDA focuses on providing a streamlined experience specifically for GDB users working with x86/x64 architectures.

cyrus-and logo

gdb-dashboard

10,951

Modular visual interface for GDB in Python

Pros of gdb-dashboard

  • Lightweight and easy to set up, requiring no additional dependencies
  • Provides a clean, customizable dashboard layout within GDB
  • Offers a modular design, allowing users to enable/disable specific modules

Cons of gdb-dashboard

  • Limited to GDB only, not supporting other debuggers
  • Less extensive feature set compared to Voltron's multi-debugger capabilities
  • May require more manual configuration for advanced use cases

Code Comparison

gdb-dashboard:

class Dashboard:
    def __init__(self):
        self.modules = []
        self.enabled = True

    def add_module(self, module):
        self.modules.append(module)

Voltron:

class View(object):
    def __init__(self, *args, **kwargs):
        self.args = kwargs.get('args', [])
        self.body = None
        self.client = None

Both projects aim to enhance the debugging experience, but gdb-dashboard focuses on providing a streamlined, built-in solution for GDB users, while Voltron offers a more comprehensive, multi-debugger approach with additional features and flexibility.

Convert Figma logo designs to code with AI

Visual Copilot

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

Voltron

build

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:

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

The author's setup looks something like this:

voltron example LLDB

Any debugger command can be split off into a view and highlighted with a specified Pygments lexer:

command views

More screenshots are here.

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

If you are on Windows without a shell, have problems installing, or would prefer to install manually, please see the manual installation documentation.

Quick Start

  1. 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

  2. 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

  3. 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

  4. Set a breakpoint and run your inferior.

     (*db) b main
 (*db) run

  5. 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.

Documentation

See the wiki on github.

FAQ

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.

LLDB

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.

WinDbg

More information about WinDbg/CDB support here.

Misc

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.

License

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.

Credits

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.