REVEN-Axion 2018v1.5.0
Low Level Python API - Objects

Table of Contents

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

Addresses

logical_address

Represents a logical address.

Constructors

__init__(segment, offset)

Create a logical address from a segment and an offset.

Parameters
segmentSegment selector of the logical address -> integer
offsetVirtual offset of the logical address -> integer

Attributes

Member Type Documentation
segment integer Segment selector
offset integer Offset

logical_address_range

A range of logical addresses.

Constructors

__init__(segment=0, offset=0, size=0)

Create a logical address range from a segment, an address, and a size.

Parameters
segmentSegment selector of the logical address -> integer
offsetVirtual offset of the logical address -> integer
sizesize of the logical address range -> integer

__init__(start, end)

Create a logical address range from two logical addresses.

Parameters
startLogical address marking the beginning of the range. -> logical_address
endLogical address marking the end of the range. -> logical_address

Attributes

Member Type Documentation
start logical_address Start of the range
end logical_address End of the range

physical_address

Represents a physical address.

Constructors

__init__(offset)

Create a physical address with an offset.

Parameters
offsetPhysical offset of the address in main RAM -> integer

Attributes

Member Type Documentation
paged boolean True if the physical address represents a successfully translated address.
offset integer Offset

Analysis

analysis_progress

Tells the state of the current analysis.

Attributes

Member Type Documentation
busy boolean Is an analysis in progress ?
max_tsc integer Max TSC
text string Text of the progress
current_sequence integer Current sequence
max_sequences integer Max number of sequences
current_tsc integer Current TSC

binary_report

Report of errors.

Attributes

Member Type Documentation
binary_name string Name of the binary
bugs list(bug) List of bugs in this binary

bug

A bug or vulnerability found by Reven.

Attributes

Member Type Documentation
severity string Severity of the bug
cwe_id integer Identifier of this bug in the CWE database
symbol_name string Symbol name where the bug occurred
description string Description of the bug
cwe_description string Description of this bug in the CWE database

bug_bug

A bug or vulnerability found by Reven.

Attributes

Member Type Documentation
static_location bug_static_location Static location of the bug
type bug_type Type of the bug
occurrences list(bug_occurrence) Occurrences of the bug

bug_dynamic_location

Dynamic bug location.

Attributes

Member Type Documentation
instruction integer Instruction index in sequence
sequence integer Sequence index in run
run_id integer Run id

bug_metadata

Map id to strings for bug reports

Attributes

Member Type Documentation
symbols dict(std::uint64_t -> string) Symbol name by symbol id
runs dict(std::uint64_t -> string) Run name by run id
binaries dict(std::uint64_t -> string) Binary name by binary id-> dict()

bug_occurrence

A bug or vulnerability occurrence found by Reven.

Attributes

Member Type Documentation
severity bug_severity Severity of the occurrence
description string Description of the occurrence
location bug_dynamic_location Dynamic location of the occurrence

bug_report

Bug report

Attributes

Member Type Documentation
bugs list(bug_bug) Bugs
metadata bug_metadata metadata

bug_severity

Bug severity.

Enum values

Enum Documentation
high High severity
unknown Unknown severity
medium Medium severity
low Low severity

bug_static_location

Static bug location

Attributes

Member Type Documentation
binary_id integer Binary id
symbol_id integer Symbol id

bug_type

Bug type.

Enum values

Enum Documentation
memory_leak Memory leak
double_free Double free
unknown Unknown bug type
invalid_free Invalid free
use_after_free Use after free
deref_not_checked Dereferencing not checked
null_pointer Null pointer dereference
heap_overflow Heap-based buffer overflow

level_type

Level type of log message.

Enum values

Enum Documentation
warning Warning log
general General log
success Success log
error Error log

log

Represents a Reven log or limitation.

Attributes

Member Type Documentation
message string Message
type level_type Type
location execution_point Location if available

state_info

Name and date of a saved state.

Attributes

Member Type Documentation
timestamp string When the state was saved
name string Name of the state

