volatility3.framework.interfaces.symbols module

Symbols provide structural information about a set of bytes.

class BaseSymbolTableInterface(name, native_types, table_mapping=None, class_types=None)[source]

Bases: object

The base interface, inherited by both NativeTables and SymbolTables.

native_types is a NativeTableInterface used for native types for the particular loaded symbol table table_mapping allows tables referenced by symbols to be remapped to a different table name if necessary

Note: table_mapping is a rarely used feature (since symbol tables are typically self-contained)

Parameters
  • name (str) – Name of the symbol table

  • native_types (NativeTableInterface) – The native symbol table used to resolve any base/native types

  • table_mapping (Optional[Dict[str, str]]) – A dictionary mapping names of tables (which when present within the table will be changed to the mapped table)

  • class_types (Optional[Mapping[str, Type[ObjectInterface]]]) – A dictionary of types and classes that should be instantiated instead of Struct to construct them

clear_symbol_cache()[source]

Clears the symbol cache of this symbol table.

Return type

None

del_type_class(name)[source]

Removes the associated class override for a specific Symbol type.

Return type

None

property enumerations: Iterable[Any]

Returns an iterator of the Enumeration names.

Return type

Iterable[Any]

get_symbol(name)[source]

Resolves a symbol name into a symbol object.

If the symbol isn’t found, it raises a SymbolError exception

Return type

SymbolInterface

get_symbol_type(name)[source]

Resolves a symbol name into a symbol and then resolves the symbol’s type.

Return type

Optional[Template]

get_symbols_by_location(offset, size=0)[source]

Returns the name of all symbols in this table that live at a particular offset.

Return type

Iterable[str]

get_symbols_by_type(type_name)[source]

Returns the name of all symbols in this table that have type matching type_name.

Return type

Iterable[str]

get_type(name)[source]

Resolves a symbol name into an object template.

If the symbol isn’t found it raises a SymbolError exception

Return type

Template

get_type_class(name)[source]

Returns the class associated with a Symbol type.

Return type

Type[ObjectInterface]

property natives: volatility3.framework.interfaces.symbols.NativeTableInterface

Returns None or a NativeTable for handling space specific native types.

Return type

NativeTableInterface

set_type_class(name, clazz)[source]

Overrides the object class for a specific Symbol type.

Name must be present in self.types

Parameters
  • name (str) – The name of the type to override the class for

  • clazz (Type[ObjectInterface]) – The actual class to override for the provided type name

Return type

None

property symbols: Iterable[str]

Returns an iterator of the Symbol names.

Return type

Iterable[str]

property types: Iterable[str]

Returns an iterator of the Symbol type names.

Return type

Iterable[str]

class MetadataInterface(json_data)[source]

Bases: object

Interface for accessing metadata stored within a symbol table.

Constructor that accepts json_data.

class NativeTableInterface(name, native_types, table_mapping=None, class_types=None)[source]

Bases: volatility3.framework.interfaces.symbols.BaseSymbolTableInterface

Class to distinguish NativeSymbolLists from other symbol lists.

Parameters
  • name (str) – Name of the symbol table

  • native_types (NativeTableInterface) – The native symbol table used to resolve any base/native types

  • table_mapping (Optional[Dict[str, str]]) – A dictionary mapping names of tables (which when present within the table will be changed to the mapped table)

  • class_types (Optional[Mapping[str, Type[ObjectInterface]]]) – A dictionary of types and classes that should be instantiated instead of Struct to construct them

clear_symbol_cache()

Clears the symbol cache of this symbol table.

Return type

None

del_type_class(name)

Removes the associated class override for a specific Symbol type.

Return type

None

property enumerations: Iterable[str]

Returns an iterator of the Enumeration names.

Return type

Iterable[str]

get_enumeration(name)[source]
Return type

Template

get_symbol(name)[source]

Resolves a symbol name into a symbol object.

If the symbol isn’t found, it raises a SymbolError exception

Return type

SymbolInterface

get_symbol_type(name)

Resolves a symbol name into a symbol and then resolves the symbol’s type.

Return type

Optional[Template]

get_symbols_by_location(offset, size=0)

Returns the name of all symbols in this table that live at a particular offset.

Return type

Iterable[str]

get_symbols_by_type(type_name)

Returns the name of all symbols in this table that have type matching type_name.

Return type

Iterable[str]

get_type(name)

Resolves a symbol name into an object template.

If the symbol isn’t found it raises a SymbolError exception

Return type

Template

get_type_class(name)

Returns the class associated with a Symbol type.

Return type

Type[ObjectInterface]

property natives: volatility3.framework.interfaces.symbols.NativeTableInterface

Returns None or a NativeTable for handling space specific native types.

Return type

NativeTableInterface

set_type_class(name, clazz)

Overrides the object class for a specific Symbol type.

Name must be present in self.types

Parameters
  • name (str) – The name of the type to override the class for

  • clazz (Type[ObjectInterface]) – The actual class to override for the provided type name

Return type

None

property symbols: Iterable[str]

Returns an iterator of the Symbol names.

Return type

Iterable[str]

property types: Iterable[str]

Returns an iterator of the Symbol type names.

Return type

Iterable[str]

class SymbolInterface(name, address, type=None, constant_data=None)[source]

