"""A `Context` maintains the accumulated state required for various plugins and framework functions. This has been made an object to allow quick swapping and changing of contexts, to allow a plugin to act on multiple different contexts without them interfering eith each other. """ import functools import hashlib import typing from volatility.framework import constants, interfaces, symbols, validity class Context(interfaces.context.ContextInterface): """Maintains the context within which to construct objects The context object is the main method of carrying around state that's been constructed for the purposes of investigating memory. It contains a symbol_space of all the symbols that can be accessed by plugins using the context. It also contains the memory made up of data and translation layers, and it contains a factory method for creating new objects. Other context objects can be constructed as long as they support the :class:`~volatility.framework.interfaces.context.ContextInterface`. This is the primary context object to be used in the volatility framework. It maintains the """ def __init__(self) -> None: """Initializes the context.""" super().__init__() self._symbol_space = symbols.SymbolSpace() self._memory = interfaces.layers.Memory() self._config = interfaces.configuration.HierarchicalDict() # ## Symbol Space Functions @property def config(self) -> interfaces.configuration.HierarchicalDict: """Returns a mutable copy of the configuration, but does not allow the whole configuration to be altered""" return self._config @config.setter def config(self, value: interfaces.configuration.HierarchicalDict) -> None: if not isinstance(value, interfaces.configuration.HierarchicalDict): raise TypeError("Config must be of type HierarchicalDict") self._config = value @property def symbol_space(self) -> interfaces.symbols.SymbolSpaceInterface: """The space of all symbols that can be accessed within this context. """ return self._symbol_space @property def memory(self) -> interfaces.layers.Memory: """A Memory object, allowing access to all data and translation layers currently available within the context""" return self._memory # ## Address Space Functions def add_layer(self, layer: interfaces.layers.DataLayerInterface) -> None: """Adds a named translation layer to the context Args: layer: The layer to be added to the memory Raises: volatility.framework.exceptions.LayerException: if the layer is already present, or has unmet dependencies """ self._memory.add_layer(layer) # ## Object Factory Functions def object(self, symbol: typing.Union[str, interfaces.objects.Template], layer_name: str, offset: int, native_layer_name: typing.Optional[str] = None, **arguments) -> interfaces.objects.ObjectInterface: """Object factory, takes a context, symbol, offset and optional layername Looks up the layername in the context, finds the object template based on the symbol, and constructs an object using the object template on the layer at the offset. Args: symbol: The name (or template) of the symbol type on which to construct the object. If this is a name, it should contain an explicit table name. layer_name: The name of the layer on which to construct the object offset: The offset within the layer at which the data used to create the object lives Returns: A fully constructed object """ if not isinstance(symbol, interfaces.objects.Template): object_template = self._symbol_space.get_type(symbol) else: object_template = symbol # Ensure that if a pre-constructed type is provided we just instantiate it arguments.update(object_template.vol) object_template = object_template.clone() object_template.update_vol(**arguments) return object_template(context = self, object_info = interfaces.objects.ObjectInformation(layer_name = layer_name, offset = offset, native_layer_name = native_layer_name)) @functools.lru_cache() def module(self, # type: ignore # FIXME: mypy #5107 module_name: str, layer_name: str, offset: int, native_layer_name: typing.Optional[str] = None, size: typing.Optional[int] = None) -> interfaces.context.ModuleInterface: """Creates a module object""" if size: return SizedModule(self, module_name = module_name, layer_name = layer_name, offset = offset, size = size, native_layer_name = native_layer_name) return Module(self, module_name = module_name, layer_name = layer_name, offset = offset, native_layer_name = native_layer_name) def get_module_wrapper(method: str) -> typing.Callable: """Returns a symbol using the symbol_table_name of the Module""" def wrapper(self, name: str) -> typing.Callable: self._check_type(name, str) if constants.BANG in name: raise ValueError("Name cannot reference another module") return getattr(self._context.symbol_space, method)(self._module_name + constants.BANG + name) return wrapper class Module(interfaces.context.ModuleInterface): def object(self, symbol_name: typing.Optional[str] = None, type_name: typing.Optional[str] = None, offset: typing.Optional[int] = None, native_layer_name: typing.Optional[str] = None, **kwargs) -> interfaces.objects.ObjectInterface: """Returns an object created using the symbol_table_name and layer_name of the Module @param symbol_name: Name of the symbol (within the module) to construct, type_name and offset must not be specified @type symbol_name: str @param type_name: Name of the type (within the module) to construct, offset must be specified and symbol_name must not @type type_name: str @param offset: The location (absolute within memory), type_name must be specified and symbol_name must not @type offset: int """ type_arg = None # type: typing.Optional[typing.Union[str, interfaces.objects.Template]] if symbol_name is not None: self._check_type(symbol_name, str) if constants.BANG in symbol_name: raise ValueError("Symbol_name cannot reference another module") symbol = self._context.symbol_space.get_symbol(self.symbol_table_name + constants.BANG + symbol_name) if symbol.type is None: raise ValueError("Symbol {} has no associated type information".format(symbol.name)) type_arg = symbol.type offset = symbol.address + self._offset elif type_name is not None and offset is not None: self._check_type(type_name, str) self._check_type(offset, int) if constants.BANG in type_name: raise ValueError("Type_name cannot reference another module") type_arg = self.symbol_table_name + constants.BANG + type_name else: raise ValueError("One of symbol_name, or type_name & offset, must be specified to construct a module") # Ensure we don't use a layer_name other than the module's, why would anyone do that? if 'layer_name' in kwargs: del kwargs['layer_name'] return self._context.object(type_arg, self._layer_name, offset, native_layer_name, **kwargs) get_symbol = get_module_wrapper('get_symbol') get_type = get_module_wrapper('get_type') get_enum = get_module_wrapper('get_enum') has_symbol = get_module_wrapper('has_symbol') has_type = get_module_wrapper('has_type') has_enum = get_module_wrapper('has_enum') class SizedModule(Module): def __init__(self, context: interfaces.context.ContextInterface, module_name: str, layer_name: str, offset: int, size: int, symbol_table_name: typing.Optional[str] = None, native_layer_name: typing.Optional[str] = None) -> None: super().__init__(context, module_name = module_name, layer_name = layer_name, offset = offset, native_layer_name = native_layer_name, symbol_table_name = symbol_table_name) self._size = self._check_type(size, int) @property def size(self) -> int: """Returns the size of the module (0 for unknown size)""" return self._size @property # type: ignore # FIXME: mypy #5107 @functools.lru_cache() def hash(self) -> str: """Hashes the module for equality checks The mapping should be sorted and should be quicker than reading the data We turn it into JSON to make a common string and use a quick hash, because collissions are unlikely""" layer = self._context.memory[self.layer_name] if not isinstance(layer, interfaces.layers.TranslationLayerInterface): raise TypeError("Hashing modules on non-TranslationLayers is not allowed") return hashlib.md5( bytes(str(list(layer.mapping(self.offset, self.size, ignore_errors = True))), 'utf-8')).hexdigest() def get_symbols_by_absolute_location(self, offset: int, size: int = 0) -> typing.List[str]: """Returns the symbols within this module that live at the specified absolute offset provided""" if size < 0: raise ValueError("Size must be strictly non-negative") if offset > self._offset + self.size: return [] return list(self._context.symbol_space.get_symbols_by_location(offset = offset - self._offset, size = size, table_name = self.symbol_table_name)) class ModuleCollection(validity.ValidityRoutines): """Class to contain a collection of SizedModules and reason about their contents""" def __init__(self, modules: typing.List[SizedModule]) -> None: for module in modules: self._check_type(module, SizedModule) self._modules = modules def deduplicate(self) -> 'ModuleCollection': """Returns a new deduplicated ModuleCollection featuring no repeated modules (based on data hash) All 0 sized modules will have identical hashes and are therefore included in the deduplicated version """ new_modules = [] seen = set() # type: typing.Set[str] for mod in self._modules: if mod.hash not in seen or mod.size == 0: new_modules.append(mod) seen.add(mod.hash) # type: ignore # FIXME: mypy #5107 return ModuleCollection(new_modules) @property def modules(self) -> typing.Dict[str, typing.List[SizedModule]]: """A name indexed dictionary of modules using that name in this collection""" return self._generate_module_dict(self._modules) @classmethod def _generate_module_dict(cls, modules: typing.List[SizedModule]) -> typing.Dict[str, typing.List[SizedModule]]: result = {} # type: typing.Dict[str, typing.List[SizedModule]] for module in modules: modlist = result.get(module.name, []) modlist.append(module) result[module.name] = modlist return result def get_module_symbols_by_absolute_location(self, offset: int, size: int = 0) -> \ typing.Iterable[typing.Tuple[str, typing.List[str]]]: """Returns a tuple of (module_name, list_of_symbol_names) for each module, where symbols live at the absolute offset in memory provided""" if size < 0: raise ValueError("Size must be strictly non-negative") for module in self._modules: if (offset <= module.offset + module.size) and (offset + size >= module.offset): yield (module.name, module.get_symbols_by_absolute_location(offset, size))