Add determinism tests for verdict artifact generation and update SHA256 sums script
- Implemented comprehensive tests for verdict artifact generation to ensure deterministic outputs across various scenarios, including identical inputs, parallel execution, and change ordering. - Created helper methods for generating sample verdict inputs and computing canonical hashes. - Added tests to validate the stability of canonical hashes, proof spine ordering, and summary statistics. - Introduced a new PowerShell script to update SHA256 sums for files, ensuring accurate hash generation and file integrity checks.
This commit is contained in:
StellaOps Bot
@@ -1,10 +1,219 @@
|
||||
# Archived: Triage UI Reducer Spec
|
||||
# StellaOps Triage UI Reducer Spec (Pure State + Explicit Commands)
|
||||
|
||||
This document was an in-development implementation spec for a deterministic UI reducer/state machine. It has been archived to:
|
||||
## 0. Purpose
|
||||
|
||||
- `docs/_archive/ux/TRIAGE_UI_REDUCER_SPEC.md`
|
||||
Define a deterministic, testable UI state machine for triage UI surfaces:
|
||||
|
||||
Canonical references:
|
||||
- State transitions are pure functions.
|
||||
- Side effects are emitted as explicit commands.
|
||||
- Enables UI replay for debugging (aligns with StellaOps determinism and replay ethos).
|
||||
|
||||
- `docs/modules/ui/architecture.md` (UI architecture and standards)
|
||||
- `docs/15_UI_GUIDE.md` (Console usage guide)
|
||||
Target stack: Angular v17 + TypeScript.
|
||||
|
||||
## 1. Core Concepts
|
||||
|
||||
- **Action:** user/system event (route change, button click, HTTP success).
|
||||
- **State:** all data required to render triage surfaces.
|
||||
- **Command:** side-effect request (HTTP, download, navigation).
|
||||
|
||||
Reducer signature:
|
||||
|
||||
```ts
|
||||
type ReduceResult = { state: TriageState; cmd: Command };
|
||||
function reduce(state: TriageState, action: Action): ReduceResult;
|
||||
```
|
||||
|
||||
## 2. State Model
|
||||
|
||||
```ts
|
||||
export type Lane =
|
||||
| "ACTIVE"
|
||||
| "BLOCKED"
|
||||
| "NEEDS_EXCEPTION"
|
||||
| "MUTED_REACH"
|
||||
| "MUTED_VEX"
|
||||
| "COMPENSATED";
|
||||
|
||||
export type Verdict = "SHIP" | "BLOCK" | "EXCEPTION";
|
||||
|
||||
export interface MutedCounts {
|
||||
reach: number;
|
||||
vex: number;
|
||||
compensated: number;
|
||||
}
|
||||
|
||||
export interface FindingRow {
|
||||
id: string; // caseId == findingId
|
||||
lane: Lane;
|
||||
verdict: Verdict;
|
||||
score: number;
|
||||
reachable: "YES" | "NO" | "UNKNOWN";
|
||||
vex: "affected" | "not_affected" | "under_investigation" | "unknown";
|
||||
exploit: "YES" | "NO" | "UNKNOWN";
|
||||
asset: string;
|
||||
updatedAt: string; // ISO-8601 UTC
|
||||
}
|
||||
|
||||
export interface CaseHeader {
|
||||
id: string;
|
||||
verdict: Verdict;
|
||||
lane: Lane;
|
||||
score: number;
|
||||
policyId: string;
|
||||
policyVersion: string;
|
||||
inputsHash: string;
|
||||
why: string; // short narrative
|
||||
chips: Array<{ key: string; label: string; value: string; evidenceIds?: string[] }>;
|
||||
}
|
||||
|
||||
export type EvidenceType =
|
||||
| "SBOM_SLICE"
|
||||
| "VEX_DOC"
|
||||
| "PROVENANCE"
|
||||
| "CALLSTACK_SLICE"
|
||||
| "REACHABILITY_PROOF"
|
||||
| "REPLAY_MANIFEST"
|
||||
| "POLICY"
|
||||
| "SCAN_LOG"
|
||||
| "OTHER";
|
||||
|
||||
export interface EvidenceItem {
|
||||
id: string;
|
||||
type: EvidenceType;
|
||||
title: string;
|
||||
issuer?: string;
|
||||
signed: boolean;
|
||||
signedBy?: string;
|
||||
contentHash: string;
|
||||
createdAt: string;
|
||||
previewUrl?: string;
|
||||
rawUrl: string;
|
||||
}
|
||||
|
||||
export type DecisionKind = "MUTE_REACH" | "MUTE_VEX" | "ACK" | "EXCEPTION";
|
||||
|
||||
export interface DecisionItem {
|
||||
id: string;
|
||||
kind: DecisionKind;
|
||||
reasonCode: string;
|
||||
note?: string;
|
||||
ttl?: string;
|
||||
actor: { subject: string; display?: string };
|
||||
createdAt: string;
|
||||
revokedAt?: string;
|
||||
signatureRef?: string;
|
||||
}
|
||||
|
||||
export type SnapshotTrigger =
|
||||
| "FEED_UPDATE"
|
||||
| "VEX_UPDATE"
|
||||
| "SBOM_UPDATE"
|
||||
| "RUNTIME_TRACE"
|
||||
| "POLICY_UPDATE"
|
||||
| "DECISION"
|
||||
| "RESCAN";
|
||||
|
||||
export interface SnapshotItem {
|
||||
id: string;
|
||||
trigger: SnapshotTrigger;
|
||||
changedAt: string;
|
||||
fromInputsHash: string;
|
||||
toInputsHash: string;
|
||||
summary: string;
|
||||
}
|
||||
|
||||
export interface SmartDiff {
|
||||
fromInputsHash: string;
|
||||
toInputsHash: string;
|
||||
inputsChanged: Array<{ key: string; before?: string; after?: string; evidenceIds?: string[] }>;
|
||||
outputsChanged: Array<{ key: string; before?: string; after?: string; evidenceIds?: string[] }>;
|
||||
}
|
||||
|
||||
export interface TriageState {
|
||||
route: { page: "TABLE" | "CASE"; caseId?: string };
|
||||
filters: {
|
||||
showMuted: boolean;
|
||||
lane?: Lane;
|
||||
search?: string;
|
||||
page: number;
|
||||
pageSize: number;
|
||||
};
|
||||
|
||||
table: {
|
||||
loading: boolean;
|
||||
rows: FindingRow[];
|
||||
mutedCounts?: MutedCounts;
|
||||
error?: string;
|
||||
etag?: string;
|
||||
};
|
||||
|
||||
caseView: {
|
||||
loading: boolean;
|
||||
header?: CaseHeader;
|
||||
evidenceLoading: boolean;
|
||||
evidence?: EvidenceItem[];
|
||||
decisionsLoading: boolean;
|
||||
decisions?: DecisionItem[];
|
||||
snapshotsLoading: boolean;
|
||||
snapshots?: SnapshotItem[];
|
||||
diffLoading: boolean;
|
||||
activeDiff?: SmartDiff;
|
||||
error?: string;
|
||||
etag?: string;
|
||||
};
|
||||
|
||||
ui: {
|
||||
decisionDrawerOpen: boolean;
|
||||
diffPanelOpen: boolean;
|
||||
toast?: { kind: "success" | "error" | "info"; message: string };
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
## 3. Commands
|
||||
|
||||
```ts
|
||||
export type Command =
|
||||
| { type: "NONE" }
|
||||
| { type: "HTTP_GET"; url: string; headers?: Record<string, string>; onSuccess: Action; onError: Action }
|
||||
| { type: "HTTP_POST"; url: string; body: unknown; headers?: Record<string, string>; onSuccess: Action; onError: Action }
|
||||
| { type: "HTTP_DELETE"; url: string; headers?: Record<string, string>; onSuccess: Action; onError: Action }
|
||||
| { type: "DOWNLOAD"; url: string }
|
||||
| { type: "NAVIGATE"; route: TriageState["route"] };
|
||||
```
|
||||
|
||||
## 4. Actions (Minimum Set)
|
||||
|
||||
Action unions will evolve, but should include:
|
||||
|
||||
- routing actions (`ROUTE_TABLE`, `ROUTE_CASE`)
|
||||
- table load and filter actions (`TABLE_LOAD`, `TABLE_LOAD_OK/ERR`, filter updates)
|
||||
- case load and nested resource actions (header/evidence/decisions/snapshots/diff)
|
||||
- decision drawer open/close and decision create/revoke actions
|
||||
- bundle export actions
|
||||
|
||||
## 5. Determinism Requirements
|
||||
|
||||
- Reducer must be pure (no global mutation, time access, randomness).
|
||||
- All derived URLs must be deterministic for a given state.
|
||||
- ETag/If-None-Match should be supported to reduce payload churn and improve sealed-mode behavior.
|
||||
|
||||
## 6. Unit Testing Requirements
|
||||
|
||||
Minimum tests:
|
||||
|
||||
- Reducer purity: no external effects.
|
||||
- `TABLE_LOAD` produces correct URL for filters.
|
||||
- `ROUTE_CASE` triggers case header load.
|
||||
- `CASE_LOAD_OK` triggers evidence load (and the integration layer triggers other nested loads deterministically).
|
||||
- `DECISION_CREATE_OK` closes drawer and refreshes case header.
|
||||
- `BUNDLE_EXPORT_OK` emits `DOWNLOAD`.
|
||||
|
||||
Recommended:
|
||||
|
||||
- Golden state snapshots to ensure backwards compatibility when the state model evolves.
|
||||
|
||||
---
|
||||
|
||||
**Document Version**: 1.0
|
||||
**Target Platform**: Angular v17 + TypeScript
|
||||
|
||||
@@ -1,10 +1,269 @@
|
||||
# Archived: Triage UX Guide
|
||||
# StellaOps Triage UX Guide (Narrative-First + Proof-Linked)
|
||||
|
||||
This document was an in-development UX specification. It has been archived to:
|
||||
## 0. Scope
|
||||
|
||||
- `docs/_archive/ux/TRIAGE_UX_GUIDE.md`
|
||||
This guide specifies the user experience for StellaOps triage and evidence workflows:
|
||||
|
||||
Canonical references:
|
||||
- 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.
|
||||
|
||||
- `docs/20_VULNERABILITY_EXPLORER_GUIDE.md` (triage workflow and determinism expectations)
|
||||
- `docs/15_UI_GUIDE.md` (Console usage guide)
|
||||
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
|
||||
|
||||
Reference in New Issue
Block a user