This repository has been archived on 2026-09-16. You can view files and clone it, but cannot push or open issues or pull requests.
win-diagnostics-analysis/tools/analyse.py

295 lines
13 KiB
Python

#!/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())