Python API - Services

Table of Contents

• Analysis
  • analysis_get_binaries_information
  • analysis_get_binaries_names
  • analysis_get_binaries_reports
  • analysis_get_errors
  • analysis_get_framebuffer_information
• Devices
  • device_get_all
  • device_get_history
• Reven engine
  • engine_get_progress
  • engine_pause_execution
  • engine_plug_inspector
  • engine_resume_execution
  • engine_start_execution
  • engine_start_exploration
  • engine_start_local_exploration
• Graph handling
  • graph_get_binary
  • graph_get_symbol
• Hardware
  • hardware_analysing_dump_file
• Memory
  • memory_get_allocations
  • memory_get_buffer
  • memory_get_byte
  • memory_get_dword
  • memory_get_history_between
  • memory_get_history_instruction
  • memory_get_physical_address
  • memory_get_physical_buffer
  • memory_get_qword
  • memory_get_string
  • memory_get_word
  • memory_is_accessed_by
  • memory_search_buffer
• Process introspection
  • process_get_all
  • process_get_switch_list
• Run
  • run_get_all
  • run_get_call_stack
  • run_get_delta_context
  • run_get_instructions
  • run_get_instructions_range
  • run_get_running_context
  • run_get_running_context_between
  • run_get_sequence_children
  • run_get_sequence_count
  • run_get_sequence_range
  • run_search_next_memory_use
  • run_search_next_memory_use_physical
  • run_search_next_register_use
  • run_search_operand
  • run_search_sequences
  • run_search_symbols
  • run_search_tainted_instructions
• Sequence
  • sequence_get_all_static_annotations
  • sequence_get_instructions
  • sequence_get_memories
  • sequence_get_registers
  • sequence_list_all
  • sequence_set_dynamic_annotations
  • sequence_set_static_annotations
• Server
  • server_get_info
  • server_set_service_timeout
• String accesses
  • string_get_history
  • string_search_by_content
  • string_search_by_sequences
• Symbol management
  • symbol_add
  • symbol_load_for_pid
• Trace management
  • trace_delete
  • trace_get_all
  • trace_load
  • trace_save

In this page, we will show the various services available through the Python API.

Analysis

analysis_get_binaries_information

analysis_get_binaries_information() -> project_binaries_information

Get information regarding project.

Returns

project_binaries_information

analysis_get_binaries_names

analysis_get_binaries_names() -> list(string)

Get the binaries in core.

Returns

list(string)

analysis_get_binaries_reports

analysis_get_binaries_reports() -> list(binary_report)

Get all potential bugs found in the analyzed binaries.

Those bugs are found by different inspectors. For example, inspector allocations will find allocations issues under Linux.

Returns

list(binary_report)

analysis_get_errors

analysis_get_errors() -> list(error)

Get the errors raised during an analysis.

Returns

list(error)

analysis_get_framebuffer_information

analysis_get_framebuffer_information() -> framebuffer_information

Retrieve the framebuffer information.

With this information, you can retrieve a view of the framebuffer if it's valid.

Get the framebuffer contents

# This example will save the contents of the framebuffer to a raw image.

r = reven.reven_connection()

fbi = r.analysis_get_framebuffer_information()
if not fbi.address.paged:
    print 'Framebuffer not available.'
else:
    with open('file.raw', 'wb') as f:
        f.write(r.memory_read_buffer_physical(fbi.address, fbi.total_size))

Returns

framebuffer_information

Devices

device_get_all

device_get_all() -> list(device)

Retrieve the list of devices.

Returns

list(device)

device_get_history

device_get_history(device_name, subdevice_name) -> list(device_access)

Retrieve the history of a device or one of its subdevices.

See device_get_all for a list of devices and subdevices

Parameters

device_name	Device name to search, empty to match all devices. -> string
subdevice_name	Subdevice name to search, empty to match all subdevices -> string

Returns

list(device_access)

Reven engine

engine_get_progress

engine_get_progress() -> analysis_progress

Returns the state of the current analysis.

The returned object will allow to know if the execution is still in progress or not.

Returns

analysis_progress

engine_pause_execution

engine_pause_execution() -> None

Pauses the current execution.

This does nothing if the execution is already stopped or paused.

While a Reven instance is paused, you can launch any service like when the analysis is finished.

Warning: Pausing an execution is not instantaneous because all data is flushed to the hard drive.

engine_plug_inspector

engine_plug_inspector(inspector) -> None

Enables an inspector for the next analysis.

Parameters

inspector

