dissect.target.filesystem

Module Contents

Classes

Filesystem	Base class for filesystems.
FilesystemEntry	Base class for filesystem entries.
DirEntry	Directory entry base class. Closely models os.DirEntry.
VirtualDirEntry	Directory entry base class. Closely models os.DirEntry.
VirtualDirectory	Virtual directory implementation. Backed by a dict.
VirtualFileHandle	Base class for raw binary I/O.
VirtualFile	Virtual file backed by a file-like object.
MappedFile	Virtual file backed by a file on the host machine.
MappedCompressedFile	Virtual file backed by a compressed file on the host machine.
VirtualSymlink	Virtual symlink implementation.
VirtualFilesystem	Base class for filesystems.
LayerFilesystem	Base class for filesystems.
EntryList	Wrapper list for filesystem entries.
LayerDirEntry	Directory entry base class. Closely models os.DirEntry.
LayerFilesystemEntry	Base class for filesystem entries.
RootFilesystem	Base class for filesystems.
RootDirEntry	Directory entry base class. Closely models os.DirEntry.
RootFilesystemEntry	Base class for filesystem entries.

Functions

register	Register a filesystem implementation to use when opening a filesystem.
is_multi_volume_filesystem
open
open_multi_volume

Attributes

TarFilesystem
FILESYSTEMS
MODULE_PATH
log

dissect.target.filesystem.TarFilesystem

dissect.target.filesystem.FILESYSTEMS: list[type[Filesystem]] = []

dissect.target.filesystem.MODULE_PATH = 'dissect.target.filesystems'

dissect.target.filesystem.log

class dissect.target.filesystem.Filesystem(volume: BinaryIO | list[BinaryIO] | None = None, alt_separator: str = '', case_sensitive: bool = True)

Base class for filesystems.

__type__: str = None

A short string identifying the type of filesystem.

__multi_volume__: bool = False

Whether this filesystem supports multiple volumes (disks).

volume = None

case_sensitive = True

alt_separator = ''

__repr__() → str

path(*args) → dissect.target.helpers.fsutil.TargetPath

Instantiate a new path-like object on this filesystem.

classmethod detect(fh: BinaryIO) → bool

Detect whether the fh file-handle is supported by this Filesystem implementation.

The position of fh will be restored before returning.

Parameters:

fh – A file-like object, usually a disk or partition.

Returns:

True if fh is supported, False otherwise.

classmethod detect_id(fh: BinaryIO) → bytes | None

Return a filesystem set identifier.

Only used in filesystems that support multiple volumes (disks) to find all volumes belonging to a single filesystem.

Parameters:

fh – A file-like object, usually a disk or partition.

iter_subfs() → collections.abc.Iterator[Filesystem]

Yield possible sub-filesystems.

abstract get(path: str) → FilesystemEntry

Retrieve a FilesystemEntry from the filesystem.

Parameters:

path – The path which we want to retrieve.

Returns:

A FilesystemEntry for the path.

open(path: str) → BinaryIO

Open a filesystem entry.

Parameters:

path – The location on the filesystem to open.

Returns:

A file-like object. Resolves symlinks when possible.

iterdir(path: str) → collections.abc.Iterator[str]

Iterate over the contents of a directory, return them as strings.

Parameters:

path – The location on the filesystem to iterate over.

Returns:

An iterator of directory entries as path strings.

scandir(path: str) → collections.abc.Iterator[DirEntry]

Iterate over the contents of a directory, return them as FilesystemEntry’s.

Parameters:

path – The directory to scan.

Returns:

An iterator of directory entries as FilesystemEntry’s.

listdir(path: str) → list[str]

List the contents of a directory as strings.

Parameters:

path – The directory to get the listing from.

Returns:

A list of path strings.

listdir_ext(path: str) → list[FilesystemEntry]

List the contents of a directory as FilesystemEntry’s.

Parameters:

path – The directory to get the listing from.

Returns:

A list of FilesystemEntry’s.

walk(path: str, topdown: bool = True, onerror: collections.abc.Callable[[Exception], None] | None = None, followlinks: bool = False) → collections.abc.Iterator[tuple[str, list[str], list[str]]]

Recursively walk a directory pointed to by path, returning the string representation of both files and directories.

Parameters:

• path – The path to walk on the filesystem.

• topdown – True puts the path at the top, False puts the path at the bottom.

• onerror – A method to execute when an error occurs.

• followlinks – True if we want to follow any symbolic link.

Returns:

An iterator of directory entries as path strings.

walk_ext(path: str, topdown: bool = True, onerror: collections.abc.Callable[[Exception], None] | None = None, followlinks: bool = False) → collections.abc.Iterator[tuple[list[FilesystemEntry], list[DirEntry], list[DirEntry]]]

Recursively walk a directory pointed to by path, returning FilesystemEntry of files and directories.

Parameters:

• path – The path to walk on the filesystem.

• topdown – True puts the path at the top, False puts the path at the bottom.

• onerror – A method to execute when an error occurs.

• followlinks – True if we want to follow any symbolic link.

Returns:

An iterator of directory entries as FilesystemEntry’s.

recurse(path: str) → collections.abc.Iterator[FilesystemEntry]

Recursively walk a directory and yield contents as FilesystemEntry.

