dissect.target 3.20.dev36__py3-none-any.whl → 3.20.dev38__py3-none-any.whl

dissect/target/filesystems/config.py

@@ -133,7 +133,7 @@ class ConfigurationEntry(FilesystemEntry):
     Behaves like a ``directory`` when :attr:`parser_items` is a :class:`.ConfigurationParser` or a ``dict``.
     Behaves like a ``file`` otherwise.
 
-    Attributes:
+    Args:
         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

dissect/target/helpers/compat/path_common.py

@@ -56,11 +56,11 @@ class _DissectScandirIterator:
 
     The _DissectScandirIterator provides a context manager, so scandir can be called as:
 
-    ```
-    with scandir(path) as it:
-        for entry in it
-            print(entry.name)
-    ```
+    .. code-block:: python
+
+        with scandir(path) as it:
+            for entry in it
+                print(entry.name)
 
     similar to os.scandir() behaviour since Python 3.6.
     """

dissect/target/helpers/configutil.py

@@ -69,9 +69,7 @@ def _update_dictionary(current: dict[str, Any], key: str, value: Any) -> None:
 
 
 class PeekableIterator:
-    """Source gotten from:
-    https://more-itertools.readthedocs.io/en/stable/_modules/more_itertools/more.html#peekable
-    """
+    # https://more-itertools.readthedocs.io/en/stable/_modules/more_itertools/more.html#peekable
 
     def __init__(self, iterable):
         self._iterator = iter(iterable)
@@ -98,9 +96,6 @@ class PeekableIterator:
 class ConfigurationParser:
     """A configuration parser where you can configure certain aspects of the parsing mechanism.
 
-    Attributes:
-        parsed_data: The resulting dictionary after parsing.
-
     Args:
         collapse: A ``bool`` or an ``Iterator``:
           If ``True``: it will collapse all the resulting dictionary values.
@@ -195,6 +190,8 @@ class Default(ConfigurationParser):
 
     This parser splits only on the first ``separator`` it finds:
 
+    .. code-block::
+
         key<separator>value     -> {"key": "value"}
 
         key<separator>value\n
@@ -316,7 +313,7 @@ class Bin(ConfigurationParser):
 
 
 class Xml(ConfigurationParser):
-    """Parses an XML file. Ignores any constructor parameters passed from ``ConfigurationParser`."""
+    """Parses an XML file. Ignores any constructor parameters passed from ``ConfigurationParser``."""
 
     def _tree(self, tree: ElementTree, root: bool = False) -> dict:
         """Very simple but robust xml -> dict implementation, see comments."""
@@ -395,8 +392,9 @@ class ListUnwrapper:
     def unwrap(data: Union[dict, list]) -> Union[dict, list]:
         """Transforms a list with dictionaries to a dictionary.
 
-        The order of the list is preserved. If no dictionary is found,
-        the list remains untouched:
+        The order of the list is preserved. If no dictionary is found, the list remains untouched:
+
+        .. code-block::
 
             ["value1", "value2"]    -> ["value1", "value2"]
 
@@ -622,6 +620,8 @@ class Indentation(Default):
 
     The parser parses this as the following:
 
+    .. code-block::
+
       key value
         key2 value2
                        -> {"key value": {"key2": "value2"}}
@@ -644,7 +644,7 @@ class Indentation(Default):
         Args:
             manager: A :class:`ScopeManager` that contains the logic to ``push`` and ``pop`` scopes. And keeps state.
             line: The line to be parsed.
-            key: The key that should be updated during a :method:`ScopeManager.push``.
+            key: The key that should be updated during a :method:`ScopeManager.push`.
             next_line: The next line to be parsed.
 
         Returns:
@@ -694,26 +694,28 @@ class SystemD(Indentation):
     """A :class:`ConfigurationParser` that specifically parses systemd configuration files.
 
     Examples:
-        >>> systemd_data = textwrap.dedent(
-                '''
-                [Section1]
-                Key=Value
-                [Section2]
-                Key2=Value 2\\
-                    Value 2 continued
-                '''
-            )
-        >>> parser = SystemD(io.StringIO(systemd_data))
-        >>> parser.parser_items
-        {
-            "Section1": {
-                "Key": "Value
-            },
-            "Section2": {
-                "Key2": "Value2 Value 2 continued
-            }
-        }
 
