volatility3.framework.interfaces.layers module

Defines layers for containing data.

One layer may combine other layers, map data based on the data itself, or map a procedure (such as decryption) across another layer of data.

class DataLayerInterface(context, config_path, name, metadata=None)[source]

Bases: ConfigurableInterface

A Layer that directly holds data (and does not translate it).

This is effectively a leaf node in a layer tree. It directly accesses a data source and exposes it within volatility.

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

property address_mask: int: Returns a mask which encapsulates all the active bits of an address for this layer.

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.

property dependencies: List[str]: A list of other layer names required by this layer.

Note

DataLayers must never define other layers

destroy()[source]

Causes a DataLayer to close any open handles, etc.

Systems that make use of Data Layers should call destroy when they are done with them. This will close all handles, and make the object unreadable (exceptions will be thrown using a DataLayer after destruction)

Return type:: None

classmethod get_requirements()[source]

Returns a list of Requirement objects for this type of layer.

Return type:: List[RequirementInterface]

abstract is_valid(offset, length=1)[source]

Returns a boolean based on whether the entire chunk of data (from offset to length) is valid or not.

Parameters:

offset (int) – The address to start determining whether bytes are readable/valid
length (int) – The number of bytes from offset of which to test the validity

Return type:

bool

Returns:

Whether the bytes are valid and accessible

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

abstract property maximum_address: int: Returns the maximum valid address of the space.

property metadata: Mapping: Returns a ReadOnly copy of the metadata published by this layer.

abstract property minimum_address: int: Returns the minimum valid address of the space.

property name: str: Returns the layer name.

abstract read(offset, length, pad=False)[source]

Reads an offset for length bytes and returns ‘bytes’ (not ‘str’) of length size.

If there is a fault of any kind (such as a page fault), an exception will be thrown unless pad is set, in which case the read errors will be replaced by null characters.

Parameters:

offset (int) – The offset at which to being reading within the layer
length (int) – The number of bytes to read within the layer
pad (bool) – A boolean indicating whether exceptions should be raised or bad bytes replaced with null characters

Return type:

bytes

Returns:

The bytes read from the layer, starting at offset for length bytes

scan(context, scanner, progress_callback=None, sections=None)[source]

Scans a Translation layer by chunk.

Note: this will skip missing/unmappable chunks of memory

Parameters:

context (ContextInterface) – The context containing the data layer
scanner (ScannerInterface) – The constructed Scanner object to be applied
progress_callback (Optional[Callable[[float, str], None]]) – Method that is called periodically during scanning to update progress
sections (Iterable[Tuple[int, int]]) – A list of (start, size) tuples defining the portions of the layer to scan

Return type:

Iterable[Any]

Returns:

The output iterable from the scanner object having been run against the layer

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]

abstract write(offset, data)[source]

Writes a chunk of data at offset.

Any unavailable sections in the underlying bases will cause an exception to be thrown. Note: Writes are not guaranteed atomic, therefore some data may have been written, even if an exception is thrown.

Return type:: None

class DummyProgress[source]

Bases: object

A class to emulate Multiprocessing/threading Value objects.

class LayerContainer[source]

Bases: Mapping

Container for multiple layers of data.

add_layer(layer)[source]

Adds a layer to memory model.

This will throw an exception if the required dependencies are not met

Parameters:: layer (DataLayerInterface) – the layer to add to the list of layers (based on layer.name)
Return type:: None

check_cycles()[source]

Runs through the available layers and identifies if there are cycles in the DAG.

Return type:: None

del_layer(name)[source]

Removes the layer called name.

This will throw an exception if other layers depend upon this layer

Parameters:: name (str) – The name of the layer to delete
Return type:: None

free_layer_name(prefix='layer')[source]

Returns an unused layer name to ensure no collision occurs when inserting a layer.

Parameters:: prefix (str) – A descriptive string with which to prefix the layer name
Return type:: str
Returns:: A string containing a name, prefixed with prefix, not currently in use within the LayerContainer

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

read(layer, offset, length, pad=False)[source]

Reads from a particular layer at offset for length bytes.

Returns ‘bytes’ not ‘str’

Parameters:

