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

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/parallels.py

@@ -0,0 +1,68 @@
+from pathlib import Path
+from typing import Iterator
+
+from dissect.target.exceptions import UnsupportedPluginError
+from dissect.target.helpers.fsutil import TargetPath
+from dissect.target.helpers.record import ChildTargetRecord
+from dissect.target.plugin import ChildTargetPlugin
+from dissect.target.target import Target
+
+PARALLELS_USER_PATHS = [
+    "Parallels",
+    "Documents/Parallels",
+    "Library/Group Containers/*.com.parallels.desktop.appstore/Shared/Parallels",
+]
+
+PARALLELS_SYSTEM_PATHS = [
+    "/Users/Shared/Parallels",
+]
+
+
+def find_pvms(target: Target) -> Iterator[TargetPath]:
+    """Finds virtual machines located in default folders on a macOS target.
+
+    Resources:
+        - https://kb.parallels.com/117333
+    """
+    for user_details in target.user_details.all_with_home():
+        for parallels_path in PARALLELS_SYSTEM_PATHS:
+            if (path := target.fs.path(parallels_path)).exists():
+                yield from iter_vms(path)
+
+        for parallels_path in PARALLELS_USER_PATHS:
+            if "*" in parallels_path:
+                start_path, pattern = parallels_path.split("*", 1)
+                for path in user_details.home_path.joinpath(start_path).rglob("*" + pattern):
+                    yield from iter_vms(path)
+            else:
+                if (path := user_details.home_path.joinpath(parallels_path)).exists():
+                    yield from iter_vms(path)
+
+
+def iter_vms(path: Path) -> Iterator[TargetPath]:
+    """Glob for .pvm folders in the provided folder."""
+    for file in path.rglob("*.pvm"):
+        if file.is_dir():
+            yield file
+
+
+class ParallelsChildTargetPlugin(ChildTargetPlugin):
+    """Child target plugin that yields Parallels Desktop VM files."""
+
+    __type__ = "parallels"
+
+    def __init__(self, target: Target):
+        super().__init__(target)
+        self.pvms = list(find_pvms(target))
+
+    def check_compatible(self) -> None:
+        if not self.pvms:
+            raise UnsupportedPluginError("No Parallels pvm file(s) found")
+
+    def list_children(self) -> Iterator[ChildTargetRecord]:
+        for pvm in self.pvms:
+            yield ChildTargetRecord(
+                type=self.__type__,
+                path=pvm,
+                _target=self.target,
+            )

dissect/target/plugins/child/proxmox.py

@@ -0,0 +1,23 @@
+from typing import Iterator
+
+from dissect.target.exceptions import UnsupportedPluginError
+from dissect.target.helpers.record import ChildTargetRecord
+from dissect.target.plugin import ChildTargetPlugin
+
+
+class ProxmoxChildTargetPlugin(ChildTargetPlugin):
+    """Child target plugin that yields from the VM listing."""
+
+    __type__ = "proxmox"
+
+    def check_compatible(self) -> None:
+        if self.target.os != "proxmox":
+            raise UnsupportedPluginError("Not a Proxmox operating system")
+
+    def list_children(self) -> Iterator[ChildTargetRecord]:
+        for vm in self.target.vmlist():
+            yield ChildTargetRecord(
+                type=self.__type__,
+                path=vm.path,
+                _target=self.target,
+            )

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/child/vmware_workstation.py

@@ -1,29 +1,44 @@
+from typing import Iterator
+
 from dissect.target.exceptions import UnsupportedPluginError
+from dissect.target.helpers.fsutil import TargetPath
 from dissect.target.helpers.record import ChildTargetRecord
 from dissect.target.plugin import ChildTargetPlugin
+from dissect.target.target import Target
+
+INVENTORY_PATHS = [
+    # Windows
+    "AppData/Roaming/VMware/inventory.vmls",
+    # Linux
+    ".vmware/inventory.vmls",
+]
+
+
+def find_vm_inventory(target: Target) -> Iterator[TargetPath]:
+    """Search for inventory.vmls files in user home folders.
 
+    Does not support older vmAutoStart.xml or vmInventory.xml formats."""
 
-def find_vm_inventory(target):
     for user_details in target.user_details.all_with_home():
-        inv_file = user_details.home_path.joinpath("AppData/Roaming/VMware/inventory.vmls")
-        if inv_file.exists():
-            yield inv_file
+        for inv_path in INVENTORY_PATHS:
+            if (inv_file := user_details.home_path.joinpath(inv_path)).exists():
+                yield inv_file
 
 
-class WorkstationChildTargetPlugin(ChildTargetPlugin):
+class VmwareWorkstationChildTargetPlugin(ChildTargetPlugin):
     """Child target plugin that yields from VMware Workstation VM inventory."""
 
     __type__ = "vmware_workstation"
 
-    def __init__(self, target):
+    def __init__(self, target: Target):
         super().__init__(target)
         self.inventories = list(find_vm_inventory(target))
 
     def check_compatible(self) -> None:
