docs consolidation
This commit is contained in:
master
96
docs/modules/vuln-explorer/VULNERABILITY_EXPLORER_GUIDE.md
Normal file
96
docs/modules/vuln-explorer/VULNERABILITY_EXPLORER_GUIDE.md
Normal file
@@ -0,0 +1,96 @@
|
||||
# Vulnerability Explorer and Findings Ledger (Guide)
|
||||
|
||||
The Vulnerability Explorer is the StellaOps interface for vulnerability triage and remediation planning. It brings together SBOM facts, advisory/VEX evidence, reachability signals, and policy explanations into a single, auditable workflow.
|
||||
|
||||
This guide is intentionally conceptual. Concrete schemas, identifiers, and endpoint shapes are defined in the module dossiers and schema files.
|
||||
|
||||
## Core Objects
|
||||
|
||||
- **Finding record:** the current, enriched view of a vulnerability for a specific artifact/context (tenant, image digest/artifact id, policy version).
|
||||
- **Finding history:** append-only state transitions (who/what changed status and why), suitable for audit replay.
|
||||
- **Triage actions:** discrete operator actions (assignment, comment, mitigation note, ticket link, exception request) with provenance.
|
||||
- **Evidence references:** stable pointers to SBOM slices, advisory observations, VEX observations/linksets, reachability proofs, and attestation bundles.
|
||||
|
||||
## Triage UX Contract (Console)
|
||||
|
||||
Every triage surface should answer, in order:
|
||||
|
||||
1. Can I ship this?
|
||||
2. If not, what exactly blocks me?
|
||||
3. What's the minimum safe change to unblock?
|
||||
|
||||
Key expectations:
|
||||
|
||||
- **Narrative-first:** the default view for a finding is a case-style summary ("why") plus a visible evidence rail.
|
||||
- **Proof-linking is mandatory:** every chip/badge/assertion links to the evidence objects that justify it.
|
||||
- **Quiet by default, never silent:** muted/non-actionable lanes are hidden by default but surfaced via counts and toggles; muting never deletes evidence.
|
||||
- **Replayable:** the UI should support exporting a deterministic evidence bundle for offline/audit verification.
|
||||
|
||||
## Workflow (Operator View)
|
||||
|
||||
1. Start from a finding list filtered to the relevant tenant and time window.
|
||||
2. Open a finding to review:
|
||||
- Policy outcome (block/ship/needs exception)
|
||||
- Effective VEX status (and the underlying issuer evidence)
|
||||
- Reachability/impact signals (where available)
|
||||
- Advisory provenance and conflicts
|
||||
3. Record a triage action (assign, comment, request exception) with justification.
|
||||
4. Export an evidence bundle when review, escalation, or offline verification is required.
|
||||
|
||||
The default posture is VEX-first: VEX evidence and issuer trust are treated as first-class inputs to decisioning and explainability.
|
||||
|
||||
## Lanes and Signed Decisions
|
||||
|
||||
Most UIs need "lanes" (visibility buckets) derived from deterministic risk and operator decisions. Common examples:
|
||||
|
||||
- `ACTIVE`
|
||||
- `BLOCKED`
|
||||
- `NEEDS_EXCEPTION`
|
||||
- `MUTED_REACH` (not reachable)
|
||||
- `MUTED_VEX` (effective VEX is not_affected)
|
||||
- `COMPENSATED` (controls satisfy policy)
|
||||
|
||||
Decisions that change visibility or gating should be:
|
||||
|
||||
- Signed and auditable (who did what, when, and why).
|
||||
- Append-only (revoke/expire instead of delete).
|
||||
- Linked to the policy and evidence that justified the change.
|
||||
|
||||
## Smart-Diff History
|
||||
|
||||
The Explorer should make meaningful changes obvious:
|
||||
|
||||
- Maintain immutable snapshots of inputs/outputs for each finding.
|
||||
- Highlight meaningful changes (verdict/lane changes, threshold crossings, reachability changes, effective VEX changes).
|
||||
- Keep "details" available without overwhelming the default view.
|
||||
|
||||
## Determinism, Integrity, and Replay
|
||||
|
||||
The Explorer is designed to be replayable and tamper-evident:
|
||||
|
||||
- History and actions are append-only.
|
||||
- Exports use deterministic ordering and UTC timestamps.
|
||||
- Evidence bundles carry hashes/manifests so a third party can verify integrity without trusting a live service.
|
||||
- When Merkle anchoring is enabled, exports can include roots and inclusion proofs for additional tamper evidence.
|
||||
|
||||
## Offline / Air-Gap Operation
|
||||
|
||||
- Explorer workflows must work against Offline Kit snapshots when running in sealed environments.
|
||||
- The Console should surface snapshot identity and staleness (feeds, VEX, policy versions) rather than hiding it.
|
||||
- Export bundles are the primary bridge between online and offline review.
|
||||
|
||||
## Integration Points
|
||||
|
||||
- **Console UI:** findings list + triage case view; evidence drawers; export/download flows.
|
||||
- **Policy engine:** produces explainability traces and gates actions (for example, exception workflows).
|
||||
- **Graph/Reachability:** overlays and evidence slices for reachable vs not reachable decisions where available.
|
||||
- **VEX Lens / Excititor:** issuer trust, provenance, linksets, and effective status (see `docs/VEX_CONSENSUS_GUIDE.md`).
|
||||
|
||||
## Related Docs
|
||||
|
||||
- `docs/UI_GUIDE.md`
|
||||
- `docs/VEX_CONSENSUS_GUIDE.md`
|
||||
- `docs/modules/vuln-explorer/architecture.md`
|
||||
- `docs/modules/findings-ledger/schema.md`
|
||||
- `docs/modules/findings-ledger/merkle-anchor-policy.md`
|
||||
- `docs/ARCHITECTURE_OVERVIEW.md`
|
||||
@@ -98,7 +98,7 @@ Primary actions per card:
|
||||
|
||||
### 8.2 VEX Decision Model
|
||||
|
||||
VEX decisions follow the `VexDecision` schema (`docs/schemas/vex-decision.schema.json`):
|
||||
VEX decisions follow the `VexDecision` schema (`docs/modules/vuln-explorer/schemas/vex-decision.schema.json`):
|
||||
|
||||
**Status values:**
|
||||
- `NOT_AFFECTED` - Vulnerability does not apply to this artifact
|
||||
@@ -160,7 +160,7 @@ Request/response follows `VexDecisionDto` per schema.
|
||||
|
||||
### 8.5 Audit Bundle Export
|
||||
|
||||
Immutable audit bundles follow the `AuditBundleIndex` schema (`docs/schemas/audit-bundle-index.schema.json`):
|
||||
Immutable audit bundles follow the `AuditBundleIndex` schema (`docs/modules/evidence-locker/schemas/audit-bundle-index.schema.json`):
|
||||
|
||||
**Bundle contents:**
|
||||
- Vulnerability reports (scanner outputs)
|
||||
@@ -192,8 +192,8 @@ The triage UX aligns with industry patterns from:
|
||||
|
||||
The following JSON schemas define the data contracts for VEX and audit functionality:
|
||||
|
||||
- `docs/schemas/vex-decision.schema.json` - VEX decision form and persistence
|
||||
- `docs/schemas/attestation-vuln-scan.schema.json` - Vulnerability scan attestation predicate
|
||||
- `docs/schemas/audit-bundle-index.schema.json` - Audit bundle manifest
|
||||
- `docs/modules/vuln-explorer/schemas/vex-decision.schema.json` - VEX decision form and persistence
|
||||
- `docs/modules/attestor/schemas/attestation-vuln-scan.schema.json` - Vulnerability scan attestation predicate
|
||||
- `docs/modules/evidence-locker/schemas/audit-bundle-index.schema.json` - Audit bundle manifest
|
||||
|
||||
These schemas are referenced by both backend DTOs and frontend TypeScript interfaces.
|
||||
|
||||
Reference in New Issue
Block a user