Instance of inspector to enable for the next analysis (either execution or exploration). -> object

engine_resume_execution

engine_resume_execution() -> None

Resumes the current execution.

This will invalidate any saved state of the current execution, because of the shared data of the execution.

You can save again if you pause or once the execution stops.

engine_start_execution

engine_start_execution() -> None

Starts an execution with the configured inspectors.

Note: This service returns immediately, with the Reven analysis taking place. You can know the current status of the analysis with engine_get_progress

Warning: Most services assume that the execution is done and won't work during an analysis.

engine_start_exploration

engine_start_exploration() -> None

Starts an exploration with the configured inspectors.

engine_start_local_exploration

engine_start_local_exploration(when, address, depth) -> boolean

Launches a static exploration at the given logical address.

This means we create a static symbolic context at the given address, and try to see all reachable code from this location. If a solver implementation is activated in your Reven version, paths are validated before being added.

Parameters

when	When to take the memory as reference -> execution_point
address	The logical address where the exploration should start. It should correspond to the address of a sequence that belongs to a run. Otherwise, this service will do nothing. -> logical_address
depth	The maximum number of jumps to walk, starting from address -> integer

Returns

boolean

Graph handling

graph_get_binary

graph_get_binary() -> string

Get the graph of binaries.

The result is a dot graph that can be displayed with a graphviz capable library.

Returns

string

graph_get_symbol

graph_get_symbol(symbol) -> string

Get a graph of the specified symbol.

The result is a dot graph that can be displayed with a graphviz capable library.

This graph contains all the executed sequences reachable from the symbol entry point. Only translated sequences are shown. This includes executed sequences, and sequences discovered by calling the engine_start_local_exploration service.

Parameters

symbol

The symbol name. -> string

Returns

string

Hardware

hardware_analysing_dump_file

hardware_analysing_dump_file(device_name, subdevice_name) -> integer

Parameters

device_name	_ -> string
subdevice_name	_ -> string

Returns

integer

Memory

memory_get_allocations

memory_get_allocations(address) -> list(memory_access)

Get the buffers generated by inspector allocations or inspector windows_allocations for a specific logical address.

This service requires that inspector memory_range_history was plugged before an execution, and another inspector such as inspector allocations or windows_allocations (depending on the target OS).

Parameters

address

Logical address of the buffer to seek allocations -> logical_address

Returns

list(memory_access)

memory_get_buffer

memory_get_buffer(point, address, length) -> string

Read an arbitrary buffer from memory at the specified point in time.

Warning: This service will not execute page fault exceptions.

Parameters

point	Point in time when to read the buffer -> execution_point
address	Logical address of the first byte of the buffer -> logical_address
length	Size of the buffer to read, in bytes -> integer

Returns

string

memory_get_byte

memory_get_byte(point, address) -> integer

Read a byte from memory at the specified point in time.

Warning: This service will not execute page fault exceptions.

Parameters

point	Point in time when to read the byte -> execution_point
address	Logical address of the byte -> logical_address

Returns

integer

memory_get_dword

memory_get_dword(point, address) -> integer

Read a dword (4 bytes) from memory at the specified point in time.

Warning: This service will not execute page fault exceptions.

Parameters

point	Point in time when to read the dword -> execution_point
address	Logical address of the dword -> logical_address

Returns

integer

memory_get_history_between

memory_get_history_between(run_name, start, end) -> list(memory_access)

Request the RAM history for a range of physical addresses

This service requires that inspector memory_range_history was plugged before an execution.

It will return all the memory accesses for the requested memories (in physical form).

Since we require physical address, logical addresses cannot be used here. See the memory_get_physical_address service if needed.

Parameters

run_name	Name to search -> string
start	First memory to search -> physical_address
end	Last memory to search (excluded) -> physical_address

Returns

list(memory_access)

memory_get_history_instruction

memory_get_history_instruction(point) -> list(memory_access)

Request the memory accesses for a specified execution point

This service requires that inspector memory_range_history was plugged before an execution.

It will return all the memory accesses that occurred of a specific instruction.

Parameters

point

Execution point when to search the memory accesses -> execution_point

Returns

list(memory_access)

memory_get_physical_address

memory_get_physical_address(point, address) -> physical_address

Get the physical address of a logical one at a specific timestamp.

Warning: This service will not execute page fault exceptions. If the specified address is not mapped, it will return an unmapped physical address.

Parameters

point	Execution point when to translate -> execution_point
address	Address to translate -> logical_address

Returns

physical_address

memory_get_physical_buffer

