SentinelAPI

Threat-detection middleware for FastAPI. Add it to an existing app and get fixed-window rate limiting, brute-force detection that also catches credential stuffing, and single-use refresh tokens. Every verdict goes to a private, queryable audit trail.

Status: 1.0.0, on PyPI as fastapi-sentinel, with the demo live at sentinelaapi.duckdns.org. See the changelog.

What it catches

Every verdict, blocking or not, is logged with its request's id. It also goes to an audit trail where addresses and usernames appear only as keyed hashes, and CRITICAL ones go to a webhook if you set one. With SENTINEL_ENFORCE=false, SentinelAPI records everything and blocks nothing, so you can watch it on real traffic first (rollout runbook).

Why this exists

Most "add security" advice for a backend service stops at "put a rate limiter in front of it." A rate limiter alone misses two attacks:

• Credential stuffing. An attacker spreads the attempts against one account across many addresses, so no address ever crosses a per-IP threshold. To catch it, you have to count failures per account as well as per address.
• Token replay. A stolen refresh token is used again after the real client has rotated it. A signature check does not catch that. You have to treat single-use tokens as actually single-use.

SentinelAPI catches both, and does standard rate limiting too. Each detector is small and tested on its own; there is no monolithic "security module."

Live demo

sentinelaapi.duckdns.org: each button runs one attack against the real detectors, from simulated addresses:

• a burst over the rate limit;
• credential stuffing from 20 addresses;
• a replayed refresh token.

You see each request with its verdict, and the audit trail as it is written: your own events only, and 10 attacks an hour per visitor. The same console runs locally with docker compose up --build --wait, at http://localhost:8000/.

Use it in your app

pip install "fastapi-sentinel[sqlite]"     # or [postgres], for the audit trail's database; add redis for several processes

The distribution is fastapi-sentinel, since PyPI holds sentinelapi too close to another project's name; the package you import is sentinelapi. Then create the audit table with sentinel migrate (it reads SENTINEL_DATABASE_URL), and:

from fastapi import FastAPI, HTTPException, Request
from pydantic import BaseModel

from sentinelapi.integration import install_sentinel

app = FastAPI()
sentinel = install_sentinel(app)  # rate limit + replay check on every request, and the audit trail


class Login(BaseModel):
    username: str
    password: str


@app.post("/login")
async def login(body: Login, request: Request) -> dict[str, str]:
    await sentinel.login_guard.check(request, body.username)  # 429 while the source or account is blocked
    if not passwords_match(body.username, body.password):  # your own check
        await sentinel.login_guard.failed(request, body.username)
        raise HTTPException(status_code=401, detail="Invalid credentials")
    await sentinel.login_guard.succeeded(request, body.username)
    return {"token": "..."}

Three lines are SentinelAPI's: the import, install_sentinel(app), and the guard around your own password check. Settings come from SENTINEL_* variables (see Configuration). install_sentinel(app, settings, on_event=...) also takes them explicitly, and an on_event coroutine receives every verdict after the log and the audit trail. This snippet runs as a test, against the source and against the built wheel with each extra, so it cannot drift from the code.

In your own app, run sentinel migrate against SENTINEL_DATABASE_URL before the app starts, the way you run your own migrations. SentinelAPI's history keeps its own version table, so it never touches yours. On Postgres, sentinel migrate --app-role <the role your app connects as> grants that role INSERT and SELECT on the audit table and nothing else, so the trail is append-only. sentinel purge deletes events past the retention period.

Guarantees

Each guarantee below is a test that runs on every pull request, on Python 3.11 to 3.15, and on both Redis and the in-memory backend where it applies. The names are the tests' own; a test checks that every name here exists.

Rate limiting

Brute force and credential stuffing

Single-use tokens

Audit trail

Running it

Quickstart

Docker (full stack: API + Redis + Postgres)

docker compose up --build --wait    # or: make up
curl http://localhost:8000/health

Then open http://localhost:8000/ for the attack console.

• A migrate service creates the audit table as its owner and exits. The API starts after it and connects as a role that can only add and read audit rows. Only the API's port is published.
• docker compose run --rm migrate sentinel purge applies the retention period.
• /ready answers 503 until Redis and the migrated database answer.
• Every response carries an X-Request-ID, and every log line of that request carries it too (JSON lines in production).

