reven.api module documentation

Part of reven

The REVEN python API.

Provide a pythonic way to interact with a Reven project. This mainly provides an object oriented wrapper on the low level api, plus a few helper functions to make REVEN scripting more straightforward. A minimal caching mechanism is also implemented under the hood but it should be completely transparent for the interface users.

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

>>> import reven
>>> p = reven.Project('localhost', 13370)

About properties

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

About cache

Unless otherwise documented, API objects are "cached", meaning that their values are fetched from the server once at their initialization, and are immutable afterward.

While caching usually results in consistent behavior (and of course much better performance), it can occasionally produce surprising effects.

For instance, the static comment of an Instruction is retrieved during the initialization of the Instruction instance, meaning that it won't be updated for a particular instance of an Instruction, even if another user sets the comment to another value. If you need to work with fresher values, you usually have to refresh your connection by using the Project.refresh methods, and then recreate all instances of other objects from this refreshed connection.

Missing native api binding

A few low-level objects are not exposed yet:

  • absic to tsc conversion service.
  • Strings related services.

Use the reven_api module to use those objects.

Changelog

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

1.4.4

1.4.2

1.4.1

  • API changes: Instruction.comment, BasicBlock.comment and Point.comment are no longer properties, but methods. Their respective setters are now Instruction.set_comment, BasicBlock.set_comment and Point.push_comment.
  • The new methods Instruction.set_comment and BasicBlock.set_comment can now throw a ConcurrentAccessException if the cache of the Instruction or BasicBlock instance is not fresh. This prevents accidental loss of data.
  • New method Trace.sequence_length to retrieve the number of instructions in a given sequence.
  • Added an optional argument segment to all Memory.read_xx methods. This argument, when specified, allows to override the segment of the memory used to resolve the logical address.
  • Replaced the Memory.segment property with a Memory.default_segment property that can now only be set in constructor.
  • Added an optional argument default_segment to Point.memory.
  • Major API change Project: the connected property has been removed in favor of a Project.is_connected() method.
  • API change on Trace.search_point: the cojunction parameter has been renamed to conjunction.
  • Comparison operators for Point now raise a ValueError when the user attempts to compare two points from different traces. Previously, this would always return True or False, depending on the operator, which would lead to logical errors (such as p1 > p2 and p2 > p1 being True).
  • Instruction.operand now returns None consistently when there is no operand to return (previously returned '' in some cases).
  • In ExecutionProgress: An instance is now guaranteed to represent the progress as it was at the instance's creation. Previously in some rare cases the instance would instead reflect the current progress of the server.
  • In DeviceAccess: port, is_port, is_write are now properties
  • In Memory: read_{u8, i8, u16, i16, u32, i32, u64, i64, f32, f64} are new methods
  • Addition of the new class Device.PortRange.
  • In Device, change the return value of the method ports from a reven_api.port_range object to a Device.PortRange object.
  • In Criterion, rename method reven_effect to _rvn_effect.
  • In Criterion and inherited classes: rename reven_criterion to _rvn_criterion.
  • Change of the return value of the method Memory.search.
  • In AddressSpace.Segment, rename the property address to offset.
  • In AddressSpace and inherited classes, set segments as a property.
  • In AddressSpace and inherited classes, the property segments returns a list instead of a generator.
  • In FileAddressSpace, the constructor's first parameter type is changed to a list of Memory.Segment.
  • In ProcessAddressSpace, set file_address_spaces as a property.
  • In ProcessAddressSpace, the property file_address_spaces return a list instead of a generator.
  • In ProcessAddressSpace, remove the unused constructor's parameter project.
  • In DeviceAddressSpace, remove the unused constructor's parameter project.
  • In Binary, remove the unused constructor's parameter project.
  • In Binary, the property mappings return a dictionary instead of a generator.
  • New method Project.refresh to manually refresh the cache.
  • Project.process_switches now correctly returns the list of process switches. Previously, the first element of the list was a fake process switch at the point Execution_run#0_0.

