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
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:

Return type

Dict[str, RequirementInterface]

unmet = configurable.unsatisfied(context, config_path)
if unmet:
    raise RuntimeError("Unsatisfied requirements: {}".format(unmet)
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: Optional[ContextInterface]
property layer_name: Optional[str]
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
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:

Return type

Dict[str, RequirementInterface]

unmet = configurable.unsatisfied(context, config_path)
if unmet:
    raise RuntimeError("Unsatisfied requirements: {}".format(unmet)
write(offset, value)[source]

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

Return type

None