volatility3.framework.contexts package¶

A Context maintains the accumulated state required for various plugins and framework functions.

This has been made an object to allow quick swapping and changing of contexts, to allow a plugin to act on multiple different contexts without them interfering with each other.

class ConfigurableModule(context, config_path, name)[source]¶

Bases: Module, ConfigurableInterface

Constructs a new os-independent module.

Parameters

context (ContextInterface) – The context within which this module will exist
config_path (str) – The path within the context’s configuration tree
name (str) – The name of the module

build_configuration()¶

Builds the configuration dictionary for this specific Module

Return type: HierarchicalDict

property config: HierarchicalDict¶

The Hierarchical configuration Dictionary for this Configurable object.

Return type: HierarchicalDict

property config_path: str¶

The configuration path on which this configurable lives.

Return type: str

property context: ContextInterface¶

Context that the module uses.

Return type: ContextInterface

classmethod create(context, module_name, layer_name, offset, **kwargs)¶

Return type: Module

get_absolute_symbol_address(name)¶

Returns the absolute address of the symbol within this module

Return type: int

get_enumeration(name)¶

Returns an enumeration from the module’s symbol table.

Return type: Template

classmethod get_requirements()¶

Returns a list of RequirementInterface objects required by this object.

Return type: List[RequirementInterface]

get_symbol(name)¶

Returns a symbol object from the module’s symbol table.

Return type: SymbolInterface

get_symbols_by_absolute_location(offset, size=0)¶

Returns the symbols within this module that live at the specified absolute offset provided.

Return type: List[str]

get_type(name)¶

Returns a type from the module’s symbol table.

Return type: Template

has_enumeration(name)¶

Determines whether an enumeration is present in the module’s symbol table.

Return type: bool

has_symbol(name)¶

Determines whether a symbol is present in the module’s symbol table.

Return type: bool

has_type(name)¶

Determines whether a type is present in the module’s symbol table.

Return type: bool

property layer_name: str¶

Layer name in which the Module resides.

Return type: str

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

property name: str¶

The name of the constructed module.

Return type: str

object(object_type, offset=None, native_layer_name=None, absolute=False, **kwargs)¶

Returns an object created using the symbol_table_name and layer_name of the Module.

Parameters

object_type (str) – Name of the type/enumeration (within the module) to construct
offset (Optional[int]) – The location of the object, ignored when symbol_type is SYMBOL
native_layer_name (Optional[str]) – Name of the layer in which constructed objects are made (for pointers)
absolute (bool) – whether the type’s offset is absolute within memory or relative to the module

Return type

ObjectInterface

object_from_symbol(symbol_name, native_layer_name=None, absolute=False, **kwargs)¶

Returns an object based on a specific symbol (containing type and offset information) and the layer_name of the Module. This will throw a ValueError if the symbol does not contain an associated type, or if the symbol name is invalid. It will throw a SymbolError if the symbol cannot be found.

Parameters

symbol_name (str) – Name of the symbol (within the module) to construct
native_layer_name (Optional[str]) – Name of the layer in which constructed objects are made (for pointers)
absolute (bool) – whether the symbol’s address is absolute or relative to the module

Return type

ObjectInterface

property offset: int¶

Returns the offset that the module resides within the layer of layer_name.

Return type: int

property symbol_table_name: str¶

The name of the symbol table associated with this module

Return type: str

property symbols¶: Lists the symbols contained in the symbol table for this module

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]

class Context[source]¶

Bases: ContextInterface

Maintains the context within which to construct objects.

The context object is the main method of carrying around state that’s been constructed for the purposes of investigating memory. It contains a symbol_space of all the symbols that can be accessed by plugins using the context. It also contains the memory made up of data and translation layers, and it contains a factory method for creating new objects.

Other context objects can be constructed as long as they support the ContextInterface. This is the primary context object to be used in the volatility framework. It maintains the

Initializes the context.

add_layer(layer)[source]¶

Adds a named translation layer to the context.

Parameters: layer (DataLayerInterface) – The layer to be added to the memory
Raises: volatility3.framework.exceptions.LayerException – if the layer is already present, or has unmet dependencies
Return type: None

add_module(module)¶

Adds a named module to the context.

Parameters: module (ModuleInterface) – The module to be added to the module object collection
Raises: volatility3.framework.exceptions.VolatilityException – if the module is already present, or has unmet dependencies

clone()¶

Produce a clone of the context (and configuration), allowing modifications to be made without affecting any mutable objects in the original.

Memory constraints may become an issue for this function depending on how much is actually stored in the context

Return type: ContextInterface

property config: HierarchicalDict¶

Returns a mutable copy of the configuration, but does not allow the whole configuration to be altered.

Return type: HierarchicalDict

property layers: LayerContainer¶