Does not follow symbolic links.

Parameters:

path – The path to recursively walk on the target filesystem.

Returns:

An iterator of FilesystemEntry.

glob(pattern: str) → collections.abc.Iterator[str]

Iterate over the directory part of pattern, returning entries matching pattern as strings.

Parameters:

pattern – The pattern to match.

Returns:

An iterator of path strings that match the pattern.

glob_ext(pattern: str) → collections.abc.Iterator[FilesystemEntry]

Iterate over the directory part of pattern, returning entries matching pattern as FilesysmteEntry’s.

Parameters:

pattern – The pattern to match.

Returns:

An iterator of FilesystemEntry’s that match the pattern.

exists(path: str) → bool

Determines whether path exists on a filesystem.

If the path is a symbolic link, it will attempt to resolve it to find the FilesystemEntry it points to.

Parameters:

path – a path on the filesystem.

Returns:

True if the given path exists, False otherwise.

lexists(path: str) → bool

Determines if a path exists on the filesystem without resolving links.

Parameters:

path – A path on the filesystem.

Returns:

True if the given path is a file, False otherwise.

is_file(path: str, follow_symlinks: bool = True) → bool

Determine if path is a file on the filesystem.

Parameters:

• path – The path on the filesystem.

• follow_symlinks – Whether to resolve the path if it is a symbolic link.

Returns:

True if the given path is a file or a symbolic link to a file, return False otherwise. If follow_symlinks is False, return True only if the given path is a file (without following symlinks).

is_dir(path: str, follow_symlinks: bool = True) → bool

Determine whether the given path is a directory on the filesystem.

Parameters:

• path – The path on the filesystem.

• follow_symlinks – Whether to resolve the path if it is a symbolic link.

Returns:

True if the given path is a directory or a symbolic link to a directory, return False otherwise. If follow_symlinks is False, return True only if the given path is a directory (without following symlinks).

is_symlink(path: str) → bool

Determine wether the given path is a symlink on the filesystem.

Parameters:

path – The path on the filesystem.

Returns:

True if the given path is a symbolic link, False otherwise.

readlink(path: str) → str

Read the link where the given path points to, return the resulting path as string.

If it is a symlink and returns the string that corresponds to that path. This means it follows the path a link points to, it tries to do it recursively.

Parameters:

path – The symbolic link to read.

Returns:

The path the link points to.

readlink_ext(path: str) → FilesystemEntry

Read the link where the given path points to, return the resulting path as FilesystemEntry.

If it is a symlink and returns the entry that corresponds to that path. This means it follows the path a link points to, it tries to do it recursively.

Parameters:

path – The symbolic link to read.

Returns:

The FilesystemEntry where the symbolic link points to.

stat(path: str, follow_symlinks: bool = True) → dissect.target.helpers.fsutil.stat_result

Determine the stat information of a path on the filesystem.

If path is a symlink and follow_symlinks is True, it gets resolved, attempting to stat the path where it points to.

Parameters:

• path – The filesystem path we want the stat information from.

• follow_symlinks – Whether to resolve the path if it is a symbolic link.

Returns:

The stat information of the given path.

lstat(path: str) → dissect.target.helpers.fsutil.stat_result

Determine the stat information of a path on the filesystem, without resolving symlinks.

When it detects a symlink, it will stat the information of the symlink, not the path it points to.

Parameters:

path – The filesystem path we want the stat information from.

Returns:

The stat information of the given path.

md5(path: str) → str

Calculate the MD5 digest of the contents of the file path points to.

Parameters:

path – The filesystem path to get the digest from.

Returns:

The MD5 digest of the contents of path.

sha1(path: str) → str

Calculate the SHA1 digest of the contents of the file path points to.

Parameters:

path – The filesystem path to get the digest from.

Returns:

The SHA1 digest of the contents of path.

sha256(path: str) → str

Calculate the SHA256 digest of the contents of the file path points to.

Parameters:

path – The filesystem path to get the digest from.

Returns:

The SHA256 digest of the contents of path.

hash(path: str, algos: list[str] | list[collections.abc.Callable] | None = None) → tuple[str]

Calculate the digest of the contents of path, using the algos algorithms.

Parameters:

• path – The filesystem path to get the digest from.

• algos – The types of hashes to calculate. If None it will use the common set of algorithms defined in dissect.target.helpers.hashutil.common() as [MD5, SHA1, SHA256].

Returns:

The digests of the contents of path.

class dissect.target.filesystem.FilesystemEntry(fs: Filesystem, path: str, entry: Any)

Base class for filesystem entries.

fs

path

name

entry

__repr__() → str

__str__() → str

abstract get(path: str) → Self

Retrieve a FilesystemEntry relative to this entry.

Parameters:

path – The path relative to this filesystem entry.

Returns:

A relative FilesystemEntry.

abstract open() → BinaryIO

Open this filesystem entry.

Returns:

A file-like object. Resolves symlinks when possible

iterdir() → collections.abc.Iterator[str]

Iterate over the contents of a directory, return them as strings.

Returns:

An iterator of directory entries as path strings.

abstract scandir() → collections.abc.Iterator[DirEntry]

Iterate over the contents of a directory, yields FilesystemEntry.

