git.stella-ops.org/docs-archived/product/advisories/17-Jan-2026 - Features Gap.md

Product Advisory: Interface Surfacing Strategy for “Hidden” Backend Capabilities

ID: ADVISORY-20260116-IFACE-SURFACING Status: ACTIVE Owner intent: Product-wide directive Applies to: FEATURE_MATRIX.md, CLI, Web UI, Doctor, module dossiers, sprints

0) Why this advisory exists

The Feature Gaps Report shows a typical problem in fast-moving monorepos:

• capabilities exist in code,
• but are not surfaced in CLI/UI,
• and therefore are not usable, not supportable, and not credibly marketable. This product advisory is based features discovered and documented on file FEATURE_GAPS_REPORT.md in code but not listed in FEATURE_MATRIX.md

Therefore, interface work must do two things:

1. reduce support burden (“Doctor-first operability”), and
2. strengthen the suite’s moat (evidence-grade decisions, explainability, determinism).

This advisory defines which backend capabilities should be surfaced via CLI and/or UI, and the minimal “how” to do it.

---

1) Non-negotiable principles (solo-scale rules)

P1: No “capability theatre”

If a capability is claimed in FEATURE_MATRIX.md as “available”, it must have:

• a supported activation path (UI or CLI or config + Doctor validation), and
• documentation that explains how to use it.

If not, it must be marked as:

• Automatic (always-on), or
• Internal (not supported / not marketed), or
• Planned.

P2: Prefer “exports” and “inspectors” over new UI pages

To avoid UI explosion, surface many capabilities as:

• Export profiles (downloadable artifacts)
• Inspector views (read-only detail panes)
• Minimal admin actions (rotate key, test connector, download SARIF)

Avoid building bespoke UI workflows unless they materially reduce operator labor.

P3: CLI is the control plane for automation and air-gap

Anything used in:

• CI,
• offline operations,
• bulk admin,
• reproducibility / debugging, must have a CLI path.

UI is for:

• day-to-day operator workflows,
• triage,
• explainability (“why blocked?”),
• visualizations.

P4: Doctor-first for support reduction

If a feature is likely to generate tickets (connectors, crypto, queues, replay), it must have:

• a Doctor check (and a Doctor bundle payload),
• deterministic “reason codes” for failures,
• a runbook entry.

P5: Progressive disclosure

Don’t overwhelm users with advanced controls. Expose:

• simple defaults in UI,
• advanced knobs in CLI/config,
• deep internals only in Doctor bundles.

---

2) Decision rubric: UI vs CLI vs Doc-only

Classify each discovered capability into exactly one of these:

Class A — Automatic (Doc-only)

Use when the capability:

• runs implicitly as part of scan/policy/evidence workflows, and
• doesn’t require user input to be valuable.

Requirement:

• Document it in FEATURE_MATRIX.md as Automatic.
• Ensure its outcomes show up in existing UI/exports (e.g., findings detail, evidence packet).

Examples:

• Secrets detection that runs during scan
• OS package analyzers invoked implicitly
• Symlink/whiteout handling in layered filesystem

Class B — CLI-first (automation/admin/offline)

Use when the capability:

• is primarily an operator/admin action,
• is needed in automation/CI,
• is needed offline,
• or is a bulk/advanced workflow.

Requirement:

• Add CLI commands with --format json and --output.
• Update docs with copy/paste examples.
• Add Doctor checks if it can fail due to environment dependencies.

Examples:

• SBOM convert/validate
• Key rotation, trust anchors
• Policy verdict export
• Timeline/HLC inspection

Class C — UI-first (triage/explainability)

Use when the capability:

• improves human decision-making,
• reduces triage effort,
• is part of “why blocked/approved”.

Requirement:

• Add a minimal UI surface (read-only or download action).
• Provide deterministic “reason” traces and evidence links.

Examples:

• Path witness visualization for reachability
• SARIF download in the UI
• Connector status dashboard

Class D — Both (high-value + frequent usage)

Use when the capability:

• is used in pipelines (CLI), and
• is also used in investigations/audits (UI).

Examples:

• Audit bundle export
• VEX consensus/verification
• Evidence packs

Class E — Internal (do not surface yet)

Use when the capability:

• is not stable enough to support,
• would multiply permutations,
• or is not aligned with current product focus.

Requirement:

• Do not list as a primary feature in FEATURE_MATRIX.md.
• It may remain in a “Known internal capabilities” appendix for engineering only.

---

3) Priority: what to surface first (P0/P1/P2)

P0 (must surface) — Moat + Support reduction

These directly improve “why blocked?”, auditability, operability, and adoption.

