e1262eb916
- Introduced a new JSON fixture `receipt-input.json` containing base, environmental, and threat metrics for CVSS scoring. - Added corresponding SHA256 hash file `receipt-input.sha256` to ensure integrity of the JSON fixture.
43 lines
2.4 KiB
Markdown
43 lines
2.4 KiB
Markdown
# VEX Evidence Playbook (VEX1–VEX10)
|
||
|
||
Status: Draft · Date: 2025-12-03
|
||
Scope: Define deterministic VEX evidence bundles, justification catalog, and verification workflow for reachability evidence chain (Sprint 0401 tasks 62, 64, 65).
|
||
|
||
## Goals
|
||
- Publish signed VEX justification catalog with DSSE predicates and canonical hashes.
|
||
- Require entry-point coverage %, negative tests, and config/flag hash enforcement for each justification.
|
||
- Provide offline-friendly proof bundle format with CAS paths and DSSE envelopes.
|
||
|
||
## Bundle schema (draft)
|
||
- `proofBundle.schema.json` (to be placed under `docs/benchmarks/vex-evidence-playbook.schema.json`):
|
||
- `id`, `version`, `createdAt`, `createdBy`.
|
||
- `graph_hash` (BLAKE3-256), `graph_dsse` (sha256 of envelope).
|
||
- `entrypoints[]` with `id`, `coverage_percent`, `negative_tests` (bool), `config_hash` (sha256), `flags_hash` (sha256).
|
||
- `justification_id` (must exist in justification catalog), `justification_dsse` (optional hash).
|
||
- `evidence[]` items with `type` (`trace`, `coverage`, `sbom`, `scan`, `policy`), `cas_uri`, `hash`, `dsse` (optional), `expiresAt`.
|
||
- `signatures[]` DSSE/JWS entries with `keyId`, `sig`, `envelopeDigest`.
|
||
|
||
## Justification catalog
|
||
- Canonical JSON, JCS normalized; BLAKE3 + SHA-256 recorded.
|
||
- Fields: `id`, `title`, `description`, `applicability` (list of predicates), `required_evidence` (array of types/hashes), `expiry`, `policy_links`.
|
||
- Signed with DSSE predicate `stella.ops/vexJustification@v1`.
|
||
|
||
## Determinism rules
|
||
- Canonical JSON with sorted keys; arrays sorted by `id`.
|
||
- Timestamps UTC `Z`; strip milliseconds unless non-zero.
|
||
- Hashes: primary BLAKE3-256, secondary SHA-256 for interoperability.
|
||
- DSSE subject = canonical JSON hash; verifier must check hash + signature.
|
||
|
||
## Offline verification
|
||
- `scripts/vex/verify_proof_bundle.py` (to be authored) validates schema, hashes, DSSE, and CAS availability.
|
||
- No network calls; CAS paths resolved locally via `--cas-root`.
|
||
|
||
## Fixtures (to add)
|
||
- `tests/Vex/ProofBundles/sample-proof-bundle.json` with matching DSSE.
|
||
- `docs/benchmarks/vex-justifications.catalog.json` with 5 sample justifications (VEX1–VEX5).
|
||
|
||
## Next steps
|
||
- Freeze `proofBundle.schema.json` and justification catalog hashes.
|
||
- Implement `verify_proof_bundle.py` and add CI job to run it over fixtures.
|
||
- Wire sprint 0401 tasks 62/64/65 to these artifacts; update Decisions & Risks once frozen.
|