Launcher and project management

disk_info

Status of disk usage on server

Attributes

Member Type Documentation
available integer Actual available disk capacity (free amount minus system reserved).
capacity integer Total disk capacity.
free integer Free disk capacity

file_chunk

File chunk.

Attributes

Member Type Documentation
content list(byte) Chunk data content
chunk_start integer Chunk start address
filename string Name of file owning this chunk

file_info

Information about a project file.

Attributes

Member Type Documentation
last_modified integer Timestamp of last modification
description string File description
filename string Filename

launcher_connection

Handles the connection to Reven launcher.

Constructors

`__init__(host='localhost', port=8080)`

Create a launcher connection with the specified host and port.

Parameters
hostHost to connect -> string
portPort to connect -> integer

Methods

project_create

project_create(project)

Create a new project.

Parameters
projectProject id (user, project name). -> project_id

server_launch

server_launch(project, launch_config)

Launch Reven server for given project and return server port.

Starting multiple servers for a single project

project_id = reven_api.project_id('example', 'test') port1 = launcher.server_launch(project_id) # first server launched on port1 port2 = launcher.server_launch(project_id) # second server launched on port2

Due to the design of the API, multiple servers can be started for a single project.
The main use case for this would be to launch a new execution with extra inspectors while keeping a previous one for browsing in Axion.
However, please note that this workflow is **not** officially supported.
Each started server will have its own port. These are different server instances, but Axion doesn'thave the means to display them.It will display the server as 'started' for as long as there is at least one server instance of the same project started. The displayed port will be the lowest among all server instance, and the instance at this port will be the one that Axion connects to and which will be closed if the 'force close' button is clicked.
Having different server instances launched on the same project has practical implications:
* It becomes more difficult to keep track of launched servers and projects
* It becomes more likely to connect to different server instances by mistake, wich will quickly exhaust licenses.
You can programmatically list all server instances with `launcher_connection.list_servers()`:
~~~.py
for server in launcher.list_servers():
print server # print full information
print server.project # print the project_id of the server
print server.reven_server.port # print the port of the server

From there, you can kill unwanted duplicates with launcher_connection.server_kill(port). However, there is currently no practical way of knowing which server was launched first (in particular, the most recent server does not necessarily have the highest port). The safest way to fix duplicate problems is to prevent them from happening.You can do this by checking if a server is already launched before starting a new one:

def launch_or_get_port(launcher, projectid, reven_config):
for server in l.list_servers():
if server.project == projectid:
return server.reven_server.port
# not found, launching a new one
return launcher.server_launch(projectid, reven_config)
Parameters
projectid of project to launch. -> project_id
launch_configlaunch configuration (license, port, etc.). -> reven_launch_config
Returns
integer

list_vms

list_vms()

Request list of available Virtual Machine configurations.

Returns
list(vm_info)

project_rename_file

project_rename_file(project, filename, new_filename)

Rename an input file from a project.

Rename a file after uploading

This function renames a file on the server right after uploading.

import reven_launcher from os.path import basename def project_upload_and_rename_file(launcher, project_id, path, new_name): launcher.project_upload_file(project_id, path) ~~~

Parameters
projectProject id (user, project name). -> project_id
filenameName of file to rename. -> string
new_filenameNew name for given file. -> string

project_rename

project_rename(project, new_project)

Rename a project.

Parameters
projectId of project to rename. -> project_id
new_projectNew project id (user, project name). -> project_id

list_servers

list_servers()

Request list of running Reven servers.

Returns
list(server_info)

project_details

project_details(project)

Retrieve server information of a project.

Parameters
projectProject id (user, project name). -> project_id
Returns
server_info

project_scenario

project_scenario(project)

Retrieve scenario recording status for a project.

Parameters
projectProject id (user, project name). -> project_id
Returns
scenario_recording_info

project_delete

project_delete(project)

Delete a project.

Parameters
projectProject id (user, project name). -> project_id

system_licenses_info