-        if not len(self.inventories):
+        if not self.inventories:
             raise UnsupportedPluginError("No VMWare inventories found")
 
-    def list_children(self):
+    def list_children(self) -> Iterator[ChildTargetRecord]:
         for inv in self.inventories:
             for line in inv.open("rt"):
                 line = line.strip()

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

@@ -105,6 +105,7 @@ FilesystemMACBRecord = TargetRecordDescriptor(
         ("filesize", "filesize"),
         ("boolean", "resident"),
         ("boolean", "inuse"),
+        ("boolean", "ads"),
         ("string", "volume_uuid"),
     ],
 )
@@ -122,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"}
@@ -151,7 +154,7 @@ class MftPlugin(Plugin):
         "--macb",
         group="fmt",
         action="store_true",
-        help="compacts the MFT entry timestamps into aggregated records with MACB bitfield",
+        help="compacts MFT timestamps into MACB bitfield (format: MACB[standard|ads]/MACB[filename])",
     )
     def mft(
         self, compact: bool = False, fs: int | None = None, start: int = 0, end: int = -1, macb: bool = False
@@ -342,12 +345,13 @@ def macb_aggr(records: list[Record]) -> Iterator[Record]:
     for record in records:
         found = False
 
-        offset_std = int(record._desc.name == "filesystem/ntfs/mft/std") * 5
-        offset_ads = (int(record.ads) * 10) if offset_std == 0 else 0
+        offset = 0
+        if not getattr(record, "ads", False):
+            offset = int(record._desc.name == "filesystem/ntfs/mft/filename") * 5
 
-        field = "MACB".find(record.ts_type) + offset_std + offset_ads
+        field = "MACB".find(record.ts_type) + offset
         for macb in macbs:
-            if macb.ts == record.ts:
+            if macb.ts == record.ts and macb.path == record.path:
                 macb.macb = macb_set(macb.macb, field, record.ts_type)
                 found = True
                 break
@@ -356,7 +360,7 @@ def macb_aggr(records: list[Record]) -> Iterator[Record]:
             continue
 
         macb = FilesystemMACBRecord.init_from_record(record)
-        macb.macb = "..../..../...."
+        macb.macb = "..../...."
         macb.macb = macb_set(macb.macb, field, record.ts_type)
 
         macbs.append(macb)

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.

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

@@ -1,6 +1,8 @@
+import json
+
 from dissect.target.helpers.docs import INDENT_STEP, get_docstring
 from dissect.target.loader import LOADERS_BY_SCHEME
-from dissect.target.plugin import Plugin, export
+from dissect.target.plugin import Plugin, arg, export
 
 
 class LoaderListPlugin(Plugin):
@@ -10,7 +12,12 @@ class LoaderListPlugin(Plugin):
         pass
 
     @export(output="none")
-    def loaders(self):
+    # NOTE: We would prefer to re-use arguments across plugins from argparse in query.py, but that is not possible yet.
+    # For now we use --as-json, but in the future this should be changed to inherit --json from target-query.
+    # https://github.com/fox-it/dissect.target/pull/841
+    # https://github.com/fox-it/dissect.target/issues/889
+    @arg("--as-json", dest="as_json", action="store_true")
+    def loaders(self, as_json: bool = False) -> None:
         """List the available loaders."""
 
         loaders_info = {}
@@ -21,6 +28,12 @@ class LoaderListPlugin(Plugin):
             except ImportError:
                 continue
 
-        print("Available loaders:")
-        for loader_name, loader_description in sorted(loaders_info.items()):
-            print(f"{INDENT_STEP}{loader_name} - {loader_description}")
+        loaders = sorted(loaders_info.items())
+
+        if as_json:
+            print(json.dumps([{"name": name, "description": desc} for name, desc in loaders]), end="")
+
+        else:
+            print("Available loaders:")
+            for loader_name, loader_description in loaders:
+                print(f"{INDENT_STEP}{loader_name} - {loader_description}")

dissect/target/plugins/general/network.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 from typing import Any, Iterator, Union
 
 from flow.record.fieldtypes.net import IPAddress, IPNetwork
+from flow.record.fieldtypes.net.ipv4 import Address, addr_long, addr_str, mask_to_bits
 
 from dissect.target.helpers.record import (
     MacInterfaceRecord,
@@ -16,6 +17,8 @@ InterfaceRecord = Union[UnixInterfaceRecord, WindowsInterfaceRecord, MacInterfac
 
 
 class NetworkPlugin(Plugin):
+    """Generic implementation for network interfaces plugin."""
+
     __namespace__ = "network"
 
     def __init__(self, target: Target):
@@ -40,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())
@@ -48,19 +52,23 @@ class NetworkPlugin(Plugin):
 
     @export
     def ips(self) -> list[IPAddress]:
-        return list(self._get_record_type("ip"))
+        """Return IP addresses as list of :class:`IPAddress`."""
+        return list(set(self._get_record_type("ip")))
 
     @export
     def gateways(self) -> list[IPAddress]:
-        return list(self._get_record_type("gateway"))
+        """Return gateways as list of :class:`IPAddress`."""
+        return list(set(self._get_record_type("gateway")))
 
     @export
     def macs(self) -> list[str]:
-        return list(self._get_record_type("mac"))
+        """Return MAC addresses as list of :class:`str`."""
+        return list(set(self._get_record_type("mac")))
 
     @export
-    def dns(self) -> list[str]:
-        return list(self._get_record_type("dns"))
+    def dns(self) -> list[str | IPAddress]:
+        """Return DNS addresses as list of :class:`str`."""
+        return list(set(self._get_record_type("dns")))
 
     @internal
     def with_ip(self, ip_addr: str) -> Iterator[InterfaceRecord]:
@@ -80,3 +88,10 @@ class NetworkPlugin(Plugin):
         for interface in self.interfaces():
             if any(ip_addr in cidr for ip_addr in interface.ip):
                 yield interface
+
+    def calculate_network(self, ips: int | Address, subnets: int | Address) -> Iterator[str]:
+        for ip, subnet_mask in zip(ips, subnets):
+            subnet_mask_int = addr_long(subnet_mask)
+            cidr = mask_to_bits(subnet_mask_int)
+            network_address = addr_str(addr_long(ip) & subnet_mask_int)
+            yield f"{network_address}/{cidr}"

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

@@ -1,5 +1,8 @@
+from __future__ import annotations
+
+import json
 import textwrap
-from typing import Dict, List, Type, Union
+from typing import Iterator, Type
 
 from dissect.target import plugin
 from dissect.target.helpers.docs import INDENT_STEP, get_plugin_overview
@@ -23,7 +26,8 @@ def categorize_plugins(plugins_selection: list[dict] = None) -> dict:
     return output_dict
 
 
-def get_exported_plugins():
+def get_exported_plugins() -> list:
+    """Returns list of exported plugins."""
     return [p for p in plugin.plugins() if len(p["exports"])]
 
 
@@ -50,10 +54,10 @@ def update_dict_recursive(source_dict: dict, updated_dict: dict) -> dict:
 
 
 def output_plugin_description_recursive(
-    structure_dict: Union[Dict, Plugin],
+    structure_dict: dict | Plugin,
     print_docs: bool,
-    indentation_step=0,
-) -> List[str]:
+    indentation_step: int = 0,
+) -> list[str]:
     """Create plugin overview with identations."""
 
     if isinstance(structure_dict, type) and issubclass(structure_dict, Plugin):
@@ -78,10 +82,10 @@ def get_plugin_description(
 
 
 def get_description_dict(
-    structure_dict: Dict,
+    structure_dict: dict,
     print_docs: bool,
     indentation_step: int,
-) -> List[str]:
+) -> list[str]:
     """Returns a list of indented descriptions."""
 
     output_descriptions = []
@@ -98,13 +102,24 @@ 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:
-        categorized_plugins = dict(sorted(categorize_plugins(plugins).items()))
+    # NOTE: We would prefer to re-use arguments across plugins from argparse in query.py, but that is not possible yet.
+    # For now we use --as-json, but in the future this should be changed to inherit --json from target-query.
+    # https://github.com/fox-it/dissect.target/pull/841
+    # https://github.com/fox-it/dissect.target/issues/889
+    @arg("--as-json", dest="as_json", action="store_true")
+    def plugins(self, plugins: list[Plugin] = None, print_docs: bool = False, as_json: bool = False) -> None:
+        """Print all available plugins."""
+
+        dict_plugins = list({p.path: p.plugin_desc for p in plugins}.values())
+        categorized_plugins = dict(sorted(categorize_plugins(dict_plugins).items()))
+
         plugin_descriptions = output_plugin_description_recursive(categorized_plugins, print_docs)
 
         plugins_list = textwrap.indent(
@@ -138,4 +153,32 @@ class PluginListPlugin(Plugin):
             "Failed to load:",
             failed_list,
         ]
-        print("\n".join(output_lines))
+
+        if as_json:
+            out = {"loaded": list(generate_plugins_json(plugins))}
+
+            if failed_plugins := plugin.failed():
+                out["failed"] = [
+                    {"module": p["module"], "stacktrace": "".join(p["stacktrace"])} for p in failed_plugins
+                ]
+
+            print(json.dumps(out), end="")
+
+        else:
+            print("\n".join(output_lines))
+
+
+def generate_plugins_json(plugins: list[Plugin]) -> Iterator[dict]:
+    """Generates JSON output of a list of :class:`Plugin`s."""
+
+    for p in plugins:
+        func = getattr(p.class_object, p.method_name)
+        description = getattr(func, "__doc__", None)
+        summary = description.split("\n\n", 1)[0].strip() if description else None
+
+        yield {
+            "name": p.name,
+            "output": p.output_type,
+            "description": summary,
+            "path": p.path,
+        }