ReachGraph

MERGED INTO GRAPH — the standalone service is gone (2026-09-08). reachgraph-web was a deployable of its own until SPRINT_20260722_023 GRA-10 deleted src/ReachGraph/, its compose service block, its publish key and its services-matrix row. The capability was not withdrawn: GRA-4 lifted the HTTP surface into src/Graph/__Libraries/StellaOps.ReachGraph.Application, GRA-9 composed it onto graph-api and proved it live, and the reachgraph.stella-ops.local alias now resolves to graph-api. Read the routes, hosting and deployment story in docs/modules/graph/architecture.md; the reachability model, schemas and guides below remain current and are owned by the Graph family.

Unified store for reachability subgraphs with edge-level explainability.

Audience: Policy authors and reachability consumers (Console, CLI, ExportCenter) who need to query and prove “exactly why a dependency is reachable,” and engineers populating the store from Scanner and Signals.

Purpose

The ReachGraph module provides a unified store for reachability subgraphs, enabling fast, deterministic, audit-ready answers to “exactly why a dependency is reachable.” It consolidates data from Scanner, Signals, and Attestor into content-addressed artifacts with edge-level explainability.

Quick Links

• Architecture - Technical design and implementation details
• Guides - Usage and query guides
• Schemas - ReachGraph schema definitions

Status

Key Features

• Unified Schema: reachgraph.min@v1 minimal subgraph format with edge explainability (ReachGraphMinimal)
• Content-Addressed Store: All artifacts identified by a BLAKE3-256 digest (blake3:<64-hex>)
• Slice Query API: Fast queries by package PURL, CVE, entrypoint, or file
• Deterministic Replay: Verify that same inputs produce same graph (audited in reachgraph.replay_log)
• DSSE Signing: Offline-verifiable proofs (signing hooks exist in StellaOps.ReachGraph.Signing; the signer is not yet wired into the WebService DI — graphs are stored unsigned today)

Dependencies

Upstream (this module depends on)

• Scanner - CallGraph data source; populates the store via POST /v1/reachgraphs
• Signals - runtime reachability facts, queried over HTTP (GET /signals/facts/{digest}) for the unified /v1/reachability/* API
• Attestor - DSSE signing model (hooks present; signer not wired in the WebService today)

Downstream (modules that depend on this)

• Policy Engine - Reachability-based policy evaluation
• Web Console - Reachability visualization
• CLI - Reachability queries
• ExportCenter - Reachability data exports

API Endpoints

Store API (ReachGraphController):

• POST /v1/reachgraphs - Upsert reachgraph (idempotent by digest)
• GET /v1/reachgraphs/{digest} - Retrieve reachgraph by digest
• GET /v1/reachgraphs/{digest}/slice - Query slice of reachgraph
• GET /v1/reachgraphs/by-artifact/{artifactDigest} - List subgraphs for an artifact
• POST /v1/reachgraphs/replay - Verify deterministic replay
• DELETE /v1/reachgraphs/{digest} - Delete a reachgraph (graph:admin only)

Unified reachability query API (ReachabilityController):

• POST /v1/reachability/{static|runtime|hybrid|batch}

CVE-symbol mapping API (CveMappingController):

• GET /v1/cve-mappings/{cveId}, GET /v1/cve-mappings/by-package, GET /v1/cve-mappings/by-symbol, POST /v1/cve-mappings, POST /v1/cve-mappings/analyze-patch, POST /v1/cve-mappings/{cveId}/enrich, GET /v1/cve-mappings/stats

All controllers are versioned under v1/.... Since SPRINT_20260904_003 ROA-7 these routes are served through the gateway by graph-api, not by this host. graph-api composes the same StellaOps.ReachGraph.Application controllers and owns the reachability CAS in stellaops_graph; reachgraph-web sets Router__Enabled: "false" and no longer registers with the Router, because two publishers of one prefix made the answering host vary per request. This host still serves the same controllers on its DIRECT reachgraph.stella-ops.local alias until SPRINT_20260722_023 GRA-10 retires it. It also exposes anonymous GET /healthz (liveness) and GET /readyz (readiness) probes plus a build-info endpoint.

See architecture.md for full endpoint, schema, and persistence detail.

Authentication & Authorization

• The service registers Authority resource-server authentication (AddStellaOpsResourceServerAuthentication, configuration section Authority:ResourceServer). Outside the Testing environment a fallback authorization policy requires an authenticated user on every endpoint that does not opt out with [AllowAnonymous] (only /healthz, /readyz, OpenAPI, and build-info are anonymous).
• The only scope-gated action today is DELETE /v1/reachgraphs/{digest}, which requires graph:admin (StellaOpsScopes.GraphAdmin, enforced by ReachGraphDestructiveActionAuthorizer). Missing scope returns 403 insufficient_scope; unauthenticated returns 401.
• Read and write endpoints currently require only an authenticated principal — they are not scope-gated. The canonical graph:read and graph:write scopes (defined in StellaOpsScopes) are not yet enforced on these routes; access is constrained by per-tenant rate limiting instead.
• Tenant scope is resolved from the canonical X-StellaOps-TenantId header (legacy X-Tenant-ID fallback) or the tenant JWT claim. PostgreSQL row-level security isolates each tenant’s subgraphs, slices, and replay logs via app.tenant_id.
• Rate limiting is per-tenant fixed-window: reachgraph-read allows 100 req/min, reachgraph-write allows 20 req/min; exhausted limits return 429.

Persistence

• PostgreSQL schema reachgraph (auto-migrated on startup via AddStartupMigrations from embedded 001_reachgraph_store.sql):
  • reachgraph.subgraphs — content-addressed gzip blob keyed by digest, with artifact_digest, tenant_id, scope/provenance JSONB, and node/edge counts.
  • reachgraph.slice_cache — precomputed slices (query_type in package/cve/entrypoint/file) with TTL expiry.
  • reachgraph.replay_log — audit log of deterministic replay verifications.
• Valkey/Redis (ConnectionStrings:Redis) provides the hot-path graph and slice cache (ReachGraphValkeyCache).

Related Documentation

• ReachGraph Architecture — full endpoint, schema, and persistence detail.
• API reference — generated endpoint reference.
• Scanner Architecture — CallGraph data source.
• Signals Architecture — runtime reachability facts.
• Policy Engine — primary downstream consumer of reachability verdicts.