dfvfs.helpers package

Submodules

dfvfs.helpers.command_line module

Helpers for command line tools.

class dfvfs.helpers.command_line.CLIInputReader(encoding='utf-8')[source]

Bases: object

Command line interface input reader interface.

abstract Read()[source]

Reads a string from the input.

Returns:

input.

Return type:

str

__init__(encoding='utf-8')[source]

Initializes an input reader.

Parameters:

encoding (Optional[str]) – input encoding.

class dfvfs.helpers.command_line.CLIOutputWriter(encoding='utf-8')[source]

Bases: object

Command line interface output writer interface.

Flush()[source]

Flushes buffered data to the output.

abstract Write(string)[source]

Writes a string to the output.

Parameters:

string (str) – output.

__init__(encoding='utf-8')[source]

Initializes an output writer.

Parameters:

encoding (Optional[str]) – output encoding.

class dfvfs.helpers.command_line.CLITabularTableView(column_names=None, column_sizes=None)[source]

Bases: object

Command line interface tabular table view.

AddRow(values)[source]

Adds a row of values.

Parameters:

values (list[object]) – values.

Raises:

ValueError – if the number of values is out of bounds.

Write(output_writer)[source]

Writes the table to output writer.

Parameters:

output_writer (CLIOutputWriter) – output writer.

__init__(column_names=None, column_sizes=None)[source]

Initializes a command line interface tabular table view.

Parameters:
  • column_names (Optional[list[str]]) – column names.

  • column_sizes (Optional[list[int]]) – minimum column sizes, in number of characters. If a column name or row value is larger than the minimum column size the column will be enlarged. Note that the minimum columns size will be rounded up to the number of spaces of the next tab.

class dfvfs.helpers.command_line.CLIVolumeScannerMediator(input_reader=None, output_writer=None)[source]

Bases: VolumeScannerMediator

Command line volume scanner mediator.

GetAPFSVolumeIdentifiers(volume_system, volume_identifiers)[source]

Retrieves APFS volume identifiers.

This method can be used to prompt the user to provide APFS volume identifiers.

Parameters:
  • volume_system (APFSVolumeSystem) – volume system.

  • volume_identifiers (list[str]) – volume identifiers including prefix.

Returns:

selected volume identifiers including prefix or None.

Return type:

list[str]

GetLVMVolumeIdentifiers(volume_system, volume_identifiers)[source]

Retrieves LVM volume identifiers.

This method can be used to prompt the user to provide LVM volume identifiers.

Parameters:
  • volume_system (LVMVolumeSystem) – volume system.

  • volume_identifiers (list[str]) – volume identifiers including prefix.

Returns:

selected volume identifiers including prefix or None.

Return type:

list[str]

GetPartitionIdentifiers(volume_system, volume_identifiers)[source]

Retrieves partition identifiers.

This method can be used to prompt the user to provide partition identifiers.

Parameters:
  • volume_system (VolumeSystem) – volume system.

  • volume_identifiers (list[str]) – volume identifiers including prefix.

Returns:

selected volume identifiers including prefix or None.

Return type:

list[str]

GetVSSStoreIdentifiers(volume_system, volume_identifiers)[source]

Retrieves VSS store identifiers.

This method can be used to prompt the user to provide VSS store identifiers.

Parameters:
  • volume_system (VShadowVolumeSystem) – volume system.

  • volume_identifiers (list[str]) – volume identifiers including prefix.

Returns:

selected volume identifiers including prefix or None.

Return type:

list[str]

ParseVolumeIdentifiersString(volume_identifiers_string)[source]

Parses a user specified volume identifiers string.

Parameters:

volume_identifiers_string (str) – user specified volume identifiers. A range of volumes can be defined as: “3..5”. Multiple volumes can be defined as: “1,3,5” (a list of comma separated values). Ranges and lists can also be combined as: “1,3..5”. The first volume is 1. All volumes can be defined as “all”. No volumes can be defined as an empty string or “none”.

Returns:

volume identifiers with prefix or the string “all”.

Return type:

list[str]

Raises:

