git.stella-ops.org/docs/reachability/hybrid-attestation.md

Hybrid Reachability Attestation (Graph + Edge-Bundle)

Decision date: 2025-12-11 · Owners: Scanner Guild, Attestor Guild, Signals Guild, Policy Guild

0. Context: Four Capabilities

This document supports Signed Reachability—one of four capabilities no competitor offers together:

1. Signed Reachability – Every reachability graph is sealed with DSSE; optional edge-bundle attestations for runtime/init/contested paths. Both static call-graph edges and runtime-derived edges can be attested—true hybrid reachability.
2. Deterministic Replay – Scans run bit-for-bit identical from frozen feeds and analyzer manifests.
3. Explainable Policy (Lattice VEX) – Evidence-linked VEX decisions with explicit "Unknown" state handling.
4. Sovereign + Offline Operation – FIPS/eIDAS/GOST/SM/PQC profiles and offline mirrors as first-class toggles.

All evidence is sealed in Decision Capsules for audit-grade reproducibility.

---

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.
• Support hybrid reachability by attesting both static call-graph edges and runtime-derived edges.

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.
  • For hybrid reachability: tag edges with source: static or source: runtime to distinguish call-graph derived vs. runtime-observed edges.
• 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.
• Sovereign Verification Mode: Even with no internet, all signatures and transparency proofs can be locally verified using Offline Update Kits.

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. Hybrid Reachability Details

Stella Ops provides true hybrid reachability by combining:

Signal Type	Source	Attestation
Static call-graph edges	IL/bytecode analysis, framework routing models, entry-point proximity	Graph DSSE (Level 0)
Runtime-observed edges	EventPipe, JFR, Node inspector, Go/Rust probes	Edge-bundle DSSE (Level 1) with source: runtime

Why hybrid matters:

• Static analysis catches code paths that may not execute during observed runtime
• Runtime analysis catches dynamic dispatch, reflection, and framework-injected paths
• Combining both provides confidence across build and runtime contexts
• Each edge type is separately attestable for audit and dispute resolution

Evidence linking: Each edge in the graph or bundle includes evidenceRefs pointing to the underlying proof artifacts (static analysis artifacts, runtime traces), enabling evidence-linked VEX decisions.

8. Decisions (Frozen 2025-12-13)

8.1 DSSE/Rekor Budget by Deployment Tier

Tier	Graph DSSE	Edge-Bundle DSSE	Rekor Publish	Max Bundles/Graph
Regulated (SOC2, FedRAMP, PCI)	Required	Required for runtime/contested	Required	10
Standard	Required	Optional (criteria-based)	Graph only	5
Air-gapped	Required	Optional	Offline checkpoint	5
Dev/Test	Optional	Optional	Disabled	Unlimited

Budget enforcement:

• Graph DSSE: Always submit digest to Rekor (or offline checkpoint for air-gapped)
• Edge-bundle DSSE: Submit to Rekor only when bundle_reason is disputed, runtime-hit, or security-critical
• Cap enforced by reachability.edgeBundles.maxRekorPublishes config (per tier defaults above)

8.2 Signing Layout and CAS Paths

cas://reachability/
  graphs/
    {blake3}/                  # richgraph-v1 body (JSON)
    {blake3}.dsse              # Graph DSSE envelope
    {blake3}.rekor             # Rekor inclusion proof (optional)
  edges/
    {graph_hash}/
      {bundle_id}.json         # Edge bundle body
      {bundle_id}.dsse         # Edge bundle DSSE envelope
      {bundle_id}.rekor        # Rekor inclusion proof (if published)
  revisions/
    {revision_id}/             # Revision manifest + lineage

Signing workflow:

1. Canonicalize richgraph-v1 JSON (sorted keys, arrays by deterministic key)
2. Compute BLAKE3-256 hash -> graph_hash
3. Create DSSE envelope with stella.ops/graph@v1 predicate
4. Submit digest to Rekor (online) or cache checkpoint (offline)
5. Store graph body + envelope + proof in CAS

8.3 CLI UX for Selective Bundle Verification

# Verify graph DSSE only (default)
stella graph verify --hash blake3:a1b2c3d4...

# Verify graph + all edge bundles
stella graph verify --hash blake3:a1b2c3d4... --include-bundles

# Verify specific edge bundle
stella graph verify --hash blake3:a1b2c3d4... --bundle bundle:001

# Offline verification with local CAS
stella graph verify --hash blake3:a1b2c3d4... --cas-root ./offline-cas/

# Verify Rekor inclusion
stella graph verify --hash blake3:a1b2c3d4... --rekor-proof

# Output formats
stella graph verify --hash blake3:a1b2c3d4... --format json|table|summary

8.4 Golden Fixture Plan

Fixture location: tests/Reachability/Hybrid/

Required fixtures:

Fixture	Description	Expected Verification Time
graph-only.golden.json	Minimal richgraph-v1 with DSSE	< 100ms
graph-with-runtime.golden.json	Graph + 1 runtime edge bundle	< 200ms
graph-with-contested.golden.json	Graph + 1 contested/revoked edge bundle	< 200ms
large-graph.golden.json	10K nodes, 50K edges, 5 bundles	< 2s
offline-bundle.golden.tgz	Complete offline replay pack	< 5s

CI integration:

• .gitea/workflows/hybrid-attestation.yml runs verification fixtures
• Size gate: Graph body < 10MB, individual bundle < 1MB
• Time gate: Full verification < 5s for standard tier

8.5 Implementation Status

Component	Status	Notes
Graph DSSE predicate	Done	stella.ops/graph@v1 in PredicateTypes.cs
Edge-bundle DSSE predicate	Planned	stella.ops/edgeBundle@v1
CAS layout	Done	Per section 8.2
CLI verify command	Planned	Per section 8.3
Golden fixtures	Planned	Per section 8.4
Rekor integration	Done	Via Attestor module