Bases: object

Contains information about a named location in a program’s memory.

Parameters
  • name (str) – Name of the symbol

  • address (int) – Numeric address value of the symbol

  • type (Optional[Template]) – Optional type structure information associated with the symbol

  • constant_data (Optional[bytes]) – Potential constant data the symbol points at

property address: int

Returns the relative address of the symbol within the compilation unit.

Return type

int

property constant_data: Optional[bytes]

Returns any constant data associated with the symbol.

Return type

Optional[bytes]

property name: str

Returns the name of the symbol.

Return type

str

property type: Optional[volatility3.framework.interfaces.objects.Template]

Returns the type that the symbol represents.

Return type

Optional[Template]

property type_name: Optional[str]

Returns the name of the type that the symbol represents.

Return type

Optional[str]

class SymbolSpaceInterface[source]

Bases: collections.abc.Mapping

An interface for the container that holds all the symbol-containing tables for use within a context.

abstract append(value)[source]

Adds a symbol_list to the end of the space.

Return type

None

abstract clear_symbol_cache(table_name)[source]

Clears the symbol cache for the specified table name. If no table name is specified, the caches of all symbol tables are cleared.

Return type

None

free_table_name(prefix='layer')[source]

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.
abstract get_enumeration(enum_name)[source]

Look-up an enumeration across all the contained symbol tables.

Return type

Template

abstract get_symbol(symbol_name)[source]

Look-up a symbol name across all the contained symbol tables.

Return type

SymbolInterface

abstract get_symbols_by_location(offset, size=0, table_name=None)[source]

Returns all symbols that exist at a specific relative address.

Return type

Iterable[str]

abstract get_symbols_by_type(type_name)[source]

Returns all symbols based on the type of the symbol.

Return type

Iterable[str]

abstract get_type(type_name)[source]

Look-up a type name across all the contained symbol tables.

Return type

Template

abstract has_enumeration(name)[source]

Determines whether an enumeration choice exists in the contained symbol tables.

Return type

bool

abstract has_symbol(name)[source]

Determines whether a symbol exists in the contained symbol tables.

Return type

bool

abstract has_type(name)[source]

Determines whether a type exists in the contained symbol tables.

Return type

bool

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 SymbolTableInterface(context, config_path, name, native_types, table_mapping=None, class_types=None)[source]

Bases: volatility3.framework.interfaces.symbols.BaseSymbolTableInterface, volatility3.framework.interfaces.configuration.ConfigurableInterface, abc.ABC

Handles a table of symbols.

Instantiates an SymbolTable based on an IntermediateSymbolFormat JSON file. This is validated against the appropriate schema.

Parameters
  • context (ContextInterface) – The volatility context for the symbol table

  • config_path (str) – The configuration path for the symbol table

  • name (str) – The name for the symbol table (this is used in symbols e.g. table!symbol )

  • isf_url – The URL pointing to the ISF file location

  • native_types (NativeTableInterface) – The NativeSymbolTable that contains the native types for this symbol table

  • table_mapping (Optional[Dict[str, str]]) – A dictionary linking names referenced in the file with symbol tables in the context

  • class_types (Optional[Mapping[str, Type[ObjectInterface]]]) – A dictionary of type names and classes that override StructType when they are instantiated

build_configuration()[source]

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

clear_symbol_cache()

Clears the symbol cache of this symbol table.

Return type

None

property config: volatility3.framework.interfaces.configuration.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: volatility3.framework.interfaces.context.ContextInterface

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

Return type

ContextInterface

del_type_class(name)

Removes the associated class override for a specific Symbol type.

Return type

None

property enumerations: Iterable[Any]

Returns an iterator of the Enumeration names.

Return type

Iterable[Any]

classmethod get_requirements()[source]

Returns a list of RequirementInterface objects required by this object.

Return type

List[RequirementInterface]

get_symbol(name)

Resolves a symbol name into a symbol object.

If the symbol isn’t found, it raises a SymbolError exception

Return type

SymbolInterface

get_symbol_type(name)

Resolves a symbol name into a symbol and then resolves the symbol’s type.

Return type

Optional[Template]

get_symbols_by_location(offset, size=0)

Returns the name of all symbols in this table that live at a particular offset.

Return type

Iterable[str]

get_symbols_by_type(type_name)

Returns the name of all symbols in this table that have type matching type_name.

Return type

Iterable[str]

get_type(name)

Resolves a symbol name into an object template.

If the symbol isn’t found it raises a SymbolError exception

Return type

Template

get_type_class(name)

Returns the class associated with a Symbol type.

Return type

Type[ObjectInterface]

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 natives: volatility3.framework.interfaces.symbols.NativeTableInterface

Returns None or a NativeTable for handling space specific native types.

Return type

NativeTableInterface

set_type_class(name, clazz)

Overrides the object class for a specific Symbol type.

Name must be present in self.types

Parameters
  • name (str) – The name of the type to override the class for

  • clazz (Type[ObjectInterface]) – The actual class to override for the provided type name

Return type

None

property symbols: Iterable[str]

Returns an iterator of the Symbol names.

Return type

Iterable[str]

property types: Iterable[str]

Returns an iterator of the Symbol type names.

Return type

Iterable[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]