ValueError – if the volume identifiers string is invalid.

PrintWarning(warning)[source]

Prints a warning.

Parameters:

warning (str) – warning text.

UnlockEncryptedVolume(source_scanner_object, scan_context, locked_scan_node, credentials)[source]

Unlocks an encrypted volume.

This method can be used to prompt the user to provide encrypted volume credentials.

Parameters:
Returns:

True if the volume was unlocked.

Return type:

bool

__init__(input_reader=None, output_writer=None)[source]

Initializes a volume scanner mediator.

Parameters:
  • input_reader (Optional[CLIInputReader]) – input reader, where None indicates that the stdin input reader should be used.

  • output_writer (Optional[CLIOutputWriter]) – output writer, where None indicates that the stdout output writer should be used.

class dfvfs.helpers.command_line.FileObjectInputReader(file_object, encoding='utf-8')[source]

Bases: CLIInputReader

File object command line interface input reader.

This input reader relies on the file-like object having a readline method.

Read()[source]

Reads a string from the input.

Returns:

input.

Return type:

str

__init__(file_object, encoding='utf-8')[source]

Initializes a file object input reader.

Parameters:
  • file_object (file) – file-like object to read from.

  • encoding (Optional[str]) – input encoding.

class dfvfs.helpers.command_line.FileObjectOutputWriter(file_object, encoding='utf-8')[source]

Bases: CLIOutputWriter

File object command line interface output writer.

This output writer relies on the file-like object having a write method.

Write(string)[source]

Writes a string to the output.

Parameters:

string (str) – output.

__init__(file_object, encoding='utf-8')[source]

Initializes a file object output writer.

Parameters:
  • file_object (file) – file-like object to read from.

  • encoding (Optional[str]) – output encoding.

class dfvfs.helpers.command_line.StdinInputReader(encoding='utf-8')[source]

Bases: FileObjectInputReader

Stdin command line interface input reader.

__init__(encoding='utf-8')[source]

Initializes a stdin input reader.

Parameters:

encoding (Optional[str]) – input encoding.

class dfvfs.helpers.command_line.StdoutOutputWriter(encoding='utf-8')[source]

Bases: CLIOutputWriter

Stdout command line interface output writer.

Flush()[source]

Flushes buffered data to the output.

Write(string)[source]

Writes a string to the output.

Parameters:

string (str) – output.

__init__(encoding='utf-8')[source]

Initializes a stdout output writer.

Parameters:

encoding (Optional[str]) – output encoding.

dfvfs.helpers.data_slice module

A data slice interface for file-like objects.

class dfvfs.helpers.data_slice.DataSlice(file_object)[source]

Bases: object

Data slice interface for file-like objects.

__enter__()[source]

Enters a with statement.

__exit__(unused_type, unused_value, unused_traceback)[source]

Exits a with statement.

__getitem__(key)[source]

Retrieves a range of file data.

Parameters:

key (int|slice) – offset or range of offsets to retrieve file data from.

Returns:

range of file data.

Return type:

bytes

Raises:
  • TypeError – if the type of the key is not supported.

  • ValueError – if the step value of a slice is not None.

__init__(file_object)[source]

Initializes the data slice.

Parameters:

file_object (FileIO) – a file-like object to read from.

__len__()[source]

Retrieves the file data size.

Returns:

file data size.

Return type:

int

dfvfs.helpers.fake_file_system_builder module

A builder for fake file systems.

class dfvfs.helpers.fake_file_system_builder.FakeFileSystemBuilder[source]

Bases: object

Builder object for fake file systems.

file_system

fake file system.

Type:

FakeFileSystem

AddDirectory(path)[source]

Adds a directory to the fake file system.

Note that this function will create parent directories if needed.

Parameters:

path (str) – path of the directory within the fake file system.

Raises:

ValueError – if the path is already set.

AddFile(path, file_data)[source]

Adds a “regular” file to the fake file system.

Note that this function will create parent directories if needed.

Parameters:
  • path (str) – path of the file within the fake file system.

  • file_data (bytes) – data of the file.

Raises:

