volatility3.framework.interfaces.configuration module

The configuration module contains classes and functions for interacting with the configuration and requirement trees.

Volatility plugins can specify a list of requirements (which may have subrequirements, thus forming a requirement tree). These requirement trees can contain values, which are contained in a complementary configuration tree. These two trees act as a protocol between the plugins and users. The plugins provide requirements that must be fulfilled, and the users provide configurations values that fulfill those requirements. Where the user does not provide sufficient configuration values, automagic modules may extend the configuration tree themselves.

CONFIG_SEPARATOR = '.'

Use to specify the separator between configuration hierarchies

class ClassRequirement(*args, **kwargs)[source]

Bases: RequirementInterface

Requires a specific class.

This is used as means to serialize specific classes for TranslationLayerRequirement and SymbolTableRequirement classes.

Parameters
  • name – The name of the requirement

  • description – A short textual description of the requirement

  • default – The default value for the requirement if no value is provided

  • optional – Whether the requirement must be satisfied or not

add_requirement(requirement)

Adds a child to the list of requirements.

Parameters

requirement (RequirementInterface) – The requirement to add as a child-requirement

Return type

None

property cls: Optional[Type]

Contains the actual chosen class based on the configuration value’s class name.

config_value(context, config_path, default=None)

Returns the value for this Requirement from its config path.

Parameters
  • context (ContextInterface) – the configuration store to find the value for this requirement

  • config_path (str) – the configuration path of the instance of the requirement to be recovered

  • default (Union[int, bool, bytes, str, List[Union[int, bool, bytes, str]], None]) – a default value to provide if the requirement’s configuration value is not found

Return type

Union[int, bool, bytes, str, List[Union[int, bool, bytes, str]], None]

property default: Optional[Union[int, bool, bytes, str, List[Union[int, bool, bytes, str]]]]

Returns the default value if one is set.

property description: str

A short description of what the Requirement is designed to affect or achieve.

property name: str

The name of the Requirement.

Names cannot contain CONFIG_SEPARATOR (‘.’ by default) since this is used within the configuration hierarchy.

property optional: bool

Whether the Requirement is optional or not.

remove_requirement(requirement)

Removes a child from the list of requirements.

Parameters

requirement (RequirementInterface) – The requirement to remove as a child-requirement

Return type

None

property requirements: Dict[str, RequirementInterface]

Returns a dictionary of all the child requirements, indexed by name.

unsatisfied(context, config_path)[source]

Checks to see if a class can be recovered.

Return type

Dict[str, RequirementInterface]

unsatisfied_children(context, config_path)

Method that will validate all child requirements.

Parameters
  • context (ContextInterface) – the context containing the configuration data for this requirement

  • config_path (str) – the configuration path of this instance of the requirement

Return type

Dict[str, RequirementInterface]

Returns

A dictionary of full configuration paths for each unsatisfied child-requirement

class ConfigurableInterface(context, config_path)[source]

Bases: object

Class to allow objects to have requirements and read configuration data from the context config tree.

Basic initializer that allows configurables to access their own config settings.

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

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.

classmethod get_requirements()[source]

Returns a list of RequirementInterface objects required by this object.

Return type

List[RequirementInterface]

classmethod make_subconfig(context, base_config_path, **kwargs)[source]

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

classmethod unsatisfied(context, config_path)[source]

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 ConfigurableRequirementInterface(name, description=None, default=None, optional=False)[source]

Bases: RequirementInterface

Simple Abstract class to provide build_required_config.

Parameters
  • name (str) – The name of the requirement

  • description (Optional[str]) – A short textual description of the requirement

  • default (Union[int, bool, bytes, str, List[Union[int, bool, bytes, str]], None]) – The default value for the requirement if no value is provided

  • optional (bool) – Whether the requirement must be satisfied or not

add_requirement(requirement)

Adds a child to the list of requirements.

Parameters

requirement (RequirementInterface) – The requirement to add as a child-requirement

Return type

None

build_configuration(context, config_path, value)[source]

Proxies to a ConfigurableInterface if necessary.

Return type

HierarchicalDict

config_value(context, config_path, default=None)

Returns the value for this Requirement from its config path.

