Download the plugin

Download the latest .zip file from your License Portal. Always download from here — never from a third-party source, as redistributed copies may be modified.

Install in WordPress

1. In your WordPress admin, go to Plugins → Add New → Upload Plugin
2. Choose the bothammer.zip file you downloaded
3. Click Install Now, then Activate Plugin
4. A new Bothammer menu item will appear in your sidebar

What gets installed

Bothammer creates its own database tables on activation and writes an entry to your .htaccess file for the three-tier blocking system. Depending how large you set your blacklist too, this can be quite a few entries, but that's perfectly fine. It also registers several WordPress cron jobs for background syncing. We write to our plugin directory and the mu-plugin/bothammer-cache directory.

Optional but recommended

• nftables — for kernel-level IP blocking (Linux only). If not present, Bothammer falls back to .htaccess blocking and logs a non-fatal error.
• API keys — AbuseIPDB, IPinfo.io, MaxMind, VirusTotal, Greynoise, or Shodan for enriched IP intelligence. Free tiers on most services are sufficient for low-to-medium traffic sites.
• Cloudflare or AWS account — for WAF auto-sync.

Where to find your key

Your license key was emailed to you immediately after purchase. It has the format BH-XXXX-XXXX-XXXX-XXXX. You can also retrieve it from the License Portal at any time.

Activating

1. In WordPress admin go to Bothammer → Settings → License
2. Paste your key into the license field
3. Click Activate License
4. Bothammer contacts the license server, verifies your key, registers your domain, and caches your plan details locally
5. A green status indicator confirms activation — your plan name and expiry date are shown

What activation does

On activation, Bothammer sends your domain and a randomly generated per-site secret to the license server. The secret is stored in Cloudflare KV and used to sign all future API requests with HMAC-SHA256. This means your license key never travels over the wire after the initial activation — only signed requests do.

From the plugin

Go to Bothammer → Settings → License and click Deactivate. This removes your domain from the license server and frees the seat. The plugin continues running locally but the Intelligence Feed disconnects and Pro/Agency features are gated until you reactivate on a new domain.

From the License Portal

If you no longer have access to the WordPress admin (e.g. a site you are migrating away from), visit bothammer.com/portal, enter your license key, and click Deactivate next to the domain you want to remove.

The concept

When Bothammer blacklists an IP on your site, that IP is queued for upload to the shared Intelligence Feed — a database hosted on Cloudflare's edge. Every five minutes, a background cron job uploads your queued IPs and downloads IPs that have been reported by other sites in the network.

Downloaded IPs are automatically added to your local blacklist. Bots that hit one site get blocked across the entire network within one sync cycle — typically under 5 minutes.

Security model

Every API request to the Feed is signed with HMAC-SHA256 using a per-site secret generated at activation. The secret never leaves your server after setup. Requests without a valid signature are rejected by the Worker. Your domain is verified on every request — a license activated on site-a.com cannot make requests claiming to be site-b.com.

What is shared

Only IP addresses, their country code, and ASN are shared. No URLs, no User-Agents, no visitor data, no content from your site. The Feed is a pure IP reputation list.

Enable the feed

1. Make sure your license is activated (the feed requires an active Pro or Agency licence)
2. Go to Bothammer → Settings → Intelligence Feed
3. Toggle Enable Intelligence Feed on
4. Choose your mode: Send + Pull (recommended) or Pull only
5. Save settings — the first sync runs within 5 minutes

Verify it is working

Go to Bothammer → Settings → Intelligence Feed and check the Last sync timestamp. After the first successful sync you will see an Uploaded count and a Downloaded count. You can also check your debug log for lines like:

[INFO] Bothammer: uploaded 8 IPs
[INFO] Bothammer: downloaded and applied 17 IPs

What federation keys do

A federation key is a shared secret you set on multiple sites. Sites sharing the same federation key only exchange bot intelligence with each other — not with the public feed. This is useful for agencies managing multiple client sites, or for organisations that want to share threat data internally without contributing to or receiving from the public network.

Setting up a federation key

1. Go to Bothammer → Settings → Intelligence Feed on your Agency licence site
2. Enter a federation key in the Federation Key field — this can be any string, but treat it like a password
3. Save settings
4. Repeat on every other site you want in the same private ring, using the exact same key

Threshold score

Each visitor accumulates a threat score based on their User-Agent, headers, IP reputation, request patterns, and behaviour. When the score crosses your configured threshold (default: 21), Bothammer takes action based on the current protection mode. You can adjust the threshold in Bothammer → Settings → Detection.

Blacklisting

Go to Bothammer → Blacklist to add entries manually. You can blacklist by exact IP, CIDR range, ASN (e.g. AS13335), country code, User-Agent string, or request URI pattern. Bulk import is supported — paste a list of IPs or upload a file exported from a Cloud WAF.

Whitelisting

Whitelisted entries are never blocked regardless of their threat score. Whitelist by IP, CIDR, ASN, or User-Agent. You can also whitelist with a secret URL parameter — useful for giving trusted crawlers or monitoring services a pass without exposing your whitelist publicly.

