Blackhole is a WordPress security plugin that detects and traps bad bots in a virtual black hole, where they are denied access to your entire site.
Add your own virtual black hole trap for bad bots.
Bye bye bad bots..
Bad bots are the worst. They do all sorts of nasty stuff and waste server resources. The Blackhole plugin helps to stop bad bots and save precious resources for legit visitors.
How does it work?
First the plugin adds a hidden trigger link to the footer of your pages. You then add a line to your robots.txt file that forbids all bots from following the hidden link. Bots that then ignore or disobey your robots rules will crawl the link and fall into the trap. Once trapped, bad bots are denied further access to your WordPress site.
I call it the “one-strike” rule: bots have one chance to obey your site’s robots.txt rule. Failure to comply results in immediate banishment. The best part is that the Blackhole only affects bad bots: human users never see the hidden link, and good bots obey the robots rules in the first place. Win-win! ๐
Using a caching plugin? Check out the Installation notes for important info.
Features
Blackhole for Bad Bots protects your site against bad bots, spammers, scrapers, scanners, and other automated threats.
Not using WordPress? Check out the standalone PHP version of Blackhole!
Check out Blackhole Pro and level up with advanced features!
Whitelist
By default, this plugin does NOT block any of the major search engines (user agents):
These search engines (and all of their myriad variations) are whitelisted via user agent. So are a bunch of other “useful” bots. They always are allowed full access to your site, even if they disobey your robots.txt rules. This list can be customized in the plugin settings. For a complete list of whitelisted bots, visit the Help tab in the plugin settings (under “Whitelist Settings”).
Privacy
User Data: This plugin automatically blocks bad bots. When bad bots fall into the trap, their IP address, user agent, and other request data are stored in the WP database. No other user data is collected by this plugin. At any time, the administrator may delete all saved data via the plugin settings.
Services: This plugin does not connect to any third-party locations or services.
Cookies: This plugin does not set any cookies.
Credit: Header Image Courtesy NASA/JPL-Caltech.
Blackhole for Bad Bots is developed and maintained by Jeff Starr, 15-year WordPress developer and book author.
Support development
I develop and maintain this free plugin with love for the WordPress community. To show support, you can make a donation or purchase one of my books:
And/or purchase one of my premium WordPress plugins:
Links, tweets and likes also appreciated. Thank you! ๐
Installing Blackhole for Bad Bots
Note: For the robots.txt rules, there are two scenarios:
For complete documentation, click the “Help” tab in the upper-right corner of the Blackhole settings screen. Help tab also available on the “Bad Bots” screen.
More info on installing WP plugins
Verify Blackhole is working properly
Using a caching plugin? Check out the section below called “Caching Plugins” for important info.
Caching Plugins
Blackhole works with any type of caching except for “page caching”. It is not yet compatible with page caching plugins/scripts. So if your site uses any sort of page caching, do not use this plugin. Thank you!
More details: There are many types of cache plugins. They provide all sorts of different caching mechanisms and features. All caching features work great with Blackhole except for โpage cachingโ. With page caching, the required WP init
hook may not be fired, which means that plugins like Blackhole are not able to log and ban requests dynamically. Fortunately, some of the most popular caching plugins provide settings that enable full compatibility with Blackhole. For a complete list, check out this article. Note: that article was written for Blackhole Pro, but the compatibility list and general info apply also to Blackhole (free version).
No robots.txt?
For the robots.txt file, there are two possible scenarios:
If you go with option #1, here are the steps to create a robots.txt file for your site:
robots.txt
and upload to your serverDone. Now you can add the Blackhole rules provided on the plugin settings page. See the next section to learn more and validate your robots.txt file.
To view your robots.txt file, visit the following URL (replace example.com with your domain):
https://example.com/robots.txt
Tip: you can find a link to your site’s robots.txt file on the plugin settings page.
Robots Tools & Info
Here are some collected resources for working with robots.txt. See also the next section, “Testing Robots.txt” for more tools.
Lots more great resources on the web to learn about and validate your robots.txt file. Read up, it’s important for SEO.
Testing Robots.txt
To test that your site’s robots.txt rules are correct, you can use a free robots.txt checker. Google provides a robots checker inside of your Google account (i.e., must be logged in to Google). There are many other robots validators around online. Here are some examples:
Tons more robots tools available online, just search for something like “validate robots.txt” (without the quotes) to discover more.
Testing Blackhole
To test that the Blackhole trap is working, first remove your IP address(es) from the plugin setting, “Whitelist IPs”. Also make sure your browser is not included in the plugin setting, “Whitelist Bots” (for example, Chrome is whitelisted). OR instead of changing any plugin settings, you can use a proxy service and non-whitelisted browser (e.g., Brave or Opera) to perform the test.
After removing your IP address and user agent (or using a proxy service), view the source code of any web page on your site. Scroll down near the footer of the page until you locate a link that looks similar to the following:
<a rel="nofollow" style="display:none" href="https://example.com/?blackhole=1234567890" title="Do NOT follow this link or you will be banned from the site!">Name of Your Website</a>
Click the link (the href
value) to view the Warning Message. After visiting the Warning Message, refresh the page to view the Access Denied message. And/or visit any other page on the front-end of your site to verify that you have been banned. But don’t worry, you will never be banned from the WP Admin Area or the WP Login Page. So simply log in and remove your IP address from the Bad Bots list to restore front-end access.
More information on how to verify Blackhole is working »
Why no bots?
If you’re not seeing any bad bots getting blocked, there are several things to keep in mind:
So keep those things in mind. In most cases it’s just a matter of time before some bad bots fall into the black hole.
Also note that the plugin provides two “whitelist” settings:
By default, certain things are automatically whitelisted when the plugin is activated. For example, your IP address is added to the whitelist IP setting. Also Chrome and other user agents are added to the whitelist user-agents setting. Just to keep in mind when testing plugin functionality.
Whitelisted Bots
Blackhole for Bad Bots is rigorously tested to ensure that the top search engine bots are NEVER BLOCKED. Any bots reporting a User Agent that contains any of the following strings will always have access to your site, even if they disobey robots.txt.
a6-indexer, adsbot-google, ahrefsbot, aolbuild, apis-google, baidu, bingbot, bingpreview, butterfly, cloudflare, chrome, duckduckgo, embedly, facebookexternalhit, facebot, google page speed, googlebot, ia_archiver, linkedinbot, mediapartners-google, msnbot, netcraftsurvey, outbrain, pinterest, quora, rogerbot, showyoubot, slackbot, slurp, sogou, teoma, tweetmemebot, twitterbot, uptimerobot, urlresolver, vkshare, w3c_validator, wordpress, wp rocket, yandex
Of course, this list is completely customizable via the plugin settings. Each added string is matched against the full user agent, so be careful. Learn more about user agents of the top search engines.
You can also whitelist bots by IP address. Visit the setting, “Whitelist IPs”, and enter the IP address (separate multiple IPs with commas). You can also whitelist entire ranges of IPs. In the same plugin setting, add something like this:
123.456.
That will allow all bots reporting any IP that begins with 123.456.
. You can also whitelist IP addresses using CIDR notation. Check out the Help tab on the plugin settings page for details.
Customizing
Blackhole provides plenty of hooks for customizing and extending:
blackhole_options blackhole_badbots blackhole_get_options blackhole_get_badbots blackhole_log_data blackhole_trigger blackhole_vars blackhole_log blackhole_ip_keys blackhole_alert_name blackhole_alert_subject blackhole_alert_message blackhole_alert_headers blackhole_needle blackhole_message_default blackhole_message_custom blackhole_message_nothing blackhole_ignore_loggedin blackhole_ignore_backend blackhole_ignore_login blackhole_block_status blackhole_block_protocol blackhole_block_connection blackhole_ip_filter blackhole_validate_ip_log blackhole_settings_contextual_help blackhole_badbots_contextual_help
If you need a hook added, drop me a line, will be glad to hook it up ๐
Custom Warning Template
The Blackhole displays two types of messages:
The Blocked Message may be customized via the plugin settings. The Warning Message may be customized by setting up a custom template:
blackhole-template.php
from the plugin’s /inc/
directory/wp-content/my-awesome-theme/blackhole-template.php
If the custom template exists in your theme directory, the plugin automatically will use it to display the Warning Message. If the custom template does not exist in your theme directory, the plugin will fallback to the default warning message.
Tip: Instead of including the custom template in your theme, you can include via /wp-content/
directory, like: /wp-content/blackhole/blackhole-template.php
More options available in the Pro version »
Uninstalling
Blackhole for Bad Bots cleans up after itself. All plugin settings and the bad bot list will be removed from your database when the plugin is uninstalled via the Plugins screen. After uninstalling, don’t forget to remove the blackhole rules from your robots.txt
file. It’s fine to leave them in place, it will not hurt anything, but they serve no purpose without the plugin installed.
More specifically, Blackhole adds only two things to the database: options and bot list. When the plugin is uninstalled/deleted via the Plugins screen, both of those items are removed automatically via the following lines in uninstall.php
:
delete_option('bbb_options'); delete_option('bbb_badbots');
So after uninstalling the plugin and deleting the robots.txt rules, there will be no trace of Blackhole for Bad Bots on your site.
Like the plugin?
If you like Blackhole for Bad Bots, please take a moment to give a 5-star rating. It helps to keep development and support going strong. Thank you!
Yes, three of them:
Pro versions with more features available at Plugin Planet.
Blackhole uses its own “smart bot technology” that only blocks bots if they have demonstrated bad behavior. Firewalls typically are “static” and block requests based on a predefined set of patterns. That means that firewalls sometimes block legitimate visitors. Blackhole never blocks regular visitors, and only it blocks bots that disobey your site’s robots.txt rules. So the rate of false positives is close to zero.
In order for the plugin to add the trigger link to your pages, your theme must include the template tag, wp_footer()
. This is a recommended tag for all WordPress themes, so your theme should include it. If not, you can either add it yourself or contact the theme developer and ask for help. Here is more information about wp_footer(). Once the footer tag is included, the plugin will be able to add the trigger link to your pages.
No. Never. All the major search engine bots are whitelisted and will never be blocked. Unless you remove them from the whitelist setting, which is not recommended.
Impossible because the plugin never blocks by user agent. It only blocks by IP address. No other criteria are used to block anything.
Question: Is it possible to block some bots by just adding them to blocked list and deny them Access to my website?
Answer: Not possible with the free version, but the Pro version includes an easy way to add bots manually (via the Bad Bots Log).
Visit the plugin settings and add to the list.
Visit the plugin settings and click the button.
Not possible with the free version, but can do with the Pro version.
Visit the plugin settings and click the button.
Yes. Visit Perishable Press to download a PHP-based version that does not require WordPress.
Yes, the Pro version is available at Plugin Planet.
Not yet, but it’s on the to-do list.
Your server IP address and your local (home) IP address (or whichever IP you are using when the plugin is installed).
Yes, you can add the following code anywhere in your theme template:
<?php if (function_exists('blackhole_trigger')) blackhole_trigger(); ?>
Question: Should whitelisted bots contain exact names, or can I just use partial names?
Answer: You can use partial names or full names, depending on how specific you would like to be with blocking. If you look at the default whitelisted bot strings, you will see that they are just portions of the full user agent. So for example you can block all bots that include the string “whateverbot” by including that string in the whitelist setting. It makes it easier to block bots, but you have to be careful about false positives.
If you like Blackhole for Bad Bots, please take a moment to give a 5-star rating. It helps to keep development and support going strong. Thank you!
3.7.1 (2024/06/29)
dismiss_notice_link
Full changelog @ https://plugin-planet.com/wp/changelog/blackhole-bad-bots.txt