Entry point object to find interesting points in a trace.

Warnings

This object is not meant to be constructed directly. Use RevenServer.trace.search (Trace.search) instead.

Limitations

The last context of a trace is currently not searchable.

Examples

>>> # From a reven_server
>>> search = reven_server.trace.search
>>>
>>> # search for rip = 0xdeadbeef in the whole trace.
>>> for context in search.pc(0xdeadbeef):
>>>     print(context)
Method __init__ Undocumented
Method symbol Search all contexts where the PC register (RIP on x86-64) is pointing to a symbol.
Method binary Search all contexts where the PC register (RIP on x86-64) is pointing to a binary.
Method pc Search all contexts where the PC register (RIP on x86-64) is equal to an address.
Method _search_range Undocumented
Method _search Undocumented
def __init__(self, _rvn, trace):
Undocumented
def symbol(self, symbol, from_context=None, to_context=None):

Search all contexts where the PC register (RIP on x86-64) is pointing to a symbol.

A valid `ossi.Symbol` object must be given. To get one, use the `Ossi.symbols` method.

Warnings

Depends on the fast search resources (Binary ranges and PC ranges). If one of them is not available, an exception will be raised.

Limitations

The last context of a trace is currently not searchable.

Examples

>>> # Search for symbol "CreateProcessW" in binary "kernelbase.dll"
>>> for symbol in reven_server.ossi.symbols('^CreateProcessW$', binary_hint='kernelbase\.dll'):
>>>     for ctx in trace.search.symbol(symbol):
>>>         print(ctx)
Context before #23886919
Context before #1370448535
Context before #2590849986
>>> # Search for symbol "CreateProcessW" in binary "kernelbase.dll" until context before transition 25000000
>>> for symbol in reven_server.ossi.symbols('^CreateProcessW$', binary_hint='kernelbase\.dll'):
>>>     for ctx in trace.search.symbol(symbol, to_context=trace.context_before(25000000)):
>>>         print(ctx)
Context before #23886919
>>> # Search for all symbol symbols that contains "acpi"
>>> for symbol in reven_server.ossi.symbols('acpi'):
>>>     for ctx in trace.search.symbol(symbol):
>>>         print(ctx)
Context before #1471900961
Context before #1471903808
Context before #1471908093
Context before #1471914935
Context before #1472413834
Context before #1472416173
Context before #1472419063
...

Information

Parameterssymbolthe symbol to search. Must be a `reven.ossi.Symbol`.
from_contextThe context from where the search starts. If None, search from the first context in the trace.
to_contextThe context where the search ends. This context is excluded from the search. If None, search until the last context in the trace.
ReturnsA generator of trace.Context instances.
RaisesTypeErrorif `symbol` is not a `reven.ossi.Symbol`.
TypeErrorif `from_context` or `to_context` are not None and not a `reven.trace.Context`.
ValueErrorif `to_context` is lower than `from_context`.
RuntimeErrorif binary ranges resource is unavailable.
RuntimeErrorif pc ranges resource is unavailable.
def binary(self, binary, from_context=None, to_context=None):

Search all contexts where the PC register (RIP on x86-64) is pointing to a binary.

A valid `ossi.Binary` object must be given. To get one, use the `Ossi.executed_binaries` method.

Warnings

Depends on the fast seach binary ranges resource. If unavailable, the binary search is still working but in a very slow mode.

Limitations

The last context of a trace is currently not searchable.

Examples

>>> # Search for binary "kernelbase.dll"
>>> for binary in reven_server.ossi.executed_binaries('kernelbase\.dll'):
>>>     for ctx in trace.search.binary(binary):
>>>         print(ctx)
Context before #240135
Context before #240136
Context before #240137
Context before #240138
Context before #240139
Context before #240140
Context before #240141
...
>>> # Search for binary "kernelbase.dll" until context before transition 240138
>>> for binary in reven_server.ossi.executed_binaries('kernelbase\.dll'):
>>>     for ctx in trace.search.binary(binary, to_context=trace.context_before(240138)):
>>>         print(ctx)
Context before #240135
Context before #240136
Context before #240137
>>> # Search for binaries that contains "\.exe"
>>> for binary in reven_server.ossi.executed_binaries('\.exe'):
>>>     for ctx in trace.search.binary(binary):
>>>         print(ctx)
Context before #1537879110
Context before #1537879111
Context before #1537879112
Context before #1537879113
Context before #1537879372
Context before #1537879373
Context before #1537879374
...

Information

Parametersbinarythe binary to search. Must be a `reven.ossi.Binary`.
from_contextThe context from where the search starts. If None, search from the first context in the trace.
to_contextThe context where the search ends. This context is excluded from the search. If None, search until the last context in the trace.
ReturnsA generator of trace.Context instances.
RaisesTypeErrorif `binary` is not a `reven.ossi.Binary`.
TypeErrorif `from_context` or `to_context` are not None and not a `reven.trace.Context`.
ValueErrorif `to_context` is lower than `from_context`.
def pc(self, address, from_context=None, to_context=None):

Search all contexts where the PC register (RIP on x86-64) is equal to an address.

Warnings

Depends on the fast search PC ranges resource. If unavailable, the pc search is still working but in a very slow mode.

Limitations

The last context of a trace is currently not searchable.

Examples

>>> # Search for RIP = 0x7fff57263b2f
>>> for ctx in trace.search.pc(0x7fff57263b2f):
>>>     print(ctx)
Context before #240135
Context before #281211
Context before #14608067
Context before #14690369
Context before #15756067
Context before #15787089
...
>>> # Search for RIP = 0x7fff57263b2f until context before transition 14608067
>>> for ctx in trace.search.pc(0x7fff57263b2f, to_context=trace.context_before(14608067)):
>>>     print(ctx)
Context before #240135
Context before #281211
>>> # Search for RIP = 0x7fff57263b2f from context before transition 14608067
>>> for ctx in trace.search.pc(0x7fff57263b2f, from_context=trace.context_before(14608067)):
>>>     print(ctx)
Context before #14608067
Context before #14690369
Context before #15756067
Context before #15787089
...

Information

Parametersaddressthe address to search. Must be an int-like object.
from_contextThe context from where the search starts. If None, search from the first context in the trace.
to_contextThe context where the search ends. This context is excluded from the search. If None, search until the last context in the trace.
ReturnsA generator of trace.Context instances.
RaisesTypeErrorif `address` is not an `int`.
TypeErrorif `from_context` or `to_context` are not None and not a `reven.trace.Context`.
ValueErrorif `to_context` is lower than `from_context`.
def _search_range(self, from_context, to_context):
Undocumented
def _search(self, criteria, from_context, to_context):
Undocumented
API Documentation for reven2, generated by pydoctor at 2020-06-18 13:59:59.