Noureddine RAMDI / fastapi-guard: fine-grained security middleware for FastAPI with composable per-route decorators

Created Mon, 04 May 2026 10:23:01 +0000 Modified Sat, 23 May 2026 20:41:27 +0000
885 Words
github-stars python fastapi security middleware rate-limiting ip-filtering

rennf93/fastapi-guard

Security middleware is often an all-or-nothing deal — you either protect your entire API globally or struggle to retrofit nuanced rules per endpoint. fastapi-guard flips that script with a composable per-route decorator system that lets you stack security policies directly on your FastAPI endpoints. This approach gives you fine-grained control with less overhead and more clarity.

What fastapi-guard does and its architecture

fastapi-guard is a production-ready security middleware library tailored for FastAPI applications. It provides IP filtering, rate limiting, signature-based attack detection, and over 20 security decorators that you can apply per route. The decorators cover common security needs like authentication enforcement, geo-blocking, behavioral analysis, and more.

Under the hood, fastapi-guard is built on top of guard-core, a framework-agnostic security engine designed to be adaptable across multiple web frameworks and languages. guard-core has adapters for Python frameworks (FastAPI, Flask, Django, Tornado), TypeScript/JavaScript frameworks (Express, NestJS, Fastify, Hono), and Rust frameworks (Actix, Axum, Rocket, Tower). This abstraction makes fastapi-guard just one implementation of a broader, language-agnostic security model.

The library supports both middleware-level configuration for global protections and fine-grained per-route decorators that stack declarative security rules on individual endpoints. This dual approach allows you to combine broad protections with precise controls where needed.

Additionally, fastapi-guard offers an optional cloud dashboard that provides real-time monitoring, dynamic rule updates, and GDPR compliance tools. This dashboard collects telemetry through an agent-based system that buffers events and metrics, using circuit-breaker patterns for transport reliability.

The core library is fully self-contained and MIT licensed, making it easy to adopt without vendor lock-in.

What makes fastapi-guard’s security model stand out

The main technical strength of fastapi-guard is its composable per-route decorator system. Instead of configuring security policies globally or through configuration files, you directly annotate your FastAPI endpoint functions with decorators that can stack multiple security rules. This results in very readable, maintainable code where security policies are explicit at the route level.

For example, you can combine rate limiting, IP whitelisting, geo-blocking, and behavioral analysis decorators on a single endpoint without complex middleware logic.

The tradeoff is the added complexity in understanding the security stack applied per route, especially in large projects with many endpoints. However, this is balanced by the clarity and explicitness of the decorators, which are easier to audit and adjust.

Under the hood, the codebase leverages guard-core’s modular design, which isolates the security logic from framework specifics. This separation improves code quality and testability. The Python adapter for FastAPI follows idiomatic patterns and integrates cleanly with FastAPI’s dependency injection and routing.

The optional cloud dashboard adds value for teams needing centralized monitoring and compliance tooling but is not mandatory. Some users may prefer to use the middleware purely as a local library without cloud telemetry.

Overall, the code is surprisingly clean for a security middleware library, balancing feature richness without undue complexity.

Quick start with fastapi-guard

The project provides straightforward installation commands:

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

After installation, you can apply decorators to your FastAPI routes to enforce security policies as needed. The README and docs provide detailed examples for configuring rate limiting, IP filtering, and other protections.

Here’s a minimal example of applying a rate limit decorator:

from fastapi import FastAPI
from fastapi_guard.decorators import rate_limit

app = FastAPI()

@app.get("/resource")
@rate_limit(calls=10, period_seconds=60)
async def protected_resource():
    return {"message": "This endpoint is rate limited to 10 calls per minute."}

This declarative style makes it clear what protections apply at the route level without combing through global middleware settings.

Verdict

fastapi-guard is a solid security middleware choice if you need fine-grained, composable security rules per FastAPI route. Its foundation on guard-core offers potential for cross-framework reuse and a clean separation of concerns.

The per-route decorator system is the most distinctive feature, enabling clear, maintainable security policies tied directly to endpoint code. This can improve developer experience and auditability compared to monolithic global middleware.

The optional cloud dashboard is a plus for teams that want centralized monitoring and compliance tools but isn’t required to benefit from the library.

That said, the complexity of stacking many decorators can grow, and some projects may prefer simpler, global middleware rules if their security needs are uniform.

If your FastAPI app demands nuanced security policies at the endpoint level or you want a modular approach that could extend beyond FastAPI, fastapi-guard is worth exploring.

→ GitHub Repo: rennf93/fastapi-guard ⭐ 777 · Python