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)

{
  "nodes": [
    {
      "id": "sym:sha256:...",
      "symbol_id": "func:ELF:sha256:...",
      "code_id": "code:ELF:sha256:...",
      "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:..."
}

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}

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].
Roots must include load-time constructors when present.

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.

3.8 KiB Raw Blame History