ValueError – if the path is already set.

AddFileReadData(path, file_data_path)[source]

Adds a “regular” file to the fake file system.

Parameters:
  • path (str) – path of the file within the fake file system.

  • file_data_path (str) – path of the file to read the file data from.

Raises:

ValueError – if the path is already set.

Adds a symbolic link to the fake file system.

Parameters:
  • path (str) – path of the symbolic link within the fake file system.

  • linked_path (str) – path that is linked.

Raises:

ValueError – if the path is already set.

__init__()[source]

Initializes a fake file system builder.

dfvfs.helpers.file_system_searcher module

A searcher to find file entries within a file system.

class dfvfs.helpers.file_system_searcher.FileSystemSearcher(file_system, mount_point)[source]

Bases: object

Searcher to find file entries within a file system.

Find(find_specs=None)[source]

Searches for matching file entries within the file system.

Parameters:

find_specs (Optional[list[FindSpec]]) – find specifications, where None will return all allocated file entries.

Yields:

PathSpec – path specification of a matching file entry.

GetFileEntryByPathSpec(path_spec)[source]

Retrieves a file entry for a path specification.

Parameters:

path_spec (PathSpec) – path specification.

Returns:

file entry or None.

Return type:

FileEntry

GetRelativePath(path_spec)[source]

Returns the relative path based on a resolved path specification.

The relative path is the location of the upper most path specification. The the location of the mount point is stripped off if relevant.

Parameters:

path_spec (PathSpec) – path specification.

Returns:

corresponding relative path or None if the relative path could not

be determined.

Return type:

str

Raises:

PathSpecError – if the path specification is incorrect.

SplitPath(path)[source]

Splits the path into path segments.

Parameters:

path (str) – path.

Returns:

path segments without the root path segment, which is an

empty string.

Return type:

list[str]

__init__(file_system, mount_point)[source]

Initializes a file system searcher.

Parameters:
  • file_system (FileSystem) – file system.

  • mount_point (PathSpec) – mount point path specification that refers to the base location of the file system.

Raises:
  • PathSpecError – if the mount point path specification is incorrect.

  • ValueError – when file system or mount point is not set.

class dfvfs.helpers.file_system_searcher.FindSpec(case_sensitive=True, file_entry_types=None, is_allocated=True, location=None, location_glob=None, location_regex=None, location_separator='/')[source]

Bases: object

Find specification.

AtLastLocationSegment(segment_index)[source]

Determines if the a location segment is the last one or greater.

Parameters:

segment_index (int) – index of the location path segment.

Returns:

True if at maximum depth, False if not.

Return type:

bool

CompareLocation(file_entry, mount_point=None)[source]

Compares a file entry location against the find specification.

Parameters:
  • file_entry (FileEntry) – file entry.

  • mount_point (Optional[PathSpec]) – mount point path specification that refers to the base location of the file system. The mount point is ignored if it is not an OS path specification.

Returns:

True if the location of the file entry matches that of the find

specification, False if not or if the find specification has no location defined.

Return type:

bool

Raises:

ValueError – if mount point is set and is of type OS and the location of the path specification of the file entry falls outside the mount point.

CompareNameWithLocationSegment(file_entry, segment_index)[source]

Compares a file entry name against a find specification location segment.

Parameters:
  • file_entry (FileEntry) – file entry.

  • segment_index (int) – index of the location segment to compare against, where 0 represents the root segment.

Returns:

True if the location segment of the file entry matches that of the

find specification, False if not or if the find specification has no location defined.

Return type:

bool

ComparePathSpecLocation(path_spec, file_system, mount_point=None)[source]

Compares a path specification location against the find specification.

Parameters:
  • path_spec (PathSpec) – path specification.

  • file_system (FileSystem) – file system.

  • mount_point (Optional[PathSpec]) – mount point path specification that refers to the base location of the file system. The mount point is ignored if it is not an OS path specification.

Returns:

True if the location of the file entry matches that of the find

specification, False if not or if the find specification has no location defined.

Return type:

bool

Raises:

