dissect.target 3.23.dev45__tar.gz → 3.23.dev46__tar.gz

{dissect_target-3.23.dev45 → dissect_target-3.23.dev46}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dissect.target
-Version: 3.23.dev45
+Version: 3.23.dev46
 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.23.dev46/dissect/target/helpers/network.py

@@ -0,0 +1,178 @@
+from __future__ import annotations
+
+from enum import IntEnum
+
+
+class IANAProtocol(IntEnum):
+    """Enum of IANA Protocol numbers.
+
+    Resources:
+        - https://www.iana.org/assignments/protocol-numbers/protocol-numbers.xhtml
+    """
+
+    HOPOPT = 0
+    ICMP = 1
+    IGMP = 2
+    GGP = 3
+    IPV4 = 4
+    ST = 5
+    TCP = 6
+    CBT = 7
+    EGP = 8
+    IGP = 9
+    BBN_RCC_MON = 10
+    NVP_II = 11
+    PUP = 12
+    ARGUS = 13
+    EMCON = 14
+    XNET = 15
+    CHAOS = 16
+    UDP = 17
+    MUX = 18
+    DCN_MEAS = 19
+    HMP = 20
+    PRM = 21
+    XNS_IDP = 22
+    TRUNK_1 = 23
+    TRUNK_2 = 24
+    LEAF_1 = 25
+    LEAF_2 = 26
+    RDP = 27
+    IRTP = 28
+    ISO_TP4 = 29
+    NETBLT = 30
+    MFE_NSP = 31
+    MERIT_INP = 32
+    DCCP = 33
+    _3PC = 34
+    IDPR = 35
+    XTP = 36
+    DDP = 37
+    IDPR_CMTP = 38
+    TPPP = 39
+    IL = 40
+    IPV6 = 41
+    SDRP = 42
+    IPV6_ROUTE = 43
+    IPV6_FRAG = 44
+    IDRP = 45
+    RSVP = 46
+    GRE = 47
+    DSR = 48
+    BNA = 49
+    ESP = 50
+    AH = 51
+    I_NLSP = 52
+    SWIPE = 53
+    NARP = 54
+    MIN_IPV4 = 55
+    TLSP = 56
+    SKIP = 57
+    IPV6_ICMP = 58
+    IPV6_NONXT = 59
+    IPV6_OPTS = 60
+    ANY_HOST_INTERNAL_PROTOCOL = 61
+    CFTP = 62
+    ANY_LOCAL_NETWORK = 63
+    SAT_EXPAK = 64
+    KRYPTOLAN = 65
+    RVD = 66
+    IPPC = 67
+    ANY_DISTRIBUTED_FILE_SYSTEM = 68
+    SAT_MON = 69
+    VISA = 70
+    IPCV = 71
+    CPNX = 72
+    CPHB = 73
+    WSN = 74
+    PVP = 75
+    BR_SAT_MON = 76
+    SUN_ND = 77
+    WB_MON = 78
+    WB_EXPAK = 79
+    ISO_IP = 80
+    VMTP = 81
+    SECURE_VMTP = 82
+    VINES = 83
+    IPTM = 84
+    NSFNET_IGP = 85
+    DGP = 86
+    TCF = 87
+    EIGRP = 88
+    OSPFIGP = 89
+    SPRITE_RPC = 90
+    LARP = 91
+    MTP = 92
+    AX_25 = 93
+    IPIP = 94
+    MICP = 95
+    SCC_SP = 96
+    ETHERIP = 97
+    ENCAP = 98
+    ANY_PRIVATE_ENCRYPTION_SCHEME = 99
+    GMTP = 100
+    IFMP = 101
+    PNNI = 102
+    PIM = 103
+    ARIS = 104
+    SCPS = 105
+    QNX = 106
+    AN = 107
+    IPCOMP = 108
+    SNP = 109
+    COMPAQ_PEER = 110
+    IPX_IN_IP = 111
+    VRRP = 112
+    PGM = 113
+    ANY_0_HOP_PROTOCOL = 114
+    L2TP = 115
+    DDX = 116
+    IATP = 117
+    STP = 118
+    SRP = 119
+    UTI = 120
+    SMP = 121
+    SM = 122
+    PTP = 123
+    ISIS_OVER_IPV4 = 124
+    FIRE = 125
+    CRTP = 126
+    CRUDP = 127
+    SSCOPMCE = 128
+    IPLT = 129
+    SPS = 130
+    PIPE = 131
+    SCTP = 132
+    FC = 133
+    RSVP_E2E_IGNORE = 134
+    MOBILITY_HEADER = 135
+    UDP_LITE = 136
+    MPLS_IN_IP = 137
+    MANET = 138
+    HIP = 139
+    SHIM6 = 140
+    WESP = 141
+    ROHC = 142
+    ETHERNET = 143
+    AGGFRAG = 144
+    NSH = 145
+    HOMA = 146
+    BIT_EMU = 147
+    # Unassigned = 148-252
+    # Use for experimentation and testing = 253-254
+    RESERVED_255 = 255
+
+    @classmethod
+    def _missing_(cls, value: int) -> IANAProtocol:
+        # Allows values other than defined members
+        member = int.__new__(cls, value)
+
+        if value >= 148 and value <= 252:
+            member._name_ = f"UNASSIGNED_{value!s}"
+        elif value in (253, 254):
+            member._name_ = f"USE_FOR_EXPERIMENTATION_AND_TESTING_{value!s}"
+        else:
+            member._name_ = f"UNKNOWN_{value!s}"
+
+        member._value_ = value
+        return member

