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:
2025-10-30 00:09:39 +02:00
parent 3154c67978
commit 7b5bdcf4d3
503 changed files with 16136 additions and 54638 deletions

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