# VEX Evidence Playbook (VEX1–VEX10)

Status: Frozen · Date: 2025-12-04  
Scope: Define deterministic VEX evidence bundles, justification catalog, and verification workflow for reachability evidence chain (Sprint 0401 tasks 62, 64, 65).

## Artifacts (frozen)
- Schema: `docs/benchmarks/vex-evidence-playbook.schema.json`
- Justification catalog (+ DSSE): `docs/benchmarks/vex-justifications.catalog.json`, `docs/benchmarks/vex-justifications.catalog.dsse.json`
- Proof bundle fixtures (+ DSSE): `tests/Vex/ProofBundles/sample-proof-bundle.json`, `tests/Vex/ProofBundles/sample-proof-bundle.dsse.json`, `tests/Vex/ProofBundles/sample-proof-bundle-config.json`, `tests/Vex/ProofBundles/sample-proof-bundle-config.dsse.json`
- CAS evidence set: `tests/Vex/ProofBundles/cas/` (graph, coverage, negative tests, runtime trace, config, flags + DSSE for graph/coverage)
- OpenVEX statement: `tests/Vex/ProofBundles/openvex-sample.json`
- OpenVEX config fixture: `tests/Vex/ProofBundles/openvex-config.json`
- Verifier + tests: `scripts/vex/verify_proof_bundle.py`, `tests/Vex/ProofBundles/test_verify_sample.sh`
- CI guard: `.gitea/workflows/vex-proof-bundles.yml`

## 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; re-evaluate on SBOM/graph/runtime change.
- Provide offline-friendly proof bundle format with CAS paths and DSSE envelopes; mandate OpenVEX canonical serialization and Rekor-ready signature digests.

## Bundle schema (frozen)
- `docs/benchmarks/vex-evidence-playbook.schema.json` (JSON Schema 2020-12):
  - `graph.hash` (BLAKE3-256 preferred) + `graph.dsse`.
  - `openvex` block with canonical SHA-256 + BLAKE3 and statement id.
  - `justification.id` (must exist in catalog) + optional DSSE ref.
  - `entrypoints[]`: `coverage_percent` (must meet min threshold), `negative_tests`, `config_hash`, `flags_hash`.
  - `evidence[]` (graph, coverage, runtime_trace, negative_test, config, flags, sbom, scan, policy) with CAS URI + hash + optional DSSE.
  - `rbac` approvals, `reevaluation` triggers (sbom/graph/runtime true), `uncertainty` state (U0–U3), optional `policy` summary.
  - `signatures[]` with DSSE/JWS envelope digest and optional Rekor metadata.

## Justification catalog
- Canonical JSON, JCS normalized; BLAKE3 + SHA-256 recorded; DSSE sidecar at `docs/benchmarks/vex-justifications.catalog.dsse.json`.
- Fields per entry: `id`, `title`, `description`, `applicability`, `required_evidence`, `expiry_days`, `reevaluate_on`, `rbac`, `policy_links`, `uncertainty_gate`.
- Covers VEX1–VEX10 (vulnerable_code_not_present, component_not_present, config_not_vulnerable, unreachable, runtime guard, compensating control, update staged, analysis ongoing, EOL scope, false positive proven).

## 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` validates schema, catalog membership, DSSE references, CAS hashes, entrypoint coverage/negative tests, RBAC, reevaluation triggers, and uncertainty gates. No network calls; CAS paths resolved via `--cas-root`.
- Quick check: `tests/Vex/ProofBundles/test_verify_sample.sh`

## Fixtures
- `tests/Vex/ProofBundles/sample-proof-bundle.json` (+ DSSE) grounded in CAS artefacts under `tests/Vex/ProofBundles/cas/`.
- `docs/benchmarks/vex-justifications.catalog.json` with VEX1–VEX10 entries and DSSE sidecar.