#!/usr/bin/env python3 """Analyse a stored legacy capture into a validated diagnostic v1 artifact.""" import argparse from collections import OrderedDict from datetime import datetime import hashlib import importlib.util import json import os from pathlib import Path import re import sys import tempfile ROOT = Path(__file__).resolve().parents[1] spec = importlib.util.spec_from_file_location("diagnostic_validation", ROOT / "tools" / "validate.py") 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, "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.", }, } def pointer(*parts): return "/" + "/".join(str(part).replace("~", "~0").replace("/", "~1") for part in parts) def slug(value): result = re.sub(r"[^A-Za-z0-9._:-]+", "-", str(value)).strip("-").lower() return result or "unknown" def valid_timestamp(value): if not isinstance(value, str): return None try: parsed = datetime.fromisoformat(value.replace("Z", "+00:00")) except ValueError: return None 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, "reason": "Legacy section is not an object."} source_status = section.get("status") status = source_status if source_status in ("ok", "skipped", "unavailable") else "unavailable" count = section.get("count") if type(count) is not int or count < 0: data = section.get("data") count = len(data) if isinstance(data, list) else None result = {"status": status, "record_count": count, "truncated": bool(section.get("truncated", False))} if status != "ok": reason = section.get("error") if not isinstance(reason, str) or not reason.strip(): reason = (f"Legacy capture used unsupported section status: {source_status}." if source_status not in ("skipped", "unavailable") else f"Legacy capture marked section {status} without a reason.") result["reason"] = reason return result def selected_event_sections(capture): sections = capture["sections"] version = capture["schema_version"] names = (("recent_system_errors", "recent_application_errors") if version == 1 else ("recent_system_events", "recent_application_events")) return [(name, sections[name]) for name in names if name in sections] def analyse(capture, artifact, artifact_hash, reference_time, producer_version): version = capture.get("schema_version") if type(version) is not int or version not in (1, 2): raise ValueError(f"unsupported legacy capture schema version: {version!r}") if not isinstance(capture.get("sections"), dict): raise ValueError("legacy capture requires an object at /sections") collected_at = valid_timestamp(capture.get("generated_at")) if collected_at is None: raise ValueError("/generated_at: expected a timezone-qualified ISO timestamp") if valid_timestamp(reference_time) is None: raise ValueError("--reference-time: expected a timezone-qualified ISO timestamp") collection_sections = {name: normalize_section(section) for name, section in capture["sections"].items()} complete = bool(collection_sections) and all( section["status"] == "ok" and not section["truncated"] for section in collection_sections.values()) collection_status = "complete" if complete else "partial" observations = [] groups = OrderedDict() for section_name, section in selected_event_sections(capture): data = section.get("data", []) if isinstance(section, dict) else [] if not isinstance(data, list): continue for index, event in enumerate(data): if not isinstance(event, dict): continue observation_id = f"event-{slug(section_name)}-{index + 1}" observation = {"id": observation_id, "section": section_name, "source_pointer": pointer("sections", section_name, "data", index), "value": event} observed_at = valid_timestamp(event.get("TimeCreated")) if observed_at: observation["observed_at"] = observed_at observations.append(observation) provider = str(event.get("ProviderName", "Unknown provider")) raw_event_id = event.get("Id", "unknown") event_id = raw_event_id if type(raw_event_id) in (int, str) else "unknown" 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"] 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, "title": f"Unanalysed event: {provider} / {event_id}", "description": "The event is preserved for review; no migrated technical rule matches it.", "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.") system = {"host": capture.get("host", {})} if isinstance(capture.get("summary"), dict): system["legacy_summary"] = capture["summary"] return { "schema_version": 1, "metadata": {"producer": {"name": "win-diagnostics", "version": producer_version}, "collected_at": collected_at, "analysis_reference_time": reference_time, "source": {"artifact": artifact, "schema_version": version, "sha256": artifact_hash}}, "system": system, "collection": {"mode": capture.get("mode", "Full"), "status": collection_status, "sections": collection_sections}, "observations": observations, "findings": findings, "warnings": warnings, } def analyse_file(input_path, evidence_root, output_path, reference_time, producer_version, force=False): if input_path.is_symlink(): raise ValueError(f"{input_path}: input symlinks are not supported") input_path = input_path.resolve() evidence_root = evidence_root.resolve() output_path = output_path.resolve() if not input_path.is_relative_to(evidence_root): raise ValueError(f"{input_path}: input must be inside --evidence-root") if output_path == input_path: raise ValueError("input and output paths must differ") artifact = input_path.relative_to(evidence_root).as_posix() capture = validation.load_json(input_path) result = analyse(capture, artifact, hashlib.sha256(input_path.read_bytes()).hexdigest(), reference_time, producer_version) errors = validation.validate_document(result) if not errors: errors = validation.verify_evidence(result, evidence_root) if errors: raise ValueError("generated diagnostic is invalid:\n" + "\n".join(errors)) if output_path.exists() and not force: raise ValueError(f"{output_path}: output exists; use --force to replace it") output_path.parent.mkdir(parents=True, exist_ok=True) descriptor, temporary_name = tempfile.mkstemp(prefix=f".{output_path.name}.", dir=output_path.parent) temporary = Path(temporary_name) try: with os.fdopen(descriptor, "w", encoding="utf-8") as stream: json.dump(result, stream, indent=2, ensure_ascii=False, allow_nan=False) stream.write("\n") if force: os.replace(temporary, output_path) else: os.link(temporary, output_path) finally: temporary.unlink(missing_ok=True) return result def parser(): result = argparse.ArgumentParser(description=__doc__) result.add_argument("input", type=Path) result.add_argument("--evidence-root", required=True, type=Path) result.add_argument("--output", required=True, type=Path) result.add_argument("--reference-time", required=True) result.add_argument("--producer-version", required=True) result.add_argument("--force", action="store_true") return result def main(argv=None): args = parser().parse_args(argv) try: analyse_file(args.input, args.evidence_root, args.output, args.reference_time, args.producer_version, args.force) except (OSError, ValueError, KeyError, TypeError, RecursionError) as error: print(f"error: {error}", file=sys.stderr) return 1 print(f"Wrote validated diagnostic v1: {args.output}") return 0 if __name__ == "__main__": sys.exit(main())