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(). To make this distinction clearer in our documentation, the documentation for a property always starts with the keyword Property: (e.g., see the properties
Every notable changes to this api will be documented in this file.
Symbol.namechanged: 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 (
reven2.address.LogicalAddressSegmentIndexinstance now displays as a clickable link that instructs Axion to open a hexdump widget for that address in Jupyter Notebook.
reven2.session.Sessions.publish_addressmethod to publish an address to clients like Axion.
trace.Modeclass that indicates the current mode.
CPUExceptionare now faster to fetch back from the server: up to 5x faster in some workloads.
Ossi.executed_processesmethod to get the processes executed in the trace. Currently this feature will return results only for windows.
Trace.filterto iterate on contexts that match filter policies. Currently process policies and ring policy are available.
preview.prototypespackage containing basic parsing of C function prototypes
BackTraceclass have been deprecated and are scheduled for removal in version 2.10. Use
Stackinstance to display the backtrace.
reven2.Trace.memory_accessesmethod now supports fetching memory accesses on the entire trace or between 2 transitions without specifying an address range.
Instructions were displayed without their prefixes.
Instruction.operandsmethods may have changed from previous versions. See the release notes for more detailed information about the changes.
TaintResultView.filter_by_context_rangefunctions has been modified in the way the
to_contextparameter is handled. Previously, the taint would not propagate through the
Transitionright before the
to_contextparameter. With this change, it is now the case. This means that a simple taint between context
c + 1will now propagate through the transition between context
cand its successor context, whereas before it would propagate through no context at all.
Context.find_register_changecould loop infinitely when invoked in backward.
Context.find_register_changecould skip changes depending on the value of the
None(its default value).
reven2now only support Python 3.7+.
TaintAccess.state_afterwould sometimes raise a StopIteration Exception.
Tainter.simple_taintwould mistakenly share the same taint data.
Taint.accessesfor querying all the transitions that touch the tainted data. Can be filtered to query only the transitions that change taint state (like
Taint.changesas deprecated. Use
TaintResultView.take_nmethod would sometimes return the wrong number of results.
Search.memoryto search byte patterns throughout the whole trace
TaintedRegisterSlicewould sometimes take the entire register instead of the requested slice
reven2.bookmarkmodule that allows to programmatically add, access, edit and remove bookmarks.
reven2.address.LogicalAddressSegmentIndex.translateto translate the virtual address into
reven2.trace.Transition.find_inversemethod to get the transition that performs the
inverseoperation to the given transition.
reven2.trace.Context.find_register_changemethod to find the next/previous context in which the content of the requested register is modified.
reven2.sessionmodule that allows to publish various events to clients like Axion.
reven2.RevenServer.sessionsproperty that lists the sessions tracked by the RevenServer.
reven2.RevenServer.connectnow accept an additional keyword parameter 'sessions' to set the tracked sessions
reven2.trace.Transitioninstance now displays as a clickable link that instructs Axion to select that transition in Jupyter Notebook.
ProjectManager.connectto connect to a REVEN project from its name
ossi.OssiContext.processto get the information of the current
Instructionobject would sometimes contain wrong operands for relative
Context.readmethod up to x3 in typical workloads
timeoutargument to the
String.memory_accessesmethod, allowing to specify how long this function should attempt to recover all accesses before raising an exception.
Stack.backtraceproperty so that it returns a string instead of printing it.
ifregister accessible from the API. Previously, attempting to access
reven2.arch.x64.ifwould raise a
ifis a python keyword. You can now access the
tracepackage containing basic classes to navigate in a trace and inspect cpu registers and memory
searchmodule containing basic objects to search interesting points in a trace
trace.Transition.memory_accessesto query memory accesses from the trace
stackmodule containing basic objects to get interesting information on the stack like the backtrace
stringmodule containing a basic `String` object to get interesting strings in the trace and their memory accesses
ossipackage containing basic objects to get Operating System Semantic Information (OSSI)
typespackage containing various predefined types and type constructors
archpackage containing the various x86_64 registers
addresspackage containing representation of memory addresses
preview.project_managerpackage containing basic (incomplete) bindings to the REVEN project manager REST API
preview.taintpackage containing an experimental, simplified API for the taint
||Defines memory address classes|
||Contains classes and instances related to the description of the machine architecture.|
||No module docstring; 2/3 classes documented|
||Module related to trace filter. See the
||No module docstring; 3/3 classes, 0/10 functions, 0/1 variables documented|
||Package related to OSSI information. See the
||This is the prelude module of the Reven2 python API|
||Contains subpackages and modules whose API is not considered stable yet.|
||Module related to trace search. See the
||No module docstring; 7/8 classes documented|
||Module related to sessions, that allow to publish information to various other connected clients (e.g., Axion).|
||Module related to stack. See the
||Module related to strings in trace. See the
||Module related to the execution trace. See the
||Contains classes and instances related to the description of data types.|
||Module that provide util functions|