system_licenses_info()

Return licenses usage.

Returns
licenses_info

project_remove_file

project_remove_file(project, filename)

Remove an input file from a project.

Parameters
projectProject id (user, project name). -> project_id
filenameName of file to remove. -> string

project_abort_scenario_recording

project_abort_scenario_recording(project)

Abort current scenario recording for a project.

Parameters
projectProject id (user, project name). -> project_id

list_projects

list_projects(user)

Request list of projects for given user.

Parameters
userName of user to request projects from -> string
Returns
list(project_id)

list_users

list_users()

Request list of reven users.

Returns
list(string)

project_record_scenario

project_record_scenario(project, scenario)

Record a scenario.

Parameters
projectProject id (user, project name). -> project_id
scenarioScenario configuration. -> scenario_recording_config

server_kill

server_kill(port)

Kill Reven server by port.

Parameters
portPort of Reven server. -> integer

project_list_files

project_list_files(project)

List input files of a project.

Parameters
projectProject id (user, project name). -> project_id
Returns
list(file_info)

project_download_file

project_download_file(project, filename)

Download and return a file chunk.

Parameters
projectProject id (user, project name). -> project_id
filenameName of file to download. -> string
Returns
file_chunk

server_restart

server_restart(port)

Restart Reven server by port, return new server port.

Parameters
portPort of Reven server. -> integer
Returns
integer

system_disk_info

system_disk_info()

Return disk usage.

Returns
disk_info

project_upload_file

project_upload_file(project, filepath)

Upload input file to a project.

Parameters
projectProject id (user, project name). -> project_id
filepathPath of the file to upload. -> string

project_download_file_as

project_download_file_as(project, filename, destination)

Download a file to a client side location.

Parameters
projectProject id (user, project name). -> project_id
filenameName of file to download. -> string
destinationFilepath to save downloaded file as. -> string

server_unblock

server_unblock(port)

Unblock Reven server by port (stop current service).

Parameters
portPort of Reven server. -> integer

licenses_info

Status of license availability

Attributes

Member Type Documentation
team_left integer Number of available team lincenses
mono_left integer Number of available mono lincenses
mono_total integer Total number of mono licenses
team_total integer Total number of team licenses

project_id

Identify a project by its username and project name pair.

Constructors

__init__(user, project)

Create a project id from a user and a project name.

Parameters
userUsername -> string
projectProject name -> string

Attributes

Member Type Documentation
project string Project name
user string Username

reven_launch_config

Reven launch configuration.

Attributes

Member Type Documentation
reven_arguments string Arguments given to Reven server
is_mono boolean True if license is restricted to one connected user
port integer Port listening to

scenario_config

Configuration of a Reven scenario.

Attributes

Member Type Documentation
binary_dump_hint string Dump hint (symbol or address)
system_pdb_path string Pdb path (generated from vm configuration)
binary_name string Name of analysed binary
vm_config_name string Name of virtual machine configuration
binary_arguments string Arguments passed to binary
binary_dump_address string Effective dump address (generated from dump hint)-> string

scenario_recording_config

Information required to launch a scenario recording.

Attributes

Member Type Documentation
recording scenario_recording_launch_config Dynamic (volatile) information to launch scenario recording
scenario scenario_config Static information (binary configuration) for scenario recording

scenario_recording_info

Status of scenario recording.

Attributes

Member Type Documentation
core_name string Core name used for recording
is_recording boolean True if recording is running
is_successful boolean True if recording was successful
log_chunk string Current log

scenario_recording_launch_config

Dynamic information required to launch a scenario recording.

Attributes

Member Type Documentation
vnc_port string Vnc port to run vm's vnc server
vnc_password string Vnc password to use for vm's vnc server
is_interactive boolean Enable interactive mode (no preloader scenario auto recording)

server_info

Reven server info.

Attributes

Member Type Documentation
project project_id Project id
reven_server reven_launch_config Launch configuration
scenario scenario_config Scenario configuration

vm_info

