dissect.target 3.13.dev26__py3-none-any.whl → 3.14__py3-none-any.whl

dissect/target/filesystems/config.py

@@ -15,7 +15,32 @@ log = getLogger(__name__)
 
 
 class ConfigurationFilesystem(VirtualFilesystem):
-    __fstype__: str = "META:configuration"
+    """A special :class:`.Filesystem` class that allows you to browse and interact with configuration files
+    as ``directories`` and ``files`` by parsing the file into key/value pairs.
+
+    Depending on the ``value`` of a configuration file's ``key``, it will act like a ``directory`` or ``file``:
+        * When the ``key`` contains sub-values (dictionary), it will act like a ``directory``.
+        * Otherwise it will act like a ``file``.
+
+    Examples:
+        >>> fs = ConfigurationFilesystem(target, "/etc")
+        >>> entry = fs.get("xattr.conf")
+        <ConfigurationEntry path=/etc/xattr.conf value=<dissect.target.helpers.configutil.Default object at 0x115683280>
+        >>> entry.listdir() # listed entries are the keys in the configuration file
+        [...
+        'system.posix_acl_access',
+        'system.posix_acl_default',
+        'trusted.SGI_ACL_DEFAULT',
+        'trusted.SGI_ACL_FILE',
+        ...]
+        >>> entry.get("system.posix_acl_access") # returns the value of the key
+        <ConfigurationEntry path=/etc/xattr.conf/system.posix_acl_access value=permissions>
+        >>> entry.get("system.posix_acl_access").open().read() # returns the raw value of the key
+        b'permissions\\n'
+
+    """
+
+    __type__: str = "META:configuration"
 
     def __init__(self, target: Target, path: str, **kwargs):
         super().__init__(**kwargs)
@@ -28,8 +53,8 @@ class ConfigurationFilesystem(VirtualFilesystem):
         the start of the path.
 
         Returns:
