git.stella-ops.org/docs/VULNERABILITY_EXPLORER_GUIDE.md

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