Configuration of a Virtual Machine used for scenario recording.

Attributes

Member Type Documentation
pdb_path string Path to pdb matching vm system
dynamic_launch string Launch prefix for dynamic binaries
stopper string Stopper program to call for stopping the vm
name string Name of configuration
static_launch string Launch prefix for static binaries-> string
vbox_name string Name of the vm in VirtualBox
os string OS installed on the vm
vnc_port string Port to launch VNC server on
vnc_password string Password of VNC server
segment string Default segment for dump address
display string Display string used in GUI

Loaded binaries

address_space

Represents a binary memory mapping

Attributes

Member Type Documentation
start integer start address
base integer base address
end integer end address

library_information

Represents a library in a project.

Attributes

Member Type Documentation
symbols list(symbol) Symbols in this binary
mapping dict(std::uint64_t -> list(address_space)) Memory mapping of this binary
name string Name of the library

project_binaries_information

Represents the project binaries information.

Attributes

Member Type Documentation
libraries_information list(library_information) Symbols in this binary

Binary

mini_symbol

A symbol.

Constructors

__init__(name, rva)

Create a mini_symbol.

Parameters
nameName of the symbol -> string
rvaRelative virtual address of the symbol -> integer

Attributes

Member Type Documentation
rva integer Symbol rva
name string Symbol name

Context

float_register

Represents a register with a floating point value.

Attributes

Member Type Documentation
defined boolean True if the register has valid value
value string Value of the register

memory_page_chunk

Represents a part of or a full page of memory.

Attributes

Member Type Documentation
paged boolean The page is mapped in physical memory
logical_address logical_address Logical address of the start of the page
bytes list(byte) Bytes of the page
physical_address physical_address Physical address of the start of the page
size integer Size of the page chunk

numeric_register

Represents a register with a numeric value.

Attributes

Member Type Documentation
defined boolean True if the register has valid value
type symbolic_type Type of the register
value integer Value of the register

running_context

Represents the context of the machine at a point in time.

Methods

read_byte

read_byte(address)

Read a byte from an address

Parameters
addressLogical address to read -> logical_address
Returns
integer

is_paged

is_paged(address)

Is the page mapped in physical memory?

Parameters
addressLogical address to check -> logical_address
Returns
boolean

physical_address

physical_address(address)

Returns the physical address of an address

Parameters
addressLogical address to translate -> logical_address
Returns
physical_address

Attributes

Member Type Documentation
memory_pages list(memory_page_chunk) Memories
vector_registers dict(string -> vector_register) Registers with a vector value
float_registers dict(string -> float_register) Registers with a float value
numeric_registers dict(string -> numeric_register) Registers with a numeric value

running_context_range

Represents the context of the machine between two points in time.

Attributes

Member Type Documentation
after running_context Final state
before running_context Initial state

symbolic

Represents a symbolic value.

Constructors

__init__(address, size)

Create a symbolic physical memory buffer.

Parameters
addressPhysical address of the symbolic value -> physical_address
sizeSize of the buffer in bytes -> integer

__init__(name, size=0)

Create a symbolic register.

Parameters
nameThe register name -> string
sizeThe register size in bytes -> integer

Attributes

Member Type Documentation
read_only boolean Read only
physical_address physical_address Physical address
name string Name
content string Content
type symbolic_type Type
size integer Size of the access

symbolic_context

Represents an aggregated delta context of the symbolic memories and registers between two points.

Attributes

Member Type Documentation
memories list(symbolic) Memories
registers list(symbolic) Registers

symbolic_type

Type of a symbolic variable. For registers, this also specifies the group of register.

Enum values

Enum Documentation
register_internal Internal registers (EIP, CR registers, etc)
data_named User-chosen named value
register_flag General purpose flags (does not contain FPU flags)
memory Memory access
register_index Index registers (xSI and xDI)
unknown Unknown symbolic type
register_fpu Floating point registers (R0-7 ; contains ST0-7 and MM0-7) and FPU flags
register_segment Segment registers (CS, DS, ES, FS, GS)
memory_physical Direct memory access
computation Operation between two symbolics
register_sse SSE registers (XMM etc)
register_stack Stack registers (xBP and xSP)
integer Integer value
floating Floating point value
register_all_purpose All purpose register (xAX, xBX, xCX, xDX)
register_debug Debug registers
data_vector_part Vector register