Returns:

An iterator of FilesystemEntry.

listdir() → list[str]

List the contents of a directory as strings.

Returns:

A list of path strings.

listdir_ext() → list[Self]

List the contents of a directory as a list of FilesystemEntry.

Returns:

A list of FilesystemEntry.

walk(topdown: bool = True, onerror: collections.abc.Callable[[Exception], None] | None = None, followlinks: bool = False) → collections.abc.Iterator[tuple[str, list[str], list[str]]]

Recursively walk a directory and yield its contents as strings split in a tuple of lists of files, directories and symlinks.

These contents include::

-files -directories -symboliclinks

Parameters:

• topdown – True puts this entry at the top of the list, False puts this entry at the bottom.

• onerror – A method to execute when an error occurs.

• followlinks – True if we want to follow any symbolic link.

Returns:

An iterator of directory entries as path strings.

walk_ext(topdown: bool = True, onerror: collections.abc.Callable[[Exception], None] | None = None, followlinks: bool = False) → collections.abc.Iterator[tuple[list[Self], list[Self], list[Self]]]

Recursively walk a directory and yield its contents as FilesystemEntry split in a tuple of lists of files, directories and symlinks.

Parameters:

• topdown – True puts this entry at the top of the list, False puts this entry at the bottom.

• onerror – A method to execute when an error occurs.

• followlinks – True if we want to follow any symbolic link

Returns:

An iterator of tuples FilesystemEntry.

recurse() → collections.abc.Iterator[FilesystemEntry]

Recursively walk a directory and yield its contents as DirEntry.

Does not follow symbolic links.

Returns:

An iterator of DirEntry.

glob(pattern: str) → collections.abc.Iterator[str]

Iterate over this directory part of patern, returning entries matching pattern as strings.

Parameters:

pattern – The pattern to match.

Returns:

An iterator of path strings that match the pattern.

glob_ext(pattern: str) → collections.abc.Iterator[Self]

Iterate over the directory part of pattern, returning entries matching pattern as FilesysmteEntry.

Parameters:

pattern – The pattern to glob for.

Returns:

An iterator of FilesystemEntry that match the pattern.

exists(path: str) → bool

Determines whether a path, relative to this entry, exists.

If the path is a symbolic link, it will attempt to resolve it to find the FilesystemEntry it points to.

Parameters:

path – The path relative to this entry.

Returns:

True if the path exists, False otherwise.

lexists(path: str) → bool

Determine wether a path relative to this enty, exists without resolving links.

Parameters:

path – The path relative to this entry.

Returns:

True if the path exists, False otherwise.

abstract is_file(follow_symlinks: bool = True) → bool

Determine if this entry is a file.

Parameters:

follow_symlinks – Whether to resolve the entry if it is a symbolic link.

Returns:

True if the entry is a file or a symbolic link to a file, return False otherwise. If follow_symlinks is False, return True only if the entry is a file (without following symlinks).

abstract is_dir(follow_symlinks: bool = True) → bool

Determine if this entry is a directory.

Parameters:

follow_symlinks – Whether to resolve the entry if it is a symbolic link.

Returns:

True if the entry is a directory or a symbolic link to a directory, return False otherwise. If follow_symlinks is False, return True only if the entry is a directory (without following symlinks).

abstract is_symlink() → bool

Determine whether this entry is a symlink.

Returns:

True if the entry is a symbolic link, False otherwise.

abstract readlink() → str

Read the link where this entry points to, return the resulting path as string.

If it is a symlink and returns the entry that corresponds to that path. This means it follows the path a link points to, it tries to do it recursively.

Returns:

The path the link points to.

readlink_ext() → Self

Read the link where this entry points to, return the resulting path as FilesystemEntry.

If it is a symlink and returns the string that corresponds to that path. This means it follows the path a link points to, it tries to do it recursively.

Returns:

The filesystem entry the link points to.

abstract stat(follow_symlinks: bool = True) → dissect.target.helpers.fsutil.stat_result

Determine the stat information of this entry.

If the entry is a symlink and follow_symlinks is True, it gets resolved, attempting to stat the path where it points to.

Parameters:

follow_symlinks – Whether to resolve the symbolic link if this entry is a symbolic link.

Returns:

The stat information of this entry.

abstract lstat() → dissect.target.helpers.fsutil.stat_result

Determine the stat information of this entry, without resolving the symlinks.

When it detects a symlink, it will stat the information of the symlink, not the path it points to.

Returns:

The stat information of this entry.

abstract attr() → Any

The attributes related to this entry, resolving any symlinks.

If the entry is a symbolic link, it will attempt to resolve it first. Resulting in the attr information of the entry it points to.

Returns:

The attributes of this entry.

abstract lattr() → Any

The attributes related to this current entry, without resolving links.

Returns:

The attributes of this entry.

md5() → str

Calculates the MD5 digest of this entry.

Returns:

The MD5 digest of this entry.

sha1() → str

Calculates the SHA1 digest of this entry.

Returns:

The SHA1 digest of this entry.

sha256() → str

Calculates the SHA256 digest of this entry.

Returns:

The SHA256 digest of this entry.

hash(algos: list[str] | list[collections.abc.Callable] | None = None) → tuple[str]