On a server, deploy/docker-compose.prod.yml adds the production settings, requires the secrets in .env and puts Caddy in front with HTTPS (deploy runbook).

Local dev (in-memory backend + SQLite, zero external services)

With uv, which installs the exact versions of uv.lock:

uv sync --all-extras
uv run sentinel migrate        # creates the audit table (SQLite here)
uv run uvicorn examples.demo_app.main:app --reload

Or with pip: pip install -e ".[demo]", then sentinel migrate and uvicorn examples.demo_app.main:app --reload. make demo does both. Set SENTINEL_DEMO_MODE=true for the attack console at /. The demo's API is in docs/openapi.json, and at /docs while it runs.

Try it:

# Normal login
curl -X POST localhost:8000/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"alice@example.com","password":"correct-horse-battery-staple"}'

# Trigger brute-force detection (run this ~10x with a wrong password)
curl -X POST localhost:8000/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"alice@example.com","password":"wrong"}'

# See what SentinelAPI has caught: operators only, with SENTINEL_OPERATOR_TOKEN
# (start the demo with SENTINEL_OPERATOR_TOKEN=dev-operator-token to try this;
# docker compose sets it for you)
curl -H "Authorization: Bearer dev-operator-token" "localhost:8000/security/events?threat_level=high"

Architecture

The detection logic never imports FastAPI, Redis or SQLAlchemy. It depends on a CounterBackend protocol and returns plain SecurityEvent dataclasses, so it can be tested on its own, with no external service:

sentinelapi/
├── domain/entities.py        # ThreatType, ThreatLevel, SecurityEvent: no dependencies
├── detectors/                # Pure logic: depends only on domain/ and the storage protocol
│   ├── rate_limiter.py       # Fixed windows per client, stricter per path prefix
│   ├── brute_force.py        # Two axes, per source and per account, checked before the password
│   └── jwt_replay.py         # Single-use tokens by `jti`, for refresh and reset tokens
├── storage/
│   ├── backend.py            # The CounterBackend protocol: the seam between logic and infrastructure
│   ├── memory_backend.py     # No dependencies: tests and a single process
│   └── redis_backend.py      # Counters shared by several processes
├── audit/                    # Models, Alembic migrations and the background writer of the audit trail
├── alerts/webhook.py         # CRITICAL events to a chat webhook
├── client_address.py         # The client's address, through the proxies you trust
├── privacy.py                # Keyed hashes for addresses, accounts and fingerprints
├── clock.py                  # The only module that reads the time
├── middleware.py             # Pure ASGI adapter over the detectors
├── integration.py            # install_sentinel: wires all of it into an app
├── cli.py                    # sentinel migrate, sentinel purge
└── config.py                 # Pydantic settings, every one a SENTINEL_* variable

Brute-force detection is not in the middleware. Rate limiting and replay detection apply to every request and need nothing but its headers, so the middleware runs them. Brute-force detection needs to know whether a login succeeded. The middleware could only learn that by parsing response bodies, which is fragile, so it is a guard that your login endpoint calls (ADR-0003).

Replay detection runs only on the paths you name. Ordinary access tokens are sent on every call by design; calling that "replay" would flag every legitimate request. The detector is for tokens meant to be redeemed exactly once: refresh-token rotation, password-reset links, email-verification links.

The structure is enforced, not just described: 19 architecture rules, each checked on every pull request by a test, an import contract or a CI job, and 10 decision records.

Configuration

All settings are SENTINEL_-prefixed environment variables, or lines in a .env file (.env.example lists every one). Lists and maps are JSON, as in SENTINEL_TRUSTED_PROXIES=["10.0.0.0/8"]. A test checks that every setting is in this section.

General

Rate limiting

Brute force (the login guard)

Single-use tokens

Audit trail

Alerts and the demo

Overhead

make bench (benchmarks/overhead.py) calls the ASGI app directly, with no network and no HTTP client, so it measures what SentinelAPI adds and nothing else. It runs the same endpoint three ways: without SentinelAPI, with it on the memory backend, and with it on Redis. Nothing is blocked, so every request pays the full check.

