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

• Compatibility note: The following deprecated classes and methods have been removed: Stack.backtrace, BackTrace, Taint.changes, TaintChanges, TaintChangeView.
• Compatibility note: The return value of Symbol.name changed: previously it would return the prototype, now it returns the short name (Symbol.name_only) of a symbol if available, or defaults to the source name (Symbol.source_name).
• In Jupyter Notebook, a reven2.address.LinearAddress, reven2.address.LogicalAddress or reven2.address.LogicalAddressSegmentIndex instance now displays as a clickable link that instructs Axion to open a hexdump widget for that address in Jupyter Notebook.
• Added the reven2.session.Sessions.publish_address method to publish an address to clients like Axion.
• Add new name-related properties to Symbol: Symbol.source_name, Symbol.name_only and Symbol.prototype.
• Added trace.Mode class that indicates the current mode.
• Added Transition.pc and Transition.mode properties.
• The Transition, Instruction, CPUException are now faster to fetch back from the server: up to 5x faster in some workloads.
• Add the Ossi.executed_processes method to get the processes executed in the trace. Currently this feature will return results only for windows.
• Add the Trace.filter to iterate on contexts that match filter policies. Currently process policies and ring policy are available.
• Add preview.prototypes package containing basic parsing of C function prototypes

2.9.0

• Compatibility note: the Stack.backtrace method and BackTrace class have been deprecated and are scheduled for removal in version 2.10. Use str or display with a Stack instance to display the backtrace.
• The reven2.Trace.memory_accesses method now supports fetching memory accesses on the entire trace or between 2 transitions without specifying an address range.
• Added Transition.step_out and Transition.step_over

2.8.1

• Fix issue were Instructions were displayed without their prefixes.

2.8.0

• 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