Low Level Python API - Services

Table of Contents

• Analysis
  • analysis_get_binaries_information
  • analysis_get_binaries_names
  • analysis_get_bug_report
  • analysis_get_framebuffer_information
  • analysis_get_logs
• Binary
  • binary_add_symbols
• Devices
  • device_get_all
  • device_get_history
• Disconnection
  • disconnect
• Reven engine
  • engine_get_current_preset
  • engine_get_preset_of_saved_trace
  • 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_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_physical_buffer_from_last_execution_point
  • memory_get_qword
  • memory_get_string
  • memory_get_word
  • memory_get_wstring_as_string
  • memory_search_buffer
• Process introspection
  • process_get_all
  • process_get_switch_list
  • process_map_memory_segment
• Run
  • run_get_all
  • run_get_call_stack
  • run_get_delta_context
  • run_get_execution_point_by_tsc
  • 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_list_all
  • sequence_set_dynamic_annotations
  • sequence_set_static_annotations
  • sequence_test_and_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
• 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.

Get binaries mapping information

# This example displays all binaries present in the trace and their memory mappings.

import sys, reven_api
r = reven_api.reven_connection('localhost', 13370)
bi = r.analysis_get_binaries_information()
for li in bi.libraries_information:
    sys.stdout.write('%s:\n' % li.name)
    for m in li.mapping:
        for asp in m.data():
            sys.stdout.write(' [%s, %s]' % (hex(asp.start), hex(asp.end)))
    sys.stdout.write('\n\n')

Exceptions

ServiceNotAllowedDuringExecutionError	If this service is called during the execution.
RuntimeError	If the connection is lost, in case of bad input, or in case of internal service error.

Returns

project_binaries_information

analysis_get_binaries_names

analysis_get_binaries_names() -> list(string)

Get the binaries in core.

Exceptions

ServiceNotAllowedDuringExecutionError	If this service is called during the execution.
RuntimeError	If the connection is lost, in case of bad input, or in case of internal service error.

Returns

list(string)

analysis_get_bug_report

analysis_get_bug_report() -> bug_report

Get all potential bugs found in the analyzed binaries.

Those bugs are found by different inspectors.

Exceptions

ServiceNotAllowedDuringExecutionError	If this service is called during the execution.
RuntimeError	If the connection is lost, in case of bad input, or in case of internal service error.

Returns

bug_report

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 saves the contents of the framebuffer to a raw image.

r = reven_api.reven_connection('localhost', 13370)
fbi = r.analysis_get_framebuffer_information()
if not fbi.address.paged:
    print 'Framebuffer not available.'
else:
    exec_point = reven_api.execution_point('Execution run', 0, 0)
    with open('file.raw', 'wb') as f:
        f.write(r.memory_get_physical_buffer(exec_point, fbi.address, fbi.total_size))

This service can be called during the execution.

Exceptions

RuntimeError

If the connection is lost, in case of bad input, or in case of internal service error.

Returns

framebuffer_information

analysis_get_logs

analysis_get_logs() -> list(log)

Get the logs raised during an analysis.

Exceptions

ServiceNotAllowedDuringExecutionError	If this service is called during the execution.
RuntimeError	If the connection is lost, in case of bad input, or in case of internal service error.

Returns

list(log)

Binary

binary_add_symbols

binary_add_symbols(binary, symbols) -> None

Add symbols to a binary.

Exceptions

ServiceNotAllowedDuringExecutionError	If this service is called during the execution.
RuntimeError	If the connection is lost, in case of bad input, or in case of internal service error.

Parameters

binary	The binary where to add the symbols. -> string
symbols	The symbols to add. -> list(mini_symbol)

Devices

device_get_all

device_get_all() -> list(device)

Retrieve the list of devices. This service can be called during the execution.

Exceptions

RuntimeError

If the connection is lost, in case of bad input, or in case of internal service error.

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

Exceptions

ServiceNotAllowedDuringExecutionError	If this service is called during the execution.
RuntimeError	If the connection is lost, in case of bad input, or in case of internal service error.

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)

Disconnection

disconnect

disconnect() -> None

Immediately close the connection.

Use this method to avoid locking a license token by keeping connections longer than necessary.

Note

Closing the last connection to a REVEN server releases its license token.

Reven engine

engine_get_current_preset

engine_get_current_preset() -> list(inspector_specifications)

List current configuration of inspectors.

Returns a list of inspector specifications.

The list contains all available inspectors, plugged or not.

This service can be called during the execution.

Exceptions

RuntimeError

If the connection is lost, in case of bad input, or in case of internal service error.