-            A list of ``parts``: [filename, keys, into, the, file].
-            And the resolved entry.
+            A list of ``parts`` containing keys: [keys, into, the, file].
+            And the resolved entry: Entry(filename)
         """
         entry = relentry or self.root
 
@@ -40,7 +65,7 @@ class ConfigurationFilesystem(VirtualFilesystem):
 
         parts = path.split("/")
 
-        for idx, part in enumerate(parts):
+        for idx, part in enumerate(parts, start=1):
             # Resolve link
             if entry.is_symlink():
                 entry = entry.readlink_ext()
@@ -63,30 +88,85 @@ class ConfigurationFilesystem(VirtualFilesystem):
     def get(
         self, path: str, relentry: Optional[FilesystemEntry] = None, *args, **kwargs
     ) -> Union[FilesystemEntry, ConfigurationEntry]:
+        """Retrieve a :class:`ConfigurationEntry` or :class:`.FilesystemEntry` relative to the root or ``relentry``.
+
+        Raises:
+            FileNotFoundError: if it could not find the entry.
+        """
         parts, entry = self._get_till_file(path, relentry)
 
+        if entry.is_dir():
+            return entry
+
+        entry = self._convert_entry(entry, *args, **kwargs)
+
         for part in parts:
-            if isinstance(entry, ConfigurationEntry):
-                entry = entry.get(part)
-            else:
-                try:
-                    # The parts in _get_till_file also includes the filename, so we do not join
-                    # the part with entry.path here.
-                    config_parser = parse(entry, *args, **kwargs)
-                    entry = ConfigurationEntry(self, entry.path, entry, config_parser)
-                except (FileNotFoundError, ConfigurationParsingError):
-                    # If a parsing error gets created, it should return the `entry`
-                    log.debug(f"Error when parsing {entry.path}/{part}")
+            _prev_entry = entry
+            entry = entry.get(part)
+            if entry is None:
+                raise FileNotFoundError(f"{part!r} not found in {_prev_entry}.")
+
+        return entry
+
+    def _convert_entry(
+        self, file_entry: FilesystemEntry, *args, **kwargs
+    ) -> Union[ConfigurationEntry, FilesystemEntry]:
+        """Creates a :class:`ConfigurationEntry` from a ``file_entry``.
+
+        If an error occurs during the parsing of the file contents,
+        the original ``file_entry`` is returned.
+        """
+        entry = file_entry
+        try:
+            config_parser = parse(entry, *args, **kwargs)
+            entry = ConfigurationEntry(self, entry.path, entry, config_parser)
+        except ConfigurationParsingError:
+            # If a parsing error gets created, it should return the `entry`
+            log.debug("Error when parsing %s", entry.path)
+
         return entry
 
 
 class ConfigurationEntry(FilesystemEntry):
+    """A Special filesystem entry.
+
+    Behaves like a ``directory`` when :attr:`parser_items` is a :class:`.ConfigurationParser` or a ``dict``.
+    Behaves like a ``file`` otherwise.
+
+    Attributes:
+        parser_items: A dict-like object containing all configuration entries and values.
+            In most cases this is either a :class:`.ConfigurationParser` or ``dict``.
+            Otherwise, its the entry's value
+
+    Examples:
+        >>> fs = ConfigurationFilesystem(target, "/etc")
+        >>> entry = fs.get("xattr.conf")
+        <ConfigurationEntry path=/etc/xattr.conf value=<dissect.target.helpers.configutil.Default object at 0x115683280>
+        >>> entry.listdir() # listed entries are the keys in the configuration file
+        [...
+        'system.posix_acl_access',
+        'system.posix_acl_default',
+        'trusted.SGI_ACL_DEFAULT',
+        'trusted.SGI_ACL_FILE',
+        ...]
+        >>> entry.as_dict()
+        {
+            ...
+            "system.posix_acl_access" : "...",
+            ...
+        }
+        >>> entry.get("system.posix_acl_access") # returns the value of the key
+        <ConfigurationEntry path=/etc/xattr.conf/system.posix_acl_access value=permissions>
+        >>> entry.get("system.posix_acl_access").open().read() # returns the raw value of the key
+        b'permissions\\n'
+    """
+
     def __init__(
         self,
         fs: Filesystem,
         path: str,
         entry: FilesystemEntry,
-        parser_items: Optional[Union[dict, Any]] = None,
+        parser_items: Optional[Union[dict, ConfigurationParser, str, list]] = None,
     ) -> None:
         super().__init__(fs, path, entry)
         self.parser_items = parser_items
@@ -94,23 +174,48 @@ class ConfigurationEntry(FilesystemEntry):
     def __getitem__(self, item: str) -> ConfigurationEntry:
         return self.parser_items[item]
 
-    def get(self, path: Optional[str] = None) -> ConfigurationEntry:
+    def __repr__(self) -> str:
+        output = f"path={self.path}"
+
+        if not isinstance(self.parser_items, dict):
+            output += f" value={self.parser_items}"
+
+        return f"<{self.__class__.__name__} {output}"
+
+    def get(self, key, default: Optional[Any] = None) -> Union[ConfigurationEntry, Any, None]:
+        """Gets the dictionary key that belongs to this entry using ``key``.
+        Behaves like ``dictionary.get()``.
+
+        Args:
+            ``key``: A dictionary key that is inside :attr:`parser_items`.
+            ``default``: The default value to return if ``key`` is not inside this entry.
+
+        Returns:
+            a :class:`ConfigurationEntry` when ``key`` is present, otherwise its ``default``.
+        """
         # Check for path in config entry
-        if not path:
-            # Return self if configuration was found.
-            return self
+        if not key:
+            raise TypeError("key should be defined")
 
-        if path in self.parser_items:
+        if key in self.parser_items:
             return ConfigurationEntry(
                 self.fs,
-                fsutil.join(self.path, path, alt_separator=self.fs.alt_separator),
+                fsutil.join(self.path, key, alt_separator=self.fs.alt_separator),
                 self.entry,
-                self.parser_items[path],
+                self.parser_items[key],
             )
-        raise NotADirectoryError(f"Cannot open a {path!r} on a value")
+        return default
+
+    def _write_value_mapping(self, values: dict[str, Any], indentation_nr: int = 0) -> str:
+        """Internal function to transform the ``values`` dictionary to a string representation.
 
-    def _write_value_mapping(self, values: dict[str, Any], indentation_nr=0) -> str:
-        """Writes a dictionary to the output, c style."""
+        Args:
+            values: A dictionary or its contents.
+            indentation_nr: How much indentation this entry should receive.
+
+        Returns:
+            An indented string containing all the information inside ``values``.
+        """
         prefix = " " * indentation_nr
         output_buffer = io.StringIO()
 
@@ -126,9 +231,14 @@ class ConfigurationEntry(FilesystemEntry):
         return output_buffer.getvalue()
 
     def open(self) -> BinaryIO:
-        # Return fh for path if entry is a file
-        # Return bytes of value if entry is ConfigurationEntry
+        """Open this :class:`ConfigurationEntry`.
+
+        If :attr:`parser_items` is a :class:`.ConfigurationParser`,
+        it will ``open`` the underlying entry.
 
