REVEN-Axion 2018v1.5.0
Axion plugins

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

IDA-Sync plugin

The IDA-sync Axion plugin enables the synchronization of IDA instances with the currently selected instruction of an Axion instance. It is basically a wrapper around Ret-Sync, which is a tool written by Alexandre Gazet.

Ret-Sync

Ret-Sync allows remote setup, that is having IDA on a different host than the backend debugger (REVEN). To allow this kind of configuration, the Ret-Sync IDA plugin handles debugger events through a network socket and dispatch it to the right IDA window. More information can be found our Github repository at https://github.com/tetrane/ret-sync.

ida-sync.png
Ret-Sync remote setup

The IDA-Sync Axion plugin provides a graphical widget to use REVEN as a Ret-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 those two plugins together.

Setup

Prerequisites

To use this plugin there are several prerequisites:

  • The binary mapping information must be available in Reven. If you manually record 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, if a firewall is activated, it must allow python to open a socket on the selected host and port.

Get Ret-Sync

To use the plugin, you have to download Ret-Sync first. We recommend fetching our forked project (on github) as it is the REVEN-supported version.

$ git clone https://github.com/tetrane/ret-sync

Configure Ret-Sync

By default, Ret-Sync will work on a local configuration where IDA and Axion are on the same host (Ret-Sync will listen on 127.0.0.1). If it is your case you can skip this part.

To allow remote usage of Ret-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 Ret-Sync will listen on. eg:

[INTERFACE]
host=192.168.1.16
port=9100

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 target binary in IDA

To synchronize an IDA instance with Axion, you obviously need to load a binary present in the trace. To get this binary you can extract it from the scenario archive (which can be found inside the analyse directory of a project).

Load Ret-Sync IDA plugin

We assume that you download Ret-Sync from our github forked project.

There are three IDA plugins in the Ret-Sync repository:

  • ext_ida/SyncPlugin-6.8-or-lower.py: must be used with IDA 6.8 or lower version.
  • ext_ida/SyncPlugin-6.9x.py: must be used with IDA 6.9.
  • ext_ida/SyncPlugin-7-or-higher.py: must be used with IDA 7 or higher version.

You can then load the Ret-Sync IDA plugin that match your IDA version through the File > Script File menu. This will create a Ret-Sync process listening for debugger events.

Once loaded, the plugin will create a new tab in IDA and allow you to change the binary name. IDA-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.

Connect Axion to IDA

Finally, you can start the Axion IDA-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.

Remark

If the base address of the studied binary is different between AXION and IDA (because of ASLR for example), the synchronisation will still work correctly but the displayed addresses will be different between AXION and IDA. To have the same addresses, the binary in IDA must be rebased to the right base address (using the Edit > Segments > Rebase Program menu) and the plugins in IDA and AXION must be restarded.

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.

This file is located in /usr/share/reven/reven_scripts/gen_dump.py on Linux, and in C:\Python27\lib\site-packages\reven\rvnkd\gen_dump.py on Windows.

$ python /usr/share/reven/reven_scripts/gen_dump.py --help
usage: gen_dump.py [-h] [--host host] [--port port] [-r run] [-s sequence]
[-i instruction]
output
Create a Windbg full kernel-dump file (a.k.a. MEMORY.DMP) of a reven instance.
positional arguments:
output the output file
optional arguments:
-h, --help show this help message and exit
--host host the reven host
--port port the reven server port
-r run the reven execution run name. Default: Execution run
-s sequence the reven execution sequence. Default: 0
-i instruction the reven execution instruction. Default: 0
$ python /usr/share/reven/reven_scripts/gen_dump.py --host 192.168.1.254 --port 13370 -s 34567 /tmp/MEMORY.dmp
Looking for windows kernel objects
----------------------------------
[*] KPCR: 8273cc00
[*] KdVersionBlock: 8273bbc0
[-] Error: page fault exception, while trying to access memory at 23:[82981fec]
[-] Error while getting KdDebuggerDataBlock from KdVersionBlock: page fault exception
Scanning physical memory (273B000))
[*] KdDebuggerDataBlock: 8273bbe8
Writing DMP header
------------------
Filling header 100%
[-] Invalid Windows PAE status: 0 (expect 1)
Loading physical address space
------------------------------
Number of run: 2
Number of pages: 130958
Run 1/2: Writing page 158/158 100%
Run 2/2: Writing page 130800/130800 100%
[+] Successfully created DMP file `/tmp/MEMORY.dmp`.

The generated dump file size will be equal to the physical memory amount configured in the virtual machine used to record 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

pcap_launchcmd = "(wget 'http://#h:80/reven_data/#u/#p/output/#c' -O '#g' && wireshark -r '#g' ; rm '#g')&"

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:

sshfs reven@your_reven_server_hostname:reven_data $HOME/reven_data

Then, the pcap command becomes simply:

pcap_launchcmd = "(wireshark -r $HOME/reven_data/#u/#p/output/#c)&"

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 package is installed from the debian repositories. If not so, restart axion after installing the package.