# Reachability Drift Detection - Architecture

Module: Scanner Version: 1.1 Status: Implemented (core drift engine + API; Node Babel integration pending; tier-2 router wiring complete — Sprint 20260512_032). Last Updated: 2026-05-13

1. Overview

Reachability Drift Detection tracks function-level reachability changes between scans. It highlights when code changes create new paths to sensitive sinks or remove existing paths, producing deterministic evidence for triage and VEX workflows.

Key outcomes:

• Detect regressions when previously unreachable sinks become reachable.
• Validate mitigations when reachable sinks become unreachable.
• Provide deterministic evidence for audit and policy decisions.

2. Key Concepts

2.1 Call Graph

A directed graph of function calls:

• Nodes: functions, methods, lambdas with file and line metadata.
• Edges: call relationships (direct, virtual, dynamic).
• Entrypoints: public handlers (HTTP, CLI, background services).
• Sinks: security-sensitive APIs from the sink registry.

2.2 Reachability Analysis

Multi-source traversal from entrypoints to sinks to determine exploitability.

2.3 Drift Detection

Compares reachability between base and head scans:

• became_reachable: risk increased (new path to sink).
• became_unreachable: risk decreased (path removed or mitigated).

2.4 Cause Attribution

Explains why drift happened by correlating code changes with paths.

3. Data Flow

flowchart TD
    A[Source or binary] --> B[Call graph extractor]
    B --> C[CallGraphSnapshot]
    C --> D[Reachability analyzer]
    D --> E[ReachabilityResult]
    C --> F[Code change extractor]
    E --> G[ReachabilityDriftDetector]
    F --> G
    G --> H[ReachabilityDriftResult]
    H --> I[Storage + API]

4. Component Architecture

4.1 Call Graph Extractors

Registered extractors are configured in CallGraphServiceCollectionExtensions. The drift API tier is set by IDriftLanguageRouter (src/Scanner/__Libraries/StellaOps.Scanner.ReachabilityDrift/Routing/DriftLanguageRouter.cs), which is the canonical source of supported languages and alias normalization. Tier-1 aliases: csharp/c#/cs/.net/net -> dotnet, nodejs/javascript/js/typescript/ts -> node, golang -> go, py -> python, jvm -> java. Tier-2 aliases (SPRINT_20260512_032): bunjs -> bun, rb -> ruby, rs -> rust; deno and php have no aliases. The GET /api/v1/scans/{scanId}/drift endpoint returns HTTP 400 for any language outside the union of tier-1 and tier-2 sets (currently cobol, binary, and any unrecognised value).

4.2 Reachability Analyzer

Located in src/Scanner/__Libraries/StellaOps.Scanner.CallGraph/Analysis/.

4.3 Drift Detector

ReachabilityDriftDetector compares base and head snapshots and produces ReachabilityDriftResult with compressed paths.

4.4 Path Compressor and Cause Explainer

• PathCompressor reduces paths to key nodes and optionally includes full paths.
• DriftCauseExplainer correlates changes to explain why drift happened.

5. Language Support Matrix

Sprint 20260512_032 (TASK-032-04) extended the drift router to ten canonical languages. Tier-1 has full extractor + classifier + drift wiring. Tier-2 has router recognition (alias normalization + HTTP 200 instead of 400) and an existing classifier source documenting recognised framework patterns; the extractor registration in CallGraphServiceCollectionExtensions is still pending a follow-up sprint.

Per-tier-2 framework conventions recognised by the existing classifiers (pinned in DriftLanguageRouterTests.Frameworks_<Lang>_Match_..._Conventions):

The drift API supported set is the canonical contract; adding a new tier (e.g. JavaScript-standalone) requires a sprint task that:

1. Extends DriftLanguageRouter.BuildTier2Descriptors() (or a new BuildTier3Descriptors() helper) with the new descriptor + alias list + framework list — matching the patterns already recognised by the corresponding <Lang>EntrypointClassifier.cs source;
2. Registers the corresponding ICallGraphExtractor in AddCallGraphServices();
3. Adds tier-2a behavioral coverage to ReachabilityDriftEndpointsTests.

6. Storage Schema

Migrations are in src/Scanner/__Libraries/StellaOps.Scanner.Storage/Postgres/Migrations/.

Core tables:

• call_graph_snapshots: scan_id, language, graph_digest, extracted_at, node_count, edge_count, entrypoint_count, sink_count, snapshot_json.
• reachability_results: scan_id, language, graph_digest, result_digest, computed_at, reachable_node_count, reachable_sink_count, result_json.
• code_changes: scan_id, base_scan_id, language, node_id, file, symbol, change_kind, details, detected_at.
• reachability_drift_results: base_scan_id, head_scan_id, language, newly_reachable_count, newly_unreachable_count, detected_at, result_digest.
• drifted_sinks: drift_result_id, sink_node_id, sink_category, direction, cause_kind, cause_description, compressed_path, associated_vulns.
• material_risk_changes: extended with base_scan_id, cause, cause_kind, path_nodes, associated_vulns for drift attachments.

7. Cache and Determinism

If the call graph cache is enabled (CallGraph:Cache), cached keys follow this pattern:

• callgraph:graph:{scanId}:{language}
• callgraph:reachability:{scanId}:{language}

Determinism is enforced by stable ordering and deterministic IDs (see DeterministicIds).

8. API Endpoints

Base path: /api/v1

See docs/api/scanner-drift-api.md for details.

9. Integration Points

• Policy gates: planned in SPRINT_3600_0005_0001_policy_ci_gate_integration.md.
• VEX candidate emission: planned alongside policy gates.
• Attestation: StellaOps.Scanner.ReachabilityDrift.Attestation provides DSSE signing utilities (integration is optional).

10. Performance Characteristics (Targets)

11. References

• docs/implplan/archived/SPRINT_3600_0002_0001_call_graph_infrastructure.md
• docs/implplan/archived/SPRINT_3600_0003_0001_drift_detection_engine.md
• docs/api/scanner-drift-api.md
• docs/operations/reachability-drift-guide.md
• docs/product/advisories/archived/17-Dec-2025 - Reachability Drift Detection.md
• src/Scanner/__Libraries/StellaOps.Scanner.ReachabilityDrift/