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.
- class dfvfs.helpers.command_line.CLIOutputWriter(encoding='utf-8')[source]
Bases:
object
Command line interface output writer interface.
- 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.
- 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.
- 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
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')[source]
Bases:
CLIInputReader
File object command line interface input reader.
This input reader relies on the file-like object having a readline method.
- 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.
- class dfvfs.helpers.command_line.StdinInputReader(encoding='utf-8')[source]
Bases:
FileObjectInputReader
Stdin command line interface input reader.
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.
- __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.
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
- 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.
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.
- 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.
- 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
- 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
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]
- parent_node
source scan parent node.
- Type
- 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
- GetUnscannedSubNode()[source]
Retrieves the first unscanned sub node.
- Returns
sub scan node or None if not available.
- Return type
- 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
- property type_indicator
path specification type indicator.
- 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
- 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
- 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
- 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.
- 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
- 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
- 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
- GetUnscannedScanNode()[source]
Retrieves the first unscanned scan node.
- Returns
scan node or None if not available.
- Return type
- 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
- 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.
- 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')[source]
Bases:
object
Text file interface for file-like objects.
- 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]
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.
- 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
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[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'
- 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
- 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.
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