Using PDBs on air-gapped networks

esReven Enterprise edition can be deployed on fully air-gapped networks, where no Internet connection is available. In this situation, the default PDBs servers (Microsoft's and others) the Reven configuration points to will not be accessible, so manual operations are required to retrieve these files.

• Using a locally-accessible PDB server
• Temporarily connecting the server to the Internet
• Retrieving PDBs from a list built by Reven
• About Reven's local PDB store
• A note about mandatory PDBs

Using a locally-accessible PDB server

By default, Reven's configuration points to PDB servers accessible on the Internet. However, it is frequent for users working on an air-gapped network to have their own PDB server accessible over HTTP acting as a mirror for use with tools such as WinDbg or IDA. If such is your case, you can edit the list of PDB server Reven uses, see the documentation about this.

Temporarily connecting the server to the Internet

If you don't have a local PDB mirror, then by far the easiest option is to temporarily connect your Reven instance to the Internet when you add a new VM or install significant software. Here is the general procedure to follow:

1. Open the snapshot's page in the Project Manager (click on the snapshot's name in the VM Manager page)
2. Locate the "Prepare the Snapshot" section at the top.
3. If your snapshot is not yet prepared, click on "Prepare" and wait for the operation to finish.
4. Now connect the Reven server to the Internet
5. Click on "Show advanced", then on "Download PDB files". This will effectively download all possible PDBs from the prepared file system.
6. You can monitor and control the PDB download task in the Tasks & Sessions tab.

Note that if the software you want to analyze can be augmented with PDBs (such as Chrome), make sure it is installed prior to preparing the snapshot. See advanced snapshot management for more information.

Retrieving PDBs from a list built by Reven

Start by applying the same procedure just above but without an Internet connection. Then at the end of the PDB download task you can download a text file named snapshot_name-missing_pdbs.txt by clicking on the Download missing pdb list button. The file contains the list of the PDBs Reven could not successfully download. Copy this file over to an Internet-capable machine and use it to download all PDBs yourself.

The following Python script should help you do that easily:

#!/usr/bin/env python3

import argparse
import urllib.request
from pathlib import Path

PDB_SERVERS = [
    "https://msdl.microsoft.com/download/symbols",
    "https://chromium-browser-symsrv.commondatastorage.googleapis.com/",
    "https://symbols.mozilla.org/",
    # "https://download.amd.com/dir/bin",
    # "https://driver-symbols.nvidia.com/",
    # "https://software.intel.com/sites/downloads/symbols/",
]

parser = argparse.ArgumentParser(prog="PDB downloader")
parser.add_argument(
    "--pdb-list",
    required=True,
    type=Path,
    help="List of missing PDBs, one per line in a file, in the form `<pdb_name>.pdb/<GUID><AGE>/<pdb_name>.pdb`",
)
parser.add_argument(
    "--output",
    default="output",
    type=Path,
    help="Output path to store the PDBs (default: ./output)",
)

args = parser.parse_args()

print("Downloading PDBs from file '%s' into folder '%s'" % (args.pdb_list, args.output))

output = args.output
output.mkdir(exist_ok=True, parents=True)

for pdb in args.pdb_list.read_text().strip().split("\n"):
    pdb = pdb.strip()
    (output / pdb).parent.mkdir(exist_ok=True, parents=True)
    for server in PDB_SERVERS:
        url = server + "/" + pdb
        print(url, end=" - ")
        try:
            urllib.request.urlretrieve(url, output / pdb)
            print("OK")
            break
        except Exception as e:
            print(e)

Usage is as follow: python3 pdb_download.py --pdb-list ./my_snapshot-missing_pdbs.txt --output output

The content of the output folder may be directly copied to your Reven's local PDB store.

Note that the action Download light PDBs from the Scenario Replay page does not generate a missing pdbs file.

About Reven's local PDB store

During normal operation, Reven first looks for PDBs in its local PDB store. This store is common to every scenario of an esReven installation. Therefore, a last resort option on an air-gapped network is to populate the store manually on the server's disk with a set of PDBs that you would have downloaded on an separate network.

The store's path is $DATA/reven/symbols where $DATA is the main storage folder for esReven, as configured in the .env file at the root of the esReven installation.

The store structure respects the following format:

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

example:

hal.pdb
 └── 81C1AF690083498BA941D5EC628CDCF41
     └── hal.pdb
ntdll.pdb
 └── 4E4F50879F8345499DAE85935D2391CE1
     └── ntdll.pdb
ntkrnlmp.pdb
 ├── 0DE6DC238E194BB78608D54B1E6FA3791
 │   └── ntkrnlmp.pdb
 ├── 23CA40E78F5F4BF9A6B2929BC6A5597D1
 │   └── ntkrnlmp.pdb
 ├── 2980EE566EE240BAA4CC403AB766D2651
 │   └── ntkrnlmp.pdb
 └── 83DB42404EFD4AB6AFB6FA864B700CB31
     └── ntkrnlmp.pdb

This structure is exactly the same as Microsoft's PDB store, and makes it easy to merge two PDB sets together.

A note about mandatory PDBs

While in general PDBs are only used for displaying more debug symbols when analyzing a binary, certain PDBs are necessary for Reven features. You should really make sure they are available if you download PDBs manually.

NOTE: Having the right PDB for the kernel being run is mandatory for anything related to OSSIs in Reven. There must be an exact GUID match between the kernel and its PDB.

NOTE: Outside of the PDBs mentionned in the table above, if a PDB is missing, Reven will simply fetch the symbols available in the PE binary instead.