On a Windows 11 laptop (20 logical CPUs, Python 3.12.10), 20,000 requests per configuration, with Redis in Docker Desktop on the same machine:

On Redis, the cost is one round trip per request (INCR and EXPIRE in one pipeline). Docker Desktop's virtual network makes that round trip slower than it would be on a Linux server. The target was p95 ≤ 2 ms with Redis on the same host.

Testing

uv run pytest                    # everything, the demo app end to end included
uv run pytest -m browser         # the attack console in Chromium, with axe-core (after: uv run playwright install chromium)

# The detectors alone: no framework, database or Redis needed
uv run python -m unittest discover -s tests/unit -p "test_rate_limiter.py"
uv run python -m unittest discover -s tests/unit -p "test_brute_force.py"
uv run python -m unittest discover -s tests/unit -p "test_jwt_replay.py"

make test, make lint, make typecheck and make check-imports wrap the same commands. With SENTINEL_TEST_REDIS_URL and SENTINEL_TEST_DATABASE_URL set, the backend contract runs on Redis and the migrations on Postgres too. CI also builds the image, starts the full stack from an empty database (backup and restore included), and installs the wheel with each extra.

Security audit

On 2026-10-22, an audit of the prototype found a way around each detector and gaps in the audit trail. Each finding became a story in the backlog, and each fix landed with a test that reproduces the finding, in #10 to #19:

• Rate limiting: the in-memory backend blocked a client that stayed under its limit; a new User-Agent reset the count; behind a proxy, every client shared the proxy's address; blocking began only past twice the limit.
• Brute force: a block still let the right password in; usernames were counted as typed; the owner's login erased an attack.
• Single-use tokens: a token without exp was forgotten after an hour.
• Audit trail: raw addresses and usernames were readable by anyone; every request wrote a row while it was being answered; the table was created at startup.

Later, checking this README's claims against the code found that, with lock, credential stuffing never reached CRITICAL or the webhook. That was fixed in #29 (SEN-43).

Known limitations

No way around a detector is known. These are the costs of the design, each one chosen in a decision record:

• With lock, anyone who knows a username can keep its owner out for the brute-force window (15 minutes), by failing 8 times. That is the price of stopping credential stuffing without a challenge. signal avoids it if your app can ask for a CAPTCHA or MFA (ADR-0005).
• Fixed windows allow a burst at their boundary: a client can send up to twice its limit in a short span across two windows (ADR-0002).
• Limits count per address, and per /64 for IPv6 (ADR-0004). Clients behind one NAT (an office, a mobile carrier) share a limit: size the global limit for that, and put stricter ones on sensitive prefixes such as /auth/. An attacker with many addresses stays under any per-address limit. On logins, the account axis still catches many attempts against one account, but not password spraying: a few attempts against each of many accounts, from many addresses.
• Brute-force detection sees only the logins your endpoint reports through the guard, and replay detection only the paths in SENTINEL_JWT_REPLAY_PATHS, for tokens signed with SENTINEL_JWT_SECRET.
• The memory backend counts per process. With several workers, use Redis; production refuses the memory backend unless you allow it.

Roadmap

Planned in docs/BACKLOG.md:

1. Done: a locked, linted and type-checked repository, with CI on every pull request.
2. Done: detectors without the evasions above.
3. Done: a three-line integration, and an audit trail that is migrated, private and safe under a flood.
4. Done: a production-ready stack (safe settings, a reproducible image, one command, readiness and request ids), webhook alerts on CRITICAL events and the attack console.
5. Done: the deployed demo, runbooks, a measured overhead, the package on PyPI, the demo's OpenAPI document, this README and the changelog: release 1.0.0.

Next, optional stories: a sliding-window limiter (SEN-39), replay detection for tokens signed with a key pair (SEN-40), the console in Spanish (SEN-41) and Prometheus metrics (SEN-42).

Documentation

• Specification: scope, architecture, the detection contract, the audit table and every setting.
• Changelog.
• Backlog and sprint notes.
• Architecture rules and decision records.
• Runbooks: deploy, back up and restore, rotate secrets, roll out, release.
• The demo's API: docs/openapi.json.

Security

Found a vulnerability? Please report it privately: see SECURITY.md.

License

MIT