dissect.target 3.19.dev58__py3-none-any.whl → 3.20__py3-none-any.whl

dissect/target/helpers/regutil.py

@@ -1,11 +1,13 @@
-""" Registry related abstractions """
+"""Registry related abstractions"""
+
 from __future__ import annotations
 
 import fnmatch
 import re
-import struct
 from collections import defaultdict
 from datetime import datetime
+from enum import IntEnum
+from functools import cached_property
 from io import BytesIO
 from pathlib import Path
 from typing import BinaryIO, Iterator, Optional, TextIO, Union
@@ -28,6 +30,19 @@ ValueType = Union[int, str, bytes, list[str]]
 """The possible value types that can be returned from the registry."""
 
 
+class RegistryValueType(IntEnum):
+    NONE = regf.REG_NONE
+    SZ = regf.REG_SZ
+    EXPAND_SZ = regf.REG_EXPAND_SZ
+    BINARY = regf.REG_BINARY
+    DWORD = regf.REG_DWORD
+    DWORD_BIG_ENDIAN = regf.REG_DWORD_BIG_ENDIAN
+    MULTI_SZ = regf.REG_MULTI_SZ
+    FULL_RESOURCE_DESCRIPTOR = regf.REG_FULL_RESOURCE_DESCRIPTOR
+    RESOURCE_REQUIREMENTS_LIST = regf.REG_RESOURCE_REQUIREMENTS_LIST
+    QWORD = regf.REG_QWORD
+
+
 class RegistryHive:
     """Base class for registry hives."""
 
@@ -296,6 +311,7 @@ class VirtualKey(RegistryKey):
         self._class_name = class_name
         self._values: dict[str, RegistryValue] = {}
         self._subkeys: dict[str, RegistryKey] = {}
+        self._timestamp: datetime = None
         self.top: RegistryKey = None
         super().__init__(hive=hive)
 
@@ -325,11 +341,19 @@ class VirtualKey(RegistryKey):
         return self._path
 
     @property
-    def timestamp(self) -> datetime:
+    def timestamp(self) -> datetime | None:
         if self.top:
             return self.top.timestamp
+
+        if self._timestamp:
+            return self._timestamp
+
         return None
 
+    @timestamp.setter
+    def timestamp(self, ts: datetime) -> None:
+        self._timestamp = ts
+
     def subkey(self, subkey: str) -> RegistryKey:
         try:
             return self._subkeys[subkey.lower()]
@@ -405,8 +429,8 @@ class VirtualValue(RegistryValue):
         return self._value
 
     @property
-    def type(self) -> int:
-        return None
+    def type(self) -> RegistryValueType:
+        return RegistryValueType.NONE
 
 
 class HiveCollection(RegistryHive):
@@ -622,7 +646,7 @@ class RegfHive(RegistryHive):
         try:
             return RegfKey(self, self.hive.open(key))
         except regf.RegistryKeyNotFoundError as e:
-            raise RegistryKeyNotFoundError(key, cause=e)
+            raise RegistryKeyNotFoundError(key) from e
 
 
 class RegfKey(RegistryKey):
@@ -652,7 +676,7 @@ class RegfKey(RegistryKey):
         try:
             return RegfKey(self.hive, self.key.subkey(subkey))
         except regf.RegistryKeyNotFoundError as e:
-            raise RegistryKeyNotFoundError(subkey, cause=e)
+            raise RegistryKeyNotFoundError(subkey) from e
 
     def subkeys(self) -> list[RegistryKey]:
         return [RegfKey(self.hive, k) for k in self.key.subkeys()]
@@ -661,7 +685,7 @@ class RegfKey(RegistryKey):
         try:
             return RegfValue(self.hive, self.key.value(value))
         except regf.RegistryValueNotFoundError as e:
-            raise RegistryValueNotFoundError(value, cause=e)
+            raise RegistryValueNotFoundError(value) from e
 
     def values(self) -> list[RegistryValue]:
         return [RegfValue(self.hive, v) for v in self.key.values()]
@@ -683,8 +707,8 @@ class RegfValue(RegistryValue):
         return self.kv.value
 
     @property
-    def type(self) -> int:
-        return self.kv.type
+    def type(self) -> RegistryValueType:
+        return RegistryValueType(self.kv.type)
 
 
 class RegFlex:
@@ -750,17 +774,22 @@ class RegFlexKey(VirtualKey):
 
 class RegFlexValue(VirtualValue):
     def __init__(self, hive: RegistryHive, name: str, value: ValueType):
-        self._parsed_value = None
         super().__init__(hive, name, value)
 