memory_get_physical_buffer(point, address, length) -> string

Read an arbitrary buffer from physical memory at the specified point in time.

Parameters

point	Point in time when to read the buffer -> execution_point
address	Logical address of the first byte of the buffer -> physical_address
length	Size of the buffer to read, in bytes -> integer

Returns

string

memory_get_qword

memory_get_qword(point, address) -> integer

Read a qword (8 bytes) from memory at the specified point in time.

Warning: This service will not execute page fault exceptions.

Parameters

point	Point in time when to read the qword -> execution_point
address	Logical address of the qword -> logical_address

Returns

integer

memory_get_string

memory_get_string(point, address) -> string

Read a null terminated string from memory at the specified point in time.

Note: If some part of the string cannot be read (pagefault, etc), the string will be stopped.

Parameters

point	Point in time when to read the string -> execution_point
address	Logical address of the first byte of the string -> logical_address

Returns

string

memory_get_word

memory_get_word(point, address) -> integer

Read a word (2 bytes) from memory at the specified point in time.

Warning: This service will not execute page fault exceptions.

Parameters

point	Point in time when to read the word -> execution_point
address	Logical address of the first byte of the word -> logical_address

Returns

integer

memory_is_accessed_by

memory_is_accessed_by(point, memories) -> boolean

Returns true if one of the memories is accessed at a specific instruction.

Parameters

point	Point in time to check memory accesses -> execution_point
memories	Logical address to check -> list(physical_address)

Returns

boolean

memory_search_buffer

memory_search_buffer(point, first_address, last_address, pattern) -> list(logical_address)

Search in an arbitrary buffer from a memory segment at the specified point in time.

Parameters

point	Point in time where to search data -> execution_point
first_address	First address to search (included) -> logical_address
last_address	Last address to search (included) -> logical_address
pattern	Raw string of the pattern to search. See binascii.unhexify if you need binary data. -> string

Returns

list(logical_address)

Process introspection

process_get_all

process_get_all() -> list(process)

Retrieve the processes at the beginning of the scenario.

Returns

list(process)

process_get_switch_list

process_get_switch_list() -> list(process_switch)

Retrieve the list of all process switches.

Currently, process switches are only checked when fs or gs is modified.

Returns

list(process_switch)

Run

run_get_all

run_get_all() -> list(string)

Get the name of executed runs.

Returns

list(string)

run_get_call_stack

run_get_call_stack(point) -> list(sequence_in_run)

Get the call stack of a specific sequence for a run.

Parameters

point

When to get the call stack -> execution_point

Returns

list(sequence_in_run)

run_get_delta_context

run_get_delta_context(range) -> symbolic_context

Get delta context between two sequences.

Note: This service currently only works by sequences. You cannot request an instruction-based delta.

Parameters

range

Range of sequences for which to compute the delta -> execution_range

Returns

symbolic_context

run_get_instructions

run_get_instructions(run_name, sequences) -> list(sequence_instructions)

Get a range of instructions for one run, for several sequence identifiers.

Parameters

run_name	Run to get instructions for -> string
sequences	Sequences to retrieve instructions for -> list(integer)

Returns

list(sequence_instructions)

run_get_instructions_range

run_get_instructions_range(range) -> list(sequence_instructions)

Get a range of instructions for one run, starting at a specific sequence timestamp.

Parameters

range

Range of instructions to get (in sequences). -> execution_range

Returns

list(sequence_instructions)

run_get_running_context

run_get_running_context(execution_point, memory_ranges) -> running_context

Compute the running context at a point in time.Since the memory is potentially huge, the memory is not fully returned. You can request as many memory_ranges as required, though.

Warning: Each range must be page-aligned.

See also

run_get_running_context_between if you need values before and after a point

Parameters

execution_point	Starting and stopping point of the context. -> execution_point
memory_ranges	Memory ranges to fetch. Each range must be page aligned. -> list(logical_address_range)

Returns

running_context

run_get_running_context_between

run_get_running_context_between(execution_range, memory_ranges) -> running_context_range

Compute the running context between two points in time.

Since the memory is potentially huge, the memory is not fully returned. You can request as many memory_ranges as required, though.

Warning: Each range must be page-aligned.

Parameters

execution_range	Starting and stopping point of the context. -> execution_range
memory_ranges	Memory ranges to fetch. Each range must be page aligned. -> list(logical_address_range)

Returns

running_context_range

run_get_sequence_children

run_get_sequence_children(run_name, indexes, max_full_sequences, start_filter, around_sequences) -> dict(integer -> list(sequence_in_run))

