git.stella-ops.org/docs/product-advisories/unprocessed/19-Dec-2025 - Moat #7.md

1) Product direction: make “Unknowns” a first-class risk primitive

Non‑negotiable product principles

1. Unknowns are not suppressed findings

   • They are a distinct state with distinct governance.

2. Unknowns must be policy-addressable

   • If policy cannot block or allow them explicitly, the feature is incomplete.

3. Unknowns must be attested

   • Every signed decision must carry “what we don’t know” in a machine-readable way.

4. Unknowns must be default-on

   • Users may adjust thresholds, but they must not be able to “turn off unknown tracking.”

Definition: what counts as an “unknown”

PMs must ensure that “unknown” is not vague. Define reason-coded unknowns, for example:

• U-RCH: Reachability unknown (call path indeterminate)
• U-ID: Component identity unknown (ambiguous package / missing digest / unresolved PURL)
• U-PROV: Provenance unknown (cannot map binary → source/build)
• U-VEX: VEX conflict or missing applicability statement
• U-FEED: Knowledge source missing (offline feed gaps, mirror stale)
• U-CONFIG: Config/runtime gate unknown (feature flag not observable)
• U-ANALYZER: Analyzer limitation (language/framework unsupported)

Each unknown must have:

• reason_code (one of a stable enum)
• scope (component, binary, symbol, package, image, repo)
• evidence_refs (what we inspected)
• assumptions (what would need to be true/false)
• remediation_hint (how to reduce unknown)

Acceptance criterion: every unknown surfaced to users can be traced to a reason code and remediation hint.

---

2) Policy direction: “unknown budgets” must be enforceable and environment-aware

Policy model requirements

Policy must support:

• Thresholds by environment (dev/test/stage/prod)
• Thresholds by unknown type (reachability vs provenance vs feed, etc.)
• Severity weighting (e.g., unknown on internet-facing service is worse)
• Exception workflow (time-bound, owner-bound)
• Deterministic evaluation (same inputs → same result)

Recommended default policy posture (ship as opinionated defaults)

These defaults are intentionally strict in prod:

Prod (default)

• unknown_reachable == 0 (fail build/deploy)
• unknown_provenance == 0 (fail)
• unknown_total <= 3 (fail if exceeded)
• unknown_feed == 0 (fail; “we didn’t have data” is unacceptable for prod)

Stage

• unknown_reachable <= 1
• unknown_provenance <= 1
• unknown_total <= 10

Dev

• Never hard fail by default; warn + ticket/PR annotation
• Still compute unknowns and show trendlines (so teams see drift)

Exception policy (required to avoid “disable unknowns” pressure)

Implement explicit exceptions rather than toggles:

• Exception must include: owner, expiry, justification, scope, risk_ack
• Exception must be emitted into attestations and reports (“this passed with exception X”).

Acceptance criterion: there is no “turn off unknowns” knob; only thresholds and expiring exceptions.

---

3) Reporting direction: unknowns must be visible, triaged, and trendable

Required reporting surfaces

1. Release / PR report

   • Unknown summary at top:

     • total unknowns
     • unknowns by reason code
     • unknowns blocking policy vs not

   • “What changed?” vs previous baseline (unknown delta)

2. Dashboard (portfolio view)

   • Unknowns over time
   • Top teams/services by unknown count
   • Top unknown causes (reason codes)

3. Operational triage view

   • “Unknown queue” sortable by:

     • environment impact (prod/stage)
     • exposure class (internet-facing/internal)
     • reason code
     • last-seen time
     • owner

Reporting should drive action, not anxiety

Every unknown row must include:

• Why it’s unknown (reason code + short explanation)
• What evidence is missing
• How to reduce unknown (concrete steps)
• Expected effect (e.g., “adding debug symbols will likely reduce U-RCH by ~X”)

Key PM instruction: treat unknowns like an SLO. Teams should be able to commit to “unknowns in prod must trend to zero.”

---