+    @cached_property
+    def _parse(self) -> tuple[RegistryValueType, ValueType]:
+        return parse_flex_value(self._value)
+
     @property
     def value(self) -> ValueType:
-        if not self._parsed_value:
-            self._parsed_value = parse_flex_value(self._value)
-        return self._parsed_value
+        return self._parse[1]
+
+    @property
+    def type(self) -> RegistryValueType:
+        return self._parse[0]
 
 
-def parse_flex_value(value: str) -> ValueType:
+def parse_flex_value(value: str) -> tuple[RegistryValueType, ValueType]:
     """Parse values from text registry exports.
 
     Args:
@@ -770,31 +799,31 @@ def parse_flex_value(value: str) -> ValueType:
         NotImplementedError: If ``value`` is not of a supported type for parsing.
     """
     if value.startswith('"'):
-        return value.strip('"')
+        return RegistryValueType.SZ, value.strip('"')
 
     vtype, _, value = value.partition(":")
     if vtype == "dword":
-        return struct.unpack(">i", bytes.fromhex(value))[0]
+        return RegistryValueType.DWORD, int.from_bytes(bytes.fromhex(value), "big", signed=True)
     elif "hex" in vtype:
         value = bytes.fromhex(value.replace(",", ""))
         if vtype == "hex":
-            return value
+            return RegistryValueType.BINARY, value
 
         # hex(T)
         # These values match regf type values
         vtype = int(vtype[4:5], 16)
         if vtype == regf.REG_NONE:
-            return value if value else None
+            decoded = value if value else None
         elif vtype == regf.REG_SZ:
-            return regf.try_decode_sz(value)
+            decoded = regf.try_decode_sz(value)
         elif vtype == regf.REG_EXPAND_SZ:
-            return regf.try_decode_sz(value)
+            decoded = regf.try_decode_sz(value)
         elif vtype == regf.REG_BINARY:
-            return value
+            decoded = value
         elif vtype == regf.REG_DWORD:
-            return struct.unpack("<I", value)[0]
+            decoded = int.from_bytes(value, "little", signed=False)
         elif vtype == regf.REG_DWORD_BIG_ENDIAN:
-            return struct.unpack(">I", value)[0]
+            decoded = int.from_bytes(value, "big", signed=False)
         elif vtype == regf.REG_MULTI_SZ:
             d = BytesIO(value)
 
@@ -806,11 +835,12 @@ def parse_flex_value(value: str) -> ValueType:
 
                 r.append(s)
 
-            return r
+            decoded = r
         elif vtype == regf.REG_QWORD:
-            return struct.unpack(">Q", value)[0]
+            decoded = int.from_bytes(value, "big", signed=False)
         else:
             raise NotImplementedError(f"Registry flex value type {vtype}")
+        return RegistryValueType(vtype), decoded
 
 
 def has_glob_magic(pattern: str) -> bool:

dissect/target/loader.py

@@ -177,7 +177,6 @@ def open(item: Union[str, Path], *args, **kwargs) -> Loader:
 register("local", "LocalLoader")
 register("remote", "RemoteLoader")
 register("mqtt", "MQTTLoader")
-register("targetd", "TargetdLoader")
 register("asdf", "AsdfLoader")
 register("tar", "TarLoader")
 register("vmx", "VmxLoader")
@@ -206,4 +205,5 @@ register("velociraptor", "VelociraptorLoader")
 register("smb", "SmbLoader")
 register("cb", "CbLoader")
 register("cyber", "CyberLoader")
+register("proxmox", "ProxmoxLoader")
 register("multiraw", "MultiRawLoader")  # Should be last

dissect/target/loaders/mqtt.py

@@ -1,9 +1,11 @@
 from __future__ import annotations
 
+import argparse
 import atexit
 import logging
 import math
 import os
+import re
 import ssl
 import sys
 import time
@@ -280,7 +282,7 @@ class Broker:
     factor = 1
 
     def __init__(
-        self, broker: Broker, port: str, key: str, crt: str, ca: str, case: str, username: str, password: str, **kwargs
+        self, broker: str, port: str, key: str, crt: str, ca: str, case: str, username: str, password: str, **kwargs
     ):
         self.broker_host = broker
         self.broker_port = int(port)
@@ -341,9 +343,19 @@ class Broker:
             self.mqtt_client.subscribe(f"{self.case}/{host}/DISKS")
             self.mqtt_client.subscribe(f"{self.case}/{host}/READ/#")
             if self.command is not None:
+                self.mqtt_client.subscribe(f"{self.case}/{host}/CALLID")
                 self.mqtt_client.publish(f"{self.case}/{host}/COMM", self.command.encode("utf-8"))
             time.sleep(1)
 