ValueError – if mount point is set and is of type OS and the location of the path specification of the file entry falls outside the mount point.

CompareTraits(file_entry)[source]

Compares a file entry traits against the find specification.

Parameters:

file_entry (FileEntry) – file entry.

Returns:

True if the traits of the file entry, such as type, matches the

find specification, False otherwise.

Return type:

bool

HasLocation()[source]

Determines if the find specification has a location defined.

Returns:

True if find specification has a location defined, False if not.

Return type:

bool

IsLastLocationSegment(segment_index)[source]

Determines if the a location segment is the last one.

Parameters:

segment_index (int) – index of the location path segment.

Returns:

True if at maximum depth, False if not.

Return type:

bool

__init__(case_sensitive=True, file_entry_types=None, is_allocated=True, location=None, location_glob=None, location_regex=None, location_separator='/')[source]

Initializes a find specification.

Parameters:
  • case_sensitive (Optional[bool]) – True if string matches should be case sensitive.

  • file_entry_types (Optional[list[str]]) – file entry types, where None indicates no preference.

  • is_allocated (Optional[bool]) – True if the file entry should be allocated, where None represents no preference.

  • location (Optional[str|list[str]]) – location or location segments, where None indicates no preference. The location should be defined relative to the root of the file system. Note that the string will be split into segments based on the file system specific path segment separator.

  • (Optional[str (location_glob) – list[str]]): location glob or location glob segments, where None indicates no preference. The location glob should be defined relative to the root of the file system. The default is None. Note that the string will be split into segments based on the file system specific path segment separator.

  • location_regex (Optional[str|list[str]]) – location regular expression or location regular expression segments, where None indicates no preference. The location regular expression should be defined relative to the root of the file system. The default is None. Note that the string will be split into segments based on the file system specific path segment separator.

  • location_separator (str) – location segment separator.

Raises:
  • TypeError – if the location, location_glob or location_regex type is not supported.

  • ValueError – if the location, location_glob or location_regex arguments are used at the same time, or if location separator is missing and the location argument is of type string.

dfvfs.helpers.source_scanner module

Scanner for source files, directories and devices.

The source scanner tries to determine what input we are dealing with: * a file that contains a storage media image; * a device file of a storage media image device; * a regular file or directory.

The source scanner scans for different types of elements: * supported types of storage media images; * supported types of volume systems; * supported types of file systems.

These elements are represented as source scan nodes.

The source scanner uses the source scanner context to keep track of the nodea and user provided context information, such as: * which partition to default to; * which VSS stores to default to.

class dfvfs.helpers.source_scanner.SourceScanNode(path_spec)[source]

Bases: object

Source scan node.

credential

credential used to unlock the source scan node.

Type:

tuple[str, str]

path_spec

path specification.

Type:

PathSpec

parent_node

source scan parent node.

Type:

SourceScanNode

scanned

True if the source scan node has been fully scanned.

Type:

bool

sub_nodes

source scan sub nodes.

Type:

list[SourceScanNode]

GetSubNodeByLocation(location)[source]

Retrieves a sub scan node based on the location.

Parameters:

location (str) – location that should match the location of the path specification of a sub scan node.

Returns:

sub scan node or None if not available.

Return type:

SourceScanNode

GetUnscannedSubNode()[source]

Retrieves the first unscanned sub node.

Returns:

sub scan node or None if not available.

Return type:

SourceScanNode

IsFileSystem()[source]

Determines if the scan node represents a file system.

Returns:

True if the scan node represents a file system.

Return type:

bool

IsSystemLevel()[source]

Determines if the scan node has a path specification at system-level.

System-level is an indication used if the path specification is handled by the operating system and should not have a parent.

Returns:

True if the scan node has a path specification at system-level.

Return type:

bool

IsVolumeSystem()[source]

Determines if the scan node represents a volume system.

Returns:

True if the scan node represents a volume system.

Return type:

bool

IsVolumeSystemRoot()[source]

Determines if the scan node represents the root of a volume system.

Returns:

True if the scan node represents the root of a volume system.

Return type:

bool

SupportsEncryption()[source]

