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.

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: NativeTableInterface: Returns None or a NativeTable for handling space specific native types.

optional_set_type_class(name, clazz)[source]

Calls the set_type_class function but does not throw an exception. Returns whether setting the type class was successful. :type name: str :param name: The name of the type to override the class for :type clazz: Type[ObjectInterface] :param clazz: The actual class to override for the provided type name

Return type:: bool

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.

property types: Iterable[str]: Returns an iterator of the Symbol type names.

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

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: NativeTableInterface: Returns None or a NativeTable for handling space specific native types.

optional_set_type_class(name, clazz)

Calls the set_type_class function but does not throw an exception. Returns whether setting the type class was successful. :type name: str :param name: The name of the type to override the class for :type clazz: Type[ObjectInterface] :param clazz: The actual class to override for the provided type name

Return type:: bool

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.

property types: Iterable[str]: Returns an iterator of the Symbol type names.

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.

property constant_data: bytes | None: Returns any constant data associated with the symbol.

property name: str: Returns the name of the symbol.

property type: Template | None: Returns the type that the symbol represents.

property type_name: str | None: Returns the name of the type that the symbol represents.

class SymbolSpaceInterface[source]

Bases: 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: BaseSymbolTableInterface, ConfigurableInterface, 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: HierarchicalDict: The Hierarchical configuration Dictionary for this Configurable object.

property config_path: str: The configuration path on which this configurable lives.

property context: ContextInterface: The context object that this configurable belongs to/configuration is stored in.

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.

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: NativeTableInterface: Returns None or a NativeTable for handling space specific native types.

optional_set_type_class(name, clazz)

Calls the set_type_class function but does not throw an exception. Returns whether setting the type class was successful. :type name: str :param name: The name of the type to override the class for :type clazz: Type[ObjectInterface] :param clazz: The actual class to override for the provided type name

Return type:: bool

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.

property types: Iterable[str]: Returns an iterator of the Symbol type names.

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]