From bc319ece292fdfbcdc9ef475930f3878f6235771 Mon Sep 17 00:00:00 2001 From: Dandaedre Date: Wed, 16 Sep 2026 00:42:56 +0200 Subject: [PATCH] docs: publish user-focused README --- README.md | 96 ++++++++++++++++++++++++++++++++----------------------- 1 file changed, 56 insertions(+), 40 deletions(-) diff --git a/README.md b/README.md index ef675e3..2881181 100644 --- a/README.md +++ b/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.