class documentation

class Transition(object):

Entry point object for data related to a transition.

A transition is anything that changes the state of the virtual machine, from `context_before` to `context_after`. Most of the time, that would be an instruction executed by the CPU. Sometimes, it will be an exception (CPU fault or IRQ) instead. In that case, an instruction might still be related to the exception, if for instance it is the source of the fault. In that case, the instruction has not been fully executed by the CPU.

Warnings

This object is not meant to be constructed directly. Use Trace.transition instead.

Examples

Spawning: >>> # From a trace >>> tr = reven_server.trace.transition(id) >>> >>> # From a context >>> tr = context.transition_before(transition_id) >>> >>> # From a transition >>> tr = reven_server.trace.transition(id) >>> next_tr = tr + 1 >>> prev_tr = tr - 1 >>> other_tr = tr + 10000

Usage: >>> print(tr) >>> if tr.type == TransitionType.Instruction: >>> print(tr.instruction)

Method	`__init__`	Undocumented
Property	`id`	Property: Unique ID of this transition.
Property	`type`	Property: The transition's type.
Property	`pc`	Property: The address of the transition.
Property	`mode`	Property: The mode of execution of the transition.
Property	`instruction`	Property: The associated `Instruction` if one exists.
Property	`exception`	Property: The associated `CPUException` if one exists.
Method	`context_before`	Get the Context object before this transition was executed
Method	`context_after`	Get the Context object after this transition was executed
Method	`memory_accesses`	Get a generator over the `reven2.memhist.MemoryAccess`es at this transition.
Method	`find_inverse`	This method is a helper to get the transition that performs the `inverse` operation to this transition.
Method	`step_out`	Step out of the current function.
Method	`step_over`	Step over this transition.
Method	`__str__`	Undocumented
Method	`__repr__`	Undocumented
Method	`format_as_html`	This method gets an html formatting string representation for this class instance.
Method	`__eq__`	Undocumented
Method	`__ne__`	Undocumented
Method	`__lt__`	Undocumented
Method	`__le__`	Undocumented
Method	`__gt__`	Undocumented
Method	`__ge__`	Undocumented
Method	`__add__`	Undocumented
Method	`__sub__`	Undocumented
Instance Variable	`__trace`	Undocumented
Instance Variable	`_data_source`	Undocumented
Instance Variable	`_ossi_data_source`	Undocumented
Instance Variable	`_id`	Undocumented
Instance Variable	`_data_fetched`	Undocumented
Instance Variable	`_context_before`	Undocumented
Instance Variable	`_context_after`	Undocumented
Instance Variable	`_instruction_raw_fetched`	Undocumented
Instance Variable	`_legacy_data_fetched`	Undocumented
Class Variable	`_unique_count`	Undocumented
Class Method	`_unique_id`	Undocumented
Property	`_trace`	Undocumented
Property	`_data`	Undocumented
Property	`_legacy_data`	Undocumented
Property	`_instruction_raw`	Undocumented
Property	`_instruction_str`	Undocumented
Property	`_exception_str`	Undocumented
Method	`_repr_html_`	Representation used by Jupyter Notebook when an instance of the Transition class is displayed in a cell.

def __init__(self, trace, _data_source, _ossi_data_source, transition_id):

Undocumented

__trace =

Undocumented

_data_source =

Undocumented

_ossi_data_source =

Undocumented

_id =

Undocumented

_data_fetched =

Undocumented

_context_before =

Undocumented

_context_after =

Undocumented

_instruction_raw_fetched =

Undocumented

_legacy_data_fetched =

Undocumented

_unique_count =

Undocumented

(type: int)

@classmethod
def _unique_id(cls):

Undocumented

@property
_trace =

Undocumented

@property
id =

Property: Unique ID of this transition.

Can be used to spawn the object from the corresponding `Trace` object.

Information

Returns An integer.

@property
type =

Property: The transition's type.

The type of a transition can be one of the following:

TransitionType.Instruction means this transition is a fully instruction executed.
TransitionType.Exception means this transition is an exception raised by the CPU or a peripheral.

Information

Returns A TransitionType instance.

@property
pc =

Property: The address of the transition.

@property
mode =

Property: The mode of execution of the transition.

@property
instruction =

Property: The associated Instruction if one exists.

If this transition is not of type Instruction of TransitionType, None will be returned.

Information

Returns An Instruction, or None.

@property
exception =

Property: The associated CPUException if one exists.

If this transition is not of type Exception of TransitionType, None will be returned.

Information

Returns An CPUException, or None.

def context_before(self):

Get the Context object before this transition was executed

>>> Context before -> This transition

Information

Returns A Context.

def context_after(self):

Get the Context object after this transition was executed

>>> This transition -> Context after

Information

Returns A Context.

def memory_accesses(self, operation=None):

Get a generator over the reven2.memhist.MemoryAccesses at this transition.

Examples