vector_register

Represents a register with a floating point value.

Attributes

Member Type Documentation
defined boolean True if the register has valid value
value string Value of the register

Errors

LicenseError

Occurs when a connection fails due to no license being available.

Attributes

Member Type Documentation
message string None
args tuple None

ServiceNotAllowedDuringExecutionError

Occurs when a service is called during execution, if the service is not allowed to be called during execution.

Attributes

Member Type Documentation
message string None
args tuple None

Hardware

device

A hardware device with port and memory ranges.

Attributes

Member Type Documentation
port_ranges list(port_range) Port ranges of this device
description string Description of device
name string Name of the device
memory_ranges list(memory_range) Memory ranges of this device

device_access

An access to a device.

Attributes

Member Type Documentation
subdevice_name string Subdevice name
physical_address physical_address If not is_port, contains the physical_address, otherwise 0
is_port boolean If true, this is a port access
logical_address logical_address If not is_port, contains the logical_address, otherwise 0
device_name string Device name
write boolean If true, this is a write
location execution_point Location of the access
port integer If is_port, contains the port index, otherwise 0
description string Textual information of what happened

framebuffer_information

Information about the framebuffer.

Attributes

Member Type Documentation
width integer Width in pixels of the framebuffer
total_size integer Total size of the framebuffer in bytes
line_size integer Bytes per line (may be higher than width*bpp/8)
height integer Height in pixels of the framebuffer
bpp integer Number of bits per pixels
address physical_address Physical address of the framebuffer in memory

memory_range

A memory range used by a device.

Attributes

Member Type Documentation
physical_address physical_address Start address in physical mode
length integer Length of the range, in bytes
description string Description of the memory range

port_range

A port range used by a device.

Attributes

Member Type Documentation
length integer Length of the range, in ports
description string Description of the port range
port integer Start port

scenario_item

Event in the scenario.

Attributes

Member Type Documentation
content string Description of the event
index integer Index of the event in the scenario
tsc integer Value of the tsc of the event
validation_point execution_point Point where the event was validated, if available

scenario_item_container

A range extracted from the collection of scenario events of the project.

Attributes

Member Type Documentation
items list(scenario_item) Items of the range, may be empty.
range_first_id integer Index of the range's first element in the collection. Undefined if the range is empty.
collection_size integer Total size of the collection from which the range is constructed.

Inspector classes

inspector

Base class for inspectors

inspector_arg_type

Various types of arguments available to inspectors

Enum values

Enum Documentation
int_16 A integer value on 16 bits
boolean A boolean value
string A string value
int_64 A integer value on 64 bits
int_32 A integer value on 32 bits

inspector_argument

Represents an argument of an inspector.

Attributes

Member Type Documentation
type inspector_arg_type Type of argument
description string Argument description
name string Argument name

inspector_properties

Represents the properties of an inspector.

Attributes

Member Type Documentation
debug boolean True if this inspector is only useful for debugging
to_display boolean True if this inspector needs to be displayed in the client
enabled boolean True if this inspector is scheduled for next execution
experimental boolean True if this inspector is experimental
executor boolean True if this inspector can be used for execution

inspector_specifications

Represents the specifications of an inspector.

Attributes

Member Type Documentation
properties inspector_properties Inspector properties (enabled...)
arguments list(inspector_argument) Arguments for this inspector
name string Name of the inspector
description string Description of the inspector

Inspector list

alter_execution

Will alter the program's execution. Is configured through the rerun widget in Axion.

Constructors

__init__(arg2)

Initializes an alter_execution.

A command example would be #1_1(eax=1) to force eax to 1 on the second instruction of sequence #1