+        .. code-block::
+
+            >>> systemd_data = textwrap.dedent(
+                    '''
+                    [Section1]
+                    Key=Value
+                    [Section2]
+                    Key2=Value 2\\
+                        Value 2 continued
+                    '''
+                )
+            >>> parser = SystemD(io.StringIO(systemd_data))
+            >>> parser.parser_items
+            {
+                "Section1": {
+                    "Key": "Value
+                },
+                "Section2": {
+                    "Key2": "Value2 Value 2 continued
+                }
+            }
     """
 
     def _change_scope(

dissect/target/helpers/cyber.py

@@ -52,6 +52,8 @@ MATRIX_REVEAL_SECONDS = 4
 
 
 class Color(Enum):
+    """Cyber colors."""
+
     BLACK = 30
     RED = 31
     GREEN = 32

dissect/target/helpers/docs.py

@@ -46,7 +46,7 @@ def get_real_func_obj(func: Callable) -> Tuple[Type, Callable]:
     return (klass, func)
 
 
-def get_docstring(obj: Any, placeholder=NO_DOCS) -> str:
+def get_docstring(obj: Any, placeholder: str = NO_DOCS) -> str:
     """Get object's docstring or a placeholder if no docstring found"""
     # Use of `inspect.cleandoc()` is preferred to `textwrap.dedent()` here
     # because many multi-line docstrings in the codebase

dissect/target/helpers/keychain.py

@@ -8,6 +8,8 @@ log = logging.getLogger(__name__)
 
 
 class KeyType(Enum):
+    """Valid key types."""
+
     RAW = "raw"
     PASSPHRASE = "passphrase"
     RECOVERY_KEY = "recovery_key"

dissect/target/helpers/mount.py

@@ -8,7 +8,6 @@ from dissect.util.feature import Feature, feature_enabled
 
 from dissect.target.filesystem import Filesystem, FilesystemEntry
 
-HAS_FUSE3 = False
 if feature_enabled(Feature.BETA):
     from fuse3 import FuseOSError, Operations
     from fuse3.c_fuse import fuse_config_p, fuse_conn_info_p
@@ -20,6 +19,8 @@ else:
     fuse_config_p = c_void_p
     fuse_conn_info_p = c_void_p
 
+    HAS_FUSE3 = False
+
 
 log = logging.getLogger(__name__)
 

dissect/target/plugin.py

@@ -1,6 +1,6 @@
 """Dissect plugin system.
 
-See dissect/target/plugins/general/example.py for an example plugin.
+See ``dissect/target/plugins/general/example.py`` for an example plugin.
 """
 
 from __future__ import annotations
@@ -76,18 +76,19 @@ def export(*args, **kwargs) -> Callable:
     Supported keyword arguments:
         property (bool): Whether this export should be regarded as a property.
             Properties are implicitly cached.
+
         cache (bool): Whether the result of this function should be cached.
+
         record (RecordDescriptor): The :class:`flow.record.RecordDescriptor` for the records that this function yields.
             If the records are dynamically made, use DynamicRecord instead.
-        output (str): The output type of this function. Can be one of:
 
+        output (str): The output type of this function. Must be one of:
         - default: Single return value
         - record: Yields records. Implicit when record argument is given.
         - yield: Yields printable values.
         - none: No return value. Plugin is responsible for output formatting and should return ``None``.
 
     The ``export`` decorator adds some additional private attributes to an exported method or property:
-
     - ``__output__``: The output type to expect for this function, this is the same as ``output``.
     - ``__record__``: The type of record to expect, this value is the same as ``record``.
     - ``__exported__``: set to ``True`` to indicate the method or property is exported.
@@ -173,7 +174,7 @@ class Plugin:
     class attribute. Namespacing results in your plugin needing to be prefixed
     with this namespace when being called. For example, if your plugin has
     specified ``test`` as namespace and a function called ``example``, you must
-    call your plugin with ``test.example``::
+    call your plugin with ``test.example``.
 
     A ``Plugin`` class has the following private class attributes:
 
