# 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`