ProbeGuard 404 Firewall for Cloudflare GitLab releases

WordPress plugin that records 404 requests and blocks or challenges abusive IPs at the Cloudflare edge using IP Access Rules, so scanners stop reaching PHP at all. Free and GPLv2 or later.

Full documentation — features, setup, whitelist syntax, IP detection, retention, external services and changelog — lives in readme.txt, which is also what WordPress.org renders. The plugin's own Documentation tab (Tools → ProbeGuard 404 Firewall) mirrors it.

What it does

• Counts 404s per IP. Cross the threshold you set within the window you set and the address is blocked, managed-challenged or interactive-challenged through a Cloudflare IP Access Rule.
• Blocks at the edge, not in PHP. A blocked scanner never reaches WordPress again, so it costs no workers and no database writes.
• Never blocks during a visitor's request. Rules are placed by a scheduled task, with a per-IP lock so a flood cannot create duplicate rules.
• Handles repeat offenders. An address blocked recently is re-blocked on its next single 404, and each repeat lasts twice as long, up to a ceiling you set.
• Trusts the visitor IP only when it should. CF-Connecting-IP is honoured only for requests arriving from a Cloudflare edge address, and the range list refreshes daily from Cloudflare. Private and reserved addresses are never sent as block targets.
• Expires everything it creates. Blocks unblock themselves, logs are pruned, and deactivating the plugin removes the rules it added unless you ask it to keep them.
• Anchored whitelist. Wildcard patterns matched against the path, the query string and the requested host, so a whitelisted string buried in a query string does not exempt a request.
• Optional email on every block.

Requirements

WordPress 5.3 or later, PHP 7.2 or later, and a site on Cloudflare — any plan, including the free one. IP Access Rules are not a paid feature.

Quick start

1. Copy the plugin into wp-content/plugins/probeguard-404-firewall-cloudflare and activate it.
2. Create a Cloudflare API token with the single permission Zone → Firewall Services → Edit, scoped to the site's zone.
3. Paste the token and the zone ID into Tools → ProbeGuard 404 Firewall → Settings. The token is stored in a non-autoloaded option, only ever shown masked afterwards, never rendered back to the browser, and deleted when the plugin is deleted.
4. Configure thresholds on the same tab.

The token can only add and remove access rules; it cannot touch DNS, billing or anything else in the account. Cloudflare Global API Keys are not supported, because they authenticate against the entire account.

To keep credentials out of the database, define them in wp-config.php instead; the constants win over the stored values and the fields are then read-only:

define( 'EDGE404_API_TOKEN', 'your-cloudflare-api-token' );
define( 'EDGE404_ZONE_ID', 'your-zone-id' );

One further optional constant exists: if the site is behind an additional proxy in front of Cloudflare, define EDGE404_TRUSTED_PROXIES with the proxy addresses or CIDR blocks, or forwarded headers are ignored.

The plugin was called CF 404 Defender before 2.0.0. Its CF_404_API_TOKEN, CF_404_ZONE_ID and CF404_TRUSTED_PROXIES constants are still honoured — their values are copied into the settings on upgrade so the constants can be removed whenever convenient — and tables, options and pending scheduled tasks are moved to the edge404_ names on upgrade. Sites calling the plugin's filters directly should switch them to the edge404_ prefix.

Screenshots

Status: the Cloudflare connection, the noisiest addresses and the blocks currently in place, each with an Unblock button.

The 404 log, showing what each address actually asked for.

Settings: thresholds, block duration, repeat-offender handling, log retention and the whitelist.

Documentation, with links that open the right Cloudflare screens for this site.

Development

composer install          # PHP_CodeSniffer + WordPress Coding Standards
composer run lint         # php -l over every file
composer run phpcs        # coding standards

.gitlab-ci.yml runs both on every push, plus the WordPress.org Plugin Check ruleset.

License

GPLv2 or later.