git.stella-ops.org/docs/modules/vuln-explorer/README.md

StellaOps Vulnerability Explorer

Vulnerability Explorer delivers policy-aware triage, investigation, and reporting surfaces for effective findings.

Latest updates (2025-11-30)

• Documentation refresh aligned to sprint 0334: added observability/runbook snapshot and cross-links to OpenAPI draft (./api.md) and schemas in architecture.md.
• New offline-friendly observability runbook at runbooks/observability.md plus stub Grafana JSON in runbooks/dashboards/.
• Retained 2025-11-03 access-control changes; verify Authority scopes before enabling attachment uploads (docs/updates/2025-11-03-vuln-explorer-access-controls.md).

Responsibilities

• Present policy-evaluated findings with advisory, VEX, SBOM, and runtime context.
• Capture triage workflow in an immutable findings ledger with role-based access.
• Provide pivots, exports, and reports for auditors and operations teams.
• Integrate explain traces, remediation notes, and offline bundles.

Key components

• Findings Ledger service + API.
• Console module and CLI verbs for triage workflows.
• Export integrations for reports and evidence packages.

Integrations & dependencies

• Policy Engine for effective findings streams.
• Concelier/Excititor for evidence provenance.
• Scheduler for remediation/verification jobs.
• Notify for triage notifications.

Operational notes

• Audit logging per Epic 6 requirements.
• Offline-ready CSV/PDF exports with deterministic hashes.
• Dashboards for MTTR and triage throughput.
• Observability runbook and dashboard stub: see runbooks/observability.md and runbooks/dashboards/vuln-explorer-observability.json (import locally).

Implementation Status

Phase 1 – Findings Ledger & resolver (In Progress)

• Append-only ledger with Merkle root anchoring
• Projector to finding_records and finding_history tables
• Ecosystem resolvers: npm/Maven/PyPI/Go/RPM/DEB with canonical advisory keys
• Provenance hashing and time-travel snapshots
• Idempotent event processing

Phase 2 – API & simulation (Planned)

• REST endpoints: /v1/findings (list/detail/grouping/simulation)
• Batch evaluation with Policy Engine rationales
• Export orchestrator for JSON/CSV/PDF
• Simulation endpoint returning diffs without state mutation

Phase 3 – Console & CLI workflows (Planned)

• Triage UI: assignments, comments, remediation plans, simulation bar
• Detail tabs: policy, evidence, paths, remediation
• Keyboard accessibility, virtualization for large result sets
• CLI commands: stella vuln list/show/simulate/assign/accept-risk/verify-fix/export

Phase 4 – Automation & integrations (Planned)

• Advisory AI hints integration
• Zastava runtime exposure correlation
• Notify rules for SLA breaches and deadlines
• Scheduler follow-up scans and Graph Explorer deep links

Phase 5 – Exports & offline parity (Planned)

• Deterministic bundles: JSON, CSV, PDF formats
• Offline Kit manifests with signed reports
• Audit logs and compliance exports
• Evidence bundle viewer

Phase 6 – Observability & hardening (Planned)

• Dashboards: projection lag, MTTR, accepted-risk cadence
• Alerts: projector backlog, API 5xx, export failures, expiring accepted-risk
• Performance tuning for 5M findings/tenant
• Security/RBAC validation and attachment encryption

Key Acceptance Criteria

• Ledger/event sourcing reproduces historical states byte-for-byte with Merkle verification
• Resolver respects ecosystem semantics, scope, runtime context
• Triage workflows enforce justification/approval with audit records
• Simulation returns policy diffs without mutating state; CLI/UI parity achieved
• Exports reproducible with signed manifests and provenance
• RBAC/ABAC validated; attachments encrypted; tenant isolation guaranteed

Technical Decisions & Risks

• Advisory identity collisions: strict canonicalization, linkset references, raw evidence access
• Resolver inaccuracies: property-based tests, path verification, manual override workflows
• Projection lag/backlog: autoscaling, queue backpressure, alerting, pause controls
• Export size/performance: streaming NDJSON, size estimators, chunked downloads
• User confusion on suppression: rationale tab, explicit badges, explain traces

Operational Assets (Sprint 0334 · 2025-11-30)

• Observability runbook: runbooks/observability.md
• Dashboard stub: runbooks/dashboards/vuln-explorer-observability.json
• OpenAPI draft: api.md and openapi/vuln-explorer.v1.yaml
• Access controls: docs/updates/2025-11-03-vuln-explorer-access-controls.md

Epic alignment

• Epic 6: Vulnerability Explorer.
• VULN stories tracked in ../../TASKS.md and src/VulnExplorer/**/TASKS.md.