+    def _on_call_id(self, hostname: str, payload: bytes) -> None:
+        try:
+            decoded_payload = payload.decode("utf-8")
+        except UnicodeDecodeError as e:
+            log.error(f"Failed to decode payload for hostname {hostname}: {e}")
+            return
+
+        print(decoded_payload)
+
     def _on_log(self, client: mqtt.Client, userdata: Any, log_level: int, message: str) -> None:
         log.debug(message)
 
@@ -365,6 +377,8 @@ class Broker:
             self._on_read(hostname, tokens, msg.payload)
         elif response == "ID":
             self._on_id(hostname, msg.payload)
+        elif response == "CALLID":
+            self._on_call_id(hostname, msg.payload)
 
     def seek(self, host: str, disk_id: int, offset: int, flength: int, optimization_strategy: int) -> None:
         length = int(flength / self.factor)
@@ -410,16 +424,97 @@ class Broker:
         self.mqtt_client.loop_start()
 
 
-@arg("--mqtt-peers", type=int, dest="peers", help="minimum number of peers to await for first alias")
-@arg("--mqtt-case", dest="case", help="case name (broker will determine if you are allowed to access this data)")
-@arg("--mqtt-port", type=int, dest="port", help="broker connection port")
-@arg("--mqtt-broker", dest="broker", help="broker ip-address")
-@arg("--mqtt-key", dest="key", help="private key file")
-@arg("--mqtt-crt", dest="crt", help="client certificate file")
-@arg("--mqtt-ca", dest="ca", help="certificate authority file")
+def strictly_positive(value: str) -> int:
+    """
+    Validates that the provided value is a strictly positive integer.
+
+    This function is intended to be used as a type for argparse arguments.
+
+    Args:
+        value (str): The value to validate.
+
+    Returns:
+        int: The validated integer value.
+
+    Raises:
+        argparse.ArgumentTypeError: If the value is not a strictly positive integer.
+    """
+    try:
+        strictly_positive_value = int(value)
+        if strictly_positive_value < 1:
+            raise argparse.ArgumentTypeError("Value must be larger than or equal to 1.")
+        return strictly_positive_value
+    except ValueError:
+        raise argparse.ArgumentTypeError(f"Invalid integer value specified: '{value}'")
+
+
+def port(value: str) -> int:
+    """
+    Convert a string value to an integer representing a valid port number.
+
+    This function is intended to be used as a type for argparse arguments.
+
+    Args:
+        value (str): The string representation of the port number.
+    Returns:
+        int: The port number as an integer.
+    Raises:
+        argparse.ArgumentTypeError: If the port number is not an integer or out of the valid range (1-65535).
+    """
+
+    try:
+        port = int(value)
+        if port < 1 or port > 65535:
+            raise argparse.ArgumentTypeError("Port number must be between 1 and 65535.")
+        return port
+    except ValueError:
+        raise argparse.ArgumentTypeError(f"Invalid port number specified: '{value}'")
+
+
+def case(value: str) -> str:
+    """
+    Validates that the given value is a valid case name consisting of
+    alphanumeric characters and underscores only.
+
+    This function is intended to be used as a type for argparse arguments.
+
+    Args:
+        value (str): The case name to validate.
+
+    Returns:
+        str: The validated case name if it matches the required pattern.
+
+    Raises:
+        argparse.ArgumentTypeError: If the case name does not match the required pattern.
+    """
+
+    if re.match(r"^[a-zA-Z0-9_]+$", value):
+        return value
+
+    raise argparse.ArgumentTypeError(f"Invalid case name specified: '{value}'")
+
+
+@arg(
+    "--mqtt-peers",
+    type=strictly_positive,
+    dest="peers",
+    default=1,
+    help="minimum number of peers to await for first alias",
+)
+@arg(
+    "--mqtt-case",
+    type=case,
+    dest="case",
+    help="case name (broker will determine if you are allowed to access this data)",
+)
+@arg("--mqtt-port", type=port, dest="port", default=443, help="broker connection port")
+@arg("--mqtt-broker", default="localhost", dest="broker", help="broker ip-address")
+@arg("--mqtt-key", type=Path, dest="key", required=True, help="private key file")
+@arg("--mqtt-crt", type=Path, dest="crt", required=True, help="client certificate file")
+@arg("--mqtt-ca", type=Path, dest="ca", required=True, help="certificate authority file")
 @arg("--mqtt-command", dest="command", help="direct command to client(s)")
 @arg("--mqtt-diag", action="store_true", dest="diag", help="show MQTT diagnostic information")
