volatility3.framework.symbols.linux.utilities.modules module

class ModuleDisplayPlugin(*args, **kwargs)

Bases: VersionableInterface

Plugins that enumerate kernel modules (lsmod, check_modules, etc.) must inherit from this class to have unified output columns across plugins. The constructor of the plugin must call super() with the implementation set

columns_results = [('Offset', <class 'volatility3.framework.renderers.format_hints.Hex'>), ('Module Name', <class 'str'>), ('Code Size', <class 'volatility3.framework.renderers.format_hints.Hex'>), ('Taints', <class 'str'>), ('Load Arguments', <class 'str'>), ('File Output', <class 'str'>)]

classmethod generate_results(context, implementation, kernel_module_name, dump, open_implementation)

Uses the implementation set in the constructor call to produce consistent output fields across module gathering plugins

classmethod get_requirements()

Return type:

List[RequirementInterface]

version = (2, 0, 0)

class ModuleExtract(*args, **kwargs)

Bases: VersionableInterface

Extracts Linux kernel module structures into an analyzable ELF file

classmethod extract_module(context, vmlinux_name, module)

Return type:

Optional[bytes]

classmethod get_requirements()

Return type:

List[RequirementInterface]

version = (1, 0, 2)

class ModuleGathererInterface(*args, **kwargs)

Bases: VersionableInterface

abstractmethod classmethod gather_modules(context, kernel_module_name)

This method must return a generator (yield) of each gatherer_return_type found from its source

Return type:

Generator[Union[ModuleInfo, module], None, None]

gatherer_return_type

alias of Generator[ModuleInfo | extensions.module, None, None]

name = None

version = (1, 0, 0)

class ModuleGathererKernel(*args, **kwargs)

Bases: ModuleGathererInterface

Creates a ModuleInfo instance for the kernel so that plugins can determine when function pointers reference the kernel

classmethod gather_modules(context, kernel_module_name)

Returns a ModuleInfo instance that encodes the kernel This is required to map function pointers to the kernel executable

Return type:

Generator[Union[ModuleInfo, module], None, None]

gatherer_return_type

alias of Generator[ModuleInfo | extensions.module, None, None]

name = 'kernel'

version = (1, 0, 0)

class ModuleGathererLsmod(*args, **kwargs)

Bases: ModuleGathererInterface

Gathers modules from the main kernel list

classmethod gather_modules(context, kernel_module_name)

This method must return a generator (yield) of each gatherer_return_type found from its source

Return type:

Generator[Union[ModuleInfo, module], None, None]

gatherer_return_type

alias of Generator[ModuleInfo | extensions.module, None, None]

name = 'Lsmod'

version = (1, 0, 0)

class ModuleGathererScanner(*args, **kwargs)

Bases: ModuleGathererInterface

Gathers modules by scanning memory

classmethod gather_modules(context, kernel_module_name)

This method must return a generator (yield) of each gatherer_return_type found from its source

Return type:

Generator[Union[ModuleInfo, module], None, None]

gatherer_return_type

alias of Generator[ModuleInfo | extensions.module, None, None]

name = 'Scanner'

version = (1, 0, 0)

class ModuleGathererSysFs(*args, **kwargs)

Bases: ModuleGathererInterface

Gathers modules from the sysfs /sys/modules objects

classmethod gather_modules(context, kernel_module_name)

This method must return a generator (yield) of each gatherer_return_type found from its source

Return type:

Generator[Union[ModuleInfo, module], None, None]

gatherer_return_type

alias of Generator[ModuleInfo | extensions.module, None, None]

name = 'SysFs'

version = (1, 0, 0)

class ModuleGatherers(*args, **kwargs)

Bases: VersionableInterface, ConfigurableInterface

Basic initializer that allows configurables to access their own config settings.

