Python API - Objects

Table of Contents

• Addresses
  • logical_address
  • logical_address_range
  • physical_address
• Analysis
  • analysis_progress
  • binary_report
  • bug
  • error
  • state_info
• Loaded binaries
  • address_space
  • library_information
  • project_binaries_information
  • symbol_information
• Context
  • float_register
  • memory_page
  • numeric_register
  • running_context
  • running_context_range
  • symbolic
  • symbolic_context
  • symbolic_type
  • vector_register
• Hardware
  • device
  • device_access
  • framebuffer_information
  • memory_range
  • port_range
• Inspector classes
  • inspector
  • inspector_arg_type
  • inspector_argument
  • inspector_properties
  • inspector_specifications
• Inspector list
  • allocations
  • alter_execution
  • execution_semantic
  • executions_after_write
  • indirect_call_target_finder
  • memory_range_history
  • stop_execution
  • string_history
  • windows_allocations
• Memory
  • memory_access
• Process introspection
  • process
  • process_address_space
  • process_switch
• Run
  • execution_point
  • execution_range
  • sequence_in_run
  • sequence_instructions
• Searching and filtering
  • filter_criterion_address
  • filter_criterion_base
  • filter_criterion_binary
  • filter_criterion_device
  • filter_criterion_effect
  • filter_criterion_symbol
  • search_item
  • search_request
  • search_result
• Sequence
  • instruction
  • instruction_taint
  • instruction_taint_diff
  • mini_sequence
  • symbol
  • symbol_in_run_container
• 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 begin 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
description	string	Description of the bug
cwe_description	string	Description of this bug in the CWE database
cwe_id	integer	Identifier of this bug in the CWE database
path	list(logical_address)	Complete path to the bug location
symbol_name	string	Symbol name where the bug occurred
equations	list(symbolic)	Equations to trigger the bug
severity	string	Severity of the bug

error

Represents a Reven error or limitation.

Attributes

Member	Type	Documentation
line_number	integer	Line number where the error occurred
message	string	Message
filename	string	Filename where the error occurred

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

Loaded binaries

address_space

Represents a binary memory mapping

Attributes

Member	Type	Documentation
start	integer	start address
end	integer	end address

library_information

Represents a library in a project.

Attributes

Member	Type	Documentation
symbols	list(symbol_information)	Symbols in this binary
mapping	list(address_space)	Memory mapping of this binary
name	string	Name of the library

project_binaries_information

Represents the project binaries inforations.

Attributes

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

symbol_information

Represents a symbol in an analyzed library.

Attributes

Member	Type	Documentation
name	string	Name of the symbol

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

Represents a page of memory.

Attributes

Member	Type	Documentation
memories	list(byte)	Memories of the page
physical_address	physical_address	Physical address of the start of the page
logical_address	logical_address	Logical address of the start of the page

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

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

Attributes

Member	Type	Documentation
content	string	Content
read_only	boolean	Read only
physical_address	physical_address	Physical address
type	symbolic_type	Type
name	string	Name

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

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
string	A string value
int_32	A integer value on 32 bits
int_16	A integer value on 16 bits
exploration_config	Internal, please do not use.
boolean	A boolean value
int_64	A integer value on 64 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	Inspectorproperties (enabled...)
arguments	list(inspector_argument)	Arguments for this inspector
name	string	Name of the inspector
description	string	Description of the inspector

Inspector list

allocations

Track memory allocations and deallocations to detect memory issues (leaks, invalid heap access...).

Constructors

__init__(arg2, arg3)

Initializes an allocations.

Parameters

allocator_name	Customize the name of the allocator -> string
deallocator_name	Customize the name of the deallocator -> string

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

execution_semantic

Will add some semantique information to the execution.

Constructors

__init__(arg2)

Initializes an execution_semantic.

Parameters

kernel_semantic

Will also print the arguments of kernel symbols that have the form xxxxxx@number in their name. -> boolean

executions_after_write

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

indirect_call_target_finder

This inspector will try to find targets of indirect jumps in exploration.

Constructors

__init__(arg2)

Initializes an indirect_call_target_finder.

Parameters

max_depth

Maximum size of the path to backtrack (in sequences). 0 means unlimited -> integer

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

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

process

A running process.

Attributes

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

process_address_space

An address space of a process.

Attributes

Member	Type	Documentation
end	integer	End of the address space
name	string	Name of the mapped file
read	boolean	Read permission on the address space
write	boolean	Write permission on the address space
start	integer	Start of the address space
file_offset	integer	Offset of the address space inside its file
execution	boolean	Exec permission on 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, instruction_index)

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

filter_criterion_address

Criterion regarding a sequence address.

Constructors

__init__(address, effect=reven.filter_criterion_effect.match, enabled=True)

Create a filter criterion that matches sequences that contain the specified address.

Parameters

address	Addres of the sequences to match -> integer
effect	Tweak the meaning of the criterion -> filter_criterion_effect
enabled	True if the criterion should be enabled at creation -> boolean

Attributes

Member	Type	Documentation
enabled	boolean	Whether this criterion is enabled
effect	filter_criterion_effect	Effect
address	integer	Address

filter_criterion_base

Generic criterion.

Attributes

Member	Type	Documentation
enabled	boolean	Whether this criterion is enabled
effect	filter_criterion_effect	Effect

filter_criterion_binary

Criterion regarding a binary's name.

Constructors

__init__(regexp, effect=reven.filter_criterion_effect.match, enabled=True)

Create a filter criterion whose regular expression will be matched against a binary's name.

Parameters

regexp	Regexp of the binary to match -> string
effect	Tweak the meaning of the criterion -> filter_criterion_effect
enabled	True if the criterion should be enabled at creation -> boolean

Attributes

Member	Type	Documentation
enabled	boolean	Whether this criterion is enabled
effect	filter_criterion_effect	Effect
name	string	Regular expression

filter_criterion_device

Criterion regarding a sequence that does a device access.

Constructors

`__init__(device='', subdevice='', effect=reven.filter_criterion_effect.match, enabled=True)`

Create a filter criterion that matches sequences that access the specified device/subdevice.

Parameters

device	Device to match -> string
subdevice	Subdevice to match -> string
effect	Tweak the meaning of the criterion -> filter_criterion_effect
enabled	True if the criterion should be enabled at creation -> boolean

Attributes

Member	Type	Documentation
device	string	Device name
enabled	boolean	Whether this criterion is enabled
effect	filter_criterion_effect	Effect
subdevice	string	Subdevice

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

filter_criterion_symbol

Criterion regarding a symbol's name.

Constructors

__init__(regexp, effect=reven.filter_criterion_effect.match, enabled=True)

Create a filter criterion whose regular expression will be matched against a symbol's name.

Parameters

regexp	Regexp of the symbol to match -> string
effect	Tweak the meaning of the criterion -> filter_criterion_effect
enabled	True if the criterion should be enabled at creation -> boolean

Attributes

Member	Type	Documentation
enabled	boolean	Whether this criterion is enabled
effect	filter_criterion_effect	Effect
name	string	Regular expression

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(filter_criterion_base)
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 -> filter_criterion_base

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(filter_criterion_base)	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
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 offset of the sequence
annotations	list(string)	Annotations added to this sequence
address	logical_address	Address of the sequence

symbol

A symbol inside a 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

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)