test
This commit is contained in:
StellaOps Bot
@@ -0,0 +1,159 @@
|
||||
Here's a tight, first‑time‑friendly blueprint for two Stella Ops UX pillars—**Triage & Exceptions** and **Knowledge Snapshots & Merge Semantics**—with just enough background plus concrete specs your PMs/devs can ship.
|
||||
|
||||
---
|
||||
|
||||
# Triage & Exceptions (quiet‑by‑design)
|
||||
|
||||
**Why it matters (plain English):** Most scanners drown users in alerts. "Quiet‑by‑design" shows only *provable, reachable* risks and lets you create **auditable exceptions** (temporary waivers) that auto‑feed compliance packs.
|
||||
|
||||
**User flow**
|
||||
|
||||
1. **Inbox grouped by exploit path**
|
||||
|
||||
* Group key = `(artifact → package → vulnerable symbol → runtime path)`.
|
||||
* Each group shows: risk score, blast radius (count of dependents), EPSS/CVSS, and a "Proof" button.
|
||||
2. **Open a path → Proof bundle**
|
||||
|
||||
* **Reach subgraph** (who calls what).
|
||||
* **Symbol map** (function/offsets; source or binary map).
|
||||
* **VEX claims** (vendor/distro/internal) with trust score + signatures.
|
||||
3. **Raise Exception** (time‑boxed)
|
||||
|
||||
* **Required fields:** attested reason (dropdown + free text), expiry date, recheck policy (e.g., "fail build if new reachable path appears", "fail if EPSS > X").
|
||||
* **Attestation:** DSSE‑signed exception object, OCI‑attached to artifact digest.
|
||||
* Auto‑lands in **Audit Pack** (PDF/JSON bundle) and **Timeline**.
|
||||
|
||||
**Data model (C# POCO sketch)**
|
||||
|
||||
```csharp
|
||||
record ExploitPathId(string ArtifactDigest, string PackagePurl, string CveId, string Symbol, string EntryPathHash);
|
||||
|
||||
record ExceptionObj(
|
||||
string Id, ExploitPathId Path, string ReasonCode, string ReasonText,
|
||||
DateTimeOffset IssuedAt, DateTimeOffset ExpiresAt,
|
||||
RecheckPolicy Policy, EvidenceRef[] Evidence, AttestationMeta Att);
|
||||
```
|
||||
|
||||
**RecheckPolicy (examples)**
|
||||
|
||||
* `ReachGraphChange=Block`
|
||||
* `EPSSAbove=0.5`
|
||||
* `EnvScope=prod-only`
|
||||
* `UnknownsAbove=N → Block`
|
||||
|
||||
**UI essentials**
|
||||
|
||||
* **Inbox:** 3‑pane (List • Details • Proof).
|
||||
* **Proof drawer:** collapsible reach subgraph; one‑click JSON export.
|
||||
* **Exception modal:** expiry presets (7/30/90 days), reason templates (backport, feature‑flag‑off, compensating control).
|
||||
|
||||
**APIs (REST-ish)**
|
||||
|
||||
* `GET /triage/inbox?scope=env:prod&quiet=true`
|
||||
* `GET /triage/path/{id}/proof`
|
||||
* `POST /exceptions` (body = ExceptionObj sans AttestationMeta; server returns DSSE envelope)
|
||||
* `GET /audit-packs/{releaseDigest}`
|
||||
|
||||
**Guardrails**
|
||||
|
||||
* Exceptions must **never** outlive a release line by default (force renewal).
|
||||
* Creating an exception **requires evidence hooks** (see below).
|
||||
* Build gates read exceptions; if proof no longer holds (reach diff changed), gate fails.
|
||||
|
||||
---
|
||||
|
||||
# Knowledge Snapshots & Merge Semantics
|
||||
|
||||
**Plain English:** Take a sealed "photo" of everything you *know* at a point in time—SBOM, VEX, attestations, policies—so audits and incident reviews can be replayed exactly.
|
||||
|
||||
**Lifecycle: Snapshot → Seal → Export**
|
||||
|
||||
1. **Snapshot**
|
||||
|
||||
* Capture: SBOM (CycloneDX 1.6 + SPDX 3.0.1), VEX docs, reach subgraphs, exception objects, policies, trust scores, feed versions, rules hashes.
|
||||
2. **Seal**
|
||||
|
||||
* Compute **Manifest of Manifests** (Merkle root) + DSSE signature (with PQ option).
|
||||
* Store to **Authority** (Postgres) and attach to image digest (OCI ref).
|
||||
3. **Export**
|
||||
|
||||
* Produce a single **Replay Bundle** (`.stella-replay.tgz`): data + `REPLAY.yaml` (inputs, versions, lattice rules).
|
||||
* Offline‑ready.
|
||||
|
||||
**Policy pane with merge semantics**
|
||||
|
||||
* Default preview: **vendor ⊕ distro ⊕ internal** (not "vendor > distro > internal").
|
||||
* **Lattice rules** define resolution (e.g., `NOT_AFFECTED ⊕ AFFECTED → AFFECTED unless Evidence(feature_flag_off)`).
|
||||
* **Evidence hooks (required):**
|
||||
|
||||
* "Not affected because feature X off" → must include **feature‑flag attestation** (env‑scoped, signed).
|
||||
* "Backported patch" → must include **patch‑index** mapping (`fixed‑symbols`, commit OIDs).
|
||||
* "Compensating control" → must include **control attestation** (control ID, monitoring link, SLO).
|
||||
|
||||
**UI essentials**
|
||||
|
||||
* **Snapshot panel:** shows inputs (feed versions, rules hash), diff vs last snapshot, "Seal & Export" button.
|
||||
* **Policy pane:** interactive merge preview; failed hooks highlighted with "Add evidence" CTA.
|
||||
* **Replay check:** "Verify determinism" runs local re‑eval; shows PASS/FAIL badge.
|
||||
|
||||
**APIs**
|
||||
|
||||
* `POST /snapshots` → returns `SnapshotId` + content hashes
|
||||
* `POST /snapshots/{id}/seal` → returns DSSE + Merkle root
|
||||
* `GET /snapshots/{id}/export` → stream bundle
|
||||
* `POST /policy/preview` (inputs: sources+claims) → resolved verdict + missing-evidence list
|
||||
|
||||
**Storage**
|
||||
|
||||
* **Postgres** = system of record (immutable rows for sealed snapshots).
|
||||
* **Valkey** (optional) = cache (diffs, precomputed subgraphs).
|
||||
* **OCI** = distribution of attestations & snapshots alongside images.
|
||||
|
||||
---
|
||||
|
||||
# PM & Dev acceptance checklist (short)
|
||||
|
||||
* **Triage Inbox**
|
||||
|
||||
* [ ] Groups by exploit path, not by CVE alone.
|
||||
* [ ] Proof bundle includes reach subgraph + symbol map + VEX claims.
|
||||
* [ ] Exception modal enforces reason + expiry + recheck policy + evidence.
|
||||
* [ ] Exceptions are DSSE‑signed and appear in Audit Pack.
|
||||
|
||||
* **Knowledge Snapshot**
|
||||
|
||||
* [ ] Snapshot records *all* inputs (feeds, rules, versions, hashes).
|
||||
* [ ] Seal produces a verifiable Merkle root + DSSE.
|
||||
* [ ] Export bundle replays deterministically offline.
|
||||
* [ ] Policy pane supports lattice merges + evidence hooks with blocking states.
|
||||
|
||||
---
|
||||
|
||||
# Tiny implementation notes (.NET 10)
|
||||
|
||||
* Use **record structs** for small immutable IDs; keep hash fields as `ReadOnlyMemory<byte>`.
|
||||
* Attest with **in‑toto/DSSE**; provide PQ toggle (Dilithium/Falcon) at key‑policy level.
|
||||
* Graphs: store **reach subgraph** as compressed adjacency lists; index by `(digest, symbol)`.
|
||||
|
||||
---
|
||||
|
||||
If you want, I can turn this into: (a) Swagger stubs, (b) EF Core schema + migrations, or (c) a Figma‑ready UI spec with screen flows and copy.
|
||||
|
||||
---
|
||||
|
||||
## Archive Note
|
||||
|
||||
**Archived:** 2025-12-22
|
||||
|
||||
**Disposition:** Converted to implementation sprints:
|
||||
- `SPRINT_3900_0003_0001_exploit_path_inbox_proof_bundles.md`
|
||||
- `SPRINT_3900_0003_0002_recheck_policy_evidence_hooks.md`
|
||||
- `SPRINT_4100_0003_0001_snapshot_merge_preview_replay_ui.md`
|
||||
|
||||
**Documentation created:**
|
||||
- `docs/modules/triage/exploit-path-inbox.md`
|
||||
- `docs/modules/triage/proof-bundle-spec.md`
|
||||
- `docs/modules/policy/recheck-policy.md`
|
||||
- `docs/modules/policy/evidence-hooks.md`
|
||||
- `docs/modules/snapshot/replay-yaml.md`
|
||||
- `docs/modules/snapshot/merge-preview.md`
|
||||
Reference in New Issue
Block a user