# Reachability Drift Detection - Operations Guide

Module: Scanner Version: 1.0 Last Updated: 2025-12-22

Audience: operators running the Stella Ops Scanner WebService who need to configure, run, and troubleshoot reachability drift analysis.

1. Overview

Reachability Drift Detection compares call-graph reachability between two scans and surfaces newly reachable or newly unreachable sinks. The API lives in the Scanner WebService and relies on call-graph snapshots stored in PostgreSQL.

2. Prerequisites

2.1 Infrastructure Requirements

2.2 Required Services

• Scanner WebService running with storage configured.
• Call graph ingestion pipeline populating call_graph_snapshots (Scanner Worker or external ingestion).
• PostgreSQL migrations for call graph and drift tables applied (auto-migrate is enabled by default).

Optional:

• Valkey call graph cache (CallGraph:Cache).

Drift attestation is not wired into the WebService (roadmap). A drift attestation subsystem exists in the StellaOps.Scanner.ReachabilityDrift library (Attestation/DriftAttestationService.cs, IDriftSignerClient, DriftAttestationOptions with section DriftAttestation, plus the AddDriftAttestation registration extension), but as of this revision it is not registered or invoked anywhere in src/ — the Scanner WebService does not call AddDriftAttestation, and the two drift endpoints do not inject IDriftAttestationService. The two GET drift endpoints described here do not produce signed attestations, so a Signer service is not a prerequisite for running drift analysis today. Treat the attestation classes as dormant wiring until a host registers and calls them.

3. Configuration

3.1 Scanner WebService

File: etc/scanner.yaml (path depends on deployment)

scanner:
  storage:
    dsn: "Host=postgres;Database=stellaops;Username=scanner;Password=${SCANNER_DB_PASSWORD}"
    database: "scanner"          # optional; defaults to schema "scanner" when omitted
    commandTimeoutSeconds: 30

  api:
    basePath: "/api/v1"
    scansSegment: "scans"

Auto-migration is not configurable here. The Scanner WebService hard-codes AutoMigrate = true for its scanner-storage registration (Program.cs, AddScannerStorage(... AutoMigrate = true)). There is no scanner.storage.autoMigrate config key — StorageOptions exposes only driver, dsn, database, commandTimeoutSeconds, healthCheckTimeoutSeconds, and migrations (ScannerWebServiceOptions.cs, StorageOptions). Scanner storage migrations always run on startup.

3.2 Call Graph Cache (Optional)

CallGraph:
  Cache:
    enabled: true
    connection_string: "valkey:6379"
    key_prefix: "callgraph:"
    ttl_seconds: 3600
    gzip: true
    circuit_breaker:
      failure_threshold: 5
      timeout_seconds: 30
      half_open_timeout: 10

3.3 Authorization (Optional)

scanner:
  authority:
    enabled: true
    issuer: "https://authority.local"
    requiredScopes:
      - "scanner.scans.read"
      - "scanner.scans.write"

Both drift endpoints require the ScansRead policy (src/Scanner/StellaOps.Scanner.WebService/Endpoints/ReachabilityDriftEndpoints.cs). The policy is registered as an any-of assertion (Program.cs, AddStellaOpsAnyScopePolicy(ScannerPolicies.ScansRead, ...)), so a token satisfies it with either the service-local scope scanner.scans.read or the canonical catalog scope scanner:read (StellaOpsScopes.ScannerRead). When scanner.authority.enabled is false, the policies fall through to allow-all (policy.RequireAssertion(_ => true)) and allowAnonymousFallback defaults to true.

4. Running Drift Analysis

1. Ensure call graph snapshots exist for base and head scans.
2. Compute drift by providing the base scan ID:
   • GET /api/v1/scans/{scanId}/drift?baseScanId={baseScanId}&language=dotnet&includeFullPath=false
3. Page through sinks:
   • GET /api/v1/drift/{driftId}/sinks?direction=became_reachable&offset=0&limit=100

If baseScanId is omitted, the API returns the most recent stored drift result for the head scan.

4.1 Query Parameters

GET /scans/{scanId}/drift:

GET /drift/{driftId}/sinks:

Supported languages. The drift pipeline routes through IDriftLanguageRouter, which seeds ten canonical languages:

• Tier 1: dotnet (aliases csharp/c#/cs/.net/net), java (alias jvm), go (alias golang), python (alias py), and node (aliases nodejs/javascript/js/typescript/ts).
• Tier 2: bun (alias bunjs), deno (no aliases), php (no aliases), ruby (alias rb), and rust (alias rs).

When language is omitted it defaults to dotnet (LegacyDefaultLanguage). Matching is case-insensitive and any of the canonical names or aliases above is accepted. Any value the router cannot normalise to one of those ten languages returns a 400 whose body lists every canonical language (tier 1 and tier 2), built from languageRouter.SupportedLanguages.Select(d => d.Canonical) (src/Scanner/__Libraries/StellaOps.Scanner.ReachabilityDrift/Routing/DriftLanguageRouter.cs).

5. Deployment Modes

5.1 Standalone

• Run Scanner WebService with PostgreSQL reachable.
• Provide scanner.storage.dsn and scanner.api.basePath.

5.2 Unsupported Kubernetes Mode

Kubernetes deployment mode is retired. Configure readiness/liveness checks, scanner.yaml, secrets, PostgreSQL connectivity, and startup migrations through the supported Compose profile or host service manager.

5.3 Air-Gapped

• Use Offline Kit flows for advisory data and signatures.
• Avoid external endpoints; configure any optional integrations to local services.

6. Monitoring and Metrics

There are no drift-specific metrics emitted by the drift endpoints or the ReachabilityDriftDetector yet (verified: neither ReachabilityDriftEndpoints.cs nor ReachabilityDriftDetector.cs create a Meter/Counter). Recommended operational checks:

• API logs for /api/v1/scans/{scanId}/drift and /api/v1/drift/{driftId}/sinks.
• PostgreSQL table sizes and growth for call_graph_snapshots (migration 009), and code_changes, reachability_drift_results, drifted_sinks plus the material_risk_changes drift columns (migration 010).
• Valkey connectivity and cache hit rates if CallGraph:Cache is enabled.

7. Troubleshooting

Note: The drift endpoints do not return 409 Conflict. The “computation already in progress” 409 belongs to the separate reachability compute endpoint POST /api/v1/scans/{scanId}/compute-reachability (ReachabilityEndpoints.cs, which maps it under the scans route group and declares Status409Conflict), and that endpoint requires the ScansWrite policy — not ScansRead. It is not part of this drift API.

8. References

• Scanner module: reachability drift
• Scanner drift API reference
• Air-gap: reachability drift workflows
• src/Scanner/__Libraries/StellaOps.Scanner.Storage/Postgres/Migrations/009_call_graph_tables.sql (creates call_graph_snapshots)
• src/Scanner/__Libraries/StellaOps.Scanner.Storage/Postgres/Migrations/010_reachability_drift_tables.sql (creates code_changes, reachability_drift_results, drifted_sinks; extends material_risk_changes)
• src/Scanner/StellaOps.Scanner.WebService/Endpoints/ReachabilityDriftEndpoints.cs (the two drift endpoints)
• src/Scanner/__Libraries/StellaOps.Scanner.CallGraph/Caching/CallGraphCacheConfig.cs (CallGraph:Cache option keys)