@@ -430,15 +431,13 @@ def register(plugincls: Type[Plugin]) -> None:
     """Register a plugin, and put related data inside :attr:`PLUGINS`.
 
     This function uses the following private attributes that are set using decorators:
-
-    - ``__exported__``: Set in :func:`export`.
-    - ``__internal__``: Set in :func:`internal`.
+        - ``__exported__``: Set in :func:`export`.
+        - ``__internal__``: Set in :func:`internal`.
 
     Additionally, ``register`` sets the following private attributes on the `plugincls`:
-
-    - ``__plugin__``: Always set to ``True``.
-    - ``__functions__``: A list of all the methods and properties that are ``__internal__`` or ``__exported__``.
-    - ``__exports__``: A list of all the methods or properties that were explicitly exported.
+        - ``__plugin__``: Always set to ``True``.
+        - ``__functions__``: A list of all the methods and properties that are ``__internal__`` or ``__exported__``.
+        - ``__exports__``: A list of all the methods or properties that were explicitly exported.
 
     Args:
         plugincls: A plugin class to register.
@@ -1138,6 +1137,9 @@ class PluginFunction:
     method_name: str
     plugin_desc: PluginDescriptor = field(hash=False)
 
+    def __repr__(self) -> str:
+        return self.path
+
 
 def plugin_function_index(target: Optional[Target]) -> tuple[dict[str, PluginDescriptor], set[str]]:
     """Returns an index-list for plugins.
@@ -1292,7 +1294,7 @@ def find_plugin_functions(
                         path=index_name,
                         class_object=loaded_plugin_object,
                         method_name=method_name,
-                        output_type=getattr(fobject, "__output__", "text"),
+                        output_type=getattr(fobject, "__output__", "none"),
                         plugin_desc=func,
                     )
                 )
@@ -1337,7 +1339,7 @@ def find_plugin_functions(
                         path=f"{description['module']}.{funcname}",
                         class_object=loaded_plugin_object,
                         method_name=funcname,
-                        output_type=getattr(fobject, "__output__", "text"),
+                        output_type=getattr(fobject, "__output__", "none"),
                         plugin_desc=description,
                     )
                 )

dissect/target/plugins/apps/av/mcafee.py

@@ -40,6 +40,8 @@ re_strip_tags = re.compile(r"<[^!][^>]*>")
 
 
 class McAfeePlugin(Plugin):
