Python bindings

Table of Contents

• The APIs
  • The plugin API
  • Low level API Reference
  • 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 plugin 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 plugin API resides in the reven_api python library. You should use it only for features yet unsupported by the plugin 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 plugin 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:

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

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

client.start_execution([reven.InspectorMemoryHistory(), reven.InspectorStringHistory(),
                        reven.InspectorSemantics()])
while client.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 client.traces():
  print trace.name
  print trace.sequence_count
  t.search_symbol("MySymbol")

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.

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

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

The complete API reference is available here, and is discoverable through the python prompt help.

Low level API Reference

The low-level 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.

If you want to learn more about the low level python api, the following reference pages will help you:

• Python API - Services
• Python API - Objects
• 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.