stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 1 Releases Wiki Activity
Files
7b5bdcf4d3bee4e6f398d0226ba8cd3c2754e07a
git.stella-ops.org/docs/modules/graph/implementation_plan.md
master 7b5bdcf4d3 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.
2025-10-30 00:09:39 +02:00

4.4 KiB
Raw Blame History

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.