dissect.target 3.20.dev9__tar.gz → 3.20.dev11__tar.gz

{dissect_target-3.20.dev9/dissect.target.egg-info → dissect_target-3.20.dev11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: dissect.target
-Version: 3.20.dev9
+Version: 3.20.dev11
 Summary: This module ties all other Dissect modules together, it provides a programming API and command line tools which allow easy access to various data sources inside disk images or file collections (a.k.a. targets)
 Author-email: Dissect Team <dissect@fox-it.com>
 License: Affero General Public License v3

{dissect_target-3.20.dev9 → dissect_target-3.20.dev11}/dissect/target/helpers/record.py

@@ -180,7 +180,8 @@ MacInterfaceRecord = TargetRecordDescriptor(
     [
         *COMMON_INTERFACE_ELEMENTS,
         ("varint", "vlan"),
-        ("string", "proxy"),
+        ("net.ipnetwork[]", "network"),
         ("varint", "interface_service_order"),
+        ("boolean", "dhcp"),
     ],
 )

{dissect_target-3.20.dev9 → dissect_target-3.20.dev11}/dissect/target/plugins/os/unix/bsd/osx/_os.py

@@ -40,24 +40,8 @@ class MacPlugin(BsdPlugin):
     @export(property=True)
     def ips(self) -> Optional[list[str]]:
         ips = set()
-
-        # Static configured IP-addresses
-        if (preferences := self.target.fs.path(self.SYSTEM)).exists():
-            network = plistlib.load(preferences.open()).get("NetworkServices")
-
-            for interface in network.values():
-                for addresses in [interface.get("IPv4"), interface.get("IPv6")]:
-                    ips.update(addresses.get("Addresses", []))
-
-        # IP-addresses configured by DHCP
-        if (dhcp := self.target.fs.path("/private/var/db/dhcpclient/leases")).exists():
-            for lease in dhcp.iterdir():
-                if lease.is_file():
-                    lease = plistlib.load(lease.open())
-
-                    if ip := lease.get("IPAddress"):
-                        ips.add(ip)
-
+        for ip in self.target.network.ips():
+            ips.add(str(ip))
         return list(ips)
 
     @export(property=True)

dissect_target-3.20.dev11/dissect/target/plugins/os/unix/bsd/osx/network.py

@@ -0,0 +1,90 @@
+from __future__ import annotations
+
+import plistlib
+from functools import cache, lru_cache
+from typing import Iterator
+
+from dissect.target.helpers.record import MacInterfaceRecord
+from dissect.target.plugins.general.network import NetworkPlugin
+from dissect.target.target import Target
+
+
+class MacNetworkPlugin(NetworkPlugin):
+    def __init__(self, target: Target):
+        super().__init__(target)
+        self._plistnetwork = cache(self._plistnetwork)
+        self._plistlease = lru_cache(32)(self._plistlease)
+
+    def _plistlease(self, devname: str) -> dict:
+        for lease in self.target.fs.glob_ext(f"/private/var/db/dhcpclient/leases/{devname}*"):
+            return plistlib.load(lease.open())
+        return {}
+
+    def _plistnetwork(self) -> dict:
+        if (preferences := self.target.fs.path("/Library/Preferences/SystemConfiguration/preferences.plist")).exists():
+            return plistlib.load(preferences.open())
+
+    def _interfaces(self) -> Iterator[MacInterfaceRecord]:
+        plistnetwork = self._plistnetwork()
+        current_set = plistnetwork.get("CurrentSet")
+        sets = plistnetwork.get("Sets", {})
+        for name, _set in sets.items():
+            if f"/Sets/{name}" == current_set:
+                item = _set
+                for key in ["Network", "Global", "IPv4", "ServiceOrder"]:
+                    item = item.get(key, {})
+                service_order = item
+                break
+
+        network = plistnetwork.get("NetworkServices", {})
+        vlans = plistnetwork.get("VirtualNetworkInterfaces", {}).get("VLAN", {})
+
+        vlan_lookup = {key: vlan.get("Tag") for key, vlan in vlans.items()}
+
+        for _id, interface in network.items():
+            dns = set()
+            gateways = set()
+            ips = set()
+            device = interface.get("Interface", {})
+            name = device.get("DeviceName")
+            _type = device.get("Type")
+            vlan = vlan_lookup.get(name)
+            dhcp = False
+            subnetmask = []
+            network = []
+            interface_service_order = service_order.index(_id) if _id in service_order else None
+            try:
+                for addr in interface.get("DNS", {}).get("ServerAddresses", {}):
+                    dns.add(addr)
+                for addresses in [interface.get("IPv4", {}), interface.get("IPv6", {})]:
+                    subnetmask += filter(lambda mask: mask != "", addresses.get("SubnetMasks", []))
+                    if router := addresses.get("Router"):
+                        gateways.add(router)
+                    if addresses.get("ConfigMethod", "") == "DHCP":
+                        ips.add(self._plistlease(name).get("IPAddress"))
+                        dhcp = True
+                    else:
+                        for addr in addresses.get("Addresses", []):
+                            ips.add(addr)
+
+                if subnetmask:
+                    network = self.calculate_network(ips, subnetmask)
+
+                yield MacInterfaceRecord(
+                    name=name,
+                    type=_type,
+                    enabled=not interface.get("__INACTIVE__", False),
+                    dns=list(dns),
+                    ip=list(ips),
+                    gateway=list(gateways),
+                    source="NetworkServices",
+                    vlan=vlan,
+                    network=network,
+                    interface_service_order=interface_service_order,
+                    dhcp=dhcp,
+                    _target=self.target,
+                )
+
+            except Exception as e:
+                self.target.log.warning("Error reading configuration for network device %s: %s", name, e)
+                continue

dissect_target-3.20.dev11/dissect/target/plugins/os/unix/trash.py

@@ -0,0 +1,132 @@
+from typing import Iterator
+
+from dissect.target.exceptions import UnsupportedPluginError
+from dissect.target.helpers import configutil
+from dissect.target.helpers.descriptor_extensions import UserRecordDescriptorExtension
+from dissect.target.helpers.fsutil import TargetPath
+from dissect.target.helpers.record import create_extended_descriptor
+from dissect.target.plugin import Plugin, alias, export
+from dissect.target.plugins.general.users import UserDetails
+from dissect.target.target import Target
+
+TrashRecord = create_extended_descriptor([UserRecordDescriptorExtension])(
+    "linux/filesystem/recyclebin",
+    [
+        ("datetime", "ts"),
+        ("path", "path"),
+        ("filesize", "filesize"),
+        ("path", "deleted_path"),
+        ("path", "source"),
+    ],
+)
+
+
+class GnomeTrashPlugin(Plugin):
+    """Linux GNOME Trash plugin."""
+
+    PATHS = [
+        # Default $XDG_DATA_HOME/Trash
+        ".local/share/Trash",
+    ]
+
+    def __init__(self, target: Target):
+        super().__init__(target)
+        self.trashes = list(self._garbage_collector())
+
+    def _garbage_collector(self) -> Iterator[tuple[UserDetails, TargetPath]]:
+        """it aint much, but its honest work"""
+        for user_details in self.target.user_details.all_with_home():
+            for trash_path in self.PATHS:
+                if (path := user_details.home_path.joinpath(trash_path)).exists():
+                    yield user_details, path
+
+    def check_compatible(self) -> None:
+        if not self.trashes:
+            raise UnsupportedPluginError("No Trash folder(s) found")
+
+    @export(record=TrashRecord)
+    @alias(name="recyclebin")
+    def trash(self) -> Iterator[TrashRecord]:
+        """Yield deleted files from GNOME Trash folders.
+
+        Recovers deleted files and artifacts from ``$HOME/.local/share/Trash``.
+        Probably also works with other desktop interfaces as long as they follow the Trash specification from FreeDesktop.
+
+        Currently does not parse media trash locations such as ``/media/$Label/.Trash-1000/*``.
+
+        Resources:
+            - https://specifications.freedesktop.org/trash-spec/latest/
+            - https://github.com/GNOME/glib/blob/main/gio/glocalfile.c
+            - https://specifications.freedesktop.org/basedir-spec/latest/
+
+        Yields ``TrashRecord``s with the following fields:
+
+        .. code-block:: text
+
+            ts           (datetime): timestamp when the file was deleted or for expunged files when it could not be permanently deleted
+            path         (path):     path where the file was located before it was deleted
+            filesize     (filesize): size in bytes of the deleted file
+            deleted_path (path):     path to the current location of the deleted file
+            source       (path):     path to the .trashinfo file
+        """  # noqa: E501
+
+        for user_details, trash in self.trashes:
+            for trash_info_file in trash.glob("info/*.trashinfo"):
+                trash_info = configutil.parse(trash_info_file, hint="ini").get("Trash Info", {})
+                original_path = self.target.fs.path(trash_info.get("Path", ""))
+
+                # We use the basename of the .trashinfo file and not the Path variable inside the
+                # ini file. This way we can keep duplicate basenames of trashed files separated correctly.
+                deleted_path = trash / "files" / trash_info_file.name.replace(".trashinfo", "")
+
+                if deleted_path.exists():
+                    deleted_files = [deleted_path]
+
+                    if deleted_path.is_dir():
+                        for child in deleted_path.rglob("*"):
+                            deleted_files.append(child)
+
+                    for file in deleted_files:
+                        # NOTE: We currently do not 'fix' the original_path of files inside deleted directories.
+                        # This would require guessing where the parent folder starts, which is impossible without
+                        # making assumptions.
+                        yield TrashRecord(
+                            ts=trash_info.get("DeletionDate", 0),
+                            path=original_path,
+                            filesize=file.lstat().st_size if file.is_file() else None,
+                            deleted_path=file,
+                            source=trash_info_file,
+                            _user=user_details.user,
+                            _target=self.target,
+                        )
+
+                # We cannot determine if the deleted entry is a directory since the path does
+                # not exist at $TRASH/files, so we work with what we have instead.
+                else:
+                    self.target.log.warning(f"Expected trashed file(s) at {deleted_path}")
+                    yield TrashRecord(
+                        ts=trash_info.get("DeletionDate", 0),
+                        path=original_path,
+                        filesize=0,
+                        deleted_path=deleted_path,
+                        source=trash_info_file,
+                        _user=user_details.user,
+                        _target=self.target,
+                    )
+
+            # We also iterate expunged folders, they can contain files that could not be
+            # deleted when the user pressed the "empty trash" button in the file manager.
+            # Resources:
+            #   - https://gitlab.gnome.org/GNOME/glib/-/issues/1665
+            #   - https://bugs.launchpad.net/ubuntu/+source/nautilus/+bug/422012
+            for item in (trash / "expunged").rglob("*/*"):
+                stat = item.lstat()
+                yield TrashRecord(
+                    ts=stat.st_mtime,  # NOTE: This is the timestamp at which the file failed to delete
+                    path=None,  # We do not know the original file path
+                    filesize=stat.st_size if item.is_file() else None,
+                    deleted_path=item,
+                    source=trash / "expunged",
+                    _user=user_details.user,
+                    _target=self.target,
+                )

{dissect_target-3.20.dev9 → dissect_target-3.20.dev11}/dissect/target/tools/utils.py

@@ -90,6 +90,10 @@ def generate_argparse_for_unbound_method(
         raise ValueError(f"Value `{method}` is not an unbound plugin method")
 
     desc = method.__doc__ or docs.get_func_description(method, with_docstrings=True)
+
+    if "\n" in desc:
+        desc = inspect.cleandoc(desc)
+
     help_formatter = argparse.RawDescriptionHelpFormatter
     parser = argparse.ArgumentParser(description=desc, formatter_class=help_formatter, conflict_handler="resolve")
 

{dissect_target-3.20.dev9 → dissect_target-3.20.dev11/dissect.target.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: dissect.target
-Version: 3.20.dev9
+Version: 3.20.dev11
 Summary: This module ties all other Dissect modules together, it provides a programming API and command line tools which allow easy access to various data sources inside disk images or file collections (a.k.a. targets)
 Author-email: Dissect Team <dissect@fox-it.com>
 License: Affero General Public License v3

{dissect_target-3.20.dev9 → dissect_target-3.20.dev11}/dissect.target.egg-info/SOURCES.txt

@@ -210,6 +210,7 @@ dissect/target/plugins/os/unix/history.py
 dissect/target/plugins/os/unix/locale.py
 dissect/target/plugins/os/unix/packagemanager.py
 dissect/target/plugins/os/unix/shadow.py
+dissect/target/plugins/os/unix/trash.py
 dissect/target/plugins/os/unix/bsd/__init__.py
 dissect/target/plugins/os/unix/bsd/_os.py
 dissect/target/plugins/os/unix/bsd/citrix/__init__.py
@@ -223,6 +224,7 @@ dissect/target/plugins/os/unix/bsd/openbsd/__init__.py
 dissect/target/plugins/os/unix/bsd/openbsd/_os.py
 dissect/target/plugins/os/unix/bsd/osx/__init__.py
 dissect/target/plugins/os/unix/bsd/osx/_os.py
+dissect/target/plugins/os/unix/bsd/osx/network.py
 dissect/target/plugins/os/unix/bsd/osx/user.py
 dissect/target/plugins/os/unix/esxi/__init__.py
 dissect/target/plugins/os/unix/esxi/_os.py
@@ -522,6 +524,7 @@ tests/plugins/os/unix/test_journal.py
 tests/plugins/os/unix/test_locale.py
 tests/plugins/os/unix/test_packagemanager.py
 tests/plugins/os/unix/test_shadow.py
+tests/plugins/os/unix/test_trash.py
 tests/plugins/os/unix/test_users.py
 tests/plugins/os/unix/test_version.py
 tests/plugins/os/unix/bsd/__init__.py
@@ -530,6 +533,7 @@ tests/plugins/os/unix/bsd/citrix/test__os.py
 tests/plugins/os/unix/bsd/citrix/test_history.py
 tests/plugins/os/unix/bsd/osx/__init__.py
 tests/plugins/os/unix/bsd/osx/test__os.py
+tests/plugins/os/unix/bsd/osx/test_network.py
 tests/plugins/os/unix/bsd/osx/test_user.py
 tests/plugins/os/unix/esxi/__init__.py
 tests/plugins/os/unix/esxi/test__os.py

dissect_target-3.20.dev11/tests/plugins/os/unix/bsd/osx/test_network.py

@@ -0,0 +1,172 @@
+from typing import Iterator
+from unittest import mock
+
+import pytest
+
+from dissect.target.plugins.os.unix.bsd.osx.network import MacNetworkPlugin
+from dissect.target.target import Target
+
+
+@pytest.fixture
+def almost_empty_plist() -> Iterator[dict]:
+    yield {"CurrentSet": {}}
+
+
+@pytest.fixture
+def fake_plist() -> Iterator[dict]:
+    yield {
+        "CurrentSet": "/Sets/1",
+        "NetworkServices": {
+            "1": {
+                "DNS": {"ServerAddresses": ["8.8.8.8"]},
+                "IPv4": {
+                    "Addresses": ["192.122.13.34"],
+                    "Router": "8.8.8.8",
+                },
+                "Interface": {
+                    "DeviceName": "en0",
+                    "Type": "Ethernet",
+                },
+            },
+        },
+        "Sets": {
+            "1": {
+                "Network": {
+                    "Global": {"IPv4": {"ServiceOrder": ["1"]}},
+                },
+            },
+        },
+        "VirtualNetworkInterfaces": {"VLAN": {"vlan0": {"Tag": 2}}},
+    }
+
+
+@pytest.fixture
+def vlan0(fake_plist: dict) -> Iterator[dict]:
+    fake_plist["NetworkServices"]["1"]["Interface"].update({"DeviceName": "vlan0"})
+    yield fake_plist
+
+
+@pytest.fixture
+def inactive(fake_plist: dict) -> Iterator[dict]:
+    fake_plist["NetworkServices"]["1"].update({"__INACTIVE__": True})
+    yield fake_plist
+
+
+@pytest.fixture
+def ipv6(fake_plist: dict) -> Iterator[dict]:
+    del fake_plist["NetworkServices"]["1"]["IPv4"]
+    fake_plist["NetworkServices"]["1"]["IPv6"] = {"Addresses": ["::1"]}
+    yield fake_plist
+
+
+@pytest.fixture
+def reorder(fake_plist: dict) -> Iterator[dict]:
+    fake_plist["Sets"]["1"]["Network"]["Global"]["IPv4"]["ServiceOrder"] = ["2", "1"]
+    yield fake_plist
+
+
+@pytest.fixture
+def double(fake_plist: dict) -> Iterator[dict]:
+    fake_plist["NetworkServices"]["2"] = fake_plist["NetworkServices"]["1"]
+    yield fake_plist
+
+
+@pytest.fixture
+def dhcp(fake_plist: dict) -> Iterator[dict]:
+    fake_plist["NetworkServices"]["1"]["IPv4"].update({"ConfigMethod": "DHCP"})
+    yield fake_plist
+
+
+@pytest.mark.parametrize(
+    "lease,netinfo_param,expected,count",
+    [
+        ({"IPAddress": None}, "almost_empty_plist", [], 0),
+        (
+            {},
+            "fake_plist",
+            [
+                (0, "hostname", ["dummys Mac"]),
+                (0, "domain", ["None"]),
+                (0, "name", ["en0"]),
+                (0, "type", ["Ethernet"]),
+                (0, "ip", ["192.122.13.34"]),
+                (0, "gateway", ["8.8.8.8"]),
+                (0, "dns", ["8.8.8.8"]),
+                (0, "vlan", ["None"]),
+                (0, "enabled", ["True"]),
+                (0, "interface_service_order", ["0"]),
+                (0, "mac", ["None"]),
+                (0, "vlan", ["None"]),
+            ],
+            1,
+        ),
+        (
+            {"IPAddress": "10.0.0.2"},
+            "dhcp",
+            [
+                (0, "ip", sorted(["10.0.0.2"])),
+            ],
+            1,
+        ),
+        (
+            {},
+            "vlan0",
+            [
+                (0, "vlan", ["2"]),
+            ],
+            1,
+        ),
+        (
+            {},
+            "inactive",
+            [
+                (0, "enabled", ["False"]),
+            ],
+            1,
+        ),
+        (
+            {},
+            "ipv6",
+            [
+                (0, "ip", ["::1"]),
+            ],
+            1,
+        ),
+        (
+            {},
+            "reorder",
+            [
+                (0, "interface_service_order", ["1"]),
+            ],
+            1,
+        ),
+        (
+            {},
+            "double",
+            [
+                (0, "enabled", ["True"]),
+                (1, "enabled", ["True"]),
+            ],
+            2,
+        ),
+    ],
+)
+def test_macos_network(
+    target_osx: Target, lease: dict, netinfo_param: str, expected: dict, count: int, request: pytest.FixtureRequest
+) -> None:
+    plistnetwork = request.getfixturevalue(netinfo_param)
+    with mock.patch(
+        "dissect.target.plugins.os.unix.bsd.osx.network.MacNetworkPlugin._plistlease", return_value=lease
+    ), mock.patch(
+        "dissect.target.plugins.os.unix.bsd.osx.network.MacNetworkPlugin._plistnetwork", return_value=plistnetwork
+    ):
+        network = MacNetworkPlugin(target_osx)
+
+    interfaces = list(network.interfaces())
+    assert len(interfaces) == count
+    for index, key, value in expected:
+        attr = getattr(interfaces[index], key)
+        if not isinstance(attr, list):
+            attr = [attr]
+        attr = list(sorted(map(str, attr)))
+        assert attr == value

dissect_target-3.20.dev11/tests/plugins/os/unix/test_trash.py

@@ -0,0 +1,78 @@
+from datetime import datetime, timezone
+from io import BytesIO
+
+from dissect.target.filesystem import VirtualFilesystem
+from dissect.target.plugins.os.unix._os import UnixPlugin
+from dissect.target.plugins.os.unix.trash import GnomeTrashPlugin
+from dissect.target.target import Target
+from tests._utils import absolute_path
+
+
+def test_gnome_trash(target_unix_users: Target, fs_unix: VirtualFilesystem) -> None:
+    """test if GNOME Trash plugin finds all deleted files including recursively deleted folders and expunged items."""
+
+    fs_unix.map_file_fh("etc/hostname", BytesIO(b"hostname"))
+    fs_unix.map_dir("home/user/.local/share/Trash", absolute_path("_data/plugins/os/unix/trash"))
+    target_unix_users.add_plugin(UnixPlugin)
+    target_unix_users.add_plugin(GnomeTrashPlugin)
+
+    # test if the plugin and its alias were registered
+    assert target_unix_users.has_function("trash")
+    assert target_unix_users.has_function("recyclebin")
+
+    results = sorted(list(target_unix_users.trash()), key=lambda r: r.source)
+    assert len(results) == 11
+
+    # test if we find a deleted file
+    assert results[2].ts == datetime(2024, 12, 31, 13, 37, 0, tzinfo=timezone.utc)
+    assert results[2].path == "/home/user/Documents/some-location/another-file.bin"
+    assert results[2].filesize == 369
+    assert results[2].deleted_path == "/home/user/.local/share/Trash/files/another-file.bin"
+    assert results[2].source == "/home/user/.local/share/Trash/info/another-file.bin.trashinfo"
+    assert results[2].username == "user"
+    assert results[2].hostname == "hostname"
+
+    # test if we still find a file by just the .trashinfo file and no entry in the $Trash/files folder
+    assert results[6].path == "/home/user/Downloads/missing-file.txt"
+    assert results[6].filesize == 0
+    assert results[6].source == "/home/user/.local/share/Trash/info/missing-file.txt.trashinfo"
+
+    # test if we find a deleted directory
+    assert results[7].ts == datetime(2024, 12, 31, 1, 2, 3, tzinfo=timezone.utc)
+    assert results[7].path == "/home/user/Downloads/some-dir"
+    assert results[7].filesize is None
+    assert results[7].deleted_path == "/home/user/.local/share/Trash/files/some-dir"
+    assert results[7].source == "/home/user/.local/share/Trash/info/some-dir.trashinfo"
+    assert results[7].username == "user"
+    assert results[7].hostname == "hostname"
+
+    # test if we find files nested inside a deleted directory
+    deleted_paths = [r.deleted_path for r in results]
+    assert deleted_paths == [
+        "/home/user/.local/share/Trash/expunged/123456789/some-dir",
+        "/home/user/.local/share/Trash/expunged/123456789/some-dir/some-file.txt",
+        "/home/user/.local/share/Trash/files/another-file.bin",
+        "/home/user/.local/share/Trash/files/example.jpg",
+        "/home/user/.local/share/Trash/files/file.txt.2",
+        "/home/user/.local/share/Trash/files/file.txt",
+        "/home/user/.local/share/Trash/files/missing-file.txt",
+        "/home/user/.local/share/Trash/files/some-dir",
+        "/home/user/.local/share/Trash/files/some-dir/another-dir",
+        "/home/user/.local/share/Trash/files/some-dir/some-file.txt",
+        "/home/user/.local/share/Trash/files/some-dir/another-dir/another-file.txt",
+    ]
+
+    # test if we find two deleted files that had the same basename
+    assert results[4].path == "/home/user/Desktop/file.txt"
+    assert results[4].deleted_path == "/home/user/.local/share/Trash/files/file.txt.2"
+    assert results[4].filesize == 10
+    assert results[5].path == "/home/user/Documents/file.txt"
+    assert results[5].deleted_path == "/home/user/.local/share/Trash/files/file.txt"
+    assert results[5].filesize == 20
+
+    # test if we find expunged files
+    assert results[0].path is None
+    assert results[0].deleted_path == "/home/user/.local/share/Trash/expunged/123456789/some-dir"
+    assert results[1].path is None
+    assert results[1].deleted_path == "/home/user/.local/share/Trash/expunged/123456789/some-dir/some-file.txt"
+    assert results[1].filesize == 79