git.stella-ops.org/docs/reachability/evidence-schema.md

# Reachability Evidence Schema (Draft v1, Nov 2026)

Purpose: define the canonical fields for reachability graph nodes/edges, runtime facts, and unknowns so Scanner, Signals, Policy, Replay, CLI/UI, and SbomService stay aligned. This replaces scattered notes in advisories.

## 1. Core identifiers

- `symbol_id`: canonical ID for a function/symbol; includes `{format, build_id?, file_hash?, section?, addr, length}` plus optional `code_block_hash`. Always deterministic and lowercase.
- `code_id`: `{format, build_id?, file_hash?, start, length, code_block_hash?}`; used when symbol names are absent.
- `symbol_digest`: sha256 of normalized signature (demangled name + params + return type; strip addresses). For stripped code, combine synthetic name + block hash.
- `purl`: package URL of the owning component (from SBOM resolver); `pkg:unknown` when unresolved.

## 2. Graph payload (`richgraph-v1` additions)

```jsonc
{
  "nodes": [
    {
      "id": "sym:sha256:...",
      "symbol_id": "func:ELF:sha256:...",
      "code_id": "code:ELF:sha256:...",
      "code_block_hash": "sha256:deadbeef...",
      "purl": "pkg:deb/ubuntu/openssl@3.0.2?arch=amd64",
      "symbol": { "mangled": "_Z15ssl3_read_bytes", "demangled": "ssl3_read_bytes", "source": "DWARF", "confidence": 0.98 },
      "build_id": "a1b2c3...",
      "lang": "c",
      "evidence": ["dwarf", "dynsym"],
      "analyzer": { "name": "scanner.native", "version": "1.2.0", "toolchain": "ghidra-11" }
    }
  ],
  "edges": [
    {
      "from": "sym:sha256:caller",
      "to": "sym:sha256:callee",
      "kind": "direct|plt|indirect|runtime",
      "purl": "pkg:deb/ubuntu/openssl@3.0.2?arch=amd64",          // callee owner
      "symbol_digest": "sha256:...",                              // callee digest
      "candidates": ["pkg:deb/openssl@3.0.2", "pkg:deb/openssl@3.0.1"],
      "confidence": 0.92,
      "evidence": ["import", "reloc@GOT"]
    }
  ],
  "roots": [
    { "id": "init_array@0x401000", "phase": "load", "source": "DT_INIT_ARRAY" },
    { "id": "main", "phase": "runtime" }
  ],
  "graph_hash": "blake3:..."
}
```

## 2.5 Attestation levels (hybrid default)

- **Graph DSSE (required):** one DSSE envelope over the canonical graph JSON (sorted arrays/keys) with `graph_hash` = BLAKE3 of body; Rekor publish always (or mirror when offline).
- **Edge-bundle DSSE (optional):** batches of ≤512 edges, emitted only for high-signal cases (`runtime`, `init_array`/TLS roots, contested/third-party edges). Each bundle carries `graph_hash`, `bundle_reason`, per-edge `reason`, `symbol_digest`, `purl`, `confidence`, and optional `revoked=true` for quarantine. Rekor publish is configurable; CAS storage is mandatory.
- CAS layout additions:
  - Graph body: `cas://reachability/graphs/{blake3}`
  - Graph DSSE: `cas://reachability/graphs/{blake3}.dsse`
  - Edge bundle: `cas://reachability/edges/{graph_hash}/{bundle_id}` + `.dsse`
- Determinism: bundle ordering by `(bundle_reason, edge_id)`; arrays sorted before hashing.

## 3. Runtime facts (Signals ingestion)

Fields per NDJSON event:

- `symbolId` (required), `codeId`, `symbolDigest?`, `purl?`
- `hitCount`, `observedAt`, `loaderBase`, `processId`, `processName`, `containerId`, `socketAddress?`
- `callgraphId` or `scanId`, plus `evidenceUri` (CAS) if trace stored externally
- Determinism: sort keys when persisting; timestamps UTC ISO-8601.

## 4. Unknowns registry payload

See `docs/signals/unknowns-registry.md`; reachability producers emit Unknowns when:
- symbol→purl unresolved,
- call edge target unresolved,
- build-id missing for ELF and file hash used instead.

Unknowns must include `unknown_type`, `scope`, `provenance`, `confidence.p`, and `labels`.

## 5. CAS layout

- Graphs: `cas://reachability/graphs/{blake3}` (canonical JSON, sorted keys/arrays)
- Runtime traces: `cas://reachability/runtime/{sha256}`
- Unknowns evidence (optional large blobs): `cas://unknowns/{sha256}`
- Edge bundles: `cas://reachability/edges/{graph_hash}/{bundle_id}` (JSON + `.dsse`)

Metadata for each CAS object: `{ schema: "richgraph-v1", analyzer: {name,version}, createdAtUtc, toolchain_digest }`. When analyzer metadata is supplied at ingest (Signals OpenAPI), persist it alongside parsed analyzer fields from the artifact.

## 6. Validation rules

- All edges must carry either `purl` or `candidates[]`; never leave both empty.
- If `build_id` present, `symbol_id` and `code_id` must store it; if absent, record `build_id_source: "FileHash"`.
- Evidence arrays sorted; confidence in [0,1].
- `code_block_hash` (when present) must be lowercase hex with an algorithm prefix (e.g., `sha256:`) and only accompany stripped/heuristic nodes.
- Roots must include load-time constructors when present.
- When `edge_bundles` are present, each edge in a bundle must also exist in the graph edge set; `revoked=true` bundles override graph edges for policy/scoring.
- Graph DSSE is mandatory per scan; edge-bundle DSSEs are optional but must reference `graph_hash` and `bundle_id`.

## 7. Acceptance checklist

- Schema reflected in Scanner/Signals DTOs and OpenAPI responses.
- CAS writers enforce canonicalization before hashing.
- Fixtures include: build-id present/absent, init-array roots, purl-resolved imports-only edge, stripped binary with block-hash symbol digest, and an Unknowns case.