git.stella-ops.org/docs/signals/unknowns-registry.md

Unknowns Registry (Signals) — November 2026

This document defines the Unknowns Registry that turns unresolved identities or edges into first-class signals. It replaces the temporary notes from late 2026 advisories.

1. Purpose

When scanners or runtime probes cannot decisively map artifacts, symbols, or package identities, the gap is recorded as an Unknown instead of being dropped. Policy and scoring can then incorporate “unknowns pressure” to avoid silent false negatives.

2. Data model (v0)

{
  "unknown_id": "unk:sha256:<type+scope+evidence>",
  "observed_at": "2025-11-20T00:00:00Z",
  "provenance": { "source": "Scanner|Signals|SbomService|Vexer", "host": "runner-42", "scan_id": "scan:..." },
  "scope": { "artifact": { "type": "oci.image", "ref": "registry/app@sha256:..." }, "subpath": "/app/bin/libssl.so.3", "phase": "scan|runtime|build" },
  "unknown_type": "identity_gap|version_conflict|hash_mismatch|missing_edge|runtime_shadow|policy_undecidable",
  "evidence": { "raw": "dynsym missing for libssl.so.3", "signals": ["sym:memcpy", "import:SSL_free"] },
  "transitive": { "depth": 1, "parents": ["pkg:deb/openssl@3.0.2"], "children": [] },
  "confidence": { "p": 0.42, "method": "rule" },
  "exposure_hints": { "surface": ["startup"], "runtime_hits": 0 },
  "status": "open|triaged|suppressed|resolved",
  "labels": ["reachability:possible", "sbom:incomplete"]
}

3. API (idempotent)

• POST /unknowns/ingest — upsert by unknown_id; repeat payloads are no-ops.
• GET /unknowns?artifact=...&status=open — list unknowns for a target.
• POST /unknowns/{id}/triage — update status/labels, attach rationale.
• GET /unknowns/metrics — density by artifact / unknown_type / depth.

All endpoints are additive; no hard deletes. Payloads must include tenant bindings and CAS URIs when evidence is stored externally.

4. Producers

• Scanner: unresolved symbol → package mapping (stripped binaries), missing build-id, ambiguous purl; log with unknown_type=identity_gap or missing_edge.
• Signals: runtime hits that cannot map to a graph node or purl; unresolved call edges.
• SbomService: conflicting versions for same path; hash mismatch between SBOM and observed file.
• Vexer/Policy: advisory without trustable provenance (unknown_type=policy_undecidable).

5. Consumers & scoring

• Signals scoring adds unknowns_pressure = f(density(depth<=1), runtime_shadow, policy_undecidable) and feeds it into reachability/risk scores.
• Policy can block not_affected claims when unknowns_pressure exceeds thresholds.
• UI/CLI show unknown chips with reason and depth; operators can triage or suppress.

5.1 Multi-Factor Ranking

Unknowns are ranked using a 5-factor scoring algorithm that computes a composite score from:

• Popularity (P) - Deployment impact based on usage count
• Exploit Potential (E) - CVE severity if known
• Uncertainty (U) - Accumulated flag weights
• Centrality (C) - Graph position importance (betweenness)
• Staleness (S) - Evidence age since last analysis

Based on the composite score, unknowns are assigned to triage bands:

• HOT (score >= 0.70): Immediate rescan, 15-minute scheduling
• WARM (0.40 <= score < 0.70): Scheduled rescan within 12-72h
• COLD (score < 0.40): Weekly batch processing

See Unknowns Ranking Algorithm for the complete formula reference.

6. Storage & CAS

• Primary store: append-only KV/graph in Mongo (collections unknowns, unknown_metrics).
• Evidence blobs: CAS under cas://unknowns/{sha256} for large payloads (runtime traces, partial SBOMs).
• Include analyzer fingerprint + schema version in each record for replay.

7. Integration checkpoints

• Add writer hooks in Scanner/Signals once richgraph-v1 and runtime ingestion surface unmapped items.
• Extend reachability lattice docs to note unknowns_pressure input.
• Add Grafana panel for unknown density per artifact/namespace.

8. Acceptance criteria

• APIs deployed with idempotent behavior and tenant guards.
• At least two producer paths writing Unknowns (Scanner unresolved symbol; Signals runtime shadow).
• Metrics endpoint shows density and trend; UI/CLI expose triage status.