voltron/README.md

93 lines
3.6 KiB
Markdown
Raw Normal View History

Voltron
2013-06-25 09:07:17 +00:00
=======
2014-10-28 12:44:51 +00:00
Voltron is an extensible debugger UI for hackers. It allows you to attach utility views running in other terminals to your debugger (LLDB or GDB), displaying helpful information such as disassembly, stack contents, register values, etc, while still giving you the same debugger CLI you're used to. You can still have your pimped out custom prompt, macros, plugins, terminal colour scheme - whatever you're used to - but you get the added bonus of a sweet customisable heads-up display.
2013-06-29 17:56:57 +00:00
2014-09-28 04:06:07 +00:00
Voltron also provides a platform on which to build your own UI views, requesting and processing data from the debugger back end to suit your own requirements. To this end, Voltron provides (and uses internally) a JSON API available over UNIX domain sockets, TCP sockets and an HTTP server.
2013-06-25 09:07:17 +00:00
2014-10-29 07:18:30 +00:00
![voltron example](http://i.imgur.com/niDtVjN.png)
2013-06-25 09:07:17 +00:00
Support
-------
2013-06-25 09:07:17 +00:00
2014-10-17 11:53:34 +00:00
`voltron` is built primarily for LLDB, and also supports GDB version 7 and later.
2013-07-08 03:31:11 +00:00
The following architectures are supported:
* x86
* x86_64
2013-10-09 06:40:46 +00:00
* armv7s
* arm64
2013-10-29 08:52:23 +00:00
arm64 support is LLDB-only at this stage.
Installation
------------
A standard python setup script is included.
2013-07-11 04:16:42 +00:00
# python setup.py install
2013-10-31 13:22:26 +00:00
This will install the `voltron` egg wherever that happens on your system, and an executable named `voltron` to `/usr/local/bin/`.
2013-07-08 17:57:47 +00:00
Quick Start
-----------
2013-06-25 09:07:17 +00:00
1. Configure your debugger to load Voltron when it starts by sourcing the `dbgentry.py` entry point script. The full path will be inside the `voltron` egg. For example, on OS X it might be */Library/Python/2.7/site-packages/voltron-0.1-py2.7.egg/dbgentry.py*.
2013-10-31 13:20:11 +00:00
For LLDB:
2013-06-25 09:07:17 +00:00
command script import /path/to/voltron/dbgentry.py
2013-07-04 18:08:57 +00:00
For GDB:
2013-07-04 18:08:57 +00:00
2014-09-28 04:20:46 +00:00
source /path/to/voltron/dbgentry.py
voltron init
2013-07-04 18:08:57 +00:00
This part can go in your `.lldbinit` or `.gdbinit` so it's automatically executed when the debugger starts.
2. Start your debugger. On LLDB you need to call `voltron init` after you load the inferior, as a target must be loaded before Voltron's hooks can be installed. This means `voltron init` cannot be called from `.lldbinit` the way it can from `.gdbinit`. Hopefully this will be remedied with a more versatile hooking mechanism in a future version of LLDB (this has been discussed with the developers).
2013-07-04 18:08:57 +00:00
$ lldb file_to_debug
(lldb) voltron init
2013-07-04 18:08:57 +00:00
3. In another terminal (I use iTerm panes) start one of the UI views
$ voltron view reg -v
$ voltron view stack
$ voltron view disasm
$ voltron view bt
$ voltron view cmd 'reg read'
2013-07-04 18:08:57 +00:00
2014-10-28 12:44:51 +00:00
4. Set a breakpoint and run your inferior. Once the inferior has started and the debugger has stopped (either because you interrupted it or because it hit a breakpoint) the views will update.
2013-10-31 13:20:11 +00:00
(*db) b main
(*db) run
2013-10-31 13:20:11 +00:00
5. The debugger should hit the breakpoint and the views will be updated. A forced update can be triggered with the following command:
2013-07-04 18:37:31 +00:00
(lldb) voltron stopped
2013-07-04 18:08:57 +00:00
2014-09-28 04:06:07 +00:00
Documentation
-------------
2014-09-28 04:06:07 +00:00
See the [wiki](https://github.com/snare/voltron/wiki) on github.
2013-06-25 09:07:17 +00:00
Bugs
----
2014-09-28 04:06:07 +00:00
See the [issue tracker](https://github.com/snare/voltron/issues) on github.
2013-06-25 09:07:17 +00:00
License
-------
This software is released under the "Buy snare a beer" license. 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](http://github.com/richo) definitely deserves a few beers for his contributions.
Credits
-------
2014-09-28 04:06:07 +00:00
Thanks to Azimuth Security for letting me spend time working on this.
Props to [richo](http://github.com/richo) for all his contributions to Voltron.
[fG!](http://github.com/gdbinit)'s gdbinit was the original inspiration for this project.