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
andSymbolTableRequirement
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
- 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 requirementconfig_path (
str
) – the configuration path of the instance of the requirement to be recovereddefault (
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.
- remove_requirement(requirement)¶
Removes a child from the list of requirements.
- Parameters
requirement (
RequirementInterface
) – The requirement to remove as a child-requirement- Return type
- property requirements: Dict[str, RequirementInterface]¶
Returns a dictionary of all the child requirements, indexed by name.
- unsatisfied_children(context, config_path)¶
Method that will validate all child requirements.
- Parameters
context (
ContextInterface
) – the context containing the configuration data for this requirementconfig_path (
str
) – the configuration path of this instance of the requirement
- Return type
- 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
- property config: HierarchicalDict¶
The Hierarchical configuration Dictionary for this Configurable object.
- 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
- 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 configurationbase_config_path (
str
) – The base configuration path on which to build the new configurationkwargs – Keyword arguments that are used to populate the new configuration path
- Returns
The newly generated full configuration path
- Return type
- 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
- 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 requirementdescription (
Optional
[str
]) – A short textual description of the requirementdefault (
Union
[int
,bool
,bytes
,str
,List
[Union
[int
,bool
,bytes
,str
]],None
]) – The default value for the requirement if no value is providedoptional (
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
- build_configuration(context, config_path, value)[source]¶
Proxies to a ConfigurableInterface if necessary.
- Return type
- 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 requirementconfig_path (
str
) – the configuration path of the instance of the requirement to be recovereddefault (
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.
- remove_requirement(requirement)¶
Removes a child from the list of requirements.
- Parameters
requirement (
RequirementInterface
) – The requirement to remove as a child-requirement- Return type
- 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 requirementconfig_path (
str
) – The configuration path for this requirement to test satisfaction
- Return type
- 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 requirementconfig_path (
str
) – the configuration path of this instance of the requirement
- Return type
- 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
- 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 requirementconfig_path (
str
) – the configuration path of the instance of the requirement to be recovereddefault (
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 constructableconfig_path (
str
) – The configuration path for the specific instance of this constructable
- Return type
- 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.
- remove_requirement(requirement)¶
Removes a child from the list of requirements.
- Parameters
requirement (
RequirementInterface
) – The requirement to remove as a child-requirement- Return type
- 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 requirementconfig_path (
str
) – The configuration path for this requirement to test satisfaction
- Return type
- 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 requirementconfig_path (
str
) – the configuration path of this instance of the requirement
- Return type
- 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 initiallyseparator (
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
- 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
- Returns
A duplicate HierarchicalDict of this object
- 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 valuevalue (
HierarchicalDict
) – HierarchicalDict to be merged under the key nodeoverwrite (
bool
) – A boolean defining whether the value will be overwritten if it already exists
- Return type
- 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
- 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
andStringRequirement
) or complex types (such asTranslationLayerRequirement
,SymbolTableRequirement
andClassRequirement
- Parameters
name (
str
) – The name of the requirementdescription (
Optional
[str
]) – A short textual description of the requirementdefault (
Union
[int
,bool
,bytes
,str
,List
[Union
[int
,bool
,bytes
,str
]],None
]) – The default value for the requirement if no value is providedoptional (
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
- 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 requirementconfig_path (
str
) – the configuration path of the instance of the requirement to be recovereddefault (
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.
- 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
- 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 requirementconfig_path (
str
) – The configuration path for this requirement to test satisfaction
- Return type
- 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 requirementconfig_path (
str
) – the configuration path of this instance of the requirement
- Return type
- 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 requirementdescription (
Optional
[str
]) – A short textual description of the requirementdefault (
Union
[int
,bool
,bytes
,str
,List
[Union
[int
,bool
,bytes
,str
]],None
]) – The default value for the requirement if no value is providedoptional (
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 requirementconfig_path (
str
) – the configuration path of the instance of the requirement to be recovereddefault (
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.
- 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
- unsatisfied_children(context, config_path)¶
Method that will validate all child requirements.
- Parameters
context (
ContextInterface
) – the context containing the configuration data for this requirementconfig_path (
str
) – the configuration path of this instance of the requirement
- Return type
- 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