docs: separate user and contributor guides
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:
Dandaedre 2026-09-16 00:47:06 +02:00
parent bc319ece29
commit 3b139c15db
Signed by: Dandaedre
GPG Key ID: 440C6592E8A26D99
2 changed files with 45 additions and 10 deletions

View File

@ -14,8 +14,8 @@ 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
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
@ -59,17 +59,13 @@ is available at [schemas/diagnostic.schema.json](schemas/diagnostic.schema.json)
| `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.
## Contributing
See the [contributor guide](docs/development.md).
## License
The software is licensed under the MIT License. Diagnostic data produced or

39
docs/development.md Normal file
View File

@ -0,0 +1,39 @@
# Development
This document covers contributor workflows for Win Diagnostics. Runtime usage
is documented in the main [README](../README.md).
## Test environment
Tests require uv. The Makefile creates `.venv`, synchronizes the pinned packages
from `requirements.txt`, and invokes Python only from that environment.
```bash
make test
```
The suite covers diagnostic contract validation, evidence hashes and JSON
Pointers, supported capture schemas, collection limitations, deterministic
analysis, event grouping, the complete rule catalog, watchlist gates, standalone
operation, and the production shell/jq runtime.
## Rule maintenance
Event classifications live in `rules/event-rules.json`; advisory software and
driver checks live in `rules/watchlist.json`. Keep rule descriptions factual and
traceable. A match must not claim causality, exploitation, or hardware failure
without corresponding evidence.
When changing a rule:
1. Add or update a sanitized fixture that exercises the behavior.
2. Verify finding identity, severity, confidence, and evidence references.
3. Confirm incomplete collection cannot imply a healthy result.
4. Run `make test` and `git diff --check`.
## Contract changes
`schemas/diagnostic.schema.json` is a public interface. Preserve compatibility
for existing consumers or introduce a new schema version with documented
mapping. Keep test-only Python support code under `tests/`; production analysis
and validation remain shell/jq based.