Chapter 2 - Registry Parsing

Section 2.1 - Opening a Hive

Using the yarp library to open Windows registry hives using a class structure that is very portable and flexible.

Example Usage:

$ python yarp_base.py {NTUSER HIVE}

References:

Opening a Registry Hive

This class demonstrates how to open a registry hive file with the yarp tool. This library not only allows us to open a single offline hive, but also leverage any available transaction logs to include additional information otherwise available on the Window’s system. This class handles both the opening of the primary hive and attempted recovery of the transaction logs.

class RegistryBase:
    """Base class containing common registry parsing code. Will open a hive
    and attempt recovery using available transaction logs"""

    def __init__(self, reg_file):
        """Base __init__ method, responsible for opening a hive."""
        self.reg_file = reg_file
        self.tx_log_files = []
        self.hive = None
        self._open_hive()

    def _open_hive(self):
        """Open a registry hive with yarp. Must be an open file object with read
        permissions. Will attempt to recover the hive with transaction logs if
        present.
        """
        self.hive = Registry.RegistryHive(self.reg_file)
        self._recover_hive()

    def _recover_hive(self):
        """Search for transaction logs and attempt recovery of the hive."""
        hive_path = self.hive.registry_file.file_object.name
        tx_logs = RegistryHelpers.DiscoverLogFiles(hive_path)
        self.tx_log_files = []
        for tx_path in ["log_path", "log1_path", "log2_path"]:
            log_obj = None
            if getattr(tx_logs, tx_path, None):
                log_obj = open(getattr(tx_logs, tx_path), "rb")
            self.tx_log_files.append(log_obj)
        self.hive.recover_auto(*self.tx_log_files)

    def close(self):
        """Properly close a hive."""
        self.hive = None
        self.reg_file.close()
        for log in self.tx_log_files:
            if log:
                log.close()

Docstring References

class RegistryBase(reg_file)

Base class containing common registry parsing code. Will open a hive and attempt recovery using available transaction logs

close()

Properly close a hive.

Section 2.2 - Parsing Hive Values

Using the yarp library to parse NTUSER.DAT Windows registry hives using a class structure that is very portable and flexible. Parses the MountPoints2 and TrustRecords keys for with string and binary values.

Example Usage:

$ python yarp_ntuser.py {NTUSER HIVE}

References:

Creating a Hive Specific Parser

Since we have a strong base class providing functionality to open hives, we can build hive specific parsing classes that are tailored to handle artifacts distinct to a single hive type. In this case we set up a class to handle NTUSER.DAT files, though could get more specific on Windows versions, etc. In this class we store a few useful details including fixed values used by other methods and metadata about the class.

    def __init__(self, reg_path):
        super().__init__(reg_path)
        self.hive_type = "NTUSER.DAT"
        self.macro_enabled_val = 2147483647

Reading Hive String Values

With an open hive, we can begin to parse values from a known key location within the hive. This method allows us to specify a key path and inspect each of the sub-keys. For each of the sub-keys, we can then get the names and data associated with each value in the key. Additionally we could - if needed - continue to recurse on sub-keys here. Instead we return this cursory information for the caller to display as they wish. Since the values within MountPoints2 store string data, we don’t need to perform further parsing of the record.

    def parse_mount_points2(self):
        """Demonstration of parsing values from a key by path."""
        key_path = (
            "Software\\Microsoft\\Windows\\CurrentVersion"
            "\\Explorer\\MountPoints2"
        )
        for mp in self.hive.find_key(key_path).subkeys():
            yield {
                "name": mp.name().replace("#", "\\"),
                "values": {x.name(): x.data() for x in mp.values()},
                "last_written": mp.last_written_timestamp(),
            }

Reading Hive Binary Values

Similarly to our prior example, we can get a key by path. In this case we don’t have a sense of what Office versions are available in the key and have elected to iterate through each of those using the parse_office_versions() method. Using each of the versions, we then access the respective TrustRecords key. If found, we then parse the binary data (retrieved with the same .data() method) using Struct to extract a timestamp and integer marking whether a trusted macro was used. These parsed attributes are then returned to the caller to be displayed.

    def parse_trust_records(self):
        """Demonstration of parsing binary values within a key."""
        trust_record_path = (
            "Software\\Microsoft\\Office\\{OFFICE_VERSION}"
            "\\Word\\Security\\Trusted Documents\\TrustRecords"
        )
        for office_version in self.parse_office_versions():
            trust_rec_key = self.hive.find_key(
                trust_record_path.format(OFFICE_VERSION=office_version)
            )
            if not trust_rec_key:
                continue

            for rec in trust_rec_key.values():
                date_val, macro_enabled = struct.unpack("q12xI", rec.data())
                ms = date_val / 10.0
                dt_date = datetime(1601, 1, 1) + timedelta(microseconds=ms)
                yield {
                    "doc": rec.name(),
                    "dt": dt_date.isoformat(),
                    "macro": macro_enabled == self.macro_enabled_val,
                }

Docstring References

class NTUSER(reg_path)

Class to handle the parsing of the NTUSER.DAT hive.

parse_mount_points2()

Demonstration of parsing values from a key by path.

parse_office_versions()

Get Office versions within an open Registry hive.

Yields

(str) – Office version number (ie. ‘15.0’)

parse_trust_records()

Demonstration of parsing binary values within a key.

Indices and tables