Calculate the digest of this entry, using the algos algorithms.

Parameters:

algos – The types of hashes to calculate. If None it will use the common set of algorithms defined in dissect.target.helpers.hashutil.common() as [MD5, SHA1, SHA256].

Returns:

The various digests of this entry.

class dissect.target.filesystem.DirEntry(fs: Filesystem, path: str, name: str, entry: Any)

Directory entry base class. Closely models os.DirEntry.

Filesystem implementations are encouraged to subclass this class to provide efficient implementations of the various methods.

Parameters:

• fs – The filesystem the entry belongs to.

• path – The path of the parent directory.

• name – The name of the entry.

• entry – The raw entry backing this directory entry.

fs

The filesystem the entry belongs to.

path

The full path of the entry.

name

The name of the entry.

entry

The raw entry backing this directory entry.

stat

__fspath__() → str

__repr__() → str

get() → FilesystemEntry

Retrieve the FilesystemEntry this directory entry points to.

Subclasses should override this method to provide an efficient implementation.

is_dir(*, follow_symlinks: bool = True) → bool

Return whether this entry is a directory or a symbolic link pointing to a directory.

Subclasses should override this method to provide an efficient implementation.

is_file(*, follow_symlinks: bool = True) → bool

Return whether this entry is a file or a symbolic link pointing to a file.

Subclasses should override this method to provide an efficient implementation.

is_symlink() → bool

Return whether this entry is a symbolic link.

Subclasses should override this method to provide an efficient implementation.

is_junction() → bool

Return whether this entry is a junction (only valid for NTFS).

inode() → int

Return the inode number of this entry.

class dissect.target.filesystem.VirtualDirEntry(fs: Filesystem, path: str, name: str, entry: Any)

Bases: DirEntry

Directory entry base class. Closely models os.DirEntry.

Filesystem implementations are encouraged to subclass this class to provide efficient implementations of the various methods.

Parameters:

• fs – The filesystem the entry belongs to.

• path – The path of the parent directory.

• name – The name of the entry.

• entry – The raw entry backing this directory entry.

fs: VirtualFilesystem

The filesystem the entry belongs to.

entry: FilesystemEntry

The raw entry backing this directory entry.

get() → FilesystemEntry

Retrieve the FilesystemEntry this directory entry points to.

Subclasses should override this method to provide an efficient implementation.

stat(*, follow_symlinks: bool = True) → dissect.target.helpers.fsutil.stat_result

class dissect.target.filesystem.VirtualDirectory(fs: VirtualFilesystem, path: str)

Bases: FilesystemEntry

Virtual directory implementation. Backed by a dict.

up = None

top: FilesystemEntry | None = None

entries: dict[str, FilesystemEntry]

__getitem__(item: str) → FilesystemEntry

__contains__(item: str) → bool

open() → BinaryIO

Open this filesystem entry.

Returns:

A file-like object. Resolves symlinks when possible

attr() → Any

The attributes related to this entry, resolving any symlinks.

If the entry is a symbolic link, it will attempt to resolve it first. Resulting in the attr information of the entry it points to.

Returns:

The attributes of this entry.

lattr() → Any

The attributes related to this current entry, without resolving links.

Returns:

The attributes of this entry.

add(name: str, entry: FilesystemEntry) → None

Add an entry to this VirtualDirectory.

get(path: str) → FilesystemEntry

Retrieve a FilesystemEntry relative to this entry.

Parameters:

path – The path relative to this filesystem entry.

Returns:

A relative FilesystemEntry.

scandir() → collections.abc.Iterator[DirEntry]

Iterate over the contents of a directory, yields FilesystemEntry.

Returns:

An iterator of FilesystemEntry.

stat(follow_symlinks: bool = True) → dissect.target.helpers.fsutil.stat_result

Determine the stat information of this entry.

If the entry is a symlink and follow_symlinks is True, it gets resolved, attempting to stat the path where it points to.

Parameters:

follow_symlinks – Whether to resolve the symbolic link if this entry is a symbolic link.

Returns:

The stat information of this entry.

lstat() → dissect.target.helpers.fsutil.stat_result

Determine the stat information of this entry, without resolving the symlinks.

When it detects a symlink, it will stat the information of the symlink, not the path it points to.

Returns:

The stat information of this entry.

is_dir(follow_symlinks: bool = True) → bool

Determine if this entry is a directory.

Parameters:

follow_symlinks – Whether to resolve the entry if it is a symbolic link.

Returns:

True if the entry is a directory or a symbolic link to a directory, return False otherwise. If follow_symlinks is False, return True only if the entry is a directory (without following symlinks).

is_file(follow_symlinks: bool = True) → bool

Determine if this entry is a file.

Parameters:

follow_symlinks – Whether to resolve the entry if it is a symbolic link.

Returns:

True if the entry is a file or a symbolic link to a file, return False otherwise. If follow_symlinks is False, return True only if the entry is a file (without following symlinks).

is_symlink() → bool

Determine whether this entry is a symlink.

Returns:

True if the entry is a symbolic link, False otherwise.

readlink() → str

Read the link where this entry points to, return the resulting path as string.

If it is a symlink and returns the entry that corresponds to that path. This means it follows the path a link points to, it tries to do it recursively.

