LW Firewall

Lightweight WordPress firewall - rate-limits endpoints, blocks bots, bans repeat offenders, and adds security headers.

Overview

Installation

composer require lwplugins/lw-firewall

Or upload the lw-firewall folder to /wp-content/plugins/ and activate through the Plugins menu. The MU-plugin worker is installed automatically on activation.

Features

How It Works

LW Firewall installs an MU-plugin worker that intercepts requests before WordPress fully loads, protecting your server from bots, brute-force attacks, DDoS, and vulnerability scanners.

Processing order:

1. IP Whitelist - whitelisted IPs skip all checks
2. IP Blacklist - blacklisted IPs get 403 immediately
3. Geo Blocking - block entire countries (Cloudflare header or CIDR lookup)
4. Auto-Ban - previously banned IPs get 403
5. 404 Flood - IPs with excessive 404s get 429
6. Bot Blocking - User-Agent matching (all requests)
7. Endpoint Detection - filter params, cron, xmlrpc, login, REST API
8. Rate Limiting - per-IP counters with auto-ban escalation

Endpoint Protection

Geo Blocking

• Block visitors by country (Cloudflare or CIDR fallback)
• Enabled by default for CN, RU, IN, VN, ID, BD
• Apache-level geo blocking via .htaccess - blocks before PHP loads
• Configurable block action (403 Forbidden or redirect to homepage)

Bot Blocking

• User-Agent based blocking (20+ bad bots blocked by default)
• Applies to all requests, not just specific endpoints

IP Management

• IP whitelist and blacklist with CIDR range support
• Automatic server/localhost IP whitelisting
• Full IPv6 support

Auto-Ban

• Escalating protection for repeat offenders
• Per-IP violation counters

Security HTTP Headers

• X-Content-Type-Options
• X-Frame-Options
• And other configurable security headers

Storage Backends

Auto-detection picks the best available backend.

Additional Features

• Cloudflare-aware IP detection (CF-Connecting-IP with IP range validation)
• Import/Export settings as JSON
• Optional request logging with viewer
• wp-config.php constant overrides

Settings

Configure under LW Plugins > Firewall. The settings page uses a tabbed interface with 9 tabs:

WP-CLI Commands

Status

wp lw-firewall status

Shows firewall status overview: enabled, storage, rate limit, worker status, etc.

Configuration

# List all settings
wp lw-firewall config list
wp lw-firewall config list --format=json
 
# Set a value
wp lw-firewall config set rate_limit 50
wp lw-firewall config set enabled true
wp lw-firewall config set storage apcu
wp lw-firewall config set action 429
 
# Reset to defaults
wp lw-firewall config reset --yes

Blocked Bots

# List blocked User-Agents
wp lw-firewall bots list
wp lw-firewall bots list --format=json
 
# Add a bot
wp lw-firewall bots add "newbot/1.0"
 
# Remove a bot
wp lw-firewall bots remove "newbot/1.0"

Logs

# View recent logs
wp lw-firewall logs list
wp lw-firewall logs list --limit=50
wp lw-firewall logs list --format=json
 
# Clear all logs
wp lw-firewall logs clear --yes

Worker Management

# Install/reinstall the MU-plugin worker
wp lw-firewall worker install
 
# Remove the worker
wp lw-firewall worker remove

IP Management

# List whitelist or blacklist
wp lw-firewall ip list whitelist
wp lw-firewall ip list blacklist
wp lw-firewall ip list whitelist --format=json
 
# Add an IP or CIDR range
wp lw-firewall ip add whitelist 192.168.1.100
wp lw-firewall ip add blacklist 10.0.0.0/8
 
# Remove an IP or CIDR range
wp lw-firewall ip remove whitelist 192.168.1.100
wp lw-firewall ip remove blacklist 10.0.0.0/8

Geo Blocking

# List blocked countries
wp lw-firewall geo list
wp lw-firewall geo list --format=json
 
# Add a country (ISO 3166-1 alpha-2 code)
wp lw-firewall geo add CN
wp lw-firewall geo add RU
 
# Remove a country
wp lw-firewall geo remove CN
 
# Update CIDR cache for all blocked countries
wp lw-firewall geo update

Configuration via wp-config.php

Settings can be overridden via constants in wp-config.php:

define( 'LW_FIREWALL_ENABLED', true );
define( 'LW_FIREWALL_STORAGE', 'apcu' );
define( 'LW_FIREWALL_RATE_LIMIT', 50 );
define( 'LW_FIREWALL_RATE_WINDOW', 120 );
define( 'LW_FIREWALL_ACTION', '429' );
define( 'LW_FIREWALL_LOG_ENABLED', true );

AI Abilities

When used with LW Site Manager, the following abilities are available for AI agents. All abilities are registered under the firewall category and require manage_options capability.

lw-firewall/get-options (readonly)

Returns all LW Firewall settings merged with defaults.

Input: none

Output:

{
  "success": true,
  "options": {
    "enabled": true,
    "rate_limit": 30,
    "rate_window": 60,
    "ip_blacklist": [],
    "ip_whitelist": [],
    "blocked_bots": ["gptbot", "claudebot"],
    "geo_enabled": true,
    "blocked_countries": ["CN", "RU"]
  }
}

lw-firewall/get-log (readonly)

Returns recent blocked request log entries. Requires log_enabled to be active in settings.

Input:

Output:

{
  "success": true,
  "entries": [
    { "ip": "1.2.3.4", "reason": "rate_limit", "ua": "...", "url": "/wp-login.php", "time": "2025-01-01 12:00:00" }
  ],
  "total": 42
}

lw-firewall/list-blocked (readonly)

Returns all IP addresses and CIDR ranges currently on the manual blacklist.

Input: none

Output:

{
  "success": true,
  "ips": ["1.2.3.4", "10.0.0.0/8"],
  "total": 2
}

lw-firewall/block-ip (write)

Adds an IP address or CIDR range to the blacklist.

Input:

Output:

{ "success": true, "message": "1.2.3.4 has been added to the blacklist." }

Errors: 400 missing_ip, 400 invalid_ip

lw-firewall/unblock-ip (write)

Removes an IP address or CIDR range from the blacklist.

Input:

Output:

{ "success": true, "message": "1.2.3.4 has been removed from the blacklist." }

Errors: 400 missing_ip, 404 ip_not_found

Notes:

• The blacklist changes (block-ip / unblock-ip) are persisted immediately.
• Auto-banned IPs (set by the auto-ban system in storage) are separate from the manual blacklist and cannot be managed through these abilities.
• Log entries are only available when log_enabled is true in the firewall settings.

FAQ

Does it work without WooCommerce?

Yes. WooCommerce filter protection is optional. The firewall also protects wp-login.php, wp-cron.php, xmlrpc.php, REST API, and 404 floods independently.

What storage backend should I use?

APCu is fastest (in-memory, per-process). Redis is fast and shared across processes. File-based is the fallback that always works. Auto-detection picks the best available.

Will it block legitimate users?

Rate limits are per-IP. Casual users will not trigger them. Only bots and attackers sending many requests in a short window get blocked. You can whitelist trusted IPs.

Does it support Cloudflare?

Yes. It automatically detects the real visitor IP via the CF-Connecting-IP header with Cloudflare IP range validation to prevent spoofing.