1.4.0

  • Bumped version: it will now follow REVEN's.
  • Add RegisterAccessPointIterator and MemoryAccessPointIterator to iterate over Points accessing a register or a memory.
  • In MemoryAccess: prefixed boolean properties with `is_`, added content and is_read properties.
  • In ExecutionProgress: fixed last_point_index, added is_done and is_awaiting_configuration
  • Added Inspectors for proper Project start_execution implementation.
  • The Project errors method was renamed into logs.
  • The Project logs method returns a list of tuple instead of a dict of list of tuple.
  • In Report: add point, binary_name, type and remove misleading cwe_*. Bind Severity and Type.
  • Make the search_memory_access trace independent and move it out of Trace and into Project.
  • Change Trace taint method, it now returns the new type Taint and support propagation count limit.
  • Add a parameter to search_symbol that allow to filter on renamed symbol.
  • Parameters of BinaryCriterion and SymbolCriterion have changed from regexp to pattern, accuracy and case_sensitive.
  • Replace mapping by mappings in Binary. mappings returns a FileAddressSpace by process where the binary is mapped.
  • Modification of the type of Binary's symbol from vector of string to vector of Symbol.
  • Replacement of Chunk by Segment in AddressSpace that represent a named contiguous part of memory.
  • Replace Chunks by segments in AddressSpace and child.
  • Modification of Symbol.
  • Addition of map_memory_segment_into_process and add_symbols_to_binary of Project.
  • Remove base from AddressSpace.
  • Rename __contains__ to contains in AddressSpace.
  • Add base_address, vma_to_rva and vma_from_rva to FileAddressSpace.
  • Add file_address_spaces to ProcessAddressSpace.
  • Add cr3 to Process.
  • Add closest_symbol to Binary.
  • Add read_string and read_wstring to Memory
  • Add name property to SymbolicPhysicalMemory

0.0.1 - 2016-04-01 (with REVEN 1.3.0)

  • Initial release
Class ConcurrentAccessError Occurs when a modification to a shared resource is attempted, if another connection already modified the resource since the cache was last refreshed.
Class TaintDiff A taint propagation diff. It stores which elements either gain or loss the taint.
Class Taint The result of a taint propagation on a trace.
Class Criterion Criterion base class. Shouldn't be instanciated.
Class AddressCriterion Criterion object to select addresses.
Class BinaryCriterion Criterion object to select binaries.
Class SymbolCriterion Criterion object to select symbols.
Class DeviceCriterion Criterion object to select devices.
Class Report A report given by inspectors about an execution. Can signal: - potential bugs detected in the trace (such as *use-after-free*s). - *execute-after-write*s
Class FrameBuffer Video framebuffer information.
Class AddressSpace Abstract representation of a non-contiguous memory region.
Class FileAddressSpace An address space representing memory mapped files.
Class ProcessAddressSpace An address space representing the memory of a process.
Class DeviceAddressSpace An address space representing a device physical memory.
Class Binary Executable file information.
Class Process A running process.
Class ProcessSwitch A process switch during an execution.
Class Device A hardware device with port and memory ranges.
Class DeviceAccess A hardware device access. Represents either a read or write access to a port or physical memory.
Class Symbolic Base class for symbolic objects.
Class SymbolicRegister A CPU register symbolic representation.
Class SymbolicPhysicalMemory No class docstring; 3/5 methods documented
Class Symbol A symbol inside a binary.
Class Instruction A basic block instruction.
Class BasicBlock A block of uninterrupted instructions.
Class Memory This object represents the state of memory at a specified trace point.
Class MemoryAccess Represents memory access triggered by either the CPU or a device (mmio).
Class Cpu Represents the state of the CPU at some Point in the Trace.
Class Point A point in a trace.
Class RegisterAccessPointIterator Iterator on points accessing given register (read or write) from a Point.
Class MemoryAccessPointIterator Iterator on points accessing some given memory (read or write) from a Point.
Class Sequence Wrapper for reven_api.sequence_in_run.
Class Trace A trace is the list of all executed sequences. The Trace concept wraps the Run concepts used in axion and the low-level API.
Class Save A saved project.
Class ExecutionProgress Execution progress.
Class InspectorMemoryHistory This inspector tracks the history of all memory accesses. Activating it is highly recommended.
Class InspectorExecutionsAfterWrite This inspector tracks executions of the memory addresses that have been written to, to detect *execute-after-write* like in self-modifying code. It requires inspector memory_range_history.
Class InspectorAlterExecution This inspector alters the program's execution.
Class InspectorStopExecution This inspector stops the execution at a certain configured point.
Class InspectorStringHistory This inspector will collect information about string that have been manipulated during the execution.
Class Project A reven project. This is the root api object.
API Documentation for reven, generated by pydoctor at 2018-06-06 16:31:21.