docs: publish user-focused README
Win Diagnostics CI Win Diagnostics failed CI.
Beffroi/win-diagnostics/pipeline/head There was a failure building this commit Details

This commit is contained in:
Dandaedre 2026-09-16 00:42:56 +02:00
parent f93c5d3083
commit bc319ece29
Signed by: Dandaedre
GPG Key ID: 440C6592E8A26D99
1 changed files with 56 additions and 40 deletions

View File

@ -1,60 +1,76 @@
# Win Diagnostics
Win Diagnostics is a toolkit for **collecting and analysing diagnostic information from Windows systems**.
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.
Its goal is to turn raw system evidence into structured, traceable diagnostic findings.
```text id="aj3p4b"
Windows
↓
collect
↓
analyse
↓
diagnostic.json
```text
Windows capture → normalize → analyse → diagnostic.json
```
The structured diagnostic output can be inspected directly or consumed by other tools and reporting systems.
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.
Win Diagnostics does not generate reports or PDFs; diagnostic collection and interpretation are intentionally kept independent from presentation.
## Requirements
## Status
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.
🚧 **Early development / migration**
## Analyse a capture
The project is being progressively rebuilt from the previous `WinDiagnostics` tooling with a cleaner separation between collection, analysis and reporting.
See [AGENT.md](AGENT.md) for repository ownership and development rules.
[AGENTS-TASKS.md](AGENTS-TASKS.md) tracks migration passes, completed work,
acceptance criteria, and the next-pass handoff.
## Contract validation
The version-1 schema, standalone validator, and synthetic examples are available.
See [contract documentation](docs/diagnostic-contract.md) for setup and validation commands.
The first offline analysis slice supports stored legacy capture schemas 1 and 2:
The analyzer accepts stored Win Diagnostics capture schemas 1 and 2:
```bash
bash tools/analyse.sh /path/to/capture.json \
--evidence-root /path/to \
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)"
```
It normalizes collection coverage, preserves event values and JSON Pointers,
and implements all 53 reviewed event rules plus seven candidate watchlist entries. Other events remain explicitly
`unanalysed`. Reference time and producer version are
required for reproducibility. Existing output requires `--force`. Exit codes are
0 for validated output, 1 for input, validation, or I/O failure, and 2 for invalid
CLI usage. See the [rule migration status](docs/rules.md). Native Windows
collection and broader non-event evidence correlation are still migration work.
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.
See [standalone use](docs/standalone.md) for installation, exact commands,
privacy guidance, troubleshooting, and native-collection limitations.
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
bash tools/validate.sh diagnostic.json --evidence-root /path/to/evidence
```
The public format is documented in
[docs/diagnostic-contract.md](docs/diagnostic-contract.md), and the JSON Schema
is available at [schemas/diagnostic.schema.json](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:
```bash
make test
```
The fixtures are synthetic and sanitized. See
[docs/standalone.md](docs/standalone.md) for privacy guidance and troubleshooting.
## License
Software source code is licensed under the **MIT License**.
Diagnostic data produced by the tool is not automatically covered by the software license.
The software is licensed under the MIT License. Diagnostic data produced or
processed by the tool retains its own applicable terms.