96 lines
4.7 KiB
Markdown
96 lines
4.7 KiB
Markdown
# 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.
|