IP Allowlist / Blocklist

FastCMS includes a built-in IP filtering layer. Add block rules to ban malicious IPs, or use allow rules to restrict access to known trusted ranges. Rules support both single IPs and CIDR notation.

Enabling IP Filtering

IP filtering is disabled by default. Enable it in your .env:

IP_FILTER_ENABLED=true

Restart the server for the change to take effect. When disabled, all IPs are allowed regardless of any rules stored in the database.

How Rules Work

• Block rules reject matching IPs with 403 Forbidden before any route handler runs.
• Allow rules explicitly permit an IP (useful when combined with block-all defaults).
• Precedence: Block rules always win over allow rules for the same IP.
• CIDR ranges: 10.0.0.0/8 covers all 10.x.x.x addresses.
• Expiry: Rules with an expires_at date are automatically ignored after they expire.

API Reference

All IP rules endpoints require admin authentication.

List IP Rules

GET /api/v1/admin/ip-rules
Authorization: Bearer <admin_token>

Query parameters:

• rule_type — filter by block or allow
• page — page number (default: 1)
• per_page — results per page (default: 50)

Response:

{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "cidr": "203.0.113.0/24",
      "rule_type": "block",
      "reason": "Known scanner",
      "expires_at": null,
      "created": "2026-03-01T10:00:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 50,
  "total_pages": 1
}

Create an IP Rule

POST /api/v1/admin/ip-rules
Authorization: Bearer <admin_token>
Content-Type: application/json

{
  "cidr": "203.0.113.42",
  "rule_type": "block",
  "reason": "Repeated failed login attempts",
  "expires_at": "2026-04-01T00:00:00Z"
}

Fields:

Returns 201 Created with the created rule, or 422 Unprocessable Entity for invalid CIDR.

Delete an IP Rule

DELETE /api/v1/admin/ip-rules/{rule_id}
Authorization: Bearer <admin_token>

Returns 204 No Content.

Admin UI

Visit /admin/ip-rules to manage rules visually.

Features:

• Filter tabs: All / Blocked / Allowed
• Status badge showing whether IP filtering is currently active
• Modal form for adding new rules with optional expiry date picker
• One-click delete per rule

Common Patterns

Block a single IP

{"cidr": "198.51.100.1", "rule_type": "block", "reason": "Brute force attempt"}

Block an entire subnet

{"cidr": "198.51.100.0/24", "rule_type": "block", "reason": "Datacenter range"}

Temporary block (7 days)

{
  "cidr": "203.0.113.42",
  "rule_type": "block",
  "expires_at": "2026-03-12T00:00:00Z"
}

Allowlist for internal network only

Add an allow rule for your office subnet, then block 0.0.0.0/0 — only office IPs pass through.

{"cidr": "192.168.1.0/24", "rule_type": "allow", "reason": "Office network"}
{"cidr": "0.0.0.0/0", "rule_type": "block", "reason": "Block everything else"}

Note: Block rules take precedence, so 0.0.0.0/0 blocks all. The allow rule for 192.168.1.0/24 provides an explicit exemption only if your filtering logic checks allow rules before applying the catch-all block. Verify behavior with your specific setup.