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/README.md

2.4 KiB

Win Diagnostics

Win Diagnostics converts stored Windows diagnostic captures into structured, traceable findings. Its output is a versioned diagnostic.json artifact that can be reviewed directly or consumed by reporting and automation tools.

Windows capture → normalize → analyse → diagnostic.json

The analyzer records collection coverage, preserves source values and JSON Pointers, groups related events, and keeps unmatched evidence explicitly marked as unanalysed. It does not render reports or PDFs.

Requirements

Runtime analysis requires Bash, jq, and standard Unix utilities. Python and uv are used only for tests. The component has no dependency on Reportist, Beffroi Reports, or the integration workspace.

Analyse a capture

The analyzer accepts stored Win Diagnostics capture schemas 1 and 2:

bash tools/analyse.sh /path/to/evidence/capture.json \
  --evidence-root /path/to/evidence \
  --output /path/to/diagnostic.json \
  --reference-time 2026-09-15T12:00:00Z \
  --producer-version "$(git rev-parse HEAD)"

The input must be inside the evidence root. The reference time makes time-sensitive findings reproducible, and the producer version records the analyzer revision. Existing outputs are rejected unless --force is supplied.

The bundled catalog contains 53 reviewed Windows event rules and seven advisory watchlist definitions. Watchlist matches identify candidates for investigation; they do not assert exploitation or hardware failure.

Validate an artifact

Validate structure, identities, evidence links, source hashes, and referenced raw values with:

bash tools/validate.sh diagnostic.json --evidence-root /path/to/evidence

The public format is documented in docs/diagnostic-contract.md, and the JSON Schema is available at schemas/diagnostic.schema.json.

Exit codes

Code Meaning
0 Analysis or validation succeeded
1 Input, contract, evidence, or I/O failure
2 Invalid command-line usage

Testing

Run the contract, rule, fixture, and standalone tests in a uv-managed environment:

make test

The fixtures are synthetic and sanitized. See docs/standalone.md for privacy guidance and troubleshooting.

License

The software is licensed under the MIT License. Diagnostic data produced or processed by the tool retains its own applicable terms.