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

77 lines
2.4 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. 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
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 |
## 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
The software is licensed under the MIT License. Diagnostic data produced or
processed by the tool retains its own applicable terms.