Determines if the scan node supports encryption.

Returns:

True if the scan node supports encryption.

Return type:

bool

__init__(path_spec)[source]

Initializes a source scan node.

Parameters:

path_spec (PathSpec) – path specification.

property type_indicator

Retrieves the type indicator.

Returns:

path specification type indicator.

Return type:

str

class dfvfs.helpers.source_scanner.SourceScanner(resolver_context=None)[source]

Bases: object

Searcher to find volumes within a volume system.

GetVolumeIdentifiers(volume_system)[source]

Retrieves the volume identifiers.

Parameters:

volume_system (VolumeSystem) – volume system.

Returns:

sorted volume identifiers.

Return type:

list[str]

Scan(scan_context, auto_recurse=True, scan_path_spec=None)[source]

Scans for supported formats.

Parameters:
  • scan_context (SourceScannerContext) – source scanner context.

  • auto_recurse (Optional[bool]) – True if the scan should automatically recurse as far as possible.

  • scan_path_spec (Optional[PathSpec]) – path specification to indicate where the source scanner should continue scanning, where None indicates the scanner will start with the sources.

Raises:

ValueError – if the scan context is invalid.

ScanForFileSystem(source_path_spec)[source]

Scans the path specification for a supported file system format.

Parameters:

source_path_spec (PathSpec) – source path specification.

Returns:

file system path specification or None if no supported file

system type was found.

Return type:

PathSpec

Raises:

BackEndError – if the source cannot be scanned or more than one file system type is found.

ScanForStorageMediaImage(source_path_spec)[source]

Scans the path specification for a supported storage media image format.

Parameters:

source_path_spec (PathSpec) – source path specification.

Returns:

storage media image path specification or None if no supported

storage media image type was found.

Return type:

PathSpec

Raises:

BackEndError – if the source cannot be scanned or more than one storage media image type is found.

ScanForVolumeSystem(source_path_spec)[source]

Scans the path specification for a supported volume system format.

Parameters:

source_path_spec (PathSpec) – source path specification.

Returns:

volume system path specification or None if no supported volume

system type was found.

Return type:

PathSpec

Raises:

BackEndError – if the source cannot be scanned or more than one volume system type is found.

Unlock(scan_context, path_spec, credential_identifier, credential_data)[source]

Unlocks a locked scan node e.g. the scan node of an encrypted volume.

Parameters:
  • scan_context (SourceScannerContext) – source scanner context.

  • path_spec (PathSpec) – path specification of the locked scan node.

  • credential_identifier (str) – credential identifier used to unlock the scan node.

  • credential_data (bytes) – credential data used to unlock the scan node.

Returns:

True if the scan node was successfully unlocked.

Return type:

bool

Raises:
  • BackEndError – if the scan node cannot be unlocked.

  • KeyError – if the scan node does not exists or is not locked.

__init__(resolver_context=None)[source]

Initializes a source scanner.

Parameters:

resolver_context (Optional[Context]) – resolver context, where None indicates to use the built-in context which is not multi process safe.

class dfvfs.helpers.source_scanner.SourceScannerContext[source]

Bases: object

Contextual information for the source scanner.

source_type

type of source.

Type:

str

updated

True if the source scanner context has been updated.

Type:

bool

AddScanNode(path_spec, parent_scan_node)[source]

Adds a scan node for a certain path specification.

Parameters:
  • path_spec (PathSpec) – path specification.

  • parent_scan_node (SourceScanNode) – parent scan node or None.

Returns:

scan node.

Return type:

SourceScanNode

Raises:
  • KeyError – if the scan node already exists.

  • RuntimeError – if the parent scan node is not present.

GetRootScanNode()[source]

Retrieves the root scan node.

Returns:

scan node or None if not available.

Return type:

SourceScanNode

GetScanNode(path_spec)[source]

Retrieves a scan node for a certain path specification.

Parameters:

path_spec (PathSpec) – path specification.

Returns:

scan node or None if not available.

Return type:

SourceScanNode

GetUnscannedScanNode()[source]

Retrieves the first unscanned scan node.

