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