Python binding
Axion can easily be extended in python thanks to the python API. Moreover, Axion is shipped with a few plugins and external scripts:
Percent addon
The percent addon add the capability of jumping between stack memory accesses. If the currently selected instruction writes something on the stack, percent will go to the next instruction reading the memory, on the other way, if the current instruction is reading some value on the stack, percent will jump on the previous instruction writting the memory. In practice, this is very useful to follow push/pop operands or call/ret boundaries.
The addon is named percent as it has been designed to work like the vim editor percent keybinding on curly brackets.
To use this addon, you must map a key to the to plugin in the shortcut configuration panel.
Gdbserver addon
The Gdbserver addon provides compatibility with the common gdb serial protocol api and migth be useful to users who need to use their favorite gdb compatible debugger as REVEN frontend. You can start the listening server via a graphical widget accessible through the Window menu.
To simply test the addon, start the service through the widget, and then connect to it with gdb command line.
Qb-sync addon
Qb-Sync is a Quarkslab's tool which enables synchronisation between an IDA instance and remote debugger.
To use this addon there are several prerequisites:
- The binary mapping informations must be available in Reven. If you manually generate the scenario and omit to run the dump_process tool or run it too early (before the target binary is mapped), you will not be able to use this addon.
- You must ensure network connectivity between Axion and IDA hosts.
Qb-Sync allows remote setup, that is having IDA on a different host than the backend debugger (REVEN). To allow this kind of configuration, the Qb-Sync IDA plugin handles debugger events through a network socket and dispatch it to the right IDA window. More information can be found on the QuarksLab blog at http://blog.quarkslab.com/qb-sync.html.
The Axion Qb-sync addon provides a graphical widget to use REVEN as a Qb-sync debugger backend, so you can have both a dynamic view (Axion) and a static view (IDA) synced. The following steps describe how to use the addon.
Get qb-sync
To use the addon, you have to download Qb-sync first. We recommend fetching our forked project (on github) as it is the tested version.
Load target binary in IDA
To synchronize an IDA instance with reven, you obviously need to load a binary present in the trace. To get this binary you can either extract it from the scenario archive (which can be found indide the analyse directory of a project) or directly dump the executable from memory using the memory python API.
Once the target binary is loaded into IDA, ensure it is mapped at the right address. If not then rebase it using the 'Edit' -> 'Segments' -> 'Rebase Program' menu. Reven memory mapping can be obtained with the binaries information python API.
Configure Qb-sync
By default, Qb-sync will work on a local configuration where IDA and Axion are on the same host (the IDA plugin will listen on 127.0.0.1). If it is your case you can skip this part.
To allow remote usage of Qb-sync, a configuration file must be placed on the IDA host. Qb-sync will load any .sync file it found in either the IDB or home directories. The .sync file follows the .ini syntax and allows setting the host and port the IDA plugin will listen on. eg:
Where the host option is the IDA machine address (which can be retreived by issuing an ipconfig command on windows or ifconfig on linux).
Load Qb-sync IDA plugin
You can then load the Qb-sync IDA plugin (SyncPlugin.py in the ext_ida directory) through the 'File' -> 'Script File' menu. This will create a Qb-Sync process listenning for debugger events.
Once loaded, the plugin will create a new tab in IDA and allow you to change the binary name. Qb-Sync enable the syncronization only when the right binary is being debugged so you must ensure a perfect matching between the IDA and REVEN binary names.
Note that the binary name information must therefore be available in REVEN; this means the trace must contain processes information provided by the scenario.
Connect Axion to IDA
Finally, you can start the Axion Qb-sync addon through the widget (in the 'miscellaneous' menu) and connect to the previsouly loaded IDA plugin (using the latter's ip address and port) to enable the synchronisation.
RvnKd addon
The RvnKd addon provides a python library allowing to create a full memory dump at a specific execution point which will be compatible with Microsoft KD/WindDbg debuggers.
A command line tool called gen_dump.py is provided to show case the library usage.
The run, sequence and instruction arguments are used to specify at which moment of the trace the dump will be generated, and needs to match to a kernel sequence. The reason is, in order to perform physical address translation and access kernel virtual memory, rvnkd needs to know a ring0 directory table base value. The gen_dump.py extracts it from the cr3 cpu context register while executing a kernel process.
The generated dump file size will be equal to the physical memory amount configured in the virtual machine used to generate the scenario.
The gen_dump.py script tries several methods to recover the needed kernel structures, some attempt may fail and produce errors. This is the normal behavior and the generated dump file will be completely valid anyway.
Wireshark launcher addon
pcap_launcher.py enables the user to inspect either network or usb traffic, based on the project's scenario hardware information.
This plugin adds two buttons in REVEN-Axion toolbar. Clicking on one of them will generate the relevant pcap-ng file on the server side, retrieve it back and launch wireshark on the client side.
The default command for starting wireshark is the following, but a small configuration tuning may be necessary for it to work with your actual setup (see source file for full customization):
Moreover, since the pcap-ng file is generated on the server, you may want to use sshfs to have access to your projects data as if they were on your local filesystem:
Wireshark to axion sync addon
You might also want to enable synchronization between the selected packet in Wireshark and the selected sequence and physical buffer in Axion. This requires two plugins, one on the Axion side and one on the Wireshark side, and the latter requires manual activation:
wireshark plugin
The wireshark plugin is installed but disabled by default.
Start by checking your plugin installation: verify you have a menu entry Tools > axion_sync. If not, install the debian package wireshark-axion_sync from your REVEN release repository. It will install axion_sync plugin for wireshark system wide.
Then enable it: in wireshark, go to Edit > Preferences > Statistics and check Enable axion_sync on packet selection. This setting will be kept across wireshark restarts.
Click on any frame to sync' axion.
axion_sync plugin
axion_sync plugin is enabled by default and you should have nothing to do on this side.
It will launch a server listenning on port 9000 for any selection request from wireshark's plugin.
On frame selection from wireshark, axion will:
- append to physical history widget all sub-buffers used by the network card for the selected frame (header and content are usually in separate buffers)
- select the instruction on which the network card access occured.
From the physical history widget you can track network buffer uses. Then, in the instruction view, on the accessing instruction operands you can easily invoke an hex dump window to see the logical buffer and use memory history to continue your track.
Please note that by default, we install axion_sync in what should be debian's wireshark default plugin directory (/usr/lib/x86_64-linux-gnu/wireshark/plugins/1.12.1/). If you happen to use another version of wireshark, you are free to copy the .so file into ~/.wireshark/plugins/. The plugin is not guaranteed to work on any other version, though.