+        Returns:
+            A file-like object holding a byte representation of :attr:`parser_items`.
+        """
         if isinstance(self.parser_items, ConfigurationParser):
             # Currently trying to open the underlying entry
             return self.entry.open()
@@ -141,7 +251,7 @@ class ConfigurationEntry(FilesystemEntry):
             yield entry.name
 
     def scandir(self) -> Iterator[ConfigurationEntry]:
-        # Return dict keys
+        """Return the items inside :attr:`parser_items` as ``ConfigurationEntries``."""
         if self.is_file():
             raise NotADirectoryError()
 
@@ -152,19 +262,39 @@ class ConfigurationEntry(FilesystemEntry):
         return not self.is_dir(follow_symlinks)
 
     def is_dir(self, follow_symlinks: bool = True) -> bool:
+        """Returns whether this :class:`ConfigurationEntry` can be considered a directory."""
+        # if self.parser_items has keys (thus sub-values), we can consider it a directory.
         return hasattr(self.parser_items, "keys")
 
     def is_symlink(self) -> bool:
+        """Return whether this :class:`ConfigurationEntry` is a symlink or not.
+
+        Returns:
+            False, as ``ConfigurationEntries`` are never symlinks.
+        """
+        # ConfigurationEntries are already resolved, so are never symlinks.
         return False
 
-    def exists(self, path: str) -> bool:
-        return self.entry.exists() and path in self.parser_items
+    def exists(self, key: str) -> bool:
+        """Return whether the underlying :class:`.FilesystemEntry` :attr:`entry` and
+        supplied ``key`` exists inside this :class:`ConfigurationEntry`.
+
+        Returns:
+            Whether the ``entry`` and ``key`` exists
+        """
+        return self.entry.exists() and key in self.parser_items
 
     def stat(self, follow_symlinks: bool = True) -> fsutil.stat_result:
+        """Returns the stat from the underlying :class:`.FilesystemEntry` :attr:`entry`."""
         return self.entry.stat(follow_symlinks)
 
     def lstat(self) -> fsutil.stat_result:
+        """Returns the lstat from the underlying :class:`.FilesystemEntry` :attr:`entry`."""
+
         return self.entry.lstat()
 
     def as_dict(self) -> dict:
+        """Returns :attr:`parser_items` as a dictionary."""
+        if isinstance(self.parser_items, ConfigurationParser):
+            return self.parser_items.parsed_data
         return self.parser_items

dissect/target/filesystems/dir.py

@@ -13,7 +13,7 @@ from dissect.target.helpers import fsutil
 
 
 class DirectoryFilesystem(Filesystem):
-    __fstype__ = "dir"
+    __type__ = "dir"
 
     def __init__(self, path: Path, *args, **kwargs):
         super().__init__(None, *args, **kwargs)

dissect/target/filesystems/exfat.py

@@ -15,7 +15,7 @@ ExfatFileTree = tuple[exfat.c_exfat.FILE, dict[str, Optional["ExfatFileTree"]]]
 
 
 class ExfatFilesystem(Filesystem):
-    __fstype__ = "exfat"
+    __type__ = "exfat"
 
     def __init__(self, fh: BinaryIO, *args, **kwargs):
         super().__init__(fh, case_sensitive=False, alt_separator="\\", *args, **kwargs)

dissect/target/filesystems/extfs.py

@@ -15,7 +15,7 @@ from dissect.target.helpers import fsutil
 
 
 class ExtFilesystem(Filesystem):
-    __fstype__ = "ext"
+    __type__ = "ext"
 
     def __init__(self, fh: BinaryIO, *args, **kwargs):
         super().__init__(fh, *args, **kwargs)
@@ -125,6 +125,10 @@ class ExtFilesystemEntry(FilesystemEntry):
             ]
         )
 
+        # Set birthtime if available
+        if self.entry.crtime:
+            st_info.st_birthtime = self.entry.crtime.timestamp()
+
         # Set the nanosecond resolution separately
         st_info.st_atime_ns = self.entry.atime_ns
         st_info.st_mtime_ns = self.entry.mtime_ns

dissect/target/filesystems/fat.py

@@ -11,7 +11,7 @@ from dissect.target.helpers import fsutil
 
 
 class FatFilesystem(Filesystem):
-    __fstype__ = "fat"
+    __type__ = "fat"
 
     def __init__(self, fh: BinaryIO, *args, **kwargs):
         super().__init__(fh, case_sensitive=False, alt_separator="\\", *args, **kwargs)

dissect/target/filesystems/ffs.py

@@ -14,7 +14,7 @@ from dissect.target.helpers import fsutil
 
 
 class FfsFilesystem(Filesystem):
-    __fstype__ = "ffs"
+    __type__ = "ffs"
 
     def __init__(self, fh: BinaryIO, *args, **kwargs):
         super().__init__(fh, *args, **kwargs)

dissect/target/filesystems/itunes.py

@@ -22,7 +22,7 @@ if TYPE_CHECKING:
 class ITunesFilesystem(Filesystem):
     """Filesystem implementation for iTunes backups."""
 
-    __fstype__ = "itunes"
+    __type__ = "itunes"
 
     def __init__(self, backup: ITunesBackup, *args, **kwargs):
         super().__init__(None, *args, **kwargs)

dissect/target/filesystems/ntfs.py

@@ -20,7 +20,7 @@ from dissect.target.helpers import fsutil
 
 
 class NtfsFilesystem(Filesystem):
-    __fstype__ = "ntfs"
+    __type__ = "ntfs"
 
     def __init__(
         self,

dissect/target/filesystems/smb.py

@@ -31,7 +31,7 @@ log = logging.getLogger(__name__)
 class SmbFilesystem(Filesystem):
     """Filesystem implementation for SMB."""
 
-    __fstype__ = "smb"
+    __type__ = "smb"
 
     def __init__(self, conn: SMBConnection, share_name: str, *args, **kwargs):
         super().__init__(None, *args, **kwargs, alt_separator="\\", case_sensitive=False)

dissect/target/filesystems/squashfs.py

@@ -15,7 +15,7 @@ from dissect.target.helpers import fsutil
 
 
 class SquashFSFilesystem(Filesystem):
-    __fstype__ = "squashfs"
+    __type__ = "squashfs"
 
     def __init__(self, fh: BinaryIO, *args, **kwargs):
         super().__init__(fh, *args, **kwargs)

dissect/target/filesystems/tar.py

@@ -28,7 +28,7 @@ log = logging.getLogger(__name__)
 class TarFilesystem(Filesystem):
     """Filesystem implementation for tar files."""
 
-    __fstype__ = "tar"
+    __type__ = "tar"
 
     def __init__(
         self,

dissect/target/filesystems/vmfs.py

@@ -16,7 +16,7 @@ from dissect.target.helpers import fsutil
 
 
 class VmfsFilesystem(Filesystem):
-    __fstype__ = "vmfs"
+    __type__ = "vmfs"
 
     def __init__(self, fh: BinaryIO, *args, **kwargs):
         super().__init__(fh, *args, **kwargs)

dissect/target/filesystems/xfs.py

@@ -18,7 +18,7 @@ log = logging.getLogger(__name__)
 
 
 class XfsFilesystem(Filesystem):
-    __fstype__ = "xfs"
+    __type__ = "xfs"
 
     def __init__(self, fh: BinaryIO, *args, **kwargs):
         super().__init__(fh, *args, **kwargs)

dissect/target/filesystems/zip.py

@@ -28,7 +28,7 @@ class ZipFilesystem(Filesystem):
     See https://github.com/python/cpython/issues/82102 for more information.
     """
 
-    __fstype__ = "zip"
+    __type__ = "zip"
 
     def __init__(
         self,

dissect/target/helpers/cache.py

@@ -144,7 +144,7 @@ class Cache:
 
         if read_file_cache:
             target.log.debug("Reading from cache file: %s", cache_file)
-            if os.access(cache_file, os.R_OK, effective_ids=True):
+            if os.access(cache_file, os.R_OK, effective_ids=bool(os.supports_effective_ids)):
                 if os.stat(cache_file).st_size != 0:
                     try:
                         return self.open_reader(cache_file, output)
@@ -173,7 +173,7 @@ class Cache:
                         err,
                     )
 
-            if os.access(temp_dir, os.W_OK | os.R_OK | os.X_OK, effective_ids=True):
+            if os.access(temp_dir, os.W_OK | os.R_OK | os.X_OK, effective_ids=bool(os.supports_effective_ids)):
                 if os.path.exists(temp_path):
                     try:
                         os.remove(temp_path)