stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 16 Releases Wiki Activity
Files
49922dff5ad4435420dac177e832ba4290ceaea9
git.stella-ops.org/docs/benchmarks/vex-evidence-playbook.md
StellaOps Bot 4dc7cf834a
Some checks failed
AOC Guard CI / aoc-guard (push) Has been cancelled
Details
AOC Guard CI / aoc-verify (push) Has been cancelled
Details
Concelier Attestation Tests / attestation-tests (push) Has been cancelled
Details
Console CI / console-ci (push) Has been cancelled
Details
Docs CI / lint-and-preview (push) Has been cancelled
Details
Export Center CI / export-ci (push) Has been cancelled
Details
VEX Proof Bundles / verify-bundles (push) Has been cancelled
Details
Add sample proof bundle configurations and verification script 
- 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.
2025-12-04 08:54:32 +02:00

3.6 KiB
Raw Blame History

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.