:py:mod:`dissect.target.filesystem` =================================== .. py:module:: dissect.target.filesystem Module Contents --------------- Classes ~~~~~~~ .. autoapisummary:: dissect.target.filesystem.Filesystem dissect.target.filesystem.FilesystemEntry dissect.target.filesystem.VirtualDirectory dissect.target.filesystem.VirtualFileHandle dissect.target.filesystem.VirtualFile dissect.target.filesystem.MappedFile dissect.target.filesystem.MappedCompressedFile dissect.target.filesystem.VirtualSymlink dissect.target.filesystem.VirtualFilesystem dissect.target.filesystem.LayerFilesystem dissect.target.filesystem.EntryList dissect.target.filesystem.LayerFilesystemEntry dissect.target.filesystem.RootFilesystem dissect.target.filesystem.RootFilesystemEntry Functions ~~~~~~~~~ .. autoapisummary:: :nosignatures: dissect.target.filesystem.register dissect.target.filesystem.is_multi_volume_filesystem dissect.target.filesystem.open dissect.target.filesystem.open_multi_volume Attributes ~~~~~~~~~~ .. autoapisummary:: dissect.target.filesystem.TarFilesystem dissect.target.filesystem.FILESYSTEMS dissect.target.filesystem.MODULE_PATH dissect.target.filesystem.log .. py:data:: TarFilesystem .. py:data:: FILESYSTEMS :type: list[Type[Filesystem]] :value: [] .. py:data:: MODULE_PATH :value: 'dissect.target.filesystems' .. py:data:: log .. py:class:: Filesystem(volume: Optional[BinaryIO | list[BinaryIO]] = None, alt_separator: str = '', case_sensitive: bool = True) Base class for filesystems. .. py:property:: __fstype__ :type: str :classmethod: .. py:attribute:: __type__ :type: str A short string identifying the type of filesystem. .. py:attribute:: __multi_volume__ :type: bool :value: False Whether this filesystem supports multiple volumes (disks). .. py:method:: __repr__() -> str Return repr(self). .. py:method:: path(*args) -> dissect.target.helpers.fsutil.TargetPath Instantiate a new path-like object on this filesystem. .. py:method:: detect(fh: BinaryIO) -> bool :classmethod: Detect whether the ``fh`` file-handle is supported by this ``Filesystem`` implementation. The position of ``fh`` will be restored before returning. :param fh: A file-like object, usually a disk or partition. :returns: ``True`` if ``fh`` is supported, ``False`` otherwise. .. py:method:: detect_id(fh: BinaryIO) -> Optional[bytes] :classmethod: Return a filesystem set identifier. Only used in filesystems that support multiple volumes (disks) to find all volumes belonging to a single filesystem. :param fh: A file-like object, usually a disk or partition. .. py:method:: iter_subfs() -> Iterator[Filesystem] Yield possible sub-filesystems. .. py:method:: get(path: str) -> FilesystemEntry :abstractmethod: Retrieve a :class:`FilesystemEntry` from the filesystem. :param path: The path which we want to retrieve. :returns: A :class:`FilesystemEntry` for the path. .. py:method:: open(path: str) -> BinaryIO Open a filesystem entry. :param path: The location on the filesystem to open. :returns: A file-like object. Resolves symlinks when possible. .. py:method:: iterdir(path: str) -> Iterator[str] Iterate over the contents of a directory, return them as strings. :param path: The location on the filesystem to iterate over. :returns: An iterator of directory entries as path strings. .. py:method:: scandir(path: str) -> Iterator[FilesystemEntry] Iterate over the contents of a directory, return them as FilesystemEntry's. :param path: The directory to scan. :returns: An iterator of directory entries as FilesystemEntry's. .. py:method:: listdir(path: str) -> list[str] List the contents of a directory as strings. :param path: The directory to get the listing from. :returns: A list of path strings. .. py:method:: listdir_ext(path: str) -> list[FilesystemEntry] List the contents of a directory as FilesystemEntry's. :param path: The directory to get the listing from. :returns: A list of FilesystemEntry's. .. py:method:: walk(path: str, topdown: bool = True, onerror: Optional[Callable] = None, followlinks: bool = False) -> Iterator[str] Walk a directory pointed to by ``path``, returning the string representation of both files and directories. It walks across all the files inside ``path`` recursively. :param path: The path to walk on the filesystem. :param topdown: ``True`` puts the ``path`` at the top, ``False`` puts the ``path`` at the bottom. :param onerror: A method to execute when an error occurs. :param followlinks: ``True`` if we want to follow any symbolic link. :returns: An iterator of directory entries as path strings. .. py:method:: walk_ext(path: str, topdown: bool = True, onerror: Optional[Callable] = None, followlinks: bool = False) -> Iterator[FilesystemEntry] Walk a directory pointed to by ``path``, returning FilesystemEntry's of both files and directories. It walks across all the files inside ``path`` recursively. :param path: The path to walk on the filesystem. :param topdown: ``True`` puts the ``path`` at the top, ``False`` puts the ``path`` at the bottom. :param onerror: A method to execute when an error occurs. :param followlinks: ``True`` if we want to follow any symbolic link. :returns: An iterator of directory entries as FilesystemEntry's. .. py:method:: glob(pattern: str) -> Iterator[str] Iterate over the directory part of ``pattern``, returning entries matching ``pattern`` as strings. :param pattern: The pattern to match. :returns: An iterator of path strings that match the pattern. .. py:method:: glob_ext(pattern: str) -> Iterator[FilesystemEntry] Iterate over the directory part of ``pattern``, returning entries matching ``pattern`` as FilesysmteEntry's. :param pattern: The pattern to match. :returns: An iterator of FilesystemEntry's that match the pattern. .. py:method:: 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. :param path: a path on the filesystem. :returns: ``True`` if the given path exists, ``False`` otherwise. .. py:method:: lexists(path: str) -> bool Determines if a ``path`` exists on the filesystem without resolving links. :param path: A path on the filesystem. :returns: ``True`` if the given path is a file, ``False`` otherwise. .. py:method:: is_file(path: str, follow_symlinks: bool = True) -> bool Determine if ``path`` is a file on the filesystem. :param path: The path on the filesystem. :param 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). .. py:method:: is_dir(path: str, follow_symlinks: bool = True) -> bool Determine whether the given ``path`` is a directory on the filesystem. :param path: The path on the filesystem. :param 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). .. py:method:: is_symlink(path: str) -> bool Determine wether the given ``path`` is a symlink on the filesystem. :param path: The path on the filesystem. :returns: ``True`` if the given path is a symbolic link, ``False`` otherwise. .. py:method:: 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. :param path: The symbolic link to read. :returns: The path the link points to. .. py:method:: 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. :param path: The symbolic link to read. :returns: The ``FilesystemEntry`` where the symbolic link points to. .. py:method:: 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. :param path: The filesystem path we want the stat information from. :param follow_symlinks: Whether to resolve the path if it is a symbolic link. :returns: The stat information of the given path. .. py:method:: 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. :param path: The filesystem path we want the stat information from. :returns: The stat information of the given path. .. py:method:: md5(path: str) -> str Calculate the MD5 digest of the contents of the file ``path`` points to. :param path: The filesystem path to get the digest from. :returns: The MD5 digest of the contents of ``path``. .. py:method:: sha1(path: str) -> str Calculate the SHA1 digest of the contents of the file ``path`` points to. :param path: The filesystem path to get the digest from. :returns: The SHA1 digest of the contents of ``path``. .. py:method:: sha256(path: str) -> str Calculate the SHA256 digest of the contents of the file ``path`` points to. :param path: The filesystem path to get the digest from. :returns: The SHA256 digest of the contents of ``path``. .. py:method:: hash(path: str, algos: Optional[list[str] | list[Callable]] = None) -> tuple[str] Calculate the digest of the contents of ``path``, using the ``algos`` algorithms. :param path: The filesystem path to get the digest from. :param algos: The types of hashes to calculate. If ``None`` it will use the common set of algorithms defined in :py:func:`dissect.target.helpers.hashutil.common` as ``[MD5, SHA1, SHA256]``. :returns: The digests of the contents of ``path``. .. py:class:: FilesystemEntry(fs: Filesystem, path: str, entry: Any) Base class for filesystem entries. .. py:method:: __repr__() -> str Return repr(self). .. py:method:: __str__() -> str Return str(self). .. py:method:: get(path: str) -> FilesystemEntry :abstractmethod: Retrieve a :class:`FilesystemEntry` relative to this entry. :param path: The path relative to this filesystem entry. :returns: A relative :class:`FilesystemEntry`. .. py:method:: open() -> BinaryIO :abstractmethod: Open this filesystem entry. :returns: A file-like object. Resolves symlinks when possible .. py:method:: iterdir() -> Iterator[str] :abstractmethod: Iterate over the contents of a directory, return them as strings. :returns: An iterator of directory entries as path strings. .. py:method:: scandir() -> Iterator[FilesystemEntry] :abstractmethod: Iterate over the contents of a directory, yields :class:`FilesystemEntry`. :returns: An iterator of :class:`FilesystemEntry`. .. py:method:: listdir() -> list[str] List the contents of a directory as strings. :returns: A list of path strings. .. py:method:: listdir_ext() -> list[FilesystemEntry] List the contents of a directory as a list of :class:`FilesystemEntry`. :returns: A list of :class:`FilesystemEntry`. .. py:method:: walk(topdown: bool = True, onerror: Optional[Callable] = None, followlinks: bool = False) -> Iterator[str] Walk a directory and list its contents as strings. It walks across all the files inside the entry recursively. These contents include:: - files - directories - symboliclinks :param topdown: ``True`` puts this entry at the top of the list, ``False`` puts this entry at the bottom. :param onerror: A method to execute when an error occurs. :param followlinks: ``True`` if we want to follow any symbolic link. :returns: An iterator of directory entries as path strings. .. py:method:: walk_ext(topdown: bool = True, onerror: Optional[Callable] = None, followlinks: bool = False) -> Iterator[FilesystemEntry] Walk a directory and show its contents as :class:`FilesystemEntry`. It walks across all the files inside the entry recursively. These contents include:: - files - directories - symboliclinks :param topdown: ``True`` puts this entry at the top of the list, ``False`` puts this entry at the bottom. :param onerror: A method to execute when an error occurs. :param followlinks: ``True`` if we want to follow any symbolic link :returns: An iterator of :class:`FilesystemEntry`. .. py:method:: glob(pattern: str) -> Iterator[str] Iterate over this directory part of ``patern``, returning entries matching ``pattern`` as strings. :param pattern: The pattern to match. :returns: An iterator of path strings that match the pattern. .. py:method:: glob_ext(pattern: str) -> Iterator[FilesystemEntry] Iterate over the directory part of ``pattern``, returning entries matching ``pattern`` as :class:`FilesysmteEntry`. :param pattern: The pattern to glob for. :returns: An iterator of :class:`FilesystemEntry` that match the pattern. .. py:method:: 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 :class:`FilesystemEntry` it points to. :param path: The path relative to this entry. :returns: ``True`` if the path exists, ``False`` otherwise. .. py:method:: lexists(path: str) -> bool Determine wether a ``path`` relative to this enty, exists without resolving links. :param path: The path relative to this entry. :returns: ``True`` if the path exists, ``False`` otherwise. .. py:method:: is_file(follow_symlinks: bool = True) -> bool :abstractmethod: Determine if this entry is a file. :param 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). .. py:method:: is_dir(follow_symlinks: bool = True) -> bool :abstractmethod: Determine if this entry is a directory. :param 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). .. py:method:: is_symlink() -> bool :abstractmethod: Determine whether this entry is a symlink. :returns: ``True`` if the entry is a symbolic link, ``False`` otherwise. .. py:method:: readlink() -> str :abstractmethod: 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. .. py:method:: readlink_ext() -> FilesystemEntry Read the link where this entry points to, return the resulting path as :class:`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. .. py:method:: stat(follow_symlinks: bool = True) -> dissect.target.helpers.fsutil.stat_result :abstractmethod: 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. :param follow_symlinks: Whether to resolve the symbolic link if this entry is a symbolic link. :returns: The stat information of this entry. .. py:method:: lstat() -> dissect.target.helpers.fsutil.stat_result :abstractmethod: 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. .. py:method:: attr() -> Any :abstractmethod: 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. .. py:method:: lattr() -> Any :abstractmethod: The attributes related to this current entry, **without** resolving links. :returns: The attributes of this entry. .. py:method:: md5() -> str Calculates the MD5 digest of this entry. :returns: The MD5 digest of this entry. .. py:method:: sha1() -> str Calculates the SHA1 digest of this entry. :returns: The SHA1 digest of this entry. .. py:method:: sha256() -> str Calculates the SHA256 digest of this entry. :returns: The SHA256 digest of this entry. .. py:method:: hash(algos: Optional[list[str] | list[Callable]] = None) -> tuple[str] Calculate the digest of this entry, using the ``algos`` algorithms. :param algos: The types of hashes to calculate. If ``None`` it will use the common set of algorithms defined in :py:func:`dissect.target.helpers.hashutil.common` as ``[MD5, SHA1, SHA256]``. :returns: The various digests of this entry. .. py:class:: VirtualDirectory(fs, path) Bases: :py:obj:`FilesystemEntry` Virtual directory implementation. Backed by a dict. .. py:method:: __getitem__(item) -> FilesystemEntry .. py:method:: __contains__(item) -> bool .. py:method:: open() -> BinaryIO Open this filesystem entry. :returns: A file-like object. Resolves symlinks when possible .. py:method:: 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. .. py:method:: lattr() -> Any The attributes related to this current entry, **without** resolving links. :returns: The attributes of this entry. .. py:method:: add(name: str, entry: FilesystemEntry) -> None Add an entry to this :class:`VirtualDirectory`. .. py:method:: get(path: str) -> FilesystemEntry Retrieve a :class:`FilesystemEntry` relative to this entry. :param path: The path relative to this filesystem entry. :returns: A relative :class:`FilesystemEntry`. .. py:method:: iterdir() -> Iterator[str] Iterate over the contents of a directory, return them as strings. :returns: An iterator of directory entries as path strings. .. py:method:: scandir() -> Iterator[FilesystemEntry] Iterate over the contents of a directory, yields :class:`FilesystemEntry`. :returns: An iterator of :class:`FilesystemEntry`. .. py:method:: 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. :param follow_symlinks: Whether to resolve the symbolic link if this entry is a symbolic link. :returns: The stat information of this entry. .. py:method:: 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. .. py:method:: is_dir(follow_symlinks: bool = True) -> bool Determine if this entry is a directory. :param 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). .. py:method:: is_file(follow_symlinks: bool = True) -> bool Determine if this entry is a file. :param 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). .. py:method:: is_symlink() -> bool Determine whether this entry is a symlink. :returns: ``True`` if the entry is a symbolic link, ``False`` otherwise. .. py:method:: 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. .. py:method:: readlink_ext() -> FilesystemEntry Read the link where this entry points to, return the resulting path as :class:`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. .. py:class:: VirtualFileHandle(fh: BinaryIO) Bases: :py:obj:`io.RawIOBase` Base class for raw binary I/O. .. py:method:: readinto(b: bytearray) -> int .. py:method:: 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. .. py:method:: readable() -> bool Return whether object was opened for reading. If False, read() will raise OSError. .. py:method:: 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(). .. py:class:: VirtualFile(fs: Filesystem, path: str, entry: Any) Bases: :py:obj:`FilesystemEntry` Virtual file backed by a file-like object. .. py:method:: 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. .. py:method:: lattr() -> Any The attributes related to this current entry, **without** resolving links. :returns: The attributes of this entry. .. py:method:: get(path: str) -> FilesystemEntry Retrieve a :class:`FilesystemEntry` relative to this entry. :param path: The path relative to this filesystem entry. :returns: A relative :class:`FilesystemEntry`. .. py:method:: iterdir() -> Iterator[str] Iterate over the contents of a directory, return them as strings. :returns: An iterator of directory entries as path strings. .. py:method:: scandir() -> Iterator[FilesystemEntry] Iterate over the contents of a directory, yields :class:`FilesystemEntry`. :returns: An iterator of :class:`FilesystemEntry`. .. py:method:: open() -> BinaryIO Open this filesystem entry. :returns: A file-like object. Resolves symlinks when possible .. py:method:: 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. :param follow_symlinks: Whether to resolve the symbolic link if this entry is a symbolic link. :returns: The stat information of this entry. .. py:method:: 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. .. py:method:: is_dir(follow_symlinks: bool = True) -> bool Determine if this entry is a directory. :param 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). .. py:method:: is_file(follow_symlinks: bool = True) -> bool Determine if this entry is a file. :param 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). .. py:method:: is_symlink() -> bool Determine whether this entry is a symlink. :returns: ``True`` if the entry is a symbolic link, ``False`` otherwise. .. py:method:: 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. .. py:method:: readlink_ext() -> FilesystemEntry Read the link where this entry points to, return the resulting path as :class:`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. .. py:class:: MappedFile(fs: Filesystem, path: str, entry: Any) Bases: :py:obj:`VirtualFile` Virtual file backed by a file on the host machine. .. py:method:: open() -> BinaryIO Open this filesystem entry. :returns: A file-like object. Resolves symlinks when possible .. py:method:: 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. :param follow_symlinks: Whether to resolve the symbolic link if this entry is a symbolic link. :returns: The stat information of this entry. .. py:method:: 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. .. py:method:: 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. .. py:method:: lattr() -> dict[str, bytes] The attributes related to this current entry, **without** resolving links. :returns: The attributes of this entry. .. py:class:: MappedCompressedFile(fs: Filesystem, path: str, entry: Any, algo: str = 'gzip') Bases: :py:obj:`MappedFile` Virtual file backed by a compressed file on the host machine. .. py:method:: open() -> BinaryIO Open this filesystem entry. :returns: A file-like object. Resolves symlinks when possible .. py:class:: VirtualSymlink(fs: Filesystem, path: str, target: str) Bases: :py:obj:`FilesystemEntry` Virtual symlink implementation. .. py:method:: 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. .. py:method:: lattr() -> Any The attributes related to this current entry, **without** resolving links. :returns: The attributes of this entry. .. py:method:: get(path) -> FilesystemEntry Retrieve a :class:`FilesystemEntry` relative to this entry. :param path: The path relative to this filesystem entry. :returns: A relative :class:`FilesystemEntry`. .. py:method:: iterdir() -> Iterator[str] Iterate over the contents of a directory, return them as strings. :returns: An iterator of directory entries as path strings. .. py:method:: scandir() -> Iterator[FilesystemEntry] Iterate over the contents of a directory, yields :class:`FilesystemEntry`. :returns: An iterator of :class:`FilesystemEntry`. .. py:method:: open() -> BinaryIO Open this filesystem entry. :returns: A file-like object. Resolves symlinks when possible .. py:method:: 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. :param follow_symlinks: Whether to resolve the symbolic link if this entry is a symbolic link. :returns: The stat information of this entry. .. py:method:: 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. .. py:method:: is_dir(follow_symlinks: bool = True) -> bool Determine if this entry is a directory. :param 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). .. py:method:: is_file(follow_symlinks: bool = True) -> bool Determine if this entry is a file. :param 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). .. py:method:: is_symlink() -> bool Determine whether this entry is a symlink. :returns: ``True`` if the entry is a symbolic link, ``False`` otherwise. .. py:method:: 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. .. py:class:: VirtualFilesystem(**kwargs) Bases: :py:obj:`Filesystem` Base class for filesystems. .. py:attribute:: __type__ :value: 'virtual' .. py:attribute:: mount .. py:method:: detect(fh: BinaryIO) -> bool :staticmethod: Detect whether the ``fh`` file-handle is supported by this ``Filesystem`` implementation. The position of ``fh`` will be restored before returning. :param fh: A file-like object, usually a disk or partition. :returns: ``True`` if ``fh`` is supported, ``False`` otherwise. .. py:method:: get(path: str, relentry: Optional[FilesystemEntry] = None) -> FilesystemEntry Retrieve a :class:`FilesystemEntry` from the filesystem. :param path: The path which we want to retrieve. :returns: A :class:`FilesystemEntry` for the path. .. py:method:: makedirs(path: str) -> VirtualDirectory Create virtual directories into the VFS from the given path. .. py:method:: map_fs(vfspath: str, fs: Filesystem) -> None Mount a dissect filesystem to a directory in the VFS .. py:method:: map_dir(vfspath: str, realpath: str) -> None Recursively map a directory from the host machine into the VFS. .. py:method:: map_file(vfspath: str, realpath: str, compression: Optional[str] = None) -> None Map a file from the host machine into the VFS. .. py:method:: map_file_fh(vfspath: str, fh: BinaryIO) -> None Map a file handle into the VFS. .. py:method:: map_file_entry(vfspath: str, entry: FilesystemEntry) -> None Map a :class:`FilesystemEntry` into the VFS. Any missing subdirectories up to, but not including, the last part of ``vfspath`` will be created. .. py:method:: 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. :param vfspath: Destination path in the virtual filesystem. :param tar_file: Source path of the tar file to map. :param map_single_file: Only mount a single file found inside the tar at the specified path. .. py:method:: 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. :param vfspath: Destination path in the virtual filesystem. :param tar_file: Source path of the tar file to map. .. py:method:: link(src: str, dst: str) -> None Hard link a :class:`FilesystemEntry` to another location. :param src: The path to the target of the link. :param dst: The path to the link. .. py:method:: symlink(src: str, dst: str) -> None Create a symlink to another location. :param src: The path to the target of the symlink. :param dst: The path to the symlink. .. py:class:: LayerFilesystem(**kwargs) Bases: :py:obj:`Filesystem` Base class for filesystems. .. py:property:: case_sensitive :type: bool Whether the filesystem is case sensitive. .. py:property:: alt_separator :type: str The alternative separator of the filesystem. .. py:attribute:: __type__ :value: 'layer' .. py:attribute:: add_layer .. py:method:: __getattr__(attr: str) -> Any Provide "magic" access to filesystem specific attributes from any of the layers. For example, on a :class:`LayerFilesystem` ``fs``, you can do ``fs.ntfs`` to access the internal NTFS object if it has an NTFS layer. .. py:method:: detect(fh: BinaryIO) -> bool :staticmethod: Detect whether the ``fh`` file-handle is supported by this ``Filesystem`` implementation. The position of ``fh`` will be restored before returning. :param fh: A file-like object, usually a disk or partition. :returns: ``True`` if ``fh`` is supported, ``False`` otherwise. .. py:method:: 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. :param path: The path to mount the filesystem at. :param fs: The filesystem to mount. :param ignore_existing: Whether to ignore existing mounts and create a new layer. Defaults to ``True``. .. py:method:: link(dst: str, src: str) -> None Hard link a :class:`FilesystemEntry` to another location. .. py:method:: symlink(dst: str, src: str) -> None Create a symlink to another location. .. py:method:: append_layer(**kwargs) -> VirtualFilesystem Append a new layer. .. py:method:: prepend_layer(**kwargs) -> VirtualFilesystem Prepend a new layer. .. py:method:: append_fs_layer(fs: Filesystem) -> None Append a filesystem as a layer. :param fs: The filesystem to append. .. py:method:: prepend_fs_layer(fs: Filesystem) -> None Prepend a filesystem as a layer. :param fs: The filesystem to prepend. .. py:method:: remove_fs_layer(fs: Filesystem) -> None Remove a filesystem layer. :param fs: The filesystem to remove. .. py:method:: remove_layer(idx: int) -> None Remove a layer by index. :param idx: The index of the layer to remove. .. py:method:: get(path: str, relentry: Optional[LayerFilesystemEntry] = None) -> LayerFilesystemEntry Get a :class:`FilesystemEntry` from the filesystem. .. py:class:: EntryList(value: FilesystemEntry | list[FilesystemEntry]) Bases: :py:obj:`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. .. py:method:: __getattr__(attr: str) -> Any .. py:class:: LayerFilesystemEntry(fs: Filesystem, path: str, entry: FilesystemEntry) Bases: :py:obj:`FilesystemEntry` Base class for filesystem entries. .. py:method:: get(path: str) -> FilesystemEntry Retrieve a :class:`FilesystemEntry` relative to this entry. :param path: The path relative to this filesystem entry. :returns: A relative :class:`FilesystemEntry`. .. py:method:: open() -> BinaryIO Open this filesystem entry. :returns: A file-like object. Resolves symlinks when possible .. py:method:: iterdir() -> Iterator[str] Iterate over the contents of a directory, return them as strings. :returns: An iterator of directory entries as path strings. .. py:method:: scandir() -> Iterator[LayerFilesystemEntry] Iterate over the contents of a directory, yields :class:`FilesystemEntry`. :returns: An iterator of :class:`FilesystemEntry`. .. py:method:: is_file(follow_symlinks: bool = True) -> bool Determine if this entry is a file. :param 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). .. py:method:: is_dir(follow_symlinks: bool = True) -> bool Determine if this entry is a directory. :param 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). .. py:method:: is_symlink() -> bool Determine whether this entry is a symlink. :returns: ``True`` if the entry is a symbolic link, ``False`` otherwise. .. py:method:: 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. .. py:method:: 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. :param follow_symlinks: Whether to resolve the symbolic link if this entry is a symbolic link. :returns: The stat information of this entry. .. py:method:: 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. .. py:method:: 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. .. py:method:: lattr() -> Any The attributes related to this current entry, **without** resolving links. :returns: The attributes of this entry. .. py:class:: RootFilesystem(target: dissect.target.target.Target) Bases: :py:obj:`LayerFilesystem` Base class for filesystems. .. py:attribute:: __type__ :value: 'root' .. py:method:: detect(fh: BinaryIO) -> bool :staticmethod: Detect whether the ``fh`` file-handle is supported by this ``Filesystem`` implementation. The position of ``fh`` will be restored before returning. :param fh: A file-like object, usually a disk or partition. :returns: ``True`` if ``fh`` is supported, ``False`` otherwise. .. py:method:: get(path: str, relentry: Optional[LayerFilesystemEntry] = None) -> RootFilesystemEntry Get a :class:`FilesystemEntry` from the filesystem. .. py:class:: RootFilesystemEntry(fs: Filesystem, path: str, entry: FilesystemEntry) Bases: :py:obj:`LayerFilesystemEntry` Base class for filesystem entries. .. py:attribute:: fs :type: RootFilesystem .. py:method:: get(path: str) -> RootFilesystemEntry Retrieve a :class:`FilesystemEntry` relative to this entry. :param path: The path relative to this filesystem entry. :returns: A relative :class:`FilesystemEntry`. .. py:method:: open() -> BinaryIO Open this filesystem entry. :returns: A file-like object. Resolves symlinks when possible .. py:method:: iterdir() -> Iterator[str] Iterate over the contents of a directory, return them as strings. :returns: An iterator of directory entries as path strings. .. py:method:: scandir() -> Iterator[RootFilesystemEntry] Iterate over the contents of a directory, yields :class:`FilesystemEntry`. :returns: An iterator of :class:`FilesystemEntry`. .. py:method:: is_file(follow_symlinks: bool = True) -> bool Determine if this entry is a file. :param 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). .. py:method:: is_dir(follow_symlinks: bool = True) -> bool Determine if this entry is a directory. :param 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). .. py:method:: is_symlink() -> bool Determine whether this entry is a symlink. :returns: ``True`` if the entry is a symbolic link, ``False`` otherwise. .. py:method:: 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. .. py:method:: 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. :param follow_symlinks: Whether to resolve the symbolic link if this entry is a symbolic link. :returns: The stat information of this entry. .. py:method:: 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. .. py:method:: 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. .. py:method:: lattr() -> Any The attributes related to this current entry, **without** resolving links. :returns: The attributes of this entry. .. py:function:: 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. :param module: The module where to find the filesystem. :param class_name: The class to load. :param internal: Whether it is an internal module or not. .. py:function:: is_multi_volume_filesystem(fh: BinaryIO) -> bool .. py:function:: open(fh: BinaryIO, *args, **kwargs) -> Filesystem .. py:function:: open_multi_volume(fhs: list[BinaryIO], *args, **kwargs) -> Filesystem