Windows: Cleanup devicetree + extension class

Moves a lot of the code that was parsing information about device
objects out of the `DeviceTree` plugin logic and into the
`DEVICE_OBJECT` extension class. Also moved the dict mapping integer
values to device types into the extension module.

Fixes a bug within the extension class' `get_attached_devices` method -
now, immediate children of the device in the tree are yielded, instead
of the faulty deep traversal that was occuring before. Because of this
bugfix in an extension class, this also bumps the framework patch
version number.

Author: dgmcdona

volatility3/framework/constants/_version.py

@@ -1,7 +1,7 @@
 # We use the SemVer 2.0.0 versioning scheme
 VERSION_MAJOR = 2  # Number of releases of the library with a breaking change
 VERSION_MINOR = 23  # Number of changes that only add to the interface
-VERSION_PATCH = 0  # Number of changes that do not change the interface
+VERSION_PATCH = 1  # Number of changes that do not change the interface
 VERSION_SUFFIX = ""
 
 PACKAGE_VERSION = (

volatility3/framework/plugins/windows/devicetree.py

@@ -3,75 +3,14 @@
 #
 
 import logging
-from typing import Iterator, List, Set, Tuple
+from typing import Iterator, List, Set, Tuple, Union
 
 from volatility3.framework import constants, exceptions, interfaces, renderers
 from volatility3.framework.configuration import requirements
 from volatility3.framework.renderers import format_hints
-from volatility3.framework.symbols.windows.extensions import DEVICE_OBJECT
+from volatility3.framework.symbols.windows import extensions
 from volatility3.plugins.windows import driverscan
 
-DEVICE_CODES = {
-    0x00000027: "FILE_DEVICE_8042_PORT",
-    0x00000032: "FILE_DEVICE_ACPI",
-    0x00000029: "FILE_DEVICE_BATTERY",
-    0x00000001: "FILE_DEVICE_BEEP",
-    0x0000002A: "FILE_DEVICE_BUS_EXTENDER",
-    0x00000002: "FILE_DEVICE_CD_ROM",
-    0x00000003: "FILE_DEVICE_CD_ROM_FILE_SYSTEM",
-    0x00000030: "FILE_DEVICE_CHANGER",
-    0x00000004: "FILE_DEVICE_CONTROLLER",
-    0x00000005: "FILE_DEVICE_DATALINK",
-    0x00000006: "FILE_DEVICE_DFS",
-    0x00000035: "FILE_DEVICE_DFS_FILE_SYSTEM",
-    0x00000036: "FILE_DEVICE_DFS_VOLUME",
-    0x00000007: "FILE_DEVICE_DISK",
-    0x00000008: "FILE_DEVICE_DISK_FILE_SYSTEM",
-    0x00000033: "FILE_DEVICE_DVD",
-    0x00000009: "FILE_DEVICE_FILE_SYSTEM",
-    0x0000003A: "FILE_DEVICE_FIPS",
-    0x00000034: "FILE_DEVICE_FULLSCREEN_VIDEO",
-    0x0000000A: "FILE_DEVICE_INPORT_PORT",
-    0x0000000B: "FILE_DEVICE_KEYBOARD",
-    0x0000002F: "FILE_DEVICE_KS",
-    0x00000039: "FILE_DEVICE_KSEC",
-    0x0000000C: "FILE_DEVICE_MAILSLOT",
-    0x0000002D: "FILE_DEVICE_MASS_STORAGE",
-    0x0000000D: "FILE_DEVICE_MIDI_IN",
-    0x0000000E: "FILE_DEVICE_MIDI_OUT",
-    0x0000002B: "FILE_DEVICE_MODEM",
-    0x0000000F: "FILE_DEVICE_MOUSE",
-    0x00000010: "FILE_DEVICE_MULTI_UNC_PROVIDER",
-    0x00000011: "FILE_DEVICE_NAMED_PIPE",
-    0x00000012: "FILE_DEVICE_NETWORK",
-    0x00000013: "FILE_DEVICE_NETWORK_BROWSER",
-    0x00000014: "FILE_DEVICE_NETWORK_FILE_SYSTEM",
-    0x00000028: "FILE_DEVICE_NETWORK_REDIRECTOR",
-    0x00000015: "FILE_DEVICE_NULL",
-    0x00000016: "FILE_DEVICE_PARALLEL_PORT",
-    0x00000017: "FILE_DEVICE_PHYSICAL_NETCARD",
-    0x00000018: "FILE_DEVICE_PRINTER",
-    0x00000019: "FILE_DEVICE_SCANNER",
-    0x0000001C: "FILE_DEVICE_SCREEN",
-    0x00000037: "FILE_DEVICE_SERENUM",
-    0x0000001A: "FILE_DEVICE_SERIAL_MOUSE_PORT",
-    0x0000001B: "FILE_DEVICE_SERIAL_PORT",
-    0x00000031: "FILE_DEVICE_SMARTCARD",
-    0x0000002E: "FILE_DEVICE_SMB",
-    0x0000001D: "FILE_DEVICE_SOUND",
-    0x0000001E: "FILE_DEVICE_STREAMS",
-    0x0000001F: "FILE_DEVICE_TAPE",
-    0x00000020: "FILE_DEVICE_TAPE_FILE_SYSTEM",
-    0x00000038: "FILE_DEVICE_TERMSRV",
-    0x00000021: "FILE_DEVICE_TRANSPORT",
-    0x00000022: "FILE_DEVICE_UNKNOWN",
-    0x0000002C: "FILE_DEVICE_VDM",
-    0x00000023: "FILE_DEVICE_VIDEO",
-    0x00000024: "FILE_DEVICE_VIRTUAL_DISK",
-    0x00000025: "FILE_DEVICE_WAVE_IN",
-    0x00000026: "FILE_DEVICE_WAVE_OUT",
-}
-
 vollog = logging.getLogger(__name__)
 
 
@@ -101,97 +40,76 @@ def _generator(self) -> Iterator[Tuple]:
             self.config["kernel"],
         ):
             try:
