Merge pull request #960 from RuBublik/poolscanner-thread-support

Add threads pool tag scanning

test/test_volatility.py

@@ -190,6 +190,16 @@ def test_windows_svcscan(image, volatility, python):
     assert rc == 0
 
 
+def test_windows_thrdscan(image, volatility, python):
+    rc, out, err = runvol_plugin("windows.thrdscan.ThrdScan", image, volatility, python)
+    # find pid 4 (of system process) which starts with lowest tids
+    assert out.find(b"\t4\t8") != -1
+    assert out.find(b"\t4\t12") != -1
+    assert out.find(b"\t4\t16") != -1
+    #assert out.find(b"this raieses AssertionError") != -1
+    assert rc == 0
+
+
 def test_windows_privileges(image, volatility, python):
     rc, out, err = runvol_plugin(
         "windows.privileges.Privs", image, volatility, python, pluginargs=["--pid", "4"]

volatility3/framework/constants/__init__.py

@@ -44,8 +44,8 @@ BANG = "!"
 
 # We use the SemVer 2.0.0 versioning scheme
 VERSION_MAJOR = 2  # Number of releases of the library with a breaking change
-VERSION_MINOR = 6  # Number of changes that only add to the interface
-VERSION_PATCH = 1  # Number of changes that do not change the interface
+VERSION_MINOR = 7  # Number of changes that only add to the interface
+VERSION_PATCH = 0  # Number of changes that do not change the interface
 VERSION_SUFFIX = ""
 
 # TODO: At version 2.0.0, remove the symbol_shift feature

volatility3/framework/plugins/windows/poolscanner.py

@@ -222,6 +222,24 @@ class PoolScanner(plugins.PluginInterface):
                 type_name=symbol_table + constants.BANG + "_EPROCESS",
                 object_type="Process",
                 size=(600, None),
+                skip_type_test=True,
+                page_type=PoolType.PAGED | PoolType.NONPAGED | PoolType.FREE,
+            ),
+            # threads on windows before windows8
+            PoolConstraint(
+                b"Thr\xe5",  # -> “protected” allocation, MSB is set.
+                type_name=symbol_table + constants.BANG + "_ETHREAD",
+                object_type="Thread",
+                size=(600, None),  # -> 0x0258 - size of struct in win5.1
+                skip_type_test=True,
+                page_type=PoolType.PAGED | PoolType.NONPAGED | PoolType.FREE,
+            ),
+            # threads on windows starting with windows8
+            PoolConstraint(
+                b"Thre",
+                type_name=symbol_table + constants.BANG + "_ETHREAD",
+                object_type="Thread",
+                size=(600, None),  # -> 0x0258 - size of struct in win5.1
                 page_type=PoolType.PAGED | PoolType.NONPAGED | PoolType.FREE,
             ),
             # files on windows before windows 8

volatility3/framework/plugins/windows/thrdscan.py