Parameters
commandsCommands (automatically filled by rerun widget) -> string

executions_after_write

Allows to track a executions after memory write like self modifying code (requires inspector memory_range_history)

memory_range_history

Allows to track the history of all memory accesses.

stop_execution

Allows to control when to stop the execution.

Constructors

__init__(arg2, arg3, arg4)

Initializes an stop_execution.

Parameters
stop_at_top_levelLeave once the starting function ends -> boolean
symbolLeave once a specific symbol is reached -> string
sequence_numberLeave after translating this number of sequences -> integer

string_history

Will look for and record all strings that are dereferenced throughout the execution.

Constructors

__init__(arg2, arg3, arg4, arg5, arg6)

Initializes an string_history.

Parameters
min_invalid_sizeMinimum size non null-terminated strings must have to be considered -> integer
min_valid_sizeMinimum size null-terminated strings must have to be considered -> integer
max_sizeMaximum size of a string (allows to overlook temporary buffers) -> integer
max_string_workerMaximum size of current strings to consider and keep in RAM -> integer
utf-16Will look for utf-16 strings as well. -> boolean

windows_allocations

POC for the ie_crash trace. Will track all the allocations, deallocations, deref and then detect memory errors (use after free, double free...) in Windows.

Memory

memory_access

Represents a memory access.

Attributes

Member Type Documentation
size integer Size of the memory access
content integer Content of the memory after the access
instruction_index integer Instruction index for this memory access
run_id integer Run identifier where the memory access occurred
read boolean True if the memory was accessed for reading
timestamp integer Timestamp for this memory access
tsc integer Tsc timestamp of the memory access
logical logical_address Logical address used to access the memory
allocation boolean True if this is an allocation type of access
write boolean True if the memory was accessed for writing
free boolean True if this is a deallocation type of access
execution boolean True if the memory was accessed for execution
physical physical_address Physical address used of the memory

Process introspection

memory_segment

A segment in memory representing a part of/full binary.

Constructors

__init__(base_address, start, size, binary)

Create a memory segment.

Parameters
base_addressBase address where the binary is mapped -> integer
startStart address of the binary's segment in memory -> integer
sizeSize of the memory segment -> integer
binaryPath of binary -> string

Attributes

Member Type Documentation
binary string Binary path
start integer Start address of binary's segment in memory
base_address integer Base address of the binary
size integer Size of the memory segment

process

A running process.

Attributes

Member Type Documentation
address_spaces list(process_address_space) Address spaces
cr3 integer Process cr3
pid integer Process identifier
name string Process name

process_address_space

An address space of a process.

Attributes

Member Type Documentation
start integer Start of the address space
end integer End of the address space
name string Name of the mapped file
base_address integer Base address of the address space

process_switch

A process switch during a run.

Attributes

Member Type Documentation
cr3 integer New process CR3
pid integer New process identifier
point execution_point Execution point when the switch occurred

Run

execution_point

Execution point inside a trace.

Constructors

__init__(run_name, sequence_identifier, instruction_index)

Create an execution point of the specified run point.

Parameters
run_nameThe name of the referenced run -> string
sequence_identifierIndex of the sequence inside the run -> integer
instruction_index0-based index of the instruction inside the sequence -> integer

__init__(sequence_identifier, instruction_index=0)

Create an execution point of the point for the main run.

Parameters
sequence_identifierIndex of the sequence inside the main run -> integer
instruction_index0-based index of the instruction inside the sequence -> integer

Methods

valid

valid()

Returns true if the execution point is valid.

The execution point is only tested for its validity against the sequence identifier. More precisely, this function returns true if the sequence identifier is not the root sequence identifier.

Returns
boolean

Attributes

Member Type Documentation
instruction_index integer Instruction index
sequence_identifier integer Sequence identifier
run_name string Name of the run

execution_range

An range of sequences or instructions inside an execution.

Constructors

__init__(run_name, sequence_identifier, range=1, instruction_index=-1)

