AIWAF is a comprehensive security middleware suite for FastAPI applications that provides intelligent protection against bots, malicious requests, and various web attacks.

• Header Analysis: Validates HTTP headers to identify suspicious patterns
• User-Agent Detection: Recognizes bot patterns while allowing legitimate crawlers
• Header Quality Scoring: Assigns quality scores based on header completeness
• Suspicious Combinations: Detects unusual header combinations

• IP Blacklisting: Automatic and manual IP blocking with temporary/permanent options
• IP Whitelisting: Exemption system for trusted IPs and networks
• Rate Limiting: Configurable rate limiting with automatic blocking
• Request Monitoring: Comprehensive logging and statistics

• Multiple Storage Backends: Memory and file-based storage
• Environment Variable Support: Easy deployment configuration
• JSON Configuration Files: Centralized configuration management
• Runtime Configuration: Update settings without restart

• Real-time Statistics: Detailed blocking and security metrics
• Activity Monitoring: Track recent security events
• Health Checks: Built-in system health monitoring
• Export Capabilities: Data export for analysis

pip install fastapi uvicorn

from fastapi import FastAPI
from aiwaf import AIWAF

# Create FastAPI app
app = FastAPI()

# Initialize AIWAF with default settings
aiwaf = AIWAF(app)

@app.get("/")
async def root():
    return {"message": "Protected by AIWAF!"}

@app.get("/api/data")
async def get_data():
    return {"data": "This endpoint is protected"}

uvicorn main:app --host 0.0.0.0 --port 8000

from aiwaf import AIWAF, AIWAFConfig

# Custom configuration
config = {
    "header_validation": {
        "enabled": True,
        "block_suspicious": True,
        "quality_threshold": 3,
        "exempt_paths": ["/health", "/docs"]
    },
    "rate_limiting": {
        "enabled": True,
        "max_requests": 100,
        "window_seconds": 300
    }
}

aiwaf = AIWAF(app, **config)

Create aiwaf_config.json:

{
  "header_validation": {
    "enabled": true,
    "block_suspicious": true,
    "quality_threshold": 3,
    "exempt_paths": ["/health", "/metrics", "/docs"],
    "custom_suspicious_patterns": ["badbot", "scanner"],
    "custom_legitimate_patterns": ["googlebot", "bingbot"]
  },
  "rate_limiting": {
    "enabled": true,
    "max_requests": 50,
    "window_seconds": 300
  },
  "storage": {
    "backend": "file",
    "file_path": "aiwaf_data.json"
  },
  "security": {
    "log_blocked_requests": true,
    "log_suspicious_requests": true
  }
}

Load from file:

aiwaf = AIWAF(app, config_file="aiwaf_config.json")

export AIWAF_HEADER_VALIDATION_ENABLED=true
export AIWAF_HEADER_BLOCK_SUSPICIOUS=true
export AIWAF_HEADER_QUALITY_THRESHOLD=3
export AIWAF_RATE_LIMITING_ENABLED=true
export AIWAF_RATE_MAX_REQUESTS=100
export AIWAF_STORAGE_BACKEND=file

# Block an IP
aiwaf.block_ip("192.168.1.100", "Suspicious activity", duration=3600)

# Permanently block an IP
aiwaf.block_ip("10.0.0.50", "Malicious requests")

# Whitelist an IP
aiwaf.add_exemption("203.0.113.10", "Trusted partner")

# Check if IP is blocked
if aiwaf.is_blocked("192.168.1.100"):
    print("IP is blocked")

# Unblock an IP
aiwaf.unblock_ip("192.168.1.100")

# Get comprehensive statistics
stats = aiwaf.get_statistics()
print(f"Total blocked IPs: {stats['blacklist']['total_blocked']}")

# Get recent activity
activity = aiwaf.get_recent_activity(hours=24)
print(f"Blocks in last 24h: {activity['summary']['blocks_in_period']}")

# Health check
health = aiwaf.health_check()
print(f"System status: {health['status']}")

# Update configuration at runtime
aiwaf.update_config({
    "header_validation": {
        "quality_threshold": 2
    },
    "rate_limiting": {
        "max_requests": 200
    }
})

# Enable/disable features
aiwaf.enable_feature("rate_limiting")
aiwaf.disable_feature("header_validation")

Add these endpoints to your FastAPI app for web-based management:

@app.get("/admin/aiwaf/stats")
async def get_aiwaf_stats():
    return aiwaf.get_statistics()

@app.post("/admin/aiwaf/block")
async def block_ip(ip: str, reason: str):
    success = aiwaf.block_ip(ip, reason)
    return {"success": success}

@app.post("/admin/aiwaf/exempt")  
async def exempt_ip(ip: str):
    aiwaf.add_exemption(ip)
    return {"success": True}

Test the bot detection with curl:

# This should be blocked (curl user agent)
curl http://localhost:8000/api/data

# This should be allowed (browser-like headers)
curl -H "User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36" \
     -H "Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8" \
     -H "Accept-Language: en-US,en;q=0.5" \
     -H "Accept-Encoding: gzip, deflate" \
     -H "Connection: keep-alive" \
     http://localhost:8000/api/data

AIWAF consists of several key components:

1. HeaderValidationMiddleware: Analyzes HTTP headers for bot detection
2. BlacklistManager: Manages IP blocking and whitelisting
3. Storage System: Pluggable storage backends (memory/file)
4. Configuration System: Flexible configuration management
5. Rate Limiter: Request rate limiting and throttling

Request → AIWAF Middleware → Header Analysis → Rate Limiting → Blacklist Check → FastAPI App

• Memory Storage: Fast, in-memory storage (default)
• File Storage: Persistent JSON file storage
• Extensible: Easy to add Redis, database backends

Check the examples/ directory for complete working examples:

• simple_example.py: Basic AIWAF usage
• example_app.py: Full-featured example with admin endpoints
• config_example.py: Configuration file example

git clone https://github.com/aiwaf/aiwaf-fastapi.git
cd aiwaf-fastapi
pip install -e ".[dev]"

pytest

black aiwaf/
flake8 aiwaf/

Contributions are welcome! Please read our contributing guidelines and submit pull requests to our GitHub repository.

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

• GitHub Issues: Report bugs and request features
• Documentation: Full documentation
• Discussions: Community discussions

• Initial release
• Header validation middleware
• IP blacklisting and whitelisting
• Rate limiting
• Multiple storage backends
• Configuration management
• Statistics and monitoring
• FastAPI integration