layer (str) – The name of the layer to read from
offset (int) – Where to begin reading within the layer
length (int) – How many bytes to read from the layer
pad (bool) – Whether to raise exceptions or return null bytes when errors occur

Return type:

bytes

Returns:

The result of reading from the requested layer

values() → an object providing a view on D's values

write(layer, offset, data)[source]

Writes to a particular layer at offset for length bytes.

Return type:: None

class ScannerInterface[source]

Bases: VersionableInterface

Class for layer scanners that return locations of particular values from within the data.

These are designed to be given a chunk of data and return a generator which yields any found items. They should NOT perform complex/time-consuming tasks, these should be carried out by the consumer of the generator on the items returned.

They will be provided all available data (therefore not necessarily contiguous) in ascending offset order, in chunks no larger than chunk_size + overlap where overlap is the amount of data read twice once at the end of an earlier chunk and once at the start of the next chunk.

It should be noted that the scanner can maintain state if necessary. Scanners should balance the size of chunk based on the amount of time scanning the chunk will take (ie, do not set an excessively large chunksize and try not to take a significant amount of time in the __call__ method).

Scanners must NOT return results found after self.chunk_size (ie, entirely contained within the overlap). It is the responsibility of the scanner not to return such duplicate results.

Scanners can mark themselves as thread_safe, if they do not require state in either their own class or the context. This will allow the scanner to be run in parallel against multiple blocks.

property context: ContextInterface | None

property layer_name: str | None

thread_safe = False

version = (0, 0, 0)

class TranslationLayerInterface(context, config_path, name, metadata=None)[source]

Bases: DataLayerInterface

Provides a layer that translates or transforms another layer or layers.

Translation layers always depend on another layer (typically translating offsets in a virtual offset space into a smaller physical offset space).

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

property address_mask: int: Returns a mask which encapsulates all the active bits of an address for this layer.

build_configuration()

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.

abstract property dependencies: List[str]: Returns a list of layer names that this layer translates onto.

destroy()

Causes a DataLayer to close any open handles, etc.

Systems that make use of Data Layers should call destroy when they are done with them. This will close all handles, and make the object unreadable (exceptions will be thrown using a DataLayer after destruction)

Return type:: None

classmethod get_requirements()

Returns a list of Requirement objects for this type of layer.

Return type:: List[RequirementInterface]

abstract is_valid(offset, length=1)

Returns a boolean based on whether the entire chunk of data (from offset to length) is valid or not.

Parameters:

offset (int) – The address to start determining whether bytes are readable/valid
length (int) – The number of bytes from offset of which to test the validity

Return type:

bool

Returns:

Whether the bytes are valid and accessible

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

abstract mapping(offset, length, ignore_errors=False)[source]

Returns a sorted iterable of (offset, sublength, mapped_offset, mapped_length, layer) mappings.

ignore_errors will provide all available maps with gaps, but their total length may not add up to the requested length This allows translation layers to provide maps of contiguous regions in one layer

Return type:: Iterable[Tuple[int, int, int, int, str]]

abstract property maximum_address: int: Returns the maximum valid address of the space.

property metadata: Mapping: Returns a ReadOnly copy of the metadata published by this layer.

abstract property minimum_address: int: Returns the minimum valid address of the space.

property name: str: Returns the layer name.

read(offset, length, pad=False)[source]

Reads an offset for length bytes and returns ‘bytes’ (not ‘str’) of length size.

Return type:: bytes

scan(context, scanner, progress_callback=None, sections=None)

Scans a Translation layer by chunk.

Note: this will skip missing/unmappable chunks of memory

Parameters:

context (ContextInterface) – The context containing the data layer
scanner (ScannerInterface) – The constructed Scanner object to be applied
progress_callback (Optional[Callable[[float, str], None]]) – Method that is called periodically during scanning to update progress
sections (Iterable[Tuple[int, int]]) – A list of (start, size) tuples defining the portions of the layer to scan

Return type:

Iterable[Any]

Returns:

The output iterable from the scanner object having been run against the layer

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]

write(offset, value)[source]

Writes a value at offset, distributing the writing across any underlying mapping.

Return type:: None