P0-1: Exports and evidence surfaces

• Add/standardize CLI:
  • stella export audit ...
  • stella export lineage ...
  • stella export risk ...
  • stella export evidence-pack ...
• UI: ensure Export Center supports:
  • download audit bundles,
  • download lineage evidence packs,
  • download risk bundles.

Acceptance:

• Export outputs are deterministic, versioned, and include a manifest with hashes.
• Doctor validates export prerequisites (storage, permissions, disk space).

P0-2: “Why blocked?” explainability completeness

• CLI:
  • stella score explain <digest|runId> --format json
  • stella reachability witness <digest> --vuln <cve> --format mermaid|json
  • stella reachability guards <digest> --format json
• UI:
  • add “Witness Path” view for reachable findings (Mermaid/GraphViz render),
  • show confidence breakdown (path/guard/runtime components),
  • link to evidence URIs (stella://...) and replay manifests where available.

Acceptance:

• For any blocked decision, UI can show:
  • which gate blocked,
  • what evidence triggered it,
  • and at least one witness or explanation trace.

P0-3: SARIF in UI (high adoption win)

• UI: add “Download SARIF” for a scan run and/or digest.
• CLI already exists (stella scan sarif).

Acceptance:

• UI downloads match CLI outputs (same schema/version).
• Exports include metadata (digest, scan time, policy profile id).

P0-4: Concelier connector truth (reduce ticket load)

• Docs: update FEATURE_MATRIX.md to reflect connector reality (33+ connectors).
• UI: add a “Feeds & Connectors Status” page:
  • list connectors, last success, last error, next scheduled run (if applicable),
  • link to logs and Doctor bundle instructions.
• CLI:
  • stella db status
  • stella db connectors list
  • stella db connectors test <name>

Acceptance:

• Any ingestion failure has a reason code and remediation hint.

---

P1 (next) — Admin confidence + advanced workflows

These increase operational safety and enterprise readiness without large UI build.

P1-1: SBOM lineage CLI parity (UI already exists)

• Add:
  • stella sbom lineage list
  • stella sbom lineage show <id>
  • stella sbom lineage export <id> --format json|spdx|cdx

P1-2: VEX operational completeness

• CLI:
  • stella vex verify <doc>
  • stella vex evidence export <digest|component>
  • stella vex webhooks list/add/remove
  • stella issuer keys list/create/rotate/revoke
• UI:
  • minimal webhook management screen (list + add/remove),
  • issuer keys page can remain UI-only if already present, but CLI needed for automation.

P1-3: Policy debug and portability

• CLI:
  • stella policy lattice explain ...
  • stella policy verdicts export ...
  • stella policy promote ... (if promotion pipeline exists)
• UI:
  • add “download verdict” and “download decision capsule” actions in policy and release views.

P1-4: Auth/admin CLI coverage

• Add CLI wrappers for UI-only admin tasks:
  • stella auth clients list/create/...
  • stella auth roles ...
  • stella auth scopes list
  • stella auth token inspect
  • stella auth api-keys ...

---

P2 (later) — Nice-to-have / heavy UI

These can be strong, but risk expanding support and UI scope.

• BinaryIndex corpus ingestion UI
• Fingerprint visualization UI
• Evidence holds (legal hold) management UI
• Incident mode workflows and dashboards beyond a basic toggle + export hooks
• Full timeline UI (unless needed for core workflows)

---

4) Mapping: discovered gaps -> recommended surfacing

This section is the “agent checklist”.

Batch 1: SBOM & ingestion

• SPDX 3.0 Build Attestation
  • Class: D (Both) if used for audits; otherwise B (CLI-first)
  • CLI: stella attest build --format spdx3 --output ...
  • UI: Export Center adds “Build Attestation (SPDX 3.0)”
• CycloneDX CBOM Support
  • Class: B (CLI-first) + Doc
  • CLI: stella sbom export --type cbom --format cdx
• Layer SBOM composition
  • Class: B (CLI-first) + Doc
  • Ensure docs explain when/why layer SBOM is useful (base image triage, provenance).
• SBOM advisory matching
  • Class: A (Automatic) + UI visibility
  • UI: show “matched advisory sources” in SBOM/finding details; doc-only if already visible.
• Graph lineage service (UI exists)
  • Class: B (CLI-first) to match UI
  • CLI: stella graph lineage show <digest|purl>
• SBOM validation pipeline / format conversion
  • Class: B (CLI-first)
  • CLI: stella sbom validate, stella sbom convert
• Trivy DB export (offline)
  • Class: B (CLI-first) + optional UI under Offline Kit
  • UI: optional “download trivy db” action if it reduces ticket load.