dissect_target-3.23.dev46/dissect/target/plugins/os/windows/firewall.py

@@ -0,0 +1,309 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from itertools import islice
+from typing import TYPE_CHECKING, Any, Callable, Final
+
+from dissect.target.exceptions import RegistryValueNotFoundError, UnsupportedPluginError
+from dissect.target.helpers.network import IANAProtocol
+from dissect.target.helpers.record import DynamicDescriptor, TargetRecordDescriptor
+from dissect.target.plugin import Plugin, export
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+    from pathlib import Path
+
+    from dissect.target.helpers.regutil import RegistryKey
+    from dissect.target.target import Target
+
+
+WindowsFirewallLogRecord = TargetRecordDescriptor(
+    "windows/firewall/log",
+    [
+        ("datetime", "ts"),
+        ("string", "action"),
+        ("string", "protocol"),
+        ("net.ipaddress", "src_ip"),
+        ("net.ipaddress", "dst_ip"),
+        ("varint", "src_port"),
+        ("varint", "dst_port"),
+        ("filesize", "size"),
+        ("string", "tcpflags"),
+        ("string", "tcpsyn"),
+        ("string", "tcpack"),
+        ("string", "tcpwin"),
+        ("string", "icmptype"),
+        ("string", "icmpcode"),
+        ("string", "info"),
+        ("string", "path"),
+        ("path", "source"),
+    ],
+)
+
+
+class WindowsFirewallPlugin(Plugin):
+    """Windows Firewall plugin."""
+
+    __namespace__ = "firewall"
+
+    RULE_KEYS = (
+        # Defaults
+        "HKLM\\SYSTEM\\CurrentControlSet\\Services\\SharedAccess\\Defaults\\FirewallPolicy\\FirewallRules",
+        # Parameters
+        "HKLM\\SYSTEM\\CurrentControlSet\\Services\\SharedAccess\\Parameters\\FirewallPolicy\\FirewallRules",
+        "HKLM\\SYSTEM\\CurrentControlSet\\Services\\SharedAccess\\Parameters\\FirewallPolicy\\Mdm\\FirewallRules",
+        # Legacy
+        "HKLM\\SOFTWARE\\Policies\\Microsoft\\WindowsFirewall\\FirewallRules",
+        # Other
+        "HKLM\\SYSTEM\\CurrentControlSet\\Services\\SharedAccess\\Parameters\\FirewallPolicy\\RestrictedServices\\AppIso\\FirewallRules",
+        "HKLM\\SYSTEM\\CurrentControlSet\\Services\\SharedAccess\\Parameters\\FirewallPolicy\\RestrictedServices\\Configurable\\System",
+        "HKLM\\SYSTEM\\CurrentControlSet\\Services\\SharedAccess\\Parameters\\FirewallPolicy\\RestrictedServices\\Static\\System",
+    )
+
+    LOGGING_KEYS = (
+        # Defaults
+        "HKLM\\SYSTEM\\CurrentControlSet\\Services\\SharedAccess\\Defaults\\FirewallPolicy\\PublicProfile\\Logging"
+        "HKLM\\SYSTEM\\CurrentControlSet\\Services\\SharedAccess\\Defaults\\FirewallPolicy\\StandardProfile\\Logging"
+        "HKLM\\SYSTEM\\CurrentControlSet\\Services\\SharedAccess\\Defaults\\FirewallPolicy\\DomainProfile\\Logging"
+        # Parameters
+        "HKLM\\SYSTEM\\CurrentControlSet\\Services\\SharedAccess\\Parameters\\FirewallPolicy\\PublicProfile\\Logging",
+        "HKLM\\SYSTEM\\CurrentControlSet\\Services\\SharedAccess\\Parameters\\FirewallPolicy\\StandardProfile\\Logging",
+        "HKLM\\SYSTEM\\CurrentControlSet\\Services\\SharedAccess\\Parameters\\FirewallPolicy\\DomainProfile\\Logging",
+    )
+
+    def __init__(self, target: Target):
+        super().__init__(target)
+        self.keys = list(self.find_rule_keys())
+        self.log_paths = list(self.find_log_paths())
+
+    def find_rule_keys(self) -> Iterator[RegistryKey]:
+        for key in self.RULE_KEYS:
+            yield from self.target.registry.keys(key)
+
+    def find_log_paths(self) -> Iterator[Path]:
+        seen = set()
+
+        for path in self.target.fs.path("sysvol/Windows/System32/LogFiles/Firewall").glob("pfirewall*"):
+            seen.add(path)
+            yield path
+
+        if self.target.has_function("registry"):
+            for log_key in self.LOGGING_KEYS:
+                for key in self.target.registry.keys(log_key):
+                    try:
+                        log_path = self.target.resolve(key.value("LogFilePath").value)
+                        if log_path.is_file() and log_path not in seen:
+                            seen.add(log_path)
+                            yield log_path
+                    except (ValueError, RegistryValueNotFoundError):  # noqa: PERF203
+                        pass
+
+    def check_compatible(self) -> None:
+        if not self.keys and not self.log_paths:
+            raise UnsupportedPluginError("No Windows Firewall registry keys or log files found on target")
+
+    @export(record=DynamicDescriptor(["string", "boolean"]))
+    def rules(self) -> Iterator[DynamicDescriptor]:
+        """Return firewall rules saved in the Windows registry.
+
+        For a Windows operating system, the Firewall rules are stored in the
+        ``HKLM\\SYSTEM\\CurrentControlSet\\Services\\SharedAccess\\Parameters\\FirewallPolicy\\FirewallRules`` registry key.
+
+        References:
+            - https://learn.microsoft.com/en-us/openspecs/windows_protocols/ms-gpfas/2efe0b76-7b4a-41ff-9050-1023f8196d16
+
+        Yields dynamic records with usually the following fields:
+
+        .. code-block:: text
+
+            hostname (string): The target hostname.
+            domain (string): The target domain.
+            key (string): The rule key name.
+            version (string): The version field of the rule.
+            action (string): The action of the rule.
+            active (boolean): Whether the rule is active.
+            dir (string): The direction of the rule.
+            protocol (string): The specified IANA protocol (UDP, TCP, etc).
+            lport (string): The listening port or range of the rule.
+            rport (string): The receiving port or range the rule.
+            profile (string): The Profile field of the rule.
+            app (string): The App field of the rule.
+            svc (string): The Svc of the rule.
+            name (string): The Name of the rule.
+            desc (string): The Desc of the rule.
+            embed_ctxt (string): The EmbedCtxt of the rule.
+        """  # noqa: E501
+
+        FIELD_MAP: Final[dict[str, str]] = {
+            "app": "path",
+            "active": "boolean",
+            # protocol int is translated to a string at runtime
+            # lport and rport can be a string (e.g. port ranges or other text)
+            "lport": "string[]",
+            "rport": "string[]",
+        }
+        VALUE_MAP: Final[dict[str, Callable[[str], Any]]] = {"active": lambda val: val.upper() == "TRUE"}
+
+        for reg in self.keys:
+            for entry in reg.values():
+                r = [
+                    ("string", "key"),
+                    ("string", "version"),
+                ]
+                data = {}
+
+                pairs: list[str] = entry.value.split("|")
+                data["version"] = pairs.pop(0)
+
+                for kv in pairs:
+                    key, _, value = kv.partition("=")
+
+                    if not (key := key.lower()):
+                        continue
+
+                    field_type = FIELD_MAP.get(key, "string")
+                    r.append((field_type, key))
+
+                    try:
+                        value = VALUE_MAP[key](value)
+                    except KeyError:
+                        pass
+                    data[key] = value
+
+                # Resolve file paths to TargetPaths
+                if "app" in data:
+                    data["app"] = self.target.resolve(data["app"])
+
+                # Translate protocol numbers to IANA names
+                if protocol := data.get("protocol"):
+                    if protocol.isnumeric():
+                        data["protocol"] = IANAProtocol(int(protocol)).name
+                    elif protocol.isalpha():
+                        data["protocol"] = protocol.upper()
+
+                # Make sure actions and directions are consistent
+                if "action" in data:
+                    data["action"] = data["action"].upper()
+                if "dir" in data:
+                    data["dir"] = data["dir"].upper()
+
+                # Put port ranges in a list
+                if "lport" in data:
+                    data["lport"] = data["lport"].split(",")
+                if "rport" in data:
+                    data["rport"] = data["rport"].split(",")
+
+                r.append(("path", "source"))
+
+                yield TargetRecordDescriptor("windows/firewall/rule", r)(
+                    key=entry.name,
+                    **data,
+                    source=f"HKLM\\{reg.path}",
+                    _target=self.target,
+                )
+
+    @export(record=WindowsFirewallLogRecord)
+    def logs(self) -> Iterator[WindowsFirewallLogRecord]:
+        """Parse Windows Firewall log files.
+
+        Currently parses ``pfirewall*`` files in ``sysvol\\Windows\\System32\\LogFiles\\Firewall\\`` only.
+        Does not yet parse dynamically set log locations e.g. ``netsh advfirewall set currentprofile logging filename``.
+
+        References:
+            - https://learn.microsoft.com/en-us/windows/security/operating-system-security/network-security/windows-firewall/configure-logging
+
+        Yields Windows Firewall log records with the following fields:
+
+        .. code-block:: text
+
+            ts (datetime): The timestamp of the log entry.
+            hostname (string): The target hostname.
+            domain (string): The target domain.
+            action (string): Allow or Block.
+            protocol (string): TCP, UDP or other IANA protocol value.
+            src_ip (net.ipaddress): Source IP address.
+            dst_ip (net.ipaddress): Destination IP address.
+            src_port (varint): Source port number.
+            dst_port (varint): Destination port number.
+            size (filesize): Size in bytes of the packet(s).
+            tcpflags (string): TCP header control flags.
+            tcpsyn (string): TCP sequence number.
+            tcpack (string): TCP acknowledgement number.
+            tcpwin (string): TCP window size in bytes.
+            icmptype (string): ICMP packet type.
+            icmpcode (string): ICMP packet code.
+            info (string): Additional information.
+            path (string): Direction of the traffic, either SEND, RECEIVE, FORWARD or UNKNOWN.
+            source (path): Source path of the record log line.
+        """
+
+        for path in self.log_paths:
+            with path.open("rt") as fh:
+                try:
+                    header = list(islice(fh, 4))
+                    config = LogConfig(header)
+                except Exception as e:
+                    self.target.log.warning("Unable to read Windows Firewall log file config in %s: %s", path, e)
+                    self.target.log.debug("", exc_info=e)
+                    continue
+
+                if config.version != 1.5:
+                    self.target.log.warning(
+                        "Unsupported Windows Firewall log file version %r in log file %s", header[0], path
+                    )
+                    continue
+
+                for line in fh:
+                    if not (line := line.strip()):
+                        continue
+
+                    entry = {
+                        k.replace("-", "_"): v if v != "-" else None for k, v in zip(config.fields, line.split(" "))
+                    }
+
+                    entry["ts"] = datetime.strptime(f"{entry['date']} {entry['time']}", "%Y-%m-%d %H:%M:%S").replace(
+                        tzinfo=self.target.datetime.tzinfo if config.time_format == "local" else timezone.utc
+                    )
+                    entry.pop("date")
+                    entry.pop("time")
+
+                    yield WindowsFirewallLogRecord(
+                        **entry,
+                        source=path,
+                        _target=self.target,
+                    )
+
+
+@dataclass
+class LogConfig:
+    """Windows Firewall Log ``pfirewall.log`` file config parser.
+
+    Fields can differ depending on configuration and version.
+
+    Example structure of a regular ``pfirewall.log`` file:
+
+    .. code-block::
+
+        #Version: 1.5
+        #Software: Microsoft Windows Firewall
+        #Time Format: Local
+        #Fields: date time action protocol src-ip dst-ip src-port dst-port size tcpflags tcpsyn tcpack tcpwin icmptype icmpcode info path
+
+        2022-01-01 13:37:00 DROP UDP 1.2.3.4 5.6.7.8 1234 5678 1337 - - - - - - - RECEIVE
+    """  # noqa: E501
+
+    raw: list[str] = field(repr=False)
+    version: float | None = None
+    software: str | None = None
+    time_format: str | None = None
+    fields: list[str] | None = None
+
+    def __post_init__(self):
+        assert len(self.raw) == 4
+        _, _, self.version = self.raw[0].strip().partition("#Version: ")
+        _, _, self.software = self.raw[1].strip().partition("#Software: ")
+        _, _, self.time_format = self.raw[2].strip().lower().partition("#time format: ")
+        _, _, fields = self.raw[3].strip().partition("#Fields: ")
+        self.version = float(self.version)
+        self.fields = fields.split(" ")

