feat(docs): Add comprehensive documentation for Vexer, Vulnerability Explorer, and Zastava modules
- Introduced AGENTS.md, README.md, TASKS.md, and implementation_plan.md for Vexer, detailing mission, responsibilities, key components, and operational notes. - Established similar documentation structure for Vulnerability Explorer and Zastava modules, including their respective workflows, integrations, and observability notes. - Created risk scoring profiles documentation outlining the core workflow, factor model, governance, and deliverables. - Ensured all modules adhere to the Aggregation-Only Contract and maintain determinism and provenance in outputs.
This commit is contained in:
		
							
								
								
									
										70
									
								
								docs/modules/vuln-explorer/implementation_plan.md
									
									
									
									
									
										Normal file
									
								
							
							
						
						
									
										70
									
								
								docs/modules/vuln-explorer/implementation_plan.md
									
									
									
									
									
										Normal file
									
								
							| @@ -0,0 +1,70 @@ | ||||
| # 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/Excitator: 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. | ||||
		Reference in New Issue
	
	Block a user