Batch 2: scanning & detection

• Secrets detection, OS analyzers
  • Class: A (Automatic) + Document
  • Update FEATURE_MATRIX.md: “runs during scan; shown in findings”.
• Symbol-level vulnerability matching
  • Class: C (UI-first) if it materially improves triage
  • UI: “Symbol match” tab in finding detail (no heavy workflow).
• SARIF export
  • Class: D (Both)
  • Add UI download.
• Concurrent worker config
  • Class: B (CLI-first)
  • CLI: stella scanner workers set/get or stella scan run --workers N.

Batch 3: reachability analysis

• Confidence calculator / EWS explanation
  • Class: D (Both)
  • CLI: stella score explain, stella reachability explain
  • UI: confidence breakdown and witness.
• Path witness generation
  • Class: C (UI-first) + keep CLI support
  • UI: render witness (Mermaid/GraphViz).
• Runtime signal correlation
  • Class: B (CLI-first) to complement UI
  • CLI: stella signals inspect <digest|runId>
• Gate detection (guards)
  • Class: B (CLI-first) + UI is already present
  • CLI: stella reachability guards <digest>.

Batch 4: binary analysis

• Keep CLI-first; avoid UI until demanded.
• Add minimal doc + optional UI download links (export fingerprint result) later.

Batch 5: advisory sources / Concelier

• Primary action: documentation correction + connector status.
• UI: Feeds & Connectors Status page (P0).
• CLI: connector list/status/test.

Batch 6: VEX processing

• P1: CLI for verify/evidence export/webhooks/issuer keys.
• UI: minimal webhook mgmt + improve “consensus rationale” explainability.

Batch 7: policy engine

• P1: CLI lattice explain, verdict export, risk provider config exposure (at least in docs + config validation + Doctor).
• UI: provide download actions; avoid building policy authoring wizard.

Batch 8: attestation & signing

• Key rotation and trust anchors:
  • Class: B (CLI-first), optionally UI later
  • CLI: stella keys rotate, stella trust-anchors add/list/remove
• Predicate registry browser:
  • Class: B (CLI-first)
  • CLI: stella attest predicates list
• Signer audit logs:
  • Class: B (CLI-first)
  • CLI: stella sign audit export.

Batch 9: regional crypto

• Crypto profiles and plugin health:
  • Class: B (CLI-first)
  • CLI: stella crypto profiles list/select, stella crypto plugins status
  • Doctor checks required (HSM/PKCS#11 availability, cert chains, etc.)

Batch 10: evidence & findings

• Audit bundle export:
  • Class: D (Both)
  • CLI: stella export audit
  • UI: ensure it’s a first-class export action.
• Evidence holds / incident mode:
  • Class: P2 unless required by early customers; keep as internal or config-only with docs.

Batch 11: determinism & replay

• HLC inspection, timeline query, scoring explanation:
  • Class: B (CLI-first) for diagnostics
  • CLI: stella hlc status, stella timeline query, stella score explain.

Batch 12: operations

• Where UI exists but CLI missing:
  • Class: B (CLI-first)
  • Add:
    • stella orchestrator jobs list/show/retry/cancel
    • stella orchestrator deadletter list/show/replay
    • stella scheduler preview

Batch 13: release orchestration

• (When release orchestration is shipped)
  • Class: D (Both)
  • CLI parity required:
    • stella release create/promote/rollback
    • stella release hooks ...
    • stella agent status

Batch 14: auth & access control

• Class: B (CLI-first)
• Add admin CLI wrappers for: scopes, clients, roles, api-keys, token inspect.

Batch 15: notifications & integrations

• UI exists; add CLI for automation/testing:
  • stella notify channels list/test
  • stella notify templates list/render
  • stella integrations test
  • stella notify preferences export/import

---

5) Documentation requirements (must be done alongside surfacing)

When surfacing a capability:

1. Update FEATURE_MATRIX.md (and the correct category).
2. Update the relevant module dossier (docs/modules/<module>/architecture.md or a dedicated guide).
3. Add examples (copy/paste) for CLI usage and for UI navigation paths.
4. If the capability is automatic, document where its output appears.

Also: do not claim “UI support” if it is “API-only”.

---

6) Implementation pattern (avoid interface sprawl)

Preferred UI patterns

• “Download” button for exportable artifacts (SARIF, audit bundle, evidence pack).
• “Inspector” panels inside existing pages (Findings detail, VEX detail, Policy detail).
• One consolidated “Ops” section for status dashboards.
• One consolidated “Integrations” section for connectors and tests.