Returns:

The path the link points to.

readlink_ext() → FilesystemEntry

Read the link where this entry points to, return the resulting path as FilesystemEntry.

If it is a symlink and returns the string that corresponds to that path. This means it follows the path a link points to, it tries to do it recursively.

Returns:

The filesystem entry the link points to.

class dissect.target.filesystem.VirtualFileHandle(fh: BinaryIO)

Bases: io.RawIOBase

Base class for raw binary I/O.

fh

readinto(b: bytearray) → int

seek(offset: int, whence: int = io.SEEK_SET) → int

Change stream position.

Change the stream position to the given byte offset. The offset is interpreted relative to the position indicated by whence. Values for whence are:

• 0 – start of stream (the default); offset should be zero or positive

• 1 – current stream position; offset may be negative

• 2 – end of stream; offset is usually negative

Return the new absolute position.

readable() → bool

Return whether object was opened for reading.

If False, read() will raise OSError.

seekable() → bool

Return whether object supports random access.

If False, seek(), tell() and truncate() will raise OSError. This method may need to do a test seek().

class dissect.target.filesystem.VirtualFile(fs: Filesystem, path: str, entry: Any)

Bases: FilesystemEntry

Virtual file backed by a file-like object.

attr() → Any

The attributes related to this entry, resolving any symlinks.

If the entry is a symbolic link, it will attempt to resolve it first. Resulting in the attr information of the entry it points to.

Returns:

The attributes of this entry.

lattr() → Any

The attributes related to this current entry, without resolving links.

Returns:

The attributes of this entry.

get(path: str) → FilesystemEntry

Retrieve a FilesystemEntry relative to this entry.

Parameters:

path – The path relative to this filesystem entry.

Returns:

A relative FilesystemEntry.

scandir() → collections.abc.Iterator[DirEntry]

Iterate over the contents of a directory, yields FilesystemEntry.

Returns:

An iterator of FilesystemEntry.

open() → BinaryIO

Open this filesystem entry.

Returns:

A file-like object. Resolves symlinks when possible

stat(follow_symlinks: bool = True) → dissect.target.helpers.fsutil.stat_result

Determine the stat information of this entry.

If the entry is a symlink and follow_symlinks is True, it gets resolved, attempting to stat the path where it points to.

Parameters:

follow_symlinks – Whether to resolve the symbolic link if this entry is a symbolic link.

Returns:

The stat information of this entry.

lstat() → dissect.target.helpers.fsutil.stat_result

Determine the stat information of this entry, without resolving the symlinks.

When it detects a symlink, it will stat the information of the symlink, not the path it points to.

Returns:

The stat information of this entry.

is_dir(follow_symlinks: bool = True) → bool

Determine if this entry is a directory.

Parameters:

follow_symlinks – Whether to resolve the entry if it is a symbolic link.

Returns:

True if the entry is a directory or a symbolic link to a directory, return False otherwise. If follow_symlinks is False, return True only if the entry is a directory (without following symlinks).

is_file(follow_symlinks: bool = True) → bool

Determine if this entry is a file.

Parameters:

follow_symlinks – Whether to resolve the entry if it is a symbolic link.

Returns:

True if the entry is a file or a symbolic link to a file, return False otherwise. If follow_symlinks is False, return True only if the entry is a file (without following symlinks).

is_symlink() → bool

Determine whether this entry is a symlink.

Returns:

True if the entry is a symbolic link, False otherwise.

readlink() → str

Read the link where this entry points to, return the resulting path as string.

If it is a symlink and returns the entry that corresponds to that path. This means it follows the path a link points to, it tries to do it recursively.

Returns:

The path the link points to.

readlink_ext() → FilesystemEntry

Read the link where this entry points to, return the resulting path as FilesystemEntry.

If it is a symlink and returns the string that corresponds to that path. This means it follows the path a link points to, it tries to do it recursively.

Returns:

The filesystem entry the link points to.

class dissect.target.filesystem.MappedFile(fs: Filesystem, path: str, entry: Any)

Bases: VirtualFile

Virtual file backed by a file on the host machine.

entry: str

open() → BinaryIO

Open this filesystem entry.

Returns:

A file-like object. Resolves symlinks when possible

stat(follow_symlinks: bool = True) → dissect.target.helpers.fsutil.stat_result

Determine the stat information of this entry.

If the entry is a symlink and follow_symlinks is True, it gets resolved, attempting to stat the path where it points to.

Parameters:

follow_symlinks – Whether to resolve the symbolic link if this entry is a symbolic link.

Returns:

The stat information of this entry.

lstat() → dissect.target.helpers.fsutil.stat_result

Determine the stat information of this entry, without resolving the symlinks.

When it detects a symlink, it will stat the information of the symlink, not the path it points to.

Returns:

The stat information of this entry.

attr() → dict[str, bytes]

The attributes related to this entry, resolving any symlinks.

If the entry is a symbolic link, it will attempt to resolve it first. Resulting in the attr information of the entry it points to.

Returns:

The attributes of this entry.

lattr() → dict[str, bytes]

The attributes related to this current entry, without resolving links.

Returns:

The attributes of this entry.

class dissect.target.filesystem.MappedCompressedFile(fs: Filesystem, path: str, entry: str, algo: str = 'gzip')