all_gatherers_identifier = [<class 'volatility3.framework.symbols.linux.utilities.modules.ModuleGathererLsmod'>, <class 'volatility3.framework.symbols.linux.utilities.modules.ModuleGathererSysFs'>, <class 'volatility3.framework.symbols.linux.utilities.modules.ModuleGathererScanner'>, <class 'volatility3.framework.symbols.linux.utilities.modules.ModuleGathererKernel'>]

build_configuration()

Constructs a HierarchicalDictionary of all the options required to build this component in the current context.

Ensures that if the class has been created, it can be recreated using the configuration built Inheriting classes must override this to ensure any dependent classes update their configurations too

Return type:

HierarchicalDict

property config: HierarchicalDict

The Hierarchical configuration Dictionary for this Configurable object.

property config_path: str

The configuration path on which this configurable lives.

property context: ContextInterface

The context object that this configurable belongs to/configuration is stored in.

classmethod get_requirements()

Returns a list of RequirementInterface objects required by this object.

classmethod make_subconfig(context, base_config_path, **kwargs)

Convenience function to allow constructing a new randomly generated sub-configuration path, containing each element from kwargs.

Parameters:

• context (ContextInterface) – The context in which to store the new configuration

• base_config_path (str) – The base configuration path on which to build the new configuration

• kwargs – Keyword arguments that are used to populate the new configuration path

Returns:

The newly generated full configuration path

Return type:

str

classmethod unsatisfied(context, config_path)

Returns a list of the names of all unsatisfied requirements.

Since a satisfied set of requirements will return [], it can be used in tests as follows:

