reven2

package documentation

The Reven 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.14.0

2.13.0

  • Add a file `py.typed` to inform that the reven2 package is typed

2.12.0

2.11.0

2.10.2

2.10.1

  • Add Type.to_bytes method to convert a value of a type to bytes.

2.10.0

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

2.6.0

2.5.0

2.4.0

  • No changes

2.3.0

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
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 filter Module related to trace filter. See the Trace object.
Module framebuffer This module contains the Framebuffer type used to acces the framebuffer and take screenshots from the trace.
Module memhist No module docstring; 0/1 variable, 0/10 function, 3/3 classes documented
Module memory_range This module contains the MemoryRange type that model a range of memory addresses, and related types.
Package ossi Package related to OSSI information. See the OssiContext object.
Module prelude This is the prelude module of the Reven python API
Package preview Contains subpackages and modules whose API is not considered stable yet.
Module register_slice This module contains the RegisterSlice type that models a bitwise-slice of a register.
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 __init__.py:

Variable __version__ Undocumented
__version__: str =

Undocumented