diff --git a/volatility/framework/automagic/__init__.py b/volatility/framework/automagic/__init__.py index 5936f6aaa..bde06def5 100644 --- a/volatility/framework/automagic/__init__.py +++ b/volatility/framework/automagic/__init__.py @@ -17,13 +17,17 @@ from volatility.framework.configuration import requirements vollog = logging.getLogger(__name__) -def available(context, config_path = 'automagic'): +def available(context): """Returns an ordered list of all subclasses of :class:`~volatility.framework.interfaces.automagic.AutomagicInterface`. The order is based on the priority attributes of the subclasses, in order to ensure the automagics are listed in an appropriate order. + + :param context: The context that will contain any automagic configuration values. + :type context: volatility.framework.interfaces.context.ContextInterface """ import_files(sys.modules[__name__]) + config_path = 'automagic' return sorted([clazz(context, interfaces.configuration.path_join(config_path, clazz.__name__)) for clazz in class_subclasses(interfaces.automagic.AutomagicInterface)], key = lambda x: x.priority) diff --git a/volatility/framework/automagic/construct_layers.py b/volatility/framework/automagic/construct_layers.py index 3de5a7653..193ac048e 100644 --- a/volatility/framework/automagic/construct_layers.py +++ b/volatility/framework/automagic/construct_layers.py @@ -14,7 +14,7 @@ class ConstructionMagic(interfaces.automagic.AutomagicInterface): and from the bottom of the tree upwards, attempt to construct all :class:`~volatility.framework.interfaces.configuration.ConstructableRequirementInterface` based classes. - :warning: This `automagic` should run first to prevent existing configurations getting re-configured. + :warning: This `automagic` should run first to allow existing configurations to have been constructed for use by later automagic """ priority = 0 diff --git a/volatility/framework/interfaces/automagic.py b/volatility/framework/interfaces/automagic.py index 2be2b12d4..0ee46b0be 100644 --- a/volatility/framework/interfaces/automagic.py +++ b/volatility/framework/interfaces/automagic.py @@ -1,4 +1,7 @@ -"""Defines the automagic interfaces for populating the context before a plugin runs""" +"""Defines the automagic interfaces for populating the context before a plugin runs + +Automagic objects attempt to automatically fill configuration values that a user has not filled. +""" from abc import ABCMeta, abstractmethod @@ -8,9 +11,28 @@ from volatility.framework.interfaces import configuration as interfaces_configur class AutomagicInterface(interfaces_configuration.ConfigurableInterface, metaclass = ABCMeta): - """Class that defines an automagic component that can help fulfill a Requirement""" + """Class that defines an automagic component that can help fulfill a Requirement + + These classes are callable with the following parameters: + + :param context: The context in which to store configuration data that the automagic might populate + :type context: ~volatility.framework.interfaces.context.ContextInterface + :param config_path: Configuration path where the configurable's data under the context's config lives + :type config_path: str + :param configurable: The top level configurable whose requirements may need statisfying + :type configurable: ~volatility.framework.interfaces.configuration.ConfigurableInterface + :param progress_callback: An optional function accepting a percentage and optional description to indicate + progress during long calculations + + .. note:: + + The `context` provided here may be different to that provided during initialization. The `context` provided at + initialization should be used for local configuration of the automagic itself, the `context` provided during + the call is to be populated by the automagic. + """ priority = 10 + """An ordering to indicate how soon this automagic should be run""" def __init__(self, context, config_path, *args, **kwargs): super().__init__(context, config_path)