Returns:

scan node or None if not available.

Return type:

SourceScanNode

HasFileSystemScanNodes()[source]

Determines if a file system was detected during the scan.

Returns:

True if a file system was detected during the scan.

Return type:

bool

HasLockedScanNodes()[source]

Determines if a locked scan node was detected during the scan.

A locked scan node is e.g. an encrypted volume for which a credential, e.g. password, to unlock the volume is not available.

Returns:

True if a locked scan node was detected during the scan.

Return type:

bool

HasScanNode(path_spec)[source]

Determines if there is a scan node for a certain path specification.

Parameters:

path_spec (PathSpec) – path specification.

Returns:

True if there is a scan node for the path specification.

Return type:

bool

IsLockedScanNode(path_spec)[source]

Determines if a scan node is locked.

A locked scan node is e.g. an encrypted volume for which a credential, e.g. password, to unlock the volume is not available.

Parameters:

path_spec (PathSpec) – path specification.

Returns:

True if the scan node is locked.

Return type:

bool

IsSourceTypeDirectory()[source]

Determines if the source type is a directory.

Returns:

True if the source type is a directory, False if not or

None if not set.

Return type:

bool

IsSourceTypeFile()[source]

Determines if the source type is a file.

Returns:

True if the source type is a file, False if not or None if not set.

Return type:

bool

LockScanNode(path_spec)[source]

Marks a scan node as locked.

Parameters:

path_spec (PathSpec) – path specification.

Raises:

KeyError – if the scan node does not exists.

OpenSourcePath(source_path)[source]

Opens the source path.

Parameters:

source_path (str) – source path.

RemoveScanNode(path_spec)[source]

Removes a scan node of a certain path specification.

Parameters:

path_spec (PathSpec) – path specification.

Returns:

parent scan node or None if not available.

Return type:

SourceScanNode

Raises:

RuntimeError – if the scan node has sub nodes.

SOURCE_TYPE_DIRECTORY = 'directory'
SOURCE_TYPE_FILE = 'file'
SOURCE_TYPE_STORAGE_MEDIA_DEVICE = 'storage media device'
SOURCE_TYPE_STORAGE_MEDIA_IMAGE = 'storage media image'
SetSourceType(source_type)[source]

Sets the source type.

Parameters:

source_type (str) – source type.

UnlockScanNode(path_spec, credential_identifier, credential_data)[source]

Marks a scan node as unlocked.

Parameters:
  • path_spec (PathSpec) – path specification.

  • credential_identifier (str) – credential identifier used to unlock the scan node.

  • credential_data (bytes) – credential data used to unlock the scan node.

Raises:

KeyError – if the scan node does not exists or is not locked.

__init__()[source]

Initializes a source scanner context.

property locked_scan_nodes

Retrieves the locked scan nodes.

Returns:

locked scan nodes.

Return type:

list[SourceScanNode]

dfvfs.helpers.text_file module

A text file interface for file-like objects.

class dfvfs.helpers.text_file.TextFile(file_object, encoding='utf-8', encoding_errors='strict', end_of_line='\n')[source]

Bases: object

Text file interface for file-like objects.

__enter__()[source]

Enters a with statement.

__exit__(unused_type, unused_value, unused_traceback)[source]

Exits a with statement.

__init__(file_object, encoding='utf-8', encoding_errors='strict', end_of_line='\n')[source]

Initializes the text file.

Parameters:
  • file_object (FileIO) – a file-like object to read from.

  • encoding (Optional[str]) – text encoding.

  • encoding_errors (Optional[str]) – text encoding errors handler.

  • end_of_line (Optional[str]) – end of line indicator.

__iter__()[source]

Returns a line of text.

Yields:

str – line of text.

get_offset()[source]

Retrieves the current offset into the file-like object.

Returns:

current offset into the file-like object.

Return type:

int

readline(size=None)[source]

Reads a single line of text.

The functions reads one entire line from the file-like object. A trailing end-of-line indicator (newline by default) is kept in the string (but may be absent when a file ends with an incomplete line). An empty string is returned only when end-of-file is encountered immediately.

