DriftScope

Runtime API drift + source blast-radius detector.

DriftScope complements OpenAPI diff tools by using observed JSON responses as the evidence source and mapping risky changes into consuming Python/JavaScript/TypeScript code.

Quick start

Python 3.10+. Runtime dependencies: none.

python -m pip install driftscope-runtime

python -m driftscope compare \
  --endpoint "GET /rate_limit" \
  --baseline examples/baseline.json \
  --current examples/current.json \
  --source-dir examples/app \
  --out out/report.json \
  --junit out/report.junit.xml \
  --sarif out/report.sarif.json \
  --fixture-out out/regression-fixture.json

High-severity drift returns exit code 2 for CI.

Probe a public JSON endpoint

python -m driftscope probe https://api.example.com/resource --out snapshots/current.json

Only HTTP(S) is allowed and responses are capped at 5 MB by default.

Benchmark

python -m driftscope benchmark benchmark/corpus.json --out benchmark/results.json

The corpus contains 50 minimal runtime fixtures mapped to officially documented GitHub REST API 2026 breaking changes/affected endpoints. It measures runtime detectability and source-impact mapping and includes a stale-spec counterfactual replay where the old spec is intentionally held unchanged while runtime payloads change. That replay demonstrates the no-spec/stale-spec coverage gap; it is not a claim about historical wall-clock detection timing. It does not claim the fixtures are archived production traffic.

What is implemented

• runtime JSON structural fingerprints;
• removed/type/nullability/presence drift;
• bounded observed scalar-domain and numeric-range drift;
• Python AST source usage mapping;
• JS/TS property/destructuring usage mapping;
• impacted-file and risk scoring;
• deterministic SHA-256 report certificates;
• generated regression-fixture manifests;
• JSON/JUnit/SARIF output;
• safe bounded HTTP JSON probe;
• GitHub Actions CI;
• 50-case provenance-backed benchmark.

Security

DriftScope performs no shell execution. The probe restricts schemes and response size. Source scanning is read-only and ignores common dependency/build directories.

Limits

• Runtime sampling cannot prove behavior for unseen payload variants.
• Source mapping is conservative static evidence, not a full call graph.
• The included spec-only benchmark metadata is not an oasdiff run.
• Wall-clock 'earlier than spec update' claims require archived runtime traffic and timestamped historical spec snapshots; this build does not invent those timestamps.