5590a99a1a
- Created `StellaOps.TestKit.Tests` project for unit tests related to determinism. - Implemented `DeterminismManifestTests` to validate deterministic output for canonical bytes and strings, file read/write operations, and error handling for invalid schema versions. - Added `SbomDeterminismTests` to ensure identical inputs produce consistent SBOMs across SPDX 3.0.1 and CycloneDX 1.6/1.7 formats, including parallel execution tests. - Updated project references in `StellaOps.Integration.Determinism` to include the new determinism testing library.
97 lines
4.6 KiB
Markdown
97 lines
4.6 KiB
Markdown
# 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/16_VEX_CONSENSUS_GUIDE.md`).
|
|
|
|
## Related Docs
|
|
|
|
- `docs/15_UI_GUIDE.md`
|
|
- `docs/16_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/07_HIGH_LEVEL_ARCHITECTURE.md`
|