The REVEN2 python API.

Provide a pythonic way to interact with a Reven server. This mainly provides an object oriented wrapper on the low level api, plus a few helper functions to make REVEN scripting more straightforward.

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

>>> import reven2 as rvn2
>>> server = rvn2.RevenServer('localhost', 13370)

About properties

Field members in our python classes are typically encapsulated in properties. For instance, the private field RevenServer._host can be read from RevenServer.host. Properties are special methods that should not be called with parenthesis, e.g. RevenServer.host, not RevenServer.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 RevenServer's documentation).

Changelog

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

2.8.0 (Unreleased)

• Compatibility note: The values returned by the Instruction.mnemonic and Instruction.operands methods may have changed from previous versions. See the release notes for more detailed information about the changes.
• Compatibility note: The behavior of the Tainter.simple_taint and TaintResultView.filter_by_context_range functions has been modified in the way the to_context parameter is handled. Previously, the taint would not propagate through the Transition right before the to_context parameter. With this change, it is now the case. This means that a simple taint between context c and context c + 1 will now propagate through the transition between context c and its successor context, whereas before it would propagate through no context at all.
• Fixed issue where Context.find_register_change could loop infinitely when invoked in backward.
• Fixed issue where Context.find_register_change could skip changes depending on the value of the fetch_count parameter.
• Fixed an AttributeError on TaintResultView.filter_by_context_range when to_context is None (its default value).
• Improved accuracy of the `Transition.find_inverse` method so that it returns the correct transition in more cases. Previously incorrect matches might be produced on pagefault/iret, syscall/sysret, sysenter/sysexit.
• Drop support for Python 2 and Python 3.5. reven2 now only support Python 3.7+.

2.7.0

• Added RevenServer.scenario_name property.
• Fixed issue where TaintAccess.state_before and TaintAccess.state_after would sometimes raise a StopIteration Exception.
• Fixed issue where multiple calls to Tainter.simple_taint would mistakenly share the same taint data.

2.6.0

• Added Taint.accesses for querying all the transitions that touch the tainted data. Can be filtered to query only the transitions that change taint state (like Taint.changes).
• Mark Taint.changes as deprecated. Use Taint.accesses instead.
• Fixed issue where TaintResultView.take_n method would sometimes return the wrong number of results.
• Added Trace.first_context, Trace.last_context, Trace.first_transition, Trace.last_transition
• Added Search.memory to search byte patterns throughout the whole trace
• Fixed issue where TaintedRegisterSlice would sometimes take the entire register instead of the requested slice

2.5.0

• Added reven2.bookmark module that allows to programmatically add, access, edit and remove bookmarks.
• Added reven2.address.LinearAddress.translate, reven2.address.LogicalAddress.translate, reven2.address.LogicalAddressSegmentIndex.translate to translate the virtual address into reven2.address.PhysicalAddress.
• Added reven2.trace.Transition.find_inverse method to get the transition that performs the inverse operation to the given transition.
• Added reven2.trace.Context.find_register_change method to find the next/previous context in which the content of the requested register is modified.
• Added reven2.session module that allows to publish various events to clients like Axion.
• Added reven2.RevenServer.sessions property that lists the sessions tracked by the RevenServer.
• reven2.RevenServer and reven2.RevenServer.connect now accept an additional keyword parameter 'sessions' to set the tracked sessions
• In Jupyter Notebook, a reven2.trace.Transition instance now displays as a clickable link that instructs Axion to select that transition in Jupyter Notebook.

2.4.0

• No changes

2.3.0

• Marker names created by preview.taint.simple_taint are changed from tag0/tag1 to Tag0/Tag1
• Added ProjectManager.hostname and ProjectManager.port properties
• Added ProjectManager.connect to connect to a REVEN project from its name
• Added ossi.OssiContext.process to get the information of the current ossi.process.Process

2.2.1

• Fixed an issue where the Instruction object would sometimes contain wrong operands for relative jmp
• Improved the performance of the Context.read method up to x3 in typical workloads
• Added a timeout argument to the String.memory_accesses method, allowing to specify how long this function should attempt to recover all accesses before raising an exception.
• Modified Stack.backtrace property so that it returns a string instead of printing it.
• Made the if register accessible from the API. Previously, attempting to access reven2.arch.x64.if would raise a SyntaxError, because if is a python keyword. You can now access the if register through reven2.arch.x64.if_.

2.2.0

• Add trace package containing basic classes to navigate in a trace and inspect cpu registers and memory
• Add search module containing basic objects to search interesting points in a trace
• Add trace.Trace.memory_accesses and trace.Transition.memory_accesses to query memory accesses from the trace
• Add memhist package containing MemoryAccess object
• Add stack module containing basic objects to get interesting information on the stack like the backtrace
• Add string module containing a basic `String` object to get interesting strings in the trace and their memory accesses
• Add ossi package containing basic objects to get Operating System Semantic Information (OSSI)
• Add types package containing various predefined types and type constructors
• Add arch package containing the various x86_64 registers
• Add address package containing representation of memory addresses
• Add preview.project_manager package containing basic (incomplete) bindings to the REVEN project manager REST API
• Add preview.taint package containing an experimental, simplified API for the taint
• Add explicit relative imports, for Python 3 compatibility

2.0.0-dev

• The API is currently in development
• cleanup and rework of the RevenServer class (previously Project)

2.0.0-prerelease

• The API is currently not available