IP Blacklist

Overview

The IP blacklist lets you block specific IP addresses or entire network ranges from accessing your domains. When a request comes from a blacklisted IP, HAProxy drops it immediately at the proxy level with a 403 Forbidden response -- the request never reaches your origin server. This is the simplest and most effective way to block known attackers, abusive IPs, or unwanted traffic sources.

The IP blacklist is the first check in the WAF processing pipeline (after the whitelist bypass). It runs at all WAF levels (low, medium, and high) and is always active when the WAF is enabled for a domain.

Adding IPs to the Blacklist

1. Navigate to Dashboard -> WAF.
2. Select the domain you want to configure.
3. Go to the IP Blacklist tab.
4. Enter an IP address or CIDR range and click Add.

You can also add blacklist entries via the API:

POST /api/waf
{
  "rule_type": "block_ip",
  "value": "45.33.32.0/24",
  "domain_id": "your-domain-uuid",
  "enabled": true
}

See API Keys for authentication details when using the API programmatically.

Supported Formats

You can block individual IPs or entire ranges using IPv4 addresses with optional CIDR notation:

# Single IP address
192.168.1.100

# CIDR range (blocks 256 addresses)
192.168.1.0/24

# Larger CIDR range (blocks 65,536 addresses)
10.0.0.0/16

# Very broad range (blocks 16.7 million addresses)
10.0.0.0/8

Validation Rules

The API validates IP blacklist entries with these rules:

• Must match the pattern: X.X.X.X or X.X.X.X/N
• Each octet must be between 0 and 255
• CIDR suffix must be between 0 and 32
• IPv6 addresses are supported at the dashboard level

Examples

Warning: Be cautious with broad CIDR ranges. Blocking a /16 affects over 65,000 IPs, and a /8 affects over 16 million. Many legitimate users could be behind IPs in those ranges, especially with shared hosting or mobile networks.

Per-Domain Blacklists

Each domain maintains its own independent blacklist. An IP blocked on example.com is not automatically blocked on api.example.com. This allows you to apply different blocking policies to different services.

If you need to block an IP across all your domains, you must add it to each domain's blacklist individually. Alternatively, you can create a global WAF rule (without a domain_id) via the API, though dashboard management is per-domain.

Tip: If you manage many domains and frequently block the same IPs, consider using the API keys feature to script bulk blacklist updates across all domains.

IP Whitelist

In addition to the blacklist, you can add trusted IPs to a whitelist. Whitelisted IPs bypass all WAF checks for that domain, including:

• IP blacklist
• Rate limiting
• Bot protection (JS challenge)
• OWASP pattern matching

This is processed as the very first step in the WAF pipeline -- before any other check runs.

When to Whitelist

Use the whitelist for:

• Your own IP addresses -- So your development and testing traffic is never blocked
• Monitoring and health check services -- UptimeRobot, Pingdom, StatusCake, and similar services that send automated requests
• Trusted API consumers -- Integration partners that need reliable access
• CI/CD pipelines -- Build servers and deployment tools that interact with your services
• Payment processors -- Webhook callbacks from Stripe, PayPal, or similar services

Adding a Whitelist Entry

1. Go to Dashboard -> WAF -> select domain -> IP Blacklist tab.
2. Switch to the Whitelist section.
3. Add the trusted IP or CIDR range.

Warning: Be careful with broad CIDR ranges in the whitelist. A whitelisted IP bypasses all WAF protections including rate limiting, bot protection, and OWASP rules. Only whitelist IPs you fully trust. A compromised whitelisted IP has unrestricted access to your domain through the proxy.

Real-Time Updates

Changes to the IP blacklist take effect immediately through the standard config push flow:

1. You add or remove an IP in the dashboard.
2. The change is saved to the database and validated.
3. A config update is pushed to the WebSocket server.
4. The WebSocket server forwards it to the agent on the shield VPS.
5. The agent regenerates the WAF Lua script with the updated blacklist.
6. HAProxy is reloaded with zero-downtime (new configuration applied to new connections).

The entire process completes in seconds. There is no caching delay or propagation period. If the HAProxy reload fails for any reason, the agent automatically rolls back to the previous working configuration.

Blocked Request Logging

When a request is blocked by the IP blacklist, it is logged in the WAF events with:

View blocked requests in Dashboard -> WAF -> Events.

Note: WAF events have a 7-day retention policy and are capped at 5,000 events per server per day to prevent storage abuse from high-volume attacks. If you are under sustained attack and hitting the event cap, the blocking still functions -- only the logging is limited.