Returns

list(inspector_specifications)

engine_get_preset_of_saved_trace

engine_get_preset_of_saved_trace(state_name) -> list(inspector_specifications)

List configuration of inspectors in a saved execution trace state.

Returns a list of inspector specifications.

The list contains all available inspectors, plugged or not

This service can be called during the execution.

Exceptions

RuntimeError

If the connection is lost, in case of bad input, or in case of internal service error.

Parameters

state_name

Name of the saved trace to query preset from. -> string

Returns

list(inspector_specifications)

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.

This service can be called during the execution.

Exceptions

RuntimeError

If the connection is lost, in case of bad input, or in case of internal service error.

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.

This service can be called during the execution.

Exceptions

RuntimeError

If the connection is lost, in case of bad input, or in case of internal service error.

engine_plug_inspector

engine_plug_inspector(inspector) -> None

Enables an inspector for the next analysis.

Exceptions

ServiceNotAllowedDuringExecutionError	If this service is called during the execution.
RuntimeError	If the connection is lost, in case of bad input, or in case of internal service error.

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.

Exceptions

ServiceNotAllowedDuringExecutionError	If this service is called during the execution.
RuntimeError	If the connection is lost, in case of bad input, or in case of internal service error.

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 are unavailable during an execution. Please refer to the documentation of eachservice to determine if it can be called during an execution.

Exceptions

ServiceNotAllowedDuringExecutionError	If this service is called during the execution.
RuntimeError	If the connection is lost, in case of bad input, or in case of internal service error.

engine_start_exploration

engine_start_exploration() -> None

Starts an exploration with the configured inspectors.

Exceptions

ServiceNotAllowedDuringExecutionError	If this service is called during the execution.
RuntimeError	If the connection is lost, in case of bad input, or in case of internal service error.

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.

Exceptions

ServiceNotAllowedDuringExecutionError	If this service is called during the execution.
RuntimeError	If the connection is lost, in case of bad input, or in case of internal service error.

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.

Exceptions

ServiceNotAllowedDuringExecutionError	If this service is called during the execution.
RuntimeError	If the connection is lost, in case of bad input, or in case of internal service error.

Returns

string

graph_get_symbol

