From 816f94c4262d84f15731691b9e17b5457e0ac035 Mon Sep 17 00:00:00 2001 From: Dandaedre Date: Tue, 15 Sep 2026 22:47:19 +0200 Subject: [PATCH] feat: migrate first diagnostic event rule batch --- AGENTS-TASKS.md | 16 +++++++ README.md | 7 +-- docs/diagnostic-contract.md | 8 ++-- docs/rules.md | 34 ++++++++++++++ schemas/diagnostic.schema.json | 9 ++++ tests/test_analyse.py | 43 +++++++++++++++++ tests/test_contract.py | 1 + tools/analyse.py | 85 ++++++++++++++++++++++++++++++++-- 8 files changed, 192 insertions(+), 11 deletions(-) create mode 100644 docs/rules.md diff --git a/AGENTS-TASKS.md b/AGENTS-TASKS.md index c5fad24..4a5a38d 100644 --- a/AGENTS-TASKS.md +++ b/AGENTS-TASKS.md @@ -87,6 +87,22 @@ valid diagnostic result independently of reporting tools. ## Handoff log +### 2026-09-15 — First event-rule migration batch + +- Advanced WD3.1 with 15 reviewed rules covering bugchecks, dump generation, + storage/TPM, services, NDIS, application failures, Windows Update, MSI, shadow + copies, DCOM and unexpected shutdown. The remaining 38 rules and seven watchlist + matchers keep WD3.1 open. +- Added optional diagnostic v1 `age_days` and `relevance_weight` fields so fading + rules retain the legacy 7-to-90-day relevance curve without changing technical + confidence. Reference time remains explicit and partial captures still cap + confidence independently. +- Validation: 21 diagnostic tests pass, including an exact provider/ID/severity/ + confidence catalog assertion and old-event fading. No remediation text entered + the diagnostic engine. +- Next: migrate the next event-rule batch, then implement watchlist matching and + explicit correlation coverage under WD3.2. + ### 2026-09-15 — First offline analyser slice - Completed WD1.4, WD2.3–WD2.4, WD3.3–WD3.5 and WD4.1 for the bounded first diff --git a/README.md b/README.md index f59a5f3..c34a187 100644 --- a/README.md +++ b/README.md @@ -43,11 +43,12 @@ python tools/analyse.py /path/to/capture.json \ ``` It normalizes collection coverage, preserves event values and JSON Pointers, -implements the reviewed Service Control Manager Event 7000 rule, and leaves all -other events explicitly `unanalysed`. Reference time and producer version are +and implements the first 15 reviewed event rules. 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. Remaining rules and native Windows collection are still migration work. +CLI usage. See the [rule migration status](docs/rules.md). Remaining rules, +watchlist matching, and native Windows collection are still migration work. ## License diff --git a/docs/diagnostic-contract.md b/docs/diagnostic-contract.md index 9629689..abf75ef 100644 --- a/docs/diagnostic-contract.md +++ b/docs/diagnostic-contract.md @@ -69,7 +69,9 @@ JSON Pointers escape `~` as `~0` and `/` as `~1`; the empty pointer names the ro A finding has `id`, `severity` (`critical`, `warning`, `info`, `unanalysed`), `confidence` (number 0–100), `title`, `description`, and a nonempty `evidence` list -of observation IDs. Confidence describes strength of the finding, not the chance +of observation IDs. Optional `age_days` and `relevance_weight` (0.5–1) preserve +the migrated rule catalog's time-fading behavior without changing the underlying +technical confidence. Confidence describes strength of the finding, not the chance that the system is healthy. IDs are opaque tokens; producers must keep them stable for repeated analysis of the same evidence/rule. The future analyzer must document its ID derivation. The validator rejects duplicate IDs and dangling observation @@ -97,8 +99,8 @@ python tools/analyse.py capture.json \ Input must be inside the explicit evidence root so output retains a portable source path. Existing output requires `--force`. Exit codes are 0 for a validated artifact, 1 for input, validation, or I/O failure, and 2 for invalid invocation. -The current rule catalog contains only Service Control Manager Event 7000; other -captured events remain traceable `unanalysed` findings. +The current rule catalog contains the first 15 reviewed event classifications; +other captured events remain traceable `unanalysed` findings. See [rules.md](rules.md). ## Mapping legacy captures diff --git a/docs/rules.md b/docs/rules.md new file mode 100644 index 0000000..45e2c4d --- /dev/null +++ b/docs/rules.md @@ -0,0 +1,34 @@ +# Migrated diagnostic rules + +The event catalog is migrating in reviewed batches from legacy renderer revision +`1d381904fff3d378a7c0e04588e75310a9b7ed60`. Win Diagnostics retains only +technical matching, severity, confidence, rationale, and time relevance. Report +remediation and recipient recommendations are intentionally excluded. + +## Batch 1 + +| Provider | Event ID | Severity | Confidence | Fading | +| --- | ---: | --- | ---: | --- | +| Microsoft-Windows-WER-SystemErrorReporting | 1001 | critical | 100 | no | +| volmgr | 162 | info | 100 | no | +| stornvme | 11 | critical | 92 | no | +| Microsoft-Windows-TPM-WMI | 1040 | critical | 85 | no | +| Service Control Manager | 7000 | warning | 90 | yes | +| Service Control Manager | 7009 | warning | 82 | yes | +| Microsoft-Windows-NDIS | 10317 | warning | 78 | no | +| Application Error | 1000 | warning | 75 | yes | +| Microsoft-Windows-WindowsUpdateClient | 20 | warning | 88 | yes | +| Application Hang | 1002 | warning | 70 | yes | +| MsiInstaller | 1043 | warning | 80 | yes | +| Volsnap | 36 | warning | 82 | no | +| Service Control Manager | 7043 | warning | 75 | yes | +| Microsoft-Windows-DistributedCOM | 10010 | info | 65 | no | +| EventLog | 6008 | warning | 95 | no | + +Fading begins after seven calendar days and reaches a floor of 0.5 at 90 days, +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. diff --git a/schemas/diagnostic.schema.json b/schemas/diagnostic.schema.json index 4a0e9aa..3b59ceb 100644 --- a/schemas/diagnostic.schema.json +++ b/schemas/diagnostic.schema.json @@ -210,6 +210,15 @@ "minimum": 0, "maximum": 100 }, + "relevance_weight": { + "type": "number", + "minimum": 0.5, + "maximum": 1 + }, + "age_days": { + "type": "integer", + "minimum": 0 + }, "title": { "type": "string", "pattern": "\\S" diff --git a/tests/test_analyse.py b/tests/test_analyse.py index 169690c..68a4f72 100644 --- a/tests/test_analyse.py +++ b/tests/test_analyse.py @@ -52,6 +52,39 @@ class AnalyseTests(unittest.TestCase): self.assertEqual(observation["source_pointer"], "/sections/recent_system_errors/data/0") self.assertEqual(observation["value"]["Id"], 7000) + def test_first_rule_batch_matches_reviewed_severity_and_confidence(self): + expected = { + ("Microsoft-Windows-WER-SystemErrorReporting", 1001): ("critical", 100), + ("volmgr", 162): ("info", 100), ("stornvme", 11): ("critical", 92), + ("Microsoft-Windows-TPM-WMI", 1040): ("critical", 85), + ("Service Control Manager", 7000): ("warning", 90), + ("Service Control Manager", 7009): ("warning", 82), + ("Microsoft-Windows-NDIS", 10317): ("warning", 78), + ("Application Error", 1000): ("warning", 75), + ("Microsoft-Windows-WindowsUpdateClient", 20): ("warning", 88), + ("Application Hang", 1002): ("warning", 70), + ("MsiInstaller", 1043): ("warning", 80), ("Volsnap", 36): ("warning", 82), + ("Service Control Manager", 7043): ("warning", 75), + ("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) + capture = analyser.validation.load_json(FIXTURES / "windiagnostics-v1.json") + capture = copy.deepcopy(capture) + events = [{"TimeCreated": "2026-09-14T12:00:00Z", "ProviderName": provider, + "Id": event_id, "Message": "Synthetic matching event"} + for provider, event_id in expected] + capture["sections"]["recent_system_errors"]["data"] = events + capture["sections"]["recent_system_errors"]["count"] = len(events) + result = analyser.analyse(capture, "capture.json", "0" * 64, + self.reference_time, "test-revision") + self.assertEqual(len(result["findings"]), len(expected)) + self.assertEqual({(finding["title"].rsplit(" event ", 1)[0], + int(finding["title"].rsplit(" event ", 1)[1])): + (finding["severity"], finding["confidence"]) + for finding in result["findings"]}, expected) + def test_unknown_duplicate_events_are_grouped_without_interpretation(self): result = self.run_fixture("windiagnostics-v2-full.json") self.assertEqual(len(result["findings"]), 1) @@ -69,6 +102,16 @@ class AnalyseTests(unittest.TestCase): self.assertEqual(result["collection"]["status"], "partial") self.assertEqual(result["findings"][0]["confidence"], 50) + def test_fading_uses_explicit_reference_time(self): + capture = analyser.validation.load_json(FIXTURES / "windiagnostics-v1.json") + capture = copy.deepcopy(capture) + capture["sections"]["recent_system_errors"]["data"][0]["TimeCreated"] = "2025-01-01T00:00:00Z" + result = analyser.analyse(capture, "capture.json", "0" * 64, + self.reference_time, "test-revision") + finding = result["findings"][0] + self.assertGreater(finding["age_days"], 90) + self.assertEqual(finding["relevance_weight"], 0.5) + def test_unsupported_status_is_preserved_as_limitation(self): result = self.run_fixture("windiagnostics-v2-partial.json") unexpected = [section for section in result["collection"]["sections"].values() diff --git a/tests/test_contract.py b/tests/test_contract.py index 85eae39..a793bcb 100644 --- a/tests/test_contract.py +++ b/tests/test_contract.py @@ -29,6 +29,7 @@ class DiagnosticContractTests(unittest.TestCase): (("metadata", "analysis_reference_time"), "2026-09-15T12:00:00"), (("findings", 0, "confidence"), 101), (("findings", 0, "confidence"), -1), (("findings", 0, "confidence"), "90"), (("findings", 0, "confidence"), True), + (("findings", 0, "relevance_weight"), 0.4), (("findings", 0, "age_days"), -1), (("findings", 0, "evidence"), []), (("findings", 0, "title"), " "), (("findings", 0, "severity"), "healthy"), (("observations", 0, "source_pointer"), "/broken~2escape"), diff --git a/tools/analyse.py b/tools/analyse.py index 6c2e333..b77fe50 100644 --- a/tools/analyse.py +++ b/tools/analyse.py @@ -19,11 +19,67 @@ validation = importlib.util.module_from_spec(spec) spec.loader.exec_module(validation) EVENT_RULES = { + ("Microsoft-Windows-WER-SystemErrorReporting", 1001): { + "severity": "critical", "confidence": 100, + "description": "Windows reports a reboot following a kernel bugcheck. The stop code and saved dump confirm a crash but do not identify its cause.", + }, + ("volmgr", 162): { + "severity": "info", "confidence": 100, + "description": "Windows records successful crash-dump generation; this supports a crash finding rather than proving a storage failure.", + }, + ("stornvme", 11): { + "severity": "critical", "confidence": 92, + "description": "The storage controller path reported an I/O controller error.", + }, + ("Microsoft-Windows-TPM-WMI", 1040): { + "severity": "critical", "confidence": 85, + "description": "Pre-attestation health checks reported a critical component failure.", + }, ("Service Control Manager", 7000): { "severity": "warning", "confidence": 90, - "title": "Service Control Manager event 7000", "description": "A configured service or driver failed to start.", + "fading": True, + }, + ("Service Control Manager", 7009): { + "severity": "warning", "confidence": 82, "fading": True, + "description": "A service did not connect before the Service Control Manager timeout.", + }, + ("Microsoft-Windows-NDIS", 10317): { + "severity": "warning", "confidence": 78, + "description": "A network miniport failed a transition to operational power; correlation with connectivity symptoms is required.", + }, + ("Application Error", 1000): { + "severity": "warning", "confidence": 75, "fading": True, + "description": "An application terminated unexpectedly; the application, module and exception code require review.", + }, + ("Microsoft-Windows-WindowsUpdateClient", 20): { + "severity": "warning", "confidence": 88, "fading": True, + "description": "An update installation failed.", + }, + ("Application Hang", 1002): { + "severity": "warning", "confidence": 70, "fading": True, + "description": "An application stopped responding and was closed.", + }, + ("MsiInstaller", 1043): { + "severity": "warning", "confidence": 80, "fading": True, + "description": "Windows Installer could not finish a transaction.", + }, + ("Volsnap", 36): { + "severity": "warning", "confidence": 82, + "description": "A volume shadow-copy operation was aborted.", + }, + ("Service Control Manager", 7043): { + "severity": "warning", "confidence": 75, "fading": True, + "description": "A service did not shut down cleanly.", + }, + ("Microsoft-Windows-DistributedCOM", 10010): { + "severity": "info", "confidence": 65, + "description": "A DCOM registration timeout is contextual unless repeated or correlated with symptoms.", + }, + ("EventLog", 6008): { + "severity": "warning", "confidence": 95, + "description": "Windows recorded an unexpected shutdown; this confirms an unclean stop but does not identify its cause.", }, } @@ -47,6 +103,22 @@ def valid_timestamp(value): return value if parsed.tzinfo is not None else None +def fading_metrics(rule, evidence, observations, reference_time): + if not rule.get("fading"): + return {} + observed = [datetime.fromisoformat(observations[item]["observed_at"].replace("Z", "+00:00")) + for item in evidence if "observed_at" in observations[item]] + if not observed: + return {"relevance_weight": 1.0} + reference = datetime.fromisoformat(reference_time.replace("Z", "+00:00")) + age = max(0, (reference.date() - max(observed).date()).days) + if age <= 7: + factor = 1.0 + else: + factor = max(0.5, 1.0 - 0.5 * (age - 7) / (90 - 7)) + return {"relevance_weight": round(factor, 6), "age_days": age} + + def normalize_section(section): if not isinstance(section, dict): return {"status": "unavailable", "record_count": None, "truncated": False, @@ -118,14 +190,17 @@ def analyse(capture, artifact, artifact_hash, reference_time, producer_version): groups.setdefault((provider, event_id), []).append(observation_id) findings = [] + observations_by_id = {item["id"]: item for item in observations} for (provider, event_id), evidence in groups.items(): rule = EVENT_RULES.get((provider, event_id)) if rule: confidence = min(rule["confidence"], 50) if collection_status != "complete" else rule["confidence"] - findings.append({"id": f"event-{slug(provider)}-{slug(event_id)}", - "severity": rule["severity"], "confidence": confidence, - "title": rule["title"], "description": rule["description"], - "evidence": evidence}) + finding = {"id": f"event-{slug(provider)}-{slug(event_id)}", + "severity": rule["severity"], "confidence": confidence, + "title": f"{provider} event {event_id}", + "description": rule["description"], "evidence": evidence} + finding.update(fading_metrics(rule, evidence, observations_by_id, reference_time)) + findings.append(finding) else: findings.append({"id": f"event-{slug(provider)}-{slug(event_id)}", "severity": "unanalysed", "confidence": 0,