Preferred CLI patterns

• Command groups match product nouns:
  • stella sbom ...
  • stella export ...
  • stella vex ...
  • stella policy ...
  • stella auth ...
  • stella keys ...
  • stella reachability ...
  • stella orchestrator ...
• Every new CLI command must support:
  • --format json (machine use)
  • --output <path> (CI use)
  • deterministic ordering and stable schemas

---

7) Definition of Done (interface surfacing)

For any interface surfacing task:

DOD-1: Feature matrix updated with correct classification (A/B/C/D/E) DOD-2: CLI/UI path implemented (as required by classification) DOD-3: Docs updated with copy/paste examples and screenshots where appropriate DOD-4: Doctor coverage added if failures are environment-dependent DOD-5: Determinism tests added if outputs are exported/signed/hashed DOD-6: Reason codes and explainability exist for decision-related features

---

8) Immediate next sprints (recommended)

1. P0 exports completeness: Export Center + stella export ... standardization
2. P0 explainability: witness path UI + stella score explain
3. P0 SARIF UI download
4. P0 Feeds/connectors status UI + CLI
5. P1 SBOM lineage CLI parity
6. P1 VEX verify/evidence export + webhooks mgmt
7. P1 Policy debug + verdict export
8. P1 Admin CLI (auth/keys/crypto profiles)

Archive this advisory only when superseded by a newer interface strategy directive.

---

Here’s a tight UX spec you can drop into Stella Ops to make “proof‑first” triage obvious and quiet by default.

Triage Card (Signed Evidence Card)

• Purpose: Show one issue = one verifiable proof bundle.

• Header: vuln id + package@version + scope (image/layer/path). Right side: Risk chip (score + reason).

• One‑click “Rekor Verify”: Runs DSSE/Sigstore verify and expands to show:

  • ✅ signature subject/issuer, ✅ timestamp, ✅ Rekor index + raw entry (copyable), ✅ digest(s).

• Evidence chips: OpenVEX status (affected/not_affected), patch proof (binary/backport), reachability (stack path), EPSS band.

• Actions: “Explain” (AI note), “Create task,” “Mute (reasoned),” “Export evidence (.dsse)”.

• Micro‑interactions:

  • Hover on chips → mini‑tooltip with why.
  • Copy icons on digests/Rekor IDs.
  • Keyboard shortcuts: v verify, e export, m mute.

Binary‑Diff Panel

• Purpose: Prove fixes at the binary level, not just SBOM claims.

• Scope selector: file → section → function.

• Layers: Base vs candidate (or pre‑ vs post‑patch) with inline diff.

• Hashes: Per‑file SHA‑256, per‑section, per‑function rolling hashes.

• Context: CWE + symbol names, addresses, and relocation notes.

• Artifacts:

  • Export “Signed Diff” → DSSE envelope (hash map + metadata + signer + timestamp).
  • Attach to the triage card as “Patch proof”.

• Micro‑interactions:

  • Click on symbol in call‑graph to jump to function diff.
  • Toggle opcodes ⇄ decompiled view (if available).
  • “Show only changed blocks” toggle.

Quiet/Accessible Filter Strip

• Purpose: Deterministic, low‑noise prioritization—no casino lights.

• Precedence toggles (left→right strongest to weakest):

  1. OpenVEX (not_affected/affected)
  2. Patch proof present
  3. Reachability (call‑path to runtime)
  4. EPSS (≥ threshold)

• Determinism: When ties occur, sort by OCI digest, then path, then CVSS.

• Controls:

  • EPSS slider; “Only reachable” checkbox; “Only with patch proof” checkbox.
  • “Deterministic order” lock icon (on by default).

• A11y: High‑contrast theme, focus rings, full keyboard nav, prefers‑reduced‑motion honored; all chips have aria‑labels.

• Micro‑interactions: Filters update counts without reflow; announcement region reads changes.

---

Why this matters

• Trustable triage: Users see cryptographic evidence (signatures, Rekor entries, per‑function hashes), not just scanner claims.
• Noise‑free: Precedence rules (OpenVEX → patch proof → reachability → EPSS) cut alert fatigue predictably.
• Audit‑ready: Every click can emit an exportable DSSE‑signed artifact for tickets, audits, and vendors.

---

Minimal data model additions

• EvidencePacket { sbom_ref, dsse_envelope, rekor_index, signer, timestamp }
• BinaryProof { file_hashes[], section_hashes[], function_hashes[], diff_summary }
• TriageMeta { openvex_status, reachability_path[], epss_score, precedence_tuple }

---

Done‑means‑Done checks