graph_get_symbol(sequence_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.

Exceptions

ServiceNotAllowedDuringExecutionError	If this service is called during the execution.
RuntimeError	If the connection is lost, in case of bad input, or in case of internal service error.

Parameters

sequence_symbol

A mini_sequence of the current symbol. -> mini_sequence

Returns

string

Hardware

hardware_analysing_dump_file

hardware_analysing_dump_file(device_name, subdevice_name) -> integer

Request the generation of a pcap file by dissecting device accesses.

The resulting file will be located server side, in the /output directory of the current project. Only devices with a dissection profile can be used with this service.

The returned value is the number of packets in the generated pcap file.

Exceptions

ServiceNotAllowedDuringExecutionError	If this service is called during the execution.
RuntimeError	If the connection is lost, in case of bad input, or in case of internal service error.

Parameters

device_name	name of the device. Must be 'e1000' or 'usb-ohci'. -> string
subdevice_name	_ -> string

Returns

integer

Memory

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.

Exceptions

ServiceNotAllowedDuringExecutionError	If this service is called during the execution.
RuntimeError	If the connection is lost, in case of bad input, or in case of internal service error.

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.

Exceptions

ServiceNotAllowedDuringExecutionError	If this service is called during the execution.
RuntimeError	If the connection is lost, in case of bad input, or in case of internal service error.

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.

Exceptions

ServiceNotAllowedDuringExecutionError	If this service is called during the execution.
RuntimeError	If the connection is lost, in case of bad input, or in case of internal service error.

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

Exceptions

ServiceNotAllowedDuringExecutionError	If this service is called during the execution.
RuntimeError	If the connection is lost, in case of bad input, or in case of internal service error.

Parameters

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.

Exceptions

ServiceNotAllowedDuringExecutionError	If this service is called during the execution.
RuntimeError	If the connection is lost, in case of bad input, or in case of internal service error.

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.

Exceptions

ServiceNotAllowedDuringExecutionError	If this service is called during the execution.
RuntimeError	If the connection is lost, in case of bad input, or in case of internal service error.

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.

Exceptions

ServiceNotAllowedDuringExecutionError	If this service is called during the execution.
RuntimeError	If the connection is lost, in case of bad input, or in case of internal service error.

Parameters

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

Returns

string

memory_get_physical_buffer_from_last_execution_point

memory_get_physical_buffer_from_last_execution_point(address, length) -> string

Read an arbitrary buffer from physical memory at the last executed execution point in the main run.

Note

Outside of an execution, read the buffer from the final context of the run.

This service can be called during the execution.

Exceptions

RuntimeError

If the connection is lost, in case of bad input, or in case of internal service error.

Parameters

address	Physical 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.

Exceptions

ServiceNotAllowedDuringExecutionError	If this service is called during the execution.
RuntimeError	If the connection is lost, in case of bad input, or in case of internal service error.

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.

Exceptions

ServiceNotAllowedDuringExecutionError	If this service is called during the execution.
RuntimeError	If the connection is lost, in case of bad input, or in case of internal service error.

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.

Exceptions

ServiceNotAllowedDuringExecutionError	If this service is called during the execution.
RuntimeError	If the connection is lost, in case of bad input, or in case of internal service error.

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_get_wstring_as_string

memory_get_wstring_as_string(point, address) -> string

Read a null terminated wstring from memory at the specified point in time. Assuming wchar are 2 bytes long.

Returned value is converted to a string (is not a wstring).

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

Exceptions

ServiceNotAllowedDuringExecutionError	If this service is called during the execution.
RuntimeError	If the connection is lost, in case of bad input, or in case of internal service error.

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

Exceptions

ServiceNotAllowedDuringExecutionError	If this service is called during the execution.
RuntimeError	If the connection is lost, in case of bad input, or in case of internal service error.

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.

Exceptions

ServiceNotAllowedDuringExecutionError	If this service is called during the execution.
RuntimeError	If the connection is lost, in case of bad input, or in case of internal service error.

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.

Exceptions

ServiceNotAllowedDuringExecutionError	If this service is called during the execution.
RuntimeError	If the connection is lost, in case of bad input, or in case of internal service error.

Returns

list(process_switch)

process_map_memory_segment

process_map_memory_segment(cr3, memory_segment) -> None

Map in a process a memory segment.

Exceptions

ServiceNotAllowedDuringExecutionError	If this service is called during the execution.
RuntimeError	If the connection is lost, in case of bad input, or in case of internal service error.

Parameters

cr3	The cr3 of the process where the memory segment will be mapped. -> integer
memory_segment	The memory segment to map. -> memory_segment

Run

run_get_all

run_get_all() -> list(string)

Get the name of executed runs.

Exceptions

ServiceNotAllowedDuringExecutionError	If this service is called during the execution.
RuntimeError	If the connection is lost, in case of bad input, or in case of internal service error.

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.

Exceptions

ServiceNotAllowedDuringExecutionError	If this service is called during the execution.
RuntimeError	If the connection is lost, in case of bad input, or in case of internal service error.

Parameters

point

When to get the call stack -> execution_point

Returns

list(sequence_in_run)

run_get_delta_context

run_get_delta_context(point) -> symbolic_context

Get delta context of an instruction.

Exceptions

ServiceNotAllowedDuringExecutionError	If this service is called during the execution.
RuntimeError	If the connection is lost, in case of bad input, or in case of internal service error.

Parameters

point

execution point where to get the delta context -> execution_point

Returns

symbolic_context

run_get_execution_point_by_tsc

run_get_execution_point_by_tsc(tsc) -> execution_point

Return the first execution point with tsc greater than or equal to the given tsc.

Exceptions

ServiceNotAllowedDuringExecutionError	If this service is called during the execution.
RuntimeError	If the connection is lost, in case of bad input, or in case of internal service error.

Parameters

tsc	Timestamp counter to search -> integer

Returns

execution_point

run_get_instructions

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

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

Exceptions

ServiceNotAllowedDuringExecutionError	If this service is called during the execution.
RuntimeError	If the connection is lost, in case of bad input, or in case of internal service error.

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.

Exceptions

ServiceNotAllowedDuringExecutionError	If this service is called during the execution.
RuntimeError	If the connection is lost, in case of bad input, or in case of internal service error.

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

Exceptions

ServiceNotAllowedDuringExecutionError	If this service is called during the execution.
RuntimeError	If the connection is lost, in case of bad input, or in case of internal service error.

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.

Exceptions

ServiceNotAllowedDuringExecutionError	If this service is called during the execution.
RuntimeError	If the connection is lost, in case of bad input, or in case of internal service error.

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.

Exceptions

ServiceNotAllowedDuringExecutionError	If this service is called during the execution.
RuntimeError	If the connection is lost, in case of bad input, or in case of internal service error.

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.

Exceptions

ServiceNotAllowedDuringExecutionError	If this service is called during the execution.
RuntimeError	If the connection is lost, in case of bad input, or in case of internal service error.

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.

Exceptions

ServiceNotAllowedDuringExecutionError	If this service is called during the execution.
RuntimeError	If the connection is lost, in case of bad input, or in case of internal service error.

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, size) -> execution_point

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

