76 lines
5.4 KiB
Markdown
76 lines
5.4 KiB
Markdown
# Implementation plan — Vulnerability Explorer
|
||
|
||
## Delivery phases
|
||
- **Phase 1 – Findings Ledger & resolver**
|
||
Create append-only ledger, projector, ecosystem resolvers (npm/Maven/PyPI/Go/RPM/DEB), canonical advisory keys, and provenance hashing.
|
||
- **Phase 2 – API & simulation**
|
||
Ship Vuln Explorer API (list/detail/grouping/simulation), batch evaluation with Policy Engine rationales, and export orchestrator.
|
||
- **Phase 3 – Console & CLI workflows**
|
||
Deliver triage UI (assignments, comments, remediation plans, simulation bar), keyboard accessibility, and CLI commands (`stella vuln ...`) with JSON/CSV output.
|
||
- **Phase 4 – Automation & integrations**
|
||
Integrate Advisory AI hints, Zastava runtime exposure, Notify rules, Scheduler follow-up scans, and Graph Explorer deep links.
|
||
- **Phase 5 – Exports & offline parity**
|
||
Generate deterministic bundles (JSON, CSV, PDF, Offline Kit manifests), audit logs, and signed reports.
|
||
- **Phase 6 – Observability & hardening**
|
||
Complete dashboards (projection lag, MTTR, accepted-risk cadence), alerts, runbooks, performance tuning (5M findings/tenant), and security/RBAC validation.
|
||
|
||
## Work breakdown
|
||
- **Findings Ledger**
|
||
- Define event schema, Merkle root anchoring, append-only storage, history tables.
|
||
- Projector to `finding_records` and `finding_history`, idempotent event processing, time travel snapshots.
|
||
- Resolver pipelines referencing SBOM inventory deltas, policy outputs, VEX consensus, runtime signals.
|
||
- **API & exports**
|
||
- REST endpoints (`/v1/findings`, `/v1/findings/{id}`, `/actions`, `/reports`, `/exports`) with ABAC filters.
|
||
- Simulation endpoint returning diffs, integration with Policy Engine batch evaluation.
|
||
- Export jobs for JSON/CSV/PDF plus Offline Kit bundle assembly and signing.
|
||
- **Console**
|
||
- Feature module `vuln-explorer` with grid, filters, saved views, deep links, detail tabs (policy, evidence, paths, remediation).
|
||
- Simulation drawer, delta chips, accepted-risk approvals, evidence bundle viewer.
|
||
- Accessibility (keyboard navigation, ARIA), virtualization for large result sets.
|
||
- **CLI**
|
||
- Commands `stella vuln list|show|simulate|assign|accept-risk|verify-fix|export`.
|
||
- Stable schemas for automation; piping support; tests for exit codes.
|
||
- **Integrations**
|
||
- Conseiller/Excitor: normalized advisory keys, linksets, evidence retrieval.
|
||
- SBOM Service: inventory deltas with scope/runtime flags, safe version hints.
|
||
- Notify: events for SLA breaches, accepted-risk expiries, remediation deadlines.
|
||
- Scheduler: trigger rescans when remediation plan milestones complete.
|
||
- **Observability & ops**
|
||
- Metrics (open findings, MTTR, projection lag, export duration, SLA burn), logs/traces with correlation IDs.
|
||
- Alerting on projector backlog, API 5xx spikes, export failures, accepted-risk nearing expiry.
|
||
- Runbooks covering recompute storms, mapping errors, report issues.
|
||
|
||
## Acceptance criteria
|
||
- Ledger/event sourcing reproduces historical states byte-for-byte; Merkle hashes verify integrity.
|
||
- Resolver respects ecosystem semantics, scope, and runtime context; path evidence presented in UI/CLI.
|
||
- Triage workflows (assignment, comments, accepted-risk) enforce justification and approval requirements with audit records.
|
||
- Simulation returns policy diffs without mutating state; CLI/UI parity achieved for simulation and exports.
|
||
- Exports and Offline Kit bundles reproducible with signed manifests and provenance; reports available in JSON/CSV/PDF.
|
||
- Observability dashboards show green SLOs, alerts fire for projection lag or SLA burns, and runbooks documented.
|
||
- RBAC/ABAC validated; attachments encrypted; tenant isolation guaranteed.
|
||
|
||
## Risks & mitigations
|
||
- **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.
|
||
|
||
## Test strategy
|
||
- **Unit:** resolver algorithms, state machine transitions, policy mapping, export builders.
|
||
- **Integration:** ingestion → ledger → projector → API flow, simulation, Notify notifications.
|
||
- **E2E:** Console triage scenarios, CLI flows, accessibility tests.
|
||
- **Performance:** 5M findings/tenant, projection rebuild, export generation.
|
||
- **Security:** RBAC/ABAC matrix, CSRF, attachment encryption, signed URL expiry.
|
||
- **Determinism:** time-travel snapshots, export manifest hashing, Offline Kit replay.
|
||
|
||
## Definition of done
|
||
- Services, UI/CLI, integrations, exports, and observability deployed with runbooks and Offline Kit parity.
|
||
- Documentation suite (overview, using-console, API, CLI, findings ledger, policy mapping, VEX/SBOM integration, telemetry, security, runbooks, install) updated with imposed rule statement.
|
||
- ./TASKS.md and ../../TASKS.md reflect active progress; compliance checklists appended where required.
|
||
|
||
## Sprint alignment (2025-11-30)
|
||
- Docs refresh tracked in `docs/implplan/SPRINT_0334_0001_0001_docs_modules_vuln_explorer.md` (Docs/OPS/ENG streams).
|
||
- Observability runbook evidence lives under `runbooks/observability.md` with stub dashboard JSON for offline demos.
|
||
- API/OpenAPI references: `api.md` and `openapi/vuln-explorer.v1.yaml` are the current contract drafts; keep Console/CLI generators synced to these.
|