Working with OS Specific Information (OSSI)

One very important aspect of analyzing a scenario's trace involves mapping the low level transitions in the trace to higher level OS Specific Information (OSSI) such as binary names and symbol names.

VM Requirements

  • Supported OS: Windows 64bits
    • CompactOS option: disabled. If the CompactOS option is enabled, the VM Prepare process required to retrieve the binary information will fail.
    • KPTI protections: disabled. If KPTI protections are enabled, OSSI will be available only on ring 0 or admin processes.

See the VM Creation page on how to disable these options.

Obtaining OSSI for a scenario

For Microsoft Windows systems, OSSI can be derived from binaries and Program Data Base files, also known as PDBs.

Therefore, obtaining OSSI for a scenario involves:

  1. Defining remote PDB sources for REVEN.
  2. Preparing the VM snapshot used for the scenario.
  3. Downloading PDBs.

Defining PDB sources

Local PDB store

When deriving OSSI, REVEN v2 can look up PDBs from a local PDB store. This store is defined in the settings.py or quasar.py configuration files:

# The storage for symbol files (PDBs), to pass to REVEN
QUASAR_SYMBOL_STORE = str(Path.home() / Path(".local") / Path("share") / Path("reven") / Path("symbols"))

The store is common to all the scenarios of a REVEN v2 installation. The default store path is ~/.local/share/reven/symbols.

The PDB store structure respects the following format:

<PDB filename>/<GUID><AGE>/<PDB filename>

example:

 E1G6032E.pdb
 └── 226C50445B4C4416AF88ED42E0BA63221
     └── E1G6032E.pdb
acpi.pdb
 └── 3F854976E9FE4734BBB19FD05B5543D11
     └── acpi.pdb
d3d10warp.pdb
 └── 257F5B0C541C4853B1D1CCC44655DB271
     └── d3d10warp.pdb
fltMgr.pdb
 └── 620A988036C34BAFAD3FA05B3C5E27FF1
     └── fltMgr.pdb
hal.pdb
 └── 81C1AF690083498BA941D5EC628CDCF41
     └── hal.pdb
i8042prt.pdb
 └── 2514B510EC2475DF4224FA4436871A131
     └── i8042prt.pdb
ndis.pdb
 └── C3E365B8B9DA0007DB598464D3B858CC1
     └── ndis.pdb
ntdll.pdb
 └── 4E4F50879F8345499DAE85935D2391CE1
     └── ntdll.pdb
ntfs.pdb
 └── EFB9533DBFF64A4886FB2D975BDBB1101
     └── ntfs.pdb
ntkrnlmp.pdb
 ├── 0DE6DC238E194BB78608D54B1E6FA3791
 │   └── ntkrnlmp.pdb
 ├── 23CA40E78F5F4BF9A6B2929BC6A5597D1
 │   └── ntkrnlmp.pdb
 ├── 2980EE566EE240BAA4CC403AB766D2651
 │   └── ntkrnlmp.pdb
 └── 83DB42404EFD4AB6AFB6FA864B700CB31
     └── ntkrnlmp.pdb

NOTE: Modifying the configuration files requires stopping and starting the Project Manager.

Remote PDB servers

PDBs can be downloaded:

  • Explicitly from the Program Manager .
  • Transparently while:
    • Preparing a VM Snapshot's OSSI.
    • Analyzing a scenario in Axion.

PDBs are downloaded from a configured list of PDB servers, based on the binaries present in a VM's Snapshot file system.

The list of PDB servers is defined in the settings.py or quasar.py configuration files. For example:

# The list of symbol servers to pass to REVEN
QUASAR_SYMBOL_SERVERS = [
    "https://msdl.microsoft.com/download/symbols",
]

By default, the list is empty.

Downloaded PDBs are stored the local PDB store.

NOTE: Modifying the configuration files requires stopping and starting the Project Manager.

Preparing a VM snapshot

The Prepare task will:

  • Extract the VM snapshot's file system.
  • Build kernel specific information used to derive memory mappings.

In the Project Manager,

  1. Browse to the VM manager tab, then to a VM in the list, then to a snapshot.
  2. Click on the Prepare button.
  3. You can monitor and control the Prepare task in the Tasks & Sessions tab.

WARNING:

  • Extracting a VM's file system requires about three times its size of available disk space.
  • For a Microsoft Windows 10 VM, the file system is about 40GB large, meaning you will need about 120GB of free space to perform that operation.
  • Binary files whose path is longer than 256 characters will not be extracted.

Learn more about Snapshots statuses after a Prepare operation.

Downloading PDBs

The downloading of PDBs can be done in 3 ways:

  • Explicitly from the Program Manager:

    1. Browse to the VM manager tab, then to a VM in the list, then to a snapshot.
    2. Click on the Download PDB files button.
    3. You can monitor and control the PDB download task in the Tasks & Sessions tab.
  • Transparently while:

    • Preparing a VM Snapshot's OSSI.
    • Analyzing a scenario in Axion.

If Enable live PDB download in the scenario's analysis page is checked, each time a new binary is accessed during the analysis, REVEN will try to download his PDBs if not in the local PDB store. Be careful, depending on the network and the size of the PDB, the downloading could last from some seconds to minutes. Axion will be freezed during this time.

  • Manually, you can use the bin/rabin2 tool provided with REVEN v2.
RABIN2_PDBSERVER="<pdb server>" RABIN2_SYMSTORE="<path to the local PDB store>" bin/rabin2 -PP "<binary file>"