dissect.target 3.17.dev37__py3-none-any.whl → 3.18__py3-none-any.whl

dissect/target/plugins/os/windows/defender.py

@@ -1,7 +1,10 @@
+from __future__ import annotations
+
+import re
 from datetime import datetime, timezone
 from io import BytesIO
 from pathlib import Path
-from typing import Any, BinaryIO, Generator, Iterable, Iterator, Union
+from typing import Any, BinaryIO, Generator, Iterable, Iterator, TextIO, Union
 
 import dissect.util.ts as ts
 from dissect.cstruct import Structure, cstruct
@@ -10,6 +13,27 @@ from flow.record import Record
 from dissect.target import plugin
 from dissect.target.exceptions import UnsupportedPluginError
 from dissect.target.helpers.record import TargetRecordDescriptor
+from dissect.target.plugins.os.windows.defender_helpers.defender_patterns import (
+    DEFENDER_MPLOG_BLOCK_PATTERNS,
+    DEFENDER_MPLOG_LINE,
+    DEFENDER_MPLOG_PATTERNS,
+)
+from dissect.target.plugins.os.windows.defender_helpers.defender_records import (
+    DefenderMPLogBMTelemetryRecord,
+    DefenderMPLogDetectionAddRecord,
+    DefenderMPLogDetectionEventRecord,
+    DefenderMPLogEMSRecord,
+    DefenderMPLogExclusionRecord,
+    DefenderMPLogLowfiRecord,
+    DefenderMPLogMinFilBlockedFileRecord,
+    DefenderMPLogMinFilUSSRecord,
+    DefenderMPLogOriginalFileNameRecord,
+    DefenderMPLogProcessImageRecord,
+    DefenderMPLogResourceScanRecord,
+    DefenderMPLogRTPRecord,
+    DefenderMPLogThreatActionRecord,
+    DefenderMPLogThreatRecord,
+)
 
 DEFENDER_EVTX_FIELDS = [
     ("datetime", "ts"),
@@ -73,6 +97,7 @@ DEFENDER_LOG_FILENAME_GLOB = "Microsoft-Windows-Windows Defender*"
 EVTX_PROVIDER_NAME = "Microsoft-Windows-Windows Defender"
 
 DEFENDER_QUARANTINE_DIR = "sysvol/programdata/microsoft/windows defender/quarantine"
+DEFENDER_MPLOG_DIR = "sysvol/programdata/microsoft/windows defender/support"
 DEFENDER_KNOWN_DETECTION_TYPES = [b"internalbehavior", b"regkey", b"runkey"]
 
 DEFENDER_EXCLUSION_KEY = "HKLM\\SOFTWARE\\Microsoft\\Windows Defender\\Exclusions"
@@ -237,8 +262,7 @@ struct QuarantineEntryResourceField {
 };
 """
 
-c_defender = cstruct()
-c_defender.load(defender_def)
+c_defender = cstruct().load(defender_def)
 
 STREAM_ID = c_defender.STREAM_ID
 STREAM_ATTRIBUTES = c_defender.STREAM_ATTRIBUTES
@@ -381,7 +405,7 @@ class QuarantineEntryResource:
             self.last_access_time = ts.wintimestamp(int.from_bytes(field.Data, "little"))
         elif field.Identifier == FIELD_IDENTIFIER.LastWriteTime:
             self.last_write_time = ts.wintimestamp(int.from_bytes(field.Data, "little"))
-        elif field.Identifier not in FIELD_IDENTIFIER.values.values():
+        elif field.Identifier not in FIELD_IDENTIFIER:
             self.unknown_fields.append(field)
 
 
@@ -495,6 +519,198 @@ class MicrosoftDefenderPlugin(plugin.Plugin):
                         value=exclusion_value,
                     )
 
+    def _mplog_processimage(self, data: dict) -> Iterator[DefenderMPLogProcessImageRecord]:
+        yield DefenderMPLogProcessImageRecord(**data)
+
+    def _mplog_minfiluss(self, data: dict) -> Iterator[DefenderMPLogMinFilUSSRecord]:
+        yield DefenderMPLogMinFilUSSRecord(**data)
+
+    def _mplog_blockedfile(self, data: dict) -> Iterator[DefenderMPLogMinFilBlockedFileRecord]:
+        yield DefenderMPLogMinFilBlockedFileRecord(**data)
+
+    def _mplog_bmtelemetry(self, data: dict) -> Iterator[DefenderMPLogBMTelemetryRecord]:
+        data["ts"] = datetime.strptime(data["ts"], "%m-%d-%Y %H:%M:%S")
+        yield DefenderMPLogBMTelemetryRecord(**data)
+
+    def _mplog_ems(self, data: dict) -> Iterator[DefenderMPLogEMSRecord]:
+        yield DefenderMPLogEMSRecord(**data)
+
+    def _mplog_originalfilename(self, data: dict) -> Iterator[DefenderMPLogOriginalFileNameRecord]:
+        yield DefenderMPLogOriginalFileNameRecord(**data)
+
+    def _mplog_exclusion(self, data: dict) -> Iterator[DefenderMPLogExclusionRecord]:
+        yield DefenderMPLogExclusionRecord(**data)
+
+    def _mplog_lowfi(self, data: dict) -> Iterator[DefenderMPLogLowfiRecord]:
+        yield DefenderMPLogLowfiRecord(**data)
+
+    def _mplog_detectionadd(self, data: dict) -> Iterator[DefenderMPLogDetectionAddRecord]:
+        yield DefenderMPLogDetectionAddRecord(**data)
+
+    def _mplog_threat(self, data: dict) -> Iterator[DefenderMPLogThreatRecord]:
+        yield DefenderMPLogThreatRecord(**data)
+
+    def _mplog_resourcescan(self, data: dict) -> Iterator[DefenderMPLogResourceScanRecord]:
+        data["start_time"] = datetime.strptime(data["start_time"], "%m-%d-%Y %H:%M:%S")
+        data["end_time"] = datetime.strptime(data["end_time"], "%m-%d-%Y %H:%M:%S")
+        data["ts"] = data["start_time"]
+        rest = data.pop("rest")
+        yield DefenderMPLogResourceScanRecord(
+            threats=re.findall("Threat Name:([^\n]+)", rest),
+            resources=re.findall("Resource Path:([^\n]+)", rest),
+            **data,
+        )
+
+    def _mplog_threataction(self, data: dict) -> Iterator[DefenderMPLogThreatActionRecord]:
+        data["ts"] = datetime.strptime(data["ts"], "%m-%d-%Y %H:%M:%S")
+        rest = data.pop("rest")
+        yield DefenderMPLogThreatActionRecord(
+            threats=re.findall("Threat Name:([^\n]+)", rest),
+            resources=re.findall("(?:Path|File Name):([^\n]+)", rest),
+            actions=re.findall("Action:([^\n]+)", rest),
+            **data,
+        )
+
+    def _mplog_rtp_log(self, data: dict) -> Iterator[DefenderMPLogRTPRecord]:
+        times = {}
+        for dtkey in ["ts", "last_perf", "first_rtp_scan"]:
+            try:
+                times[dtkey] = datetime.strptime(data[dtkey], "%m-%d-%Y %H:%M:%S")
+            except ValueError:
+                pass
+
+        yield DefenderMPLogRTPRecord(
+            _target=self.target,
+            source_log=data["source_log"],
+            **times,
+            plugin_states=re.findall(r"^\s+(.*)$", data["plugin_states"])[0],
+            process_exclusions=re.findall(DEFENDER_MPLOG_LINE, data["process_exclusions"]),
+            path_exclusions=re.findall(DEFENDER_MPLOG_LINE, data["path_exclusions"]),
+            ext_exclusions=re.findall(DEFENDER_MPLOG_LINE, data["ext_exclusions"]),
+        )
+
+    def _mplog_detectionevent(self, data: dict) -> Iterator[DefenderMPLogDetectionEventRecord]:
+        yield DefenderMPLogDetectionEventRecord(**data)
+
+    def _mplog_line(
+        self, mplog_line: str, source: Path
+    ) -> Iterator[
+        DefenderMPLogProcessImageRecord
+        | DefenderMPLogMinFilUSSRecord
+        | DefenderMPLogMinFilBlockedFileRecord
+        | DefenderMPLogEMSRecord
+        | DefenderMPLogOriginalFileNameRecord
+        | DefenderMPLogExclusionRecord
+        | DefenderMPLogLowfiRecord
+        | DefenderMPLogDetectionAddRecord
+        | DefenderMPLogThreatRecord
+        | DefenderMPLogDetectionEventRecord
+    ]:
+        for pattern, record in DEFENDER_MPLOG_PATTERNS:
+            if match := pattern.match(mplog_line):
+                data = match.groupdict()
+                data["_target"] = self.target
+                data["source_log"] = source
+                yield from getattr(self, f"_mplog_{record.name.split('/')[-1:][0]}")(data)
+
+    def _mplog_block(
+        self, mplog_line: str, mplog: TextIO, source: Path
+    ) -> Iterator[DefenderMPLogResourceScanRecord | DefenderMPLogThreatActionRecord | DefenderMPLogRTPRecord]:
+        block = ""
+        for prefix, suffix, pattern, record in DEFENDER_MPLOG_BLOCK_PATTERNS:
+            if prefix.search(mplog_line):
+                block += mplog_line
+                break
+        if block:
+            while mplog_line := mplog.readline():
+                block += mplog_line
+                if suffix.search(mplog_line):
+                    break
+            match = pattern.match(block)
+            data = match.groupdict()
+            data["_target"] = self.target
+            data["source_log"] = source
+            yield from getattr(self, f"_mplog_{record.name.split('/')[-1:][0]}")(data)
+
+    def _mplog(
+        self, mplog: TextIO, source: Path
+    ) -> Iterator[
+        DefenderMPLogProcessImageRecord
+        | DefenderMPLogMinFilUSSRecord
+        | DefenderMPLogMinFilBlockedFileRecord
+        | DefenderMPLogBMTelemetryRecord
+        | DefenderMPLogEMSRecord
+        | DefenderMPLogOriginalFileNameRecord
+        | DefenderMPLogExclusionRecord
+        | DefenderMPLogLowfiRecord
+        | DefenderMPLogDetectionAddRecord
+        | DefenderMPLogThreatRecord
+        | DefenderMPLogDetectionEventRecord
+        | DefenderMPLogResourceScanRecord
+        | DefenderMPLogThreatActionRecord
+        | DefenderMPLogRTPRecord
+    ]:
+        while mplog_line := mplog.readline():
+            yield from self._mplog_line(mplog_line, source)
+            yield from self._mplog_block(mplog_line, mplog, source)
+
+    @plugin.export(
+        record=[
+            DefenderMPLogProcessImageRecord,
+            DefenderMPLogMinFilUSSRecord,
+            DefenderMPLogMinFilBlockedFileRecord,
+            DefenderMPLogBMTelemetryRecord,
+            DefenderMPLogEMSRecord,
+            DefenderMPLogOriginalFileNameRecord,
+            DefenderMPLogExclusionRecord,
+            DefenderMPLogLowfiRecord,
+            DefenderMPLogDetectionAddRecord,
+            DefenderMPLogThreatRecord,
+            DefenderMPLogDetectionEventRecord,
+            DefenderMPLogResourceScanRecord,
+            DefenderMPLogThreatActionRecord,
+            DefenderMPLogRTPRecord,
+        ]
+    )
+    def mplog(
+        self,
+    ) -> Iterator[
+        DefenderMPLogProcessImageRecord
+        | DefenderMPLogMinFilUSSRecord
+        | DefenderMPLogMinFilBlockedFileRecord
+        | DefenderMPLogBMTelemetryRecord
+        | DefenderMPLogEMSRecord
+        | DefenderMPLogOriginalFileNameRecord
+        | DefenderMPLogExclusionRecord
+        | DefenderMPLogLowfiRecord
+        | DefenderMPLogDetectionAddRecord
+        | DefenderMPLogThreatRecord
+        | DefenderMPLogDetectionEventRecord
+        | DefenderMPLogResourceScanRecord
+        | DefenderMPLogThreatActionRecord
+        | DefenderMPLogRTPRecord
+    ]:
+        """Return the contents of the Defender MPLog file.
+
+        References:
+            - https://www.crowdstrike.com/blog/how-to-use-microsoft-protection-logging-for-forensic-investigations/
+            - https://www.intrinsec.com/hunt-mplogs/
+            - https://github.com/Intrinsec/mplog_parser
+        """
+        mplog_directory = self.target.fs.path(DEFENDER_MPLOG_DIR)
+
+        if not (mplog_directory.exists() and mplog_directory.is_dir()):
+            return
+
+        for mplog_file in mplog_directory.glob("MPLog-*"):
+            for encoding in ["UTF-16", "UTF-8"]:
+                try:
+                    with mplog_file.open("rt", encoding=encoding) as mplog:
+                        yield from self._mplog(mplog, self.target.fs.path(mplog_file))
+                    break
+                except UnicodeError:
+                    continue
+
     @plugin.arg(
         "--output",
         "-o",
@@ -526,7 +742,7 @@ class MicrosoftDefenderPlugin(plugin.Plugin):
                     subdir = resource.resource_id[0:2]
                     resourcedata_location = resourcedata_directory.joinpath(subdir).joinpath(resource.resource_id)
                     if not resourcedata_location.exists():
-                        self.target.log.warning(f"Could not find a ResourceData file for {entry.resource_id}.")
+                        self.target.log.warning(f"Could not find a ResourceData file for {resource.resource_id}.")
                         continue
                     if not resourcedata_location.is_file():
                         self.target.log.warning(f"{resourcedata_location} is not a file!")

dissect/target/plugins/os/windows/defender_helpers/defender_patterns.py

@@ -0,0 +1,282 @@
+import re
+
+from dissect.target.plugins.os.windows.defender_helpers.defender_records import (
+    DefenderMPLogBMTelemetryRecord,
+    DefenderMPLogDetectionAddRecord,
+    DefenderMPLogDetectionEventRecord,
+    DefenderMPLogEMSRecord,
+    DefenderMPLogExclusionRecord,
+    DefenderMPLogLowfiRecord,
+    DefenderMPLogMinFilBlockedFileRecord,
+    DefenderMPLogMinFilUSSRecord,
+    DefenderMPLogOriginalFileNameRecord,
+    DefenderMPLogProcessImageRecord,
+    DefenderMPLogResourceScanRecord,
+    DefenderMPLogRTPRecord,
+    DefenderMPLogThreatActionRecord,
+    DefenderMPLogThreatRecord,
+)
+
+DEFENDER_MPLOG_TS_PATTERN = r"(?P<ts>[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}\.[0-9]{3}Z) "
+
+# Loosely based on https://github.com/Intrinsec/mplog_parser but feel free to add patterns
+
+DEFENDER_MPLOG_PATTERNS = [
+    # Process Image
+    (
+        re.compile(
+            "".join(
+                [
+                    DEFENDER_MPLOG_TS_PATTERN,
+                    r"ProcessImageName: (?P<process_image_name>.*), ",
+                    r"Pid: (?P<pid>\d*), ",
+                    r"TotalTime: (?P<total_time>\d*), ",
+                    r"Count: (?P<count>\d*), ",
+                    r"MaxTime: (?P<max_time>\d*), ",
+                    r"MaxTimeFile: (?P<max_time_file>.*), ",
+                    r"EstimatedImpact: (?P<estimated_impact>\d*)",
+                ]
+            )
+        ),
+        DefenderMPLogProcessImageRecord,
+    ),
+    # Mini-filter Unsuccessful scan status
+    (
+        re.compile(
+            "".join(
+                [
+                    DEFENDER_MPLOG_TS_PATTERN,
+                    r"\[Mini-filter\] (Unsuccessful scan status)[^:]*: (?P<path>.+) ",
+                    r"Process: (?P<process>.+), ",
+                    r"Status: (?P<status>.+), ",
+                    r"State: (?P<state>.+), ",
+                    r"ScanRequest (?P<scan_request>.+), ",
+                    r"FileId: (?P<file_id>.+), ",
+                    r"Reason: (?P<reason>.+), ",
+                    r"IoStatusBlockForNewFile: (?P<io_status_block_for_new_file>.+), ",
+                    r"DesiredAccess:(?P<desired_access>.+), ",
+                    r"FileAttributes:(?P<file_attributes>.+), ",
+                    r"ScanAttributes:(?P<scan_attributes>.+), ",
+                    r"AccessStateFlags:(?P<access_state_flags>.+), ",
+                    r"BackingFileInfo: (?P<backing_file_info>.+)",
+                ]
+            )
+        ),
+        DefenderMPLogMinFilUSSRecord,
+    ),
+    # EMS Scan
+    (
+        re.compile(
+            "".join(
+                [
+                    DEFENDER_MPLOG_TS_PATTERN,
+                    r".*",
+                    r"process: (?P<process>\w*) ",
+                    r"pid: (?P<pid>\d*), ",
+                    r"sigseq: (?P<sigseq>\w*), ",
+                    r"sendMemoryScanReport: (?P<send_memory_scan_report>\d*), ",
+                    r"source: (?P<source>\d*)",
+                ]
+            )
+        ),
+        DefenderMPLogEMSRecord,
+    ),
+    # Original filename
+    (
+        re.compile(
+            "".join(
+                [
+                    DEFENDER_MPLOG_TS_PATTERN,
+                    r".*",
+                    r"original file name \"(?P<original_file_name>.*)\" ",
+                    r"for \"(?P<full_path>.*)\", ",
+                    r"hr=(?P<hr>\w*)",
+                ]
+            )
+        ),
+        DefenderMPLogOriginalFileNameRecord,
+    ),
+    # Mini-filter Blocked file
+    (
+        re.compile(
+            "".join(
+                [
+                    DEFENDER_MPLOG_TS_PATTERN,
+                    r".*",
+                    r"\[Mini-filter\] Blocked file: (?P<blocked_file>.+) ",
+                    r"Process: (?P<process>.+), ",
+                    r"Status: (?P<status>.+), ",
+                    r"State: (?P<state>.+), ",
+                    r"ScanRequest (?P<scan_request>.+), ",
+                    r"FileId: (?P<file_id>.+), ",
+                    r"Reason: (?P<reason>.+), ",
+                    r"IoStatusBlockForNewFile: (?P<io_status_block_for_new_file>.+), ",
+                    r"DesiredAccess:(?P<desired_access>.+), ",
+                    r"FileAttributes:(?P<file_attributes>.+), ",
+                    r"ScanAttributes:(?P<scan_attributes>.+), ",
+                    r"AccessStateFlags:(?P<access_state_flags>.+), ",
+                    r"BackingFileInfo: (?P<backing_file_info>.+)",
+                ]
+            )
+        ),
+        DefenderMPLogMinFilBlockedFileRecord,
+    ),
+    # Exclusion
+    (
+        re.compile(
+            "".join(
+                [
+                    DEFENDER_MPLOG_TS_PATTERN,
+                    r"\[Exclusion\] (?P<full_path_with_drive_letter>.+) ",
+                    r"-> (?P<full_path_with_device_path>.+)",
+                ]
+            )
+        ),
+        DefenderMPLogExclusionRecord,
+    ),
+    # Lowfi
+    (
+        re.compile(
+            "".join(
+                [
+                    DEFENDER_MPLOG_TS_PATTERN,
+                    r".*",
+                    r"lowfi: (?P<lowfi>.+)",
+                ]
+            )
+        ),
+        DefenderMPLogLowfiRecord,
+    ),
+    # Detection add
+    (
+        re.compile(
+            "".join(
+                [
+                    DEFENDER_MPLOG_TS_PATTERN,
+                    r".*",
+                    r"DETECTION_ADD\S* (?P<detection>.*)",
+                ]
+            )
+        ),
+        DefenderMPLogDetectionAddRecord,
+    ),
+    # Threat
+    (
+        re.compile(
+            "".join(
+                [
+                    DEFENDER_MPLOG_TS_PATTERN,
+                    r".*",
+                    r"threat: (?P<threat>.*)",
+                ]
+            )
+        ),
+        DefenderMPLogThreatRecord,
+    ),
+    # Detection event
+    (
+        re.compile(
+            "".join(
+                [
+                    DEFENDER_MPLOG_TS_PATTERN,
+                    r".*",
+                    r"DETECTIONEVENT MPSOURCE_\S+ HackTool:(?P<threat_type>.*) file:(?P<command>.*)",
+                ]
+            )
+        ),
+        DefenderMPLogDetectionEventRecord,
+    ),
+]
+
+
+DEFENDER_MPLOG_BLOCK_PATTERNS = [
+    (
+        re.compile(r"Begin Resource Scan"),
+        re.compile(r"End Scan"),
+        re.compile(
+            "".join(
+                [
+                    r"Begin Resource Scan.*\n",
+                    r"Scan ID:(?P<scan_id>[^\n]+)\n",
+                    r"Scan Source:(?P<scan_source>\d+)\n",
+                    r"Start Time:(?P<start_time>[0-9\-\:\s]*)\n",
+                    r"End Time:(?P<end_time>[0-9\-\:\s]*)\n",
+                    r".*",
+                    r"Resource Schema:(?P<resource_schema>[^\n]+)\n",
+                    r"Resource Path:(?P<resource_path>[^\n]+)\n",
+                    r"Result Count:(?P<result_count>\d+)\n",
+                    r"(?P<rest>.*)\n",
+                    r"End Scan",
+                ]
+            ),
+            re.MULTILINE | re.DOTALL,
+        ),
+        DefenderMPLogResourceScanRecord,
+    ),
+    # Threat actions
+    (
+        re.compile(r"Beginning threat actions"),
+        re.compile(r"Finished threat actions"),
+        re.compile(
+            "".join(
+                [
+                    r"Beginning threat actions\n",
+                    r"Start time:(?P<ts>[0-9\-\:\s]*)\n",
+                    r"(?P<rest>.*)\n",
+                    r"Finished threat actions",
+                ]
+            ),
+            re.MULTILINE | re.DOTALL,
+        ),
+        DefenderMPLogThreatActionRecord,
+    ),
+    # RTP
+    (
+        re.compile(r"\*\*RTP Perf Log\*\*"),
+        re.compile(r"\*\*END RTP Perf Log\*\*"),
+        re.compile(
+            "".join(
+                [
+                    r"\*+RTP Perf Log\*+\n",
+                    r"RTP Start:(?P<ts>.*)\n",
+                    r"Last Perf:(?P<last_perf>.*)\n",
+                    r"First RTP Scan:(?P<first_rtp_scan>.*)\n",
+                    r"Plugin States:(?P<plugin_states>.*)\n",
+                    r"Process Exclusions:\n(?P<process_exclusions>.*)",
+                    r"Path Exclusions:\n(?P<path_exclusions>.*)",
+                    r"Ext Exclusions:\n(?P<ext_exclusions>.*)",
+                    r"Worker Threads",
+                ]
+            ),
+            re.MULTILINE | re.DOTALL,
+        ),
+        DefenderMPLogRTPRecord,
+    ),
+    # BM Telemetry (block)
+    (
+        re.compile(r"BEGIN BM telemetry"),
+        re.compile(r"END BM telemetry"),
+        re.compile(
+            "".join(
+                [
+                    r"BEGIN BM telemetry\n",
+                    r"(GUID):(?P<guid>.+)\n",
+                    r"(SignatureID):(?P<signature_id>.+)\n",
+                    r"(SigSha):(?P<sigsha>.+)\n",
+                    r"(ThreatLevel):(?P<threat_level>.+)\n",
+                    r"(ProcessID):(?P<process_id>.+)\n",
+                    r"(ProcessCreationTime):(?P<process_creation_time>.+)\n",
+                    r"(SessionID):(?P<session_id>.+)\n",
+                    r"(CreationTime):(?P<ts>.+)\n",
+                    r"(ImagePath):(?P<image_path>.+)\n",
+                    r"(Taint Info):(?P<taint_info>.+)\n",
+                    r"(Operations):(?P<operations>.+)\n",
+                    r"END BM telemetry",
+                ]
+            )
+        ),
+        DefenderMPLogBMTelemetryRecord,
+    ),
+]
+
+DEFENDER_MPLOG_LINE = re.compile(r"^\s+(.*)$", re.MULTILINE)