Bases: MappedFile

Virtual file backed by a compressed file on the host machine.

entry: str

open() → BinaryIO

Open this filesystem entry.

Returns:

A file-like object. Resolves symlinks when possible

class dissect.target.filesystem.VirtualSymlink(fs: Filesystem, path: str, target: str)

Bases: FilesystemEntry

Virtual symlink implementation.

target

attr() → Any

The attributes related to this entry, resolving any symlinks.

If the entry is a symbolic link, it will attempt to resolve it first. Resulting in the attr information of the entry it points to.

Returns:

The attributes of this entry.

lattr() → Any

The attributes related to this current entry, without resolving links.

Returns:

The attributes of this entry.

get(path: str) → FilesystemEntry

Retrieve a FilesystemEntry relative to this entry.

Parameters:

path – The path relative to this filesystem entry.

Returns:

A relative FilesystemEntry.

scandir() → collections.abc.Iterator[DirEntry]

Iterate over the contents of a directory, yields FilesystemEntry.

Returns:

An iterator of FilesystemEntry.

open() → BinaryIO

Open this filesystem entry.

Returns:

A file-like object. Resolves symlinks when possible

stat(follow_symlinks: bool = True) → dissect.target.helpers.fsutil.stat_result

Determine the stat information of this entry.

If the entry is a symlink and follow_symlinks is True, it gets resolved, attempting to stat the path where it points to.

Parameters:

follow_symlinks – Whether to resolve the symbolic link if this entry is a symbolic link.

Returns:

The stat information of this entry.

lstat() → dissect.target.helpers.fsutil.stat_result

Determine the stat information of this entry, without resolving the symlinks.

When it detects a symlink, it will stat the information of the symlink, not the path it points to.

Returns:

The stat information of this entry.

is_dir(follow_symlinks: bool = True) → bool

Determine if this entry is a directory.

Parameters:

follow_symlinks – Whether to resolve the entry if it is a symbolic link.

Returns:

True if the entry is a directory or a symbolic link to a directory, return False otherwise. If follow_symlinks is False, return True only if the entry is a directory (without following symlinks).

is_file(follow_symlinks: bool = True) → bool

Determine if this entry is a file.

Parameters:

follow_symlinks – Whether to resolve the entry if it is a symbolic link.

Returns:

True if the entry is a file or a symbolic link to a file, return False otherwise. If follow_symlinks is False, return True only if the entry is a file (without following symlinks).

is_symlink() → bool

Determine whether this entry is a symlink.

Returns:

True if the entry is a symbolic link, False otherwise.

readlink() → str

Read the link where this entry points to, return the resulting path as string.

If it is a symlink and returns the entry that corresponds to that path. This means it follows the path a link points to, it tries to do it recursively.

Returns:

The path the link points to.

class dissect.target.filesystem.VirtualFilesystem(**kwargs)

Bases: Filesystem

Base class for filesystems.

__type__ = 'virtual'

A short string identifying the type of filesystem.

root

static detect(fh: BinaryIO) → bool

Detect whether the fh file-handle is supported by this Filesystem implementation.

The position of fh will be restored before returning.

Parameters:

fh – A file-like object, usually a disk or partition.

Returns:

True if fh is supported, False otherwise.

get(path: str, relentry: FilesystemEntry | None = None) → FilesystemEntry

Retrieve a FilesystemEntry from the filesystem.

Parameters:

path – The path which we want to retrieve.

Returns:

A FilesystemEntry for the path.

makedirs(path: str) → VirtualDirectory

Create virtual directories into the VFS from the given path.

map_fs(vfspath: str, fs: Filesystem, base: str = '/') → None

Mount a dissect filesystem to a directory in the VFS.

mount

map_dir(vfspath: str, realpath: pathlib.Path | str) → None

Recursively map a directory from the host machine into the VFS.

map_file(vfspath: str, realpath: str | pathlib.Path, compression: str | None = None) → None

Map a file from the host machine into the VFS.

map_file_fh(vfspath: str, fh: BinaryIO) → None

Map a file handle into the VFS.

map_file_entry(vfspath: str, entry: FilesystemEntry) → None

Map a FilesystemEntry into the VFS.

Any missing subdirectories up to, but not including, the last part of vfspath will be created.

map_dir_from_tar(vfspath: str, tar_file: str | pathlib.Path, map_single_file: bool = False) → None

Map files in a tar onto the VFS.

Parameters:

• vfspath – Destination path in the virtual filesystem.

• tar_file – Source path of the tar file to map.

• map_single_file – Only mount a single file found inside the tar at the specified path.

map_file_from_tar(vfspath: str, tar_file: str | pathlib.Path) → None

Map a single file in a tar archive to the given path in the VFS.

The provided tar archive should contain one file.

Parameters:

• vfspath – Destination path in the virtual filesystem.

• tar_file – Source path of the tar file to map.

link(src: str, dst: str) → None

Hard link a FilesystemEntry to another location.

Parameters:

• src – The path to the target of the link.

• dst – The path to the link.

symlink(src: str, dst: str) → None

Create a symlink to another location.

Parameters:

• src – The path to the target of the symlink.

• dst – The path to the symlink.