@@ -0,0 +1,141 @@
+##
+## plugin for testing addition of threads scan support to poolscanner.py
+##
+import logging
+import datetime
+from typing import Iterable
+
+from volatility3.framework import renderers, interfaces, exceptions
+from volatility3.framework.configuration import requirements
+from volatility3.framework.renderers import format_hints
+from volatility3.plugins.windows import poolscanner
+from volatility3.plugins import timeliner
+
+vollog = logging.getLogger(__name__)
+
+
+class ThrdScan(interfaces.plugins.PluginInterface, timeliner.TimeLinerInterface):
+    """Scans for windows threads."""
+
+    # version 2.6.0 adds support for scanning for 'Ethread' structures by pool tags
+    _required_framework_version = (2, 6, 0)
+    _version = (1, 0, 0)
+
+    @classmethod
+    def get_requirements(cls):
+        return [
+            requirements.ModuleRequirement(
+                name="kernel",
+                description="Windows kernel",
+                architectures=["Intel32", "Intel64"],
+            ),
+            requirements.PluginRequirement(
+                name="poolscanner", plugin=poolscanner.PoolScanner, version=(1, 0, 0)
+            ),
+        ]
+
+    @classmethod
+    def scan_threads(
+        cls,
+        context: interfaces.context.ContextInterface,
+        layer_name: str,
+        symbol_table: str,
+    ) -> Iterable[interfaces.objects.ObjectInterface]:
+        """Scans for threads using the poolscanner module and constraints.
+
+        Args:
+            context: The context to retrieve required elements (layers, symbol tables) from
+            layer_name: The name of the layer on which to operate
+            symbol_table: The name of the table containing the kernel symbols
+
+        Returns:
+              A list of _ETHREAD objects found by scanning memory for the "Thre" / "Thr\\xE5" pool signatures
+        """
+
+        constraints = poolscanner.PoolScanner.builtin_constraints(
+            symbol_table, [b"Thr\xe5", b"Thre"]
+        )
+
+        for result in poolscanner.PoolScanner.generate_pool_scan(
+            context, layer_name, symbol_table, constraints
+        ):
+            _constraint, mem_object, _header = result
+            yield mem_object
+
+    def _generator(self):
+        kernel = self.context.modules[self.config["kernel"]]
+
+        for ethread in self.scan_threads(
+            self.context, kernel.layer_name, kernel.symbol_table_name
+        ):
+            try:
+                thread_offset = ethread.vol.offset
+                owner_proc_pid = ethread.Cid.UniqueProcess
+                thread_tid = ethread.Cid.UniqueThread
+                thread_start_addr = ethread.StartAddress
+                thread_create_time = (
+                    ethread.get_create_time()
+                )  # datetime.datetime object / volatility3.framework.renderers.UnparsableValue object
+                thread_exit_time = (
+                    ethread.get_exit_time()
+                )  # datetime.datetime object / volatility3.framework.renderers.UnparsableValue object
+            except (ValueError, exceptions.InvalidAddressException):
+                vollog.debug(
+                    "Thread :{}, invalid address {} in layer {}".format(
+                        thread_tid, thread_start_addr, kernel.layer_name
+                    )
+                )
+                continue
+
+            yield (
+                0,
+                (
+                    format_hints.Hex(thread_offset),
+                    owner_proc_pid,
+                    thread_tid,
+                    format_hints.Hex(thread_start_addr),
+                    thread_create_time,
+                    thread_exit_time,
+                ),
+            )
+
+    def generate_timeline(self):
+        for row in self._generator():
+            _depth, row_data = row
+            row_dict = {}
+            (
+                row_dict["Offset"],
+                row_dict["PID"],
+                row_dict["TID"],
+                row_dict["StartAddress"],
+                row_dict["CreateTime"],
+                row_dict["ExitTime"],
+            ) = row_data
+
+            # Skip threads with no creation time
+            # - mainly system process threads
+            if not isinstance(row_dict["CreateTime"], datetime.datetime):
+                continue
+            description = f"Thread: Tid {row_dict['TID']} in Pid {row_dict['PID']} (Offset {row_dict['Offset']})"
+
+            # yield created time, and if there is exit time, yield it too.
+            yield (description, timeliner.TimeLinerType.CREATED, row_dict["CreateTime"])
+            if isinstance(row_dict["ExitTime"], datetime.datetime):
+                yield (
+                    description,
+                    timeliner.TimeLinerType.MODIFIED,
+                    row_dict["ExitTime"],
+                )
+
+    def run(self):
+        return renderers.TreeGrid(
+            [
+                ("Offset", format_hints.Hex),
+                ("PID", int),
+                ("TID", int),
+                ("StartAddress", format_hints.Hex),
+                ("CreateTime", datetime.datetime),
+                ("ExitTime", datetime.datetime),
+            ],
+            self._generator(),
+        )

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

@@ -492,9 +492,47 @@ class KMUTANT(objects.StructType, pool.ExecutiveObject):
         return header.NameInfo.Name.String  # type: ignore
 
 
-class ETHREAD(objects.StructType):
+class ETHREAD(objects.StructType, pool.ExecutiveObject):
     """A class for executive thread objects."""
 
+    def is_valid(self) -> bool:
+        """Determine if the object is valid."""
+
+        try:
+            # validation by TID:
+            if self.Cid.UniqueThread % 4 != 0:  # NT tids are divisible by 4
+                return False
+
+            # validation by PID of parent process:
+            if self.Cid.UniqueProcess % 4 != 0:
+                return False
+
+            # validation by thread creation time:
+            if (
+                self.Cid.UniqueProcess != 4
+            ):  # The System process (PID 4) has no create time
+                ctime = self.get_create_time()
+                if not isinstance(ctime, datetime.datetime):
+                    return False
+
+                if not (1998 < ctime.year < 2030):
+                    return False
+
+        except exceptions.InvalidAddressException:
+            return False
+
+        # passed all validations
+        return True
+
+    def get_create_time(self):
+        # For Windows XPs
+        if self.has_member("ThreadsProcess"):
+            return conversion.wintime_to_datetime(self.CreateTime.QuadPart >> 3)
+        return conversion.wintime_to_datetime(self.CreateTime.QuadPart)
+
+    def get_exit_time(self):
+        return conversion.wintime_to_datetime(self.ExitTime.QuadPart)
+
     def owning_process(self) -> interfaces.objects.ObjectInterface:
         """Return the EPROCESS that owns this thread."""