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