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)
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).
Every notable changes to this api will be documented in this file.
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.reven2.Trace.memory_accesses method now supports fetching memory accesses on the entire trace or between 2 transitions without specifying an address range.Transition.step_out and Transition.step_overInstructions were displayed without their prefixes.Instruction.mnemonic and Instruction.operands methods may have changed from previous versions. See the release notes for more detailed information about the changes.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.Context.find_register_change could loop infinitely when invoked in backward.Context.find_register_change could skip changes depending on the value of the fetch_count parameter.TaintResultView.filter_by_context_range when to_context is None (its default value).reven2 now only support Python 3.7+.RevenServer.scenario_name property.TaintAccess.state_before and TaintAccess.state_after would sometimes raise a StopIteration Exception.Tainter.simple_taint would mistakenly share the same taint data.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).Taint.changes as deprecated. Use Taint.accesses instead.TaintResultView.take_n method would sometimes return the wrong number of results.Trace.first_context, Trace.last_context, Trace.first_transition, Trace.last_transitionSearch.memory to search byte patterns throughout the whole traceTaintedRegisterSlice would sometimes take the entire register instead of the requested slicereven2.bookmark module that allows to programmatically add, access, edit and remove bookmarks.reven2.address.LinearAddress.translate, reven2.address.LogicalAddress.translate, reven2.address.LogicalAddressSegmentIndex.translate to translate the virtual address into reven2.address.PhysicalAddress.reven2.trace.Transition.find_inverse method to get the transition that performs the inverse operation to the given transition.reven2.trace.Context.find_register_change method to find the next/previous context in which the content of the requested register is modified.reven2.session module that allows to publish various events to clients like Axion.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 sessionsreven2.trace.Transition instance now displays as a clickable link that instructs Axion to select that transition in Jupyter Notebook.tag0/tag1 to Tag0/Tag1ProjectManager.hostname and ProjectManager.port propertiesProjectManager.connect to connect to a REVEN project from its nameossi.OssiContext.process to get the information of the current ossi.process.ProcessInstruction object would sometimes contain wrong operands for relative jmpContext.read method up to x3 in typical workloadstimeout argument to the String.memory_accesses method, allowing to specify how long this function should attempt to recover all accesses before raising an exception.Stack.backtrace property so that it returns a string instead of printing it.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_.trace package containing basic classes to navigate in a trace and inspect cpu registers and memorysearch module containing basic objects to search interesting points in a tracetrace.Trace.memory_accesses and trace.Transition.memory_accesses to query memory accesses from the tracememhist package containing MemoryAccess objectstack module containing basic objects to get interesting information on the stack like the backtracestring module containing a basic `String` object to get interesting strings in the trace and their memory accessesossi package containing basic objects to get Operating System Semantic Information (OSSI)types package containing various predefined types and type constructorsarch package containing the various x86_64 registersaddress package containing representation of memory addressespreview.project_manager package containing basic (incomplete) bindings to the REVEN project manager REST APIpreview.taint package containing an experimental, simplified API for the taintRevenServer class (previously Project)| Module | address |
Defines memory address classes |
| Package | arch |
Contains classes and instances related to the description of the machine architecture. |
| Module | bookmark |
No module docstring; 2/3 classes documented |
| Module | memhist |
No module docstring; 3/3 classes, 0/10 functions, 0/1 variables documented |
| Package | ossi |
Package related to OSSI information. See the OssiContext object. |
| Module | prelude |
This is the prelude module of the Reven2 python API |
| Package | preview |
Contains subpackages and modules whose API is not considered stable yet. |
| Module | search |
Module related to trace search. See the Search object. |
| Module | search_in_memory |
No module docstring; 7/8 classes documented |
| Module | session |
Module related to sessions, that allow to publish information to various other connected clients (e.g., Axion). |
| Module | stack |
Module related to stack. See the Stack object. |
| Module | string |
Module related to strings in trace. See the String object. |
| Package | trace |
Module related to the execution trace. See the Trace object. |
| Package | types |
Contains classes and instances related to the description of data types. |
| Module | util |
Module that provide util functions |
From the __init__.py module:
| Variable | __version__ |
Undocumented |