Skip to main content

API Sentinel 🛡️

PyPI version Python 3.10+ FastAPI License: MIT OpenAPI 3.x

API Sentinel (api-drift-detector) is an asynchronous API contract monitoring and schema-drift detection system for FastAPI and ASGI applications. It intercepts runtime traffic, compares request and response payloads against your OpenAPI specification in real-time, surfaces contract violations, aggregates recurring drift statistics, and provides CI/CD contract gating.

OpenAPI Specification
        ↓
Expected API Contract
        ↓
   API Sentinel   ←──  Runtime API Traffic (Zero-Latency Async Interception)
        ↓
Schema Drift Engine  (Missing fields, Extra fields, Type mismatches, Shadow APIs)
        ↓
Persistent History & Interactive Dashboard / CI/CD Gating

🚀 Key Features

  1. ⚡ Zero-Latency Async Interception

    • Uses non-blocking background tasks (asyncio.create_task) and response stream buffering. API requests and responses stream immediately to clients without waiting for contract validation.
  2. 🔍 Comprehensive Schema Drift Engine

    • Detects missing required fields, undocumented extra fields, data type mismatches, enum violations, array item violations, and undocumented query/path parameters.
    • Detects Shadow APIs (runtime endpoints invoked in production that are missing from the OpenAPI documentation).
    • Detects Undocumented Status Codes (e.g. server returning uncontracted 400 or 500 error envelopes).
  3. 🔒 Sensitive Data Masking

    • Automatically redacts sensitive fields (passwords, tokens, API keys, secrets, authorization headers, private keys, credit cards) across request/response headers, query parameters, and deeply nested JSON bodies before persistence or display.
  4. 🧬 Dynamic Multi-Payload Schema Inference

    • Inactive or evolving APIs can be inferred dynamically on the fly.
    • Merges multiple observed payloads to infer unified JSON schemas with type unions (string | null), optional fields, and per-path field observation frequency rates.
  5. 📋 OpenAPI Specification Validation

    • Built-in validator verifying syntax, OpenAPI versions (3.0.x, 3.1.x), path templates, route compilation, and schema definitions.
    • Usable via CLI (api-sentinel validate) and programmatic Python imports.
  6. 📈 Recurring Schema Drift History & Aggregation

    • Tracks cumulative occurrence counts, first-seen timestamps, last-seen timestamps, and representative sample payloads for recurring drifts.
    • Dedicated API endpoint /api/drift/stats and recurring drift widget on the dashboard.
  7. 🧭 Unified Endpoint Explorer

    • Merges your OpenAPI specification catalog with live runtime traffic telemetry.
    • Filter between:
      • All Endpoints
      • Documented & Observed
      • Spec Only (Unseen): Endpoints documented in spec with 0 traffic calls.
      • Undocumented Traffic: Shadow APIs receiving traffic without spec documentation.
    • Search, method filtering, and side-by-side spec vs. runtime inferred schema detail view.
  8. 🤖 CI/CD Contract Check CLI

    • Dedicated command api-sentinel check --spec openapi.yaml --traffic <file> to validate API contracts in automated deployment pipelines.
    • Returns exit code 0 on success and non-zero exit code 1 when violations breach policy (--fail-on error, --fail-on warning, --fail-on drift).
    • Includes ready-to-use GitHub Actions workflow (.github/workflows/ci.yml).
  9. 📊 Real-Time Developer Dashboard

    • Modern dark-mode interface with live metrics, pass/fail timeline charts, recent validation logs, and JSON/HTML export capabilities.
  10. 💾 Database Persistence

    • Automatically records all validation results, schema diffs, and recurring drift records to SQLite via SQLAlchemy (aiosqlite), persisting telemetry across server restarts.
  11. 🪄 OpenAPI Specification Wizard

    • Visual browser-based interface to design, edit, preview, test, and save OpenAPI specifications without touching raw YAML.

📦 Installation

pip install api-drift-detector

From GitHub:

pip install git+https://github.com/T41h4X/API_sentinel.git

⚡ Quick Start

1. Start the Sentinel Dashboard (Terminal 1)

api-sentinel dashboard

Open http://127.0.0.1:8001 to monitor incoming traffic and contract drifts.

2. Attach Middleware to Your FastAPI App (Terminal 2)