{dissect_target-3.23.dev45 → dissect_target-3.23.dev46}/dissect.target.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dissect.target
-Version: 3.23.dev45
+Version: 3.23.dev46
 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.23.dev45 → dissect_target-3.23.dev46}/dissect.target.egg-info/SOURCES.txt

@@ -73,6 +73,7 @@ dissect/target/helpers/loaderutil.py
 dissect/target/helpers/localeutil.py
 dissect/target/helpers/mount.py
 dissect/target/helpers/mui.py
+dissect/target/helpers/network.py
 dissect/target/helpers/polypath.py
 dissect/target/helpers/protobuf.py
 dissect/target/helpers/record.py
@@ -345,6 +346,7 @@ dissect/target/plugins/os/windows/cim.py
 dissect/target/plugins/os/windows/clfs.py
 dissect/target/plugins/os/windows/datetime.py
 dissect/target/plugins/os/windows/env.py
+dissect/target/plugins/os/windows/firewall.py
 dissect/target/plugins/os/windows/generic.py
 dissect/target/plugins/os/windows/jumplist.py
 dissect/target/plugins/os/windows/lnk.py
@@ -405,7 +407,6 @@ dissect/target/plugins/os/windows/regf/auditpol.py
 dissect/target/plugins/os/windows/regf/bam.py
 dissect/target/plugins/os/windows/regf/cit.py
 dissect/target/plugins/os/windows/regf/clsid.py
