Windows diagnostic collection and analysis toolkit producing structured, machine-readable findings from system evidence.
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.
Go to file
Dandaedre bc319ece29
Win Diagnostics CI Win Diagnostics failed CI.
Beffroi/win-diagnostics/pipeline/head There was a failure building this commit Details
docs: publish user-focused README
2026-09-16 00:42:56 +02:00
docs docs: complete non-Python runtime migration 2026-09-16 00:29:32 +02:00
examples feat: define diagnostic v1 contract and evidence validator 2026-09-15 16:32:36 +02:00
rules refactor: port diagnostic runtime to shell and jq 2026-09-16 00:27:49 +02:00
schemas feat: migrate first diagnostic event rule batch 2026-09-15 22:47:19 +02:00
tests refactor: port diagnostic runtime to shell and jq 2026-09-16 00:27:49 +02:00
tools refactor: port diagnostic runtime to shell and jq 2026-09-16 00:27:49 +02:00
.gitignore feat: define diagnostic v1 contract and evidence validator 2026-09-15 16:32:36 +02:00
AGENT.md refactor: port diagnostic runtime to shell and jq 2026-09-16 00:27:49 +02:00
AGENTS-TASKS.md docs: complete non-Python runtime migration 2026-09-16 00:29:32 +02:00
Jenkinsfile refactor: port diagnostic runtime to shell and jq 2026-09-16 00:27:49 +02:00
LICENSE Initial commit 2026-09-15 14:51:04 +02:00
Makefile refactor: port diagnostic runtime to shell and jq 2026-09-16 00:27:49 +02:00
README.md docs: publish user-focused README 2026-09-16 00:42:56 +02:00
requirements.in feat: define diagnostic v1 contract and evidence validator 2026-09-15 16:32:36 +02:00
requirements.txt feat: define diagnostic v1 contract and evidence validator 2026-09-15 16:32:36 +02:00

README.md

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.