A LayerContainer object, allowing access to all data and translation layers currently available within the context.

Return type: LayerContainer

module(module_name, layer_name, offset, native_layer_name=None, size=None)[source]¶

Constructs a new os-independent module.

Parameters

module_name (str) – The name of the module
layer_name (str) – The layer within the context in which the module exists
offset (int) – The offset at which the module exists in the layer
native_layer_name (Optional[str]) – The default native layer for objects constructed by the module
size (Optional[int]) – The size, in bytes, that the module occupies from offset location within the layer named layer_name

Return type

ModuleInterface

property modules: ModuleContainer¶

A container for modules loaded in this context

Return type: ModuleContainer

object(object_type, layer_name, offset, native_layer_name=None, **arguments)[source]¶

Object factory, takes a context, symbol, offset and optional layername.

Looks up the layername in the context, finds the object template based on the symbol, and constructs an object using the object template on the layer at the offset.

Parameters

object_type (Union[str, Template]) – The name (or template) of the symbol type on which to construct the object. If this is a name, it should contain an explicit table name.
layer_name (str) – The name of the layer on which to construct the object
offset (int) – The offset within the layer at which the data used to create the object lives
native_layer_name (Optional[str]) – The name of the layer the object references (for pointers) if different to layer_name

Return type

ObjectInterface

Returns

A fully constructed object

property symbol_space: SymbolSpaceInterface¶

The space of all symbols that can be accessed within this context.

Return type: SymbolSpaceInterface

class Module(context, config_path, name)[source]¶

Bases: ModuleInterface

Constructs a new os-independent module.

Parameters

context (ContextInterface) – The context within which this module will exist
config_path (str) – The path within the context’s configuration tree
name (str) – The name of the module

build_configuration()¶

Builds the configuration dictionary for this specific Module

Return type: HierarchicalDict

property config: HierarchicalDict¶

The Hierarchical configuration Dictionary for this Configurable object.

Return type: HierarchicalDict

property config_path: str¶

The configuration path on which this configurable lives.

Return type: str

property context: ContextInterface¶

Context that the module uses.

Return type: ContextInterface

classmethod create(context, module_name, layer_name, offset, **kwargs)[source]¶

Return type: Module

get_absolute_symbol_address(name)¶

Returns the absolute address of the symbol within this module

Return type: int

get_enumeration(name)¶

Returns an enumeration from the module’s symbol table.

Return type: Template

classmethod get_requirements()¶

Returns a list of RequirementInterface objects required by this object.

Return type: List[RequirementInterface]

get_symbol(name)¶

Returns a symbol object from the module’s symbol table.

Return type: SymbolInterface

get_symbols_by_absolute_location(offset, size=0)[source]¶

Returns the symbols within this module that live at the specified absolute offset provided.

Return type: List[str]

get_type(name)¶

Returns a type from the module’s symbol table.

Return type: Template

has_enumeration(name)¶

Determines whether an enumeration is present in the module’s symbol table.

Return type: bool

has_symbol(name)¶

Determines whether a symbol is present in the module’s symbol table.

Return type: bool

has_type(name)¶

Determines whether a type is present in the module’s symbol table.

Return type: bool

property layer_name: str¶

Layer name in which the Module resides.

Return type: str

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

property name: str¶

The name of the constructed module.

Return type: str

object(object_type, offset=None, native_layer_name=None, absolute=False, **kwargs)[source]¶

Returns an object created using the symbol_table_name and layer_name of the Module.

Parameters

object_type (str) – Name of the type/enumeration (within the module) to construct
offset (Optional[int]) – The location of the object, ignored when symbol_type is SYMBOL
native_layer_name (Optional[str]) – Name of the layer in which constructed objects are made (for pointers)
absolute (bool) – whether the type’s offset is absolute within memory or relative to the module

Return type

ObjectInterface

object_from_symbol(symbol_name, native_layer_name=None, absolute=False, **kwargs)[source]¶

Returns an object based on a specific symbol (containing type and offset information) and the layer_name of the Module. This will throw a ValueError if the symbol does not contain an associated type, or if the symbol name is invalid. It will throw a SymbolError if the symbol cannot be found.

Parameters

symbol_name (str) – Name of the symbol (within the module) to construct
native_layer_name (Optional[str]) – Name of the layer in which constructed objects are made (for pointers)
absolute (bool) – whether the symbol’s address is absolute or relative to the module

Return type

ObjectInterface

property offset: int¶

Returns the offset that the module resides within the layer of layer_name.

Return type: int

property symbol_table_name: str¶

The name of the symbol table associated with this module

Return type: str

property symbols¶: Lists the symbols contained in the symbol table for this module

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]

class ModuleCollection(modules=None)[source]¶

Bases: ModuleContainer

Class to contain a collection of SizedModules and reason about their contents.