+    """McAfee antivirus plugin."""
+
     __namespace__ = "mcafee"
 
     DIRS = [

dissect/target/plugins/apps/av/sophos.py

@@ -30,6 +30,8 @@ SophosLogRecord = TargetRecordDescriptor(
 
 
 class SophosPlugin(Plugin):
+    """Sophos antivirus plugin."""
+
     __namespace__ = "sophos"
 
     LOG_SOPHOS_HOME = "sysvol/ProgramData/Sophos/Clean/Logs/Clean.log"

dissect/target/plugins/apps/av/trendmicro.py

@@ -51,6 +51,8 @@ c_pfwlog = cstruct().load(pfwlog_def)
 
 
 class TrendMicroPlugin(Plugin):
+    """TrendMicro antivirus plugin."""
+
     __namespace__ = "trendmicro"
 
     LOG_FOLDER = "sysvol/Program Files (x86)/Trend Micro/Security Agent"

dissect/target/plugins/apps/browser/chromium.py

@@ -608,6 +608,15 @@ def remove_padding(decrypted: bytes) -> bytes:
 
 
 def decrypt_v10(encrypted_password: bytes) -> str:
+    """Decrypt a version 10 encrypted password.
+
+    Args:
+        encrypted_password: The encrypted password bytes.
+
+    Returns:
+        Decrypted password string.
+    """
+
     if not HAS_CRYPTO:
         raise ValueError("Missing pycryptodome dependency for AES operation")
 
@@ -625,12 +634,24 @@ def decrypt_v10(encrypted_password: bytes) -> str:
 
 
 def decrypt_v10_2(encrypted_password: bytes, key: bytes) -> str:
-    """
-    struct chrome_pass {
-        byte signature[3] = 'v10';
-        byte iv[12];
-        byte ciphertext[EOF];
-    }
+    """Decrypt a version 10 type 2 password.
+
+    References:
+
+        .. code-block::
+
+            struct chrome_pass {
+                byte signature[3] = 'v10';
+                byte iv[12];
+                byte ciphertext[EOF];
+            }
+
+    Args:
+        encrypted_password: The encrypted password bytes.
+        key: The encryption key.
+
+    Returns:
+        Decrypted password string.
     """
 
     if not HAS_CRYPTO:

dissect/target/plugins/apps/shell/powershell.py

@@ -1,3 +1,5 @@
+from typing import Iterator
+
 from dissect.target.exceptions import UnsupportedPluginError
 from dissect.target.helpers.descriptor_extensions import UserRecordDescriptorExtension
 from dissect.target.helpers.record import create_extended_descriptor
@@ -14,6 +16,8 @@ ConsoleHostHistoryRecord = create_extended_descriptor([UserRecordDescriptorExten
 
 
 class PowerShellHistoryPlugin(Plugin):
+    """Windows PowerShell history plugin."""
+
     PATHS = [
         "AppData/Roaming/Microsoft/Windows/PowerShell/psreadline",
         ".local/share/powershell/PSReadLine",
@@ -35,10 +39,10 @@ class PowerShellHistoryPlugin(Plugin):
             raise UnsupportedPluginError("No ConsoleHost_history.txt files found")
 
     @export(record=ConsoleHostHistoryRecord)
-    def powershell_history(self):
+    def powershell_history(self) -> Iterator[ConsoleHostHistoryRecord]:
         """Return PowerShell command history for all users.
 
-        The PowerShell ConsoleHost_history.txt file contains information about the commands executed with PowerShell in
+        The PowerShell ``ConsoleHost_history.txt`` file contains information about the commands executed with PowerShell in
         a terminal. No data is recorded from terminal-less PowerShell sessions. Commands are saved to disk after the process has completed.
         PSReadLine does not save commands containing 'password', 'asplaintext', 'token', 'apikey' or 'secret'.
 

dissect/target/plugins/apps/shell/wget.py

@@ -52,7 +52,7 @@ class WgetPlugin(Plugin):
             - https://gitlab.com/gnuwget/wget/-/blob/master/src/hsts.c
             - https://en.wikipedia.org/wiki/HTTP_Strict_Transport_Security
 
-        Yields ``WgetHstsRecord``s with the following fields:
+        Yields ``WgetHstsRecord`` records with the following fields:
 
         .. code-block:: text
 

dissect/target/plugins/apps/ssh/openssh.py

@@ -31,6 +31,8 @@ def find_sshd_directory(target: Target) -> TargetPath:
 
 
 class OpenSSHPlugin(SSHPlugin):
+    """OpenSSH plugin."""
+
     __namespace__ = "openssh"
 
     SSHD_DIRECTORIES = ["/sysvol/ProgramData/ssh", "/etc/ssh"]

dissect/target/plugins/apps/ssh/opensshd.py

@@ -74,6 +74,8 @@ SSHD_MULTIPLE_DEFINITIONS_ALLOWED_FIELDS = (
 
 
 class SSHServerPlugin(SSHPlugin):
+    """OpenSSHd server plugin."""
+
     __namespace__ = "opensshd"
 
     def __init__(self, target: Target):

dissect/target/plugins/apps/vpn/wireguard.py

@@ -52,15 +52,13 @@ class WireGuardPlugin(Plugin):
 
     __namespace__ = "wireguard"
 
-    """
-    TODO: NetworkManager uses a different stanza format
-          "/etc/NetworkManager/system-connections/Wireguard*",
-    TODO: systemd uses a different stanza format
-          "/etc/systemd/network/wg*.netdev",
-          "/etc/systemd/network/*wg*.netdev",
-    TODO: other locations such as $HOME/.config/wireguard
-    TODO: parse native network manager formats from MacOS, Ubuntu and Windows.
-    """
+    # TODO: NetworkManager uses a different stanza format
+    #       "/etc/NetworkManager/system-connections/Wireguard*",
+    # TODO: systemd uses a different stanza format
+    #       "/etc/systemd/network/wg*.netdev",
+    #       "/etc/systemd/network/*wg*.netdev",
+    # TODO: other locations such as $HOME/.config/wireguard
+    # TODO: parse native network manager formats from MacOS, Ubuntu and Windows.
 
     CONFIG_GLOBS = [
         # Linux
@@ -160,6 +158,8 @@ def _parse_config(content: str) -> ConfigParser:
 
 
 class MultiDict(OrderedDict):
+    """OrderedDict implementation which allows multiple values for the keys ``Peer`` and ``Interface``."""
+
     def __init__(self, *args, **kwargs):
         self._unique = 0
         super().__init__(*args, **kwargs)

dissect/target/plugins/apps/webhosting/cpanel.py

@@ -23,6 +23,8 @@ CPANEL_LASTLOGIN_PATTERN = re.compile(
 
 
 class CPanelPlugin(Plugin):
+    """cPanel webhosting plugin."""
+
     # TODO: Parse other log files https://support.cartika.com/portal/en/kb/articles/whm-cpanel-log-files-and-locations
     __namespace__ = "cpanel"
 

dissect/target/plugins/apps/webserver/caddy.py

@@ -22,6 +22,8 @@ LOG_REGEX = re.compile(
 
 
 class CaddyPlugin(WebserverPlugin):
+    """Caddy webserver plugin."""
+
     __namespace__ = "caddy"
 
     def __init__(self, target: Target):

dissect/target/plugins/apps/webserver/nginx.py

@@ -18,6 +18,8 @@ LOG_REGEX = re.compile(
 
 
 class NginxPlugin(WebserverPlugin):
+    """Nginx webserver plugin."""
+
     __namespace__ = "nginx"
 
     def __init__(self, target: Target):

dissect/target/plugins/child/esxi.py

@@ -1,3 +1,5 @@
+from typing import Iterator
+
 from dissect.target.exceptions import UnsupportedPluginError
 from dissect.target.helpers.record import ChildTargetRecord
 from dissect.target.plugin import ChildTargetPlugin
@@ -12,7 +14,7 @@ class ESXiChildTargetPlugin(ChildTargetPlugin):
         if self.target.os != "esxi":
             raise UnsupportedPluginError("Not an ESXi operating system")
 
-    def list_children(self):
+    def list_children(self) -> Iterator[ChildTargetRecord]:
         for vm in self.target.vm_inventory():
             yield ChildTargetRecord(
                 type=self.__type__,

dissect/target/plugins/child/virtuozzo.py

@@ -1,3 +1,5 @@
+from typing import Iterator
+
 from dissect.target.exceptions import UnsupportedPluginError
 from dissect.target.helpers.record import ChildTargetRecord
 from dissect.target.plugin import ChildTargetPlugin
@@ -9,13 +11,15 @@ class VirtuozzoChildTargetPlugin(ChildTargetPlugin):
     Virtuozzo conatiners are by default registered in the folder ``vz/root/$VEID``,
     where VEID will be substituted with the actual container UUID.
 
-    /
-      etc/
-      var/
-      vz/
-          root/
-              <container-uuid>/
-              <container-uuid>/
+    .. code-block::
+
+        /
+        etc/
+        var/
+        vz/
+            root/
+                <container-uuid>/
+                <container-uuid>/
 
     References:
         - https://docs.virtuozzo.com/virtuozzo_hybrid_server_7_command_line_reference/managing-system/configuration-files.html
@@ -29,7 +33,7 @@ class VirtuozzoChildTargetPlugin(ChildTargetPlugin):
         if not self.target.fs.path(self.PATH).exists():
             raise UnsupportedPluginError("No Virtuozzo path found")
 
-    def list_children(self):
+    def list_children(self) -> Iterator[ChildTargetRecord]:
         for container in self.target.fs.path(self.PATH).iterdir():
             yield ChildTargetRecord(
                 type=self.__type__,

dissect/target/plugins/filesystem/acquire_hash.py

@@ -1,5 +1,6 @@
 import csv
 import gzip
+from typing import Iterator
 
 from dissect.target.exceptions import UnsupportedPluginError
 from dissect.target.helpers.record import TargetRecordDescriptor
@@ -27,7 +28,7 @@ class AcquireHashPlugin(Plugin):
             raise UnsupportedPluginError("No hash file found")
 
     @export(record=AcquireHashRecord)
-    def acquire_hashes(self):
+    def acquire_hashes(self) -> Iterator[AcquireHashRecord]:
         """Return file hashes collected by Acquire.
 
         An Acquire file container contains a file hashes csv when the hashes module was used. The content of this csv

dissect/target/plugins/filesystem/icat.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import shutil
 import sys
 
@@ -27,24 +29,26 @@ class ICatPlugin(Plugin):
     )
     @arg("--ads", type=str, default="", help="Alternate Data Stream name")
     @export(output="none")
-    def icat(self, inum, fs, ads):
+    def icat(self, inum: int, fs: int | None, ads: str) -> None:
         """Output the contents of a file based on its MFT segment or inode number. Supports Alternate Data Streams
 
         Example:
-            # outputs contents of segment defaults to 'sysvol'
-            target-query <TARGET> -f icat --segment 96997
+            .. code-block::
+
+                # outputs contents of segment defaults to 'sysvol'
+                target-query <TARGET> -f icat --segment 96997
 
-            # outputs contents of inode defaults to '/'
-            target-query <TARGET> -f icat --inode 50947
+                # outputs contents of inode defaults to '/'
+                target-query <TARGET> -f icat --inode 50947
 
-            # outputs contents of segment's ADS
-            target-query <TARGET> -f icat --segment 96997 --ads Zone.Identifier
+                # outputs contents of segment's ADS
+                target-query <TARGET> -f icat --segment 96997 --ads Zone.Identifier
 
-            # outputs contents of segment in filesystem 3 of target
-            target-query <TARGET> -f icat --fs 3 --segment 96997
+                # outputs contents of segment in filesystem 3 of target
+                target-query <TARGET> -f icat --fs 3 --segment 96997
 
-            # outputs contents of inode in filesystem 2 of target
-            target-query <TARGET> -f icat --fs 2 --inode 50947
+                # outputs contents of inode in filesystem 2 of target
+                target-query <TARGET> -f icat --fs 2 --inode 50947
         """
 
         open_as = None

dissect/target/plugins/filesystem/ntfs/mft.py

@@ -123,6 +123,8 @@ COMPACT_RECORD_TYPES = {
 
 
 class MftPlugin(Plugin):
+    """NTFS MFT plugin."""
+
     def __init__(self, target):
         super().__init__(target)
         self.ntfs_filesystems = {index: fs for index, fs in enumerate(self.target.filesystems) if fs.__type__ == "ntfs"}

dissect/target/plugins/filesystem/ntfs/mft_timeline.py

@@ -93,6 +93,8 @@ def format_info(
 
 
 class MftTimelinePlugin(Plugin):
+    """NTFS MFT timeline plugin."""
+
     def check_compatible(self) -> None:
         ntfs_filesystems = [fs for fs in self.target.filesystems if fs.__type__ == "ntfs"]
         if not len(ntfs_filesystems):
@@ -100,7 +102,7 @@ class MftTimelinePlugin(Plugin):
 
     @export(output="yield")
     @arg("--ignore-dos", action="store_true", help="ignore DOS file names")
-    def mft_timeline(self, ignore_dos: bool = False):
+    def mft_timeline(self, ignore_dos: bool = False) -> Iterator[str]:
         """Return the MFT records of all NTFS filesystems in a human readable format (unsorted).
 
         The Master File Table (MFT) contains metadata about every file and folder on a NFTS filesystem.

dissect/target/plugins/filesystem/ntfs/usnjrnl.py

@@ -24,6 +24,8 @@ UsnjrnlRecord = TargetRecordDescriptor(
 
 
 class UsnjrnlPlugin(Plugin):
+    """NFTS UsnJrnl plugin."""
+
     def check_compatible(self) -> None:
         pass
 

dissect/target/plugins/filesystem/ntfs/utils.py

@@ -13,12 +13,14 @@ DRIVE_LETTER_RE = re.compile(r"[a-zA-Z]:")
 
 
 class InformationType(Enum):
+    """Valid information types"""
+
     STANDARD_INFORMATION = auto()
     FILE_INFORMATION = auto()
     ALTERNATE_DATA_STREAM = auto()
 
 
-def get_drive_letter(target: Target, filesystem: NtfsFilesystem):
+def get_drive_letter(target: Target, filesystem: NtfsFilesystem) -> str:
     """Retrieve the drive letter from the loaded mounts
 
     When the drive letter is not available for that filesystem it returns empty.