Skip to content

FastAPI Guard

FastAPI Guard Logo

PyPI version Release License: MIT CI CodeQL

pages-build-deployment Docs Update Downloads

fastapi-guard is a comprehensive security library for FastAPI applications, providing middleware to control IPs, log requests, and detect penetration attempts. It integrates seamlessly with FastAPI to offer robust protection against various security threats, ensuring your application remains secure and reliable.

Quick Start

from fastapi import FastAPI
from guard.middleware import SecurityMiddleware
from guard.models import SecurityConfig

app = FastAPI()

config = SecurityConfig(
    ipinfo_token="your_token_here",
    enable_redis=False,
    rate_limit=100,
    auto_ban_threshold=5
)

app.add_middleware(SecurityMiddleware, config=config)

Example App

Inside examples, you can find a simple example app that demonstrates how to use FastAPI Guard.

You can also download the example app as a Docker container from GitHub Container Registry.

# Pull the latest version
docker pull ghcr.io/rennf93/fastapi-guard-example:latest

# Or pull a specific version (matches library releases)
docker pull ghcr.io/rennf93/fastapi-guard-example:v1.1.0

Running the Example App

The easiest way to run the example app is with Docker Compose, which automatically sets up Redis:

# Clone the repository
git clone https://github.com/rennf93/fastapi-guard.git
cd fastapi-guard/examples

# Start the app with Redis
docker compose up

This will start both the FastAPI Guard example app and Redis service. The app will be available at http://0.0.0.0:8000.

Using Docker Container Only

Alternatively, you can run just the container:

# Run with default settings
docker run -host 0.0.0.0 -p 8000:8000 ghcr.io/rennf93/fastapi-guard-example:latest

# Run with custom Redis connection
docker run -host 0.0.0.0 -p 8000:8000
 -e REDIS_URL=redis://your-redis-host:your-redis-port
 -e REDIS_PREFIX=your-redis-prefix
 -e IPINFO_TOKEN=your-ipinfo-token
 ghcr.io/rennf93/fastapi-guard-example:latest

The example app includes endpoints to test various security features of FastAPI Guard. Access the Swagger documentation at http://0.0.0.0:8000/docs after running the container.

Features

  • IP Whitelisting and Blacklisting: Control access based on IP addresses.
  • User Agent Filtering: Block requests from specific user agents.
  • Rate Limiting: Limit the number of requests from a single IP.
  • Automatic IP Banning: Automatically ban IPs after a certain number of suspicious requests.
  • Penetration Attempt Detection: Detect and log potential penetration attempts.
  • Custom Logging: Log security events to a custom file.
  • CORS Configuration: Configure CORS settings for your FastAPI application.
  • Cloud Provider IP Blocking: Block requests from cloud provider IPs (AWS, GCP, Azure).
  • IP Geolocation: Use IPInfo.io API to determine the country of an IP address.
  • Flexible Storage: Choose between Redis-backed distributed state or in-memory storage
  • Automatic Fallback: Seamless operation with/without Redis connection

Documentation