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

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

Returns the configuration object for this context.

Return type

HierarchicalDict

abstract property layers

Returns the memory object for the context.

Return type

LayerContainer

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 occupys from offset location within the layer named layer_name

Return type

ModuleInterface

Returns

A module object

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 (Optional[str]) – The layer this object references (should it be a pointer or similar)

Returns

A fully constructed object

abstract property symbol_space

Returns the symbol_space for the context.

This object must support the SymbolSpaceInterface

Return type

SymbolSpaceInterface

class ModuleInterface(context, module_name, layer_name, offset, symbol_table_name=None, native_layer_name=None)

Bases: object

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

• 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

• symbol_table_name (Optional[str]) – The name of an associated symbol table

• native_layer_name (Optional[str]) – The default native layer for objects constructed by the module

property context

Context that the module uses.

Return type

ContextInterface

get_enumeration(name)

Returns an enumeration from the module.

Return type

Template

get_symbol(name)

Returns a symbol from the module.

Return type

SymbolInterface

get_type(name)

Returns a type from the module.

Return type

Template

has_enumeration(name)

Determines whether an enumeration is present in the module.

Return type

bool

has_symbol(name)

Determines whether a symbol is present in the module.

Return type

bool

has_type(name)

Determines whether a type is present in the module.

Return type

bool

property layer_name

Layer name in which the Module resides.

Return type

str

property name

The name of the constructed module.

Return type

str

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 (Optional[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, **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

Return type

ObjectInterface

Returns

The constructed object

property offset

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

Return type

int