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
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
bc319ece29
commit
3b139c15db
16
README.md
16
README.md
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
Reference in New Issue