stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity
Files
491e8836535ab3daa30eff7a77f76f5b00331a74
git.stella-ops.org/docs/20_VULNERABILITY_EXPLORER_GUIDE.md
master 491e883653 Add tests for SBOM generation determinism across multiple formats 
- 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.
2025-12-24 00:36:14 +02:00

4.6 KiB
Raw Blame History

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