>>> # Getting all accesses as a list at transition 42 (can be long if there are a lots of accesses):
>>> list(trace.transition(42).memory_accesses())
[MemoryAccess(transition=Transition(id=42), physical_address=PhysicalAddress(offset=0x7fc03eb8), size=8,
    operation=MemoryAccessOperation.Write, virtual_address=LinearAddress(offset=0xffff88007fc03eb8))]

>>> # Getting the first memory access at transition 14
>>> next(trace.transition(14).memory_accesses())
MemoryAccess(transition=Transition(id=14), physical_address=PhysicalAddress(offset=0x1f270a2), size=1,
    operation=MemoryAccessOperation.Read, virtual_address=LinearAddress(offset=0xffffffff81f270a2))

>>> # Getting all addresses that are read at transition 0.
>>> addresses = set()
>>> for access in trace.transition(0).memory_accesses(operation=reven2.memhist.MemoryAccessOperation.Read):
>>>     physical_offset = access.physical_address.offset
>>>     for address in range(physical_offset, physical_offset + access.size)
>>>         addresses.add(address)
>>> for address in addresses:
>>>     print reven2.address.PhysicalAddress(address)
phy:0x36f05080
phy:0x36f05081
phy:0x36f05082
phy:0x36f05083
phy:0x36f05084
phy:0x36f05085
phy:0x36f05086
phy:0x36f05087

Information

Parameters	operation	Only return accesses whose operation equals the specified `reven2.memhist.MemoryAccessOperation`. If None, return all accesses.
Returns	a generator of `reven2.memhist.MemoryAccess`.
Raises	RuntimeError	if the memory history resource has not been generated

def find_inverse(self):

This method is a helper to get the transition that performs the inverse operation to this transition.

Inverse operations

The transition switches between user and kernel land. Examples:

a syscall transition => the related sysret transition
a sysret transition => the related syscall transition
a exception transition => the related iretq transition
a iretq transition => the related exception transition

The transition does memory accesses:

case 1: a unique access. The access is selected.
case 2: multiple write accesses. The first one is selected.
case 3: multiple read accesses. The first one is selected.
case 4: multiple read and write accesses. The first write access is selected. This enable to get the matching ret transition on an indirect call transition e.g. call [rax + 10].

If the selected access is a write then the next read access on the same memory range is searched for.

If the selected access is a read then the previous write access on the same memory range is searched for.

Example find_inverse on:

a call transition => the related ret transition.
a ret transition => the related call transition.
a push transition => the related pop or mov transition.
a pop transition => the related push transition.
a store transition => the related load transition.
a load transition => the related store transition.

Note

Due to the fact that find_inverse matches with memory accesses to find the inverse instruction, in some special cases, such as ROP chain, the inverse of e.g. a ret will not be a call instruction, but could be a mov to the memory, for example.

Dependencies

This method requires that the REVEN2 server have the Memory history enabled.

Usage

It can be combined with other features like backtrace to obtain interesting results.

Example

For example, to jump to the end of the current function:

>>> import reven2
>>> reven_server = reven2.RevenServer('localhost', 13370)
>>> current_transition = reven_server.trace.transition(10000000)
>>> ret_transition = current_transition.find_inverse()

Information

Returns reven2.trace.Transition or None if no inverse found.

def step_out(self, is_forward=True):

Step out of the current function.

Step out forward: exit the current function by returning the transition after the ret.

Step out backward: exit the current function by returning the call transition.

Information

Parameters	is_forward	`bool`, `True` to step out forward and `False` to step out backward
Returns	`reven2.trace.Transition` or `None` if the transition is not in the recorded trace.
Raises	RuntimeError	if the debugger interface is not available.

def step_over(self, is_forward=True):

Step over this transition.

Step over forward:

on a call, skip the function and return the transition after the ret
otherwise return the next transition

Step over backward:

if the previous instruction is a ret, skip the function and return the call transition.
otherwise return the previous transition

Information

Parameters	is_forward	`bool`, `True` to step over forward and `False` to step over backward.
Returns	`reven2.trace.Transition` or `None` if the transition is not in the recorded trace.
Raises	RuntimeError	if the debugger interface is not available.

@property
_data =

Undocumented

@property
_legacy_data =

Undocumented

@property
_instruction_raw =

Undocumented

@property
_instruction_str =

Undocumented

@property
_exception_str =

Undocumented

def __str__(self):

Undocumented

def __repr__(self):

Undocumented

def format_as_html(self):

This method gets an html formatting string representation for this class instance.

Information

Returns String

def _repr_html_(self):

Representation used by Jupyter Notebook when an instance of the Transition class is displayed in a cell.

The transition is returned as a clickable link containing the transition id, that publishes the transition to all tracked reven2.session.Sessions.

def __eq__(self, other):

Undocumented

def __ne__(self, other):

Undocumented

def __lt__(self, other):

Undocumented

def __le__(self, other):

Undocumented

def __gt__(self, other):

Undocumented

def __ge__(self, other):

Undocumented

def __add__(self, other):

Undocumented

def __sub__(self, other):

Undocumented

API Documentation for reven2, generated by pydoctor 21.2.2 at 2021-10-01 07:18:12.