Parameters:

size (Optional[int]) – maximum byte size to read. If present and non-negative, it is a maximum byte count (including the trailing end-of-line) and an incomplete line may be returned.

Returns:

line of text.

Return type:

str

Raises:
  • UnicodeDecodeError – if a line cannot be decoded and encoding errors is set to strict.

  • ValueError – if the size is smaller than zero or exceeds the maximum (as defined by _MAXIMUM_READ_BUFFER_SIZE).

readlines(sizehint=None)[source]

Reads lines of text.

The function reads until EOF using readline() and return a list containing the lines read.

Parameters:

sizehint (Optional[int]) – maximum byte size to read. If present, instead of reading up to EOF, whole lines totalling sizehint bytes are read.

Returns:

lines of text.

Return type:

list[str]

tell()[source]

Retrieves the current offset into the file-like object.

Returns:

current offset into the file-like object.

Return type:

int

dfvfs.helpers.volume_scanner module

Scanner for supported volume and file systems.

class dfvfs.helpers.volume_scanner.VolumeScanner(mediator=None)[source]

Bases: object

Volume scanner.

GetBasePathSpecs(source_path, options=None)[source]

Determines the base path specifications.

Parameters:
  • source_path (str) – source path.

  • options (Optional[VolumeScannerOptions]) – volume scanner options. If None the default volume scanner options are used, which are defined in the VolumeScannerOptions class.

Returns:

path specifications.

Return type:

list[PathSpec]

Raises:

ScannerError – if the source path does not exists, or if the source path is not a file or directory, or if the format of or within the source file is not supported.

__init__(mediator=None)[source]

Initializes a volume scanner.

Parameters:

mediator (Optional[VolumeScannerMediator]) – a volume scanner mediator.

class dfvfs.helpers.volume_scanner.VolumeScannerMediator[source]

Bases: object

Volume scanner mediator.

abstract GetAPFSVolumeIdentifiers(volume_system, volume_identifiers)[source]

Retrieves APFS volume identifiers.

This method can be used to prompt the user to provide APFS volume identifiers.

Parameters:
  • volume_system (APFSVolumeSystem) – volume system.

  • volume_identifiers (list[str]) – volume identifiers including prefix.

Returns:

selected volume identifiers including prefix or None.

Return type:

list[str]

abstract GetLVMVolumeIdentifiers(volume_system, volume_identifiers)[source]

Retrieves LVM volume identifiers.

This method can be used to prompt the user to provide LVM volume identifiers.

Parameters:
  • volume_system (LVMVolumeSystem) – volume system.

  • volume_identifiers (list[str]) – volume identifiers including prefix.

Returns:

selected volume identifiers including prefix or None.

Return type:

list[str]

abstract GetPartitionIdentifiers(volume_system, volume_identifiers)[source]

Retrieves partition identifiers.

This method can be used to prompt the user to provide partition identifiers.

Parameters:
  • volume_system (TSKVolumeSystem) – volume system.

  • volume_identifiers (list[str]) – volume identifiers including prefix.

Returns:

selected volume identifiers including prefix or None.

Return type:

list[str]

abstract GetVSSStoreIdentifiers(volume_system, volume_identifiers)[source]

Retrieves VSS store identifiers.

This method can be used to prompt the user to provide VSS store identifiers.

Parameters:
  • volume_system (VShadowVolumeSystem) – volume system.

  • volume_identifiers (list[str]) – volume identifiers including prefix.

Returns:

selected volume identifiers including prefix or None.

Return type:

list[str]

GetVolumeIdentifiers(volume_system, volume_identifiers)[source]

Retrieves volume identifiers.

This method can be used to prompt the user to provide volume identifiers.

Parameters:
  • volume_system (APFSVolumeSystem) – volume system.

  • volume_identifiers (list[str]) – volume identifiers including prefix.

Returns:

selected volume identifiers including prefix or None.

Return type:

list[str]

GetVolumeSnapshotIdentifiers(volume_system, volume_identifiers)[source]

Retrieves volume snapshot identifiers.