from fastapi import FastAPI
from api_sentinel import APISentinelMiddleware

app = FastAPI(title="My Service")

# Register Sentinel Middleware
app.add_middleware(
    APISentinelMiddleware,
    openapi_path="openapi.yaml",            # Path to your OpenAPI spec
    dashboard_url="http://127.0.0.1:8001",  # Dashboard address
    enabled=True,
    print_clean=True,
)

@app.get("/api/v1/users/{user_id}")
async def get_user(user_id: int):
    # Any schema mismatch or undocumented fields will trigger live alerts!
    return {"id": user_id, "name": "Alice"}

Run your FastAPI application:

uvicorn app:app --reload --port 8000

Any request sent to http://127.0.0.1:8000/api/v1/users/42 is validated asynchronously and streamed directly into your dashboard.


💻 Command Line Interface (CLI)

The CLI is available as both api-sentinel and api-drift-detector:

# 1. Start the interactive dashboard
api-sentinel dashboard --host 127.0.0.1 --port 8001

# 2. Validate OpenAPI specification syntax and structure
api-sentinel validate --spec openapi.yaml

# 3. Run CI/CD contract check (spec check)
api-sentinel check --spec openapi.yaml

# 4. Run CI/CD contract check against captured traffic payloads
api-sentinel check --spec openapi.yaml --traffic traffic.json --fail-on error

# 5. Output contract check results in JSON format
api-sentinel check --spec openapi.yaml --json

# 6. Check installed version
api-sentinel version

🤖 CI/CD Integration (GitHub Actions)

Add this workflow to your repository (.github/workflows/ci.yml):

name: API Sentinel Contract Check

on: [push, pull_request]

jobs:
  contract-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.11"
      - run: pip install api-drift-detector
      - name: Validate OpenAPI Contract
        run: api-sentinel validate --spec openapi.yaml
      - name: Check Contract Violations
        run: api-sentinel check --spec openapi.yaml --fail-on error

⚙️ Configuration

Configure API Sentinel via environment variables (prefixed with SENTINEL_) or a .env file:

Variable Default Description
SENTINEL_DATABASE_URL sqlite+aiosqlite:///./sentinel.db SQLAlchemy SQLite database connection string
SENTINEL_RETENTION_DAYS 30 Days to retain validation records before automated cleanup
SENTINEL_MASKED_FIELDS ["password", "token", "credit_card", "authorization", "secret", "api_key", "apikey", "access_token", "private_key"] Fields masked as [REDACTED]
SENTINEL_SELECTIVE_PERSISTENCE false When true, only saves WARNING and FAILED validation results
SENTINEL_OPENAPI_SPEC_PATH openapi.yaml Default OpenAPI specification file path

🧪 Testing

Run the full automated test suite:

pytest -v

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

Metadata

Release files for api-drift-detector 0.1.4

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for api-drift-detector 0.1.4
File Size Uploaded Provenance Actions
api_drift_detector-0.1.4.tar.gz 130.4 kB Without provenance Details for api_drift_detector-0.1.4.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for api-drift-detector 0.1.4
File Interpreter ABI Platform Actions
api_drift_detector-0.1.4-py3-none-any.whl Python 3 none any Details for api_drift_detector-0.1.4-py3-none-any.whl

Total release size: 221.6 kB

Release files / api_drift_detector-0.1.4.tar.gz

Download URL api_drift_detector-0.1.4.tar.gz
Size 130.4 kB
Tags Source
SHA-256 checksum
How to use checksums
5d713bc684750e05898b114d7abb626ed64e02f13638305366d77c57af7bcd7c
BLAKE2b-256 checksum
How to use checksums
e8e7bd892b8134e5a03c39b97151927996e7ef30dfb207045f0ec365d10babec
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.9

Release files / api_drift_detector-0.1.4-py3-none-any.whl

Download URL api_drift_detector-0.1.4-py3-none-any.whl
Size 91.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
cac7933013a3b1106dbb6791a22c8865eabac9c7a7772044009de6e6cea97aab
BLAKE2b-256 checksum
How to use checksums
2670ce900d437dcaa9d5196cba0bfe130b578f6ab26ce743f2fb924e6c7b95ba
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.9

Security for api-drift-detector 0.1.4

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page