class documentation

class Transition:

View In Hierarchy

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 __add__ Undocumented
Method __eq__ Compares the instance for equality with an object.
Method __ge__ Undocumented
Method __gt__ Undocumented
Method __hash__ Returns the hash for this value.
Method __init__ Undocumented
Method __le__ Undocumented
Method __lt__ Undocumented
Method __ne__ Compares the instance for equality with an object.
Method __repr__ Undocumented
Method __str__ Returns the nicely printable string representation of this instance.
Method __sub__ Undocumented
Method context_after Get the Context object after this transition was executed:
Method context_before Get the Context object before this transition was executed:
Method find_inverse This method is a helper to get the transition that performs the inverse operation to this transition.
Method format_as_html This method gets an html formatting string representation for this class instance.
Method format_as_html_for_classic_jupyter_notebook This method gets an html formatting string representation for this class instance.
Method memory_accesses Get a generator over the reven2.memhist.MemoryAccesses at this transition.
Method step_out Step out of the current function.
Method step_over Step over this transition.
Property exception Property: The associated CPUException if one exists.
Property id Property: Unique ID of this transition.
Property instruction Property: The associated Instruction if one exists.
Property mode Property: The mode of execution of the transition.
Property pc Property: The address of the transition.
Property type Property: The transition's type.
Class Method _unique_id Undocumented
Method _repr_html_ Representation used by Jupyter when an instance of the Transition class is displayed in a cell.
Class Variable _unique_count Undocumented
Instance Variable __trace Undocumented
Instance Variable _context_after Undocumented
Instance Variable _context_before Undocumented
Instance Variable _data_fetched Undocumented
Instance Variable _data_source Undocumented
Instance Variable _id Undocumented
Instance Variable _instruction_raw_fetched Undocumented
Instance Variable _legacy_data_fetched Undocumented
Instance Variable _ossi_data_source Undocumented
Property _data Undocumented
Property _exception_str Undocumented
Property _instruction_raw Undocumented
Property _instruction_str Undocumented
Property _legacy_data Undocumented
Property _trace Undocumented
def __add__(self, other):

Undocumented

Parameters
other:intUndocumented
Returns
TransitionUndocumented
def __eq__(self, other):

Compares the instance for equality with an object.

  • if the object is not a Transition, returns False.
Parameters
other:_AnyUndocumented
Returns
boolUndocumented
def __ge__(self, other):

Undocumented

Parameters
other:TransitionUndocumented
Returns
boolUndocumented
def __gt__(self, other):

Undocumented

Parameters
other:TransitionUndocumented
Returns
boolUndocumented
def __hash__(self):

Returns the hash for this value.

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

Undocumented

Parameters
trace:TraceUndocumented
_data_source:_data_source.DataSourceUndocumented
_ossi_data_source:_ossi._DataSourceUndocumented
transition_id:intUndocumented
def __le__(self, other):

Undocumented

Parameters
other:TransitionUndocumented
Returns
boolUndocumented
def __lt__(self, other):

Undocumented

Parameters
other:TransitionUndocumented
Returns
boolUndocumented
def __ne__(self, other):

Compares the instance for equality with an object.

  • if the object is not a Transition, returns True.
Parameters
other:_AnyUndocumented
Returns
boolUndocumented
def __repr__(self):

Undocumented

Returns
strUndocumented
def __str__(self):

Returns the nicely printable string representation of this instance.

Returns
strUndocumented
def __sub__(self, other):

Undocumented

Parameters
other:intUndocumented
Returns
TransitionUndocumented
def context_after(self):

Get the Context object after this transition was executed:

    This transition -> Context after

Information

Returns
ContextA Context.
def context_before(self):

Get the Context object before this transition was executed:

    Context before -> This transition

Information

Returns
ContextA Context.
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
_Optional[Transition]reven2.trace.Transition or None if no inverse found.
def format_as_html(self):

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

Information

Returns
strString
def format_as_html_for_classic_jupyter_notebook(self):

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

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

Warning

The link only works using classic Jupyter Notebook. It does not work with the JupyterLab used by esReven.

Information

Returns
strString
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:_Optional[_memhist.MemoryAccessOperation]Only return accesses whose operation equals the specified reven2.memhist.MemoryAccessOperation. If None, return all accesses.
Returns
_Iterator[_memhist.MemoryAccess]a generator of reven2.memhist.MemoryAccess.
Raises
RuntimeErrorif the memory history resource has not been generated
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:boolbool, True to step out forward and False to step out backward
Returns
_Optional[Transition]reven2.trace.Transition or None if the transition is not in the recorded trace.
Raises
RuntimeErrorif 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:boolbool, True to step over forward and False to step over backward.
Returns
_Optional[Transition]reven2.trace.Transition or None if the transition is not in the recorded trace.
Raises
RuntimeErrorif the debugger interface is not available.
@property
exception: _Optional[CPUException] =

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.
@property
id: int =

Property: Unique ID of this transition.

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

Information

Returns
An integer.
@property
instruction: _Optional[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
mode: Mode =

Property: The mode of execution of the transition.

@property
pc: int =

Property: The address of the transition.

@property
type: TransitionType =

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.
@classmethod
def _unique_id(cls):

Undocumented

Returns
strUndocumented
def _repr_html_(self):

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

Returns
strUndocumented
_unique_count: int =

Undocumented

__trace =

Undocumented

_context_after =

Undocumented

_context_before =

Undocumented

_data_fetched: _Optional[_reven_api.TransitionData] =

Undocumented

_data_source =

Undocumented

_id =

Undocumented

_instruction_raw_fetched: _Optional[bytearray] =

Undocumented

_legacy_data_fetched: _Optional[_reven_api.instruction] =

Undocumented

_ossi_data_source =

Undocumented

@property
_data: _reven_api.TransitionData =

Undocumented

@property
_exception_str: str =

Undocumented

@property
_instruction_raw: bytearray =

Undocumented

@property
_instruction_str: str =

Undocumented

@property
_legacy_data: _reven_api.instruction =

Undocumented

@property
_trace: Trace =

Undocumented