# Reachability Drift Detection - Architecture

Module: Scanner Version: 1.1 Status: Implemented (core drift engine + API + Worker producer, SPRINT_20261017_006 PCD-874; Node Babel integration pending; tier-2 router wiring complete — Sprint 20260512_032). Last Updated: 2026-10-19

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/__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.Persistence/Migrations/ (the drift tables are part of the consolidated baseline 001_scanner_consolidated_baseline.sql).

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.

Writer (SPRINT_20261017_006 PCD-874, owner ruling 2026-10-18 “build the producer”): the Scanner Worker stage reachability-drift (ReachabilityDriftStageExecutor), which runs after publish-signals-unknowns:

1. It stores the call graph prepare-reachability-inputs extracted in call_graph_snapshots, under the drift router’s canonical language (an extracted javascript graph is stored as node, its digest recomputed because the digest covers the language). A language outside the router’s set is not stored. The extractor yields one language per scan (the first candidate with a non-empty graph), so a scan stores one snapshot.
2. The tenant is the scan’s owner in scan_runtime_state, never lease metadata. A scan without a recorded owner stores nothing.
3. When the scan submission declared a base scan in the metadata key reachability.drift.base_scan_id, it loads the base scan’s stored graph of the same tenant and language, runs CodeChangeFactExtractor.Extract and ReachabilityDriftDetector.Detect, and stores the code changes and then the drift result (drifted_sinks.code_change_id references code_changes). code_changes keeps one row per scan pair, language, symbol and change kind, so the stage passes the first fact of each such identity to the detector and the store. A base scan of another tenant, or one without a stored graph in that language, yields no drift and a warning log. A storage failure fails the stage.

The scan submit route (scanner.scans.submit) accepts the declared base only when the scan coordinator resolves it for the submitting tenant; an unknown or foreign scan is refused with 400 before a scan exists, and the worker receives the canonical key with the base scan’s own identifier. The read-scoped drift GET (§8) computes a drift for a supplied baseScanId without writing anything (PCD-847); without baseScanId it returns the result the stage stored, and the drifted-sinks route pages that result.

Retention: call_graph_snapshots is source-of-truth and kept until its scan is explicitly disposed (migration 009); no age sweep exists, because a later scan may name any earlier scan as its base. The three derived tables are rebuilt by the same stage from the retained snapshots (migration 010).

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. The Console screen /security/reachability/drift (scan id and language as query parameters) reads the stored result with the drift GET and pages its sinks with the drifted-sinks route; it requires scanner:read.

9. Integration Points

• Policy gates: planned in SPRINT_3600_0005_0001_policy_ci_gate_integration.md.
• VEX candidate emission: withdrawn (SPRINT_20260930_002 PCD-222). The Smart-Diff emitter was never wired into a host, and its store and routes are frozen.
• Attestation: StellaOps.Scanner.ReachabilityDrift.Attestation provides DSSE signing utilities (integration is optional).

10. Performance Characteristics (Targets)

11. References

• docs-archive/implplan/SPRINT_3600_0002_0001_call_graph_infrastructure.md
• docs-archive/implplan/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/