unmet = configurable.unsatisfied(context, config_path)
if unmet:
    raise RuntimeError("Unsatisfied requirements: {}".format(unmet)

Return type:

Dict[str, RequirementInterface]

version = (1, 0, 0)

class ModuleInfo(offset: int, name: str, start: int, end: int)

Bases: NamedTuple

Used to track the name and boundary of a kernel module

Create new instance of ModuleInfo(offset, name, start, end)

count(value, /)

Return number of occurrences of value.

end: int

Alias for field number 3

index(value, start=0, stop=9223372036854775807, /)

Return first index of value.

Raises ValueError if the value is not present.

name: str

Alias for field number 1

offset: int

Alias for field number 0

start: int

Alias for field number 2

class Modules(*args, **kwargs)

Bases: VersionableInterface

Kernel modules related utilities.

classmethod flatten_run_modules_results(run_results, deduplicate=True)

Flatten a dictionary mapping plugin names and modules list, to a single merged list. This is useful to get a generic lookup list of all the detected modules.

Parameters:

• run_results (Dict[str, List[ModuleInfo]]) – dictionary of plugin names mapping a list of detected modules

• deduplicate (bool) – remove duplicate modules, based on their offsets

Return type:

List[ModuleInfo]

Returns:

List of ModuleInfo objects

classmethod get_hidden_modules(context, vmlinux_module_name, known_module_addresses, modules_memory_boundaries)

Enumerate hidden modules by taking advantage of memory address alignment patterns

This technique is much faster and uses less memory than the traditional scan method in Volatility2, but it doesn’t work with older kernels.

From kernels 4.2 struct module allocation are aligned to the L1 cache line size. In i386/amd64/arm64 this is typically 64 bytes. However, this can be changed in the Linux kernel configuration via CONFIG_X86_L1_CACHE_SHIFT. The alignment can also be obtained from the DWARF info i.e. DW_AT_alignment<64>, but dwarf2json doesn’t support this feature yet. In kernels < 4.2, alignment attributes are absent in the struct module, meaning alignment cannot be guaranteed. Therefore, for older kernels, it’s better to use the traditional scan technique.

Parameters:

• context (ContextInterface) – The context to retrieve required elements (layers, symbol tables) from

• vmlinux_module_name (str) – The name of the kernel module on which to operate

• known_module_addresses (Set[int]) – Set with known module addresses

• modules_memory_boundaries (Tuple) – Minimum and maximum address boundaries for module allocation.

Yields:

module objects

Return type:

Iterable[module]

classmethod get_kset_modules(context, vmlinux_name)

Return type:

Dict[str, module]

classmethod get_load_parameters(context, vmlinux_name, module)

Recovers the load parameters of the given kernel module Returns a tuple (key,value) for each parameter

Return type:

Generator[Tuple[str, Union[str, int, None]], None, None]

classmethod get_module_address_alignment(context, vmlinux_module_name)

Obtain the module memory address alignment.

struct module is aligned to the L1 cache line, which is typically 64 bytes for most common i386/AMD64/ARM64 configurations. In some cases, it can be 128 bytes, but this will still work.

Parameters:

• context (ContextInterface) – The context to retrieve required elements (layers, symbol tables) from

• vmlinux_module_name (str) – The name of the kernel module on which to operate

Return type:

int

Returns:

The struct module alignment

classmethod get_module_info_for_module(address_mask, module)

Returns a ModuleInfo instance for module

This performs address masking to avoid endless calls to mask_mods_list

Returns None if the name is smeared

Return type:

Optional[ModuleInfo]

static get_modules_memory_boundaries(context, vmlinux_module_name)

Determine the boundaries of the module allocation area

Parameters:

• context (ContextInterface) – The context to retrieve required elements (layers, symbol tables) from

• vmlinux_module_name (str) – The name of the kernel module on which to operate

Return type:

Tuple[int, int]

Returns:

A tuple containing the minimum and maximum addresses for the module allocation area.

classmethod list_modules(context, vmlinux_module_name)

Lists all the modules in the primary layer.

Parameters:

• context (ContextInterface) – The context to retrieve required elements (layers, symbol tables) from

• layer_name – The name of the layer on which to operate

• vmlinux_symbols – The name of the table containing the kernel symbols

Yields:

The modules present in the layer_name layer’s modules list

Return type:

Iterable[ObjectInterface]

This function will throw a SymbolError exception if kernel module support is not enabled.

classmethod lookup_module_address(cls, context, kernel_module_name, handlers, target_address)

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 type:

Tuple[str, str]

classmethod mask_mods_list(cls, context, kernel_layer_name, mods)

A helper function to mask the starting and end address of kernel modules

Return type:

List[Tuple[str, int, int]]

classmethod module_lookup_by_address(context, kernel_module_name, modules, target_address)

Determine if a target address lies in a module memory space. Returns the module where the provided address lies.

modules must be non-empty and contain masked addresses via get_module_info_for_module or a ValueError will be thrown

Parameters:

• context (ContextInterface) – The context on which to operate

• layer_name – The name of the layer on which to operate

• modules (Iterable[ModuleInfo]) – An iterable containing the modules to match the address against

• target_address (int) – The address to check for a match

Return type:

Optional[Tuple[ModuleInfo, Optional[str]]]

Returns:

The first memory module in which the address fits and the symbol name for target_address

Kernel documentation:

“within_module” and “within_module_mem_type” functions

classmethod run_modules_scanners(context, kernel_module_name, caller_wanted_gatherers, flatten=True)

Run module scanning plugins and aggregate the results. It is designed to not operate any inter-plugin results triage.

Rules for caller_wanted_gatherers:

If ModuleGatherers.all_gathers_identifier is specified then every source will be populated

If empty or an invalid gatherer is specified then a ValueError is thrown

All gatherer names must be unique

Parameters:

• called_wanted_sources – The list of sources to gather modules.

• flatten (bool) – Whether to de-duplicate modules across gatherers

Return type:

Dict[str, List[ModuleInfo]]

Returns:

Dictionary mapping each gatherer to its corresponding result

static validate_alignment_patterns(addresses, address_alignment)

Check if the memory addresses meet our alignments patterns

Parameters:

• addresses (Iterable[int]) – Iterable with the address values

• address_alignment (int) – Number of bytes for alignment validation

Return type:

bool

Returns:

True if all the addresses meet the alignment

version = (3, 0, 2)