-dissect/target/plugins/os/windows/regf/firewall.py
 dissect/target/plugins/os/windows/regf/mru.py
 dissect/target/plugins/os/windows/regf/muicache.py
 dissect/target/plugins/os/windows/regf/nethist.py
@@ -502,6 +503,7 @@ tests/helpers/test_keychain.py
 tests/helpers/test_loaderutil.py
 tests/helpers/test_localeutil.py
 tests/helpers/test_modifier.py
+tests/helpers/test_network.py
 tests/helpers/test_protobuf.py
 tests/helpers/test_record.py
 tests/helpers/test_regex.py
@@ -714,6 +716,7 @@ tests/plugins/os/windows/test_datetime.py
 tests/plugins/os/windows/test_defender.py
 tests/plugins/os/windows/test_env.py
 tests/plugins/os/windows/test_everything.py
+tests/plugins/os/windows/test_firewall.py
 tests/plugins/os/windows/test_generic.py
 tests/plugins/os/windows/test_jumplist.py
 tests/plugins/os/windows/test_lnk.py

dissect_target-3.23.dev46/tests/helpers/test_network.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+import pytest
+
+from dissect.target.helpers.network import IANAProtocol
+
+
+@pytest.mark.parametrize(
+    ("input_number", "expected_output"),
+    [
+        (0, "HOPOPT"),
+        (6, "TCP"),
+        (17, "UDP"),
+        (27, "RDP"),
+        (148, "UNASSIGNED_148"),
+        (169, "UNASSIGNED_169"),
+        (252, "UNASSIGNED_252"),
+        (253, "USE_FOR_EXPERIMENTATION_AND_TESTING_253"),
+        (255, "RESERVED_255"),
+        (1337, "UNKNOWN_1337"),
+    ],
+)
+def test_helpers_network_iana_protocol_translation(input_number: int, expected_output: str) -> None:
+    """Test if we translate IANA protocol numbers correctly."""
+
+    assert IANAProtocol(input_number).name == expected_output
+    assert IANAProtocol(input_number).value == input_number