From 757866e637945c9316b7eed70ca4ee94881fc2b9 Mon Sep 17 00:00:00 2001 From: Dandaedre Date: Tue, 15 Sep 2026 22:58:05 +0200 Subject: [PATCH] feat: migrate event and watchlist catalogs --- AGENTS-TASKS.md | 20 +++- README.md | 6 +- docs/rules.md | 15 ++- tests/test_analyse.py | 66 +++++++++++- tools/analyse.py | 245 +++++++++++++++++++++++++++++++++++++++++- 5 files changed, 341 insertions(+), 11 deletions(-) diff --git a/AGENTS-TASKS.md b/AGENTS-TASKS.md index 4a5a38d..e266049 100644 --- a/AGENTS-TASKS.md +++ b/AGENTS-TASKS.md @@ -63,8 +63,10 @@ the public interface, with collection limitations documented. Depends on normalized evidence and the diagnostic contract. -- [ ] WD3.1 Port reusable rules and watchlist matching with traceable evidence; keep investigation-specific conclusions and organisational recommendations outside this engine. +- [x] WD3.1 Port reusable rules and watchlist matching with traceable evidence; keep investigation-specific conclusions and organisational recommendations outside this engine. - [ ] WD3.2 Preserve and test event grouping, deduplication, correlation, unknown-event behavior, collection completeness, severity, and confidence. + - Primary event grouping, unknown events, watchlist gates, completeness, severity, + and confidence are covered; reliability-history deduplication remains pending. - [x] WD3.3 Make time-dependent analysis repeatable using a defined reference time; document intentional differences from legacy behavior. - [x] WD3.4 Emit schema-valid `diagnostic.json`; verify every finding's evidence reference resolves and raw observations remain available. - [x] WD3.5 Run sanitized regression fixtures for known diagnostic situations without the original machine; record exact commands and results. @@ -87,6 +89,22 @@ valid diagnostic result independently of reporting tools. ## Handoff log +### 2026-09-15 — Complete event and watchlist catalog + +- Completed WD3.1 and advanced WD3.2 for the selected event-analysis scope: all 53 event rules + and seven candidate watchlist entries are migrated with raw observation links. + Remediation/action text remains outside the diagnostic engine. +- Watchlist matching preserves exact case-insensitive identity, driver basename, + version, enabled-state, prerequisite, and repeated-event gates. Candidate wording + avoids inferring vulnerability exploitation, active conflict, or root cause. +- Added catalog fingerprint, six-candidate fixture, negative gate, and positive + Intel event-correlation tests. Unknown events remain grouped and unanalysed; + incomplete collection stays visible and caps candidate confidence. +- Validation: all 25 diagnostic tests and the complete integration pipeline pass. + Native collection and broader structured hardware/health rules remain open. +- Next: implement reliability-history deduplication and non-event diagnostic checks, + then validate native collection on Windows before claiming full behavior parity. + ### 2026-09-15 — First event-rule migration batch - Advanced WD3.1 with 15 reviewed rules covering bugchecks, dump generation, diff --git a/README.md b/README.md index c34a187..edf9871 100644 --- a/README.md +++ b/README.md @@ -43,12 +43,12 @@ python tools/analyse.py /path/to/capture.json \ ``` It normalizes collection coverage, preserves event values and JSON Pointers, -and implements the first 15 reviewed event rules. Other events remain explicitly +and implements all 53 reviewed event rules plus seven candidate watchlist entries. Other events remain explicitly `unanalysed`. Reference time and producer version are required for reproducibility. Existing output requires `--force`. Exit codes are 0 for validated output, 1 for input, validation, or I/O failure, and 2 for invalid -CLI usage. See the [rule migration status](docs/rules.md). Remaining rules, -watchlist matching, and native Windows collection are still migration work. +CLI usage. See the [rule migration status](docs/rules.md). Native Windows +collection and broader non-event evidence correlation are still migration work. ## License diff --git a/docs/rules.md b/docs/rules.md index 45e2c4d..86c8df5 100644 --- a/docs/rules.md +++ b/docs/rules.md @@ -5,7 +5,7 @@ The event catalog is migrating in reviewed batches from legacy renderer revision technical matching, severity, confidence, rationale, and time relevance. Report remediation and recipient recommendations are intentionally excluded. -## Batch 1 +## Event catalog | Provider | Event ID | Severity | Confidence | Fading | | --- | ---: | --- | ---: | --- | @@ -30,5 +30,14 @@ matching the legacy weighting curve. It is emitted as `relevance_weight` plus `age_days`; technical `confidence` is unchanged. Analysis requires an explicit timezone-qualified reference time, and future-dated evidence has age zero. -The remaining 38 event rules and seven watchlist matchers are pending. Until a -rule is migrated, matching events remain `unanalysed` with their raw evidence. +All 53 legacy event classifications are now migrated. A standalone fingerprint +test locks provider, event ID, severity, confidence, fading flag, and fading +parameters to the reviewed source catalog. Events without a catalog entry remain +`unanalysed` with their raw evidence. + +All seven advisory watchlist entries are also migrated: WinRing0, Dell dbutil, +GIGABYTE OC GURU II 2.08, Intel wireless repeated failures, OBS overlay tools, +OBS audio hooks, and SMBv1. Matches are exact and case-insensitive; driver paths +match by basename, versions and enabled states are enforced where specified, and +OBS/Intel prerequisite gates must pass. Results remain warning-level candidates +whose descriptions explicitly avoid claims of exploitation or causation. diff --git a/tests/test_analyse.py b/tests/test_analyse.py index 68a4f72..b5413b5 100644 --- a/tests/test_analyse.py +++ b/tests/test_analyse.py @@ -1,4 +1,5 @@ import copy +import hashlib import importlib.util import json from pathlib import Path @@ -35,7 +36,7 @@ class AnalyseTests(unittest.TestCase): "windiagnostics-v2-compact.json": ("partial", 0, 0), "windiagnostics-v2-full.json": ("partial", 3, 1), "windiagnostics-v2-partial.json": ("partial", 3, 1), - "windiagnostics-watchlist.json": ("partial", 3, 1), + "windiagnostics-watchlist.json": ("partial", 11, 7), } for name, values in expected.items(): with self.subTest(name=name): @@ -68,8 +69,9 @@ class AnalyseTests(unittest.TestCase): ("Microsoft-Windows-DistributedCOM", 10010): ("info", 65), ("EventLog", 6008): ("warning", 95), } - self.assertEqual({key: (rule["severity"], rule["confidence"]) - for key, rule in analyser.EVENT_RULES.items()}, expected) + actual = {key: (rule["severity"], rule["confidence"]) + for key, rule in analyser.EVENT_RULES.items()} + self.assertEqual({key: actual[key] for key in expected}, expected) capture = analyser.validation.load_json(FIXTURES / "windiagnostics-v1.json") capture = copy.deepcopy(capture) events = [{"TimeCreated": "2026-09-14T12:00:00Z", "ProviderName": provider, @@ -85,6 +87,16 @@ class AnalyseTests(unittest.TestCase): (finding["severity"], finding["confidence"]) for finding in result["findings"]}, expected) + def test_complete_rule_catalog_matches_legacy_classification_metadata(self): + catalog = sorted((provider, event_id, rule["severity"], rule["confidence"], + bool(rule.get("fading")), rule.get("fade_after_days", 7), + rule.get("fade_to_half_days", 90)) + for (provider, event_id), rule in analyser.EVENT_RULES.items()) + encoded = json.dumps(catalog, separators=(",", ":"), ensure_ascii=False).encode() + self.assertEqual(len(catalog), 53) + self.assertEqual(hashlib.sha256(encoded).hexdigest(), + "00c4b492d013a4f10e8a07da1f6a6819010061b3085819f143311b8279b0c7dc") + def test_unknown_duplicate_events_are_grouped_without_interpretation(self): result = self.run_fixture("windiagnostics-v2-full.json") self.assertEqual(len(result["findings"]), 1) @@ -92,6 +104,54 @@ class AnalyseTests(unittest.TestCase): self.assertEqual(result["findings"][0]["confidence"], 0) self.assertEqual(len(result["findings"][0]["evidence"]), 3) + def test_watchlist_fixture_emits_six_traceable_candidates(self): + result = self.run_fixture("windiagnostics-watchlist.json") + findings = {finding["id"]: finding for finding in result["findings"] + if finding["id"].startswith("watchlist-")} + self.assertEqual(set(findings), { + "watchlist-winring0", "watchlist-dell-dbutil", "watchlist-gigabyte-oc-guru", + "watchlist-obs-overlay", "watchlist-obs-audio-hooks", "watchlist-smb1", + }) + self.assertNotIn("watchlist-intel-wifi-observed", findings) + observations = {item["id"]: item for item in result["observations"]} + for finding in findings.values(): + self.assertEqual(finding["severity"], "warning") + self.assertEqual(finding["confidence"], 50) + self.assertTrue(all(item in observations for item in finding["evidence"])) + self.assertIn("/sections/system_drivers/data/0", + {item["source_pointer"] for item in observations.values()}) + + def test_watchlist_exact_version_enabled_and_requirement_gates(self): + capture = analyser.validation.load_json(FIXTURES / "windiagnostics-watchlist.json") + capture = copy.deepcopy(capture) + capture["sections"]["installed_programs"]["data"][2]["DisplayVersion"] = "2.09" + capture["sections"]["enabled_windows_features"]["data"][0]["State"] = 1 + capture["sections"]["installed_programs"]["data"] = [ + item for item in capture["sections"]["installed_programs"]["data"] + if item["DisplayName"] != "OBS Studio"] + result = analyser.analyse(capture, "capture.json", "0" * 64, + self.reference_time, "test-revision") + ids = {finding["id"] for finding in result["findings"]} + self.assertNotIn("watchlist-gigabyte-oc-guru", ids) + self.assertNotIn("watchlist-smb1", ids) + self.assertNotIn("watchlist-obs-overlay", ids) + self.assertNotIn("watchlist-obs-audio-hooks", ids) + + def test_watchlist_event_gate_requires_repeated_matching_events(self): + capture = analyser.validation.load_json(FIXTURES / "windiagnostics-watchlist.json") + capture = copy.deepcopy(capture) + capture["sections"]["system_drivers"]["data"].append( + {"Name": "NETWTW10", "PathName": "C:\\Drivers\\netwtw10.sys", "State": "Running"}) + for event, event_id in zip(capture["sections"]["recent_system_events"]["data"], (5002, 5005)): + event["ProviderName"] = "Netwtw10" + event["Id"] = event_id + result = analyser.analyse(capture, "capture.json", "0" * 64, + self.reference_time, "test-revision") + finding = next(item for item in result["findings"] + if item["id"] == "watchlist-intel-wifi-observed") + self.assertEqual(len(finding["evidence"]), 3) + self.assertTrue(any(item.startswith("event-") for item in finding["evidence"])) + def test_partial_collection_caps_known_rule_confidence(self): capture = analyser.validation.load_json(FIXTURES / "windiagnostics-v1.json") capture = copy.deepcopy(capture) diff --git a/tools/analyse.py b/tools/analyse.py index b77fe50..af5ab75 100644 --- a/tools/analyse.py +++ b/tools/analyse.py @@ -81,8 +81,197 @@ EVENT_RULES = { "severity": "warning", "confidence": 95, "description": "Windows recorded an unexpected shutdown; this confirms an unclean stop but does not identify its cause.", }, + ("Service Control Manager", 7023): { + "severity": "warning", "confidence": 88, "fading": True, + "description": "A service terminated and returned an error; impact depends on the named service and whether its function is needed.", + }, + ("MsiInstaller", 11704): { + "severity": "warning", "confidence": 92, "fading": True, + "description": "Windows Installer reported a suspended installation that blocked another product transaction.", + }, + ("MsiInstaller", 11722): { + "severity": "warning", "confidence": 92, "fading": True, + "description": "A program executed by an MSI package did not complete as expected, so the installation was not successful.", + }, + ("VSS", 12344): { + "severity": "warning", "confidence": 82, + "description": "A Volume Shadow Copy writer failed during its freeze operation; backups or restore points near that time may be incomplete.", + }, + (".NET Runtime", 1022): { + "severity": "info", "confidence": 80, + "description": "The process could not initialize profiler-attach support; this is contextual unless profiling was expected.", + }, + ("Waterfox Default Browser Agent", 5): { + "severity": "info", "confidence": 55, + "description": "The captured event has no message, so it provides no actionable evidence by itself.", + }, + ("Microsoft-Windows-Kernel-Boot", 29): { + "severity": "warning", "confidence": 92, + "description": "Windows failed Fast Startup; the status and adjacent shutdown events do not establish the underlying cause.", + }, + ("Service Control Manager", 7031): { + "severity": "warning", "confidence": 95, + "description": "A service terminated unexpectedly; Windows may schedule a recovery action.", + }, + ("Microsoft-Windows-DeviceAssociationService", 3505): { + "severity": "warning", "confidence": 70, + "description": "Device association failed during pairing enumeration; the message does not identify a failed hardware component.", + }, + ("Microsoft-Windows-HAL", 15): { + "severity": "warning", "confidence": 90, + "description": "The IOMMU reported an error; its raw identifier does not identify a component or prove physical failure.", + }, + ("Microsoft-Windows-HAL", 21): { + "severity": "warning", "confidence": 90, + "description": "The ACPI time/alarm method failed while Windows attempted to set the hardware real-time clock.", + }, + ("usbaudio2", 38): { + "severity": "warning", "confidence": 90, + "description": "A USB audio control request failed.", + }, + ("ESENT", 419): { + "severity": "critical", "confidence": 95, + "description": "The database engine could not read a database page; the recorded error identifies the failure class.", + }, + ("ESENT", 474): { + "severity": "critical", "confidence": 98, + "description": "A database page failed checksum verification; this confirms corrupt read data but does not isolate its cause.", + }, + ("ESENT", 907): { + "severity": "critical", "confidence": 95, + "description": "ESENT detected a transient memory problem; this is a stability signal, not proof of a defective RAM module.", + }, + ("ESENT", 908): { + "severity": "critical", "confidence": 95, + "description": "The database process terminated after a fatal error; its error code and adjacent ESENT events require correlation.", + }, + ("Microsoft-Windows-Defrag", 264): { + "severity": "warning", "confidence": 92, + "description": "Storage optimization did not complete; an unsupported filesystem is not evidence of a failing disk.", + }, + ("Microsoft-Windows-WLAN-AutoConfig", 10002): { + "severity": "info", "confidence": 85, + "description": "A WLAN extension stopped; this can accompany adapter shutdown or reset and does not establish a driver defect.", + }, + ("Microsoft-Windows-DistributedCOM", 10016): { + "severity": "info", "confidence": 90, + "description": "DCOM denied an activation request; common Windows component instances are expected and do not alone establish a fault.", + }, + ("Netwtw10", 6062): { + "severity": "info", "confidence": 60, + "description": "The driver logged an LSO trigger; the message alone does not establish adapter failure.", + }, + ("Microsoft-Windows-Hyper-V-Hypervisor", 167): { + "severity": "warning", "confidence": 90, + "description": "VM side-channel mitigations were not enabled with HyperThreading; this is a security configuration signal.", + }, + ("volmgr", 161): { + "severity": "warning", "confidence": 95, + "description": "Windows could not create a crash dump; this reduces crash evidence without identifying the crash cause.", + }, + ("Microsoft-Windows-WinRM", 10149): { + "severity": "info", "confidence": 90, + "description": "WinRM is not listening for remote-management requests; this may be intentional.", + }, + ("winsrvext", 100): { + "severity": "info", "confidence": 85, + "description": "The named process delayed shutdown; a brief delay does not establish system instability.", + }, + ("Netwtw10", 5005): { + "severity": "warning", "confidence": 95, + "description": "The Intel wireless driver reported an internal adapter error and failure.", + }, + ("Netwtw10", 5032): { + "severity": "warning", "confidence": 90, + "description": "The Intel wireless miniport reset watchdog was triggered.", + }, + ("Netwtw10", 5002): { + "severity": "warning", "confidence": 95, + "description": "The Intel driver reported an adapter malfunction.", + }, + ("Netwtw10", 5010): { + "severity": "warning", "confidence": 95, + "description": "The wireless adapter returned an invalid value to the Intel driver.", + }, + ("Microsoft-Windows-Perflib", 1008): { + "severity": "warning", "confidence": 90, + "description": "A performance-counter provider failed to open; counters may be unavailable without implying hardware failure.", + }, + ("Microsoft-Windows-WMI", 63): { + "severity": "info", "confidence": 90, + "description": "A WMI provider registered with LocalSystem privileges; this describes a privilege boundary, not proof of exploitation.", + }, + ("Microsoft-Windows-Winlogon", 6004): { + "severity": "warning", "confidence": 80, + "description": "A Winlogon notification subscriber failed; impact depends on the subscriber and affected operation.", + }, + ("Microsoft-Windows-RestartManager", 10010): { + "severity": "info", "confidence": 85, + "description": "Restart Manager could not restart an application across the reported security identity boundary.", + }, + ("Microsoft-Windows-Search", 10024): { + "severity": "warning", "confidence": 85, + "description": "Windows Search terminated a filter host that stopped responding; indexing or a file-format filter may be affected.", + }, + ("Microsoft-Windows-CodeIntegrity", 3116): { + "severity": "info", "confidence": 95, + "description": "Policy signature metadata was recorded; this message does not report a blocked driver.", + }, + ("Microsoft-Windows-CodeIntegrity", 3099): { + "severity": "info", "confidence": 95, + "description": "An App Control policy was loaded; activation is not itself a driver failure.", + }, + ("Microsoft-Windows-CodeIntegrity", 3085): { + "severity": "info", "confidence": 90, + "description": "WHQL signing requirements were not enforced for this boot; other signature checks may still be active.", + }, + ("Microsoft-Windows-CodeIntegrity", 3076): { + "severity": "warning", "confidence": 95, + "description": "App Control audit policy would have blocked a file; audit mode did not block it.", + }, + ("Microsoft-Windows-CodeIntegrity", 3077): { + "severity": "warning", "confidence": 95, + "description": "App Control blocked a file that did not satisfy its policy.", + }, } +WATCHLIST = ( + {"id": "winring0", "title": "WinRing0 low-level driver vulnerability candidate", + "match": ({"section": "system_drivers", "field": "PathName", "basename": True, + "values": ("WinRing0.sys", "WinRing0x64.sys")},), + "description": "Microsoft documents WinRing0 as vulnerable; a filename match does not verify the binary or prove exploitation."}, + {"id": "dell-dbutil", "title": "Dell dbutil_2_3 driver vulnerability candidate", + "match": ({"section": "system_drivers", "field": "PathName", "basename": True, + "values": ("dbutil_2_3.sys",)},), + "description": "Dell documents an access-control vulnerability in dbutil_2_3.sys; file identity and remediation state require verification."}, + {"id": "gigabyte-oc-guru", "title": "GIGABYTE OC GURU II 2.08 vulnerability candidate", + "match": ({"section": "installed_programs", "field": "DisplayName", + "values": ("OC GURU II", "GIGABYTE OC GURU II"), + "version_field": "DisplayVersion", "versions": ("2.08",)},), + "description": "The vendor lists this exact software version as affected; other versions are not inferred to be affected."}, + {"id": "intel-wifi-observed", "title": "Intel wireless driver repeated-failure candidate", + "match": ({"section": "system_drivers", "field": "Name", "values": ("Netwtw10",)},), + "events": {"provider": "Netwtw10", "ids": ("5002", "5005", "5010", "5032"), "minimum": 2}, + "description": "An installed Intel wireless driver has repeated matching failure signals; correlation does not prove a shared defect or cause."}, + {"id": "obs-overlay", "title": "OBS and overlay-tool conflict candidate", + "match": ({"section": "installed_programs", "field": "DisplayName", + "values": ("MSI Afterburner", "RivaTuner Statistics Server", "EVGA Precision X1", + "ASUS GPU Tweak II", "Overwolf", "FRAPS")},), + "requires": ({"section": "installed_programs", "field": "DisplayName", "values": ("OBS Studio",)},), + "description": "OBS documents possible hook conflicts with these overlay tools; co-installation does not prove simultaneous use or failure."}, + {"id": "obs-audio-hooks", "title": "OBS and audio-enhancement conflict candidate", + "match": ({"section": "installed_programs", "field": "DisplayName", + "values": ("Nahimic", "Nahimic Audio", "Sonic Radar", "Sonic Studio")}, + {"section": "services", "field": "Name", "values": ("NahimicService",)}), + "requires": ({"section": "installed_programs", "field": "DisplayName", "values": ("OBS Studio",)},), + "description": "OBS documents possible interference from these audio tools; installation does not establish an active conflict."}, + {"id": "smb1", "title": "SMBv1 enabled security-risk candidate", + "match": ({"section": "enabled_windows_features", "field": "FeatureName", + "values": ("SMB1Protocol", "SMB1Protocol-Client", "SMB1Protocol-Server"), + "enabled_only": True},), + "description": "Microsoft documents significant SMBv1 vulnerabilities; an enabled feature is not evidence of an attack."}, +) + def pointer(*parts): return "/" + "/".join(str(part).replace("~", "~0").replace("/", "~1") for part in parts) @@ -141,6 +330,31 @@ def normalize_section(section): return result +def watch_matches(capture, matcher): + section = capture["sections"].get(matcher["section"]) + if not isinstance(section, dict) or section.get("status") != "ok": + return [] + data = section.get("data") + if not isinstance(data, list): + return [] + expected = {str(value).casefold() for value in matcher["values"]} + matches = [] + for index, item in enumerate(data): + if not isinstance(item, dict): + continue + value = str(item.get(matcher["field"], "")).strip() + identity = value.strip('"').replace("\\", "/").rsplit("/", 1)[-1] if matcher.get("basename") else value + if identity.casefold() not in expected: + continue + versions = matcher.get("versions") + if versions and str(item.get(matcher.get("version_field", "DriverVersion"), "")) not in versions: + continue + if matcher.get("enabled_only") and item.get("State") not in (2, "Enabled", "enabled"): + continue + matches.append((matcher["section"], index, item)) + return matches + + def selected_event_sections(capture): sections = capture["sections"] version = capture["schema_version"] @@ -208,10 +422,39 @@ def analyse(capture, artifact, artifact_hash, reference_time, producer_version): "description": "The event is preserved for review; no migrated technical rule matches it.", "evidence": evidence}) + for entry in WATCHLIST: + matches = [match for matcher in entry["match"] for match in watch_matches(capture, matcher)] + requirement_groups = [watch_matches(capture, matcher) for matcher in entry.get("requires", ())] + if not matches or any(not group for group in requirement_groups): + continue + event_gate = entry.get("events") + event_evidence = [] + if event_gate: + wanted_ids = set(event_gate["ids"]) + event_evidence = [item["id"] for item in observations + if str(item["value"].get("ProviderName", "")) == event_gate["provider"] + and str(item["value"].get("Id", "")) in wanted_ids] + if len(event_evidence) < event_gate["minimum"]: + continue + evidence = [] + for section_name, index, item in matches + [match for group in requirement_groups for match in group]: + observation_id = f"watch-{slug(entry['id'])}-{slug(section_name)}-{index + 1}" + if observation_id not in {observation["id"] for observation in observations}: + observations.append({"id": observation_id, "section": section_name, + "source_pointer": pointer("sections", section_name, "data", index), + "value": item}) + if observation_id not in evidence: + evidence.append(observation_id) + evidence.extend(item for item in event_evidence if item not in evidence) + findings.append({"id": f"watchlist-{entry['id']}", "severity": "warning", + "confidence": 50 if collection_status != "complete" else 85, + "title": entry["title"], "description": entry["description"], + "evidence": evidence}) + warnings = [str(item) for item in capture.get("warnings", []) if str(item).strip()] if collection_status != "complete": warnings.append("Legacy capture collection is incomplete; finding confidence is capped at 50.") - warnings.append(f"Initial migrated analyser supports {len(EVENT_RULES)} event rule; unmatched events remain unanalysed.") + warnings.append(f"Migrated analyser supports {len(EVENT_RULES)} event rules and {len(WATCHLIST)} candidate watchlist entries; unmatched events remain unanalysed.") system = {"host": capture.get("host", {})} if isinstance(capture.get("summary"), dict): system["legacy_summary"] = capture["summary"]