IP Filtering

FastCMS supports CIDR-based IP filtering to allow or block access from specific IP addresses or ranges. Rules are stored in the database and evaluated on every request.

Enable IP Filtering

IP_FILTER_ENABLED=true

When disabled (default), all IP filtering middleware is bypassed completely.

How It Works

• Block rules — deny the request with 403 Forbidden
• Allow rules — used for documentation/allowlist purposes (does not bypass block rules)
• Rules support CIDR notation: 192.168.1.0/24, 10.0.0.1, 2001:db8::/32
• Rules can have an optional expiry date — expired rules are ignored automatically
• Block rules take precedence

Exempt paths (never filtered): /health, /api/v1/health

API Endpoints

All endpoints require admin authentication.

List Rules

GET /api/v1/ip-rules
Authorization: Bearer ADMIN_TOKEN

Query Parameters:

Create a Rule

POST /api/v1/ip-rules
Authorization: Bearer ADMIN_TOKEN
Content-Type: application/json

Block a single IP:

{
  "cidr": "203.0.113.5",
  "rule_type": "block",
  "reason": "Repeated abuse",
  "expires_at": null
}

Block a CIDR range with expiry:

{
  "cidr": "198.51.100.0/24",
  "rule_type": "block",
  "reason": "Suspicious range",
  "expires_at": "2026-06-01T00:00:00Z"
}

Allow a trusted range:

{
  "cidr": "10.0.0.0/8",
  "rule_type": "allow",
  "reason": "Internal network"
}

Delete a Rule

DELETE /api/v1/ip-rules/{rule_id}
Authorization: Bearer ADMIN_TOKEN

Blocked Request Response

HTTP/1.1 403 Forbidden

{
  "detail": "Access denied: Repeated abuse"
}

CIDR Notation Reference

X-Forwarded-For Support

When running behind a reverse proxy or load balancer, FastCMS reads the client IP from headers in this order:

1. X-Forwarded-For (first IP in list)
2. X-Real-IP
3. Direct connection IP

Ensure your proxy sets these headers correctly.

Audit Integration

All blocked requests are logged to the audit system:

GET /api/v1/audit?event_type=security&event_action=ip_blocked
Authorization: Bearer ADMIN_TOKEN