• Triage card verify shows raw Rekor JSON + signature details.
• Binary‑diff export produces a DSSE file that re‑verifies offline.
• Filter strip yields identical ordering given the same inputs (golden test).
• Keyboard‑only usage covers: open card, verify, export, toggle filters, navigate diffs.

Want me to turn this into three Figma‑ready wireframes (with exact layout specs and aria‑labels), or generate sample DSSE envelopes + Rekor verify outputs so your team can test end‑to‑end?

-- Here’s a tight, practical first pass for a “doctor” setup wizard that runs right after install and anytime from Settings → Diagnostics. It gives instant confidence that Stella Ops is wired correctly, without needing full integrations configured.

---

What the “doctor” does (in plain terms)

It runs a few lightweight health checks to confirm your system can:

• talk to its database,
• reach its attestation store (for signed proofs),
• verify a sample artifact end‑to‑end (SBOM + VEX).

If these pass, your install is sound and you can add integrations later at your pace.

---

Mandatory checks (first pass)

1. DB connectivity + schema version

• Why: If the DB is unreachable or the schema is outdated, nothing else matters.

• Checks:

  • TCP/connect to Postgres URI.
  • SELECT 1; liveness.
  • Read schema_version from stella.meta (or your flyway/liquibase table).
  • Compare to the app’s expected version; warn if migrations pending.

• CLI sketch:

  stella doctor db \
    --url "$STELLA_DB_URL" \
    --expect-schema "2026.01.0"
  

• Pass criteria: reachable + current (or actionable “run migrations” hint).

2. Attestation store availability (Rekor/Cosign)

• Why: Stella relies on signed evidence; if the ledger/store isn’t reachable, you can’t prove integrity.

• Checks:

  • Resolve/HTTP 200 for Rekor base URL (or your mirror).
  • Cosign key material present (KMS, keyless, or offline bundle).
  • Clock skew sanity (<5s) for signature verification.

• CLI sketch:

  stella doctor attest \
    --rekor-url "$STELLA_REKOR_URL" \
    --cosign-key "$STELLA_COSIGN_KEY" \
    --mode "online|offline"
  

• Pass criteria: ledger reachable (or offline bundle found) + keys valid.

3. Artifact verification pipeline run (SBOM + VEX sample)

• Why: Proves the whole trust path works—fetch, verify, evaluate policy.

• Checks:

  • Pull a tiny, known test artifact by digest (immutable).
  • Verify signature/attestations (DSSE in Rekor or offline bundle).
  • Fetch/validate SBOM (CycloneDX/SPDX) and a sample VEX.
  • Run policy engine: “no‑go if critical vulns without VEX justification.”

• CLI sketch:

  stella doctor verify \
    --artifact "oci://registry.example/test@sha256:deadbeef..." \
    --require-sbom \
    --require-vex
  

• Pass criteria: signature + SBOM + VEX validate; policy engine returns ✅.

---

Output & UX

• One‑screen summary with green/yellow/red statuses and terse fixes.
• Copy‑paste remediations (DB URI example, Rekor URL, cosign key path).
• Evidence links (e.g., “View attestation entry” or “Open policy run”).
• Export: stella doctor --json > doctor-report.json for support.

---

Where this fits in the installer/wizard

• UI & CLI both follow the same steps:

  1. DB setup → quick migration → Doctor: DB
  2. Choose attestation mode (Rekor/cosign keyless/offline bundle) → Doctor: Attest
  3. Minimal “verification pipeline” config (test registry creds or bundled sample) → Doctor: Verify

• Each step has defaults (Postgres + Rekor URL + bundled demo artifact) and a “Skip for now” with a reminder tile in Settings → Integrations.

---

Failure → Suggested fixes (examples)

• DB schema mismatch → “Run stella migrate up to 2026.01.0.”
• Rekor unreachable → “Check DNS/proxy; or switch to Offline Attestations in Settings.”
• Cosign key missing → “Add key (KMS/file) or enable keyless; see Keys → Add.”
• SBOM/VEX missing → “Enable ‘Generate SBOM on build’ and ‘Collect VEX from vendors’, or load a demo bundle.”

---

Next steps (beyond first pass)

• Optional checks the wizard can add later:

  • Registry reachability (pull by digest).
  • Settings store (Valkey cache reachability).
  • Notifications (send test webhook/email).
  • SCM/Vault/LDAP plugin stubs: ping + auth flow (but not required to pass install).

If you want, I can turn this into:

• a ready‑to‑ship CLI command spec,
• a UI wireframe of the three-step doctor,
• or JSON schemas for the doctor’s machine‑readable report.