fastapi-guard 8.0.0

Website · Docs · Playground · Dashboard · Discord

Production-ready security middleware for FastAPI.
IP filtering, rate limiting, signature-based attack-pattern detection, and 20+ per-route security decorators.

Quick Start

uv add fastapi-guard        # uv (recommended)
pip install fastapi-guard    # pip
poetry add fastapi-guard     # poetry

Example

from fastapi import FastAPI
from guard import SecurityMiddleware, SecurityConfig

app = FastAPI()

config = SecurityConfig(
    enable_rate_limiting=True,
    rate_limit=100,
    rate_limit_window=60,
    enable_ip_banning=True,
    auto_ban_threshold=5,
    auto_ban_duration=86400,
    custom_log_file="security.log",
    enforce_https=True,
    enable_cors=True,
    cors_allow_origins=["*"],
    cors_allow_methods=["GET", "POST"],
    cors_allow_headers=["*"],
    cors_allow_credentials=True,
    cors_expose_headers=["X-Custom-Header"],
    cors_max_age=600,
    block_cloud_providers={"AWS", "GCP", "Azure"},
)

app.add_middleware(SecurityMiddleware, config=config)

For production, wire guard.lifespan.guard_lifespan into FastAPI(lifespan=...) so initialization runs at app startup instead of on the first request, see Eager initialization.

A connection with no client address (a Unix domain socket, some serverless ASGI adapters) is rejected with 403 by default (fail_secure=True); set fail_secure=False to run the pipeline with identity "unknown" instead, allowed unless a whitelist or a country allow-list is configured (blacklist, country, and cloud checks cannot match without an address; detection and the shared rate-limit bucket still apply). Add the literal string "unix" to trusted_proxies to resolve the real client from X-Forwarded-For on such a connection, see Proxy Security.

SecurityMiddleware protects HTTP requests only; it never runs for WebSocket connections. Secure a @app.websocket route explicitly with Depends(guard_websocket), see WebSockets.

Per-Route Security Decorators

Apply security rules at the endpoint level with composable decorators:

from guard import SecurityConfig, SecurityDecorator

config = SecurityConfig(
    auth_verifier=lambda request, credential: {"user": "demo"} if credential else None,
)
guard = SecurityDecorator(config)


@app.get("/api/payments")
@guard.require_auth(type="bearer")
@guard.rate_limit(requests=10, window=60)
@guard.block_countries(["CN", "RU"])
@guard.require_https()
async def process_payment():
    return {"status": "ok"}

require_auth and api_key_auth require a verifier (per-route verifier= or global SecurityConfig.auth_verifier); without one the request is rejected with 401. For a presence-only Authorization header gate, use require_authorization_header(scheme="bearer") instead. See the authentication tutorial for the full migration.

Available decorator categories:

• Access --- require_ip, block_countries, allow_countries, block_clouds, bypass
• Auth --- require_https, require_auth, api_key_auth, require_headers
• Rate Limiting --- rate_limit, geo_rate_limit
• Content --- block_user_agents, content_type_filter, max_request_size, require_referrer, custom_validation, detection_exclusion
• Behavioral --- usage_monitor, return_monitor, suspicious_frequency, behavior_analysis
• Advanced --- time_window, honeypot_detection, suspicious_detection

Full decorator reference

Cloud Dashboard

FastAPI Guard has a centralized cloud platform for real-time monitoring and threat analysis across all your applications.

• Dashboard --- real-time security events, threat intelligence, attack pattern analytics
• Playground --- try every security feature in-browser with real attack data from a live server
• Dynamic Rules --- update security configuration from the dashboard without redeploying
• GDPR Tools --- consent management, data export, account deletion

Connect your existing setup in 2 minutes:

uv add guard-agent    # or: pip install guard-agent

from fastapi import FastAPI
from guard import SecurityConfig, SecurityMiddleware

security_config = SecurityConfig(
    enable_agent=True,
    agent_api_key="your-api-key",
    agent_endpoint="https://api.guard-core.com",
    agent_project_id="your-project-id",
    agent_buffer_size=100,
    agent_flush_interval=2,
    agent_enable_events=True,
    agent_enable_metrics=True,
    enable_dynamic_rules=True,
    dynamic_rule_interval=60,
)

app = FastAPI()
app.add_middleware(SecurityMiddleware, config=security_config)

That is the entire integration. The middleware drives the agent's lifecycle for you --- do not import guard_agent, construct an AgentConfig, or wire a lifespan hook when using fastapi-guard; doing so spins up a second agent that never sees traffic.

Free tier includes 10,000 events/month --- no credit card required.

The core library is fully self-contained and MIT licensed. The cloud dashboard is optional.

Monitoring agent buffer health

When enable_agent=True, the middleware exposes an agent_stats property that returns the current buffer drop counters and transport circuit-breaker state without needing to reach into the agent directly:

middleware: SecurityMiddleware = ...

stats = middleware.agent_stats
# {"enabled": True, "buffer_stats": {"events_dropped": 0, "metrics_dropped": 0, ...},
#  "transport_stats": {"circuit_breaker_state": "CLOSED", ...}, ...}

When the agent is disabled or failed to initialize, the property returns {"enabled": False}. Read it on each scrape; it reflects live counters and is not cached.

Ecosystem

FastAPI Guard is built on guard-core, a framework-agnostic security engine. The same protection is available across Python, TypeScript, and Rust.

Python

Package	Role	PyPI
guard-core	Framework-agnostic security engine
guard-agent	Telemetry agent
fastapi-guard	FastAPI / Starlette adapter (this package)
flaskapi-guard	Flask adapter
djapi-guard	Django adapter
tornadoapi-guard	Tornado adapter

TypeScript / JavaScript

Published under the @guardcore npm scope. Source in the guard-core-ts monorepo. Production-ready.

Package	Role	npm
@guardcore/core	Core engine
@guardcore/express	Express adapter
@guardcore/nestjs	NestJS adapter
@guardcore/fastify	Fastify adapter
@guardcore/hono	Hono adapter

Rust

Published on crates.io. 🚧 Placeholder crates: implementation in progress.

Package	Role	crates.io
guard-core	Core engine
actix-guard-rs	Actix adapter
axum-guard-rs	Axum adapter
rocket-guard-rs	Rocket adapter
tower-guard-rs	Tower adapter

AI Coding Agents

Package	Role	PyPI
guard-core-mcp	MCP server: config validation, docs search, detection sandbox

An MCP server that answers questions about FastAPI Guard from the version installed in your project, rather than from a model's memory of it. It validates a config against the real SecurityConfig model (catching silently-ignored typos like redis_failopen), looks up any field's type, default and description, searches the bundled docs, and runs a payload through the real detection engine to show whether it would be blocked and by which pattern.

uv add --dev guard-core-mcp
claude mcp add guard-core -- uv run guard-core-mcp

Install it into the same environment as FastAPI Guard; it introspects what is actually installed there, so an isolated run (uvx) has nothing to read.

Documentation

• Installation
• First Steps
• Configuration Reference
• Decorator Reference
• API Reference
• Example App
• Redis Integration

Contributing

Contributions are welcome. See CONTRIBUTING.md for guidelines.

New security features (checks, detection patterns, handlers) should be contributed to guard-core. This repo covers the FastAPI/Starlette adapter layer.

License

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

Author

Renzo Franceschini