master
7b5bdcf4d3
- 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.
65 lines
4.4 KiB
Markdown
65 lines
4.4 KiB
Markdown
# 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.
|