Get the children sequences of a some sequences in a run.

Sequences are assumed to be children of each other, such as the result of run_get_call_stack service.

Parameters

run_name	Name of the run we want sequences for -> string
indexes	A list of indexes to retrieve -> list(integer)
max_full_sequences	Maximum number of children before filtering -> integer
start_filter	Number of sequences to show at the start and end of the sequence -> integer
around_sequences	Number of sequences to show around the stack element -> integer

Returns

dict(integer -> list(sequence_in_run))

run_get_sequence_count

run_get_sequence_count(run_name) -> integer

Get the number of sequences inside a run.

Parameters

run_name

Name of the run -> string

Returns

integer

run_get_sequence_range

run_get_sequence_range(range) -> list(sequence_in_run)

Retrieve the sequences of a run for a specific a range.

Parameters

range

Range of sequences to retrieve -> execution_range

Returns

list(sequence_in_run)

run_search_next_memory_use

run_search_next_memory_use(execution_point, forward, read, write, address) -> execution_point

Finds the next use of the specified logical memory, before or after the specified point.

Parameters

execution_point	Where to start the search -> execution_point
forward	True to search forward in time -> boolean
read	True to search read memories -> boolean
write	True to search written memories -> boolean
address	Address to search -> logical_address

Returns

execution_point

run_search_next_memory_use_physical

run_search_next_memory_use_physical(execution_point, forward, read, write, address) -> execution_point

Finds the next use of the specified physical memory, before or after the specified point.

Parameters

execution_point	Where to start the search -> execution_point
forward	True to search forward in time -> boolean
read	True to search read memories -> boolean
write	True to search written memories -> boolean
address	Address to search -> physical_address

Returns

execution_point

run_search_next_register_use

run_search_next_register_use(execution_point, forward, read, write, register_name, stop=execution_point()) -> execution_point

Finds the next use of the specified register, before or after the specified point.

This service returns either when a result is found or stop if no result is found.

Parameters

execution_point	Where to start the search -> execution_point
forward	True to search forward in time -> boolean
read	True to search read registers -> boolean
write	True to search written registers -> boolean
register_name	Register name to search -> string
stop	Stop searching when this point is reached -> execution_point

Returns

execution_point

run_search_operand

run_search_operand(execution_point, operand_index) -> symbolic

Finds the next use of the specified symbolics, between the specified point (included)

Parameters

execution_point	The point where to search the operand -> execution_point
operand_index	Number of operand to search (0, 1 or 2 on x86) -> integer

Returns

symbolic

run_search_sequences

run_search_sequences(range, search) -> search_result

Search sequences matching the specified set of criteria.

Example: Simple search by address

r = reven.reven_connection()

range = reven.execution_range(0, 20000)
search = reven.search_request(reven.filter_criterion_address(0x400000))
result = r.run_search_sequences(range, search)
for sequence in result.nodes: print sequence

Example: Search sequences contained in binary test or binary kernel

range = reven.execution_range(0, 20000)
search = reven.search_request([
    reven.filter_criterion_binary("test"),
    reven.filter_criterion_binary("kernel")],
  False)
print r.run_search_sequences(range, search)

Example: Find the first result incrementally search

range = reven.execution_range(0, 1000000)
search = reven.search_request(reven.filter_criterion_address(0x400000))

# Stop after one result only
search.max_results = 1

# The service returns each time we process 10000 sequences (to print a progress bar)
search.max_sequences = 10000

Parameters

range	Range of sequences where to restrict the search. This range can be (0, 0xfffffffffffffffff) to search all the run -> execution_range
search	Search request object with the specified criteria -> search_request

Returns

search_result

run_search_symbols

run_search_symbols(run_name, filter_on_name, filter_is_regexp, called_only, fetch_from_index, fetch_max) -> symbol_in_run_container

Searches for symbols in a specified run, according to the specified criteria.

Parameters

run_name	Run name to search -> string
filter_on_name	Name of the symbols to search -> string
filter_is_regexp	If true, filter_on_name is a regular expression -> boolean
called_only	If true, only returned symbols that were called during the execution -> boolean
fetch_from_index	Return some symbols starting from the specified index (progressive loading) -> integer
fetch_max	Maximum number of symbols to return (progressive loading) -> integer

Returns

symbol_in_run_container

run_search_tainted_instructions

run_search_tainted_instructions(start, stop, count, initial_taint, taint_deref) -> dict(execution_point -> instruction_taint_diff)