class dissect.target.filesystem.LayerFilesystem(**kwargs)

Bases: Filesystem

Base class for filesystems.

__type__ = 'layer'

A short string identifying the type of filesystem.

layers: list[Filesystem] = []

mounts

root

__getattr__(attr: str) → Any

Provide “magic” access to filesystem specific attributes from any of the layers.

For example, on a LayerFilesystem fs, you can do fs.ntfs to access the internal NTFS object if it has an NTFS layer.

static detect(fh: BinaryIO) → bool

Detect whether the fh file-handle is supported by this Filesystem implementation.

The position of fh will be restored before returning.

Parameters:

fh – A file-like object, usually a disk or partition.

Returns:

True if fh is supported, False otherwise.

mount(path: str, fs: Filesystem, ignore_existing: bool = True) → None

Mount a filesystem at a given path.

If there’s an overlap with an existing mount, creates a new layer.

Parameters:

• path – The path to mount the filesystem at.

• fs – The filesystem to mount.

• ignore_existing – Whether to ignore existing mounts and create a new layer. Defaults to True.

link(dst: str, src: str) → None

Hard link a FilesystemEntry to another location.

symlink(dst: str, src: str) → None

Create a symlink to another location.

append_layer(**kwargs) → VirtualFilesystem

Append a new layer.

add_layer

prepend_layer(**kwargs) → VirtualFilesystem

Prepend a new layer.

append_fs_layer(fs: Filesystem) → None

Append a filesystem as a layer.

Parameters:

fs – The filesystem to append.

prepend_fs_layer(fs: Filesystem) → None

Prepend a filesystem as a layer.

Parameters:

fs – The filesystem to prepend.

remove_fs_layer(fs: Filesystem) → None

Remove a filesystem layer.

Parameters:

fs – The filesystem to remove.

remove_layer(idx: int) → None

Remove a layer by index.

Parameters:

idx – The index of the layer to remove.

property case_sensitive: bool

Whether the filesystem is case sensitive.

property alt_separator: str

The alternative separator of the filesystem.

get(path: str, relentry: LayerFilesystemEntry | None = None) → LayerFilesystemEntry

Get a FilesystemEntry from the filesystem.

class dissect.target.filesystem.EntryList(value: FilesystemEntry | list[FilesystemEntry])

Bases: list

Wrapper list for filesystem entries.

Exposes a __getattr__ on a list of items. Useful to access internal objects from filesystem implementations. For example, access the underlying NTFS object from a list of virtual and NTFS entries.

__getattr__(attr: str) → Any

class dissect.target.filesystem.LayerDirEntry(fs: Filesystem, path: str, name: str, entry: Any)

Bases: DirEntry

Directory entry base class. Closely models os.DirEntry.

Filesystem implementations are encouraged to subclass this class to provide efficient implementations of the various methods.

Parameters:

• fs – The filesystem the entry belongs to.

• path – The path of the parent directory.

• name – The name of the entry.

• entry – The raw entry backing this directory entry.

fs: LayerFilesystem

The filesystem the entry belongs to.

entry: list[DirEntry]

The raw entry backing this directory entry.

get() → LayerFilesystemEntry

Retrieve the FilesystemEntry this directory entry points to.

Subclasses should override this method to provide an efficient implementation.

class dissect.target.filesystem.LayerFilesystemEntry(fs: Filesystem, path: str, entry: FilesystemEntry)

Bases: FilesystemEntry

Base class for filesystem entries.

entries: EntryList

get(path: str) → FilesystemEntry

Retrieve a FilesystemEntry relative to this entry.

Parameters:

path – The path relative to this filesystem entry.

Returns:

A relative FilesystemEntry.

open() → BinaryIO

Open this filesystem entry.

Returns:

A file-like object. Resolves symlinks when possible

scandir() → collections.abc.Iterator[LayerDirEntry]

Iterate over the contents of a directory, yields FilesystemEntry.

Returns:

An iterator of FilesystemEntry.

is_file(follow_symlinks: bool = True) → bool

Determine if this entry is a file.

Parameters:

follow_symlinks – Whether to resolve the entry if it is a symbolic link.

Returns:

True if the entry is a file or a symbolic link to a file, return False otherwise. If follow_symlinks is False, return True only if the entry is a file (without following symlinks).

is_dir(follow_symlinks: bool = True) → bool

Determine if this entry is a directory.

Parameters:

follow_symlinks – Whether to resolve the entry if it is a symbolic link.

Returns:

True if the entry is a directory or a symbolic link to a directory, return False otherwise. If follow_symlinks is False, return True only if the entry is a directory (without following symlinks).

is_symlink() → bool

Determine whether this entry is a symlink.

Returns:

True if the entry is a symbolic link, False otherwise.

readlink() → str

Read the link where this entry points to, return the resulting path as string.

If it is a symlink and returns the entry that corresponds to that path. This means it follows the path a link points to, it tries to do it recursively.

Returns:

The path the link points to.

stat(follow_symlinks: bool = True) → dissect.target.helpers.fsutil.stat_result

Determine the stat information of this entry.

If the entry is a symlink and follow_symlinks is True, it gets resolved, attempting to stat the path where it points to.

Parameters:

follow_symlinks – Whether to resolve the symbolic link if this entry is a symbolic link.

