docs: simplify diagnostic usage
This commit is contained in:
parent
5770b61460
commit
bf331f6bdb
74
README.md
74
README.md
|
|
@ -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.
|
||||
|
|
|
|||
Reference in New Issue