git.stella-ops.org/docs/ux/TRIAGE_UX_GUIDE.md

StellaOps Triage UX Guide (Narrative-First + Proof-Linked)

0. Scope

This guide specifies the user experience for StellaOps triage and evidence workflows:

• Narrative-first case view that answers the three operator questions quickly.
• Proof-linked evidence surfaces (SBOM/VEX/provenance/reachability/replay).
• Quiet-by-default noise controls with reversible, signed decisions.
• Smart-diff history that explains meaningful risk changes.

Architecture constraints:

• Lattice/risk evaluation executes in scanner.webservice.
• concelier and excititor preserve per-source provenance (every merged/pruned datum remains traceable to origin).

1. UX Contract

Every triage surface must answer, in order:

1. Can I ship this?
2. If not, what exactly blocks me?
3. What's the minimum safe change to unblock?

Everything else is secondary and should be progressively disclosed.

2. Primary Objects in the UX

• Finding/Case: a specific vuln/rule tied to an asset (image/artifact/environment).
• Risk Result: deterministic lattice output (score/verdict/lane), computed by scanner.webservice.
• Evidence Artifact: signed, hash-addressed proof objects (SBOM slice, VEX doc, provenance, reachability slice, replay manifest).
• Decision: reversible user/system action that changes visibility/gating (mute/ack/exception) and is always signed/auditable.
• Snapshot: immutable record of inputs/outputs hashes enabling smart-diff.

3. Global UX Principles

3.1 Narrative-first, list-second

Default view is a case narrative header plus an evidence rail. Lists exist for scanning and sorting, but not as the primary cognitive surface.

3.2 Time-to-evidence target

From pipeline alert click -> human-readable verdict + first evidence link:

• p95 <= 30 seconds (including auth and initial fetch)
• evidence is always one click away (no deep tab chains)

3.3 Proof-linking is mandatory

Any chip/badge that asserts a fact must link to the exact evidence object(s) that justify it.

Examples:

• "Reachable: Yes" -> call-stack slice and/or runtime hit record
• "VEX: not_affected" -> effective VEX assertion plus signature details
• "Blocked by Policy Gate X" -> policy artifact plus lattice explanation

3.4 Quiet by default, never silent

Muted lanes are hidden by default but surfaced with counts and a toggle. Muting never deletes; it creates a signed decision with TTL/reason and is reversible.

3.5 Deterministic and replayable

Users must be able to export an evidence bundle containing:

• scan replay manifest (feeds/rules/policies/hashes)
• signed artifacts
• outputs (risk result, snapshots)

so auditors can replay identically.

4. Information Architecture

4.1 Screens

1. Findings table (global)

• purpose: scan, sort, filter, jump into cases
• default: muted lanes hidden
• banner: shows count of auto-muted by policy with a "Show" toggle

2. Case view (single-page narrative)

• purpose: decision making plus proof review
• above fold: verdict + chips + deterministic score
• right rail: evidence list
• tabs (max 3):
  • Evidence (default)
  • Reachability & Impact
  • History (smart-diff)

3. Export / verify bundle

• purpose: offline/audit verification
• async export job, then download DSSE-signed bundle when enabled
• verification UI: signature status, hash tree, issuer chain

4.2 Lanes (visibility buckets)

Lanes are a UX categorization derived from deterministic risk plus decisions:

• ACTIVE
• BLOCKED
• NEEDS_EXCEPTION
• MUTED_REACH (non-reachable)
• MUTED_VEX (effective VEX says not_affected)
• COMPENSATED (controls satisfy policy)

Default: show ACTIVE/BLOCKED/NEEDS_EXCEPTION. Muted lanes appear behind a toggle and via the banner counts.

5. Case View Layout (Required)

5.1 Top Bar

• Asset name / image tag / environment
• Last evaluated time
• Policy profile name (e.g., "Strict CI Gate")

5.2 Verdict Banner (Above fold)

Large, unambiguous verdict:

• SHIP
• BLOCKED
• NEEDS EXCEPTION

Below verdict:

• One-line "why" summary (max ~140 chars), e.g. "Reachable path observed; exploit signal present; Policy 'prod-strict' blocks."

5.3 Chips (Each chip is clickable)

Minimum set:

• Reachability: Reachable / Not reachable / Unknown (with confidence)
• Effective VEX: affected / not_affected / under_investigation
• Exploit signal: yes/no + source indicator
• Exposure: internet-exposed yes/no (if available)
• Asset tier: tier label
• Gate: allow/block/exception-needed (policy gate name)

Chip click behavior:

• opens evidence panel anchored to the proof objects
• shows source chain (concelier/excititor preserved sources)

5.4 Evidence Rail (Always visible right side)

List of evidence artifacts with:

• type icon
• title
• issuer
• signed/verified indicator
• short content digest
• created timestamp

Actions per item:

• preview
• copy digest
• open raw
• "show in bundle" marker

5.5 Actions Footer (Only primary actions)

• create work item
• acknowledge / mute (opens decision drawer)
• propose exception (decision with TTL plus approver chain)
• export evidence bundle

No more than 4 primary buttons. Secondary actions go into a menu.

6. Decision Flows (Mute/Ack/Exception)

6.1 Decision Drawer (common UI)

Fields:

• decision kind: mute reach / mute VEX / acknowledge / exception
• reason code (dropdown) plus free-text note
• TTL (required for exceptions; optional for mutes)
• policy ref (auto-filled; editable only by admins)
• sign and apply (server-side signing where enabled; user identity included)

On submit:

• create decision (audited)
• re-evaluate lane/verdict if applicable
• create snapshot ("DECISION" trigger)
• show toast with undo link

6.2 Undo

Undo is implemented as "revoke decision" (signed revoke record or revocation fields). Never delete.

7. Smart-Diff UX

7.1 Timeline

Chronological snapshots:

• when (timestamp)
• trigger (feed/vex/sbom/policy/runtime/decision/rescan)
• summary (short)

7.2 Diff panel

Two-column diff:

• inputs changed (with proof links): VEX assertion changed, policy version changed, runtime trace arrived, etc.
• outputs changed: lane, verdict, score, gates

7.3 Meaningful change definition

The UI only highlights meaningful changes:

• verdict change
• lane change
• score crosses a policy threshold
• reachability state changes
• effective VEX status changes

Other changes remain in expandable details.

8. Performance & UI Engineering Requirements

• findings table uses virtual scroll and server-side pagination
• case view loads in 2 steps:
  1. header narrative (small payload)
  2. evidence list plus snapshots (lazy)
• evidence previews are lazy-loaded and cancellable
• use ETag/If-None-Match for case and evidence list endpoints
• UI must remain usable under high latency (air-gapped / offline kits):
  • show cached last-known verdict with a clear "stale" marker
  • allow exporting bundles from cached artifacts when permissible

9. Accessibility & Operator Usability

• keyboard navigation: table rows, chips, evidence list
• high contrast mode supported
• all status is conveyed by text + shape (not color only)
• copy-to-clipboard for digests, purls, CVE IDs

10. Telemetry (Must instrument)

• TTFS: notification click -> verdict banner rendered
• time-to-proof: click chip -> proof preview shown
• mute reversal rate (auto-muted later becomes actionable)
• bundle export success/latency

11. Responsibilities by Service

• scanner.webservice:
  • produces reachability results, risk results, snapshots
  • stores/serves case narrative header, evidence indexes, smart-diff
• concelier:
  • aggregates vuln feeds and preserves per-source provenance
• excititor:
  • merges VEX and preserves original assertion sources
• notify.webservice:
  • emits first_signal / risk_changed / gate_blocked
• scheduler.webservice:
  • re-evaluates existing images on feed/policy updates, triggers snapshots

---

Document Version: 1.0 Target Platform: .NET 10, PostgreSQL >= 16, Angular v17