Parameters
  • context (ContextInterface) – the configuration store to find the value for this requirement

  • config_path (str) – the configuration path of the instance of the requirement to be recovered

  • default (Union[int, bool, bytes, str, List[Union[int, bool, bytes, str]], None]) – a default value to provide if the requirement’s configuration value is not found

Return type

Union[int, bool, bytes, str, List[Union[int, bool, bytes, str]], None]

property default: Optional[Union[int, bool, bytes, str, List[Union[int, bool, bytes, str]]]]

Returns the default value if one is set.

property description: str

A short description of what the Requirement is designed to affect or achieve.

property name: str

The name of the Requirement.

Names cannot contain CONFIG_SEPARATOR (‘.’ by default) since this is used within the configuration hierarchy.

property optional: bool

Whether the Requirement is optional or not.

remove_requirement(requirement)

Removes a child from the list of requirements.

Parameters

requirement (RequirementInterface) – The requirement to remove as a child-requirement

Return type

None

property requirements: Dict[str, RequirementInterface]

Returns a dictionary of all the child requirements, indexed by name.

abstract unsatisfied(context, config_path)

Method to validate the value stored at config_path for the configuration object against a context.

Returns a list containing its own name (or multiple unsatisfied requirement names) when invalid

Parameters
  • context (ContextInterface) – The context object containing the configuration for this requirement

  • config_path (str) – The configuration path for this requirement to test satisfaction

Return type

Dict[str, RequirementInterface]

Returns

A dictionary of configuration-paths to requirements that could not be satisfied

unsatisfied_children(context, config_path)

Method that will validate all child requirements.

Parameters
  • context (ContextInterface) – the context containing the configuration data for this requirement

  • config_path (str) – the configuration path of this instance of the requirement

Return type

Dict[str, RequirementInterface]

Returns

A dictionary of full configuration paths for each unsatisfied child-requirement

class ConstructableRequirementInterface(*args, **kwargs)[source]

Bases: RequirementInterface

Defines a Requirement that can be constructed based on their own requirements.

This effectively offers a means for serializing specific python types, to be reconstructed based on simple configuration data. Each constructable records a class requirement, which indicates the object that will be constructed. That class may have its own requirements (which is why validation of a ConstructableRequirement must happen after the class configuration value has been provided). These values are then provided to the object’s constructor by name as arguments (as well as the standard context and config_path arguments).

Parameters
  • name – The name of the requirement

  • description – A short textual description of the requirement

  • default – The default value for the requirement if no value is provided

  • optional – Whether the requirement must be satisfied or not

add_requirement(requirement)

Adds a child to the list of requirements.

Parameters

requirement (RequirementInterface) – The requirement to add as a child-requirement

Return type

None

config_value(context, config_path, default=None)

Returns the value for this Requirement from its config path.

Parameters
  • context (ContextInterface) – the configuration store to find the value for this requirement

  • config_path (str) – the configuration path of the instance of the requirement to be recovered

  • default (Union[int, bool, bytes, str, List[Union[int, bool, bytes, str]], None]) – a default value to provide if the requirement’s configuration value is not found

Return type

Union[int, bool, bytes, str, List[Union[int, bool, bytes, str]], None]

abstract construct(context, config_path)[source]

Method for constructing within the context any required elements from subrequirements.

Parameters
  • context (ContextInterface) – The context object containing the configuration data for the constructable

  • config_path (str) – The configuration path for the specific instance of this constructable

Return type

None

property default: Optional[Union[int, bool, bytes, str, List[Union[int, bool, bytes, str]]]]

Returns the default value if one is set.

property description: str

A short description of what the Requirement is designed to affect or achieve.

property name: str

The name of the Requirement.

Names cannot contain CONFIG_SEPARATOR (‘.’ by default) since this is used within the configuration hierarchy.

property optional: bool

Whether the Requirement is optional or not.

remove_requirement(requirement)

Removes a child from the list of requirements.

Parameters

requirement (RequirementInterface) – The requirement to remove as a child-requirement

Return type

None

property requirements: Dict[str, RequirementInterface]

Returns a dictionary of all the child requirements, indexed by name.

abstract unsatisfied(context, config_path)

Method to validate the value stored at config_path for the configuration object against a context.

Returns a list containing its own name (or multiple unsatisfied requirement names) when invalid

