4dc7cf834a
Some checks failed
AOC Guard CI / aoc-guard (push) Has been cancelled
AOC Guard CI / aoc-verify (push) Has been cancelled
Concelier Attestation Tests / attestation-tests (push) Has been cancelled
Console CI / console-ci (push) Has been cancelled
Docs CI / lint-and-preview (push) Has been cancelled
Export Center CI / export-ci (push) Has been cancelled
VEX Proof Bundles / verify-bundles (push) Has been cancelled
- Introduced sample proof bundle configuration files for testing, including `sample-proof-bundle-config.dsse.json`, `sample-proof-bundle.dsse.json`, and `sample-proof-bundle.json`. - Implemented a verification script `test_verify_sample.sh` to validate proof bundles against specified schemas and catalogs. - Updated existing proof bundle configurations with new metadata, including versioning, created timestamps, and justification details. - Enhanced evidence entries with expiration dates and hashes for better integrity checks. - Ensured all new configurations adhere to the defined schema for consistency and reliability in testing.
49 lines
3.6 KiB
Markdown
49 lines
3.6 KiB
Markdown
# 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.
|