-                try:
-                    driver_name = driver.DriverName.get_string()
-                except (ValueError, exceptions.InvalidAddressException):
-                    vollog.log(
-                        constants.LOGLEVEL_VVVV,
-                        f"Failed to get Driver name : {driver.vol.offset:x}",
-                    )
-                    driver_name = renderers.UnparsableValue()
-
-                yield (
-                    0,
-                    (
-                        format_hints.Hex(driver.vol.offset),
-                        "DRV",
-                        driver_name,
-                        renderers.NotApplicableValue(),
-                        renderers.NotApplicableValue(),
-                        renderers.NotApplicableValue(),
-                    ),
-                )
-
-                # Scan to get the device information of driver.
-                for device in driver.get_devices():
-                    for level, (
-                        offset,
-                        drv_name,
-                        dev_name,
-                        att_drv_name,
-                        dev_typ,
-                    ) in self._traverse_device_stack(device, driver_name, 1):
-                        yield level, (
-                            offset,
-                            "DEV" if level == 1 else "ATT",
-                            drv_name,
-                            dev_name,
-                            att_drv_name,
-                            dev_typ,
-                        )
-
-            except exceptions.InvalidAddressException:
+                driver_name = driver.DriverName.get_string()
+            except (ValueError, exceptions.InvalidAddressException):
                 vollog.log(
                     constants.LOGLEVEL_VVVV,
-                    f"Invalid address identified in drivers and devices: {driver.vol.offset:x}",
+                    f"Failed to get Driver name : {driver.vol.offset:x}",
                 )
-                continue
+                driver_name = renderers.UnparsableValue()
+
+            yield (
+                0,
+                (
+                    format_hints.Hex(driver.vol.offset),
+                    "DRV",
+                    driver_name,
+                    renderers.NotApplicableValue(),
+                    renderers.NotApplicableValue(),
+                    renderers.NotApplicableValue(),
+                ),
+            )
+
+            # Scan to get the device information of driver.
+            for device in driver.get_devices():
+                for level, device_entry in self._traverse_device_stack(device, 1):
+                    try:
+                        device_name = device.get_device_name()
+                    except exceptions.InvalidAddressException:
+                        device_name = renderers.UnparsableValue()
+
+                    try:
+                        attached_driver_name = device.get_attached_driver_name()
+                    except exceptions.InvalidAddressException:
+                        attached_driver_name = renderers.UnparsableValue()
+
+                    try:
+                        device_type = device.get_device_type()
+                    except exceptions.InvalidAddressException:
+                        device_type = renderers.UnparsableValue()
+
+                    yield level, (
+                        format_hints.Hex(device_entry.vol.offset),
+                        "DEV" if level == 1 else "ATT",
+                        driver_name,
+                        device_name,
+                        attached_driver_name,
+                        device_type,
+                    )
 