Parameters
  • context (ContextInterface) – The context object containing the configuration for this requirement

  • config_path (str) – The configuration path for this requirement to test satisfaction

Return type

Dict[str, RequirementInterface]

Returns

A dictionary of configuration-paths to requirements that could not be satisfied

unsatisfied_children(context, config_path)

Method that will validate all child requirements.

Parameters
  • context (ContextInterface) – the context containing the configuration data for this requirement

  • config_path (str) – the configuration path of this instance of the requirement

Return type

Dict[str, RequirementInterface]

Returns

A dictionary of full configuration paths for each unsatisfied child-requirement

class HierarchicalDict(initial_dict=None, separator='.')[source]

Bases: Mapping

The core of configuration data, it is a mapping class that stores keys within itself, and also stores lower hierarchies.

Parameters
  • initial_dict (Optional[Dict[str, SimpleTypeRequirement]]) – A dictionary to populate the HierarchicalDict with initially

  • separator (str) – A custom hierarchy separator (defaults to CONFIG_SEPARATOR)

branch(key)[source]

Returns the HierarchicalDict housed under the key.

This differs from the data property, in that it is directed by the key, and all layers under that key are returned, not just those in that level.

Higher layers are not prefixed with the location of earlier layers, so branching a hierarchy containing a.b.c.d on a.b would return a hierarchy containing c.d, not a.b.c.d.

Parameters

key (str) – The location within the hierarchy to return higher layers.

Return type

HierarchicalDict

Returns

The HierarchicalDict underneath the specified key (not just the data at that key location in the tree)

clone()[source]

Duplicates the configuration, allowing changes without affecting the original.

Return type

HierarchicalDict

Returns

A duplicate HierarchicalDict of this object

property data: Dict

Returns just the data-containing mappings on this level of the Hierarchy.

generator()[source]

A generator for the data in this level and lower levels of this mapping.

Return type

Generator[str, None, None]

Returns

Returns each item in the top level data, and then all subkeys in a depth first order

get(k[, d]) D[k] if k in D, else d.  d defaults to None.
items() a set-like object providing a view on D's items
keys() a set-like object providing a view on D's keys
merge(key, value, overwrite=False)[source]

Acts similarly to splice, but maintains previous values.

If overwrite is true, then entries in the new value are used over those that exist within key already

Parameters
  • key (str) – The location within the hierarchy at which to merge the value

  • value (HierarchicalDict) – HierarchicalDict to be merged under the key node

  • overwrite (bool) – A boolean defining whether the value will be overwritten if it already exists

Return type

None

property separator: str

Specifies the hierarchy separator in use in this HierarchyDict.

splice(key, value)[source]

Splices an existing HierarchicalDictionary under a specific key.

This can be thought of as an inverse of branch(), although branch does not remove the requested hierarchy, it simply returns it.

Return type

None

values() an object providing a view on D's values
class RequirementInterface(name, description=None, default=None, optional=False)[source]

Bases: object

Class that defines a requirement.

