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
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:
parent
f93c5d3083
commit
bc319ece29
96
README.md
96
README.md
|
|
@ -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.
|
||||
|
|
|
|||
Reference in New Issue