New linux plugin: modxview

volatility3/framework/constants/_version.py

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

volatility3/framework/constants/linux/__init__.py

@@ -6,6 +6,7 @@
 Linux-specific values that aren't found in debug symbols
 """
 from enum import IntEnum, Flag
+from dataclasses import dataclass
 
 KERNEL_NAME = "__kernel__"
 
@@ -352,3 +353,57 @@ def flags(self) -> str:
 MODULE_MAXIMUM_CORE_SIZE = 20000000
 MODULE_MAXIMUM_CORE_TEXT_SIZE = 20000000
 MODULE_MINIMUM_SIZE = 4096
+
+
+@dataclass
+class TaintFlag:
+    shift: int
+    desc: str
+    when_present: bool
+    module: bool
+
+
+TAINT_FLAGS = {
+    "P": TaintFlag(
+        shift=1 << 0, desc="PROPRIETARY_MODULE", when_present=True, module=True
+    ),
+    "G": TaintFlag(
+        shift=1 << 0, desc="PROPRIETARY_MODULE", when_present=False, module=True
+    ),
+    "F": TaintFlag(shift=1 << 1, desc="FORCED_MODULE", when_present=True, module=False),
+    "S": TaintFlag(
+        shift=1 << 2, desc="CPU_OUT_OF_SPEC", when_present=True, module=False
+    ),
+    "R": TaintFlag(shift=1 << 3, desc="FORCED_RMMOD", when_present=True, module=False),
+    "M": TaintFlag(shift=1 << 4, desc="MACHINE_CHECK", when_present=True, module=False),
+    "B": TaintFlag(shift=1 << 5, desc="BAD_PAGE", when_present=True, module=False),
+    "U": TaintFlag(shift=1 << 6, desc="USER", when_present=True, module=False),
+    "D": TaintFlag(shift=1 << 7, desc="DIE", when_present=True, module=False),
+    "A": TaintFlag(
+        shift=1 << 8, desc="OVERRIDDEN_ACPI_TABLE", when_present=True, module=False
+    ),
+    "W": TaintFlag(shift=1 << 9, desc="WARN", when_present=True, module=False),
+    "C": TaintFlag(shift=1 << 10, desc="CRAP", when_present=True, module=True),
+    "I": TaintFlag(
+        shift=1 << 11, desc="FIRMWARE_WORKAROUND", when_present=True, module=False
+    ),
+    "O": TaintFlag(shift=1 << 12, desc="OOT_MODULE", when_present=True, module=True),
+    "E": TaintFlag(
+        shift=1 << 13, desc="UNSIGNED_MODULE", when_present=True, module=True
+    ),
+    "L": TaintFlag(shift=1 << 14, desc="SOFTLOCKUP", when_present=True, module=False),
+    "K": TaintFlag(shift=1 << 15, desc="LIVEPATCH", when_present=True, module=True),
+    "X": TaintFlag(shift=1 << 16, desc="AUX", when_present=True, module=True),
+    "T": TaintFlag(shift=1 << 17, desc="RANDSTRUCT", when_present=True, module=True),
+    "N": TaintFlag(shift=1 << 18, desc="TEST", when_present=True, module=True),
+}
+"""Flags used to taint kernel and modules, for debugging purposes.
+
+Map based on 6.12-rc5.
+
+Documentation :
+    - https://www.kernel.org/doc/Documentation/admin-guide/sysctl/kernel.rst#:~:text=guide/sysrq.rst.-,tainted,-%3D%3D%3D%3D%3D%3D%3D%0A%0ANon%2Dzero%20if
+    - https://www.kernel.org/doc/Documentation/admin-guide/tainted-kernels.rst#:~:text=More%20detailed%20explanation%20for%20tainting
+    - taint_flag kernel struct
+    - taint_flags kernel constant
+"""

volatility3/framework/plugins/linux/check_modules.py

@@ -18,6 +18,7 @@
 class Check_modules(plugins.PluginInterface):
     """Compares module list to sysfs info, if available"""
 
+    _version = (1, 0, 0)
     _required_framework_version = (2, 0, 0)
 
     @classmethod

volatility3/framework/plugins/linux/modxview.py

@@ -0,0 +1,172 @@
+# This file is Copyright 2024 Volatility Foundation and licensed under the Volatility Software License 1.0
+# which is available at https://www.volatilityfoundation.org/license/vsl-v1.0
+#
+import logging
+from typing import List, Dict, Set, Iterator
+from volatility3.plugins.linux import lsmod, check_modules, hidden_modules
+from volatility3.framework import interfaces
+from volatility3.framework.configuration import requirements
+from volatility3.framework.renderers import format_hints, TreeGrid, NotAvailableValue
+from volatility3.framework.symbols.linux import extensions
+from volatility3.framework.constants import architectures
+from volatility3.framework.symbols.linux.utilities import tainting
+
+vollog = logging.getLogger(__name__)
+
+
+class Modxview(interfaces.plugins.PluginInterface):
+    """Centralize lsmod, check_modules and hidden_modules results to efficiently
+    spot modules presence and taints."""
+
+    _version = (1, 0, 0)
+    _required_framework_version = (2, 18, 0)
+
+    @classmethod
+    def get_requirements(cls) -> List[interfaces.configuration.RequirementInterface]:
+        return [
+            requirements.ModuleRequirement(
+                name="kernel",
+                description="Linux kernel",
+                architectures=architectures.LINUX_ARCHS,
+            ),
+            requirements.VersionRequirement(
+                name="linux-tainting", component=tainting.Tainting, version=(1, 0, 0)
+            ),
+            requirements.PluginRequirement(
+                name="lsmod", plugin=lsmod.Lsmod, version=(2, 0, 0)
+            ),
+            requirements.PluginRequirement(
+                name="check_modules",
+                plugin=check_modules.Check_modules,
+                version=(1, 0, 0),
+            ),
+            requirements.PluginRequirement(
+                name="hidden_modules",
+                plugin=hidden_modules.Hidden_modules,
+                version=(1, 0, 0),
+            ),
+            requirements.BooleanRequirement(
+                name="plain_taints",
+                description="Display the plain taints string for each module.",
+                optional=True,
+                default=False,
+            ),
+        ]
+
+    @classmethod
+    def flatten_run_modules_results(
+        cls, run_results: Dict[str, List[extensions.module]], deduplicate: bool = True
+    ) -> Iterator[extensions.module]:
+        """Flatten a dictionary mapping plugin names and modules list, to a single merged list.
+        This is useful to get a generic lookup list of all the detected modules.
+
+        Args:
+            run_results: dictionary of plugin names mapping a list of detected modules
+            deduplicate: remove duplicate modules, based on their offsets
+
+        Returns:
+            Iterator of modules objects
+        """
+        seen_addresses = set()
+        for modules in run_results.values():
+            for module in modules:
+                if deduplicate and module.vol.offset in seen_addresses:
+                    continue
+                seen_addresses.add(module.vol.offset)
+                yield module
+
+    @classmethod
+    def run_modules_scanners(
+        cls,
+        context: interfaces.context.ContextInterface,
+        kernel_name: str,
+        run_hidden_modules: bool = True,
+    ) -> Dict[str, List[extensions.module]]:
+        """Run module scanning plugins and aggregate the results.
+
+        Args:
+            run_hidden_modules: specify if the hidden_modules plugin should be run
+        Returns:
+            Dictionary mapping each plugin to its corresponding result
+        """
+
+        kernel = context.modules[kernel_name]
+        run_results = {}
+        # lsmod
+        run_results["lsmod"] = list(lsmod.Lsmod.list_modules(context, kernel_name))
+        # check_modules
+        sysfs_modules: dict = check_modules.Check_modules.get_kset_modules(
+            context, kernel_name
+        )
+        ## Convert get_kset_modules() offsets back to module objects
+        run_results["check_modules"] = [
+            kernel.object(object_type="module", offset=m_offset, absolute=True)
+            for m_offset in sysfs_modules.values()
+        ]
+        # hidden_modules
+        if run_hidden_modules:
+            known_modules_addresses = set(
+                context.layers[kernel.layer_name].canonicalize(module.vol.offset)
+                for module in run_results["lsmod"] + run_results["check_modules"]
+            )
+            modules_memory_boundaries = (
+                hidden_modules.Hidden_modules.get_modules_memory_boundaries(
+                    context, kernel_name
+                )
+            )
+            run_results["hidden_modules"] = list(
+                hidden_modules.Hidden_modules.get_hidden_modules(
+                    context,
+                    kernel_name,
+                    known_modules_addresses,
+                    modules_memory_boundaries,
+                )
+            )
+
+        return run_results
+
+    def _generator(self):
+        kernel_name = self.config["kernel"]
+        run_results = self.run_modules_scanners(self.context, kernel_name)
+        modules_offsets = {}
+        for key in ["lsmod", "check_modules", "hidden_modules"]:
+            modules_offsets[key] = set(module.vol.offset for module in run_results[key])
+
+        seen_addresses = set()
+        for modules_list in run_results.values():
+            for module in modules_list:
+                if module.vol.offset in seen_addresses:
+                    continue
+                seen_addresses.add(module.vol.offset)
+
+                if self.config.get("plain_taints"):
+                    taints = module.get_taints_as_plain_string()
+                else:
+                    taints = ",".join(module.get_taints_parsed())
+
+                yield (
+                    0,
+                    (
+                        module.get_name() or NotAvailableValue(),
+                        format_hints.Hex(module.vol.offset),
+                        module.vol.offset in modules_offsets["lsmod"],
+                        module.vol.offset in modules_offsets["check_modules"],
+                        module.vol.offset in modules_offsets["hidden_modules"],
+                        taints or NotAvailableValue(),
+                    ),
+                )
+
+    def run(self):
+        columns = [
+            ("Name", str),
+            ("Address", format_hints.Hex),
+            ("In procfs", bool),
+            ("In sysfs", bool),
+            ("Hidden", bool),
+            ("Taints", str),
+        ]
+
+        return TreeGrid(
+            columns,
+            self._generator(),
+        )

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

@@ -19,7 +19,7 @@
 from volatility3.framework.objects import utility
 from volatility3.framework.symbols import generic, linux, intermed
 from volatility3.framework.symbols.linux.extensions import elf
-
+from volatility3.framework.symbols.linux.utilities import tainting
 
 vollog = logging.getLogger(__name__)
 
@@ -279,6 +279,30 @@ def get_symbol_by_address(self, wanted_sym_address):
 
         return None
 
+    def get_taints_as_plain_string(self) -> str:
+        """Convert the module's taints value to a 1-1 character mapping.
+        Convenient wrapper around framework's Tainting capabilities.
+
+        Returns:
+            The raw taints string.
+        """
+        return tainting.Tainting(
+            self._context,
+            linux.LinuxUtilities.get_module_from_volobj_type(self._context, self).name,
+        ).get_taints_as_plain_string(self.taints, True)
+
+    def get_taints_parsed(self) -> List[str]:
+        """Convert the module's taints string to a 1-1 descriptor mapping.
+        Convenient wrapper around framework's Tainting capabilities.
+
+        Returns:
+            A comprehensive (user-friendly) taint descriptor list.
+        """
+        return tainting.Tainting(
+            self._context,
+            linux.LinuxUtilities.get_module_from_volobj_type(self._context, self).name,
+        ).get_taints_parsed(self.taints, True)
+
     @property
     def section_symtab(self):
         if self.has_member("kallsyms"):