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

73 lines
2.3 KiB
Markdown

# 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.
```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, jq, 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:
```bash
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
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 |
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.