295 lines
13 KiB
Python
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())
|