This method can be used to prompt the user to provide volume snapshot identifiers.

Parameters:
  • volume_system (APFSVolumeSystem) – volume system.

  • volume_identifiers (list[str]) – volume identifiers including prefix.

Returns:

selected volume identifiers including prefix or None.

Return type:

list[str]

abstract UnlockEncryptedVolume(source_scanner_object, scan_context, locked_scan_node, credentials)[source]

Unlocks an encrypted volume.

This method can be used to prompt the user to provide encrypted volume credentials.

Parameters:
Returns:

True if the volume was unlocked.

Return type:

bool

class dfvfs.helpers.volume_scanner.VolumeScannerOptions[source]

Bases: object

Volume scanner options.

credentials

credentials, per type, to unlock volumes.

Type:

list[tuple[str, str]]

partitions

partition identifiers.

Type:

list[str]

scan_mode

mode that defines how the VolumeScanner should scan for volumes and snapshots.

Type:

str

snapshots

snapshot identifiers.

Type:

list[str]

volumes

volume identifiers, e.g. those of an APFS or LVM volume system.

Type:

list[str]

SCAN_MODE_ALL = 'all'
SCAN_MODE_SNAPSHOTS_ONLY = 'snapshots-only'
SCAN_MODE_VOLUMES_ONLY = 'volumes-only'
__init__()[source]

Initializes volume scanner options.

class dfvfs.helpers.volume_scanner.WindowsVolumeScanner(mediator=None)[source]

Bases: VolumeScanner

Windows volume scanner.

OpenFile(windows_path)[source]

Opens the file specified by the Windows path.

Parameters:

windows_path (str) – Windows path to the file.

Returns:

file-like object or None if the file does not exist.

Return type:

FileIO

ScanForWindowsVolume(source_path, options=None)[source]

Scans for a Windows volume.

Parameters:
  • source_path (str) – source path.

  • options (Optional[VolumeScannerOptions]) – volume scanner options. If None the default volume scanner options are used, which are defined in the VolumeScannerOptions class.

Returns:

True if a Windows volume was found.

Return type:

bool

Raises:

ScannerError – if the source path does not exists, or if the source path is not a file or directory, or if the format of or within the source file is not supported.

__init__(mediator=None)[source]

Initializes a Windows volume scanner.

Parameters:

mediator (VolumeScannerMediator) – a volume scanner mediator.

dfvfs.helpers.windows_path_resolver module

A resolver for Windows paths to file system specific formats.

class dfvfs.helpers.windows_path_resolver.WindowsPathResolver(file_system, mount_point, drive_letter='C')[source]

Bases: object

Resolver object for Windows paths.

GetWindowsPath(path_spec)[source]

Returns the Windows path based on a resolved path specification.

Parameters:

path_spec (PathSpec) – a path specification.

Returns:

corresponding Windows path or None if the Windows path could not

be determined.

Return type:

str

Raises:

PathSpecError – if the path specification is incorrect.

ResolvePath(path, expand_variables=True)[source]

Resolves a Windows path in file system specific format.

Parameters:
  • path (str) – Windows path to resolve.

  • expand_variables (Optional[bool]) – True if path variables should be expanded or not.

Returns:

path specification in file system specific format.

Return type:

PathSpec

SetEnvironmentVariable(name, value)[source]

Sets an environment variable in the Windows path helper.

Parameters:
  • name (str) – name of the environment variable without enclosing %-characters, e.g. SystemRoot as in %SystemRoot%.

  • value (str) – value of the environment variable.

__init__(file_system, mount_point, drive_letter='C')[source]

Initializes a Windows path helper.

The mount point indicates a path specification where the Windows file system is mounted. This can either be a path specification into a storage media image or a directory accessible by the operating system.

Parameters:
  • file_system (FileSystem) – a file system.

  • mount_point (PathSpec) – mount point path specification.

  • drive_letter (Optional[str]) – drive letter used by the file system.

Raises:
  • PathSpecError – if the mount point path specification is incorrect.

  • ValueError – when file system or mount point is not set.

Module contents