FastAPI Guard¶
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.
Live Playground¶
Try FastAPI Guard features directly in your browser:
https://playground.fastapi-guard.com
This interactive demo allows you to explore FastAPI Guard's capabilities without any setup.
Docker Container¶
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.2.2
Running the Example App¶
Using Docker Compose (Recommended)¶
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