The three-tier .htaccess system

Bothammer maintains up to 1,000 of your top-ranked IPs directly in .htaccess using Apache RewriteMap. IPs in the top 1,000 by hit count are blocked at the Apache level before PHP even starts — zero CPU cost per blocked request. IPs outside the top 1,000 are still blocked by the PHP layer on first contact, then ranked up into the .htaccess tier as they accumulate hits.

Cloudflare

1. In Cloudflare, go to My Profile → API Tokens → Create Token
2. Use the Edit Cloudflare Workers template, scoped to your zone
3. Copy the token
4. In Bothammer go to Settings → WAF Sync → Cloudflare
5. Paste your API token and Zone ID, then enable auto-sync

AWS WAF

1. Create an IAM user with wafv2:UpdateIPSet and wafv2:GetIPSet permissions
2. Create an IP Set in AWS WAF for Bothammer to manage
3. In Bothammer go to Settings → WAF Sync → AWS WAF
4. Enter your Access Key ID, Secret, region, and IP Set ARN

Go to Bothammer → Settings → Notifications to configure channels. Each channel can be toggled independently and scoped to specific event types.

CPU Guardian runs as a background systemd service that monitors CPU load and takes configurable action when your threshold is exceeded. The default threshold is 15%.

Available actions

• Monitor only — log the event and send a notification, take no further action
• Suspend HTTPD — temporarily bring down the web server for a configurable hold-down period
• Shutdown HTTPD — permanently stop the web server until you manually restart it
• Close public interface — block external traffic while keeping internal access alive
• Execute custom script — run any script you specify; possibilities are unlimited
• Send notification only — alert you and do nothing else

How it works

Bothammer injects a hidden link into your page HTML using CSS display:none. Real human visitors never see or click it. Any automated crawler that follows links indiscriminately will hit the trap URL, immediately identifying itself as a bot. Bothammer blacklists the IP on contact.

Enable honeypots

1. Go to Bothammer → Settings → Honeypot
2. Toggle Enable Honeypot Traps on
3. Optionally customise the trap URL pattern
4. Save — the trap link is injected automatically into your theme's footer

What this means

This error appears in your log when Bothammer tries to add an IP to the kernel-level nftables blacklist but the nftables table or set does not exist on your server. It is a non-fatal error — .htaccess and PHP-level blocking still work normally.

[ERROR] Failed to add IP 82.21.248.218 to nftables blacklist: Error: No such file or directory
add element inet filter blacklist { 82.21.248.218 timeout 3600s }
                ^^^^^^^^^

Fix: create the nftables table and set

Run these commands on your server as root. This creates the permanent inet filter table with a blacklist set that Bothammer expects.

nft add table inet filter
nft add set inet filter blacklist { type ipv4_addr \; flags timeout \; }
nft add rule inet filter input ip saddr @blacklist drop
nft-save  # or: nft list ruleset > /etc/nftables.conf

If nftables is not installed on your server at all, either install it (apt install nftables) or disable the nftables sync in Bothammer → Settings → Firewall to suppress the error.

Bothammer writes up to 999 IPs to your .htaccess file ranked by hit count. When you see a log line like:

[WARNING] ❌ Triggering IP 87.236.176.53 EXCLUDED from .htaccess (not in top 1000 (active-only mode))

This means the IP was blacklisted and added to your database, but it did not have enough hit count to displace an existing top-1000 entry in .htaccess yet. It is still blocked — by PHP on its next request. Once it returns and accumulates hits, it will rank into the .htaccess tier automatically.

This is by design. Putting thousands of IPs in .htaccess would make the file enormous and slow Apache's startup. The top-1000 tier covers your most persistent attackers at zero PHP cost; everything else is caught by PHP before it can cause damage.

If none of the above apply, email [email protected] with your license key and the exact error message.

Check the cron is running

The feed sync runs via WordPress cron every 5 minutes. If your server does not have a real cron job calling wp-cron.php and your site has low traffic, WordPress cron may not fire reliably. Add a real system cron job:

*/5 * * * * curl -s https://yoursite.com/wp-cron.php?doing_wp_cron > /dev/null 2>&1

Check your license is active

The feed will not sync if the license is not active or if Bothammer activation has not been run. Check Bothammer → Settings → License.

Check outbound HTTPS

The feed requires outbound HTTPS to your Cloudflare Worker URL. Some hosting environments block outbound requests. Check with your host, or look for curl errors in your debug log.

Identify the blocked IP

Go to Bothammer → Bot Jail and search for the IP or User-Agent. The Threat reason column shows exactly which signals contributed to the score.

Whitelist the IP

Go to Bothammer → Whitelist → Add Entry and add the IP, CIDR range, or ASN. Whitelisted entries are never blocked regardless of score.

Adjust the threshold

If you see a pattern of legitimate services being caught at a score just above your threshold, raise the threshold slightly in Bothammer → Settings → Detection. Common legitimate services that score higher than expected: monitoring tools, uptime checkers, and corporate proxies that strip browser headers.