The REVEN python API.

Provide a pythonic way to interact with a Reven project. This mainly provides an object oriented wrapper on the low level api, plus a few helper functions to make REVEN scripting more straightforward. A minimal caching mechanism is also implemented under the hood but it should be completely transparent for the interface users.

To use it, the first step is to connect to a running Reven project, for example on port 13370 of the host localhost:

>>> import reven
>>> p = reven.Project('localhost', 13370)

About properties

Field members in our python classes are typically encapsulated in properties. For instance, the private field Project._host can be read from Project.host. Properties are special methods that should not be called with parenthesis, e.g. Project.host, not Project.host(). To make this distinction clearer in our documentation, the documentation for a property always starts with the keyword Property: (e.g., see the properties host and port in Project's documentation).

About cache

Unless otherwise documented, API objects are "cached", meaning that their values are fetched from the server once at their initialization, and are immutable afterward.

While caching usually results in consistent behavior (and of course much better performance), it can occasionally produce surprising effects.

For instance, the static comment of an Instruction is retrieved during the initialization of the Instruction instance, meaning that it won't be updated for a particular instance of an Instruction, even if another user sets the comment to another value. If you need to work with fresher values, you usually have to refresh your connection by using the Project.refresh methods, and then recreate all instances of other objects from this refreshed connection.

Missing native api binding

A few low-level objects are not exposed yet:

absic to tsc conversion service.
Strings related services.

Use the reven_api module to use those objects.

Changelog

Every notable changes to this api will be documented in this file.

1.4.2

Calling Project.disconnect now immediately closes the connection, which helps to recover licence tokens in some cases. However, it also means that objects obtained from this Project instance (such as Point or Trace instances) will become invalid, and calling their methods after Project.disconnect may raise exceptions.
Fixed AddressSpace.contains method.

1.4.1

API changes: Instruction.comment, BasicBlock.comment and Point.comment are no longer properties, but methods. Their respective setters are now Instruction.set_comment, BasicBlock.set_comment and Point.push_comment.
The new methods Instruction.set_comment and BasicBlock.set_comment can now throw a ConcurrentAccessException if the cache of the Instruction or BasicBlock instance is not fresh. This prevents accidental loss of data.
New method Trace.sequence_length to retrieve the number of instructions in a given sequence.
Added an optional argument segment to all Memory.read_xx methods. This argument, when specified, allows to override the segment of the memory used to resolve the logical address.
Replaced the Memory.segment property with a Memory.default_segment property that can now only be set in constructor.
Added an optional argument default_segment to Point.memory.
Major API change Project: the connected property has been removed in favor of a Project.is_connected() method.
API change on Trace.search_point: the cojunction parameter has been renamed to conjunction.
Comparison operators for Point now raise a ValueError when the user attempts to compare two points from different traces. Previously, this would always return True or False, depending on the operator, which would lead to logical errors (such as p1 > p2 and p2 > p1 being True).
Instruction.operand now returns None consistently when there is no operand to return (previously returned '' in some cases).
In ExecutionProgress: An instance is now guaranteed to represent the progress as it was at the instance's creation. Previously in some rare cases the instance would instead reflect the current progress of the server.
In DeviceAccess: port, is_port, is_write are now properties
In Memory: read_{u8, i8, u16, i16, u32, i32, u64, i64, f32, f64} are new methods
Addition of the new class Device.PortRange.
In Device, change the return value of the method ports from a reven_api.port_range object to a Device.PortRange object.
In Criterion, rename method reven_effect to _rvn_effect.
In Criterion and inherited classes: rename reven_criterion to _rvn_criterion.
Change of the return value of the method Memory.search.
In AddressSpace.Segment, rename the property address to offset.
In AddressSpace and inherited classes, set segments as a property.
In AddressSpace and inherited classes, the property segments returns a list instead of a generator.
In FileAddressSpace, the constructor's first parameter type is changed to a list of Memory.Segment.
In ProcessAddressSpace, set file_address_spaces as a property.
In ProcessAddressSpace, the property file_address_spaces return a list instead of a generator.
In ProcessAddressSpace, remove the unused constructor's parameter project.
In DeviceAddressSpace, remove the unused constructor's parameter project.
In Binary, remove the unused constructor's parameter project.
In Binary, the property mappings return a dictionary instead of a generator.
New method Project.refresh to manually refresh the cache.
Project.process_switches now correctly returns the list of process switches. Previously, the first element of the list was a fake process switch at the point Execution_run#0_0.

1.4.0

Bumped version: it will now follow REVEN's.
Add RegisterAccessPointIterator and MemoryAccessPointIterator to iterate over Points accessing a register or a memory.
In MemoryAccess: prefixed boolean properties with `is_`, added content and is_read properties.
In ExecutionProgress: fixed last_point_index, added is_done and is_awaiting_configuration
Added Inspectors for proper Project start_execution implementation.
The Project errors method was renamed into logs.
The Project logs method returns a list of tuple instead of a dict of list of tuple.
In Report: add point, binary_name, type and remove misleading cwe_*. Bind Severity and Type.
Make the search_memory_access trace independent and move it out of Trace and into Project.
Change Trace taint method, it now returns the new type Taint and support propagation count limit.
Add a parameter to search_symbol that allow to filter on renamed symbol.
Parameters of BinaryCriterion and SymbolCriterion have changed from regexp to pattern, accuracy and case_sensitive.
Replace mapping by mappings in Binary. mappings returns a FileAddressSpace by process where the binary is mapped.
Modification of the type of Binary's symbol from vector of string to vector of Symbol.
Replacement of Chunk by Segment in AddressSpace that represent a named contiguous part of memory.
Replace Chunks by segments in AddressSpace and child.
Modification of Symbol.
Addition of map_memory_segment_into_process and add_symbols_to_binary of Project.
Remove base from AddressSpace.
Rename __contains__ to contains in AddressSpace.
Add base_address, vma_to_rva and vma_from_rva to FileAddressSpace.
Add file_address_spaces to ProcessAddressSpace.
Add cr3 to Process.
Add closest_symbol to Binary.
Add read_string and read_wstring to Memory
Add name property to SymbolicPhysicalMemory

0.0.1 - 2016-04-01 (with REVEN 1.3.0)

Initial release

Class	ConcurrentAccessError	Occurs when a modification to a shared resource is attempted, if another connection already modified the resource since the cache was last refreshed.
Class	TaintDiff	A taint propagation diff. It stores which elements either gain or loss the taint.
Class	Taint	The result of a taint propagation on a trace.
Class	Criterion	Criterion base class. Shouldn't be instanciated.
Class	AddressCriterion	Criterion object to select addresses.
Class	BinaryCriterion	Criterion object to select binaries.
Class	SymbolCriterion	Criterion object to select symbols.
Class	DeviceCriterion	Criterion object to select devices.
Class	Report	A report given by inspectors about an execution. Can signal: - potential bugs detected in the trace (such as use-after-frees). - execute-after-writes
Class	FrameBuffer	Video framebuffer information.
Class	AddressSpace	Abstract representation of a non-contiguous memory region.
Class	FileAddressSpace	An address space representing memory mapped files.
Class	ProcessAddressSpace	An address space representing the memory of a process.
Class	DeviceAddressSpace	An address space representing a device physical memory.
Class	Binary	Executable file information.
Class	Process	A running process.
Class	ProcessSwitch	A process switch during an execution.
Class	Device	A hardware device with port and memory ranges.
Class	DeviceAccess	A hardware device access. Represents either a read or write access to a port or physical memory.
Class	Symbolic	Base class for symbolic objects.
Class	SymbolicRegister	A CPU register symbolic representation.
Class	SymbolicPhysicalMemory	No class docstring; 3/5 methods documented
Class	Symbol	A symbol inside a binary.
Class	Instruction	A basic block instruction.
Class	BasicBlock	A block of uninterrupted instructions.
Class	Memory	This object represents the state of memory at a specified trace point.
Class	MemoryAccess	Represents memory access triggered by either the CPU or a device (mmio).
Class	Cpu	Represents the state of the CPU at some `Point` in the `Trace`.
Class	Point	A point in a trace.
Class	RegisterAccessPointIterator	Iterator on points accessing given register (read or write) from a `Point`.
Class	MemoryAccessPointIterator	Iterator on points accessing some given memory (read or write) from a `Point`.
Class	Sequence	Wrapper for `reven_api.sequence_in_run`.
Class	Trace	A trace is the list of all executed sequences. The `Trace` concept wraps the `Run` concepts used in axion and the low-level API.
Class	Save	A saved project.
Class	ExecutionProgress	Execution progress.
Class	InspectorMemoryHistory	This inspector tracks the history of all memory accesses. Activating it is highly recommended.
Class	InspectorExecutionsAfterWrite	This inspector tracks executions of the memory addresses that have been written to, to detect execute-after-write like in self-modifying code. It requires inspector memory_range_history.
Class	InspectorAlterExecution	This inspector alters the program's execution.
Class	InspectorStopExecution	This inspector stops the execution at a certain configured point.
Class	InspectorStringHistory	This inspector will collect information about string that have been manipulated during the execution.
Class	Project	A reven project. This is the root api object.

r.api : module documentation