Create an execution range from the specified arguments.

Parameters
run_nameThe name of the referenced run -> string
sequence_identifierIndex of the sequence inside the run -> integer
rangeNumber of sequences or instructions in the range -> integer
instruction_index0-based index of the instruction inside the sequence -> integer

__init__(sequence_identifier, range, instruction_index)

Create an instruction-based execution range from the specified arguments (begins at the specified sequence/instruction and end after 'range' instructions).

Parameters
sequence_identifierIndex of the sequence inside the main run -> integer
rangeNumber of sequences or instructions in the range -> integer
instruction_index0-based index of the instruction inside the sequence -> integer

__init__(sequence_identifier, range=1)

Create a sequence-based execution range from the specified arguments (begins at the first instruction of the specified sequence and end at the beginning of 'sequence_identifier' + 'range'.

Parameters
sequence_identifierIndex of the sequence inside the main run -> integer
rangeNumber of sequences in the range -> integer

Methods

begin

begin()

Returns the start execution point of this range

Returns
execution_point

valid

valid()

Returns true if the execution point is valid.

The execution point is only tested for its validity against the sequence identifier. More precisely, this function returns true if the sequence identifier is not the root sequence identifier.

Returns
boolean

end

end()

Returns the end execution point of this range

Returns
execution_point

Attributes

Member Type Documentation
instruction_index integer Instruction index in the sequence, -1 if referencing the whole sequence
range integer The range of values. Either an instruction range if instruction_index_ is positive, or a sequence range
sequence_identifier integer Sequence identifier
run_name string Name of the run

sequence_in_run

Represents a sequence inside a run.

Attributes

Member Type Documentation
has_bug boolean Sequence bug status
index integer Sequence index
run_id integer Run index
has_children boolean Does this sequence have children ?
sequence mini_sequence Sequence
trace_infos dict(integer -> string) Trace information of the sequence
children_have_bugs boolean Childrens sequences bug status
first_child_symbol symbol Symbol of the first child
symbol symbol Symbol of this sequence

sequence_instructions

Represents a sequence with its instructions.

Attributes

Member Type Documentation
sequence sequence_in_run Sequence
instructions list(instruction) Instructions the sequence

Searching and filtering

criterion

Criterion to search on.

WARNING: This object is an 'union-like' struct. The optional members to set depend on the value of the member 'type'.

Attributes

Member Type Documentation
subdevice string Subdevice name (Valid if type == device)-> string
pattern string The pattern to match (Valid if type == symbol/cbinary)
effect criterion_effect Effect (Always valid)
case_sensitive boolean Whether the match is case sensitive or not (Valid if type == symbol/cbinary)
address integer Address (Valid if type == address)
device string Device name (Valid if type == device)
type criterion_type Type of the criterion (Always valid)
accuracy criterion_accuracy Accuracy of the criterion (Valid if type == symbol/cbinary)

criterion_accuracy

Allows to define the accuracy of a criterion

Enum values

Enum Documentation
regexp The criteria is a regular expression (POSIX).
contains The criteria is a part of the value to filter.
exact The criteria is the exact value to filter.

criterion_effect

Allows to tweak the meaning of a criterion

Enum values

Enum Documentation
invert_match Inverts the meaning of the criteria (NOT)
match Normal meaning of the criteria

criterion_type

Allows to define the type of a criterion

Enum values

Enum Documentation
device The criterion is a device criterion.
binary The criterion is a binary criterion.
symbol The criterion is a symbol criterion.
address The criterion is a address criterion.

search_item

Single result of a search.

Attributes

Member Type Documentation
comment string Comment why the result matched
sequence sequence_in_run Sequence of the result

search_request

Criteria for a search.

Constructors

__init__(filters, need_all=True)

Create a search request from the list of filters.

Parameters
filtersA list of filters to add to the search initially -> list(criterion)
need_allTrue if you need all criteria (AND), False for an OR -> boolean

__init__(filter)

Create search request from one filter.

Parameters
filterThe filter to use for the search -> criterion

Attributes

Member Type Documentation
need_all boolean If true, all criteria need to match (AND), else any criteria need to match (OR)
max_results integer Maximum number of results to return. 0 for infinite.
max_sequences integer Maximum number of sequences to check. 0 for infinite. Acts on top of the range.
criteria list(criterion) Criteria

search_result

Result of a search.

Attributes

Member Type Documentation
content list(search_item) Matching items
remaining_range execution_range Range not checked due to a reached limit

Sequence

instruction

Represents an instruction.

Attributes

Member Type Documentation
mnemonic string Mnemonic of the instruction
operand_two string Second operand of the instruction, if applicable
prefixes string Prefixes of the instruction
operand_one string First operand of the instruction, if applicable
raw_instruction list(byte) Raw instruction bytes.
offset integer Offset of the instruction if memory
size integer Size of the instruction in bytes
operand_three string Third operand of the instruction, if applicable

instruction_taint

Store the data tainting context of an instruction.

Attributes

Member Type Documentation
modifies_taint boolean Did this instruction modifies taint or not
tainted_values list(symbolic) Tainted symbolics when this instruction is executed
point execution_point The tainted instruction

instruction_taint_diff

Store the taint propagation effect of an instruction.

Attributes

Member Type Documentation
new list(symbolic) The untainted symbolics
old list(symbolic) The newly tainted symbolics

mini_sequence

Sequence of instructions.

Attributes

Member Type Documentation
symbol symbol Symbol of the sequence
size integer Size of the sequence in bytes
annotations list(string) Annotations added to this sequence
address logical_address Address of the sequence

symbol

A symbol inside of a binary.

Constructors

__init__(name)

Create a symbol with a given name.

Parameters
nameName of the symbol to create -> string

Methods

name_offset

name_offset()

Combines the name and the offset into a single string.

Returns
string

Attributes

Member Type Documentation
name string Main name of this symbol
name_index integer Index of the selected name
kernel_symbol boolean True if the symbol lies inside the kernel
binary_name string Name of the binary that contains this symbol
names list(string) Names
offset integer Offset
vma integer Virtual memory address of the symbol
segment integer Segment selector of the logical address where the symbol is located
html_documentation string Relative link to the html documentation if available

symbol_in_run_container

A range extracted from the collection of symbols of the project.

Attributes

Member Type Documentation
items list(symbol) Items of the range, may be empty.
range_first_id integer Index of the range's first element in the collection. Undefined if the range is empty.
collection_size integer Total size of the collection from which the range is constructed.

taint

Store a taint propagation result.

Attributes

Member Type Documentation
status taint_status The taint propagtion status
diffs dict(execution_point -> instruction_taint_diff) The taint propagation effects
last_tainted_point execution_point The last point reached

taint_status

Status of a taint propagation.

Enum values

Enum Documentation
unknown Unknown taint status
vanished The taint propagation stopped because nothing is tainted anymore
completed The taint propagation completed without errors
timeout The taint propagation stopped because it took longer than permitted
error The taint propagation encountered an error

String accesses

dereferenced_string

Represents a string that's been accessed during the execution.

Attributes

Member Type Documentation
content string String content
creation_sequence integer Sequence id where this string was created
valid_string boolean True if this string is valid
unique_id integer Unique ID
address logical_address String address

dereferenced_string_access

Represents a string that's been accessed during the execution.

Attributes

Member Type Documentation
symbols list(string) Symbol names of the string is accessed (same order as first list
is_write list(byte) Booleans indicating if the string is written -> list(boolean)
unique_id integer Unique ID
sequences list(integer) Sequences where the string is accessed

dereferenced_string_container

A range extracted from a collection of strings.

Attributes

Member Type Documentation
items list(dereferenced_string) Items of the range, may be empty.
range_first_id integer Index of the range's first element in the collection. Undefined if the range is empty.
collection_size integer Minimum known size of the collection from which the range is constructed (total size may be bigger).