232 lines
12 KiB
Markdown
232 lines
12 KiB
Markdown
# ReachGraph Module Architecture
|
|
|
|
## Overview
|
|
|
|
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.
|
|
|
|
## Problem Statement
|
|
|
|
Before ReachGraph, reachability data was scattered across multiple modules:
|
|
|
|
| Module | Data | Limitation |
|
|
|--------|------|------------|
|
|
| Scanner.CallGraph | `CallGraphSnapshot` | No unified query API |
|
|
| Signals | `ReachabilityFactDocument` | Runtime-focused, not auditable |
|
|
| Attestor | PoE JSON | Per-CVE only, no slice queries |
|
|
| Graph | Generic nodes/edges | Not optimized for "why reachable?" |
|
|
|
|
**Result**: Answering "why is lodash reachable?" required querying multiple systems with no guarantee of consistency or auditability.
|
|
|
|
## Solution
|
|
|
|
ReachGraph provides:
|
|
|
|
1. **Unified Schema**: Extends PoE subgraph format with edge explainability
|
|
2. **Content-Addressed Store**: All artifacts identified by BLAKE3 digest
|
|
3. **Slice Query API**: Fast queries by package, CVE, entrypoint, or file
|
|
4. **Deterministic Replay**: Verify that same inputs produce same graph
|
|
5. **DSSE Signing**: Offline-verifiable proofs
|
|
|
|
## Architecture
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ Consumers │
|
|
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
|
|
│ │ Policy │ │ Web │ │ CLI │ │ Export │ │
|
|
│ │ Engine │ │ Console │ │ │ │ Center │ │
|
|
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ │
|
|
└───────┼─────────────┼─────────────┼─────────────┼───────────────┘
|
|
│ │ │ │
|
|
└─────────────┴──────┬──────┴─────────────┘
|
|
│
|
|
┌────────────────────────────▼────────────────────────────────────┐
|
|
│ ReachGraph WebService │
|
|
│ ┌──────────────────────────────────────────────────────────┐ │
|
|
│ │ REST API │ │
|
|
│ │ POST /v1/reachgraphs GET /v1/reachgraphs/{d} │ │
|
|
│ │ GET /v1/reachgraphs/{d}/slice POST /v1/reachgraphs/replay│ │
|
|
│ └──────────────────────────────────────────────────────────┘ │
|
|
│ ┌──────────────────────────────────────────────────────────┐ │
|
|
│ │ Slice Query Engine │ │
|
|
│ │ - Package slice (by PURL) │ │
|
|
│ │ - CVE slice (paths to vulnerable sinks) │ │
|
|
│ │ - Entrypoint slice (reachable from entry) │ │
|
|
│ │ - File slice (changed file impact) │ │
|
|
│ └──────────────────────────────────────────────────────────┘ │
|
|
│ ┌──────────────────────────────────────────────────────────┐ │
|
|
│ │ Replay Driver │ │
|
|
│ │ - Rebuild graph from inputs │ │
|
|
│ │ - Verify digest matches │ │
|
|
│ │ - Log for audit trail │ │
|
|
│ └──────────────────────────────────────────────────────────┘ │
|
|
└─────────────────────────────┬───────────────────────────────────┘
|
|
│
|
|
┌─────────────────────────────▼───────────────────────────────────┐
|
|
│ ReachGraph Core Library │
|
|
│ ┌────────────────┐ ┌────────────────┐ ┌────────────────┐ │
|
|
│ │ Schema │ │ Serialization │ │ Signing │ │
|
|
│ │ │ │ │ │ │ │
|
|
│ │ ReachGraphMin │ │ Canonical JSON │ │ DSSE Wrapper │ │
|
|
│ │ EdgeExplanation│ │ BLAKE3 Digest │ │ Attestor Int. │ │
|
|
│ │ Provenance │ │ Compression │ │ │ │
|
|
│ └────────────────┘ └────────────────┘ └────────────────┘ │
|
|
└─────────────────────────────┬───────────────────────────────────┘
|
|
│
|
|
┌─────────────────────────────▼───────────────────────────────────┐
|
|
│ Persistence Layer │
|
|
│ ┌────────────────────────┐ ┌────────────────────────┐ │
|
|
│ │ PostgreSQL │ │ Valkey │ │
|
|
│ │ │ │ │ │
|
|
│ │ reachgraph.subgraphs │ │ Hot slice cache │ │
|
|
│ │ reachgraph.slice_cache│ │ (30min TTL) │ │
|
|
│ │ reachgraph.replay_log │ │ │ │
|
|
│ └────────────────────────┘ └────────────────────────┘ │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
▲
|
|
│
|
|
┌─────────────────────────────┴───────────────────────────────────┐
|
|
│ Producers │
|
|
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
|
│ │ Scanner │ │ Signals │ │ Attestor │ │
|
|
│ │ CallGraph │ │ RuntimeFacts │ │ PoE │ │
|
|
│ └──────────────┘ └──────────────┘ └──────────────┘ │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
## Data Model
|
|
|
|
### ReachGraphMinimal (v1)
|
|
|
|
The core schema extends the PoE predicate format:
|
|
|
|
```json
|
|
{
|
|
"schemaVersion": "reachgraph.min@v1",
|
|
"artifact": {
|
|
"name": "svc.payments",
|
|
"digest": "sha256:abc123...",
|
|
"env": ["linux/amd64"]
|
|
},
|
|
"scope": {
|
|
"entrypoints": ["/app/bin/svc"],
|
|
"selectors": ["prod"],
|
|
"cves": ["CVE-2024-1234"]
|
|
},
|
|
"nodes": [...],
|
|
"edges": [...],
|
|
"provenance": {...},
|
|
"signatures": [...]
|
|
}
|
|
```
|
|
|
|
### Edge Explainability
|
|
|
|
Every edge carries metadata explaining *why* it exists:
|
|
|
|
| Type | Description | Example Guard |
|
|
|------|-------------|---------------|
|
|
| `Import` | Static import | - |
|
|
| `DynamicLoad` | Runtime load | - |
|
|
| `Reflection` | Reflective call | - |
|
|
| `EnvGuard` | Env variable check | `DEBUG=true` |
|
|
| `FeatureFlag` | Feature flag | `FEATURE_X=enabled` |
|
|
| `PlatformArch` | Platform guard | `os=linux` |
|
|
| `LoaderRule` | PLT/IAT/GOT | `RTLD_LAZY` |
|
|
|
|
### Content Addressing
|
|
|
|
All artifacts are identified by BLAKE3-256 digest:
|
|
- Computed from canonical JSON (sorted keys, no nulls)
|
|
- Signatures excluded from hash computation
|
|
- Enables idempotent upserts and cache keying
|
|
|
|
## API Design
|
|
|
|
### Core Endpoints
|
|
|
|
| Method | Path | Description |
|
|
|--------|------|-------------|
|
|
| POST | `/v1/reachgraphs` | Upsert subgraph (idempotent) |
|
|
| GET | `/v1/reachgraphs/{digest}` | Get full subgraph |
|
|
| GET | `/v1/reachgraphs/{digest}/slice` | Query slice |
|
|
| POST | `/v1/reachgraphs/replay` | Verify determinism |
|
|
|
|
### Slice Query Types
|
|
|
|
1. **Package Slice** (`?q=pkg:npm/lodash@4.17.21`)
|
|
- Returns subgraph containing package and neighbors
|
|
- Configurable depth and direction
|
|
|
|
2. **CVE Slice** (`?cve=CVE-2024-1234`)
|
|
- Returns all paths from entrypoints to vulnerable sinks
|
|
- Includes edge explanations for each hop
|
|
|
|
3. **Entrypoint Slice** (`?entrypoint=/app/bin/svc`)
|
|
- Returns everything reachable from entry
|
|
- Optionally filtered to paths reaching sinks
|
|
|
|
4. **File Slice** (`?file=src/**/*.ts`)
|
|
- Returns impact of changed files
|
|
- Useful for PR-based analysis
|
|
|
|
## Integration Points
|
|
|
|
### Upstream (Data Producers)
|
|
|
|
- **Scanner.CallGraph**: Produces nodes and edges with edge explanations
|
|
- **Signals**: Provides runtime confirmation of reachability
|
|
- **Attestor**: DSSE signing integration
|
|
|
|
### Downstream (Data Consumers)
|
|
|
|
- **Policy Engine**: `ReachabilityRequirementGate` queries slices
|
|
- **Web Console**: "Why Reachable?" panel displays paths
|
|
- **CLI**: `stella reachgraph slice/replay` commands
|
|
- **ExportCenter**: Includes subgraphs in evidence bundles
|
|
|
|
## Determinism Guarantees
|
|
|
|
1. **Canonical Serialization**
|
|
- Sorted object keys (lexicographic)
|
|
- Sorted arrays by deterministic field
|
|
- UTC ISO-8601 timestamps
|
|
- No null fields (omit when null)
|
|
|
|
2. **Replay Verification**
|
|
- POST `/v1/reachgraphs/replay` rebuilds from inputs
|
|
- Returns `{match: true}` if digests match
|
|
- Logs all attempts for audit trail
|
|
|
|
3. **Content Addressing**
|
|
- Same content always produces same digest
|
|
- Enables cache keying and deduplication
|
|
|
|
## Performance Characteristics
|
|
|
|
| Operation | Target Latency | Notes |
|
|
|-----------|---------------|-------|
|
|
| Slice query | P95 < 200ms | Cached in Valkey |
|
|
| Full graph retrieval | P95 < 500ms | Compressed storage |
|
|
| Upsert | P95 < 1s | Idempotent, gzip compression |
|
|
| Replay | P95 < 5s | Depends on input size |
|
|
|
|
## Security Considerations
|
|
|
|
1. **Tenant Isolation**: RLS policies enforce at database level
|
|
2. **Rate Limiting**: 100 req/min reads, 20 req/min writes
|
|
3. **DSSE Signing**: All artifacts verifiable offline
|
|
4. **Input Validation**: Schema validation on all requests
|
|
|
|
## Related Documentation
|
|
|
|
- [Sprint 1227.0012.0001 - Core Library](../../implplan/SPRINT_1227_0012_0001_LB_reachgraph_core.md)
|
|
- [Sprint 1227.0012.0002 - Store APIs](../../implplan/SPRINT_1227_0012_0002_BE_reachgraph_store.md)
|
|
- [Sprint 1227.0012.0003 - Integration](../../implplan/SPRINT_1227_0012_0003_FE_reachgraph_integration.md)
|
|
- [PoE Predicate Spec](../../../src/Attestor/POE_PREDICATE_SPEC.md)
|
|
- [Module AGENTS.md](../../../src/__Libraries/StellaOps.ReachGraph/AGENTS.md)
|
|
|
|
---
|
|
|
|
_Last updated: 2025-12-27_
|