Finds the next instructions altering a taint between the specified point (excluded)

Parameters

start	Start point of the taint -> execution_point
stop	Stop point of the tainter. If stop < start, the taint is backwards -> execution_point
count	Maximum number of instructions to taint -> integer
initial_taint	Taint at the start point -> list(symbolic)
taint_deref	True if dereferencings need to be tainted. -> boolean

Returns

dict(execution_point -> instruction_taint_diff)

Sequence

sequence_get_all_static_annotations

sequence_get_all_static_annotations() -> list(mini_sequence)

Finds all the static sequences containing an annotation.

Returns

list(mini_sequence)

sequence_get_instructions

sequence_get_instructions(address) -> list(instruction)

Get the instructions belonging to a sequence (static).

Parameters

address

Start address of the sequence to search -> logical_address

Returns

list(instruction)

sequence_get_memories

sequence_get_memories(address) -> list(symbolic)

Get the memories belonging to a sequence (static).

Parameters

address

Start address of the sequence to search -> logical_address

Returns

list(symbolic)

sequence_get_registers

sequence_get_registers(address) -> list(symbolic)

Get the CPU registers belonging to a sequence (static).

Parameters

address

Start address of the sequence to search -> logical_address

Returns

list(symbolic)

sequence_list_all

sequence_list_all() -> list(mini_sequence)

List all the static sequences.

Returns

list(mini_sequence)

sequence_set_dynamic_annotations

sequence_set_dynamic_annotations(run_name, sequence) -> None

Modify the annotations for a dynamic sequence (sequence_in_run).

Parameters

run_name	Run to update -> string
sequence	The sequence in run to update (annotations are inside this object) -> sequence_in_run

sequence_set_static_annotations

sequence_set_static_annotations(sequence) -> None

Modify the annotations for a static sequence.

Parameters

sequence

The sequence to update (annotations are inside this object) -> list(mini_sequence)

Server

server_get_info

server_get_info() -> list(string)

Retrieve information on current server instance.

Returns

tuple: username, project.

list(string)

server_set_service_timeout

server_set_service_timeout(timeout) -> integer

Defines the timeout for all services.

Returns

the old timeout.

Note: If you only want to get the timeout without setting it, you can use set_service_timeout(0)

Parameters

timeout

timeout. Not changed if 0. If the timeout is negative, there is no timeout. -> integer

Returns

integer

String accesses

string_get_history

string_get_history(id) -> dereferenced_string_access

Request a list of accesses for a string

The identifier is found in the dereferenced_string object, under the unique_id field.

Parameters

id	String identifier -> integer

Returns

dereferenced_string_access

string_search_by_content

string_search_by_content(run_name, query, query_is_regexp, fetch_start, fetch_max) -> dereferenced_string_container

Request the dereferenced strings for a whole run

Parameters

run_name	Run name to search -> string
query	Text to be searched inside the strings -> string
query_is_regexp	If true, the query field is a regular expression -> boolean
fetch_start	First string to search (progressive loading) -> integer
fetch_max	Maximum number of strings to return -> integer

Returns

dereferenced_string_container

string_search_by_sequences

string_search_by_sequences(range, fetch_start, fetch_max) -> dereferenced_string_container

Request the dereferenced strings

Parameters

range	Range of sequences to search -> execution_range
fetch_start	First string to search (progressive loading) -> integer
fetch_max	Maximum number of strings to return -> integer

Returns

dereferenced_string_container

Symbol management

symbol_add

symbol_add(symbol_list) -> None

Add some symbols to sequences

Parameters

symbol_list

A list of symbols to add. -> list(symbol)

symbol_load_for_pid

symbol_load_for_pid(pid) -> boolean

Load the symbols for a specific PID.

Parameters

pid	PID (OS specific) of the process for which to load symbols. -> integer

Returns

boolean

Trace management

trace_delete

trace_delete(name) -> None

Delete a previously saved trace.

Parameters

name	Name of the trace file to delete -> string

trace_get_all

trace_get_all() -> list(state_info)

Retrieve the list of saved traces.

Returns

list(state_info)

trace_load

trace_load(name) -> boolean

Load the trace of a Reven instance.

Warning: This discards any unsaved data of the current Reven instance. You can save the trace before loading another one if you don't want to lose your changes.

Parameters

name	Name of the trace file to load. -> string

Returns

boolean

trace_save

trace_save(name) -> boolean

Save the trace of the Reven instance.

Parameters

name	Name of the trace file -> string

Returns

boolean