dfvfs.helpers package

Submodules

dfvfs.helpers.command_line module

Helpers for command line tools.

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

Bases: object

Command line interface input reader interface.

abstract Read()

Reads a string from the input.

Returns

input.

Return type

str

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

Bases: object

Command line interface output writer interface.

Flush()

Flushes buffered data to the output.

abstract Write(string)

Writes a string to the output.

Parameters

string (str) – output.

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

Bases: object

Command line interface tabular table view.

AddRow(values)

Adds a row of values.

Parameters

values (list[object]) – values.

Raises

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

Write(output_writer)

Writes the table to output writer.

Parameters

output_writer (CLIOutputWriter) – output writer.

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

Bases: VolumeScannerMediator

Command line volume scanner mediator.

GetAPFSVolumeIdentifiers(volume_system, volume_identifiers)

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)

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)

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)

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)

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)

Prints a warning.

Parameters

warning (str) – warning text.

UnlockEncryptedVolume(source_scanner_object, scan_context, locked_scan_node, credentials)

Unlocks an encrypted volume.

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

Parameters

• source_scanner_object (SourceScanner) – source scanner.

• scan_context (SourceScannerContext) – source scanner context.

• locked_scan_node (SourceScanNode) – locked scan node.

• credentials (Credentials) – credentials supported by the locked scan node.

Returns

True if the volume was unlocked.

Return type

bool

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

Bases: CLIInputReader

File object command line interface input reader.

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

Read()

Reads a string from the input.

Returns

input.

Return type

str

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

Bases: CLIOutputWriter

File object command line interface output writer.

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

Write(string)

Writes a string to the output.

Parameters

string (str) – output.

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

Bases: FileObjectInputReader

Stdin command line interface input reader.

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

Bases: CLIOutputWriter

Stdout command line interface output writer.

Flush()

Flushes buffered data to the output.

Write(string)

Writes a string to the output.

Parameters

string (str) – output.

dfvfs.helpers.data_slice module

A data slice interface for file-like objects.

class dfvfs.helpers.data_slice.DataSlice(file_object)

Bases: object

Data slice interface for file-like objects.

__enter__()

Enters a with statement.

__exit__(unused_type, unused_value, unused_traceback)

Exits a with statement.

__getitem__(key)

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.

__len__()

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

Bases: object

Builder object for fake file systems.

file_system

fake file system.

Type

FakeFileSystem

AddDirectory(path)

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)

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)

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.

AddSymbolicLink(path, linked_path)

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.

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)

Bases: object

Searcher to find file entries within a file system.

Find(find_specs=None)

Searches for matching file entries within the file system.

Parameters

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

Yields

PathSpec – path specification of a matching file entry.

GetFileEntryByPathSpec(path_spec)

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)

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)

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]

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='/')

Bases: object

Find specification.

AtLastLocationSegment(segment_index)

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)

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)

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

CompareTraits(file_entry)

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()

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)

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

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)

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)

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()

Retrieves the first unscanned sub node.

Returns

sub scan node or None if not available.

Return type

SourceScanNode

IsFileSystem()

Determines if the scan node represents a file system.

Returns

True if the scan node represents a file system.

Return type

bool

IsSystemLevel()

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()

Determines if the scan node represents a volume system.

Returns

True if the scan node represents a volume system.

Return type

bool

IsVolumeSystemRoot()

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()

Determines if the scan node supports encryption.

Returns

True if the scan node supports encryption.

Return type

bool

property type_indicator

path specification type indicator.

Type

str

class dfvfs.helpers.source_scanner.SourceScanner(resolver_context=None)

Bases: object

Searcher to find volumes within a volume system.

GetVolumeIdentifiers(volume_system)

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)

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)

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)

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)

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)

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.

class dfvfs.helpers.source_scanner.SourceScannerContext

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)

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()

Retrieves the root scan node.

Returns

scan node or None if not available.

Return type

SourceScanNode

GetScanNode(path_spec)

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()

Retrieves the first unscanned scan node.

Returns

scan node or None if not available.

Return type

SourceScanNode

HasFileSystemScanNodes()

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()

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)

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)

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()

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()

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)

Marks a scan node as locked.

Parameters

path_spec (PathSpec) – path specification.

Raises

KeyError – if the scan node does not exists.

OpenSourcePath(source_path)

Opens the source path.

Parameters

source_path (str) – source path.

RemoveScanNode(path_spec)

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)

Sets the source type.

Parameters

source_type (str) – source type.

UnlockScanNode(path_spec, credential_identifier, credential_data)

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.

property locked_scan_nodes

locked scan nodes.

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')

Bases: object

Text file interface for file-like objects.

__enter__()

Enters a with statement.

__exit__(unused_type, unused_value, unused_traceback)

Exits a with statement.

__iter__()

Returns a line of text.

Yields

str – line of text.

get_offset()

Retrieves the current offset into the file-like object.

Returns

current offset into the file-like object.

Return type

int

readline(size=None)

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)

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()

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)

Bases: object

Volume scanner.

GetBasePathSpecs(source_path, options=None)

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.

class dfvfs.helpers.volume_scanner.VolumeScannerMediator

Bases: object

Volume scanner mediator.

abstract GetAPFSVolumeIdentifiers(volume_system, volume_identifiers)

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)

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)

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)

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)

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)

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)

Unlocks an encrypted volume.

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

Parameters

• source_scanner_object (SourceScanner) – source scanner.

• scan_context (SourceScannerContext) – source scanner context.

• locked_scan_node (SourceScanNode) – locked scan node.

• credentials (Credentials) – credentials supported by the locked scan node.

Returns

True if the volume was unlocked.

Return type

bool

class dfvfs.helpers.volume_scanner.VolumeScannerOptions

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'

class dfvfs.helpers.volume_scanner.WindowsVolumeScanner(mediator=None)

Bases: VolumeScanner

Windows volume scanner.

OpenFile(windows_path)

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)

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.

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')

Bases: object

Resolver object for Windows paths.

GetWindowsPath(path_spec)

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)

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)

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.

Module contents