Python bindings

Table of Contents

• The APIs
  • The python API
  • The low-level python API
  • The Axion API
• REVEN Axion's python console
• How to create a plugin

Reven can be extended by using python scripts or plugins. Both are similar except that a plugin can also interact with REVEN Axion's display and can be called with a shortcut from REVEN Axion.

The APIs

There are three distinct APIs:

• The python API resides in the reven python library. It is used to manipulate the execution data, and can be called from both plugins and scripts.
• The low-level python API resides in the reven_api python library. You should use it only for features yet unsupported by the python API: it currently is the only way to create, start & stop projects, and create scenarios, all through the launcher_connection object.
• Finally, the Axion API resides in the axion_api library. This API is used to interact with Reven Axion's GUI, and exists only from the context of a plugin.

See below for snippets or the Examples page (accessible through the header of this page) for starting points.

The python API

This library is accessible from everywhere on the system through a standard Python CLI or the REVEN Axion's python console.

import reven

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

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

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

project.start_execution([reven.InspectorMemoryHistory(), reven.InspectorStringHistory()])
while project.execution_status().is_busy:
    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():

for trace in project.traces():
  print trace.name
  print trace.sequence_count
  trace.search_symbol("MySymbol") # Will certainly not found any symbol

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

trace = project.trace("Execution run")
point = trace.point(0, 0) # Sequence 0, Instruction 0
print point
print point.symbol
print point.cpu()["eax"]
print point.memory().read(0x12345678, 4) # Will probably raise an exception
point.instruction.comment = "A new comment"
point = point.next()
point = point.next_sequence()

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

Documentation

• Doxygen
• Through the python prompt help.

The low-level python API

The low-level python API is, for now, the only way to create, start & stop projects, and create scenarios, all through the launcher_connection object. See the Examples page on how to do that, along with helper functions you can use.

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

Documentation

• Low Level Python API - Services
• Low Level Python API - Objects
• Low Level Python API - Launcher Services

The Axion API

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

from axion_api import axion

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

run, seq, instr = axion.selected_sequence()

REVEN Axion's python console

• To open a REVEN Axion's python console, use the shortcut Alt+Shift+P.
• The libraries reven and axion_api are loaded automatically.
• A reven_connection instance is already created and is accessible under the name rvn_client.
• You can also invoke custom scripts from the console as follows:

py> axion.exec_script('<path_to_plugin/my_plugin.py')

How to create a plugin

A plugin can use the axion_api library to interact with the REVEN Axion's display.

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

1. Create a file 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 through the REVEN Axion's python console as follows:

   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 of name of the plugin file.

   To reload the plugin, use:

   py> axion.plugins().reload_plugin('name')

3. Define a shortcut (using menu Action Edit shortcut or F11 by default).
4. Call your plugin by using the shorcut.

The axion_calling function is important because when you use the shortcut define for your plugin, REVEN Axion will try to call this function. If it is not define, nothing will happen.