-    @staticmethod
+    @classmethod
     def _traverse_device_stack(
-        device: DEVICE_OBJECT, driver_name: str, level: int, seen: Set[int] = set()
-    ) -> Iterator[Tuple]:
+        cls, device: extensions.DEVICE_OBJECT, level: int, seen: Set[int] = set()
+    ) -> Iterator[Tuple[int, extensions.DEVICE_OBJECT]]:
         while device and device.vol.offset not in seen:
             seen.add(device.vol.offset)
-            try:
-                device_name = device.get_device_name()
-            except (ValueError, exceptions.InvalidAddressException):
-                vollog.log(
-                    constants.LOGLEVEL_VVVV,
-                    f"Failed to get Device name : {device.vol.offset:x}",
-                )
-                device_name = renderers.UnparsableValue()
-
-            device_type = DEVICE_CODES.get(device.DeviceType, "UNKNOWN")
-
-            att_drv_name = device.DriverObject.DriverName.get_string()
 
+            # Yield the first device and its level
             yield (
                 level,
-                (
-                    format_hints.Hex(device.vol.offset),
-                    driver_name,
-                    device_name,
-                    att_drv_name,
-                    device_type,
-                ),
+                device,
             )
-            try:
-                attached = device.AttachedDevice.dereference()
-                yield from DeviceTree._traverse_device_stack(
-                    attached, driver_name, level + 1, seen
-                )
-            except exceptions.InvalidAddressException:
-                vollog.debug(
-                    f"Failed to dereference attached device for device at {device.vol.offset:#x}, "
-                    "devnode may not have drivers associated with it"
-                )
+
+            for attached in device.get_attached_devices():
+                # Go depth-first through all of this device's child devices
+                yield from cls._traverse_device_stack(attached, level + 1, seen)
 
             try:
+                # Then move sideways to the next device in the current linked list
                 device = device.NextDevice.dereference()
             except exceptions.InvalidAddressException:
                 vollog.debug(
-                    f"Failed to dereference next driver in linked list at {int(device.NextDevice)}, "
+                    f"Failed to dereference next driver in linked list, "
                     "may have reached end of list"
                 )
 

volatility3/framework/symbols/windows/extensions/__init__.py

@@ -22,9 +22,8 @@
 from volatility3.framework.layers import intel
 from volatility3.framework.objects import utility
 from volatility3.framework.renderers import conversion
-from volatility3.framework.symbols import generic
+from volatility3.framework.symbols import generic, windows
 from volatility3.framework.symbols.windows.extensions import pool
-from volatility3.framework.symbols import windows
 
 vollog = logging.getLogger(__name__)
 
@@ -406,6 +405,68 @@ def dereference(self) -> interfaces.objects.ObjectInterface:
         )
 
 
