Unknowns Registry (Signals)

Audience: Signals and Scanner engineers, policy authors, and operators who triage incomplete coverage. Scope: The data model, API, producers, consumers, and storage for the Unknowns Registry — the Stella Ops subsystem that turns unresolved identities and edges into first-class signals.

The Unknowns Registry captures what Stella Ops cannot yet prove and makes that uncertainty actionable, so gaps in coverage surface as triage-able signals rather than disappearing into silent false negatives.

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 then incorporate unknowns pressure to avoid silent false negatives.

2. Data model

{
  "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

The API is idempotent and additive — every write upserts and no endpoint performs a hard delete.

• 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 and attach rationale.
• GET /unknowns/metrics — density by artifact, unknown type, and depth.

Payloads must include tenant bindings, and must carry 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 © - 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 PostgreSQL (tables 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.