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:
		
							
								
								
									
										64
									
								
								docs/modules/graph/implementation_plan.md
									
									
									
									
									
										Normal file
									
								
							
							
						
						
									
										64
									
								
								docs/modules/graph/implementation_plan.md
									
									
									
									
									
										Normal file
									
								
							| @@ -0,0 +1,64 @@ | ||||
| # Implementation plan — Graph | ||||
|  | ||||
| ## Delivery phases | ||||
| - **Phase 1 – Graph Indexer foundations**   | ||||
|   Stand up Graph Indexer service, node/edge schemas, ingestion from SBOM/Concelier/Excititor events, identity stability, and snapshot materialisation. | ||||
| - **Phase 2 – Graph API service**   | ||||
|   Expose search, query, path, impact, diff, and overlay endpoints with RBAC, cost controls, and streaming responses. | ||||
| - **Phase 3 – Console & CLI experiences**   | ||||
|   Ship Graph Explorer UI (WebGL canvas, filters, diff mode, overlays) and CLI (`stella sbom graph ...`) for automation pipelines. | ||||
| - **Phase 4 – Advanced analytics**   | ||||
|   Implement clustering, centrality, saved queries, overlay caching, and Policy Engine explain integration. | ||||
| - **Phase 5 – Exports & offline**   | ||||
|   Deliver GraphML/CSV/NDJSON exports, Offline Kit bundles (`nodes.jsonl`, `edges.jsonl`, overlays), and deterministic manifests. | ||||
| - **Phase 6 – Observability & hardening**   | ||||
|   Complete dashboards, alerts, runbooks, load/perf testing, and a11y/accessibility review. | ||||
|  | ||||
| ## Work breakdown | ||||
| - **Services** | ||||
|   - Graph Indexer: event consumers, node/edge builders, snapshot/version handling, aggregate metrics. | ||||
|   - Graph API: validation, planner/cost guard, streaming tile engine, diff/overlay builder, exports. | ||||
|   - Worker jobs: clustering, diff, overlay materialisation with backpressure awareness. | ||||
| - **Data model & storage** | ||||
|   - Collections/tables (`graph_nodes`, `graph_edges`, `graph_snapshots`, `graph_saved_queries`, `graph_overlays_cache`), indexes, tenant partitioning, append-only change logs. | ||||
|   - Evaluate document + adjacency vs graph DB abstraction; ensure deterministic serialization for exports. | ||||
| - **Console** | ||||
|   - Feature module `graph-explorer` with routes, canvas renderer, panels, diff UI, saved queries, export workflows, a11y pass. | ||||
|   - Telemetry instrumentation for user interactions and query budgets. | ||||
| - **CLI & SDK** | ||||
|   - `stella sbom graph query|diff|impact|export`, with JSON schema and piping support. | ||||
|   - SDK utilities for automation and CI pipelines. | ||||
| - **Policy & VEX integration** | ||||
|   - Fetch explain traces for policy overlays, integrate VEX suppressions, align with Policy Engine & VEX Lens data models. | ||||
| - **Observability & Ops** | ||||
|   - Metrics (ingest lag, query latency, cache hit rate), log/traces, dashboards, alerting for runaway queries and OOM. | ||||
|   - Runbooks for incident classes (query denial, cache poisoning, degraded render). | ||||
| - **Documentation** | ||||
|   - Maintain overview, API, query language, console guide, CLI reference, policy/VEX integration docs with compliance checklists. | ||||
|  | ||||
| ## Acceptance criteria | ||||
| - Graph Indexer ingests SBOM/advisory/VEX events deterministically with tenant isolation and append-only provenance. | ||||
| - Graph API serves search/query/path/diff/overlay endpoints within budgeted latency and enforces cost limits + RBAC. | ||||
| - Console explorer visualises topology, overlays, diffs, saved queries; CLI commands mirror functionality for automation. | ||||
| - Exports (GraphML/CSV/NDJSON) and Offline Kit bundles reproduce snapshots and overlays with signed manifests. | ||||
| - Observability dashboards/alerts detect ingest lag, query failures, cache churn, and memory pressure; runbooks guide remediation. | ||||
| - Policy/VEX overlays align with Policy Engine explain traces and VEX suppressions. | ||||
|  | ||||
| ## Risks & mitigations | ||||
| - **Graph scale/complexity:** adopt adjacency compression, cached overlays, streaming pagination, enforced query budgets. | ||||
| - **Tenant bleed:** strict tenant filters, fuzz tests, data masking, compliance reviews. | ||||
| - **Runaway queries/visualization:** cost planner, query timeout, UI hints, safe mode renders. | ||||
| - **Cache poisoning:** input validation, schema versioning, eviction policies. | ||||
| - **Offline parity gaps:** deterministic export pipeline, integration tests for Offline Kit import. | ||||
|  | ||||
| ## Test strategy | ||||
| - **Unit:** node/edge builders, identifier stability, overlay computations, query planner, diff engine. | ||||
| - **Integration:** end-to-end ingest + query flows across SBOM/advisory/VEX, saved query execution, diff exports. | ||||
| - **Performance:** large SBOM datasets, concurrency, memory profiling, WebGL rendering. | ||||
| - **Security:** tenant isolation tests, RBAC, query cost abuse. | ||||
| - **Offline:** export/import verification, manifest hashing, CLI replay. | ||||
|  | ||||
| ## Definition of done | ||||
| - All phases delivered with telemetry, documentation, runbooks, and Offline Kit parity. | ||||
| - Console/CLI parity validated; a11y review complete. | ||||
| - ./TASKS.md and ../../TASKS.md updated; README/architecture/plan kept current with imposed rule references. | ||||
		Reference in New Issue
	
	Block a user