ipban-manager.md

title	description	keywords
IPBanManager API - FastAPI Guard	API reference for FastAPI Guard's IP banning system, including automatic and manual IP management	ip ban api, ban management, ip blocking api, security api

IPBanManager

The IPBanManager class handles temporary IP bans in your FastAPI application.

---

Overview

from guard.handlers.ipban_handler import IPBanManager

ip_ban_manager = IPBanManager()

The IPBanManager uses an in-memory cache to track banned IPs and their ban durations.

---

Distributed Banning

When Redis is enabled:

• Bans are shared across instances
• Ban expiration is handled automatically
• Supports atomic ban operations

# Cluster-wide ban
await ip_ban_manager.ban_ip("192.168.1.1", 3600, distributed=True)

# Check ban status across cluster
is_banned = await ip_ban_manager.is_ip_banned("192.168.1.1", check_redis=True)

---

Methods

ban_ip

Ban an IP address for a specified duration.

async def ban_ip(ip: str, duration: int) -> None

Parameters:

• ip: The IP address to ban
• duration: Ban duration in seconds

Example:

await ip_ban_manager.ban_ip("192.168.1.1", 3600)  # Ban for 1 hour

is_ip_banned

Check if an IP address is currently banned.

async def is_ip_banned(ip: str) -> bool

Parameters:

• ip: The IP address to check

Returns:

• bool: True if the IP is banned, False otherwise

Example:

is_banned = await ip_ban_manager.is_ip_banned("192.168.1.1")

reset

Reset all banned IPs.

async def reset() -> None

Example:

await ip_ban_manager.reset()

---

Usage with SecurityMiddleware

The IPBanManager is automatically integrated when you use the SecurityMiddleware:

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

app = FastAPI()

config = SecurityConfig(
    auto_ban_threshold=5,  # Ban after 5 suspicious requests
    auto_ban_duration=3600  # Ban for 1 hour
)

app.add_middleware(SecurityMiddleware, config=config)