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

dissect/target/plugins/filesystem/unix/suid.py

@@ -1,4 +1,5 @@
 import stat
+from typing import Iterator
 
 from dissect.target.exceptions import UnsupportedPluginError
 from dissect.target.helpers.record import TargetRecordDescriptor
@@ -12,12 +13,14 @@ SuidRecord = TargetRecordDescriptor(
 
 
 class SuidPlugin(Plugin):
+    """Unix SUID binary plugin."""
+
     def check_compatible(self) -> None:
         if not self.target.has_function("walkfs") or self.target.os == "windows":
             raise UnsupportedPluginError("Unsupported plugin")
 
     @export(record=SuidRecord)
-    def suid_binaries(self):
+    def suid_binaries(self) -> Iterator[SuidRecord]:
         """Return all SUID binaries.
 
         A SUID binary allows all users to run it with the permissions of its owner. This means that a

dissect/target/plugins/filesystem/walkfs.py

@@ -27,6 +27,8 @@ FilesystemRecord = TargetRecordDescriptor(
 
 
 class WalkFSPlugin(Plugin):
+    """Filesystem agnostic walkfs plugin."""
+
     def check_compatible(self) -> None:
         if not len(self.target.filesystems):
             raise UnsupportedPluginError("No filesystems to walk")

dissect/target/plugins/general/example.py

@@ -69,7 +69,7 @@ class ExamplePlugin(Plugin):
         """
         pass
 
-    @export
+    @export(output="default")
     @arg("--flag", action="store_true", help="optional example flag")
     def example(self, flag: bool = False) -> str:
         """Example plugin function.
@@ -117,7 +117,7 @@ class ExamplePlugin(Plugin):
         To include registry or user information in a record, you must create a new record descriptor using
         :func:`~dissect.target.helpers.record.create_extended_descriptor` with
         :class:`~dissect.target.helpers.descriptor_extensions.RegistryRecordDescriptorExtension` and/or
-        :class:`~dissect.target.helpers.descriptor_extensions.UserRecordDescriptorExtension as extensions.
+        :class:`~dissect.target.helpers.descriptor_extensions.UserRecordDescriptorExtension` as extensions.
         """
         for key in self.target.registry.keys("HKCU\\SOFTWARE"):
             user = self.target.registry.get_user(key)

dissect/target/plugins/general/loaders.py

@@ -10,7 +10,7 @@ class LoaderListPlugin(Plugin):
         pass
 
     @export(output="none")
-    def loaders(self):
+    def loaders(self) -> None:
         """List the available loaders."""
 
         loaders_info = {}

dissect/target/plugins/general/network.py

@@ -17,6 +17,8 @@ InterfaceRecord = Union[UnixInterfaceRecord, WindowsInterfaceRecord, MacInterfac
 
 
 class NetworkPlugin(Plugin):
+    """Generic implementation for network interfaces plugin."""
+
     __namespace__ = "network"
 
     def __init__(self, target: Target):
@@ -41,6 +43,7 @@ class NetworkPlugin(Plugin):
 
     @export(record=InterfaceRecord)
     def interfaces(self) -> Iterator[InterfaceRecord]:
+        """Yield interfaces."""
         # Only search for the interfaces once
         if self._interface_list is None:
             self._interface_list = list(self._interfaces())
@@ -49,18 +52,22 @@ class NetworkPlugin(Plugin):
 
     @export
     def ips(self) -> list[IPAddress]:
+        """Return IP addresses as list of :class:`IPAddress`."""
         return list(self._get_record_type("ip"))
 
     @export
     def gateways(self) -> list[IPAddress]:
+        """Return gateways as list of :class:`IPAddress`."""
         return list(self._get_record_type("gateway"))
 
     @export
     def macs(self) -> list[str]:
+        """Return MAC addresses as list of :class:`str`."""
         return list(self._get_record_type("mac"))
 
     @export
     def dns(self) -> list[str]:
+        """Return DNS addresses as list of :class:`str`."""
         return list(self._get_record_type("dns"))
 
     @internal

dissect/target/plugins/general/osinfo.py

@@ -22,6 +22,7 @@ class OSInfoPlugin(plugin.Plugin):
 
     @plugin.export(record=OSInfoRecord)
     def osinfo(self) -> Iterator[Union[OSInfoRecord, GroupedRecord]]:
+        """Yield grouped records with target OS info."""
         for os_func in self.target._os.__functions__:
             if os_func in ["is_compatible", "get_all_records"]:
                 continue

dissect/target/plugins/general/plugins.py

@@ -98,12 +98,16 @@ def get_description_dict(
 
 
 class PluginListPlugin(Plugin):
+    """Plugin list plugin (so meta)."""
+
     def check_compatible(self) -> None:
         pass
 
     @export(output="none", cache=False)
     @arg("--docs", dest="print_docs", action="store_true")
     def plugins(self, plugins: list[dict] = None, print_docs: bool = False) -> None:
+        """Print all registered plugins to stdout."""
+
         categorized_plugins = dict(sorted(categorize_plugins(plugins).items()))
         plugin_descriptions = output_plugin_description_recursive(categorized_plugins, print_docs)
 

dissect/target/plugins/os/unix/_os.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 import logging
 import re
 import uuid
+from pathlib import Path
 from struct import unpack
 from typing import Iterator
 
@@ -145,7 +146,7 @@ class UnixPlugin(OSPlugin):
     def os(self) -> str:
         return OperatingSystem.UNIX.value
 
-    def _parse_rh_legacy(self, path):
+    def _parse_rh_legacy(self, path: Path) -> str | None:
         hostname = None
         file_contents = path.open("rt").readlines()
         for line in file_contents:

dissect/target/plugins/os/unix/bsd/citrix/history.py

@@ -44,6 +44,8 @@ CITRIX_NETSCALER_BASH_HISTORY_RE = re.compile(
 
 
 class CitrixCommandHistoryPlugin(CommandHistoryPlugin):
+    """Citrix command history plugin."""
+
     COMMAND_HISTORY_ABSOLUTE_PATHS = (("citrix-netscaler-bash", "/var/log/bash.log*"),)
     COMMAND_HISTORY_RELATIVE_PATHS = CommandHistoryPlugin.COMMAND_HISTORY_RELATIVE_PATHS + (
         ("citrix-netscaler-cli", ".nscli_history"),

dissect/target/plugins/os/unix/bsd/osx/network.py

@@ -10,6 +10,8 @@ from dissect.target.target import Target
 
 
 class MacNetworkPlugin(NetworkPlugin):
+    """macOS network interface plugin."""
+
     def __init__(self, target: Target):
         super().__init__(target)
         self._plistnetwork = cache(self._plistnetwork)

dissect/target/plugins/os/unix/bsd/osx/user.py

@@ -20,6 +20,8 @@ AccountPolicyRecord = create_extended_descriptor([UserRecordDescriptorExtension]
 
 
 class UserPlugin(Plugin):
+    """MacOS / OSX user plugin."""
+
     # TODO: Parse additional user data like: HeimdalSRPKey, KerberosKeys, ShadowHashData, LinkedIdentity,
     # inputSources, smartCardSecureTokenData, smartCardSecureTokenUUID, unlockOptions, smb_sid
 
@@ -31,6 +33,8 @@ class UserPlugin(Plugin):
 
     @export(record=AccountPolicyRecord)
     def account_policy(self) -> Iterator[AccountPolicyRecord]:
+        """Yield user account policy information"""
+
         # The data is not retrieved from the home folder of the user
         for user_details in self.target.user_details.all():
             user = plistlib.load(self.target.fs.path(user_details.user.source).open())

dissect/target/plugins/os/unix/cronjobs.py

@@ -1,4 +1,7 @@
+from __future__ import annotations
+
 import re
+from typing import Iterator
 
 from dissect.target.helpers.record import TargetRecordDescriptor
 from dissect.target.plugin import Plugin, export
@@ -28,10 +31,12 @@ EnvironmentVariableRecord = TargetRecordDescriptor(
 
 
 class CronjobPlugin(Plugin):
+    """Unix cronjob plugin."""
+
     def check_compatible(self) -> None:
         pass
 
-    def parse_crontab(self, file_path):
+    def parse_crontab(self, file_path) -> Iterator[CronjobRecord | EnvironmentVariableRecord]:
         for line in file_path.open("rt"):
             line = line.strip()
             if line.startswith("#") or not len(line):
@@ -67,9 +72,8 @@ class CronjobPlugin(Plugin):
                 )
 
     @export(record=[CronjobRecord, EnvironmentVariableRecord])
-    def cronjobs(self):
-        """
-        Return all cronjobs.
+    def cronjobs(self) -> Iterator[CronjobRecord | EnvironmentVariableRecord]:
+        """Yield cronjobs on the unix system.
 
         A cronjob is a scheduled task/command on a Unix based system. Adversaries may use cronjobs to gain
         persistence on the system.

dissect/target/plugins/os/unix/etc/etc.py

@@ -23,6 +23,8 @@ UnixConfigTreeRecord = TargetRecordDescriptor(
 
 
 class EtcTree(ConfigurationTreePlugin):
+    """Unix etc configuration tree plugin."""
+
     __namespace__ = "etc"
 
     def __init__(self, target: Target):
@@ -64,6 +66,8 @@ class EtcTree(ConfigurationTreePlugin):
     @arg("--glob", dest="pattern", required=False, default="*", type=str, help="Glob-style pattern to search for")
     @arg("--root", dest="root", required=False, default="/", type=str, help="Path to use as root for search")
     def etc(self, pattern: str, root: str) -> Iterator[UnixConfigTreeRecord]:
+        """Yield etc configuration records."""
+
         for entry, subs, items in self.config_fs.walk(root):
             for item in items:
                 try:

dissect/target/plugins/os/unix/generic.py

@@ -9,6 +9,8 @@ from dissect.target.plugin import Plugin, export
 
 
 class GenericPlugin(Plugin):
+    """Generic plugin for Unix targets."""
+
     def check_compatible(self) -> None:
         pass
 

dissect/target/plugins/os/unix/history.py

@@ -26,6 +26,8 @@ RE_FISH = re.compile(r"- cmd: (?P<command>.+?)\s+when: (?P<ts>\d+)")
 
 
 class CommandHistoryPlugin(Plugin):
+    """Unix command history plugin."""
+
     COMMAND_HISTORY_RELATIVE_PATHS = (
         ("bash", ".bash_history"),
         ("fish", ".local/share/fish/fish_history"),
@@ -59,7 +61,7 @@ class CommandHistoryPlugin(Plugin):
 
     @alias("bashhistory")
     @export(record=CommandHistoryRecord)
-    def commandhistory(self):
+    def commandhistory(self) -> Iterator[CommandHistoryRecord]:
         """Return shell history for all users.
 
         When using a shell, history of the used commands is kept on the system.
@@ -81,12 +83,12 @@ class CommandHistoryPlugin(Plugin):
     def parse_generic_history(self, file, user: UnixUserRecord, shell: str) -> Iterator[CommandHistoryRecord]:
         """Parse bash_history contents.
 
-        Regular .bash_history files contain one plain command per line.
-        An extended .bash_history file may look like this:
-        ```
-        #1648598339
-        echo "this is a test"
-        ```
+        Regular .bash_history files contain one plain command per line. Extended ``.bash_history`` files look like this:
+
+        .. code-block::
+
+            #1648598339
+            echo "this is a test"
 
         Resources:
             - http://git.savannah.gnu.org/cgit/bash.git/tree/bashhist.c
@@ -121,12 +123,12 @@ class CommandHistoryPlugin(Plugin):
     def parse_zsh_history(self, file, user: UnixUserRecord) -> Iterator[CommandHistoryRecord]:
         """Parse zsh_history contents.
 
-        Regular .zsh_history lines are just the plain commands.
-        Extended .zsh_history files may look like this:
-        ```
-        : 1673860722:0;sudo apt install sl
-        : :;
-        ```
+        Regular ``.zsh_history`` lines are just the plain commands. Extended ``.zsh_history`` files look like this:
+
+        .. code-block::
+
+            : 1673860722:0;sudo apt install sl
+            : :;
 
         Resources:
             - https://sourceforge.net/p/zsh/code/ci/master/tree/Src/hist.c
@@ -157,18 +159,18 @@ class CommandHistoryPlugin(Plugin):
     def parse_fish_history(self, history_file: TargetPath, user: UnixUserRecord) -> Iterator[CommandHistoryRecord]:
         """Parses the history file of the fish shell.
 
-        The fish history file is formatted as pseudo-YAML.
-        An example of such a file:
-        ```
-        - cmd: ls
-          when: 1688642435
-        - cmd: cd home/
-          when: 1688642441
-          paths:
-            - home/
-        - cmd: echo "test: test"
-          when: 1688986629
-        ```
+        The fish history file is formatted as pseudo-YAML. An example of such a file:
+
+        .. code-block::
+
+            - cmd: ls
+            when: 1688642435
+            - cmd: cd home/
+            when: 1688642441
+            paths:
+                - home/
+            - cmd: echo "test: test"
+            when: 1688986629
 
         Note that the last `- cmd: echo "test: test"` is not valid YAML,
         which is why we cannot safely use the Python yaml module.

dissect/target/plugins/os/unix/linux/cmdline.py

@@ -16,6 +16,8 @@ CmdlineRecord = TargetRecordDescriptor(
 
 
 class CmdlinePlugin(Plugin):
+    """Linux volatile proc commandline plugin."""
+
     def check_compatible(self) -> None:
         self.target.proc
 

dissect/target/plugins/os/unix/linux/debian/apt.py

@@ -10,13 +10,16 @@ from dissect.target.helpers.fsutil import open_decompress
 from dissect.target.plugins.os.unix.packagemanager import (
     OperationTypes,
     PackageManagerLogRecord,
+    PackageManagerPlugin,
 )
 
 APT_LOG_OPERATIONS = ["Install", "Reinstall", "Upgrade", "Downgrade", "Remove", "Purge"]
 REGEX_PACKAGE_NAMES = re.compile(r"(.*?\)),?")
 
 
-class AptPlugin(plugin.Plugin):
+class AptPlugin(PackageManagerPlugin):
+    """Apt package manager plugin."""
+
     __namespace__ = "apt"
 
     LOG_DIR_PATH = "/var/log/apt"

dissect/target/plugins/os/unix/linux/debian/dpkg.py

@@ -1,6 +1,6 @@
 import gzip
 from datetime import datetime
-from typing import Dict, Generator, List, TextIO
+from typing import Dict, Generator, Iterator, List, TextIO
 
 from dissect.target.exceptions import UnsupportedPluginError
 from dissect.target.helpers.record import TargetRecordDescriptor
@@ -59,7 +59,7 @@ class DpkgPlugin(Plugin):
             raise UnsupportedPluginError("No DPKG files found")
 
     @export(record=DpkgPackageStatusRecord)
-    def status(self):
+    def status(self) -> Iterator[DpkgPackageStatusRecord]:
         """Yield records for packages in dpkg's status database"""
 
         status_file_path = self.target.fs.path(STATUS_FILE_NAME)
@@ -82,7 +82,7 @@ class DpkgPlugin(Plugin):
             yield DpkgPackageStatusRecord(_target=self.target, **record_fields)
 
     @export(record=DpkgPackageLogRecord)
-    def log(self):
+    def log(self) -> Iterator[DpkgPackageLogRecord]:
         """Yield records for actions logged in dpkg's logs"""
 
         for log_file in self.target.fs.glob(LOG_FILES_GLOB):

dissect/target/plugins/os/unix/linux/environ.py

@@ -16,6 +16,8 @@ EnvironmentVariableRecord = TargetRecordDescriptor(
 
 
 class EnvironPlugin(Plugin):
+    """Linux volatile proc environment plugin."""
+
     def check_compatible(self) -> None:
         self.target.proc
 

dissect/target/plugins/os/unix/linux/fortios/generic.py

@@ -9,6 +9,8 @@ from dissect.target.plugins.os.unix.generic import calculate_last_activity
 
 
 class GenericPlugin(Plugin):
+    """Generic FortiOS plugin."""
+
     def check_compatible(self) -> None:
         if self.target.os != "fortios":
             raise UnsupportedPluginError("FortiOS specific plugin loaded on non-FortiOS target")

dissect/target/plugins/os/unix/linux/fortios/locale.py

@@ -5,6 +5,8 @@ from dissect.target.plugin import Plugin, export
 
 
 class LocalePlugin(Plugin):
+    """FortiOS locale plugin."""
+
     def check_compatible(self) -> None:
         if self.target.os != "fortios":
             raise UnsupportedPluginError("FortiOS specific plugin loaded on non-FortiOS target")

dissect/target/plugins/os/unix/linux/modules.py

@@ -28,6 +28,8 @@ class Module:
 
 
 class ModulePlugin(Plugin):
+    """Linux volatile kernel ``/sys/module`` plugin."""
+
     def __init__(self, target: Target):
         super().__init__(target)
         self._module_base_path = self.target.fs.path("/sys/module")

dissect/target/plugins/os/unix/linux/netstat.py

@@ -8,6 +8,8 @@ NETSTAT_TEMPLATE = "{protocol:<12}{receive_queue:<10}{transmit_queue:<11}{local_
 
 
 class NetstatPlugin(Plugin):
+    """Linux volatile netstat plugin."""
+
     def check_compatible(self) -> None:
         self.target.proc
 

dissect/target/plugins/os/unix/linux/processes.py

@@ -18,6 +18,8 @@ ProcProcessRecord = TargetRecordDescriptor(
 
 
 class ProcProcesses(Plugin):
+    """Linux ``/proc`` process volatile plugin."""
+
     def check_compatible(self) -> None:
         self.target.proc
 

dissect/target/plugins/os/unix/linux/redhat/yum.py

@@ -7,13 +7,16 @@ from dissect.target.helpers.utils import year_rollover_helper
 from dissect.target.plugins.os.unix.packagemanager import (
     OperationTypes,
     PackageManagerLogRecord,
+    PackageManagerPlugin,
 )
 
 YUM_LOG_KEYWORDS = ["Installed", "Updated", "Erased", "Obsoleted"]
 RE_TS = re.compile(r"(\w+\s{1,2}\d+\s\d{2}:\d{2}:\d{2})")
 
 
-class YumPlugin(plugin.Plugin):
+class YumPlugin(PackageManagerPlugin):
+    """Yum package manager plugin."""
+
     __namespace__ = "yum"
 
     LOG_DIR_PATH = "/var/log"

dissect/target/plugins/os/unix/linux/services.py

@@ -18,6 +18,8 @@ LinuxServiceRecord = TargetRecordDescriptor(RECORD_NAME, DEFAULT_ELEMENTS)
 
 
 class ServicesPlugin(Plugin):
+    """Linux services plugin."""
+
     SYSTEMD_PATHS = [
         "/etc/systemd/system",
         "/lib/systemd/system",
@@ -35,9 +37,9 @@ class ServicesPlugin(Plugin):
         """Return information about all installed systemd and init.d services.
 
         References:
-        - https://geeksforgeeks.org/what-is-init-d-in-linux-service-management
-        - http://0pointer.de/blog/projects/systemd-for-admins-3.html
-        - https://www.freedesktop.org/software/systemd/man/systemd.syntax.html
+            - https://geeksforgeeks.org/what-is-init-d-in-linux-service-management
+            - http://0pointer.de/blog/projects/systemd-for-admins-3.html
+            - https://www.freedesktop.org/software/systemd/man/latest/systemd.syntax.html
         """
 
         return chain(self.systemd(), self.initd())

dissect/target/plugins/os/unix/linux/sockets.py

@@ -64,6 +64,8 @@ PacketSocketRecord = TargetRecordDescriptor(
 
 
 class NetSocketPlugin(Plugin):
+    """Linux volatile net sockets plugin."""
+
     __namespace__ = "sockets"
 
     def __init__(self, target: Target):

dissect/target/plugins/os/unix/linux/suse/zypper.py

@@ -7,10 +7,13 @@ from dissect.target.helpers.fsutil import open_decompress
 from dissect.target.plugins.os.unix.packagemanager import (
     OperationTypes,
     PackageManagerLogRecord,
+    PackageManagerPlugin,
 )
 
 
-class ZypperPlugin(plugin.Plugin):
+class ZypperPlugin(PackageManagerPlugin):
+    """Zypper package manager plugin."""
+
     __namespace__ = "zypper"
 
     LOG_DIR_PATH = "/var/log/zypp"

dissect/target/plugins/os/unix/locale.py

@@ -29,6 +29,8 @@ def timezone_from_path(path: Path) -> str:
 
 
 class LocalePlugin(Plugin):
+    """Unix locale plugin."""
+
     def check_compatible(self) -> None:
         pass
 

dissect/target/plugins/os/unix/locate/gnulocate.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from typing import BinaryIO, Iterable
+from typing import BinaryIO, Iterable, Iterator
 
 from dissect.cstruct import cstruct
 
@@ -69,6 +69,8 @@ class GNULocateFile:
 
 
 class GNULocatePlugin(BaseLocatePlugin):
+    """GNU locate plugin."""
+
     __namespace__ = "gnulocate"
 
     path = "/var/cache/locate/locatedb"
@@ -78,7 +80,7 @@ class GNULocatePlugin(BaseLocatePlugin):
             raise UnsupportedPluginError(f"No locatedb file found at {self.path}")
 
     @export(record=GNULocateRecord)
-    def locate(self) -> GNULocateRecord:
+    def locate(self) -> Iterator[GNULocateRecord]:
         """Yield file and directory names from GNU findutils' locatedb file.
 
         Resources:

dissect/target/plugins/os/unix/locate/mlocate.py

@@ -115,6 +115,8 @@ class MLocateFile:
 
 
 class MLocatePlugin(BaseLocatePlugin):
+    """Unix mlocate plugin."""
+
     __namespace__ = "mlocate"
 
     path = "/var/lib/mlocate/mlocate.db"

dissect/target/plugins/os/unix/locate/plocate.py

@@ -163,6 +163,8 @@ class PLocateFile:
 
 
 class PLocatePlugin(BaseLocatePlugin):
+    """Unix plocate plugin."""
+
     __namespace__ = "plocate"
 
     path = "/var/lib/plocate/plocate.db"
@@ -177,7 +179,7 @@ class PLocatePlugin(BaseLocatePlugin):
             )
 
     @export(record=PLocateRecord)
-    def locate(self) -> PLocateRecord:
+    def locate(self) -> Iterator[PLocateRecord]:
         """Yield file and directory names from the plocate.db.
 
         ``plocate`` is the default package on Ubuntu 22 and newer to locate files.

dissect/target/plugins/os/unix/log/atop.py

@@ -247,6 +247,8 @@ class AtopFile:
 
 
 class AtopPlugin(Plugin):
+    """Unix atop plugin."""
+
     ATOP_GLOB = "atop_*"
     ATOP_MAGIC = 0xFEEDBEEF
     ATOP_PATH = "/var/log/atop"

dissect/target/plugins/os/unix/log/audit.py

@@ -24,6 +24,8 @@ AUDIT_REGEX = re.compile(r"^type=(?P<audit_type>.*) msg=audit\((?P<ts>.*):(?P<au
 
 
 class AuditPlugin(Plugin):
+    """Unix audit log plugin."""
+
     def __init__(self, target):
         super().__init__(target)
         self.log_paths = self.get_log_paths()
@@ -51,7 +53,7 @@ class AuditPlugin(Plugin):
 
         return log_paths
 
-    @export(record=[AuditRecord])
+    @export(record=AuditRecord)
     def audit(self) -> Iterator[AuditRecord]:
         """Return CentOS and RedHat audit information stored in /var/log/audit*.
 

dissect/target/plugins/os/unix/log/auth.py

@@ -22,17 +22,19 @@ RE_TS_AND_HOSTNAME = re.compile(_TS_REGEX + r"\s\S+\s")
 
 
 class AuthPlugin(Plugin):
+    """Unix auth log plugin."""
+
     def check_compatible(self) -> None:
         var_log = self.target.fs.path("/var/log")
         if not any(var_log.glob("auth.log*")) and not any(var_log.glob("secure*")):
             raise UnsupportedPluginError("No auth log files found")
 
-    @export(record=[AuthLogRecord])
+    @export(record=AuthLogRecord)
     def securelog(self) -> Iterator[AuthLogRecord]:
         """Return contents of /var/log/auth.log* and /var/log/secure*."""
         return self.authlog()
 
-    @export(record=[AuthLogRecord])
+    @export(record=AuthLogRecord)
     def authlog(self) -> Iterator[AuthLogRecord]:
         """Return contents of /var/log/auth.log* and /var/log/secure*."""