new advisories

docs/reachability/hybrid-attestation.md

@@ -0,0 +1,55 @@
+# Hybrid Reachability Attestation (Graph + Edge-Bundle)
+
+> Decision date: 2025-11-23 · Owners: Scanner Guild, Attestor Guild, Signals Guild, Policy Guild
+
+## 1. Purpose
+- Guarantee replayable, signed reachability evidence with **graph-level DSSE** for every scan while enabling **selective edge-level DSSE bundles** when finer provenance or dispute handling is required.
+- Keep CI/offline bundles lean (graph-first), but allow auditors/regulators to quarantine or prove individual edges without regenerating whole graphs.
+
+## 2. Attestation levels
+- **Level 0 (Graph DSSE) — Required**
+  - Payload: canonical `richgraph-v1` (nodes, edges, roots, graph_hash, analyzer metadata, policy_hash).
+  - Signature: one DSSE envelope per graph; submit digest to Rekor (or mirror) always.
+  - CAS: `cas://reachability/graphs/{blake3}` (body) + `cas://reachability/graphs/{blake3}.dsse` (envelope).
+- **Level 1 (Edge-Bundle DSSE) — Optional/Selective**
+  - Payload: batch of edges (size ≤ 512) with per-edge reason, evidence hashes, `symbol_digest`, `purl`, `confidence`, and `phase`.
+  - Criteria to emit bundles:
+    - Edge reason is `runtime`, `init_array`/constructors/TLS callbacks, or comes from third-party provenance.
+    - Edge is contested/flagged in Unknowns registry or under policy quarantine.
+  - Signature: one DSSE envelope per bundle; Rekor submission **configurable** (default on for contested/high-risk bundles, off for bulk benign bundles in sealed mode).
+  - CAS: `cas://reachability/edges/{graph_hash}/{bundle_id}` JSON + `.../{bundle_id}.dsse`.
+
+## 3. Producer responsibilities
+- **Scanner**
+  - Always emit Level 0 graph + manifest.
+  - When criteria match, emit Level 1 bundles; include `bundle_reason` (e.g., `runtime-hit`, `init-root`, `third-party`, `disputed`).
+  - Canonicalise JSON (sorted keys/arrays) before hashing; BLAKE3 as graph hash, SHA-256 inside bundles.
+- **Attestor/Signer**
+  - Apply DSSE for both levels; respect sovereign crypto modes (FIPS/GOST/SM/PQC) from environment.
+  - Rekor: push graph envelope digests; push edge-bundle digests only when `rekor_publish=true` (policy/default for high-risk bundles).
+
+## 4. Consumer responsibilities
+- **Signals**
+  - Ingest graph DSSE as the canonical source; ingest edge-bundles when present and attach to the same `graph_hash`.
+  - Store per-edge DSSE metadata for quarantine/override flows; surface missing edges as Unknowns only when absent from both graph and bundles.
+- **Policy**
+  - Default trust path: graph DSSE + CAS object.
+  - When an edge is quarantined/contested, drop it from consideration if an edge-bundle DSSE marks it `revoked=true` or if the Unknowns registry lists it with policy quarantine flag.
+  - For “evidence-required” rules, require either (a) graph DSSE + policy_hash match **or** (b) edge-bundle DSSE that covers the vulnerable path edges.
+- **Replay/Bench/CLI**
+  - `stella graph verify` should accept `--graph {hash}` and optional `--edge-bundles` to validate deeper provenance offline.
+
+## 5. Verification and quarantine flows
+- **Happy path**: verify graph DSSE → verify Rekor inclusion (or mirror) → hash graph body → match `graph_hash` in policy/replay manifest → accept.
+- **Dispute/quarantine**: mark specific `edge_id` as `revoked` in an edge-bundle DSSE; Policy/Signals exclude it, recompute reachability, and surface delta in explainers.
+- **Offline**: retain graph DSSE and selected edge-bundles inside replay pack; Rekor proofs cached when available.
+
+## 6. Performance & storage guardrails
+- Default: only graph DSSE is mandatory; edge-bundles capped at 512 edges per envelope and emitted only on criteria above.
+- Rekor flood control: cap edge-bundle Rekor submissions per graph (config `reachability.edgeBundles.maxRekorPublishes`, default 5). Others stay CAS-only.
+- Determinism: bundle ordering = stable sort by `(bundle_reason, edge_id)`; hash before signing.
+
+## 7. Open decisions (tracked in Sprint 0401 tasks 53–56)
+- Rekor publish defaults per deployment tier (regulated vs standard).
+- CLI UX for selective bundle verification.
+- Bench coverage for edge-bundle verification time/size.