git.stella-ops.org/docs/product-advisories/22-Dec-2026 - UI Patterns for Triage and Replay.md

Here’s a tight, first‑time‑friendly blueprint for two Stella Ops UX pillars—Triage & Exceptions and Knowledge Snapshots & Merge Semantics—with just enough background plus concrete specs your PMs/devs can ship.

---

Triage & Exceptions (quiet‑by‑design)

Why it matters (plain English): Most scanners drown users in alerts. “Quiet‑by‑design” shows only provable, reachable risks and lets you create auditable exceptions (temporary waivers) that auto‑feed compliance packs.

User flow

1. Inbox grouped by exploit path

   • Group key = (artifact → package → vulnerable symbol → runtime path).
   • Each group shows: risk score, blast radius (count of dependents), EPSS/CVSS, and a “Proof” button.

2. Open a path → Proof bundle

   • Reach subgraph (who calls what).
   • Symbol map (function/offsets; source or binary map).
   • VEX claims (vendor/distro/internal) with trust score + signatures.

3. Raise Exception (time‑boxed)

   • Required fields: attested reason (dropdown + free text), expiry date, recheck policy (e.g., “fail build if new reachable path appears”, “fail if EPSS > X”).
   • Attestation: DSSE‑signed exception object, OCI‑attached to artifact digest.
   • Auto‑lands in Audit Pack (PDF/JSON bundle) and Timeline.

Data model (C# POCO sketch)

record ExploitPathId(string ArtifactDigest, string PackagePurl, string CveId, string Symbol, string EntryPathHash);

record ExceptionObj(
    string Id, ExploitPathId Path, string ReasonCode, string ReasonText,
    DateTimeOffset IssuedAt, DateTimeOffset ExpiresAt,
    RecheckPolicy Policy, EvidenceRef[] Evidence, AttestationMeta Att);

RecheckPolicy (examples)

• ReachGraphChange=Block
• EPSSAbove=0.5
• EnvScope=prod-only
• UnknownsAbove=N → Block

UI essentials

• Inbox: 3‑pane (List • Details • Proof).
• Proof drawer: collapsible reach subgraph; one‑click JSON export.
• Exception modal: expiry presets (7/30/90 days), reason templates (backport, feature‑flag‑off, compensating control).

APIs (REST-ish)

• GET /triage/inbox?scope=env:prod&quiet=true
• GET /triage/path/{id}/proof
• POST /exceptions (body = ExceptionObj sans AttestationMeta; server returns DSSE envelope)
• GET /audit-packs/{releaseDigest}

Guardrails

• Exceptions must never outlive a release line by default (force renewal).
• Creating an exception requires evidence hooks (see below).
• Build gates read exceptions; if proof no longer holds (reach diff changed), gate fails.

---

Knowledge Snapshots & Merge Semantics

Plain English: Take a sealed “photo” of everything you know at a point in time—SBOM, VEX, attestations, policies—so audits and incident reviews can be replayed exactly.

Lifecycle: Snapshot → Seal → Export

1. Snapshot

   • Capture: SBOM (CycloneDX 1.6 + SPDX 3.0.1), VEX docs, reach subgraphs, exception objects, policies, trust scores, feed versions, rules hashes.

2. Seal

   • Compute Manifest of Manifests (Merkle root) + DSSE signature (with PQ option).
   • Store to Authority (Postgres) and attach to image digest (OCI ref).

3. Export

   • Produce a single Replay Bundle (.stella-replay.tgz): data + REPLAY.yaml (inputs, versions, lattice rules).
   • Offline‑ready.

Policy pane with merge semantics

• Default preview: vendor ⊕ distro ⊕ internal (not “vendor > distro > internal”).

• Lattice rules define resolution (e.g., NOT_AFFECTED ⊕ AFFECTED → AFFECTED unless Evidence(feature_flag_off)).

• Evidence hooks (required):

  • “Not affected because feature X off” → must include feature‑flag attestation (env‑scoped, signed).
  • “Backported patch” → must include patch‑index mapping (fixed‑symbols, commit OIDs).
  • “Compensating control” → must include control attestation (control ID, monitoring link, SLO).

UI essentials

• Snapshot panel: shows inputs (feed versions, rules hash), diff vs last snapshot, “Seal & Export” button.
• Policy pane: interactive merge preview; failed hooks highlighted with “Add evidence” CTA.
• Replay check: “Verify determinism” runs local re‑eval; shows PASS/FAIL badge.

APIs

• POST /snapshots → returns SnapshotId + content hashes
• POST /snapshots/{id}/seal → returns DSSE + Merkle root
• GET /snapshots/{id}/export → stream bundle
• POST /policy/preview (inputs: sources+claims) → resolved verdict + missing-evidence list

Storage

• Postgres = system of record (immutable rows for sealed snapshots).
• Valkey (optional) = cache (diffs, precomputed subgraphs).
• OCI = distribution of attestations & snapshots alongside images.

---

PM & Dev acceptance checklist (short)

• Triage Inbox

  • Groups by exploit path, not by CVE alone.
  • Proof bundle includes reach subgraph + symbol map + VEX claims.
  • Exception modal enforces reason + expiry + recheck policy + evidence.
  • Exceptions are DSSE‑signed and appear in Audit Pack.

• Knowledge Snapshot

  • Snapshot records all inputs (feeds, rules, versions, hashes).
  • Seal produces a verifiable Merkle root + DSSE.
  • Export bundle replays deterministically offline.
  • Policy pane supports lattice merges + evidence hooks with blocking states.

---

Tiny implementation notes (.NET 10)

• Use record structs for small immutable IDs; keep hash fields as ReadOnlyMemory<byte>.
• Attest with in‑toto/DSSE; provide PQ toggle (Dilithium/Falcon) at key‑policy level.
• Graphs: store reach subgraph as compressed adjacency lists; index by (digest, symbol).

---

If you want, I can turn this into: (a) Swagger stubs, (b) EF Core schema + migrations, or (c) a Figma‑ready UI spec with screen flows and copy.