Python binding
Axion can easily be extended in python thanks to the python API. Plugins can be loaded at startup with a startup script (see user settings).
Axion ships with a few plugins and external scripts, that are loaded by the default startup script, and that are detailed below.
Percent plugin
The percent plugin adds 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. Conversely, if the current instruction is reading some value on the stack, percent will jump to the previous instruction writting the memory. In practice, this is very useful to follow push/pop operands or call/ret boundaries.
The plugin is named percent as it has been designed to work like the vim editor percent keybinding on curly brackets.
The default key binding for this plugin is %. If you wish to modify this binding, use the shortcut configuration panel.
Gdbserver plugin
The Gdbserver plugin provides compatibility with the common gdb serial protocol api and might be useful to users who need to use their favorite gdb compatible debugger as a REVEN frontend. You can start the listening server via a graphical widget accessible through the Windows > Miscellaneous menu.
To simply test the plugin, start the service through the widget, and then connect to it with gdb command line.
Qb-sync plugin
Qb-Sync is a Quarkslab's tool which enables synchronisation between an IDA instance and a remote debugger.
To use this plugin there are several prerequisites:
- The binary mapping information 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 plugin.
- You must ensure network connectivity between Axion and IDA hosts. In particular, your firewall must allow python to open a socket on the selected host and port.
- The plugin only works until IDA 6.8 and is not compatible with IDA 6.9 and onwards.
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 plugin 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 plugin.
Get qb-sync
To use the plugin, you have to download Qb-sync first. We recommend fetching our forked project (on github) as it is the REVEN-supported 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, you must rebase it to 0 using the Edit > Segments > Rebase Program menu.
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. The configuration file should be named exactly .sync and can be located either in the IDB or in the 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 host machine address (which can be retrieved 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 enables the synchronization only when the correct binary is being debugged so you must ensure that the IDA and REVEN binary names are perfectly matching.
Note that binary name information must therefore be available in REVEN; this means that the trace must contain the process information provided by the scenario.
Connect Axion to IDA
Finally, you can start the Axion Qb-sync plugin through the widget (from Windows > Miscellaneous in Axion) and connect to the previously loaded IDA plugin (using the machine address and port of the IDA host) to enable the synchronisation.
RvnKd plugin
The RvnKd plugin 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 showcase 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 plugin
The wireshark launcher plugin enables the user to inspect either network or usb traffic, based on the project's scenario hardware information. It is located in the pcap_launcher.py file in the axion plugins directory.
This plugin adds two buttons in REVEN-Axion toolbar, network and usb. 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 used by the script for starting wireshark is given below. You may have to configure this command in the source file (pcap_launcher.py) to adapt it to your actual setup (configuration options are detailed in the source file).
Default command using http
To use this command, ensure that the directory /home/reven/reven_data/ is served over http on port 80 by the machine hosting REVEN.
Alternative using sshfs
sshfs allows to access the pcap-ng file as if they were on your local filesystem, despite it being generated server-side. Use the following command from the client to configure sshfs:
Then, the pcap command becomes simply:
Wireshark to axion sync plugin
The wireshark to axion sync plugin enables synchronization between the selected packet in Wireshark and the selected sequence and physical buffer in Axion. To function properly, it must be installed on both axion and wireshark, and manually enabled in wireshark.
wireshark side
In wireshark, verify that you have a menu entry Tools > axion_sync. If not, install the wireshark-axion_sync debian package from your REVEN release repository. It will install axion_sync plugin for wireshark system wide.
Then enable the plugin: 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 side
In axion, the plugin should be enabled by default.
It launches a server listening 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.
Troubleshooting
- 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. - If nothing happens while selecting packets in wireshark, check that the
python-webpy packageis installed from the debian repositories. If not so, restart axion after installing the package.