volatility3.framework.interfaces.context module

Defines an interface for contexts, which hold the core components that a plugin will operate upon when running.

These include a memory container which holds a series of forest of layers, and a symbol_space which contains tables of symbols that can be used to interpret data in a layer. The context also provides some convenience functions, most notably the object constructor function, object, which will construct a symbol on a layer at a particular offset.

class ContextInterface

Bases: object

All context-like objects must adhere to the following interface.

This interface is present to avoid import dependency cycles.

Initializes the context with a symbol_space.

add_layer(layer)

Adds a named translation layer to the context memory.

Parameters:

layer (DataLayerInterface) – Layer object to be added to the context memory

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

abstract property config: HierarchicalDict

Returns the configuration object for this context.

abstract property layers: LayerContainer

Returns the memory object for the context.

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

Create a module object.

A module object is associated with a symbol table, and acts like a context, but offsets locations by a known value and looks up symbols, by default within the associated symbol table. It can also be sized should that information be available.

Parameters:

• module_name (str) – The name of the module

• layer_name (str) – The layer the module is associated with (which layer the module lives within)

• offset (int) – The initial/base offset of the module (used as the offset for relative symbols)

• native_layer_name (Optional[str]) – The default native_layer_name to use when the module constructs objects

• size (Optional[int]) – The size, in bytes, that the module occupies from offset location within the layer named layer_name

Return type:

ModuleInterface

Returns:

A module object

abstract property modules: ModuleContainer

Returns the memory object for the context.

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

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

Looks up the layer_name 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]) – Either a string name of the type, or a Template of the type to be constructed

• layer_name (str) – The name of the layer on which to construct the object

• offset (int) – The address within the layer at which to construct the object

• native_layer_name (str) – The layer this object references (should it be a pointer or similar)

Returns:

A fully constructed object

abstract property symbol_space: SymbolSpaceInterface

Returns the symbol_space for the context.

This object must support the SymbolSpaceInterface

class ModuleContainer(modules=None)

Bases: Mapping

Container for multiple layers of data.

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

free_module_name(prefix='module')

Returns an unused table name to ensure no collision occurs when inserting a symbol table.

Return type:

str

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

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

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

class ModuleInterface(context, config_path, name)

Bases: ConfigurableInterface

Maintains state concerning a particular loaded module in memory.

This object is OS-independent.

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.

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 table_name (or this module if not specified) 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.

abstract 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) – The name of object type to construct (using the module’s symbol_table)

• offset (int) – the offset (unless absolute is set) from the start of the module

• native_layer_name (Optional[str]) – The native layer for objects that reference a different layer (if not the default provided during module construction)

• absolute (bool) – A boolean specifying whether the offset is absolute within the layer, or relative to the start of the module

Return type:

ObjectInterface

Returns:

The constructed object

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

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

Parameters:

• symbol_name (str) – The name of a symbol (that must be present in the module’s symbol table). The symbol’s associated type will be used to construct an object at the symbol’s offset.

• native_layer_name (Optional[str]) – The native layer for objects that reference a different layer (if not the default provided during module construction)

• absolute (bool) – A boolean specifying whether the offset is absolute within the layer, or relative to the start of 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

Returns:

The constructed object

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

symbols()

Lists the symbols contained in the symbol table for this module

Return type:

List

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]