-@arg("--mqtt-username", dest="username", help="Username for connection")
+@arg("--mqtt-username", dest="username", default="mqtt-loader", help="Username for connection")
 @arg("--mqtt-password", action="store_true", dest="password", help="Ask for password before connecting")
 class MQTTLoader(Loader):
     """Load remote targets through a broker."""

dissect/target/loaders/proxmox.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from dissect.target import container
+from dissect.target.loader import Loader
+from dissect.target.target import Target
+
+RE_VOLUME_ID = re.compile(r"(?:file=)?([^:]+):([^,]+)")
+
+
+class ProxmoxLoader(Loader):
+    """Loader for Proxmox VM configuration files.
+
+    Proxmox uses volume identifiers in the format of ``storage_id:volume_id``. The ``storage_id`` maps to a
+    storage configuration in ``/etc/pve/storage.cfg``. The ``volume_id`` is the name of the volume within
+    that configuration.
+
+    This loader currently does not support parsing the storage configuration, so it will attempt to open the
+    volume directly from the same directory as the configuration file, or from ``/dev/pve/`` (default LVM config).
+    If the volume is not found, it will log a warning.
+    """
+
+    def __init__(self, path: Path, **kwargs):
+        path = path.resolve()
+        super().__init__(path)
+        self.base_dir = path.parent
+
+    @staticmethod
+    def detect(path: Path) -> bool:
+        if path.suffix.lower() != ".conf":
+            return False
+
+        with path.open("rb") as fh:
+            lines = fh.read(512).split(b"\n")
+            needles = [b"cpu:", b"memory:", b"name:"]
+            return all(any(needle in line for line in lines) for needle in needles)
+
+    def map(self, target: Target) -> None:
+        with self.path.open("rt") as fh:
+            for line in fh:
+                if not (line := line.strip()):
+                    continue
+
+                key, value = line.split(":", 1)
+                value = value.strip()
+
+                if key.startswith(("scsi", "sata", "ide", "virtio")) and key[-1].isdigit():
+                    # https://pve.proxmox.com/wiki/Storage
+                    if match := RE_VOLUME_ID.match(value):
+                        storage_id, volume_id = match.groups()
+
+                        # TODO: parse the storage information from /etc/pve/storage.cfg
+                        # For now, let's try a few assumptions
+                        disk_path = None
+                        if (path := self.base_dir.joinpath(volume_id)).exists():
+                            disk_path = path
+                        elif (path := self.base_dir.joinpath("/dev/pve/").joinpath(volume_id)).exists():
+                            disk_path = path
+
+                        if disk_path:
+                            try:
+                                target.disks.add(container.open(disk_path))
+                            except Exception:
+                                target.log.exception("Failed to open disk: %s", disk_path)
+                        else:
+                            target.log.warning("Unable to find disk: %s:%s", storage_id, volume_id)

dissect/target/loaders/vma.py

@@ -1,4 +1,4 @@
-from dissect.hypervisor import vma
+from dissect.archive import vma
 
 from dissect.target.containers.raw import RawContainer
 from dissect.target.loader import Loader

dissect/target/loaders/xva.py

@@ -1,4 +1,4 @@
-from dissect.hypervisor import xva
+from dissect.archive import xva
 
 from dissect.target.containers.raw import RawContainer
 from dissect.target.loader import Loader

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
@@ -57,17 +57,18 @@ log = logging.getLogger(__name__)
 
 
 class OperatingSystem(StrEnum):
-    LINUX = "linux"
-    WINDOWS = "windows"
-    ESXI = "esxi"
+    ANDROID = "android"
     BSD = "bsd"
+    CITRIX = "citrix-netscaler"
+    ESXI = "esxi"
+    FORTIOS = "fortios"
+    IOS = "ios"
+    LINUX = "linux"
     OSX = "osx"
+    PROXMOX = "proxmox"
     UNIX = "unix"
-    ANDROID = "android"
     VYOS = "vyos"
-    IOS = "ios"
-    FORTIOS = "fortios"
-    CITRIX = "citrix-netscaler"
+    WINDOWS = "windows"
 
 
 def export(*args, **kwargs) -> Callable:
@@ -76,18 +77,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 +175,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 +432,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.
@@ -807,7 +807,7 @@ def load(plugin_desc: PluginDescriptor) -> Type[Plugin]:
         module = importlib.import_module(module)
         return getattr(module, plugin_desc["class"])
     except Exception as e:
-        raise PluginError(f"An exception occurred while trying to load a plugin: {module}", cause=e)
+        raise PluginError(f"An exception occurred while trying to load a plugin: {module}") from e
 
 
 def failed() -> list[dict[str, Any]]:
@@ -1138,6 +1138,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 +1295,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 +1340,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: