Python API

Table of Contents

• Quickstart
• Examples
• REVEN Axion's python console
• Other Bindings
  • Managing Projects and Scenarios
  • Extending REVEN Axion through plugins
    • How to create a plugin
• Links

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.

import reven
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:

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
  for symbol in trace.search_symbol("MySymbol"): 
    # Will certainly not find any symbol
    print symbol
    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.

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.set_comment("A new comment")
print 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.

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

Note that connecting to a project may interact with the licensing system. Please refer to this page for more information about this interaction.

Examples

• Perform an incremental search
• Start a server execution
• Use the taint information (Slicer)
• Find runtime-generated instructions
• Build the CFG of a process

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:

  py> host, port = axion.connection_info()
  py> project = reven.Project(str(host), port)

• You can also invoke custom scripts from the console as follows:

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

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

Examples

• Low-level Launcher

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.

from axion_api import axion

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

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 use the hello world plugin as a template.

2. Load your plugin in REVEN Axion by using 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 from the name of the plugin file.

   If you need to reload the plugin, use:

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

3. Optionally, if your plugin performs an action triggered by a shortcut, define this shortcut (using the Action > Edit shortcut menu or F11 by default). You can then call your plugin by using the defined shorcut.

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

Examples

• Hello world plugin that you can use as a plugin template
• Dynamic annotation plugin demonstrating plugins triggered by a shortcut

Links

• Python API Reference
• List of all examples
• Low Level Python API - Services
• Low Level Python API - Objects
• Low Level Python API - Launcher Services
• Low-level API changelog

  ---

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