docs: simplify diagnostic usage

This commit is contained in:
Dandaedre 2026-09-16 02:02:45 +02:00
parent 5770b61460
commit bf331f6bdb
Signed by: Dandaedre
GPG Key ID: 440C6592E8A26D99
1 changed files with 13 additions and 61 deletions

View File

@ -1,41 +1,22 @@
# 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.
Win Diagnostics turns stored Windows captures into versioned, traceable
`diagnostic.json` files. It does not render PDFs.
```text
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, Typst 0.15 or newer, and standard Unix
utilities. 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:
## Analyse one capture
```bash
bash tools/analyse.sh /path/to/evidence/capture.json \
bash tools/analyse.sh capture.json \
--evidence-root /path/to/evidence \
--output /path/to/diagnostic.json \
--output 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 result records collection coverage, source JSON pointers, reviewed findings,
and unmatched evidence marked `unanalysed`.
Analyse every JSON capture in a directory tree while preserving its relative
path in the output directory:
## Analyse everything in a directory
```bash
bash tools/analyse-all.sh /path/to/captures \
@ -45,42 +26,13 @@ bash tools/analyse-all.sh /path/to/captures \
--producer-version "$(git rev-parse HEAD)"
```
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:
## Validate
```bash
bash tools/validate.sh diagnostic.json --evidence-root /path/to/evidence
bash tools/validate-all.sh /path/to/diagnostics --evidence-root /path/to/evidence
```
Use `bash tools/validate-all.sh DIRECTORY --evidence-root /path/to/evidence`
to validate every JSON diagnostic in a directory tree.
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 |
The fixtures are synthetic and sanitized. See
[docs/standalone.md](docs/standalone.md) for privacy guidance and troubleshooting.
## Contributing
See the [contributor guide](docs/development.md).
## License
The software is licensed under the MIT License. Diagnostic data produced or
processed by the tool retains its own applicable terms.
See [`docs/diagnostic-contract.md`](docs/diagnostic-contract.md) for the file
format, [`docs/standalone.md`](docs/standalone.md) for operating guidance, and
[`docs/development.md`](docs/development.md) for tests and rule maintenance.