Skip to content

API Reference Overview

Architecture Update (v5.0.0)

As of v5.0.0, FastAPI Guard is a thin adapter over guard-core. All core security modules now live in the guard_core package. The public API remains unchanged — use from guard import ... for all imports. See Core Architecture for details.

Core Components

Middleware & Configuration

Internal Core Modules (v4.2.0+)

Internal Implementation

These modules are internal implementation details. Always use the public API (SecurityMiddleware, SecurityConfig, SecurityDecorator).

Documentation provided for contributors and advanced users.

  • Core Architecture: Complete internal architecture documentation
  • SecurityCheckPipeline: Chain of Responsibility pattern for security checks
  • SecurityEventBus: Centralized event dispatching
  • MetricsCollector: Request/response metrics collection
  • HandlerInitializer: Handler initialization logic
  • ErrorResponseFactory: Response creation and processing
  • RouteConfigResolver: Route configuration resolution
  • RequestValidator: Request validation utilities
  • BypassHandler: Security bypass handling
  • BehavioralProcessor: Behavioral rule processing

Handler Components

Utilities

  • Utilities: Helper functions for logging and request analysis

Key Classes and Instances

# Core middleware and configuration
from guard.middleware import SecurityMiddleware
from guard import SecurityConfig

# Security decorators
from guard import SecurityDecorator, RouteConfig
from guard_core.decorators.base import get_route_decorator_config

# Handler classes and their pre-initialized instances
from guard import CloudManager, cloud_handler
from guard import IPBanManager, ip_ban_manager
from guard import RateLimitManager, rate_limit_handler
from guard import RedisManager, redis_handler
from guard import sus_patterns_handler  # SusPatternsManager singleton instance
from guard import BehaviorTracker, BehaviorRule

# Special case - requires parameters
from guard import IPInfoManager

Singleton Pattern

Most handler classes use a singleton pattern with __new__ to ensure only one instance:

class ExampleHandler:
    _instance = None

    def __new__(cls, *args, **kwargs) -> "ExampleHandler":
        if cls._instance is None:
            cls._instance = super().__new__(cls)
            # Initialize instance attributes
        return cls._instance

Configuration Model

The SecurityConfig class is the central configuration point:

class SecurityConfig:
    def __init__(
        self,
        geo_ip_handler: GeoIPHandler | None = None,
        whitelist: list[str] | None = None,
        blacklist: list[str] = [],
        blocked_countries: list[str] = [],
        whitelist_countries: list[str] = [],
        blocked_user_agents: list[str] = [],
        auto_ban_threshold: int = 5,
        auto_ban_duration: int = 3600,
        rate_limit: int = 100,
        rate_limit_window: int = 60,
        enable_cors: bool = False,
        # ... other parameters
    ):
        # ... initialization

Optimized Loading

FastAPI Guard uses a smart loading strategy to improve performance:

  • IPInfoManager: Only downloaded and initialized when country filtering is configured
  • CloudManager: Only fetches cloud provider IP ranges when cloud blocking is enabled
  • Handlers Initialization: Middleware conditionally initializes components based on configuration

This approach reduces startup time and memory usage when not all security features are needed.

By default initialization runs lazily on the first request. For production deployments, wire guard_lifespan so initialization runs at ASGI startup instead — see Eager initialization with FastAPI lifespan.

# Conditional loading example from middleware
async def initialize(self) -> None:
    if self.config.enable_redis and self.redis_handler:
        await self.redis_handler.initialize()
        # Only initialize when needed
        if self.config.block_cloud_providers:
            await cloud_handler.initialize_redis(
                self.redis_handler, self.config.block_cloud_providers
            )
        await ip_ban_manager.initialize_redis(self.redis_handler)
        # Only initialize if country filtering is enabled
        if self.geo_ip_handler is not None:
            await self.geo_ip_handler.initialize_redis(self.redis_handler)

Security Decorators

FastAPI Guard provides a comprehensive decorator system for route-level security controls:

SecurityDecorator Class

The main decorator class combines all security capabilities:

from guard import SecurityDecorator

config = SecurityConfig()
guard_deco = SecurityDecorator(config)

# Apply to routes
@app.get("/api/sensitive")
@guard_deco.rate_limit(requests=5, window=300)
@guard_deco.require_ip(whitelist=["10.0.0.0/8"])
@guard_deco.block_countries(["CN", "RU"])
def sensitive_endpoint():
    return {"data": "sensitive"}

Decorator Categories

  • AccessControlMixin: IP filtering, geographic restrictions, cloud provider blocking
  • AuthenticationMixin: HTTPS enforcement, auth requirements, API key validation
  • RateLimitingMixin: Custom rate limits, geographic rate limiting
  • BehavioralMixin: Usage monitoring, return pattern analysis, frequency detection
  • ContentFilteringMixin: Content type filtering, size limits, user agent blocking
  • AdvancedMixin: Time windows, suspicious detection, honeypot detection

Integration with Middleware

Decorators work seamlessly with SecurityMiddleware:

# Set up middleware and decorators
app.add_middleware(SecurityMiddleware, config=config)
app.state.guard_decorator = guard_deco  # Required for integration

Route Configuration Priority

Configuration is applied in the following order of precedence:

  1. Decorator Settings (highest priority)
  2. Global Middleware Settings
  3. Default Settings (lowest priority)

This allows route-specific overrides while maintaining global defaults.