dc7c75b496
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
feat: Implement BsonJsonConverter for converting BsonDocument and BsonArray to JSON fix: Update project file to include MongoDB.Bson package test: Add GraphOverlayExporterTests to validate NDJSON export functionality refactor: Refactor Program.cs in Attestation Tool for improved argument parsing and error handling docs: Update README for stella-forensic-verify with usage instructions and exit codes feat: Enhance HmacVerifier with clock skew and not-after checks feat: Add MerkleRootVerifier and ChainOfCustodyVerifier for additional verification methods fix: Update DenoRuntimeShim to correctly handle file paths feat: Introduce ComposerAutoloadData and related parsing in ComposerLockReader test: Add tests for Deno runtime execution and verification test: Enhance PHP package tests to include autoload data verification test: Add unit tests for HmacVerifier and verification logic
StellaOps Graph
Graph Indexer + Graph API build the tenant-scoped knowledge graph that powers blast-radius analysis, provenance timelines, and saved-query automation across StellaOps. Cartographer has been retired as of 2025-10-30 (see docs/updates/2025-10-30-devops-governance.md); this module now owns ingestion, storage, overlays, and query surfaces for graph data.
Scope & responsibilities
- Ingest SBOM snapshots, advisory/VEX events, policy overlays, and runtime signals to maintain a first-party graph representation with deterministic node/edge identities.
- Serve APIs and saved-query tooling for impact analysis, dependency traversal, diffing, and policy/VEX overlays with explainable provenance.
- Supply Graph Explorer UI/CLI experiences, plus Offline Kit exports (
nodes.jsonl,edges.jsonl,overlays/) with DSSE manifests for air-gapped replay. - Maintain the Graph Index Canonical Schema and coordinate query/overlay lifecycle with Scheduler, Policy Engine, Vulnerability Explorer, and Export Center.
Architecture snapshot (Sprint 30 groundwork)
- Graph Indexer service — consumes SBOM (
sbom_snapshot), advisory, and VEX events; normalises identifiers; persists intograph_nodes,graph_edges,graph_snapshots, and overlay caches with tenant partitions. - Graph API service — exposes
GET /graph/nodes,/graph/impact/{advisory},/graph/query/saved,/graph/diff, and overlay endpoints with RBAC scopes defined in Authority (docs/updates/2025-10-26-authority-graph-scopes.md). - Overlay & diff workers — materialise impact lists, saved-query caches, and signed diff manifests; feed Scheduler
GraphBuildJob/GraphOverlayJobcontracts (docs/updates/2025-10-26-scheduler-graph-jobs.md). - Console & CLI integrations — planned modules deliver WebGL explorer, timeline viz, and CLI
stella sbom graph ...commands aligned with implementation plan phases. - Storage abstraction — supports document + adjacency (Mongo) or pluggable graph engine; both paths enforce deterministic ordering and export manifests.
Current workstreams (Q4 2025)
GRAPH-SVC-30-00x(seesrc/Graph/StellaOps.Graph.Indexer/TASKS.md) — stand up Graph Indexer pipeline, identity registry, snapshot exports.- Active sprint:
docs/implplan/SPRINT_0141_0001_0001_graph_indexer.md(Runtime & Signals 140.A) — clustering/centrality jobs, incremental/backfill pipeline, determinism tests, packaging. GRAPH-API-30-00x— draft API planner/cost guard, streaming responses, and Authority scope integration.DOCS-GRAPH-24-003& related backlog — author overview/API/query language docs; update this README again once those deliverables land.- Deployment/DevOps follow-ups (
DEVOPS-VEX-30-001,DEPLOY-VEX-30-001) coordinate dashboards, load tests, and Helm/Compose overlays for the graph stack.
Integrations & dependencies
- SBOM Service (Scanner WebService + Worker) produce
sbom_snapshotevents consumed by Graph Indexer. - Concelier/Excititor contribute advisory + VEX edges; VEX Lens consensus overlays attach to graph nodes as attributes.
- Policy Engine & Scheduler trigger recompute jobs and consume overlays for risk/impact automation.
- Vulnerability Explorer & Console surface graph queries, saved views, and diff visualisations.
- Authority defines scopes (
graph.viewer,graph.operator) and client registrations; secrets managed via existing platform patterns.
Data, observability & offline
- Collections/tables:
graph_nodes,graph_edges,graph_snapshots,graph_saved_queries,graph_overlays_cache, append-only change logs for replay. - Metrics:
graph_ingest_lag_seconds,graph_nodes_total,graph_query_latency_seconds{queryId}, overlay/diff duration counters. - Logs/traces: structured ETL logs, query planner traces, WebGL interaction telemetry (once UI lands).
- Offline bundles: deterministic
nodes.jsonl,edges.jsonl, overlay manifests + DSSE signatures, consumable by Export Center and CLI mirroring.
Key docs & updates
architecture.md— inputs, pipelines, APIs, storage choices, observability, offline handling.implementation_plan.md— phased delivery roadmap, work breakdown, risks, test strategy.schema.md— canonical node/edge schema and attribute dictionary (keep in sync with indexer code).- Updates:
docs/updates/2025-10-26-scheduler-graph-jobs.md,docs/updates/2025-10-26-authority-graph-scopes.md,docs/updates/2025-10-30-devops-governance.mdfor the latest decisions/dependencies.
Epic alignment
- Epic 5 – SBOM Graph Explorer: Graph Indexer, Graph API, saved queries, overlays, Console/CLI experiences, Offline Kit parity.
- Cross-epic ties: Policy reasoning (explain overlays), Scheduler recompute, Notify/Task Runner integration for graph incidents.