420 lines
35 KiB
Markdown
420 lines
35 KiB
Markdown
# Proof Visualization Wireframes
|
||
|
||
**Version:** 1.0.0
|
||
**Status:** APPROVED
|
||
**Created:** 2025-12-20
|
||
**Sprint Reference:** SPRINT_3500_0001_0001
|
||
|
||
---
|
||
|
||
## Overview
|
||
|
||
This document provides UX wireframes for the proof visualization features in StellaOps Console. These wireframes support:
|
||
|
||
1. **Proof Ledger View** — Displaying deterministic proof chains
|
||
2. **Score Replay Panel** — Verifying bit-identical replay
|
||
3. **Unknowns Queue** — Managing ambiguity triage
|
||
4. **Reachability Explain Widget** — Visualizing call-graph paths
|
||
5. **Proof Chain Inspector** — Deep-diving attestation chains
|
||
|
||
---
|
||
|
||
## 1. Proof Ledger View
|
||
|
||
### Purpose
|
||
Display the cryptographic proof chain for a scan, showing how the score was calculated with frozen feed snapshots.
|
||
|
||
### Wireframe
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────────────────┐
|
||
│ Scan: alpine:3.18 @ sha256:abc123... [Replay] [Export] │
|
||
├─────────────────────────────────────────────────────────────────────────────┤
|
||
│ │
|
||
│ ┌─────────────────────────────────────────────────────────────────────┐ │
|
||
│ │ PROOF CHAIN ✓ Verified │ │
|
||
│ ├─────────────────────────────────────────────────────────────────────┤ │
|
||
│ │ │ │
|
||
│ │ ┌──────────────────┐ │ │
|
||
│ │ │ SCAN MANIFEST │ │ │
|
||
│ │ │ ─────────────────│ │ │
|
||
│ │ │ ID: scan-7f3a... │ │ │
|
||
│ │ │ Artifact: alpine │ │ │
|
||
│ │ │ ┌──────────────┐ │ │ │
|
||
│ │ │ │ Concelier ↓ │ │ sha256:feed123... │ │
|
||
│ │ │ │ Snapshot │─┼──────────────────────────────────────┐ │ │
|
||
│ │ │ └──────────────┘ │ │ │ │
|
||
│ │ │ ┌──────────────┐ │ │ │ │
|
||
│ │ │ │ Excititor ↓ │ │ sha256:vex456... │ │ │
|
||
│ │ │ │ Snapshot │─┼───────────────────────────────┐ │ │ │
|
||
│ │ │ └──────────────┘ │ │ │ │ │
|
||
│ │ └──────────────────┘ │ │ │ │
|
||
│ │ │ │ │ │ │
|
||
│ │ ▼ │ │ │ │
|
||
│ │ ┌──────────────────┐ │ │ │ │
|
||
│ │ │ PROOF BUNDLE │ │ │ │ │
|
||
│ │ │ ─────────────────│ │ │ │ │
|
||
│ │ │ Root Hash: │ │ │ │ │
|
||
│ │ │ sha256:proof789. │ │ │ │ │
|
||
│ │ │ │ │ │ │ │
|
||
│ │ │ [View CBOR] │ │ │ │ │
|
||
│ │ │ [View DSSE] │ │ │ │ │
|
||
│ │ └──────────────────┘ │ │ │ │
|
||
│ │ │ │ │ │ │
|
||
│ │ ▼ ▼ ▼ │ │
|
||
│ │ ┌──────────────────────────────────────────────────────────────┐ │ │
|
||
│ │ │ FROZEN FEEDS AT SCAN TIME │ │ │
|
||
│ │ │ ─────────────────────────────────────────────────────────────│ │ │
|
||
│ │ │ Concelier: 2025-12-20T10:30:00Z (142,847 advisories) │ │ │
|
||
│ │ │ Excititor: 2025-12-20T10:30:00Z (23,491 VEX statements) │ │ │
|
||
│ │ └──────────────────────────────────────────────────────────────┘ │ │
|
||
│ │ │ │
|
||
│ └─────────────────────────────────────────────────────────────────────┘ │
|
||
│ │
|
||
│ ┌─────────────────────────────────────────────────────────────────────┐ │
|
||
│ │ PROOF SEGMENTS [Expand All]│ │
|
||
│ ├─────────────────────────────────────────────────────────────────────┤ │
|
||
│ │ │ │
|
||
│ │ #1 score_delta CVE-2024-1234 +7.5 → 8.2 [View Details] │ │
|
||
│ │ #2 vex_claim CVE-2024-1234 not_affected [View Claim] │ │
|
||
│ │ #3 reachability CVE-2024-1235 unreachable [View Graph] │ │
|
||
│ │ #4 unknown_band pkg:apk/libcrypto WARM [View Queue] │ │
|
||
│ │ │ │
|
||
│ └─────────────────────────────────────────────────────────────────────┘ │
|
||
│ │
|
||
└─────────────────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### Key Elements
|
||
|
||
| Element | Description | Interaction |
|
||
|---------|-------------|-------------|
|
||
| Scan Header | Artifact digest + scan ID | Click to copy |
|
||
| Proof Chain Status | ✓ Verified / ⚠ Unverified / ✗ Failed | Hover for details |
|
||
| Replay Button | Triggers score replay verification | Opens replay modal |
|
||
| Export Button | Downloads proof bundle (CBOR + DSSE) | ZIP download |
|
||
| Proof Segments | Expandable list of score decisions | Click to expand |
|
||
|
||
---
|
||
|
||
## 2. Score Replay Panel
|
||
|
||
### Purpose
|
||
Allow users to verify that a scan produces identical results when replayed with frozen feeds.
|
||
|
||
### Wireframe
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────────────────┐
|
||
│ ⟲ Score Replay Verification [Close] │
|
||
├─────────────────────────────────────────────────────────────────────────────┤
|
||
│ │
|
||
│ ┌─────────────────────────────────────────────────────────────────────┐ │
|
||
│ │ │ │
|
||
│ │ Original Scan Replay Result │ │
|
||
│ │ ───────────── ───────────── │ │
|
||
│ │ │ │
|
||
│ │ Proof Root: Proof Root: │ │
|
||
│ │ sha256:proof789... sha256:proof789... │ │
|
||
│ │ │ │
|
||
│ │ Score: 8.2 Score: 8.2 │ │
|
||
│ │ Findings: 47 Findings: 47 │ │
|
||
│ │ Critical: 3 Critical: 3 │ │
|
||
│ │ High: 12 High: 12 │ │
|
||
│ │ │ │
|
||
│ │ ════════ │ │
|
||
│ │ ║ MATCH ║ │ │
|
||
│ │ ════════ │ │
|
||
│ │ │ │
|
||
│ │ ✓ Bit-identical replay confirmed │ │
|
||
│ │ ✓ Proof root hashes match │ │
|
||
│ │ ✓ All 47 findings reproduced exactly │ │
|
||
│ │ │ │
|
||
│ └─────────────────────────────────────────────────────────────────────┘ │
|
||
│ │
|
||
│ ┌─────────────────────────────────────────────────────────────────────┐ │
|
||
│ │ Replay Details │ │
|
||
│ ├─────────────────────────────────────────────────────────────────────┤ │
|
||
│ │ Replayed At: 2025-12-20T14:22:30Z │ │
|
||
│ │ Scanner Version: 1.42.0 (same as original) │ │
|
||
│ │ Concelier Snapshot: sha256:feed123... (frozen) │ │
|
||
│ │ Excititor Snapshot: sha256:vex456... (frozen) │ │
|
||
│ │ Duration: 1.23s │ │
|
||
│ └─────────────────────────────────────────────────────────────────────┘ │
|
||
│ │
|
||
│ [Download Replay Report] [View Diff (none)] │
|
||
│ │
|
||
└─────────────────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### States
|
||
|
||
| State | Display | Actions |
|
||
|-------|---------|---------|
|
||
| Replaying | Spinner + progress bar | Cancel |
|
||
| Match | Green ✓ MATCH banner | Download report |
|
||
| Mismatch | Red ✗ MISMATCH banner | View diff, escalate |
|
||
| Error | Yellow ⚠ ERROR banner | Retry, view logs |
|
||
|
||
---
|
||
|
||
## 3. Unknowns Queue
|
||
|
||
### Purpose
|
||
Display packages with ambiguous or missing data, ranked by urgency for triage.
|
||
|
||
### Wireframe
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────────────────┐
|
||
│ Unknowns Queue [Filter ▾] [Export CSV] │
|
||
├─────────────────────────────────────────────────────────────────────────────┤
|
||
│ │
|
||
│ ┌───────────────────────────────────────────────────────────────────────┐ │
|
||
│ │ Summary │ │
|
||
│ │ ═══════════════════════════════════════════════════════════════════════│ │
|
||
│ │ 🔴 HOT: 12 🟠 WARM: 47 🔵 COLD: 234 ✓ RESOLVED: 1,892 │ │
|
||
│ └───────────────────────────────────────────────────────────────────────┘ │
|
||
│ │
|
||
│ ┌───────────────────────────────────────────────────────────────────────┐ │
|
||
│ │ HOT Queue (requires immediate attention) │ │
|
||
│ ├───────────────────────────────────────────────────────────────────────┤ │
|
||
│ │ │ │
|
||
│ │ Score │ Package │ Uncertainty │ Pressure │ Age │ │
|
||
│ │ ──────┼────────────────────────────┼─────────────┼──────────┼─────── │ │
|
||
│ │ 94.2 │ pkg:npm/lodash@4.17.21 │ 0.89 │ 0.95 │ 2d │ │
|
||
│ │ │ Missing: CVE-2024-9999 VEX │ │ │ │ │
|
||
│ │ │ [Research] [Request VEX] [Suppress] │ │
|
||
│ │ ──────┼────────────────────────────┼─────────────┼──────────┼─────── │ │
|
||
│ │ 87.5 │ pkg:maven/log4j@2.17.1 │ 0.72 │ 0.98 │ 5d │ │
|
||
│ │ │ Missing: Reachability data │ │ │ │ │
|
||
│ │ │ [Analyze] [Mark Reviewed] [Suppress] │ │
|
||
│ │ ──────┼────────────────────────────┼─────────────┼──────────┼─────── │ │
|
||
│ │ ... │ │ │ │ │ │
|
||
│ │ │ │
|
||
│ └───────────────────────────────────────────────────────────────────────┘ │
|
||
│ │
|
||
│ ┌───────────────────────────────────────────────────────────────────────┐ │
|
||
│ │ Ranking Factors │ │
|
||
│ ├───────────────────────────────────────────────────────────────────────┤ │
|
||
│ │ │ │
|
||
│ │ Score = (Uncertainty × 50) + (Exploit Pressure × 50) │ │
|
||
│ │ │ │
|
||
│ │ Uncertainty: │ │
|
||
│ │ - Missing VEX statement: +0.40 │ │
|
||
│ │ - Missing reachability: +0.30 │ │
|
||
│ │ - Conflicting sources: +0.20 │ │
|
||
│ │ - Stale advisory (>90d): +0.10 │ │
|
||
│ │ │ │
|
||
│ │ Exploit Pressure: │ │
|
||
│ │ - In KEV list: +0.50 │ │
|
||
│ │ - EPSS ≥ 0.90: +0.30 │ │
|
||
│ │ - EPSS ≥ 0.50: +0.15 │ │
|
||
│ │ - CVSS ≥ 9.0: +0.05 │ │
|
||
│ │ │ │
|
||
│ └───────────────────────────────────────────────────────────────────────┘ │
|
||
│ │
|
||
└─────────────────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### Band Definitions
|
||
|
||
| Band | Score Range | Color | SLA |
|
||
|------|-------------|-------|-----|
|
||
| HOT | 75-100 | 🔴 Red | 24h |
|
||
| WARM | 50-74 | 🟠 Orange | 7d |
|
||
| COLD | 25-49 | 🔵 Blue | 30d |
|
||
| RESOLVED | 0-24 / Resolved | ✓ Green | N/A |
|
||
|
||
---
|
||
|
||
## 4. Reachability Explain Widget
|
||
|
||
### Purpose
|
||
Show the call-graph path from entrypoint to vulnerable code, explaining why a finding is reachable or unreachable.
|
||
|
||
### Wireframe
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────────────────┐
|
||
│ Reachability: CVE-2024-1234 in pkg:npm/lodash@4.17.21 │
|
||
├─────────────────────────────────────────────────────────────────────────────┤
|
||
│ │
|
||
│ Status: ✓ REACHABLE Paths Found: 3 │
|
||
│ Shortest Path: 4 hops Confidence: 98% │
|
||
│ │
|
||
│ ┌───────────────────────────────────────────────────────────────────────┐ │
|
||
│ │ Shortest Path (4 hops) │ │
|
||
│ ├───────────────────────────────────────────────────────────────────────┤ │
|
||
│ │ │ │
|
||
│ │ ┌─────────────────────────┐ │ │
|
||
│ │ │ 🚪 ENTRYPOINT │ │ │
|
||
│ │ │ POST /api/users │ │ │
|
||
│ │ │ UsersController.Create()│ │ │
|
||
│ │ └───────────┬─────────────┘ │ │
|
||
│ │ │ static call │ │
|
||
│ │ ▼ │ │
|
||
│ │ ┌─────────────────────────┐ │ │
|
||
│ │ │ UserService.ValidateInput│ │ │
|
||
│ │ │ src/services/user.ts:42 │ │ │
|
||
│ │ └───────────┬─────────────┘ │ │
|
||
│ │ │ static call │ │
|
||
│ │ ▼ │ │
|
||
│ │ ┌─────────────────────────┐ │ │
|
||
│ │ │ ValidationHelper.sanitize│ │ │
|
||
│ │ │ src/utils/validate.ts:18│ │ │
|
||
│ │ └───────────┬─────────────┘ │ │
|
||
│ │ │ static call │ │
|
||
│ │ ▼ │ │
|
||
│ │ ┌─────────────────────────┐ │ │
|
||
│ │ │ 🎯 VULNERABLE CODE │ │ │
|
||
│ │ │ lodash.template() │ │ │
|
||
│ │ │ CVE-2024-1234 │ │ │
|
||
│ │ └─────────────────────────┘ │ │
|
||
│ │ │ │
|
||
│ └───────────────────────────────────────────────────────────────────────┘ │
|
||
│ │
|
||
│ ┌───────────────────────────────────────────────────────────────────────┐ │
|
||
│ │ All Paths (3) [Expand All] │ │
|
||
│ ├───────────────────────────────────────────────────────────────────────┤ │
|
||
│ │ Path 1: POST /api/users → ... → lodash.template() (4 hops) ✓ │ │
|
||
│ │ Path 2: POST /api/admin → ... → lodash.template() (6 hops) ✓ │ │
|
||
│ │ Path 3: GET /api/search → ... → lodash.template() (5 hops) ✓ │ │
|
||
│ └───────────────────────────────────────────────────────────────────────┘ │
|
||
│ │
|
||
│ [View Full Graph] [Export DSSE Attestation] │
|
||
│ │
|
||
└─────────────────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### Reachability States
|
||
|
||
| Status | Icon | Description |
|
||
|--------|------|-------------|
|
||
| REACHABLE | ✓ Green | At least one path found from entrypoint to vulnerable code |
|
||
| UNREACHABLE | ✗ Gray | No paths found; vulnerability in inactive code |
|
||
| PARTIAL | ⚠ Yellow | Some paths found but confidence < 80% |
|
||
| UNKNOWN | ? Blue | Analysis incomplete (missing call-graph data) |
|
||
|
||
---
|
||
|
||
## 5. Proof Chain Inspector
|
||
|
||
### Purpose
|
||
Deep-dive into the cryptographic attestation chain, showing DSSE envelopes and Rekor log entries.
|
||
|
||
### Wireframe
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────────────────┐
|
||
│ Proof Chain Inspector [Close] │
|
||
├─────────────────────────────────────────────────────────────────────────────┤
|
||
│ │
|
||
│ ┌───────────────────────────────────────────────────────────────────────┐ │
|
||
│ │ Chain Overview │ │
|
||
│ ├───────────────────────────────────────────────────────────────────────┤ │
|
||
│ │ │ │
|
||
│ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │
|
||
│ │ │ SBOM │───▶│ Scan │───▶│ Proof │───▶│ DSSE │ │ │
|
||
│ │ │ Digest │ │Manifest │ │ Bundle │ │Envelope │ │ │
|
||
│ │ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │ │
|
||
│ │ │ │ │ │ │ │
|
||
│ │ ▼ ▼ ▼ ▼ │ │
|
||
│ │ ✓ Verified ✓ Verified ✓ Verified ✓ Verified │ │
|
||
│ │ │ │
|
||
│ │ ┌─────────┐ │ │
|
||
│ │ │ Rekor │ Log Index: 12847392 │ │
|
||
│ │ │ Log │ Timestamp: 2025-12-20T10:30:00Z │ │
|
||
│ │ └─────────┘ │ │
|
||
│ │ │ │ │
|
||
│ │ ▼ │ │
|
||
│ │ ✓ Logged │ │
|
||
│ │ │ │
|
||
│ └───────────────────────────────────────────────────────────────────────┘ │
|
||
│ │
|
||
│ ┌───────────────────────────────────────────────────────────────────────┐ │
|
||
│ │ DSSE Envelope [Copy] │ │
|
||
│ ├───────────────────────────────────────────────────────────────────────┤ │
|
||
│ │ │ │
|
||
│ │ { │ │
|
||
│ │ "payloadType": "application/vnd.stellaops.proof+cbor", │ │
|
||
│ │ "payload": "base64...", │ │
|
||
│ │ "signatures": [ │ │
|
||
│ │ { │ │
|
||
│ │ "keyid": "sha256:signer123...", │ │
|
||
│ │ "sig": "base64..." │ │
|
||
│ │ } │ │
|
||
│ │ ] │ │
|
||
│ │ } │ │
|
||
│ │ │ │
|
||
│ └───────────────────────────────────────────────────────────────────────┘ │
|
||
│ │
|
||
│ ┌───────────────────────────────────────────────────────────────────────┐ │
|
||
│ │ Signer Information │ │
|
||
│ ├───────────────────────────────────────────────────────────────────────┤ │
|
||
│ │ │ │
|
||
│ │ Key ID: sha256:signer123... │ │
|
||
│ │ Algorithm: ECDSA P-256 │ │
|
||
│ │ Issuer: StellaOps Scanner v1.42.0 │ │
|
||
│ │ Trust Tier: VENDOR │ │
|
||
│ │ Valid From: 2025-01-01T00:00:00Z │ │
|
||
│ │ Valid Until: 2026-01-01T00:00:00Z │ │
|
||
│ │ │ │
|
||
│ │ [View Certificate] [Verify Signature] │ │
|
||
│ │ │ │
|
||
│ └───────────────────────────────────────────────────────────────────────┘ │
|
||
│ │
|
||
└─────────────────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## Component Summary
|
||
|
||
| Wireframe | Angular Component | Route |
|
||
|-----------|-------------------|-------|
|
||
| Proof Ledger View | `ProofLedgerComponent` | `/scans/:id/proof` |
|
||
| Score Replay Panel | `ScoreReplayModalComponent` | Modal overlay |
|
||
| Unknowns Queue | `UnknownsQueueComponent` | `/unknowns` |
|
||
| Reachability Explain | `ReachabilityExplainComponent` | `/findings/:id/reachability` |
|
||
| Proof Chain Inspector | `ProofChainInspectorComponent` | Modal overlay |
|
||
|
||
---
|
||
|
||
## Design Tokens
|
||
|
||
| Token | Value | Usage |
|
||
|-------|-------|-------|
|
||
| `--color-verified` | `#22c55e` | Verified status badges |
|
||
| `--color-mismatch` | `#ef4444` | Failed verification |
|
||
| `--color-unknown` | `#3b82f6` | Unknown/pending status |
|
||
| `--color-hot` | `#dc2626` | HOT band indicators |
|
||
| `--color-warm` | `#f97316` | WARM band indicators |
|
||
| `--color-cold` | `#2563eb` | COLD band indicators |
|
||
|
||
---
|
||
|
||
## Accessibility
|
||
|
||
- All status indicators include text labels (not just colors)
|
||
- Call-graph paths are keyboard-navigable
|
||
- ARIA labels on interactive elements
|
||
- High-contrast mode supported via theme tokens
|
||
|
||
---
|
||
|
||
## Approval
|
||
|
||
**UX Guild:** ☑ Approved 2025-12-20
|
||
**Product Management:** ☑ Approved 2025-12-20
|
||
**Accessibility Review:** ☐ Pending
|
||
|
||
---
|
||
|
||
## References
|
||
|
||
- `docs/db/SPECIFICATION.md` Section 5.6-5.8 — Schema definitions
|
||
- `docs/24_OFFLINE_KIT.md` Section 2.2 — Proof replay workflow
|
||
- `SPRINT_3500_0001_0001_deeper_moat_master.md` — Feature requirements
|
||
- `docs/modules/ui/architecture.md` — Console architecture
|