Low Level Python API - Objects

Table of Contents

• Addresses
  • logical_address
  • logical_address_range
  • physical_address
• Analysis
  • analysis_progress
  • binary_report
  • bug
  • bug_bug
  • bug_dynamic_location
  • bug_metadata
  • bug_occurrence
  • bug_report
  • bug_severity
  • bug_static_location
  • bug_type
  • level_type
  • log
  • state_info
• Launcher and project management
  • disk_info
  • file_chunk
  • file_info
  • launcher_connection
  • licenses_info
  • project_id
  • reven_launch_config
  • scenario_config
  • scenario_recording_config
  • scenario_recording_info
  • scenario_recording_launch_config
  • server_info
  • vm_info
• Loaded binaries
  • address_space
  • library_information
  • project_binaries_information
• Binary
  • mini_symbol
• Context
  • float_register
  • memory_page_chunk
  • numeric_register
  • running_context
  • running_context_range
  • symbolic
  • symbolic_context
  • symbolic_type
  • vector_register
• Errors
  • LicenseError
  • ServiceNotAllowedDuringExecutionError
• Hardware
  • device
  • device_access
  • framebuffer_information
  • memory_range
  • port_range
• Inspector classes
  • inspector
  • inspector_arg_type
  • inspector_argument
  • inspector_properties
  • inspector_specifications
• Inspector list
  • alter_execution
  • executions_after_write
  • memory_range_history
  • stop_execution
  • string_history
  • windows_allocations
• Memory
  • memory_access
• Process introspection
  • memory_segment
  • process
  • process_address_space
  • process_switch
• Run
  • execution_point
  • execution_range
  • sequence_in_run
  • sequence_instructions
• Searching and filtering
  • criterion
  • criterion_accuracy
  • criterion_effect
  • criterion_type
  • search_item
  • search_request
  • search_result
• Sequence
  • instruction
  • instruction_taint
  • instruction_taint_diff
  • mini_sequence
  • symbol
  • symbol_in_run_container
  • taint
  • taint_status
• String accesses
  • dereferenced_string
  • dereferenced_string_access
  • dereferenced_string_container

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

segment	Segment selector of the logical address -> integer
offset	Virtual 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

segment	Segment selector of the logical address -> integer
offset	Virtual offset of the logical address -> integer
size	size of the logical address range -> integer

__init__(start, end)

Create a logical address range from two logical addresses.

Parameters

start	Logical address marking the beginning of the range. -> logical_address
end	Logical 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

offset

Physical 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

host	Host to connect -> string
port	Port to connect -> integer

Methods

project_create

project_create(project)

Create a new project.

Parameters

project

Project 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

project	id of project to launch. -> project_id
launch_config	launch 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

project	Project id (user, project name). -> project_id
filename	Name of file to rename. -> string
new_filename	New name for given file. -> string

project_rename

project_rename(project, new_project)

Rename a project.

Parameters

project	Id of project to rename. -> project_id
new_project	New 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

project

Project id (user, project name). -> project_id

Returns

server_info

project_scenario

project_scenario(project)

Retrieve scenario recording status for a project.

Parameters

project

Project id (user, project name). -> project_id

Returns

scenario_recording_info

project_delete

project_delete(project)

Delete a project.

Parameters

project

Project 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

project	Project id (user, project name). -> project_id
filename	Name of file to remove. -> string

project_abort_scenario_recording

project_abort_scenario_recording(project)

Abort current scenario recording for a project.

Parameters

project

Project id (user, project name). -> project_id

list_projects

list_projects(user)

Request list of projects for given user.

Parameters

user	Name 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

project	Project id (user, project name). -> project_id
scenario	Scenario configuration. -> scenario_recording_config

server_kill

server_kill(port)

Kill Reven server by port.

Parameters

port	Port of Reven server. -> integer

project_list_files

project_list_files(project)

List input files of a project.

Parameters

project

Project 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

project	Project id (user, project name). -> project_id
filename	Name of file to download. -> string

Returns

file_chunk

server_restart

server_restart(port)

Restart Reven server by port, return new server port.

Parameters

port	Port 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

project	Project id (user, project name). -> project_id
filepath	Path 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

project	Project id (user, project name). -> project_id
filename	Name of file to download. -> string
destination	Filepath to save downloaded file as. -> string

server_unblock

server_unblock(port)

Unblock Reven server by port (stop current service).

Parameters

port	Port 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

user	Username -> string
project	Project 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

name	Name of the symbol -> string
rva	Relative 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

address

Logical address to read -> logical_address

Returns

integer

is_paged

is_paged(address)

Is the page mapped in physical memory?

Parameters

address

Logical address to check -> logical_address

Returns

boolean

physical_address

physical_address(address)

Returns the physical address of an address

Parameters

address

Logical 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

address	Physical address of the symbolic value -> physical_address
size	Size of the buffer in bytes -> integer

__init__(name, size=0)

Create a symbolic register.

Parameters

name	The register name -> string
size	The 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

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
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/exploration
explorator	boolean	True if this inspector can be used for exploration
executor	boolean	True if this inspector can be used for execution
debug	boolean	True if this inspector is only useful for debugging
experimental	boolean	True if this inspector is experimental

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

commands

Commands (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_level	Leave once the starting function ends -> boolean
symbol	Leave once a specific symbol is reached -> string
sequence_number	Leave 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_size	Minimum size non null-terminated strings must have to be considered -> integer
min_valid_size	Minimum size null-terminated strings must have to be considered -> integer
max_size	Maximum size of a string (allows to overlook temporary buffers) -> integer
max_string_worker	Maximum size of current strings to consider and keep in RAM -> integer
utf-16	Will 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_address	Base address where the binary is mapped -> integer
start	Start address of the binary's segment in memory -> integer
size	Size of the memory segment -> integer
binary	Path 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_name	The name of the referenced run -> string
sequence_identifier	Index of the sequence inside the run -> integer
instruction_index	0-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_identifier	Index of the sequence inside the main run -> integer
instruction_index	0-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_name	The name of the referenced run -> string
sequence_identifier	Index of the sequence inside the run -> integer
range	Number of sequences or instructions in the range -> integer
instruction_index	0-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_identifier	Index of the sequence inside the main run -> integer
range	Number of sequences or instructions in the range -> integer
instruction_index	0-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_identifier	Index of the sequence inside the main run -> integer
range	Number 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

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

__init__(filter)

Create search request from one filter.

Parameters

filter

The 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

name	Name 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

List of symbols

Attributes

Member	Type	Documentation
items	list(symbol)	List of items
range_first_id	integer	First id of the returned chunk.
collection_size	integer	Size of collection

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

List of strings

Attributes

Member	Type	Documentation
items	list(dereferenced_string)	List of items
range_first_id	integer	First id of the returned chunk.
collection_size	integer	Minimum known size of collection (actual size may be bigger)