Skip to content

IP Lists

Website Defender provides IP whitelist and blacklist management to control access at the network level. IP checks are the first step in the auth verification flow, evaluated before any token-based authentication.

IP Whitelist

The IP whitelist allows specific IP addresses or CIDR ranges to bypass all authentication checks. Whitelisted IPs are granted access immediately without any token validation.

Use cases:

  • Internal network ranges that should always have access
  • Monitoring systems and health check probes
  • Trusted CI/CD infrastructure

Supported Formats

Format Example Description
Exact IP 192.168.1.100 Matches a single IP address
CIDR range 192.168.1.0/24 Matches all IPs in the subnet
IPv6 ::1 Supports IPv6 addresses

Use CIDR for Internal Networks

Rather than whitelisting individual IPs, use CIDR notation to whitelist entire subnets. For example, 10.0.0.0/8 covers all private IPs in the 10.x.x.x range.

IP Blacklist

The IP blacklist blocks specific IP addresses or CIDR ranges before any other processing. Blacklisted IPs receive an immediate 403 Forbidden response.

Use cases:

  • Blocking known malicious IPs
  • Blocking IP ranges associated with abuse
  • Emergency blocking during active attacks

Supported Formats

The same formats as the whitelist are supported: exact IP, CIDR range, and IPv6.

Temporary Bans

Blacklist entries support an optional expiration time, enabling temporary bans:

  • Permanent -- no expiration (default)
  • Timed -- choose from preset durations: 1 hour, 6 hours, 24 hours, 7 days, 30 days
  • Auto-ban -- the threat detection engine automatically creates temporary blacklist entries when thresholds are exceeded

Expired entries are automatically cleaned up every 10 minutes.

Remarks

Each blacklist entry can include an optional remark field for notes (e.g., "suspicious scanning activity", "auto-banned: brute force"). Auto-banned entries are labeled automatically.

Blacklist Takes Priority

The blacklist is checked before the whitelist. If an IP appears in both lists, it will be blocked. Always review your blacklist entries to avoid accidentally blocking trusted IPs.

Management

Authorized Domain Binding

Each IP whitelist entry can be bound to an authorized domain, indicating which protected domain this IP is whitelisted for. When adding a whitelist entry, the domain field provides a dropdown populated from the Authorized Domains registry.

If a whitelist entry is bound to a domain, the IP is only whitelisted for requests to that specific domain. Requests to other domains will fall through to token-based authentication. If the domain field is empty, the IP is whitelisted for all domains.

Admin Dashboard

Both IP lists can be managed through the admin dashboard:

  • Add new entries with domain binding (whitelist) or without (blacklist)
  • View all current entries
  • Delete individual entries

API

IP lists can also be managed programmatically via the REST API:

Method Path Description
GET /ip-black-list List all blacklist entries
POST /ip-black-list Add a blacklist entry
DELETE /ip-black-list/:id Remove a blacklist entry
GET /ip-white-list List all whitelist entries
POST /ip-white-list Add a whitelist entry
DELETE /ip-white-list/:id Remove a whitelist entry

All API routes require authentication. See the API Reference for full details.

Auth Flow Position

In the auth verification flow, IP checks are evaluated first:

IP Blacklist → IP Whitelist → JWT Token → Git Token → License Token → Deny

This means IP-level decisions are made before any token parsing or validation occurs, providing fast rejection of known-bad actors and fast acceptance of known-good infrastructure.