reven2.ossi.ossi.Ossi

class documentation

class Ossi:

View In Hierarchy

Root object for OSSI information

It provides interface to get useful information about OSSI for:

  • the whole trace like executed binary.
  • for a particular context.

Warnings

Must not be directly constructed but retrieved through the following examples.

Examples

>>> # From a reven_server
>>> ossi = reven_server.ossi
Method __init__ Undocumented
Method __repr__ Undocumented
Method executed_binaries Get a generator over binaries that are executed in the trace.
Method executed_processes Get a generator over processes that are executed in the trace.
Method os Returns the reven2.ossi.os.Os of the trace.
Method symbols Get a generator over symbols of executed binaries.
Instance Variable _data_source Undocumented
def __init__(self, _data_source):

Undocumented

Parameters
_data_source:DataSourceUndocumented
def __repr__(self):

Undocumented

Returns
strUndocumented
def executed_binaries(self, pattern=None):

Get a generator over binaries that are executed in the trace.

Executed binaries can be filtered by their path:

  • filter enabled if the `pattern` argument is not None.
  • a `contains` approach is used.
  • the filtered pattern is a regular expression.
  • is case insensitive.

Warnings

It depends on the binary ranges resource. If unavailable, an exception will be raised.

Examples

>>> # Get all executed binaries
>>> for binary in ossi.executed_binaries():
...     print(binary.path)
c:/windows/system32/ntoskrnl.exe
c:/windows/system32/ntdll.dll
...

>>> # Get all executed binaries filtered by "ntdll"
>>> for binary in ossi.executed_binaries("ntdll"):
...     print(binary.path)
c:/windows/system32/ntdll.dll

>>> # Get all executed binaries filtered by "system32/.*.dll"
>>> for binary in ossi.executed_binaries("system32/.*.dll"):
...     print(binary.path)
c:/windows/system32/ntdll.dll
...

Information

Parameters
pattern:_Optional[str]the pattern used to filter binaries.
Returns
_Iterator[Binary]A generator of reven2.ossi.Binary instances.
Raises
RuntimeErrorif binary ranges resource is unavailable.
def executed_processes(self, pattern=None, pid=None):

Get a generator over processes that are executed in the trace.

Executed processes can be filtered by their name and/or their pid:

  • filter enabled if the `pattern` argument is not `None`, or `pid` argument is not `None`
  • to filter by their name, a `contains` approach is used.
  • the filtered pattern is a regular expression and case insensitive.

Warnings

It depends on the ossi ranges resource. If unavailable, an exception will be raised.

Examples

>>> # Get all executed processes
>>> for binary in ossi.executed_processes():
...     print(process)
cmd.exe (2716)
ShellExperienceHost.exe (2044)
svchost.exe (876)
conhost.exe (2596)
...

>>> # Get all executed process filtered by name "host"
>>> for process in ossi.executed_processes("host"):
...     print(process)
ShellExperienceHost.exe (2044)
svchost.exe (876)
conhost.exe (2596)
...

>>> # Get all executed processes filtered by pid 2596
>>> for binary in ossi.executed_processes(pid=2596):
...     print(binary.path)
conhost.exe (2596)

Information

Parameters
pattern:_Optional[str]the pattern used to filter processes.
pid:_Optional[int]the pid used to filter processes.
Returns
_Iterator[_Process]A generator of reven2.ossi.Process instances.
Raises
RuntimeErrorif ossi ranges resource is unavailable.
def os(self):

Returns the reven2.ossi.os.Os of the trace.

Examples

Displaying the current OS

>>> print(server.ossi.os())
Windows x64 10.0 (Windows 10)

Checking that the OS is either Windows 7 or Windows 8

>>> server.ossi.os().expect(reven2.ossi.Os(windows_version=reven2.ossi.WindowsVersion.Windows7),
...                         reven2.ossi.Os(windows_version=reven2.ossi.WindowsVersion.Windows8))
raised OsError: Got 'Windows 10', expected one of: 'Windows 7', 'Windows 8'

Checking that the OS is 64-bit

>>> server.ossi.os().expect(reven2.ossi.Os(architecture=reven2.ossi.Architecture.X64))

Doing something different depending on the OS

>>> os = server.ossi.os()
>>> os.expect(reven2.ossi.Os(family=reven2.ossi.OsFamily.Linux))
>>> if os.kernel_version.major == 4:
...    # do something with a kernel 4.x
...    pass
... elif os.kernel_version.major == 5:
...    # do something with a kernel 5.x
...    pass
... else:
...    raise reven2.ossi.OsError(got=os, message="Expected kernel major version 4 or 5")
Returns
_OsUndocumented
def symbols(self, pattern=None, binary_hint=None, case_sensitive=False):

Get a generator over symbols of executed binaries.

Symbols can be filtered by:

  • the name:
    • filter enabled if the `pattern` argument is not None.
    • a `contains` approch is used.
    • the filter pattern is a regular expression.
    • case sensitive depending on the `case_sensitive` argument
  • the executed binary's path.
    • filter enabled if the `binary_hint` argument is not None.
    • a `contains` approach is used.
    • the filter pattern is a regular expression.
    • is case insensitive.

Symbols are fetched from the binary file itself and its related debug file, if any.

Warnings

It depends on the binary ranges resource and OSSI feature. If one of them is unavailable, an exception will be raised.

If a binary file is not accessible from the provided filesystem, no symbols will be returned for that binary.

Examples

>>> # Get all symbols
>>> for symbol in ossi.symbols():
...     print('{} - {}'.format(symbol.name, symbol.binary.path))
NetWkstaGetInfo - c:/windows/system32/wkscli.dll
NetUseEnum - c:/windows/system32/wkscli.dll
NetGetJoinInformation - c:/windows/system32/wkscli.dll
...

>>> # Get all symbols filtered by name
>>> for symbol in ossi.symbols("acpi"):
...     print('{} - {}'.format(symbol.name, symbol.binary.path))
HalpAcpiGetTableFromBios - c:/windows/system32/hal.dll
...
PopFxFindAcpiDeviceByUniqueId - c:/windows/system32/ntoskrnl.exe
...
ACPIDispatchIrp - c:/windows/system32/drivers/acpi.sys
...

>>> # Get all symbols filtered by name and binary path
>>> for symbol in ossi.symbols("acpi", binary_hint="acpi.sys"):
...     print('{} - {}'.format(symbol.name, symbol.binary.path))
ACPIDispatchIrp - c:/windows/system32/drivers/acpi.sys
...

>>> # Get all symbols filtered by name in a case sensitive way
>>> for symbol in ossi.symbols("acpi", case_sensitive=True):
...     print('{} - {}'.format(symbol.name, symbol.binary.path))
HalacpiIrqTranslateResourcesIsa - c:/windows/system32/hal.dll
HalacpiIrqTranslateResourceRequirementsIsa - c:/windows/system32/hal.dll
...

Information

Parameters
pattern:_Optional[str]a regular expression used to compare symbols.
binary_hint:_Optional[str]a regular expression used to compare binaries's path.
case_sensitive:boolWhether the symbols comparison is case sensitive or not.
Returns
_Iterator[Symbol]A generator of reven2.ossi.Symbol instances.
Raises
RuntimeErrorif binary ranges resource is unavailable.
RuntimeErrorif OSSI feature is unavailable.
_data_source =

Undocumented