REVEN-Axion 2017v1.4.2
Python API

Reven can be extended by using Python® scripts. To do so, you can use the reven python API.

Python API Reference

Quickstart

The API is accessible as the reven module, from everywhere on the system through a standard Python CLI or REVEN Axion's python console.

1 import reven
2 import time # for time.sleep

The first step is to connect to an existing Reven instance, for example on port 13370 of the host localhost:

1 project = reven.Project('localhost', 13370)

You can then start an execution, if none has been done or loaded before:

1 project.start_execution([reven.InspectorMemoryHistory(), reven.InspectorStringHistory()])
2 while project.execution_status().is_busy:
3  time.sleep(1)

From there, you can communicate with the Reven instance through member functions of the Project class. For example, you can get information about every trace using traces():

1 for trace in project.traces():
2  print trace.name
3  print trace.sequence_count
4  for symbol in trace.search_symbol("MySymbol"):
5  # Will certainly not find any symbol
6  print symbol
7  print

Inside a Trace (which is the same as a run in REVEN Axion), the most interesting object is the Point: it represents a single execution point.

1 trace = project.trace("Execution run")
2 point = trace.point(0, 0) # Sequence 0, Instruction 0
3 print point
4 print point.symbol
5 print point.cpu()["eax"]
6 print point.memory().read(0x12345678, 4) # Will probably raise an exception
7 point.instruction.set_comment("A new comment")
8 print point.instruction.comment() # "A new comment"
9 point = point.next()
10 point = point.next_sequence()

As you can see, with these two objects you can query pretty much everything.

For more detailed information about the python API, please refer to the Python API Reference.

In your python interactive shell, you can also use the help built-in function to directly access the documentation while coding (see the official python documentation for more details on this function).

Examples

For examples of how to use the python API from IDA, see IDA support on windows.

REVEN Axion's python console

  • To open a REVEN Axion's python console, use the shortcut Alt+Shift+P.
  • The python API is loaded automatically as the reven module.
  • You can create a python Project instance with the following:
    1 py> host, port = axion.connection_info()
    2 py> project = reven.Project(str(host), port)
  • You can also invoke custom scripts from the console as follows:
1 py> axion.exec_script('<path_to_script/my_script.py')
  • The console provides autocompletion and a command history.

Other Bindings

While the python API provided by the reven module should offer most of the required functionality to use and extend REVEN, some features are not yet available through it.

Managing Projects and Scenarios

To create, start & stop projects, as well as to record scenarios, you can use the low-level python API, which is accessible trough the reven_api module. It exposes the project and scenario management features through its launcher_connection object (see Launcher services).

This API is subject to changes: you can check its changelog for per-version modifications.

NOTE: The functionality of the python API is actually provided by the low-level python API, so it would be possible to use the low-level instead of the former. However, this is discouraged. Prefer using the python API from the reven module.

NOTE: From REVEN Axion's python console, a low-level reven_connection instance is already created and accessible under the name rvn_client.

Documentation

Examples

Extending REVEN Axion through plugins

NOTE: See here for documentation about existing plugins.

To extend REVEN Axion through plugins, you can use the Axion API.

The Axion API is provided by the axion_api module.

It is accessible in the context of REVEN Axion only, either by loading a plugin or through the REVEN Axion's python console.

1 from axion_api import axion

From there you can, for example, get the selected instruction:

1 run, seq, instr = axion.selected_sequence()

How to create a plugin

A plugin can use the Axion API to interact with REVEN Axion.

To make and use a plugin through REVEN Axion, proceed as follows:

  1. Create a file called my_plugin.py in your autoload directory and define the axion_calling function.

    axion_calling plays the role of the main function for REVEN Axion.

  2. Load your plugin in REVEN Axion by using the REVEN Axion's python console as follows:

    1 py> axion.load_plugin('name', 'path_to_plugin/my_plugin.py')

    Remark: 'name' will be the name of the plugin in REVEN Axion and can be different from the name of the plugin file.

    If you need to reload the plugin, use:

    1 py> axion.plugins().reload_plugin('name')
  3. Define a shortcut (using the Action > Edit shortcut menu or F11 by default).
  4. Call your plugin by using the defined shorcut.

NOTE: The axion_calling function is mandatory, as it is the function that REVEN Axion will attempt to call when you use the shortcut defined for your plugin. If the function is not defined, nothing will happen.

NOTE: You can use the REVEN Axion's python console's autocompletion feature on the axion object to browse the Axion API.

Examples

Links

"Python" and the Python logos are trademarks or registered trademarks of the Python Software Foundation, used by Tetrane with permission from the Foundation.