A requirement is a means for plugins and other framework components to request specific configuration data. Requirements can either be simple types (such as SimpleTypeRequirement, IntRequirement, BytesRequirement and StringRequirement) or complex types (such as TranslationLayerRequirement, SymbolTableRequirement and ClassRequirement

Parameters
  • name (str) – The name of the requirement

  • description (Optional[str]) – A short textual description of the requirement

  • default (Union[int, bool, bytes, str, List[Union[int, bool, bytes, str]], None]) – The default value for the requirement if no value is provided

  • optional (bool) – Whether the requirement must be satisfied or not

add_requirement(requirement)[source]

Adds a child to the list of requirements.

Parameters

requirement (RequirementInterface) – The requirement to add as a child-requirement

Return type

None

config_value(context, config_path, default=None)[source]

Returns the value for this Requirement from its config path.

Parameters
  • context (ContextInterface) – the configuration store to find the value for this requirement

  • config_path (str) – the configuration path of the instance of the requirement to be recovered

  • default (Union[int, bool, bytes, str, List[Union[int, bool, bytes, str]], None]) – a default value to provide if the requirement’s configuration value is not found

Return type

Union[int, bool, bytes, str, List[Union[int, bool, bytes, str]], None]

property default: Optional[Union[int, bool, bytes, str, List[Union[int, bool, bytes, str]]]]

Returns the default value if one is set.

property description: str

A short description of what the Requirement is designed to affect or achieve.

property name: str

The name of the Requirement.

Names cannot contain CONFIG_SEPARATOR (‘.’ by default) since this is used within the configuration hierarchy.

property optional: bool

Whether the Requirement is optional or not.

remove_requirement(requirement)[source]

Removes a child from the list of requirements.

Parameters

requirement (RequirementInterface) – The requirement to remove as a child-requirement

Return type

None

property requirements: Dict[str, RequirementInterface]

Returns a dictionary of all the child requirements, indexed by name.

abstract unsatisfied(context, config_path)[source]

Method to validate the value stored at config_path for the configuration object against a context.

Returns a list containing its own name (or multiple unsatisfied requirement names) when invalid

Parameters
  • context (ContextInterface) – The context object containing the configuration for this requirement

  • config_path (str) – The configuration path for this requirement to test satisfaction

Return type

Dict[str, RequirementInterface]

Returns

A dictionary of configuration-paths to requirements that could not be satisfied

unsatisfied_children(context, config_path)[source]

Method that will validate all child requirements.

Parameters
  • context (ContextInterface) – the context containing the configuration data for this requirement

  • config_path (str) – the configuration path of this instance of the requirement

Return type

Dict[str, RequirementInterface]

Returns

A dictionary of full configuration paths for each unsatisfied child-requirement

class SimpleTypeRequirement(name, description=None, default=None, optional=False)[source]

Bases: RequirementInterface

Class to represent a single simple type (such as a boolean, a string, an integer or a series of bytes)

Parameters
  • name (str) – The name of the requirement

  • description (Optional[str]) – A short textual description of the requirement

  • default (Union[int, bool, bytes, str, List[Union[int, bool, bytes, str]], None]) – The default value for the requirement if no value is provided

  • optional (bool) – Whether the requirement must be satisfied or not

add_requirement(requirement)[source]

Always raises a TypeError as instance requirements cannot have children.

config_value(context, config_path, default=None)

Returns the value for this Requirement from its config path.

Parameters
  • context (ContextInterface) – the configuration store to find the value for this requirement

  • config_path (str) – the configuration path of the instance of the requirement to be recovered

  • default (Union[int, bool, bytes, str, List[Union[int, bool, bytes, str]], None]) – a default value to provide if the requirement’s configuration value is not found

Return type

Union[int, bool, bytes, str, List[Union[int, bool, bytes, str]], None]

property default: Optional[Union[int, bool, bytes, str, List[Union[int, bool, bytes, str]]]]

Returns the default value if one is set.

property description: str

A short description of what the Requirement is designed to affect or achieve.

instance_type

alias of bool

property name: str

The name of the Requirement.

Names cannot contain CONFIG_SEPARATOR (‘.’ by default) since this is used within the configuration hierarchy.

property optional: bool

Whether the Requirement is optional or not.

remove_requirement(requirement)[source]

Always raises a TypeError as instance requirements cannot have children.

property requirements: Dict[str, RequirementInterface]

Returns a dictionary of all the child requirements, indexed by name.

unsatisfied(context, config_path)[source]

Validates the instance requirement based upon its instance_type.

Return type

Dict[str, RequirementInterface]

unsatisfied_children(context, config_path)

Method that will validate all child requirements.

Parameters
  • context (ContextInterface) – the context containing the configuration data for this requirement

  • config_path (str) – the configuration path of this instance of the requirement

Return type

Dict[str, RequirementInterface]

Returns

A dictionary of full configuration paths for each unsatisfied child-requirement

class VersionableInterface(*args, **kwargs)[source]

Bases: object

A class that allows version checking so that plugins can request specific versions of components they made need

This currently includes other Plugins and scanners, but may be extended in the future

All version number should use semantic versioning

version = (0, 0, 0)
parent_path(value)[source]

Returns the parent configuration path from a configuration path.

Return type

str

path_depth(path, depth=1)[source]

Returns the path up to a certain depth.

Note that depth can be negative (such as -x) and will return all elements except for the last x components

Return type

str

path_head(value)[source]

Return the top of the configuration path

Return type

str

path_join(*args)[source]

Joins configuration paths together.

Return type

str