From f0f3bb65581e433cc7b44c2e877a1e95c927e17e Mon Sep 17 00:00:00 2001 From: Mike Auty Date: Tue, 17 Dec 2024 18:31:41 +0000 Subject: [PATCH 01/43] Core: Start to fix up the typing in ModuleCollection Fixes #1418 --- volatility3/framework/contexts/__init__.py | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/volatility3/framework/contexts/__init__.py b/volatility3/framework/contexts/__init__.py index 6961d9328..1a55656b3 100644 --- a/volatility3/framework/contexts/__init__.py +++ b/volatility3/framework/contexts/__init__.py @@ -11,7 +11,7 @@ without them interfering with each other. import functools import hashlib import logging -from typing import Callable, Iterable, List, Optional, Set, Tuple, Union +from typing import Callable, Dict, Iterable, List, Optional, Set, Tuple, Union from volatility3.framework import constants, interfaces, symbols, exceptions from volatility3.framework.objects import templates @@ -386,10 +386,9 @@ class ModuleCollection(interfaces.context.ModuleContainer): """Class to contain a collection of SizedModules and reason about their contents.""" - def __init__( - self, modules: Optional[List[interfaces.context.ModuleInterface]] = None - ) -> None: + def __init__(self, modules: Optional[List[SizedModule]] = None) -> None: self._prefix_count = {} + self._modules: Dict[str, SizedModule] = {} super().__init__(modules) def deduplicate(self) -> "ModuleCollection": @@ -402,9 +401,9 @@ class ModuleCollection(interfaces.context.ModuleContainer): new_modules = [] seen: Set[str] = set() for mod in self._modules: - if mod.hash not in seen or mod.size == 0: + if self._modules[mod].hash not in seen or self._modules[mod].size == 0: new_modules.append(mod) - seen.add(mod.hash) # type: ignore # FIXME: mypy #5107 + seen.add(self._modules[mod].hash) return ModuleCollection(new_modules) def free_module_name(self, prefix: str = "module") -> str: From a0b169cf6b1f0a5d8ced886ff855e7ad7dd791c0 Mon Sep 17 00:00:00 2001 From: Mike Auty Date: Tue, 17 Dec 2024 18:34:19 +0000 Subject: [PATCH 02/43] This PR does not strictly change any interfaces, just the inner workings of a function. --- volatility3/framework/constants/_version.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/volatility3/framework/constants/_version.py b/volatility3/framework/constants/_version.py index 55ef19e4b..2ea034176 100644 --- a/volatility3/framework/constants/_version.py +++ b/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 = 12 # 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 = ( From 1b8f831fda1fc0d47eaf81144dec81354dca8490 Mon Sep 17 00:00:00 2001 From: Mike Auty Date: Tue, 17 Dec 2024 18:37:39 +0000 Subject: [PATCH 03/43] Core: Also fix up the interface to match the concrete classes --- volatility3/framework/interfaces/context.py | 1 + 1 file changed, 1 insertion(+) diff --git a/volatility3/framework/interfaces/context.py b/volatility3/framework/interfaces/context.py index 8b5e816e8..e85429732 100644 --- a/volatility3/framework/interfaces/context.py +++ b/volatility3/framework/interfaces/context.py @@ -295,6 +295,7 @@ class ModuleInterface(interfaces.configuration.ConfigurableInterface): def has_enumeration(self, name: str) -> bool: """Determines whether an enumeration is present in the module's symbol table.""" + @property def symbols(self) -> List: """Lists the symbols contained in the symbol table for this module""" From c6209800bdc810627f8757881f32e1cf0cfb6f17 Mon Sep 17 00:00:00 2001 From: Mike Auty Date: Wed, 1 Jan 2025 13:23:02 +0000 Subject: [PATCH 04/43] Core: Fix up issues when resolving merge --- volatility3/framework/constants/_version.py | 2 +- volatility3/framework/interfaces/context.py | 1 + 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/volatility3/framework/constants/_version.py b/volatility3/framework/constants/_version.py index 02402c5c9..694375538 100644 --- a/volatility3/framework/constants/_version.py +++ b/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 = 14 # Number of changes that only add to the interface VERSION_PATCH = 1 # Number of changes that do not change the interface VERSION_SUFFIX = "" diff --git a/volatility3/framework/interfaces/context.py b/volatility3/framework/interfaces/context.py index 30840a5b9..0b2ae0cc9 100644 --- a/volatility3/framework/interfaces/context.py +++ b/volatility3/framework/interfaces/context.py @@ -306,6 +306,7 @@ class ModuleInterface(interfaces.configuration.ConfigurableInterface): @abstractmethod def symbols(self) -> List: """Lists the symbols contained in the symbol table for this module""" + raise NotImplementedError("Symbols property has not been implemented.") @abstractmethod def get_symbols_by_absolute_location(self, offset: int, size: int = 0) -> List[str]: From 443f7afc9c95c5738cd9eec841ca834860914759 Mon Sep 17 00:00:00 2001 From: Mike Auty Date: Wed, 1 Jan 2025 13:59:20 +0000 Subject: [PATCH 05/43] Core: Fix code scanning issue concerning equality --- volatility3/framework/contexts/__init__.py | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/volatility3/framework/contexts/__init__.py b/volatility3/framework/contexts/__init__.py index a9ec4ac69..e1fb56d94 100644 --- a/volatility3/framework/contexts/__init__.py +++ b/volatility3/framework/contexts/__init__.py @@ -11,6 +11,7 @@ without them interfering with each other. import functools import hashlib import logging +import re from typing import Callable, Dict, Iterable, List, Optional, Set, Tuple, Union from volatility3.framework import constants, interfaces, symbols, exceptions @@ -387,7 +388,6 @@ class ModuleCollection(interfaces.context.ModuleContainer): contents.""" def __init__(self, modules: Optional[List[SizedModule]] = None) -> None: - self._prefix_count = {} self._modules: Dict[str, SizedModule] = {} super().__init__(modules) @@ -408,13 +408,12 @@ class ModuleCollection(interfaces.context.ModuleContainer): def free_module_name(self, prefix: str = "module") -> str: """Returns an unused module name""" - if prefix not in self._prefix_count: - self._prefix_count[prefix] = 1 + existing_names = [name for name in self if re.match(rf"^{prefix}[0-9]*$", name)] + if not existing_names: return prefix - count = self._prefix_count[prefix] + count = len(existing_names) while prefix + str(count) in self: count += 1 - self._prefix_count[prefix] = count return prefix + str(count) @property From 6be039a7e5ddf23f918f073428cbab7e3604f4e7 Mon Sep 17 00:00:00 2001 From: Mike Auty Date: Wed, 1 Jan 2025 14:05:02 +0000 Subject: [PATCH 06/43] Core: Fix black error --- volatility3/framework/interfaces/context.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/volatility3/framework/interfaces/context.py b/volatility3/framework/interfaces/context.py index 0b2ae0cc9..48c066e96 100644 --- a/volatility3/framework/interfaces/context.py +++ b/volatility3/framework/interfaces/context.py @@ -306,7 +306,7 @@ class ModuleInterface(interfaces.configuration.ConfigurableInterface): @abstractmethod def symbols(self) -> List: """Lists the symbols contained in the symbol table for this module""" - raise NotImplementedError("Symbols property has not been implemented.") + raise NotImplementedError("Symbols property has not been implemented.") @abstractmethod def get_symbols_by_absolute_location(self, offset: int, size: int = 0) -> List[str]: From 1edb7a4a722c3e289815b82d3213b8871af2c06f Mon Sep 17 00:00:00 2001 From: Mike Auty Date: Fri, 17 Jan 2025 16:03:47 +0000 Subject: [PATCH 07/43] Core: Correct version dependencies to avoid conflicts Fixes #1546 --- pyproject.toml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pyproject.toml b/pyproject.toml index 86e3921d2..542a1480a 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -34,7 +34,7 @@ cloud = [ dev = [ "volatility3[full,cloud]", "jsonschema>=4.23.0,<5", - "pyinstaller>=6.11.0,<7", + "pyinstaller>=6.5.0,<7", "pyinstaller-hooks-contrib>=2024.9", "types-jsonschema>=4.23.0,<5", ] @@ -48,7 +48,7 @@ test = [ docs = [ "volatility3[dev]", - "sphinx>=8.0.0,<7", + "sphinx>=8.0.0,<9", "sphinx-autodoc-typehints>=2.5.0,<3", "sphinx-rtd-theme>=3.0.1,<4", ] From c4430cda8d6b13b0d69a787fe32e8158ae471c3a Mon Sep 17 00:00:00 2001 From: Mike Auty Date: Fri, 17 Jan 2025 16:09:35 +0000 Subject: [PATCH 08/43] Core: Try to maintain python-3.8 support for the documentation --- pyproject.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pyproject.toml b/pyproject.toml index 542a1480a..8944bb058 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -49,7 +49,7 @@ test = [ docs = [ "volatility3[dev]", "sphinx>=8.0.0,<9", - "sphinx-autodoc-typehints>=2.5.0,<3", + "sphinx-autodoc-typehints>=2.0.0,<3", "sphinx-rtd-theme>=3.0.1,<4", ] From 13a8c53f7b64bc7180b665e363b2a3f0348e8b04 Mon Sep 17 00:00:00 2001 From: Mike Auty Date: Fri, 17 Jan 2025 16:13:35 +0000 Subject: [PATCH 09/43] Core: There was no clear reason to stop supporting older versions of sphinx --- pyproject.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pyproject.toml b/pyproject.toml index 8944bb058..3f16eeece 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -48,7 +48,7 @@ test = [ docs = [ "volatility3[dev]", - "sphinx>=8.0.0,<9", + "sphinx>=4.0.0,<9", "sphinx-autodoc-typehints>=2.0.0,<3", "sphinx-rtd-theme>=3.0.1,<4", ] From 2fe8ee5983bd5faf8a89db5712512aa411329dbc Mon Sep 17 00:00:00 2001 From: Mike Auty Date: Sat, 18 Jan 2025 13:18:53 +0000 Subject: [PATCH 10/43] Layers: Update LeechCore RawIO with better error handling for readlines Fixes #1419 --- volatility3/framework/layers/leechcore.py | 2 ++ 1 file changed, 2 insertions(+) diff --git a/volatility3/framework/layers/leechcore.py b/volatility3/framework/layers/leechcore.py index eeede1673..06c359203 100644 --- a/volatility3/framework/layers/leechcore.py +++ b/volatility3/framework/layers/leechcore.py @@ -129,6 +129,8 @@ if HAS_LEECHCORE: def readline(self, __size: Optional[int] = ...) -> bytes: data = b"" + if not __size: + __size = 0 while __size > self._chunk_size or __size < 0: data += self.read(self._chunk_size) index = data.find(b"\n") From dfe3d255c064b9c78edf4f5f58eff6c15cc56486 Mon Sep 17 00:00:00 2001 From: Odysseas Stavrou Date: Mon, 20 Jan 2025 22:25:01 +0200 Subject: [PATCH 11/43] Volshell: Update Process retrieval methods with virtual/physical offsets --- volatility3/cli/volshell/linux.py | 58 +++++++++++++++++++++++++++++ volatility3/cli/volshell/windows.py | 47 +++++++++++++++++++++++ 2 files changed, 105 insertions(+) diff --git a/volatility3/cli/volshell/linux.py b/volatility3/cli/volshell/linux.py index cc58fa1c2..9ea3ea1f5 100644 --- a/volatility3/cli/volshell/linux.py +++ b/volatility3/cli/volshell/linux.py @@ -3,6 +3,7 @@ # from typing import Any, List, Optional, Tuple, Union +from enum import Enum from volatility3.cli.volshell import generic from volatility3.framework import constants, interfaces @@ -10,6 +11,16 @@ from volatility3.framework.configuration import requirements from volatility3.plugins.linux import pslist +# Could import the enum from psscan.py to avoid code duplication +class DescExitStateEnum(Enum): + """Enum for linux task exit_state as defined in include/linux/sched.h""" + + TASK_RUNNING = 0x00000000 + EXIT_DEAD = 0x00000010 + EXIT_ZOMBIE = 0x00000020 + EXIT_TRACE = EXIT_ZOMBIE | EXIT_DEAD + + class Volshell(generic.Volshell): """Shell environment to directly interact with a linux memory image.""" @@ -40,6 +51,52 @@ class Volshell(generic.Volshell): return None print(f"No task with task ID {pid} found") + def get_process(self, pid=None, offset=None): + """Get Task based on a process ID. Does not retrieve the layer, to change layer use the .pid attribute. The offset argument can be used both for physical or virtual offsets""" + + if pid is not None and offset is not None: + print("Only one parameter is accepted") + return None + + if offset is not None: + vmlinux_module_name = self.config["kernel"] + vmlinux = self.context.modules[vmlinux_module_name] + + kernel_layer_name = vmlinux.layer_name + kernel_layer = self.context.layers[kernel_layer_name] + + memory_layer_name = kernel_layer.dependencies[0] + + ptask = self.context.object( + vmlinux.symbol_table_name + constants.BANG + "task_struct", + layer_name=memory_layer_name, + offset=offset, + native_layer_name=kernel_layer_name, + ) + + try: + DescExitStateEnum(ptask.exit_state) + except ValueError: + print( + f"task_struct @ {hex(ptask.vol.offset)} as exit_state {ptask.exit_state} is likely not valid" + ) + + if not (0 < ptask.pid < 65535): + print( + f"task_struct @ {hex(ptask.vol.offset)} as pid {ptask.pid} is likely not valid" + ) + + return ptask + + if pid is not None: + tasks = self.list_tasks() + for task in tasks: + if task.pid == pid: + return task + print(f"No task with task ID {pid} found") + + return None + def list_tasks(self): """Returns a list of task objects from the primary layer""" # We always use the main kernel memory and associated symbols @@ -50,6 +107,7 @@ class Volshell(generic.Volshell): result += [ (["ct", "change_task", "cp"], self.change_task), (["lt", "list_tasks", "ps"], self.list_tasks), + (["gp", "get_process"], self.get_process), (["symbols"], self.context.symbol_space[self.current_symbol_table]), ] if self.config.get("pid", None) is not None: diff --git a/volatility3/cli/volshell/windows.py b/volatility3/cli/volshell/windows.py index 303d4d5c3..a77392561 100644 --- a/volatility3/cli/volshell/windows.py +++ b/volatility3/cli/volshell/windows.py @@ -44,11 +44,58 @@ class Volshell(generic.Volshell): ) ) + def get_process(self, pid=None, v_offset=None, p_offset=None): + """Returns the EPROCESS object that matches the pid. If v_offset/p_offset is provided, construct the EPROCESS object at the provided address. Only one parameter is allowed.""" + + if sum(1 if x is not None else 0 for x in [pid, v_offset, p_offset]) != 1: + print("Only one parameter is accepted") + return None + + kernel_name = self.config["kernel"] + kernel = self.context.modules[kernel_name] + + kernel_layer_name = kernel.layer_name + + kernel_layer = self.context.layers[kernel_layer_name] + memory_layer_name = kernel_layer.dependencies[0] + + eprocess_symbol = kernel.symbol_table_name + constants.BANG + "_EPROCESS" + + if v_offset is not None: + eproc = self.context.object( + eprocess_symbol, + layer_name=kernel_layer_name, + offset=v_offset, + ) + + return eproc + + if p_offset is not None: + eproc = self.context.object( + eprocess_symbol, + layer_name=memory_layer_name, + offset=p_offset, + native_layer_name=kernel_layer_name, + ) + + return eproc + + if pid is not None: + processes = self.list_processes() + for process in processes: + if process.UniqueProcessId == pid: + return process + print(f"No process with process ID {pid} found") + return None + + return None + def construct_locals(self) -> List[Tuple[List[str], Any]]: result = super().construct_locals() result += [ (["cp", "change_process"], self.change_process), (["lp", "list_processes", "ps"], self.list_processes), + (["gp", "get_process"], self.get_process), (["symbols"], self.context.symbol_space[self.current_symbol_table]), ] if self.config.get("pid", None) is not None: From b59f051353cd58b7d6e4bfda2f07746820f4f32a Mon Sep 17 00:00:00 2001 From: Odysseas Stavrou Date: Wed, 22 Jan 2025 02:39:35 +0200 Subject: [PATCH 12/43] Volshell: Updates to the get_process() methods --- volatility3/cli/volshell/linux.py | 55 +++++++++++++++++++---------- volatility3/cli/volshell/windows.py | 23 ++++++++---- 2 files changed, 53 insertions(+), 25 deletions(-) diff --git a/volatility3/cli/volshell/linux.py b/volatility3/cli/volshell/linux.py index 9ea3ea1f5..b3689c3ae 100644 --- a/volatility3/cli/volshell/linux.py +++ b/volatility3/cli/volshell/linux.py @@ -51,42 +51,61 @@ class Volshell(generic.Volshell): return None print(f"No task with task ID {pid} found") - def get_process(self, pid=None, offset=None): - """Get Task based on a process ID. Does not retrieve the layer, to change layer use the .pid attribute. The offset argument can be used both for physical or virtual offsets""" + def get_process(self, pid=None, virtaddr=None, physaddr=None): + """Return the task_struct object that matches the pid. If a physical or a virtual address is provided, construct the task_struct object at said address. Only one parameter is allowed. - if pid is not None and offset is not None: + Args: + pid (int, optional): PID to search for + virtaddr (int, optional): Virtual address to construct object at + physaddr (int, optional): Physical address to construct object at + + Returns: + ObjectInterface: task_struct Object + """ + + if sum(1 if x is not None else 0 for x in [pid, virtaddr, physaddr]) != 1: print("Only one parameter is accepted") return None - if offset is not None: - vmlinux_module_name = self.config["kernel"] - vmlinux = self.context.modules[vmlinux_module_name] + vmlinux_module_name = self.config["kernel"] + vmlinux = self.context.modules[vmlinux_module_name] - kernel_layer_name = vmlinux.layer_name - kernel_layer = self.context.layers[kernel_layer_name] + kernel_layer_name = vmlinux.layer_name + kernel_layer = self.context.layers[kernel_layer_name] - memory_layer_name = kernel_layer.dependencies[0] + memory_layer_name = kernel_layer.dependencies[0] - ptask = self.context.object( - vmlinux.symbol_table_name + constants.BANG + "task_struct", + task_struct_symbol = vmlinux.symbol_table_name + constants.BANG + "task_struct" + + if virtaddr is not None: + task = self.context.object( + task_struct_symbol, + layer_name=kernel_layer_name, + offset=virtaddr, + ) + + if physaddr is not None: + task = self.context.object( + task_struct_symbol, layer_name=memory_layer_name, - offset=offset, + offset=physaddr, native_layer_name=kernel_layer_name, ) + if physaddr is not None or virtaddr is not None: try: - DescExitStateEnum(ptask.exit_state) + DescExitStateEnum(task.exit_state) except ValueError: print( - f"task_struct @ {hex(ptask.vol.offset)} as exit_state {ptask.exit_state} is likely not valid" + f"task_struct @ {hex(task.vol.offset)} as exit_state {task.exit_state} is likely not valid" ) - if not (0 < ptask.pid < 65535): + if not (0 < task.pid < 65535): print( - f"task_struct @ {hex(ptask.vol.offset)} as pid {ptask.pid} is likely not valid" + f"task_struct @ {hex(task.vol.offset)} as pid {task.pid} is likely not valid" ) - return ptask + return task if pid is not None: tasks = self.list_tasks() @@ -107,7 +126,7 @@ class Volshell(generic.Volshell): result += [ (["ct", "change_task", "cp"], self.change_task), (["lt", "list_tasks", "ps"], self.list_tasks), - (["gp", "get_process"], self.get_process), + (["gp", "get_process", "get_task"], self.get_process), (["symbols"], self.context.symbol_space[self.current_symbol_table]), ] if self.config.get("pid", None) is not None: diff --git a/volatility3/cli/volshell/windows.py b/volatility3/cli/volshell/windows.py index a77392561..9b89a8b81 100644 --- a/volatility3/cli/volshell/windows.py +++ b/volatility3/cli/volshell/windows.py @@ -44,10 +44,19 @@ class Volshell(generic.Volshell): ) ) - def get_process(self, pid=None, v_offset=None, p_offset=None): - """Returns the EPROCESS object that matches the pid. If v_offset/p_offset is provided, construct the EPROCESS object at the provided address. Only one parameter is allowed.""" + def get_process(self, pid=None, virtaddr=None, physaddr=None): + """Returns the _EPROCESS object that matches the pid. If a physical or a virtual address is provided, construct the _EPROCESS object at said address. Only one parameter is allowed. - if sum(1 if x is not None else 0 for x in [pid, v_offset, p_offset]) != 1: + Args: + pid (int, optional): PID / UniqueProcessId to search for. + virtaddr (int, optional): Virtual address to construct object at + physaddr (int, optional): Physical address to construct object at + + Returns: + ObjectInterface: _EPROCESS Object + """ + + if sum(1 if x is not None else 0 for x in [pid, virtaddr, physaddr]) != 1: print("Only one parameter is accepted") return None @@ -61,20 +70,20 @@ class Volshell(generic.Volshell): eprocess_symbol = kernel.symbol_table_name + constants.BANG + "_EPROCESS" - if v_offset is not None: + if virtaddr is not None: eproc = self.context.object( eprocess_symbol, layer_name=kernel_layer_name, - offset=v_offset, + offset=virtaddr, ) return eproc - if p_offset is not None: + if physaddr is not None: eproc = self.context.object( eprocess_symbol, layer_name=memory_layer_name, - offset=p_offset, + offset=physaddr, native_layer_name=kernel_layer_name, ) From c10572905f3f3760594db07575534a5805a10fe3 Mon Sep 17 00:00:00 2001 From: Daniel Davidov <35842733+Danking555@users.noreply.github.com> Date: Wed, 22 Jan 2025 10:45:52 +0200 Subject: [PATCH 13/43] Add low stub offset kernel detection reference: Memprocfs and https://www.youtube.com/watch?v=_ShCSth6dWM --- volatility3/framework/automagic/pdbscan.py | 36 ++++++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/volatility3/framework/automagic/pdbscan.py b/volatility3/framework/automagic/pdbscan.py index 729c48063..1ccecf97a 100644 --- a/volatility3/framework/automagic/pdbscan.py +++ b/volatility3/framework/automagic/pdbscan.py @@ -11,6 +11,7 @@ import contextlib import logging import math import os +import struct from typing import Any, Callable, Dict, Iterable, List, Optional, Set, Tuple, Union from volatility3.framework import constants, exceptions, interfaces, layers @@ -376,8 +377,43 @@ class KernelPDBScanner(interfaces.automagic.AutomagicInterface): valid_kernel = (virtual_layer_name, address, res[0]) return valid_kernel + def method_low_stub_offset(self, + context: interfaces.context.ContextInterface, + vlayer: layers.intel.Intel, + progress_callback: constants.ProgressCallback = None, + ) -> Optional[ValidKernelType]: + kernel_hint = 0 + kernel_base = 0 + physical_layer = context.layers.get('memory_layer') + + # try locating kernel base via x64 Low Stub in lower 1MB starting from second page (4KB) + # if "Discard Low Memory" setting is disabled in BIOS, the Low Stub may be at the third/fourth or further pages + for offset in range(0x1000,0x100000, 0x1000): + if 0xffffffffffff00ff & int.from_bytes(physical_layer.read(offset, 0x8), "little") != 0x00000001000600E9: + continue # not _PROCESSOR_START_BLOCK->Jmp + potential_kernel_hint = int.from_bytes(physical_layer.read(offset + 0x70, 0x8), "little") + if (0xfffff80000000003 & potential_kernel_hint) != 0xfffff80000000000: + continue # not _PROCESSOR_START_BLOCK->LmTarget + kernel_hint = potential_kernel_hint & 0xffffffffffff + kernel_base = kernel_hint & (~0x1fffff) & 0xffffffffffff + break + + if kernel_base: + # Scanning 32mb in 2mb chunks for the 'ntoskrnl' base address + while (kernel_base + 0x2000000) > kernel_hint: + for i in range(0, 0x200000, 0x1000): + valid_kernel = self.check_kernel_offset( + context, vlayer, kernel_base, progress_callback + ) + if valid_kernel: + return valid_kernel + kernel_base -= 0x200000 + + return None + # List of methods to be run, in order, to determine the valid kernels methods = [ + method_low_stub_offset, method_kdbg_offset, method_module_offset, method_fixed_mapping, From 34a7dfc72fb3dced313e9a52b73b96dff31b778a Mon Sep 17 00:00:00 2001 From: Abyss Watcher Date: Thu, 23 Jan 2025 10:42:52 +0100 Subject: [PATCH 14/43] split linux modules utilities --- .../symbols/linux/utilities/modules.py | 68 +++++++++++++++++++ 1 file changed, 68 insertions(+) create mode 100644 volatility3/framework/symbols/linux/utilities/modules.py diff --git a/volatility3/framework/symbols/linux/utilities/modules.py b/volatility3/framework/symbols/linux/utilities/modules.py new file mode 100644 index 000000000..ac9b2afaf --- /dev/null +++ b/volatility3/framework/symbols/linux/utilities/modules.py @@ -0,0 +1,68 @@ +from typing import Iterator, List, Tuple + +from volatility3 import framework +from volatility3.framework import constants, interfaces +from volatility3.framework.objects import utility + + +class Modules(interfaces.configuration.VersionableInterface): + """Kernel modules related utilities.""" + + _version = (1, 0, 0) + _required_framework_version = (2, 0, 0) + + framework.require_interface_version(*_required_framework_version) + + @staticmethod + def mask_mods_list( + context: interfaces.context.ContextInterface, + layer_name: str, + mods: Iterator[interfaces.objects.ObjectInterface], + ) -> List[Tuple[str, int, int]]: + """ + A helper function to mask the starting and end address of kernel modules + """ + mask = context.layers[layer_name].address_mask + + return [ + ( + utility.array_to_string(mod.name), + mod.get_module_base() & mask, + (mod.get_module_base() & mask) + mod.get_core_size(), + ) + for mod in mods + ] + + @staticmethod + def lookup_module_address( + context: interfaces.context.ContextInterface, + kernel_module_name: str, + handlers: List[Tuple[str, int, int]], + target_address: int, + ) -> Tuple[str, str]: + """ + Searches between the start and end address of the kernel module using target_address. + Returns the module and symbol name of the address provided. + """ + kernel_module = context.modules[kernel_module_name] + mod_name = "UNKNOWN" + symbol_name = "N/A" + + for name, start, end in handlers: + if start <= target_address <= end: + mod_name = name + if name == constants.linux.KERNEL_NAME: + symbols = list( + kernel_module.get_symbols_by_absolute_location(target_address) + ) + + if len(symbols): + symbol_name = ( + symbols[0].split(constants.BANG)[1] + if constants.BANG in symbols[0] + else symbols[0] + ) + + break + + return mod_name, symbol_name From 43ab0b0c314832742c00f7821cd6f3327529894e Mon Sep 17 00:00:00 2001 From: Abyss Watcher Date: Thu, 23 Jan 2025 10:43:14 +0100 Subject: [PATCH 15/43] add deprecation decorator --- .../framework/configuration/requirements.py | 23 +++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/volatility3/framework/configuration/requirements.py b/volatility3/framework/configuration/requirements.py index 3e3608000..3af5601dc 100644 --- a/volatility3/framework/configuration/requirements.py +++ b/volatility3/framework/configuration/requirements.py @@ -11,6 +11,7 @@ expect to be in the context (such as particular layers or symboltables). import abc import logging import os +import functools from typing import Any, ClassVar, Dict, List, Optional, Set, Tuple, Type from urllib import parse, request @@ -723,3 +724,25 @@ class ModuleRequirement( """Builds the appropriate configuration for the specified requirement.""" return context.modules[value].build_configuration() + + +def deprecated_method(replacement: str, additional_information: str = ""): + """A decorator for marking functions as deprecated. + + Args: + replacement: The replacement function overriding the deprecated API (full path preferred, starting from "volatility3."). String was preferred, for convenience and to prevent import conflicts on caller side. + additional_information: Information appended at the end of the deprecation message + """ + + def decorator(deprecated_func): + @functools.wraps(deprecated_func) + def wrapper(*args, **kwargs): + nonlocal replacement, additional_information + deprecation_msg = f"Method \"{deprecated_func.__module__ + '.' + deprecated_func.__name__}\" is deprecated, use \"{replacement}\" instead. {additional_information}" + vollog.warning(deprecation_msg) + # Return the wrapped function with its original arguments + return deprecated_func(*args, **kwargs) + + return wrapper + + return decorator From 7575aa5d6354419b51d1ac563c1de4db62da0ca1 Mon Sep 17 00:00:00 2001 From: Abyss Watcher Date: Thu, 23 Jan 2025 10:44:20 +0100 Subject: [PATCH 16/43] deprecate lookup_module_address and mask_mods_list --- .../framework/symbols/linux/__init__.py | 101 ++++++++---------- 1 file changed, 44 insertions(+), 57 deletions(-) diff --git a/volatility3/framework/symbols/linux/__init__.py b/volatility3/framework/symbols/linux/__init__.py index 423284b03..3dc744f78 100644 --- a/volatility3/framework/symbols/linux/__init__.py +++ b/volatility3/framework/symbols/linux/__init__.py @@ -8,11 +8,13 @@ import logging from abc import ABC, abstractmethod from typing import Iterator, List, Tuple, Optional, Union +import volatility3.framework.symbols.linux.utilities.modules as linux_utilities_modules from volatility3 import framework from volatility3.framework import constants, exceptions, interfaces, objects from volatility3.framework.objects import utility from volatility3.framework.symbols import intermed from volatility3.framework.symbols.linux import extensions +from volatility3.framework.configuration import requirements vollog = logging.getLogger(__name__) @@ -81,7 +83,7 @@ class LinuxKernelIntermedSymbols(intermed.IntermediateSymbolTable): class LinuxUtilities(interfaces.configuration.VersionableInterface): """Class with multiple useful linux functions.""" - _version = (2, 2, 0) + _version = (2, 2, 1) _required_framework_version = (2, 0, 0) framework.require_interface_version(*_required_framework_version) @@ -338,27 +340,6 @@ class LinuxUtilities(interfaces.configuration.VersionableInterface): yield fd_num, filp, full_path - @classmethod - def mask_mods_list( - cls, - context: interfaces.context.ContextInterface, - layer_name: str, - mods: Iterator[interfaces.objects.ObjectInterface], - ) -> List[Tuple[str, int, int]]: - """ - A helper function to mask the starting and end address of kernel modules - """ - mask = context.layers[layer_name].address_mask - - return [ - ( - utility.array_to_string(mod.name), - mod.get_module_base() & mask, - (mod.get_module_base() & mask) + mod.get_core_size(), - ) - for mod in mods - ] - @classmethod def generate_kernel_handler_info( cls, @@ -382,41 +363,9 @@ class LinuxUtilities(interfaces.configuration.VersionableInterface): return [ (constants.linux.KERNEL_NAME, start_addr, end_addr) - ] + LinuxUtilities.mask_mods_list(context, kernel.layer_name, mods_list) - - @classmethod - def lookup_module_address( - cls, - kernel_module: interfaces.context.ModuleInterface, - handlers: List[Tuple[str, int, int]], - target_address: int, - ): - """ - Searches between the start and end address of the kernel module using target_address. - Returns the module and symbol name of the address provided. - """ - - mod_name = "UNKNOWN" - symbol_name = "N/A" - - for name, start, end in handlers: - if start <= target_address <= end: - mod_name = name - if name == constants.linux.KERNEL_NAME: - symbols = list( - kernel_module.get_symbols_by_absolute_location(target_address) - ) - - if len(symbols): - symbol_name = ( - symbols[0].split(constants.BANG)[1] - if constants.BANG in symbols[0] - else symbols[0] - ) - - break - - return mod_name, symbol_name + ] + linux_utilities_modules.Modules.mask_mods_list( + context, kernel.layer_name, mods_list + ) @classmethod def walk_internal_list(cls, vmlinux, struct_name, list_member, list_start): @@ -504,6 +453,44 @@ class LinuxUtilities(interfaces.configuration.VersionableInterface): [chr((code >> (i * 8)) & 0xFF) for i in range(code_bytes_length)] ) + ## Deprecated APIs ## + @classmethod + @requirements.deprecated_method( + replacement="volatility3.framework.symbols.linux.utilities.modules.Modules.mask_mods_list" + ) + def mask_mods_list( + cls, + context: interfaces.context.ContextInterface, + layer_name: str, + mods: Iterator[interfaces.objects.ObjectInterface], + ) -> List[Tuple[str, int, int]]: + """ + DEPRECATED: use "volatility3.framework.symbols.linux.utilities.modules.Modules.mask_mods_list" instead. + + A helper function to mask the starting and end address of kernel modules + """ + return linux_utilities_modules.Modules.mask_mods_list(context, layer_name, mods) + + @classmethod + @requirements.deprecated_method( + replacement="volatility3.framework.symbols.linux.utilities.modules.Modules.lookup_module_address" + ) + def lookup_module_address( + cls, + kernel_module: interfaces.context.ModuleInterface, + handlers: List[Tuple[str, int, int]], + target_address: int, + ) -> Tuple[str, str]: + """ + DEPRECATED: use "volatility3.framework.symbols.linux.utilities.modules.Modules.lookup_module_address" instead. + + Searches between the start and end address of the kernel module using target_address. + Returns the module and symbol name of the address provided. + """ + return linux_utilities_modules.Modules.lookup_module_address( + kernel_module.context, kernel_module.name, handlers, target_address + ) + class IDStorage(ABC): """Abstraction to support both XArray and RadixTree""" From fd77c041537b40f38db7428ce05a876ad5b1e08b Mon Sep 17 00:00:00 2001 From: Abyss Watcher Date: Thu, 23 Jan 2025 10:46:42 +0100 Subject: [PATCH 17/43] move to linux_utilities_modules APIs --- volatility3/framework/plugins/linux/check_idt.py | 7 +++++-- .../framework/plugins/linux/keyboard_notifiers.py | 7 +++++-- volatility3/framework/plugins/linux/kthreads.py | 9 ++++++--- volatility3/framework/plugins/linux/netfilter.py | 7 +++++-- volatility3/framework/plugins/linux/tty_check.py | 7 +++++-- 5 files changed, 26 insertions(+), 11 deletions(-) diff --git a/volatility3/framework/plugins/linux/check_idt.py b/volatility3/framework/plugins/linux/check_idt.py index 07582e2c1..5859e73d6 100644 --- a/volatility3/framework/plugins/linux/check_idt.py +++ b/volatility3/framework/plugins/linux/check_idt.py @@ -5,6 +5,7 @@ import logging from typing import List +import volatility3.framework.symbols.linux.utilities.modules as linux_utilities_modules from volatility3.framework import interfaces, renderers, symbols from volatility3.framework.configuration import requirements from volatility3.framework.renderers import format_hints @@ -99,8 +100,10 @@ class Check_idt(interfaces.plugins.PluginInterface): idt_addr = idt_addr & address_mask - module_name, symbol_name = linux.LinuxUtilities.lookup_module_address( - vmlinux, handlers, idt_addr + module_name, symbol_name = ( + linux_utilities_modules.Modules.lookup_module_address( + self.context, vmlinux.name, handlers, idt_addr + ) ) yield ( diff --git a/volatility3/framework/plugins/linux/keyboard_notifiers.py b/volatility3/framework/plugins/linux/keyboard_notifiers.py index 72273a77b..c1b7572c6 100644 --- a/volatility3/framework/plugins/linux/keyboard_notifiers.py +++ b/volatility3/framework/plugins/linux/keyboard_notifiers.py @@ -4,6 +4,7 @@ import logging +import volatility3.framework.symbols.linux.utilities.modules as linux_utilities_modules from volatility3.framework import interfaces, renderers, exceptions from volatility3.framework.configuration import requirements from volatility3.framework.renderers import format_hints @@ -66,8 +67,10 @@ class Keyboard_notifiers(interfaces.plugins.PluginInterface): ): call_addr = call_back.notifier_call - module_name, symbol_name = linux.LinuxUtilities.lookup_module_address( - vmlinux, handlers, call_addr + module_name, symbol_name = ( + linux_utilities_modules.Modules.lookup_module_address( + self.context, vmlinux.name, handlers, call_addr + ) ) yield (0, [format_hints.Hex(call_addr), module_name, symbol_name]) diff --git a/volatility3/framework/plugins/linux/kthreads.py b/volatility3/framework/plugins/linux/kthreads.py index 40e992069..2e1bbed47 100644 --- a/volatility3/framework/plugins/linux/kthreads.py +++ b/volatility3/framework/plugins/linux/kthreads.py @@ -4,6 +4,7 @@ import logging from typing import List +import volatility3.framework.symbols.linux.utilities.modules as linux_utilities_modules from volatility3.framework import constants, exceptions, interfaces, renderers from volatility3.framework.configuration import requirements from volatility3.framework.interfaces import plugins @@ -20,7 +21,7 @@ class Kthreads(plugins.PluginInterface): """Enumerates kthread functions""" _required_framework_version = (2, 11, 0) - _version = (1, 0, 2) + _version = (1, 0, 3) @classmethod def get_requirements(cls) -> List[interfaces.configuration.RequirementInterface]: @@ -88,8 +89,10 @@ class Kthreads(plugins.PluginInterface): if kthread.has_member("full_name") else task_name ) - module_name, symbol_name = linux.LinuxUtilities.lookup_module_address( - vmlinux, handlers, threadfn + module_name, symbol_name = ( + linux_utilities_modules.Modules.lookup_module_address( + self.context, vmlinux.name, handlers, threadfn + ) ) fields = [ diff --git a/volatility3/framework/plugins/linux/netfilter.py b/volatility3/framework/plugins/linux/netfilter.py index 73496dfd9..ccb831b61 100644 --- a/volatility3/framework/plugins/linux/netfilter.py +++ b/volatility3/framework/plugins/linux/netfilter.py @@ -5,6 +5,7 @@ from dataclasses import dataclass, field from abc import ABC, abstractmethod import logging +import volatility3.framework.symbols.linux.utilities.modules as linux_utilities_modules from typing import Iterator, List, Tuple from volatility3 import framework from volatility3.framework import ( @@ -263,8 +264,10 @@ class AbstractNetfilter(ABC): """Helper to obtain the module and symbol name in the format needed for the output of this plugin. """ - module_name, symbol_name = linux.LinuxUtilities.lookup_module_address( - self.vmlinux, self.handlers, addr + module_name, symbol_name = ( + linux_utilities_modules.Modules.lookup_module_address( + self._context, self.vmlinux.name, self.handlers, addr + ) ) if module_name == "UNKNOWN": diff --git a/volatility3/framework/plugins/linux/tty_check.py b/volatility3/framework/plugins/linux/tty_check.py index 45238ef8c..f375968a4 100644 --- a/volatility3/framework/plugins/linux/tty_check.py +++ b/volatility3/framework/plugins/linux/tty_check.py @@ -5,6 +5,7 @@ import logging from typing import List +import volatility3.framework.symbols.linux.utilities.modules as linux_utilities_modules from volatility3.framework import interfaces, renderers, exceptions, constants from volatility3.framework.configuration import requirements from volatility3.framework.interfaces import plugins @@ -79,8 +80,10 @@ class tty_check(plugins.PluginInterface): recv_buf = tty_dev.ldisc.ops.receive_buf - module_name, symbol_name = linux.LinuxUtilities.lookup_module_address( - vmlinux, handlers, recv_buf + module_name, symbol_name = ( + linux_utilities_modules.Modules.lookup_module_address( + self.context, vmlinux.name, handlers, recv_buf + ) ) yield (0, (name, format_hints.Hex(recv_buf), module_name, symbol_name)) From b8d9c7b88311016cea97b8b60afeec4d47558af0 Mon Sep 17 00:00:00 2001 From: Dave Lassalle Date: Thu, 23 Jan 2025 11:57:43 -0600 Subject: [PATCH 18/43] #1473 - add missing exception handling for get_key --- volatility3/framework/plugins/windows/envars.py | 12 ++++++------ .../framework/plugins/windows/getservicesids.py | 5 +++-- .../framework/plugins/windows/getsids.py | 2 +- .../plugins/windows/registry/userassist.py | 17 ++++++++++++----- .../framework/plugins/windows/svcscan.py | 6 +++--- 5 files changed, 25 insertions(+), 17 deletions(-) diff --git a/volatility3/framework/plugins/windows/envars.py b/volatility3/framework/plugins/windows/envars.py index cac4ecf40..48e1ef671 100644 --- a/volatility3/framework/plugins/windows/envars.py +++ b/volatility3/framework/plugins/windows/envars.py @@ -76,14 +76,14 @@ class Envars(interfaces.plugins.PluginInterface): "CurrentControlSet\\Control\\Session Manager\\Environment" ) sys = True - except KeyError: - with contextlib.suppress(KeyError): + except (KeyError, registry.RegistryFormatException): + with contextlib.suppress(KeyError, registry.RegistryFormatException): key = hive.get_key( "ControlSet001\\Control\\Session Manager\\Environment" ) sys = True if sys: - with contextlib.suppress(KeyError): + with contextlib.suppress(KeyError, registry.RegistryFormatException): for node in key.get_values(): try: value_node_name = node.get_name() @@ -100,11 +100,11 @@ class Envars(interfaces.plugins.PluginInterface): continue ## The user-specific variables - with contextlib.suppress(KeyError): + with contextlib.suppress(KeyError, registry.RegistryFormatException): key = hive.get_key("Environment") ntuser = True if ntuser: - with contextlib.suppress(KeyError): + with contextlib.suppress(KeyError, registry.RegistryFormatException): for node in key.get_values(): try: value_node_name = node.get_name() @@ -123,7 +123,7 @@ class Envars(interfaces.plugins.PluginInterface): ## The volatile user variables try: key = hive.get_key("Volatile Environment") - except KeyError: + except (KeyError, registry.RegistryFormatException): continue try: for node in key.get_values(): diff --git a/volatility3/framework/plugins/windows/getservicesids.py b/volatility3/framework/plugins/windows/getservicesids.py index eece7fb6c..b97d2bb46 100644 --- a/volatility3/framework/plugins/windows/getservicesids.py +++ b/volatility3/framework/plugins/windows/getservicesids.py @@ -10,6 +10,7 @@ from typing import List from volatility3.framework import renderers, interfaces, constants, exceptions from volatility3.framework.configuration import requirements +from volatility3.framework.layers import registry from volatility3.plugins.windows.registry import hivelist vollog = logging.getLogger(__name__) @@ -86,10 +87,10 @@ class GetServiceSIDs(interfaces.plugins.PluginInterface): # Get ControlSet\Services. try: services = hive.get_key(r"CurrentControlSet\Services") - except (KeyError, exceptions.InvalidAddressException): + except (KeyError, exceptions.InvalidAddressException, registry.RegistryFormatException): try: services = hive.get_key(r"ControlSet001\Services") - except (KeyError, exceptions.InvalidAddressException): + except (KeyError, exceptions.InvalidAddressException, registry.RegistryFormatException): continue if services: diff --git a/volatility3/framework/plugins/windows/getsids.py b/volatility3/framework/plugins/windows/getsids.py index df0c7a835..00c78e1cf 100644 --- a/volatility3/framework/plugins/windows/getsids.py +++ b/volatility3/framework/plugins/windows/getsids.py @@ -158,7 +158,7 @@ class GetSIDs(interfaces.plugins.PluginInterface): layers.registry.RegistryFormatException, ): continue - except (KeyError, exceptions.InvalidAddressException): + except (KeyError, exceptions.InvalidAddressException, layers.registry.RegistryFormatException): continue return sids diff --git a/volatility3/framework/plugins/windows/registry/userassist.py b/volatility3/framework/plugins/windows/registry/userassist.py index 932ee9d6f..646fb1d7f 100644 --- a/volatility3/framework/plugins/windows/registry/userassist.py +++ b/volatility3/framework/plugins/windows/registry/userassist.py @@ -13,7 +13,7 @@ from typing import Any, Generator, List, Tuple from volatility3.framework import constants, exceptions, interfaces, renderers from volatility3.framework.configuration import requirements from volatility3.framework.layers.physical import BufferDataLayer -from volatility3.framework.layers.registry import RegistryHive +from volatility3.framework.layers.registry import RegistryHive, RegistryFormatException from volatility3.framework.renderers import conversion, format_hints from volatility3.framework.symbols import intermed from volatility3.plugins.windows.registry import hivelist @@ -167,10 +167,17 @@ class UserAssist(interfaces.plugins.PluginInterface, timeliner.TimeLinerInterfac self._determine_userassist_type() - userassist_node_path = hive.get_key( - "software\\microsoft\\windows\\currentversion\\explorer\\userassist", - return_list=True, - ) + try: + userassist_node_path = hive.get_key( + "software\\microsoft\\windows\\currentversion\\explorer\\userassist", + return_list=True, + ) + except RegistryFormatException as e: + vollog.warning(f"Error accessing UserAssist key in {hive_name} at {hive.hive_offset:#x}") + return None + except KeyError: + vollog.warning(f"UserAssist key not found in {hive_name} at {hive.hive_offset:#x}") + return None if not userassist_node_path: vollog.warning("list_userassist did not find a valid node_path (or None)") diff --git a/volatility3/framework/plugins/windows/svcscan.py b/volatility3/framework/plugins/windows/svcscan.py index bd477ba27..93087f352 100644 --- a/volatility3/framework/plugins/windows/svcscan.py +++ b/volatility3/framework/plugins/windows/svcscan.py @@ -15,7 +15,7 @@ from volatility3.framework import ( symbols, ) from volatility3.framework.configuration import requirements -from volatility3.framework.layers import scanners +from volatility3.framework.layers import scanners, registry from volatility3.framework.renderers import format_hints from volatility3.framework.symbols import intermed from volatility3.framework.symbols.windows import versions @@ -159,12 +159,12 @@ class SvcScan(interfaces.plugins.PluginInterface): return cast( objects.StructType, hive.get_key(r"CurrentControlSet\Services") ) - except (KeyError, exceptions.InvalidAddressException): + except (KeyError, exceptions.InvalidAddressException, registry.RegistryFormatException): try: return cast( objects.StructType, hive.get_key(r"ControlSet001\Services") ) - except (KeyError, exceptions.InvalidAddressException): + except (KeyError, exceptions.InvalidAddressException, registry.RegistryFormatException): vollog.log( constants.LOGLEVEL_VVVV, "Could not retrieve any control set from SYSTEM hive", From 6c4cafa64f68e6b001cd1ed32e8e5fb3d9993f30 Mon Sep 17 00:00:00 2001 From: Dave Lassalle Date: Thu, 23 Jan 2025 11:59:37 -0600 Subject: [PATCH 19/43] #1473 - black fixes --- .../framework/plugins/windows/getservicesids.py | 12 ++++++++++-- volatility3/framework/plugins/windows/getsids.py | 6 +++++- .../framework/plugins/windows/registry/userassist.py | 8 ++++++-- volatility3/framework/plugins/windows/svcscan.py | 12 ++++++++++-- 4 files changed, 31 insertions(+), 7 deletions(-) diff --git a/volatility3/framework/plugins/windows/getservicesids.py b/volatility3/framework/plugins/windows/getservicesids.py index b97d2bb46..207d0e2ad 100644 --- a/volatility3/framework/plugins/windows/getservicesids.py +++ b/volatility3/framework/plugins/windows/getservicesids.py @@ -87,10 +87,18 @@ class GetServiceSIDs(interfaces.plugins.PluginInterface): # Get ControlSet\Services. try: services = hive.get_key(r"CurrentControlSet\Services") - except (KeyError, exceptions.InvalidAddressException, registry.RegistryFormatException): + except ( + KeyError, + exceptions.InvalidAddressException, + registry.RegistryFormatException, + ): try: services = hive.get_key(r"ControlSet001\Services") - except (KeyError, exceptions.InvalidAddressException, registry.RegistryFormatException): + except ( + KeyError, + exceptions.InvalidAddressException, + registry.RegistryFormatException, + ): continue if services: diff --git a/volatility3/framework/plugins/windows/getsids.py b/volatility3/framework/plugins/windows/getsids.py index 00c78e1cf..a75bbe7ea 100644 --- a/volatility3/framework/plugins/windows/getsids.py +++ b/volatility3/framework/plugins/windows/getsids.py @@ -158,7 +158,11 @@ class GetSIDs(interfaces.plugins.PluginInterface): layers.registry.RegistryFormatException, ): continue - except (KeyError, exceptions.InvalidAddressException, layers.registry.RegistryFormatException): + except ( + KeyError, + exceptions.InvalidAddressException, + layers.registry.RegistryFormatException, + ): continue return sids diff --git a/volatility3/framework/plugins/windows/registry/userassist.py b/volatility3/framework/plugins/windows/registry/userassist.py index 646fb1d7f..d50b5216e 100644 --- a/volatility3/framework/plugins/windows/registry/userassist.py +++ b/volatility3/framework/plugins/windows/registry/userassist.py @@ -173,10 +173,14 @@ class UserAssist(interfaces.plugins.PluginInterface, timeliner.TimeLinerInterfac return_list=True, ) except RegistryFormatException as e: - vollog.warning(f"Error accessing UserAssist key in {hive_name} at {hive.hive_offset:#x}") + vollog.warning( + f"Error accessing UserAssist key in {hive_name} at {hive.hive_offset:#x}" + ) return None except KeyError: - vollog.warning(f"UserAssist key not found in {hive_name} at {hive.hive_offset:#x}") + vollog.warning( + f"UserAssist key not found in {hive_name} at {hive.hive_offset:#x}" + ) return None if not userassist_node_path: diff --git a/volatility3/framework/plugins/windows/svcscan.py b/volatility3/framework/plugins/windows/svcscan.py index 93087f352..17baac5b0 100644 --- a/volatility3/framework/plugins/windows/svcscan.py +++ b/volatility3/framework/plugins/windows/svcscan.py @@ -159,12 +159,20 @@ class SvcScan(interfaces.plugins.PluginInterface): return cast( objects.StructType, hive.get_key(r"CurrentControlSet\Services") ) - except (KeyError, exceptions.InvalidAddressException, registry.RegistryFormatException): + except ( + KeyError, + exceptions.InvalidAddressException, + registry.RegistryFormatException, + ): try: return cast( objects.StructType, hive.get_key(r"ControlSet001\Services") ) - except (KeyError, exceptions.InvalidAddressException, registry.RegistryFormatException): + except ( + KeyError, + exceptions.InvalidAddressException, + registry.RegistryFormatException, + ): vollog.log( constants.LOGLEVEL_VVVV, "Could not retrieve any control set from SYSTEM hive", From 81ba89eef663727608886e66595dfd7b3dcd9831 Mon Sep 17 00:00:00 2001 From: Dave Lassalle Date: Thu, 23 Jan 2025 12:20:14 -0600 Subject: [PATCH 20/43] #1473 - update exception message --- volatility3/framework/plugins/windows/registry/userassist.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/volatility3/framework/plugins/windows/registry/userassist.py b/volatility3/framework/plugins/windows/registry/userassist.py index d50b5216e..87016553a 100644 --- a/volatility3/framework/plugins/windows/registry/userassist.py +++ b/volatility3/framework/plugins/windows/registry/userassist.py @@ -174,7 +174,7 @@ class UserAssist(interfaces.plugins.PluginInterface, timeliner.TimeLinerInterfac ) except RegistryFormatException as e: vollog.warning( - f"Error accessing UserAssist key in {hive_name} at {hive.hive_offset:#x}" + f"Error accessing UserAssist key in {hive_name} at {hive.hive_offset:#x}: {e}" ) return None except KeyError: From a68be50798254cbadc490393721e74180b4117cc Mon Sep 17 00:00:00 2001 From: Mike Auty Date: Thu, 23 Jan 2025 20:30:21 +0000 Subject: [PATCH 21/43] Revert "Typing fix" This reverts commit c82d432b10258136ff0777dfec1fbf5844316132. --- volatility3/framework/__init__.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/volatility3/framework/__init__.py b/volatility3/framework/__init__.py index a1925faef..754939460 100644 --- a/volatility3/framework/__init__.py +++ b/volatility3/framework/__init__.py @@ -5,6 +5,7 @@ # Check the python version to ensure it's suitable import glob import sys +from volatility3.framework import check_python_version as check_python_version import zipfile import importlib import inspect @@ -57,7 +58,7 @@ class NonInheritable: self.default_value = value self.cls = cls - def __get__(self, obj: Any, get_type: Optional[Type] = None) -> Any: + def __get__(self, obj: Any, get_type: Type = Optional[None]) -> Any: if type is self.cls: if hasattr(self.default_value, "__get__"): return self.default_value.__get__(obj, get_type) From 61f60ac464ba01885216704faf37ed6b6fc4beb6 Mon Sep 17 00:00:00 2001 From: Mike Auty Date: Thu, 23 Jan 2025 20:52:08 +0000 Subject: [PATCH 22/43] Core: Move the python check somewhere it can't accidentally be removed --- volatility3/framework/__init__.py | 12 +++++++++++- volatility3/framework/check_python_version.py | 14 -------------- volatility3/framework/constants/__init__.py | 2 ++ 3 files changed, 13 insertions(+), 15 deletions(-) delete mode 100644 volatility3/framework/check_python_version.py diff --git a/volatility3/framework/__init__.py b/volatility3/framework/__init__.py index 754939460..466e697bb 100644 --- a/volatility3/framework/__init__.py +++ b/volatility3/framework/__init__.py @@ -5,7 +5,6 @@ # Check the python version to ensure it's suitable import glob import sys -from volatility3.framework import check_python_version as check_python_version import zipfile import importlib import inspect @@ -16,6 +15,17 @@ from typing import Any, Dict, Generator, List, Optional, Tuple, Type, TypeVar from volatility3.framework import constants, interfaces +if ( + sys.version_info.major != constants.REQUIRED_PYTHON_VERSION[0] + or sys.version_info.minor < constants.REQUIRED_PYTHON_VERSION[1] + or ( + sys.version_info.minor == constants.REQUIRED_PYTHON_VERSION[1] + and sys.version_info.micro < constants.REQUIRED_PYTHON_VERSION[2] + ) +): + raise RuntimeError( + f"Volatility framework requires python version {".".join(str(x) for x in constants.REQUIRED_PYTHON_VERSION)} or greater" + ) # ## # diff --git a/volatility3/framework/check_python_version.py b/volatility3/framework/check_python_version.py deleted file mode 100644 index f2d284f2a..000000000 --- a/volatility3/framework/check_python_version.py +++ /dev/null @@ -1,14 +0,0 @@ -import sys - -required_python_version = (3, 8, 0) -if ( - sys.version_info.major != required_python_version[0] - or sys.version_info.minor < required_python_version[1] - or ( - sys.version_info.minor == required_python_version[1] - and sys.version_info.micro < required_python_version[2] - ) -): - raise RuntimeError( - f"Volatility framework requires python version {required_python_version[0]}.{required_python_version[1]}.{required_python_version[2]} or greater" - ) diff --git a/volatility3/framework/constants/__init__.py b/volatility3/framework/constants/__init__.py index 23cc2dde5..2e6ae0261 100644 --- a/volatility3/framework/constants/__init__.py +++ b/volatility3/framework/constants/__init__.py @@ -23,6 +23,8 @@ from volatility3.framework.constants._version import ( VERSION_SUFFIX as VERSION_SUFFIX, ) +REQUIRED_PYTHON_VERSION = (3, 8, 0) + PLUGINS_PATH = [ os.path.abspath(os.path.join(os.path.dirname(__file__), "..", "..", "plugins")), os.path.abspath(os.path.join(os.path.dirname(__file__), "..", "plugins")), From 128e1be154cc5a9853da3413565685689bf702e5 Mon Sep 17 00:00:00 2001 From: Mike Auty Date: Thu, 23 Jan 2025 20:57:44 +0000 Subject: [PATCH 23/43] Core: Fix f-string quotes --- volatility3/framework/__init__.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/volatility3/framework/__init__.py b/volatility3/framework/__init__.py index 466e697bb..0bbdefa43 100644 --- a/volatility3/framework/__init__.py +++ b/volatility3/framework/__init__.py @@ -24,7 +24,7 @@ if ( ) ): raise RuntimeError( - f"Volatility framework requires python version {".".join(str(x) for x in constants.REQUIRED_PYTHON_VERSION)} or greater" + f"Volatility framework requires python version {'.'.join(str(x) for x in constants.REQUIRED_PYTHON_VERSION)} or greater" ) # ## From 17d52c27bfc31ad9ecad7fb0b8604586039ce2b0 Mon Sep 17 00:00:00 2001 From: Daniel Davidov <35842733+Danking555@users.noreply.github.com> Date: Fri, 24 Jan 2025 21:09:28 +0200 Subject: [PATCH 24/43] Update method_low_stub_offset & run ruff & black * Eliminate unnecessary scanning for 32 bit processors where the structure PROCESSOR_START_BLOCK doesn't exist * Put offsets as values of constants in a class - LowStubLayout. * Add documentation in the class and in the function method_low_stub_offset * Run "ruff check --fix" and "black ." * Checked the method works on 3 physical machines --- volatility3/framework/automagic/pdbscan.py | 74 ++++++++++++++++++---- 1 file changed, 60 insertions(+), 14 deletions(-) diff --git a/volatility3/framework/automagic/pdbscan.py b/volatility3/framework/automagic/pdbscan.py index 1ccecf97a..7d289bcb6 100644 --- a/volatility3/framework/automagic/pdbscan.py +++ b/volatility3/framework/automagic/pdbscan.py @@ -11,7 +11,6 @@ import contextlib import logging import math import os -import struct from typing import Any, Callable, Dict, Iterable, List, Optional, Set, Tuple, Union from volatility3.framework import constants, exceptions, interfaces, layers @@ -377,25 +376,73 @@ class KernelPDBScanner(interfaces.automagic.AutomagicInterface): valid_kernel = (virtual_layer_name, address, res[0]) return valid_kernel - def method_low_stub_offset(self, + class LowStubLayout: + """ + Represents the layout of the Low Stub which exists only on x64 machines with no virtualization/emulation, + responsible for transitioning from Real Mode(16 bit) to Protected Mode(32 bit) and Long Mode(64 bit) on boot/return from sleep. + Contains offsets to fields and structures within the undocumented structure _PROCESSOR_START_BLOCK. + Here's a reference: https://github.com/mic101/windows/blob/master/WRK-v1.2/base/ntos/inc/amd64.h#L3334 + """ + + # Expected signature for validation, constructed from: + # PROCESSOR_START_BLOCK->Jmp->OpCode | PROCESSOR_START_BLOCK->Jmp->Offset | PROCESSOR_START_BLOCK->CompletionFlag + JMP_AND_COMPLETION_SIGNATURE = 0x00000001000600E9 + + # Address of LmTarget (Long Mode target) + PROCESSOR_START_BLOCK_LM_TARGET_OFFSET = ( + 0x70 # PROCESSOR_START_BLOCK->LmTarget, PVOID 8 bytes + ) + + # CR3 register within structures describing initial processor state to be started + PROCESSOR_START_BLOCK_CR3_OFFSET = 0xA0 # PROCESSOR_START_BLOCK->ProcessorState->SpecialRegisters->Cr3, ULONG64 8 bytes + + def method_low_stub_offset( + self, context: interfaces.context.ContextInterface, vlayer: layers.intel.Intel, progress_callback: constants.ProgressCallback = None, ) -> Optional[ValidKernelType]: + # This method is only valid for x64 systems + if not isinstance(vlayer, intel.Intel32e): + return None kernel_hint = 0 kernel_base = 0 - physical_layer = context.layers.get('memory_layer') + physical_layer = context.layers.get("memory_layer") - # try locating kernel base via x64 Low Stub in lower 1MB starting from second page (4KB) - # if "Discard Low Memory" setting is disabled in BIOS, the Low Stub may be at the third/fourth or further pages - for offset in range(0x1000,0x100000, 0x1000): - if 0xffffffffffff00ff & int.from_bytes(physical_layer.read(offset, 0x8), "little") != 0x00000001000600E9: - continue # not _PROCESSOR_START_BLOCK->Jmp - potential_kernel_hint = int.from_bytes(physical_layer.read(offset + 0x70, 0x8), "little") - if (0xfffff80000000003 & potential_kernel_hint) != 0xfffff80000000000: - continue # not _PROCESSOR_START_BLOCK->LmTarget - kernel_hint = potential_kernel_hint & 0xffffffffffff - kernel_base = kernel_hint & (~0x1fffff) & 0xffffffffffff + # Try locating kernel base via x64 Low Stub in lower 1MB starting from second page (4KB) + # If "Discard Low Memory" setting is disabled in BIOS, the Low Stub may be at the third/fourth or further pages + for offset in range(0x1000, 0x100000, 0x1000): + jmp_and_completion_values = int.from_bytes( + physical_layer.read(offset, 0x8), "little" + ) + if ( + 0xFFFFFFFFFFFF00FF & jmp_and_completion_values + != self.LowStubLayout.JMP_AND_COMPLETION_SIGNATURE + ): + continue + cr3_value = int.from_bytes( + physical_layer.read( + offset + self.LowStubLayout.PROCESSOR_START_BLOCK_CR3_OFFSET, 0x8 + ), + "little", + ) + + # Compare previously observed valid page table address that's stored in vlayer._initial_entry + # with PROCESSOR_START_BLOCK->ProcessorState->SpecialRegisters->Cr3 + # which was observed to be an invalid page address, so add 1 (to make it valid too) + if (cr3_value + 1) != vlayer._initial_entry: + continue + potential_kernel_hint = int.from_bytes( + physical_layer.read( + offset + self.LowStubLayout.PROCESSOR_START_BLOCK_LM_TARGET_OFFSET, + 0x8, + ), + "little", + ) + if 0x3 & potential_kernel_hint: + continue + kernel_hint = potential_kernel_hint & 0xFFFFFFFFFFFF + kernel_base = kernel_hint & (~0x1FFFFF) & 0xFFFFFFFFFFFF break if kernel_base: @@ -408,7 +455,6 @@ class KernelPDBScanner(interfaces.automagic.AutomagicInterface): if valid_kernel: return valid_kernel kernel_base -= 0x200000 - return None # List of methods to be run, in order, to determine the valid kernels From e9088be0d86fa2f68774d47371ebd2736287f1c5 Mon Sep 17 00:00:00 2001 From: Andrew Case Date: Sat, 28 Dec 2024 22:46:39 +0000 Subject: [PATCH 25/43] Prevent infinite looping and out of memory errors #1482 --- .../framework/symbols/windows/extensions/registry.py | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/volatility3/framework/symbols/windows/extensions/registry.py b/volatility3/framework/symbols/windows/extensions/registry.py index c9544a8ba..b282b13cf 100644 --- a/volatility3/framework/symbols/windows/extensions/registry.py +++ b/volatility3/framework/symbols/windows/extensions/registry.py @@ -133,8 +133,17 @@ class CM_KEY_BODY(objects.StructType): def get_full_key_name(self) -> str: output = [] + seen = set() + kcb = self.KeyControlBlock while kcb.ParentKcb: + if kcb.ParentKcb.vol.offset in seen: + return "" + seen.add(kcb.ParentKcb.vol.offset) + + if len(output) > 128: + return "" + if kcb.NameBlock.Name is None: break From 506a61d8846e6a3399ab1f964d41b09a197592a6 Mon Sep 17 00:00:00 2001 From: Andrew Case Date: Fri, 24 Jan 2025 22:09:24 +0000 Subject: [PATCH 26/43] Address feedback --- volatility3/framework/plugins/windows/handles.py | 4 ++-- volatility3/framework/symbols/windows/extensions/registry.py | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/volatility3/framework/plugins/windows/handles.py b/volatility3/framework/plugins/windows/handles.py index 38ccfbfbc..6a391fe35 100644 --- a/volatility3/framework/plugins/windows/handles.py +++ b/volatility3/framework/plugins/windows/handles.py @@ -341,7 +341,7 @@ class Handles(interfaces.plugins.PluginInterface): try: obj_name = entry.NameInfo.Name.String except (ValueError, exceptions.InvalidAddressException): - obj_name = "" + obj_name = None except exceptions.InvalidAddressException: vollog.log( @@ -359,7 +359,7 @@ class Handles(interfaces.plugins.PluginInterface): format_hints.Hex(entry.HandleValue), obj_type, format_hints.Hex(entry.GrantedAccess), - obj_name, + obj_name or renderers.NotAvailableValue(), ), ) diff --git a/volatility3/framework/symbols/windows/extensions/registry.py b/volatility3/framework/symbols/windows/extensions/registry.py index b282b13cf..a8cc7703c 100644 --- a/volatility3/framework/symbols/windows/extensions/registry.py +++ b/volatility3/framework/symbols/windows/extensions/registry.py @@ -138,11 +138,11 @@ class CM_KEY_BODY(objects.StructType): kcb = self.KeyControlBlock while kcb.ParentKcb: if kcb.ParentKcb.vol.offset in seen: - return "" + return None seen.add(kcb.ParentKcb.vol.offset) if len(output) > 128: - return "" + return None if kcb.NameBlock.Name is None: break From 8b0165b6f6ea7a6ebb70ddb01b2de29b627ddcfd Mon Sep 17 00:00:00 2001 From: Abyss Watcher Date: Sat, 25 Jan 2025 14:45:21 +0100 Subject: [PATCH 27/43] add linux_utilities_modules requirement --- volatility3/framework/plugins/linux/check_idt.py | 5 +++++ volatility3/framework/plugins/linux/keyboard_notifiers.py | 5 +++++ volatility3/framework/plugins/linux/kthreads.py | 5 +++++ volatility3/framework/plugins/linux/netfilter.py | 5 +++++ volatility3/framework/plugins/linux/tty_check.py | 5 +++++ 5 files changed, 25 insertions(+) diff --git a/volatility3/framework/plugins/linux/check_idt.py b/volatility3/framework/plugins/linux/check_idt.py index 5859e73d6..ffb707af5 100644 --- a/volatility3/framework/plugins/linux/check_idt.py +++ b/volatility3/framework/plugins/linux/check_idt.py @@ -28,6 +28,11 @@ class Check_idt(interfaces.plugins.PluginInterface): description="Linux kernel", architectures=["Intel32", "Intel64"], ), + requirements.VersionRequirement( + name="linux_utilities_modules", + component=linux_utilities_modules.Modules, + version=(1, 0, 0), + ), requirements.VersionRequirement( name="linuxutils", component=linux.LinuxUtilities, version=(2, 0, 0) ), diff --git a/volatility3/framework/plugins/linux/keyboard_notifiers.py b/volatility3/framework/plugins/linux/keyboard_notifiers.py index c1b7572c6..8577de848 100644 --- a/volatility3/framework/plugins/linux/keyboard_notifiers.py +++ b/volatility3/framework/plugins/linux/keyboard_notifiers.py @@ -27,6 +27,11 @@ class Keyboard_notifiers(interfaces.plugins.PluginInterface): description="Linux kernel", architectures=["Intel32", "Intel64"], ), + requirements.VersionRequirement( + name="linux_utilities_modules", + component=linux_utilities_modules.Modules, + version=(1, 0, 0), + ), requirements.PluginRequirement( name="lsmod", plugin=lsmod.Lsmod, version=(2, 0, 0) ), diff --git a/volatility3/framework/plugins/linux/kthreads.py b/volatility3/framework/plugins/linux/kthreads.py index 2e1bbed47..bd0e895a4 100644 --- a/volatility3/framework/plugins/linux/kthreads.py +++ b/volatility3/framework/plugins/linux/kthreads.py @@ -31,6 +31,11 @@ class Kthreads(plugins.PluginInterface): description="Linux kernel", architectures=architectures.LINUX_ARCHS, ), + requirements.VersionRequirement( + name="linux_utilities_modules", + component=linux_utilities_modules.Modules, + version=(1, 0, 0), + ), requirements.VersionRequirement( name="linuxutils", component=linux.LinuxUtilities, version=(2, 1, 0) ), diff --git a/volatility3/framework/plugins/linux/netfilter.py b/volatility3/framework/plugins/linux/netfilter.py index ccb831b61..33a8ca7cc 100644 --- a/volatility3/framework/plugins/linux/netfilter.py +++ b/volatility3/framework/plugins/linux/netfilter.py @@ -691,6 +691,11 @@ class Netfilter(interfaces.plugins.PluginInterface): description="Linux kernel", architectures=["Intel32", "Intel64"], ), + requirements.VersionRequirement( + name="linux_utilities_modules", + component=linux_utilities_modules.Modules, + version=(1, 0, 0), + ), requirements.PluginRequirement( name="lsmod", plugin=lsmod.Lsmod, version=cls._required_lsmod_version ), diff --git a/volatility3/framework/plugins/linux/tty_check.py b/volatility3/framework/plugins/linux/tty_check.py index f375968a4..9bbca246c 100644 --- a/volatility3/framework/plugins/linux/tty_check.py +++ b/volatility3/framework/plugins/linux/tty_check.py @@ -30,6 +30,11 @@ class tty_check(plugins.PluginInterface): description="Linux kernel", architectures=["Intel32", "Intel64"], ), + requirements.VersionRequirement( + name="linux_utilities_modules", + component=linux_utilities_modules.Modules, + version=(1, 0, 0), + ), requirements.PluginRequirement( name="lsmod", plugin=lsmod.Lsmod, version=(2, 0, 0) ), From ce671bb2fa3a7d03042a993814b4c11f19650cf4 Mon Sep 17 00:00:00 2001 From: Abyss Watcher Date: Sat, 25 Jan 2025 15:02:25 +0100 Subject: [PATCH 28/43] transfer deprecated_method into framework module --- volatility3/framework/__init__.py | 29 ++++++++++++++++++- .../framework/configuration/requirements.py | 23 --------------- .../framework/symbols/linux/__init__.py | 17 +++++++---- 3 files changed, 39 insertions(+), 30 deletions(-) diff --git a/volatility3/framework/__init__.py b/volatility3/framework/__init__.py index a1925faef..12254ca77 100644 --- a/volatility3/framework/__init__.py +++ b/volatility3/framework/__init__.py @@ -11,7 +11,8 @@ import inspect import logging import os import traceback -from typing import Any, Dict, Generator, List, Optional, Tuple, Type, TypeVar +import functools +from typing import Any, Callable, Dict, Generator, List, Optional, Tuple, Type, TypeVar from volatility3.framework import constants, interfaces @@ -52,6 +53,32 @@ def require_interface_version(*args) -> None: ) +class Deprecation: + """Deprecation related methods.""" + + @staticmethod + def deprecated_method(replacement: Callable, additional_information: str = ""): + """A decorator for marking functions as deprecated. + + Args: + replacement: The replacement function overriding the deprecated API, in the form of a Callable (typically a method) + additional_information: Information appended at the end of the deprecation message + """ + + def decorator(deprecated_func): + @functools.wraps(deprecated_func) + def wrapper(*args, **kwargs): + nonlocal replacement, additional_information + deprecation_msg = f"Method \"{deprecated_func.__module__ + '.' + deprecated_func.__name__}\" is deprecated, use \"{replacement.__module__ + '.' + replacement.__name__}\" instead. {additional_information}" + vollog.warning(deprecation_msg) + # Return the wrapped function with its original arguments + return deprecated_func(*args, **kwargs) + + return wrapper + + return decorator + + class NonInheritable: def __init__(self, value: Any, cls: Type) -> None: self.default_value = value diff --git a/volatility3/framework/configuration/requirements.py b/volatility3/framework/configuration/requirements.py index 3af5601dc..3e3608000 100644 --- a/volatility3/framework/configuration/requirements.py +++ b/volatility3/framework/configuration/requirements.py @@ -11,7 +11,6 @@ expect to be in the context (such as particular layers or symboltables). import abc import logging import os -import functools from typing import Any, ClassVar, Dict, List, Optional, Set, Tuple, Type from urllib import parse, request @@ -724,25 +723,3 @@ class ModuleRequirement( """Builds the appropriate configuration for the specified requirement.""" return context.modules[value].build_configuration() - - -def deprecated_method(replacement: str, additional_information: str = ""): - """A decorator for marking functions as deprecated. - - Args: - replacement: The replacement function overriding the deprecated API (full path preferred, starting from "volatility3."). String was preferred, for convenience and to prevent import conflicts on caller side. - additional_information: Information appended at the end of the deprecation message - """ - - def decorator(deprecated_func): - @functools.wraps(deprecated_func) - def wrapper(*args, **kwargs): - nonlocal replacement, additional_information - deprecation_msg = f"Method \"{deprecated_func.__module__ + '.' + deprecated_func.__name__}\" is deprecated, use \"{replacement}\" instead. {additional_information}" - vollog.warning(deprecation_msg) - # Return the wrapped function with its original arguments - return deprecated_func(*args, **kwargs) - - return wrapper - - return decorator diff --git a/volatility3/framework/symbols/linux/__init__.py b/volatility3/framework/symbols/linux/__init__.py index 3dc744f78..0b7ef751c 100644 --- a/volatility3/framework/symbols/linux/__init__.py +++ b/volatility3/framework/symbols/linux/__init__.py @@ -10,11 +10,16 @@ from typing import Iterator, List, Tuple, Optional, Union import volatility3.framework.symbols.linux.utilities.modules as linux_utilities_modules from volatility3 import framework -from volatility3.framework import constants, exceptions, interfaces, objects +from volatility3.framework import ( + constants, + exceptions, + interfaces, + objects, + Deprecation, +) from volatility3.framework.objects import utility from volatility3.framework.symbols import intermed from volatility3.framework.symbols.linux import extensions -from volatility3.framework.configuration import requirements vollog = logging.getLogger(__name__) @@ -455,8 +460,8 @@ class LinuxUtilities(interfaces.configuration.VersionableInterface): ## Deprecated APIs ## @classmethod - @requirements.deprecated_method( - replacement="volatility3.framework.symbols.linux.utilities.modules.Modules.mask_mods_list" + @Deprecation.deprecated_method( + replacement=linux_utilities_modules.Modules.mask_mods_list ) def mask_mods_list( cls, @@ -472,8 +477,8 @@ class LinuxUtilities(interfaces.configuration.VersionableInterface): return linux_utilities_modules.Modules.mask_mods_list(context, layer_name, mods) @classmethod - @requirements.deprecated_method( - replacement="volatility3.framework.symbols.linux.utilities.modules.Modules.lookup_module_address" + @Deprecation.deprecated_method( + replacement=linux_utilities_modules.Modules.lookup_module_address ) def lookup_module_address( cls, From 2e1b77f4b3186bae3dfbc7e51e2ba51e9fd850e3 Mon Sep 17 00:00:00 2001 From: Daniel Davidov <35842733+Danking555@users.noreply.github.com> Date: Sat, 25 Jan 2025 16:22:49 +0200 Subject: [PATCH 29/43] Move LowStubLayout constants to windows.constants * Moved constants out of the class and moved to constants.windows * Applied ruff and black --- volatility3/framework/automagic/pdbscan.py | 26 +++---------------- .../framework/constants/windows/__init__.py | 18 +++++++++++++ 2 files changed, 21 insertions(+), 23 deletions(-) diff --git a/volatility3/framework/automagic/pdbscan.py b/volatility3/framework/automagic/pdbscan.py index 7d289bcb6..f9c0d853d 100644 --- a/volatility3/framework/automagic/pdbscan.py +++ b/volatility3/framework/automagic/pdbscan.py @@ -376,26 +376,6 @@ class KernelPDBScanner(interfaces.automagic.AutomagicInterface): valid_kernel = (virtual_layer_name, address, res[0]) return valid_kernel - class LowStubLayout: - """ - Represents the layout of the Low Stub which exists only on x64 machines with no virtualization/emulation, - responsible for transitioning from Real Mode(16 bit) to Protected Mode(32 bit) and Long Mode(64 bit) on boot/return from sleep. - Contains offsets to fields and structures within the undocumented structure _PROCESSOR_START_BLOCK. - Here's a reference: https://github.com/mic101/windows/blob/master/WRK-v1.2/base/ntos/inc/amd64.h#L3334 - """ - - # Expected signature for validation, constructed from: - # PROCESSOR_START_BLOCK->Jmp->OpCode | PROCESSOR_START_BLOCK->Jmp->Offset | PROCESSOR_START_BLOCK->CompletionFlag - JMP_AND_COMPLETION_SIGNATURE = 0x00000001000600E9 - - # Address of LmTarget (Long Mode target) - PROCESSOR_START_BLOCK_LM_TARGET_OFFSET = ( - 0x70 # PROCESSOR_START_BLOCK->LmTarget, PVOID 8 bytes - ) - - # CR3 register within structures describing initial processor state to be started - PROCESSOR_START_BLOCK_CR3_OFFSET = 0xA0 # PROCESSOR_START_BLOCK->ProcessorState->SpecialRegisters->Cr3, ULONG64 8 bytes - def method_low_stub_offset( self, context: interfaces.context.ContextInterface, @@ -417,12 +397,12 @@ class KernelPDBScanner(interfaces.automagic.AutomagicInterface): ) if ( 0xFFFFFFFFFFFF00FF & jmp_and_completion_values - != self.LowStubLayout.JMP_AND_COMPLETION_SIGNATURE + != constants.windows.JMP_AND_COMPLETION_SIGNATURE ): continue cr3_value = int.from_bytes( physical_layer.read( - offset + self.LowStubLayout.PROCESSOR_START_BLOCK_CR3_OFFSET, 0x8 + offset + constants.windows.PROCESSOR_START_BLOCK_CR3_OFFSET, 0x8 ), "little", ) @@ -434,7 +414,7 @@ class KernelPDBScanner(interfaces.automagic.AutomagicInterface): continue potential_kernel_hint = int.from_bytes( physical_layer.read( - offset + self.LowStubLayout.PROCESSOR_START_BLOCK_LM_TARGET_OFFSET, + offset + constants.windows.PROCESSOR_START_BLOCK_LM_TARGET_OFFSET, 0x8, ), "little", diff --git a/volatility3/framework/constants/windows/__init__.py b/volatility3/framework/constants/windows/__init__.py index 7face984a..6f37acd2d 100644 --- a/volatility3/framework/constants/windows/__init__.py +++ b/volatility3/framework/constants/windows/__init__.py @@ -10,3 +10,21 @@ KERNEL_MODULE_NAMES = ["ntkrnlmp", "ntkrnlpa", "ntkrpamp", "ntoskrnl"] """The list of names that kernel modules can have within the windows OS""" PE_MAX_EXTRACTION_SIZE = 1024 * 1024 * 256 + +""" +The following constants represent the layout of the Low Stub which exists only on x64 machines with no virtualization/emulation, +responsible for transitioning from Real Mode(16 bit) to Protected Mode(32 bit) and Long Mode(64 bit) on boot/return from sleep. +Contains offsets to fields and structures within the undocumented structure _PROCESSOR_START_BLOCK. +Here's a reference: https://github.com/mic101/windows/blob/master/WRK-v1.2/base/ntos/inc/amd64.h#L3334 +""" +# Expected signature for validation, constructed from: +# PROCESSOR_START_BLOCK->Jmp->OpCode | PROCESSOR_START_BLOCK->Jmp->Offset | PROCESSOR_START_BLOCK->CompletionFlag +JMP_AND_COMPLETION_SIGNATURE = 0x00000001000600E9 + +# Address of LmTarget (Long Mode target) +PROCESSOR_START_BLOCK_LM_TARGET_OFFSET = ( + 0x70 # PROCESSOR_START_BLOCK->LmTarget, PVOID 8 bytes +) + +# CR3 register within structures describing initial processor state to be started +PROCESSOR_START_BLOCK_CR3_OFFSET = 0xA0 # PROCESSOR_START_BLOCK->ProcessorState->SpecialRegisters->Cr3, ULONG64 8 bytes From d8658f0729f7abbd8410f76571aad6369deabee6 Mon Sep 17 00:00:00 2001 From: Abyss Watcher Date: Sat, 25 Jan 2025 17:08:27 +0100 Subject: [PATCH 30/43] put deprecated functions order back --- .../framework/symbols/linux/__init__.py | 75 +++++++++---------- 1 file changed, 37 insertions(+), 38 deletions(-) diff --git a/volatility3/framework/symbols/linux/__init__.py b/volatility3/framework/symbols/linux/__init__.py index 0b7ef751c..bc2492f7a 100644 --- a/volatility3/framework/symbols/linux/__init__.py +++ b/volatility3/framework/symbols/linux/__init__.py @@ -345,6 +345,23 @@ class LinuxUtilities(interfaces.configuration.VersionableInterface): yield fd_num, filp, full_path + @classmethod + @Deprecation.deprecated_method( + replacement=linux_utilities_modules.Modules.mask_mods_list + ) + def mask_mods_list( + cls, + context: interfaces.context.ContextInterface, + layer_name: str, + mods: Iterator[interfaces.objects.ObjectInterface], + ) -> List[Tuple[str, int, int]]: + """ + DEPRECATED: use "volatility3.framework.symbols.linux.utilities.modules.Modules.mask_mods_list" instead. + + A helper function to mask the starting and end address of kernel modules + """ + return linux_utilities_modules.Modules.mask_mods_list(context, layer_name, mods) + @classmethod def generate_kernel_handler_info( cls, @@ -372,6 +389,26 @@ class LinuxUtilities(interfaces.configuration.VersionableInterface): context, kernel.layer_name, mods_list ) + @classmethod + @Deprecation.deprecated_method( + replacement=linux_utilities_modules.Modules.lookup_module_address + ) + def lookup_module_address( + cls, + kernel_module: interfaces.context.ModuleInterface, + handlers: List[Tuple[str, int, int]], + target_address: int, + ) -> Tuple[str, str]: + """ + DEPRECATED: use "volatility3.framework.symbols.linux.utilities.modules.Modules.lookup_module_address" instead. + + Searches between the start and end address of the kernel module using target_address. + Returns the module and symbol name of the address provided. + """ + return linux_utilities_modules.Modules.lookup_module_address( + kernel_module.context, kernel_module.name, handlers, target_address + ) + @classmethod def walk_internal_list(cls, vmlinux, struct_name, list_member, list_start): while list_start: @@ -458,44 +495,6 @@ class LinuxUtilities(interfaces.configuration.VersionableInterface): [chr((code >> (i * 8)) & 0xFF) for i in range(code_bytes_length)] ) - ## Deprecated APIs ## - @classmethod - @Deprecation.deprecated_method( - replacement=linux_utilities_modules.Modules.mask_mods_list - ) - def mask_mods_list( - cls, - context: interfaces.context.ContextInterface, - layer_name: str, - mods: Iterator[interfaces.objects.ObjectInterface], - ) -> List[Tuple[str, int, int]]: - """ - DEPRECATED: use "volatility3.framework.symbols.linux.utilities.modules.Modules.mask_mods_list" instead. - - A helper function to mask the starting and end address of kernel modules - """ - return linux_utilities_modules.Modules.mask_mods_list(context, layer_name, mods) - - @classmethod - @Deprecation.deprecated_method( - replacement=linux_utilities_modules.Modules.lookup_module_address - ) - def lookup_module_address( - cls, - kernel_module: interfaces.context.ModuleInterface, - handlers: List[Tuple[str, int, int]], - target_address: int, - ) -> Tuple[str, str]: - """ - DEPRECATED: use "volatility3.framework.symbols.linux.utilities.modules.Modules.lookup_module_address" instead. - - Searches between the start and end address of the kernel module using target_address. - Returns the module and symbol name of the address provided. - """ - return linux_utilities_modules.Modules.lookup_module_address( - kernel_module.context, kernel_module.name, handlers, target_address - ) - class IDStorage(ABC): """Abstraction to support both XArray and RadixTree""" From 825720ed5d8f290b244735c758149e5b9d208c12 Mon Sep 17 00:00:00 2001 From: Abyss Watcher Date: Sat, 25 Jan 2025 19:48:31 +0100 Subject: [PATCH 31/43] catch UnsatisfiedException at plugin runtime --- volatility3/cli/__init__.py | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/volatility3/cli/__init__.py b/volatility3/cli/__init__.py index 82a2a4205..d3ce74847 100644 --- a/volatility3/cli/__init__.py +++ b/volatility3/cli/__init__.py @@ -500,6 +500,16 @@ class CommandLine: renderer.filter = text_filter.CLIFilter(grid, args.filters) renderer.column_hide_list = args.hide_columns renderer.render(grid) + except exceptions.UnsatisfiedException as excp: + output = sys.stderr + output.write( + "An unsatisfied framework exception was encountered post plugin construction:\n" + ) + self.process_unsatisfied_exceptions(excp) + output.write( + f"Unable to validate the requirements: {[x for x in excp.unsatisfied]}\n", + ) + sys.exit(1) except exceptions.VolatilityException as excp: self.process_exceptions(excp) From 2ed00cc91a6764d05162c01055fc17c18124c6aa Mon Sep 17 00:00:00 2001 From: Abyss Watcher Date: Sat, 25 Jan 2025 19:52:47 +0100 Subject: [PATCH 32/43] add optional version requirement to deprecated_method --- volatility3/framework/__init__.py | 56 ++++++++++++++++++++++++++++--- 1 file changed, 51 insertions(+), 5 deletions(-) diff --git a/volatility3/framework/__init__.py b/volatility3/framework/__init__.py index 12254ca77..bf4ec4447 100644 --- a/volatility3/framework/__init__.py +++ b/volatility3/framework/__init__.py @@ -12,9 +12,11 @@ import logging import os import traceback import functools +import warnings from typing import Any, Callable, Dict, Generator, List, Optional, Tuple, Type, TypeVar -from volatility3.framework import constants, interfaces +from volatility3.framework import constants, exceptions, interfaces +from volatility3.framework.configuration import requirements # ## @@ -57,20 +59,64 @@ class Deprecation: """Deprecation related methods.""" @staticmethod - def deprecated_method(replacement: Callable, additional_information: str = ""): + def deprecated_method( + replacement: Callable, + replacement_base_class_required_version: Tuple[int, int, int] = None, + additional_information: str = "", + ): """A decorator for marking functions as deprecated. Args: replacement: The replacement function overriding the deprecated API, in the form of a Callable (typically a method) + replacement_base_class_required_version: The "replacement" base class version that the deprecated method expects before proxying to it. This implies that "replacement" is a method from a class that inherits from VersionableInterface. additional_information: Information appended at the end of the deprecation message """ def decorator(deprecated_func): @functools.wraps(deprecated_func) def wrapper(*args, **kwargs): - nonlocal replacement, additional_information - deprecation_msg = f"Method \"{deprecated_func.__module__ + '.' + deprecated_func.__name__}\" is deprecated, use \"{replacement.__module__ + '.' + replacement.__name__}\" instead. {additional_information}" - vollog.warning(deprecation_msg) + nonlocal replacement, replacement_base_class_required_version, additional_information + # Prevent version mismatches between deprecated (proxy) methods and the ones they proxy + if replacement_base_class_required_version is not None and callable( + replacement + ): + # example: replacement = volatility3.MyClass.my_dummy_function + # "MyClass.my_dummy_function" -> "MyClass" + replacement_base_class_name = replacement.__qualname__.split(".")[0] + # replacement.__globals__ example: {'MyClass': } + replacement_base_class = replacement.__globals__.get( + replacement_base_class_name + ) + + # Verify that the base class inherits from VersionableInterface + if inspect.isclass(replacement_base_class) and issubclass( + replacement_base_class, + interfaces.configuration.VersionableInterface, + ): + # Construct a requirement + req = requirements.VersionRequirement( + name=replacement_base_class.__name__, + component=replacement_base_class, + version=replacement_base_class_required_version, + ) + # Verify the requirement + if not req.matches_required( + req._version, req._component.version + ): + full_unsat_req_path = ( + deprecated_func.__module__ + + "." + + deprecated_func.__qualname__ + + "." + + req.name + ) + # Catched by the cli and redirected to process_unsatisfied_exceptions + raise exceptions.UnsatisfiedException( + {full_unsat_req_path: req} + ) + + deprecation_msg = f"Method \"{deprecated_func.__module__ + '.' + deprecated_func.__qualname__}\" is deprecated, use \"{replacement.__module__ + '.' + replacement.__qualname__}\" instead. {additional_information}" + warnings.warn(deprecation_msg, FutureWarning) # Return the wrapped function with its original arguments return deprecated_func(*args, **kwargs) From 3657c6fe5e8db92b1a6364a962b778a89e802624 Mon Sep 17 00:00:00 2001 From: Abyss Watcher Date: Sat, 25 Jan 2025 19:54:20 +0100 Subject: [PATCH 33/43] require Modules >= 1.0.0 on deprecated methods --- volatility3/framework/symbols/linux/__init__.py | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/volatility3/framework/symbols/linux/__init__.py b/volatility3/framework/symbols/linux/__init__.py index bc2492f7a..6a01efc3a 100644 --- a/volatility3/framework/symbols/linux/__init__.py +++ b/volatility3/framework/symbols/linux/__init__.py @@ -347,7 +347,8 @@ class LinuxUtilities(interfaces.configuration.VersionableInterface): @classmethod @Deprecation.deprecated_method( - replacement=linux_utilities_modules.Modules.mask_mods_list + replacement=linux_utilities_modules.Modules.mask_mods_list, + replacement_base_class_required_version=(1, 0, 0), ) def mask_mods_list( cls, @@ -391,7 +392,8 @@ class LinuxUtilities(interfaces.configuration.VersionableInterface): @classmethod @Deprecation.deprecated_method( - replacement=linux_utilities_modules.Modules.lookup_module_address + replacement=linux_utilities_modules.Modules.lookup_module_address, + replacement_base_class_required_version=(1, 0, 0), ) def lookup_module_address( cls, From 4262eff8898b3fbc017abe3c1d1e4f13fa6fb189 Mon Sep 17 00:00:00 2001 From: Abyss Watcher Date: Sat, 25 Jan 2025 20:04:51 +0100 Subject: [PATCH 34/43] adhere to AbstractNetfilter requirement checking --- .../framework/plugins/linux/netfilter.py | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) diff --git a/volatility3/framework/plugins/linux/netfilter.py b/volatility3/framework/plugins/linux/netfilter.py index 33a8ca7cc..ccb7509aa 100644 --- a/volatility3/framework/plugins/linux/netfilter.py +++ b/volatility3/framework/plugins/linux/netfilter.py @@ -99,6 +99,20 @@ class AbstractNetfilter(ABC): f"linux.LinuxUtilities version not suitable: required {linuxutils_required_version} found {linuxutils_current_version}" ) + linux_utilities_modules_required_version = ( + Netfilter._required_linux_utilities_modules_version + ) + linux_utilities_modules_current_version = ( + linux_utilities_modules.Modules._version + ) + if not requirements.VersionRequirement.matches_required( + linux_utilities_modules_required_version, + linux_utilities_modules_current_version, + ): + raise exceptions.PluginRequirementException( + f"linux_utilities_modules.Modules version not suitable: required {linux_utilities_modules_required_version} found {linux_utilities_modules_current_version}" + ) + modules = lsmod.Lsmod.list_modules(context, kernel_module_name) self.handlers = linux.LinuxUtilities.generate_kernel_handler_info( context, kernel_module_name, modules @@ -680,6 +694,7 @@ class Netfilter(interfaces.plugins.PluginInterface): _version = (1, 1, 0) + _required_linux_utilities_modules_version = (1, 0, 0) _required_linuxutils_version = (2, 1, 0) _required_lsmod_version = (2, 0, 0) @@ -694,7 +709,7 @@ class Netfilter(interfaces.plugins.PluginInterface): requirements.VersionRequirement( name="linux_utilities_modules", component=linux_utilities_modules.Modules, - version=(1, 0, 0), + version=cls._required_linux_utilities_modules_version, ), requirements.PluginRequirement( name="lsmod", plugin=lsmod.Lsmod, version=cls._required_lsmod_version From 6d43dcd3a842d308705f3ecd3c023c94be473846 Mon Sep 17 00:00:00 2001 From: Abyss Watcher Date: Sun, 26 Jan 2025 10:31:46 +0100 Subject: [PATCH 35/43] add VersionMismatchException --- volatility3/framework/exceptions.py | 31 ++++++++++++++++++++++++++++- 1 file changed, 30 insertions(+), 1 deletion(-) diff --git a/volatility3/framework/exceptions.py b/volatility3/framework/exceptions.py index 41c67b88d..0409ae5f0 100644 --- a/volatility3/framework/exceptions.py +++ b/volatility3/framework/exceptions.py @@ -8,9 +8,10 @@ space or symbol tables, and by layers when an address is invalid. The :class:`PagedInvalidAddressException` contains information about the size of the invalid page. """ -from typing import Dict, Optional +from typing import Callable, Dict, Optional, Tuple from volatility3.framework import interfaces +from volatility3.framework.interfaces.configuration import VersionableInterface class VolatilityException(Exception): @@ -134,3 +135,31 @@ class RenderException(VolatilityException): class LinuxPageCacheException(VolatilityException): """Thrown if there is an error during Linux Page Cache processing""" + + +class VersionMismatchException(VolatilityException): + """Thrown if a version mismatch has been encountered between two components.""" + + def __init__( + self, + source_component: Callable, + target_component: VersionableInterface, + target_version: Tuple[int, int, int], + failure_reason: str = None, + *args, + ): + """ + Args: + source_component: The component that required the target component + target_component: The component that is required. Must inherit from VersionableInterface + target_version: The version of the target component that was required, and ultimately was not satisfied + failure_reason: A detailed failure reason to enhande debugging and bug tracking + """ + super().__init__(*args) + self.source_component = source_component + self.target_component = target_component + self.target_version = target_version + self.failure_reason = failure_reason + + def __str__(self): + return f"{self.source_component.__module__+ '.' + self.source_component.__qualname__}: Version {self.target_version} dependency on {self.target_component.__module__+ '.' + self.target_component.__qualname__} {self.target_component.version} unmet." From 4bd385cc9dadbfe8800fddc2bce9cef1ae4dadd5 Mon Sep 17 00:00:00 2001 From: Abyss Watcher Date: Sun, 26 Jan 2025 10:33:02 +0100 Subject: [PATCH 36/43] handle VersionMismatchException --- volatility3/cli/__init__.py | 28 +++++++++++----------------- 1 file changed, 11 insertions(+), 17 deletions(-) diff --git a/volatility3/cli/__init__.py b/volatility3/cli/__init__.py index d3ce74847..b57d9a3f3 100644 --- a/volatility3/cli/__init__.py +++ b/volatility3/cli/__init__.py @@ -500,16 +500,6 @@ class CommandLine: renderer.filter = text_filter.CLIFilter(grid, args.filters) renderer.column_hide_list = args.hide_columns renderer.render(grid) - except exceptions.UnsatisfiedException as excp: - output = sys.stderr - output.write( - "An unsatisfied framework exception was encountered post plugin construction:\n" - ) - self.process_unsatisfied_exceptions(excp) - output.write( - f"Unable to validate the requirements: {[x for x in excp.unsatisfied]}\n", - ) - sys.exit(1) except exceptions.VolatilityException as excp: self.process_exceptions(excp) @@ -583,6 +573,8 @@ class CommandLine: fulltrace = traceback.TracebackException.from_exception(excp).format(chain=True) vollog.debug("".join(fulltrace)) + file_a_bug_msg = f"Please re-run with -vvv and file a bug with the output at {constants.BUG_URL}" + if isinstance(excp, exceptions.InvalidAddressException): general = "Volatility was unable to read a requested page:" if isinstance(excp, exceptions.SwappedInvalidAddressException): @@ -627,9 +619,7 @@ class CommandLine: elif isinstance(excp, exceptions.LayerException): general = f"Volatility experienced a layer-related issue: {excp.layer_name}" detail = f"{excp}" - caused_by = [ - "A faulty layer implementation (re-run with -vvv and file a bug)" - ] + caused_by = [f"A faulty layer implementation. {file_a_bug_msg}"] elif isinstance(excp, exceptions.MissingModuleException): general = f"Volatility could not import a necessary module: {excp.module}" detail = f"{excp}" @@ -640,13 +630,17 @@ class CommandLine: general = "Volatility experienced an issue when rendering the output:" detail = f"{excp}" caused_by = ["An invalid renderer option, such as no visible columns"] + elif isinstance(excp, exceptions.VersionMismatchException): + general = "A version mismatch was detected between two components:" + detail = f"{excp}" + caused_by = [ + excp.failure_reason or "An outdated API caller, such as a method.", + file_a_bug_msg, + ] else: general = "Volatility encountered an unexpected situation." detail = "" - caused_by = [ - "Please re-run using with -vvv and file a bug with the output", - f"at {constants.BUG_URL}", - ] + caused_by = [file_a_bug_msg] # Code that actually renders the exception output = sys.stderr From ba6b709aba9496f75a61a806f06719189ac97491 Mon Sep 17 00:00:00 2001 From: Abyss Watcher Date: Sun, 26 Jan 2025 10:34:18 +0100 Subject: [PATCH 37/43] use VersionMismatchException --- volatility3/framework/__init__.py | 37 ++++++++++--------------------- 1 file changed, 12 insertions(+), 25 deletions(-) diff --git a/volatility3/framework/__init__.py b/volatility3/framework/__init__.py index bf4ec4447..5d4e0f3c4 100644 --- a/volatility3/framework/__init__.py +++ b/volatility3/framework/__init__.py @@ -61,25 +61,23 @@ class Deprecation: @staticmethod def deprecated_method( replacement: Callable, - replacement_base_class_required_version: Tuple[int, int, int] = None, + replacement_version: Tuple[int, int, int] = None, additional_information: str = "", ): """A decorator for marking functions as deprecated. Args: replacement: The replacement function overriding the deprecated API, in the form of a Callable (typically a method) - replacement_base_class_required_version: The "replacement" base class version that the deprecated method expects before proxying to it. This implies that "replacement" is a method from a class that inherits from VersionableInterface. + replacement_version: The "replacement" base class version that the deprecated method expects before proxying to it. This implies that "replacement" is a method from a class that inherits from VersionableInterface. additional_information: Information appended at the end of the deprecation message """ def decorator(deprecated_func): @functools.wraps(deprecated_func) def wrapper(*args, **kwargs): - nonlocal replacement, replacement_base_class_required_version, additional_information + nonlocal replacement, replacement_version, additional_information # Prevent version mismatches between deprecated (proxy) methods and the ones they proxy - if replacement_base_class_required_version is not None and callable( - replacement - ): + if replacement_version is not None and callable(replacement): # example: replacement = volatility3.MyClass.my_dummy_function # "MyClass.my_dummy_function" -> "MyClass" replacement_base_class_name = replacement.__qualname__.split(".")[0] @@ -93,26 +91,15 @@ class Deprecation: replacement_base_class, interfaces.configuration.VersionableInterface, ): - # Construct a requirement - req = requirements.VersionRequirement( - name=replacement_base_class.__name__, - component=replacement_base_class, - version=replacement_base_class_required_version, - ) - # Verify the requirement - if not req.matches_required( - req._version, req._component.version + # SemVer check + if not requirements.VersionRequirement.matches_required( + replacement_version, replacement_base_class.version ): - full_unsat_req_path = ( - deprecated_func.__module__ - + "." - + deprecated_func.__qualname__ - + "." - + req.name - ) - # Catched by the cli and redirected to process_unsatisfied_exceptions - raise exceptions.UnsatisfiedException( - {full_unsat_req_path: req} + raise exceptions.VersionMismatchException( + deprecated_func, + replacement_base_class, + replacement_version, + "A deprecated method was unable to proxy the call to its replacement", ) deprecation_msg = f"Method \"{deprecated_func.__module__ + '.' + deprecated_func.__qualname__}\" is deprecated, use \"{replacement.__module__ + '.' + replacement.__qualname__}\" instead. {additional_information}" From 28081ed989599bc395b190cf503e8d83ef5b8fed Mon Sep 17 00:00:00 2001 From: Abyss Watcher Date: Sun, 26 Jan 2025 10:35:25 +0100 Subject: [PATCH 38/43] tidy up replacement_base_class_required_version --- volatility3/framework/symbols/linux/__init__.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/volatility3/framework/symbols/linux/__init__.py b/volatility3/framework/symbols/linux/__init__.py index 6a01efc3a..397c36c01 100644 --- a/volatility3/framework/symbols/linux/__init__.py +++ b/volatility3/framework/symbols/linux/__init__.py @@ -348,7 +348,7 @@ class LinuxUtilities(interfaces.configuration.VersionableInterface): @classmethod @Deprecation.deprecated_method( replacement=linux_utilities_modules.Modules.mask_mods_list, - replacement_base_class_required_version=(1, 0, 0), + replacement_version=(1, 0, 0), ) def mask_mods_list( cls, @@ -393,7 +393,7 @@ class LinuxUtilities(interfaces.configuration.VersionableInterface): @classmethod @Deprecation.deprecated_method( replacement=linux_utilities_modules.Modules.lookup_module_address, - replacement_base_class_required_version=(1, 0, 0), + replacement_version=(1, 0, 0), ) def lookup_module_address( cls, From 459483651b847241cb4189c4d1449fd18c0bdca7 Mon Sep 17 00:00:00 2001 From: Abyss Watcher Date: Sun, 26 Jan 2025 10:53:33 +0100 Subject: [PATCH 39/43] typo --- volatility3/framework/exceptions.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/volatility3/framework/exceptions.py b/volatility3/framework/exceptions.py index 0409ae5f0..99c5f155e 100644 --- a/volatility3/framework/exceptions.py +++ b/volatility3/framework/exceptions.py @@ -153,7 +153,7 @@ class VersionMismatchException(VolatilityException): source_component: The component that required the target component target_component: The component that is required. Must inherit from VersionableInterface target_version: The version of the target component that was required, and ultimately was not satisfied - failure_reason: A detailed failure reason to enhande debugging and bug tracking + failure_reason: A detailed failure reason to enhance debugging and bug tracking """ super().__init__(*args) self.source_component = source_component From 80eebd2f49bee665f194e4adba92cf12a192a997 Mon Sep 17 00:00:00 2001 From: Abyss Watcher Date: Sun, 26 Jan 2025 13:18:30 +0100 Subject: [PATCH 40/43] use classmethod instead of staticmethod --- volatility3/framework/symbols/linux/utilities/modules.py | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/volatility3/framework/symbols/linux/utilities/modules.py b/volatility3/framework/symbols/linux/utilities/modules.py index ac9b2afaf..82c63fc18 100644 --- a/volatility3/framework/symbols/linux/utilities/modules.py +++ b/volatility3/framework/symbols/linux/utilities/modules.py @@ -13,8 +13,9 @@ class Modules(interfaces.configuration.VersionableInterface): framework.require_interface_version(*_required_framework_version) - @staticmethod + @classmethod def mask_mods_list( + cls, context: interfaces.context.ContextInterface, layer_name: str, mods: Iterator[interfaces.objects.ObjectInterface], @@ -33,8 +34,9 @@ class Modules(interfaces.configuration.VersionableInterface): for mod in mods ] - @staticmethod + @classmethod def lookup_module_address( + cls, context: interfaces.context.ContextInterface, kernel_module_name: str, handlers: List[Tuple[str, int, int]], From 5d58ba63dbd6a60fd36faca6f23a3a1b4a11e724 Mon Sep 17 00:00:00 2001 From: Abyss Watcher Date: Sun, 26 Jan 2025 13:19:01 +0100 Subject: [PATCH 41/43] use __name__ instead of overkill __qualname__ --- volatility3/framework/exceptions.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/volatility3/framework/exceptions.py b/volatility3/framework/exceptions.py index 99c5f155e..a3d660444 100644 --- a/volatility3/framework/exceptions.py +++ b/volatility3/framework/exceptions.py @@ -162,4 +162,4 @@ class VersionMismatchException(VolatilityException): self.failure_reason = failure_reason def __str__(self): - return f"{self.source_component.__module__+ '.' + self.source_component.__qualname__}: Version {self.target_version} dependency on {self.target_component.__module__+ '.' + self.target_component.__qualname__} {self.target_component.version} unmet." + return f"{self.source_component.__module__+ '.' + self.source_component.__qualname__}: Version {self.target_version} dependency on {self.target_component.__module__+ '.' + self.target_component.__name__} {self.target_component.version} unmet." From 4cb386858ebe7c62f05b16c9f869fdf762084121 Mon Sep 17 00:00:00 2001 From: Abyss Watcher Date: Sun, 26 Jan 2025 13:20:48 +0100 Subject: [PATCH 42/43] use __self__ and enhance exception msg --- volatility3/framework/__init__.py | 16 +++++++--------- 1 file changed, 7 insertions(+), 9 deletions(-) diff --git a/volatility3/framework/__init__.py b/volatility3/framework/__init__.py index 5d4e0f3c4..aa93340cd 100644 --- a/volatility3/framework/__init__.py +++ b/volatility3/framework/__init__.py @@ -77,14 +77,12 @@ class Deprecation: def wrapper(*args, **kwargs): nonlocal replacement, replacement_version, additional_information # Prevent version mismatches between deprecated (proxy) methods and the ones they proxy - if replacement_version is not None and callable(replacement): - # example: replacement = volatility3.MyClass.my_dummy_function - # "MyClass.my_dummy_function" -> "MyClass" - replacement_base_class_name = replacement.__qualname__.split(".")[0] - # replacement.__globals__ example: {'MyClass': } - replacement_base_class = replacement.__globals__.get( - replacement_base_class_name - ) + if ( + replacement_version is not None + and callable(replacement) + and hasattr(replacement, "__self__") + ): + replacement_base_class = replacement.__self__ # Verify that the base class inherits from VersionableInterface if inspect.isclass(replacement_base_class) and issubclass( @@ -99,7 +97,7 @@ class Deprecation: deprecated_func, replacement_base_class, replacement_version, - "A deprecated method was unable to proxy the call to its replacement", + "This is a bug, the deprecated call needs to be removed and the caller needs to update their code to use the new method.", ) deprecation_msg = f"Method \"{deprecated_func.__module__ + '.' + deprecated_func.__qualname__}\" is deprecated, use \"{replacement.__module__ + '.' + replacement.__qualname__}\" instead. {additional_information}" From a25165d935c02c07510b8b4721b074d7bed21258 Mon Sep 17 00:00:00 2001 From: Abyss Watcher Date: Sun, 26 Jan 2025 13:44:23 +0100 Subject: [PATCH 43/43] 2.18.1 -> 2.19.0 bump --- volatility3/framework/constants/_version.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/volatility3/framework/constants/_version.py b/volatility3/framework/constants/_version.py index 689e39664..f2403cf4a 100644 --- a/volatility3/framework/constants/_version.py +++ b/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 = 18 # Number of changes that only add to the interface -VERSION_PATCH = 1 # Number of changes that do not change the interface +VERSION_MINOR = 19 # Number of changes that only add to the interface +VERSION_PATCH = 0 # Number of changes that do not change the interface VERSION_SUFFIX = "" PACKAGE_VERSION = (