Exceptions

ServiceNotAllowedDuringExecutionError	If this service is called during the execution.
RuntimeError	If the connection is lost, in case of bad input, or in case of internal service error.

Parameters

execution_point	Where to start the search -> execution_point
forward	True to search forward in time, false to search backward -> boolean
read	True to search read memories -> boolean
write	True to search written memories -> boolean
address	Address to search -> logical_address
size	Size in bytes of the buffer to search -> integer

Returns

execution_point

run_search_next_memory_use_physical

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

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

Exceptions

ServiceNotAllowedDuringExecutionError	If this service is called during the execution.
RuntimeError	If the connection is lost, in case of bad input, or in case of internal service error.

Parameters

execution_point	Where to start the search -> execution_point
forward	True to search forward in time, false to search backward -> boolean
read	True to search read memories -> boolean
write	True to search written memories -> boolean
address	Address to search -> physical_address
size	Size in bytes of the buffer to search -> integer

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

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

Exceptions

ServiceNotAllowedDuringExecutionError	If this service is called during the execution.
RuntimeError	If the connection is lost, in case of bad input, or in case of internal service error.

Parameters

execution_point	Where to start the search -> execution_point
forward	True to search forward in time, false to search backward -> 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

Find the next use of the specified symbolic value, at the specified point

Exceptions

ServiceNotAllowedDuringExecutionError	If this service is called during the execution.
RuntimeError	If the connection is lost, in case of bad input, or in case of internal service error.

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_api.reven_connection('localhost', 13370)
execution_range = reven_api.execution_range(0, 20000)
criterion = reven_api.criterion()
criterion.type = reven_api.criterion_type.address
criterion.effect = reven_api.criterion_effect.match
criterion.address = 0x400000
search = reven_api.search_request(criterion)
results = r.run_search_sequences(execution_range, search)
for result in results.content:
    print(result.sequence)

Example: Search sequences contained in binary test or binary kernel

execution_range = reven_api.execution_range(0, 72100)
criterion_test = reven_api.criterion()
criterion_test.type = reven_api.criterion_type.binary
criterion_test.effect = reven_api.criterion_effect.match
criterion_test.pattern = 'test'
criterion_test.accuracy = reven_api.criterion_accuracy.contains
criterion_test.case_sensitive = False
criterion_kernel = reven_api.criterion()
criterion_kernel.type = reven_api.criterion_type.binary
criterion_kernel.effect = reven_api.criterion_effect.match
criterion_kernel.pattern = 'kernel'
criterion_kernel.accuracy = reven_api.criterion_accuracy.contains
criterion_kernel.case_sensitive = False
criterions = reven_api.vector_of_criterion()
criterions.append(criterion_test)
criterions.append(criterion_kernel)
search = reven_api.search_request(criterions,
  False)
for result in r.run_search_sequences(execution_range, search).content:
    print(result.sequence)

Example: Find the first result incrementally search

criterion = reven_api.criterion()
criterion.type = reven_api.criterion_type.address
criterion.effect = reven_api.criterion_effect.match
criterion.address = 0xb7e48f5c
search = reven_api.search_request(criterion)
# Stop after one result only
search.max_results = 1

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

execution_range = reven_api.execution_range(0, 72100)
results = []
while execution_range.begin() != execution_range.end():
    run = r.run_search_sequences(execution_range, search)
    results += [result.sequence for result in run.content]
    execution_range = run.remaining_range
    b = execution_range.begin().sequence_identifier
    e = execution_range.end().sequence_identifier
    # Very basic progress bar
    completion = b * 100/e
    sys.stdout.write('[')
    for i in range(0, completion):
        sys.stdout.write('-')
    for i in range(completion, 100):
        sys.stdout.write(' ')
    print('] {:3}%'.format(completion))
# Completed, print matching sequence numbers
for result in results:
    print result.index

Exceptions

ServiceNotAllowedDuringExecutionError	If this service is called during the execution.
RuntimeError	If the connection is lost, in case of bad input, or in case of internal service error.

Parameters

range	Range of sequences where to restrict the search. This range can be (0, 0xffffffff) to search the entire 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, only_renamed, fetch_from_index, fetch_max) -> symbol_in_run_container

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

Exceptions