Common Use Cases

Blocking a Known Attacker

If you see repeated malicious requests from a specific IP in your WAF events or server logs:

1. Go to Dashboard -> WAF -> Events and note the source IP.
2. Navigate to the domain's IP Blacklist tab.
3. Add the IP address (e.g., 45.33.32.156).
4. The block takes effect within seconds.

Blocking a Hostile Network

If attacks are coming from a range of IPs within the same network (check if the first 3 octets are the same):

Block: 45.33.32.0/24

This blocks all 256 addresses from 45.33.32.0 through 45.33.32.255.

Blocking by Country IP Range

If you want to block traffic from specific regions, you can add the country's IP ranges. Country IP ranges are publicly available from Regional Internet Registries (RIRs):

• RIPE NCC -- Europe, Middle East, Central Asia
• ARIN -- North America
• APNIC -- Asia-Pacific
• LACNIC -- Latin America
• AFRINIC -- Africa

Note: Country-based blocking via IP ranges requires adding many CIDR entries. Lumos Gate also supports block_country rules using 2-letter ISO country codes (e.g., CN, RU) as a WAF rule type, which is more efficient. You can create these via the API with rule_type: "block_country".

Blocking Known Bad Networks

Some networks are notorious for hosting bots and attack infrastructure. You can proactively block these ranges. Public threat intelligence feeds such as Spamhaus DROP, FireHOL, and AbuseIPDB provide curated lists of malicious IP ranges.

Escalating from Rate Limiting

A common workflow is to use rate limiting first as a softer measure, then escalate to the blacklist:

1. Enable rate limiting and monitor the WAF events log.
2. Identify IPs that consistently trigger rate limit blocks.
3. If the IP is clearly malicious (not a legitimate user behind NAT), add it to the blacklist.
4. Blacklisted IPs are blocked immediately without consuming rate limit tracking resources.

Interaction with Other WAF Modules

The IP blacklist interacts with other WAF protection layers in a specific order:

Request arrives
    |
    v
1. IP Whitelist check -> If matched, skip ALL checks, pass to origin
    |
    v
2. IP Blacklist check -> If matched, return 403 (this module)
    |
    v
3. Bot Protection    -> JS challenge / bad UA block
    |
    v
4. Rate Limiting     -> 429 if exceeded
    |
    v
5. OWASP Rules       -> SQLi/XSS pattern matching
    |
    v
6. Pass to origin

Key implications:

• A whitelisted IP is never checked against the blacklist.
• A blacklisted IP is blocked before bot protection or rate limiting runs, so it does not consume resources in those modules.
• If you whitelist an IP that is also on the blacklist, the whitelist takes precedence (the IP is allowed through).

Best Practices

• Start with specific IPs before escalating to CIDR ranges. Blocking a /16 range blocks over 65,000 IPs and may catch legitimate users, especially on mobile networks or shared hosting.

• Review WAF events first. Before blocking an IP, check the events log to understand the attack pattern. Some "attacks" might be legitimate crawlers, monitoring services, or misconfigured integrations.

• Use the whitelist sparingly. Only whitelist IPs that you fully trust. A compromised whitelisted IP bypasses all protections.

• Document your blocks. Keep track of why you blocked specific IPs or ranges so you can review and clean up the blacklist periodically. Stale blacklist entries add unnecessary processing overhead.

• Combine with rate limiting. For less severe cases, rate limiting might be a better fit than outright blocking. Rate limiting allows normal usage while preventing abuse, and you can always escalate to a blacklist later.

• Consider bot protection for automated attacks. If you are seeing bot traffic from many different IPs (making individual blocking impractical), enable bot protection to filter out non-browser clients across the board.

• Lock down your origin. Even with a comprehensive blacklist, you should configure your origin server's firewall to only accept traffic from your shield VPS. See Origin Firewall for setup instructions.

Next Steps

• WAF Overview -- Understand the full WAF architecture, levels, and processing order
• Rate Limiting -- Configure per-domain request rate limits as a graduated response
• Bot Protection -- Block automated traffic with JavaScript challenges
• Origin Firewall -- Lock down your origin server to only accept traffic from shield VPS
• WireGuard Tunnel -- Encrypt the connection between shield and origin servers
• Notifications -- Get alerted when your server is under attack
• API Keys -- Automate blacklist management with the API
• Troubleshooting -- Common issues and solutions