primedefender-fastapi

PrimeDefender adds a security layer to FastAPI applications: it inspects incoming requests for common attack patterns, optionally blocks them, and sends structured incidents to your PrimeDefender bridge (for example for a live monitoring map).

This package publishes to PyPI as primedefender-fastapi. The import name is primedefender_fastapi.

Features

Blocked requests return JSON with HTTP 403 or 429 as appropriate. Incidents are POSTed to the bridge (default path /ingest if your PRIMEDEFENDER_BRIDGE_URL has no path).

Requirements

• Python 3.10+
• A running PrimeDefender bridge that accepts the incident JSON (see your dashboard docs).

Install

pip install primedefender-fastapi

For a local editable install while developing the package:

pip install -e ./primedefender-fastapi

Environment variables

Set these in your process environment or load them with python-dotenv before the app imports settings (see below).

*If bridge URL, API key, or site id is missing, reporting is disabled (middleware still runs detections).

See .env.example in this repository for tuning knobs (PRIMEDEFENDER_BODY_CAP_BYTES, rate limits, GeoIP TTL, etc.).

FastAPI usage

Minimal (configuration only from environment):

from fastapi import FastAPI
from primedefender_fastapi import PrimeDefenderMiddleware

app = FastAPI()
app.add_middleware(PrimeDefenderMiddleware)

Load .env early so variables exist when settings are first read:

from pathlib import Path
from dotenv import load_dotenv

load_dotenv(Path(__file__).resolve().parent / ".env")

Optional constructor overrides (other fields still come from the environment):

app.add_middleware(
    PrimeDefenderMiddleware,
    site_label="Indonesia, Bali",
    auth_bypass_mode="observe",
    suspicious_request_mode="block",
)

Explicit settings object (e.g. tests or multi-tenant):

from primedefender_fastapi import PrimeDefenderMiddleware, PrimeDefenderSettings

settings = PrimeDefenderSettings.from_env()
app.add_middleware(PrimeDefenderMiddleware, settings=settings)

Connect to the PrimeDefender bridge

1. Run your bridge (often on port 3000 or behind HTTPS).
2. Set PRIMEDEFENDER_BRIDGE_URL to that origin, e.g. http://localhost:3000.
3. Ensure the bridge exposes POST /ingest (or set the full URL including path).
4. Use a valid PRIMEDEFENDER_API_KEY accepted by the bridge.

Health check (typical): GET http://localhost:3000/health.

Test SQLi / XSS locally

With the API on port 8000:

SQL injection (query)

curl "http://127.0.0.1:8000/auth/login?next=' OR 1=1 --"

XSS

curl "http://127.0.0.1:8000/?q=%3Cscript%3Ealert(1)%3C/script%3E"

Map labels (optional test headers)

curl "http://127.0.0.1:8000/auth/login?next=' OR 1=1 --" \
  -H "X-Prime-Source-Lat: 34.6937" \
  -H "X-Prime-Source-Lon: 135.5023" \
  -H "X-Prime-Source-Label: Japan, Osaka"

Building and publishing

Uses hatchling (PEP 517):

pip install build
python -m build

Upload dist/* to PyPI with twine (use API tokens and trusted publishing in CI in production).

License

MIT — see LICENSE.

Repository

Placeholder links are set in pyproject.toml (Homepage / Repository). Replace with your real GitHub URL before publishing.