ServiceNotAllowedDuringExecutionError	If this service is called during the execution.
RuntimeError	If the connection is lost, in case of bad input, or in case of internal service error.

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, return only symbols that were called during the execution -> boolean
only_renamed	If true, return only symbols that have been renamed -> 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, initial_taint, forward, count, runtime, taint_deref) -> taint

Find the next instructions altering a taint from the specified point (excluded)

Exceptions

ServiceNotAllowedDuringExecutionError	If this service is called during the execution.
RuntimeError	If the connection is lost, in case of bad input, or in case of internal service error.

Parameters

start	Start point of the taint -> execution_point
initial_taint	Tainted values at the start point -> list(symbolic)
forward	The propagation direction -> boolean
count	The maximum number of taint propagations to perform. 0 means unlimited -> integer
runtime	Maximum time (in milliseconds) the taint engine will run for. 0 means unlimited -> integer
taint_deref	True if dereferencings need to be tainted -> boolean

Returns

taint

Sequence

sequence_get_all_static_annotations

sequence_get_all_static_annotations() -> list(mini_sequence)

Find all the static sequences containing an annotation.

Exceptions

ServiceNotAllowedDuringExecutionError	If this service is called during the execution.
RuntimeError	If the connection is lost, in case of bad input, or in case of internal service error.

Returns

list(mini_sequence)

sequence_list_all

sequence_list_all() -> list(mini_sequence)

List all the static sequences.

Exceptions

ServiceNotAllowedDuringExecutionError	If this service is called during the execution.
RuntimeError	If the connection is lost, in case of bad input, or in case of internal service error.

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

Exceptions

ServiceNotAllowedDuringExecutionError	If this service is called during the execution.
RuntimeError	If the connection is lost, in case of bad input, or in case of internal service error.

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.

Exceptions

ServiceNotAllowedDuringExecutionError	If this service is called during the execution.
RuntimeError	If the connection is lost, in case of bad input, or in case of internal service error.

Parameters

sequence

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

sequence_test_and_set_static_annotations

sequence_test_and_set_static_annotations(new_sequence, old_sequence) -> boolean

Modify atomically the annotations for a static sequence. The modification takes place only if the client knows the current value of the annotations.This prevents accidental losses of data.

Returns

True if the update took place, False if it didn't.

Exceptions

ServiceNotAllowedDuringExecutionError	If this service is called during the execution.
RuntimeError	If the connection is lost, in case of bad input, or in case of internal service error.

Parameters

new_sequence	The sequence to update (annotations are inside this object) -> list(mini_sequence)
old_sequence	What the client thinks are the current annotations. -> list(mini_sequence)

Returns

boolean

Server

server_get_info

server_get_info() -> list(string)

Retrieve information on current server instance.

Returns

tuple: username, project.

This service can be called during the execution.

Exceptions

RuntimeError

If the connection is lost, in case of bad input, or in case of internal service error.

Returns

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)

This service can be called during the execution.

Exceptions

RuntimeError

If the connection is lost, in case of bad input, or in case of internal service error.

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.

Exceptions

ServiceNotAllowedDuringExecutionError	If this service is called during the execution.
RuntimeError	If the connection is lost, in case of bad input, or in case of internal service error.

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

Exceptions

ServiceNotAllowedDuringExecutionError	If this service is called during the execution.
RuntimeError	If the connection is lost, in case of bad input, or in case of internal service error.

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

Exceptions

ServiceNotAllowedDuringExecutionError	If this service is called during the execution.
RuntimeError	If the connection is lost, in case of bad input, or in case of internal service error.

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

Exceptions

ServiceNotAllowedDuringExecutionError	If this service is called during the execution.
RuntimeError	If the connection is lost, in case of bad input, or in case of internal service error.

Parameters

symbol_list

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

Trace management

trace_delete

trace_delete(name) -> None

Delete a previously saved trace.

Exceptions

ServiceNotAllowedDuringExecutionError	If this service is called during the execution.
RuntimeError	If the connection is lost, in case of bad input, or in case of internal service error.

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.

Exceptions

ServiceNotAllowedDuringExecutionError	If this service is called during the execution.
RuntimeError	If the connection is lost, in case of bad input, or in case of internal service error.

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.

Exceptions

ServiceNotAllowedDuringExecutionError	If this service is called during the execution.
RuntimeError	If the connection is lost, in case of bad input, or in case of internal service error.

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.

Exceptions

ServiceNotAllowedDuringExecutionError	If this service is called during the execution.
RuntimeError	If the connection is lost, in case of bad input, or in case of internal service error.

Parameters

name	Name of the trace file -> string

Returns

boolean