+DEVICE_CODES = {
+    0x00000027: "FILE_DEVICE_8042_PORT",
+    0x00000032: "FILE_DEVICE_ACPI",
+    0x00000029: "FILE_DEVICE_BATTERY",
+    0x00000001: "FILE_DEVICE_BEEP",
+    0x0000002A: "FILE_DEVICE_BUS_EXTENDER",
+    0x00000002: "FILE_DEVICE_CD_ROM",
+    0x00000003: "FILE_DEVICE_CD_ROM_FILE_SYSTEM",
+    0x00000030: "FILE_DEVICE_CHANGER",
+    0x00000004: "FILE_DEVICE_CONTROLLER",
+    0x00000005: "FILE_DEVICE_DATALINK",
+    0x00000006: "FILE_DEVICE_DFS",
+    0x00000035: "FILE_DEVICE_DFS_FILE_SYSTEM",
+    0x00000036: "FILE_DEVICE_DFS_VOLUME",
+    0x00000007: "FILE_DEVICE_DISK",
+    0x00000008: "FILE_DEVICE_DISK_FILE_SYSTEM",
+    0x00000033: "FILE_DEVICE_DVD",
+    0x00000009: "FILE_DEVICE_FILE_SYSTEM",
+    0x0000003A: "FILE_DEVICE_FIPS",
+    0x00000034: "FILE_DEVICE_FULLSCREEN_VIDEO",
+    0x0000000A: "FILE_DEVICE_INPORT_PORT",
+    0x0000000B: "FILE_DEVICE_KEYBOARD",
+    0x0000002F: "FILE_DEVICE_KS",
+    0x00000039: "FILE_DEVICE_KSEC",
+    0x0000000C: "FILE_DEVICE_MAILSLOT",
+    0x0000002D: "FILE_DEVICE_MASS_STORAGE",
+    0x0000000D: "FILE_DEVICE_MIDI_IN",
+    0x0000000E: "FILE_DEVICE_MIDI_OUT",
+    0x0000002B: "FILE_DEVICE_MODEM",
+    0x0000000F: "FILE_DEVICE_MOUSE",
+    0x00000010: "FILE_DEVICE_MULTI_UNC_PROVIDER",
+    0x00000011: "FILE_DEVICE_NAMED_PIPE",
+    0x00000012: "FILE_DEVICE_NETWORK",
+    0x00000013: "FILE_DEVICE_NETWORK_BROWSER",
+    0x00000014: "FILE_DEVICE_NETWORK_FILE_SYSTEM",
+    0x00000028: "FILE_DEVICE_NETWORK_REDIRECTOR",
+    0x00000015: "FILE_DEVICE_NULL",
+    0x00000016: "FILE_DEVICE_PARALLEL_PORT",
+    0x00000017: "FILE_DEVICE_PHYSICAL_NETCARD",
+    0x00000018: "FILE_DEVICE_PRINTER",
+    0x00000019: "FILE_DEVICE_SCANNER",
+    0x0000001C: "FILE_DEVICE_SCREEN",
+    0x00000037: "FILE_DEVICE_SERENUM",
+    0x0000001A: "FILE_DEVICE_SERIAL_MOUSE_PORT",
+    0x0000001B: "FILE_DEVICE_SERIAL_PORT",
+    0x00000031: "FILE_DEVICE_SMARTCARD",
+    0x0000002E: "FILE_DEVICE_SMB",
+    0x0000001D: "FILE_DEVICE_SOUND",
+    0x0000001E: "FILE_DEVICE_STREAMS",
+    0x0000001F: "FILE_DEVICE_TAPE",
+    0x00000020: "FILE_DEVICE_TAPE_FILE_SYSTEM",
+    0x00000038: "FILE_DEVICE_TERMSRV",
+    0x00000021: "FILE_DEVICE_TRANSPORT",
+    0x00000022: "FILE_DEVICE_UNKNOWN",
+    0x0000002C: "FILE_DEVICE_VDM",
+    0x00000023: "FILE_DEVICE_VIDEO",
+    0x00000024: "FILE_DEVICE_VIRTUAL_DISK",
+    0x00000025: "FILE_DEVICE_WAVE_IN",
+    0x00000026: "FILE_DEVICE_WAVE_OUT",
+}
+
+
 class DEVICE_OBJECT(objects.StructType, pool.ExecutiveObject):
     """A class for kernel device objects."""
 
@@ -414,25 +475,36 @@ def get_device_name(self) -> str:
         header = self.get_object_header()
         return header.NameInfo.Name.String  # type: ignore
 
-    def get_attached_devices(self) -> Generator[ObjectInterface, None, None]:
+    def get_attached_driver_name(self) -> Optional[str]:
+        return self.DriverObject.DriverName.get_string()
+
+    def get_device_type(self) -> str:
+        return DEVICE_CODES.get(self.DeviceType, "UNKNOWN")
+
+    def get_attached_devices(self) -> Iterator["DEVICE_OBJECT"]:
         """Enumerate the attached device's objects"""
         seen = set()
 
         try:
             device = self.AttachedDevice.dereference()
         except exceptions.InvalidAddressException:
+            vollog.debug(
+                f"No attached device dereferenced for DEVICE_OBJECT at {self.vol.offset:#x}"
+            )
             return
 
-        while device:
-            if device.vol.offset in seen:
-                break
+        while device and device.vol.offset not in seen:
             seen.add(device.vol.offset)
 
             yield device
 
             try:
-                device = device.AttachedDevice.dereference()
+                device = device.NextDevice.dereference()
             except exceptions.InvalidAddressException:
+                vollog.debug(
+                    f"Failed to dereference next device "
+                    f"for device at {device.vol.offset:#x}, may have reached list end"
+                )
                 return