add_module(module)¶

Adds a module to the module collection

This will throw an exception if the required dependencies are not met

Parameters: module (ModuleInterface) – the module to add to the list of modules (based on module.name)
Return type: None

deduplicate()[source]¶

Returns a new deduplicated ModuleCollection featuring no repeated modules (based on data hash)

All 0 sized modules will have identical hashes and are therefore included in the deduplicated version

Return type: ModuleCollection

free_module_name(prefix='module')[source]¶

Returns an unused module name

Return type: str

get(k[, d]) → D[k] if k in D, else d. d defaults to None.¶

get_module_symbols_by_absolute_location(offset, size=0)[source]¶

Returns a tuple of (module_name, list_of_symbol_names) for each module, where symbols live at the absolute offset in memory provided.

Return type: Iterable[Tuple[str, List[str]]]

get_modules_by_symbol_tables(symbol_table)¶

Returns the modules which use the specified symbol table name

Return type: Iterable[str]

items() → a set-like object providing a view on D's items¶

keys() → a set-like object providing a view on D's keys¶

property modules: ModuleCollection¶

A name indexed dictionary of modules using that name in this collection.

Return type: ModuleCollection

values() → an object providing a view on D's values¶

class SizedModule(context, config_path, name)[source]¶

Bases: Module

Constructs a new os-independent module.

Parameters

context (ContextInterface) – The context within which this module will exist
config_path (str) – The path within the context’s configuration tree
name (str) – The name of the module

build_configuration()¶

Builds the configuration dictionary for this specific Module

Return type: HierarchicalDict

property config: HierarchicalDict¶

The Hierarchical configuration Dictionary for this Configurable object.

Return type: HierarchicalDict

property config_path: str¶

The configuration path on which this configurable lives.

Return type: str

property context: ContextInterface¶

Context that the module uses.

Return type: ContextInterface

classmethod create(context, module_name, layer_name, offset, **kwargs)¶

Return type: Module

get_absolute_symbol_address(name)¶

Returns the absolute address of the symbol within this module

Return type: int

get_enumeration(name)¶

Returns an enumeration from the module’s symbol table.

Return type: Template

classmethod get_requirements()¶

Returns a list of RequirementInterface objects required by this object.

Return type: List[RequirementInterface]

get_symbol(name)¶

Returns a symbol object from the module’s symbol table.

Return type: SymbolInterface

get_symbols_by_absolute_location(offset, size=0)[source]¶

Returns the symbols within this module that live at the specified absolute offset provided.

Return type: List[str]

get_type(name)¶

Returns a type from the module’s symbol table.

Return type: Template

has_enumeration(name)¶

Determines whether an enumeration is present in the module’s symbol table.

Return type: bool

has_symbol(name)¶

Determines whether a symbol is present in the module’s symbol table.

Return type: bool

has_type(name)¶

Determines whether a type is present in the module’s symbol table.

Return type: bool

property hash: str¶

Hashes the module for equality checks.

The mapping should be sorted and should be quicker than reading the data We turn it into JSON to make a common string and use a quick hash, because collisions are unlikely

Return type: str

property layer_name: str¶

Layer name in which the Module resides.

Return type: str

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

property name: str¶

The name of the constructed module.

Return type: str

object(object_type, offset=None, native_layer_name=None, absolute=False, **kwargs)¶

Returns an object created using the symbol_table_name and layer_name of the Module.

Parameters

object_type (str) – Name of the type/enumeration (within the module) to construct
offset (Optional[int]) – The location of the object, ignored when symbol_type is SYMBOL
native_layer_name (Optional[str]) – Name of the layer in which constructed objects are made (for pointers)
absolute (bool) – whether the type’s offset is absolute within memory or relative to the module

Return type

ObjectInterface

object_from_symbol(symbol_name, native_layer_name=None, absolute=False, **kwargs)¶

Returns an object based on a specific symbol (containing type and offset information) and the layer_name of the Module. This will throw a ValueError if the symbol does not contain an associated type, or if the symbol name is invalid. It will throw a SymbolError if the symbol cannot be found.

Parameters

symbol_name (str) – Name of the symbol (within the module) to construct
native_layer_name (Optional[str]) – Name of the layer in which constructed objects are made (for pointers)
absolute (bool) – whether the symbol’s address is absolute or relative to the module

Return type

ObjectInterface

property offset: int¶

Returns the offset that the module resides within the layer of layer_name.

Return type: int

property size: int¶

Returns the size of the module (0 for unknown size)

Return type: int

property symbol_table_name: str¶

The name of the symbol table associated with this module

Return type: str

property symbols¶: Lists the symbols contained in the symbol table for this module

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]

get_module_wrapper(method)[source]¶

Returns a symbol using the symbol_table_name of the Module.

Return type: Callable