Returns:

The stat information of this entry.

lstat() → dissect.target.helpers.fsutil.stat_result

Determine the stat information of this entry, without resolving the symlinks.

When it detects a symlink, it will stat the information of the symlink, not the path it points to.

Returns:

The stat information of this entry.

attr() → Any

The attributes related to this entry, resolving any symlinks.

If the entry is a symbolic link, it will attempt to resolve it first. Resulting in the attr information of the entry it points to.

Returns:

The attributes of this entry.

lattr() → Any

The attributes related to this current entry, without resolving links.

Returns:

The attributes of this entry.

class dissect.target.filesystem.RootFilesystem(target: dissect.target.target.Target)

Bases: LayerFilesystem

Base class for filesystems.

__type__ = 'root'

A short string identifying the type of filesystem.

target

static detect(fh: BinaryIO) → bool

Detect whether the fh file-handle is supported by this Filesystem implementation.

The position of fh will be restored before returning.

Parameters:

fh – A file-like object, usually a disk or partition.

Returns:

True if fh is supported, False otherwise.

get(path: str, relentry: LayerFilesystemEntry | None = None) → RootFilesystemEntry

Get a FilesystemEntry from the filesystem.

class dissect.target.filesystem.RootDirEntry(fs: Filesystem, path: str, name: str, entry: Any)

Bases: LayerDirEntry

Directory entry base class. Closely models os.DirEntry.

Filesystem implementations are encouraged to subclass this class to provide efficient implementations of the various methods.

Parameters:

• fs – The filesystem the entry belongs to.

• path – The path of the parent directory.

• name – The name of the entry.

• entry – The raw entry backing this directory entry.

fs: RootFilesystem

The filesystem the entry belongs to.

get() → RootFilesystemEntry

Retrieve the FilesystemEntry this directory entry points to.

Subclasses should override this method to provide an efficient implementation.

class dissect.target.filesystem.RootFilesystemEntry(fs: Filesystem, path: str, entry: FilesystemEntry)

Bases: LayerFilesystemEntry

Base class for filesystem entries.

fs: RootFilesystem

get(path: str) → RootFilesystemEntry

Retrieve a FilesystemEntry relative to this entry.

Parameters:

path – The path relative to this filesystem entry.

Returns:

A relative FilesystemEntry.

open() → BinaryIO

Open this filesystem entry.

Returns:

A file-like object. Resolves symlinks when possible

scandir() → collections.abc.Iterator[DirEntry]

Iterate over the contents of a directory, yields FilesystemEntry.

Returns:

An iterator of FilesystemEntry.

is_file(follow_symlinks: bool = True) → bool

Determine if this entry is a file.

Parameters:

follow_symlinks – Whether to resolve the entry if it is a symbolic link.

Returns:

True if the entry is a file or a symbolic link to a file, return False otherwise. If follow_symlinks is False, return True only if the entry is a file (without following symlinks).

is_dir(follow_symlinks: bool = True) → bool

Determine if this entry is a directory.

Parameters:

follow_symlinks – Whether to resolve the entry if it is a symbolic link.

Returns:

True if the entry is a directory or a symbolic link to a directory, return False otherwise. If follow_symlinks is False, return True only if the entry is a directory (without following symlinks).

is_symlink() → bool

Determine whether this entry is a symlink.

Returns:

True if the entry is a symbolic link, False otherwise.

readlink() → str

Read the link where this entry points to, return the resulting path as string.

If it is a symlink and returns the entry that corresponds to that path. This means it follows the path a link points to, it tries to do it recursively.

Returns:

The path the link points to.

stat(follow_symlinks: bool = True) → dissect.target.helpers.fsutil.stat_result

Determine the stat information of this entry.

If the entry is a symlink and follow_symlinks is True, it gets resolved, attempting to stat the path where it points to.

Parameters:

follow_symlinks – Whether to resolve the symbolic link if this entry is a symbolic link.

Returns:

The stat information of this entry.

lstat() → dissect.target.helpers.fsutil.stat_result

Determine the stat information of this entry, without resolving the symlinks.

When it detects a symlink, it will stat the information of the symlink, not the path it points to.

Returns:

The stat information of this entry.

attr() → Any

The attributes related to this entry, resolving any symlinks.

If the entry is a symbolic link, it will attempt to resolve it first. Resulting in the attr information of the entry it points to.

Returns:

The attributes of this entry.

lattr() → Any

The attributes related to this current entry, without resolving links.

Returns:

The attributes of this entry.

dissect.target.filesystem.register(module: str, class_name: str, internal: bool = True) → None

Register a filesystem implementation to use when opening a filesystem.

This function registers a filesystem using module relative to the MODULE_PATH. It lazily imports the module, and retrieves the specific class from it.

Parameters:

• module – The module where to find the filesystem.

• class_name – The class to load.

• internal – Whether it is an internal module or not.

dissect.target.filesystem.is_multi_volume_filesystem(fh: BinaryIO) → bool

dissect.target.filesystem.open(fh: BinaryIO, *args, **kwargs) → Filesystem

dissect.target.filesystem.open_multi_volume(fhs: list[BinaryIO], *args, **kwargs) → collections.abc.Iterator[Filesystem]