4) Attestations direction: unknowns must be cryptographically bound to decisions

Every signed decision/attestation must include an “unknowns summary” section.

Attestation requirements

Include at minimum:

• unknown_total
• unknown_by_reason_code (map of reason→count)
• unknown_blocking_count
• unknown_details_digest (hash of the full list if too large)
• policy_thresholds_applied (the exact thresholds used)
• exceptions_applied (IDs + expiries)
• knowledge_snapshot_id (feeds/policy bundle hash if you support offline snapshots)

Why this matters: if you sign a “pass,” you must also sign what you didn’t know at the time. Otherwise the signature is not audit-grade.

Acceptance criterion: any downstream verifier can reject a signed “pass” based solely on unknown fields (e.g., “reject if unknown_reachable>0 in prod”).

---

5) Development direction: implement unknown propagation as a first-class data flow

Core engineering tasks (must be done in this order)

A. Define the canonical “Tri-state” evaluation type

For any security claim, the evaluator must return:

• TRUE (evidence supports)
• FALSE (evidence refutes)
• UNKNOWN (insufficient evidence)

Do not represent unknown as nulls or missing fields. It must be explicit.

B. Build the unknown aggregator and reason-code framework

• A single aggregation layer computes:

  • unknown counts per scope
  • unknown counts per reason code
  • unknown “blockers” based on policy

• This must be deterministic and stable (no random ordering, stable IDs).

C. Ensure analyzers emit unknowns instead of silently failing

Any analyzer that cannot conclude must emit:

• UNKNOWN + reason code + evidence pointers Examples:
• call graph incomplete → U-RCH
• stripped binary cannot map symbols → U-PROV
• unsupported language → U-ANALYZER

D. Provide “reduce unknown” instrumentation hooks

Attach remediation metadata:

• “add build flags …”
• “upload debug symbols …”
• “enable source mapping …”
• “mirror feeds …”

This is how you prevent user backlash.

---

6) Make it default rather than optional: rollout plan without breaking adoption

Phase 1: compute + display (no blocking)

• Unknowns computed for all scans
• Reports show unknown budgets and what would have failed in prod
• Collect baseline metrics for 2–4 weeks of typical usage

Phase 2: soft gating

• In prod-like pipelines: fail only on unknown_reachable > 0
• Everything else warns + requires owner acknowledgement

Phase 3: full policy enforcement

• Enforce default thresholds
• Exceptions require expiry and are visible in attestations

Phase 4: governance integration

• Unknowns become part of:

  • release readiness checks
  • quarterly risk reviews
  • vendor compliance audits

Dev Manager instruction: invest in tooling that reduces unknowns early (symbol capture, provenance mapping, better analyzers). Otherwise “unknown gating” becomes politically unsustainable.

---

7) “Definition of Done” checklist for PMs and Dev Managers

PM DoD

• Unknowns are explicitly defined with stable reason codes
• Policy can fail on unknowns with environment-scoped thresholds
• Reports show unknown deltas and remediation guidance
• Exceptions are time-bound and appear everywhere (UI + API + attestations)
• Unknowns cannot be disabled; only thresholds/exceptions are configurable

Engineering DoD

• Tri-state evaluation implemented end-to-end
• Analyzer failures never disappear; they become unknowns
• Unknown aggregation is deterministic and reproducible
• Signed attestation includes unknown summary + policy thresholds + exceptions
• CI/CD integration can enforce “fail if unknowns > N in prod”

---

8) Concrete policy examples you can standardize internally

Minimal policy (prod)

• Block deploy if:

  • unknown_reachable > 0
  • OR unknown_provenance > 0

Balanced policy (prod)

• Block deploy if:

  • unknown_reachable > 0
  • OR unknown_provenance > 0
  • OR unknown_total > 3

Risk-sensitive policy (internet-facing prod)

• Block deploy if:

  • unknown_reachable > 0
  • OR unknown_total > 1
  • OR any unknown affects a component with known remotely-exploitable CVEs