Nginx Ultimate Bad Bot Blocker: Nginx Config for Bots
/nginx-ultimate-bad-bot-blocker
Nginx Ultimate Bad Bot Blocker is a collection of Nginx config files and shell scripts that block bad user-agents, spam referrers, and vulnerability scanners through blocklists you install on your own server. It has 4771 GitHub stars. It refreshes its lists daily via cron. Reach for it if you run Nginx and want blocklist filtering without paying for a WAF; skip it if a CDN already screens this traffic for you.
Stopping Malicious Traffic on Nginx
Public Nginx servers draw scanners probing for vulnerable WordPress themes, scrapers ignoring robots.txt, referrer-spam bots trying to pollute your analytics with a domain, and fake Googlebots that spoof the real crawler's user-agent string to slip past simple checks. Nginx doesn't filter any of that by default, so you either hand-write your own map blocks and deny rules or find a maintained list and script to do it for you. Nginx Ultimate Bad Bot Blocker exists because doing that signature by signature doesn't scale, and a blocklist that isn't updated daily goes stale within weeks as new bot signatures show up.
What is the Nginx Ultimate Bad Bot Blocker?
Nginx Ultimate Bad Bot Blocker is an Nginx add-on shipped as a set of config files (globalblacklist.conf, blockbots.conf, ddos.conf, and more) plus install, setup, and update shell scripts, maintained by Mitchell Krog. At version V4.2026.08.6097 it blocks 7115 bad referrers, 699 bad user-agents, and 218 fake Googlebot signatures, and it can refresh those lists on its own through a daily cron job.
Key Protection Features
- โBlocks 699 bad user-agents and 7115 bad referrers through globalblacklist.conf and the bots.d/*.conf files it installs, per the version V4.2026.08.6097 counts in the README.
- โFlags 218 fake Googlebot signatures: user-agents that claim to be Googlebot without matching Google's real crawler, a category most generic bot lists skip.
- โShips a dedicated ddos.conf for Nginx-level rate limiting, kept separate from the bot and referrer blocklists.
- โBlocks referrer spam through bad-referrer-words.conf and a custom-bad-referrers.conf you can extend with your own domains.
- โDetects WordPress theme-detector scanners, per the repo's own description and topics.
- โRepo topics also tag it for gambling- and porn-referrer filtering, plus adware, malware, and spyware blocking, alongside the core bot and referrer lists.
- โThe GitHub description also mentions a Fail2Ban jail for repeat offenders, though the README text here doesn't walk through how it's wired up.
- โupdate-ngxblocker can email a report after each auto-update, or run silently with the -n flag.
Who Benefits from This Blocker?
Nginx Ultimate Bad Bot Blocker fits people running their own Nginx server with shell access and root, not managed hosting where you can't drop files into /etc/nginx/. If you're already seeing scraper traffic, fake-Googlebot hits, or spam referrers cluttering your analytics, and you can set up a cron job, it saves you from hand-maintaining your own deny lists. Skip it if you're on shared hosting without root, or if a CDN in front of your site already filters this traffic before it reaches Nginx.
Installing the Nginx Bot Blocker
Linux installs pull a single script first: `sudo wget https://raw.githubusercontent.com/mitchellkrogza/nginx-ultimate-bad-bot-blocker/master/install-ngxblocker -O /usr/local/sbin/install-ngxblocker`, then `sudo chmod +x /usr/local/sbin/install-ngxblocker`. FreeBSD users can skip that and run `pkg install www/nginx-ultimate-bad-bot-blocker` instead. Running `sudo ./install-ngxblocker` does a dry run first, showing every file it will download before you commit to anything; add `-x` to actually pull globalblacklist.conf, botblocker-nginx-settings.conf, the bots.d/*.conf files, and the setup/update scripts into /etc/nginx/. From there, `sudo ./setup-ngxblocker -x` inserts the include lines into your vhost files. It assumes they live in /etc/nginx/sites-available/ and end in .vhost, though the -e flag (for example `-e conf`) points it at a different extension. Run `sudo nginx -t` to check the config, then `sudo nginx -s reload` to apply it. A separate manual-configuration path is documented in MANUAL-CONFIGURATION.md for anyone who'd rather skip the scripts.
Configuring and Maintaining Your Blocker
Put the updater on a nightly cron job so the lists don't go stale: `00 22 * * * sudo /usr/local/sbin/update-ngxblocker -e [email protected]` updates once a day and emails you a report. The README notes the maintainer sometimes ships 3-4 updates in a single day, so switching to `00 */8 * * *` catches those faster. Add `-n` to skip the email notification, or `-g` to route it through Mailgun instead. Your own edits live in files the updater never overwrites: whitelist-ips.conf, whitelist-domains.conf, blacklist-user-agents.conf, blacklist-ips.conf, bad-referrer-words.conf, and custom-bad-referrers.conf. To confirm it's working, curl your domain with a spoofed bad user-agent like `Xenu Link Sleuth/1.3.8`; the README says you should get a reset connection or empty reply instead of a normal response, while a real Googlebot or bingbot user-agent should still return 200 OK.
Strengths
- โFree and specific: 699 bad user-agents, 7115 bad referrers, and 218 fake-Googlebot signatures blocked out of the box, per the README's version-tagged counts.
- โUpdates itself through cron, so the lists don't go stale the way a one-time downloaded blocklist would.
- โYour customization files are protected from being overwritten during updates, so local tweaks survive.
- โDry-run modes on install-ngxblocker and setup-ngxblocker show every file it will touch before it touches anything.
- โFreeBSD gets an actual package (`pkg install www/nginx-ultimate-bad-bot-blocker`), not just the Linux script path.
Known Behaviors and Considerations
- โณThe GitHub facts here don't list a license, so check the repo directly before relying on it in anything license-sensitive.
- โณDuplicate [WARN] messages in the Nginx log are expected fallout from the daily blacklist reload process, not a bug, but they look alarming until you know that.
- โณThe README flags real trouble with Let's Encrypt's http-01 challenge method behind this blocker and recommends the webroot authenticator instead, without pinning down whether the cause is certbot or Nginx.
- โณsetup-ngxblocker assumes vhost files live in /etc/nginx/sites-available/ with a .vhost extension; anything else needs the -e flag, easy to miss on a first run.
- โณThe Fail2Ban jail named in the project description isn't walked through in the README text available here, so how it's configured isn't clear from this source.
- โณIt's Shell scripting built specifically for Nginx; none of it helps if you're running Apache, Caddy, or another reverse proxy.
Other Nginx Security Solutions
Frequently Asked Questions
Nginx Ultimate Bad Bot Blocker stops bad user-agents, spam referrers, vulnerability scanners, and fake Googlebots; its GitHub description also lists adware, malware, ransomware, and other malicious-site traffic among what it targets.
The maintainer updates the lists on an ongoing basis, and the README notes he sometimes pushes 3-4 updates in a single day; running update-ngxblocker nightly or every 8 hours via cron keeps your local copy current.
Nginx Ultimate Bad Bot Blocker supports customization through files like whitelist-ips.conf, whitelist-domains.conf, blacklist-user-agents.conf, and custom-bad-referrers.conf, all of which the auto-update script leaves untouched.
The README states it has been tested from Nginx 1.10.x through mainstream releases, but it doesn't claim compatibility with every version, so test in staging before rolling it out to production.
Nginx Ultimate Bad Bot Blocker's README explains these as expected behavior: daily blacklist reloads temporarily flag some IPs before whitelisting them again at the end of the load order, and it doesn't affect how Nginx runs.
Nginx Ultimate Bad Bot Blocker works alongside Let's Encrypt, but the README recommends the webroot authenticator method specifically, since some users hit unresolved issues with the http-01 challenge method.
Best use cases
- โขLocking down a self-managed Nginx server against scraper and vulnerability-scanner traffic without writing your own deny rules from scratch.
- โขCleaning up referrer spam in analytics tools by blocking the referrer domains before Nginx ever logs the hit.
- โขBlocking WordPress theme-detector bots on a self-hosted WordPress site running behind Nginx.
- โขRunning an automated, cron-driven update cycle for blocklists on a server you don't want to babysit by hand.
Related repositories
Is nginx-ultimate-bad-bot-blocker worth your time?
ChatGPT, Claude and Perplexity can all read this page. Ask one of them what it makes of nginx-ultimate-bad-bot-blocker.