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.