stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 3 Releases Wiki Activity

save progress

Browse Source
This commit is contained in:
StellaOps Bot
2025-12-20 12:15:16 +02:00
parent 439f10966b
commit 0ada1b583f
95 changed files with 12400 additions and 65 deletions
Download Patch File Download Diff File Expand all files Collapse all files

419
docs/modules/ui/wireframes/proof-visualization-wireframes.md Normal file
View File

@@ -0,0 +1,419 @@
# 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