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)

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.

property config_path: str

The configuration path on which this configurable lives.

property context: ContextInterface

Context that the module uses.

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.

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.

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 (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, object_type=None, **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

• object_type (Union[str, ObjectInterface, None]) – Override for the type from the symobl to use (or if the symbol type is missing)

Return type:

ObjectInterface

property offset: int

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

property symbol_table_name: str

The name of the symbol table associated with this module

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

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)

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.

property layers: LayerContainer

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

module(module_name, layer_name, offset, native_layer_name=None, size=None)

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

object(object_type, layer_name, offset, native_layer_name=None, **arguments)

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.

class Module(context, config_path, name)

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.

property config_path: str

The configuration path on which this configurable lives.

property context: ContextInterface

Context that the module uses.

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.

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.

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 (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, object_type=None, **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

• object_type (Union[str, ObjectInterface, None]) – Override for the type from the symobl to use (or if the symbol type is missing)

Return type:

ObjectInterface

property offset: int

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

property symbol_table_name: str

The name of the symbol table associated with this module

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)

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()

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')

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)

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.

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

class SizedModule(context, config_path, name)

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.

property config_path: str

The configuration path on which this configurable lives.

property context: ContextInterface

Context that the module uses.

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

property layer_name: str

Layer name in which the Module resides.

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.

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 (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, object_type=None, **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

• object_type (Union[str, ObjectInterface, None]) – Override for the type from the symobl to use (or if the symbol type is missing)

Return type:

ObjectInterface

property offset: int

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

property size: int

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

property symbol_table_name: str

The name of the symbol table associated with this module

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)

Returns a symbol using the symbol_table_name of the Module.

Return type:

Callable