=== Blackhole for Bad Bots ===

Plugin Name: Blackhole for Bad Bots
Plugin URI: https://perishablepress.com/blackhole-bad-bots/
Description: Protects your site against bad bots by trapping them in a blackhole.
Tags: antispam, anti-spam, anti spam, bad bots, blacklist, block, bots, honeypot, protect, robots, robots.txt, security, spam, spiders
Author: Jeff Starr
Contributors: specialk
Author URI: http://monzilla.biz/
Donate link: http://m0n.co/donate
Requires at least: 4.1
Tested up to: 4.5
Stable tag: trunk
Version: 1.2
Text Domain: bbb
Domain Path: /lang/
License: GPL v2 or later

Protect your site against bad bots by trapping them in a virtual blackhole.



== Description ==

Add your own virtual Blackhole trap for bad bots. The Blackhole plugin includes a hidden link to your pages. You then add a line to your robots.txt file that forbids bots from following the hidden link. Bots that ignore or disobey your robots rules will crawl the link and fall into the honeypot trap. Once trapped, bad bots are denied further access to your WordPress-powered website.

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! :)

**Features**

* Easy to set up
* Squeaky clean code
* Built with the WordPress API
* Born of simplicity, no frills
* Lightweight, fast and flexible
* Easy to reset the list of bad bots
* Easy to delete any bot from the list
* Plugin options configurable via settings screen
* Works silently behind the scenes to protect your site
* Optionally receive an email alert with WHOIS lookup for blocked bots
* All major search engine bots are whitelisted so they will never get blocked
* Customize the message displayed to bad bots ;)
* One-click restore plugin default options

Not using WordPress? Check out the [standalone PHP version of Blackhole](https://perishablepress.com/blackhole-bad-bots/)!

Pro version coming soon!

**Whitelist**

By default, this plugin does NOT block any of the major search engines:

* AOL.com
* Baidu
* Bingbot/MSN
* DuckDuckGo
* Googlebot
* Teoma
* Yahoo!
* Yandex

These search engines (and all of their myriad variations) are whitelisted. 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.

*Header Image Courtesy NASA/JPL-Caltech.*



== Screenshots ==

1. Blackhole Settings Screen (showing default options)
2. Blackhole Bad Bots Screen (showing some example bots)



== Installation ==

**Installing Blackhole for Bad Bots**

1. Upload the Blackhole plugin to your blog and activate
2. Visit the Blackhole Settings and copy the Robots Rules
3. Add the Robots Rules to your site's robots.txt file
4. Configure the Blackhole Settings as desired and done

[More info on installing WP plugins](http://codex.wordpress.org/Managing_Plugins#Installing_Plugins)



**No robots.txt?**

If your site does not have a robots.txt file, you can create one as follows:

1. Add a blank text file to the root directory of your site
2. Name the text file, robots.txt and upload to your server

Done. See the next section to learn more and validate your robots.txt file.



**Robots Tools & Info**

* [Learn more about robots.txt](http://www.robotstxt.org/)
* [Validate your robots.txt file](http://www.lxrmarketplace.com/robots-txt-validator-tool.html)
* [Validate robots.txt in Google Webmaster Tools](https://www.google.com/webmasters/tools/robots-testing-tool)



**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.

	aolbuild, baidu, bingbot, bingpreview, msnbot, duckduckgo, adsbot-google, googlebot, mediapartners-google, teoma, slurp, yandex

Of course, this list is completely customizable via the plugin settings. Learn more about [user agents of the top search engines](https://perishablepress.com/list-all-user-agents-top-search-engines/).



**Testing**

To test that the Blackhole trap is working, 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="Blackhole for Bad Bots">Do NOT follow this link or you will be banned from the site!</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. 



**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_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

If you need a hook added, [drop me a line](https://perishablepress.com/contact/), will be glad to hook it up ;)



**Custom Warning Template**

The Blackhole displays two types of messages:

* Initial Warning - Displayed to bots when they first fall into the trap
* Access Denied - Displayed to banned bots on subsequent visits to your site

The Access Denied message may be customized via the plugin settings. The Initial warning may be customized by setting up a custom template:

1. Copy `/inc/blackhole-template.php` to `/custom/blackhole-template.php`
2. Customize any of the markup between "BEGIN TEMPLATE" and "END TEMPLATE"
3. Upload to your server and done

When the custom template exists in the `/custom/` directory, the plugin automatically will use it to display the Initial Warning message. If no custom template exists, the plugin will fallback to the default warning message.



**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.



== Upgrade Notice ==

To upgrade Blackhole for Bad Bots, remove the old version and replace with the new version. Or just click "Update" from the Plugins screen and let WordPress do it for you automatically.

Note: uninstalling the plugin from the WP Plugins screen results in the removal of all settings and data from the WP database. 



== Frequently Asked Questions ==

**The trigger link is not appearing in the source code of my pages.**

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()](https://codex.wordpress.org/Function_Reference/wp_footer). Once the footer tag is included, the plugin will be able to add the trigger link to your pages.


**Will this block good bots like Google and Bing?**

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.


**How do I add other bots to the whitelist?**

Visit the plugin settings and add to the list.


**How do I reset the list of blocked bots?**

Visit the plugin settings and click the button.


**How can I disable the email alerts?**

Visit the plugin settings and click the button.


**Is there a standalone version of the Blackhole?**

Yes. Visit Perishable Press to download a [PHP-based version](https://perishablepress.com/blackhole-bad-bots/) that does not require WordPress.

**Is Multisite supported?**

Not yet, but it's on the to-do list.

**Can I manually include the blackhole link?**

Yes, you can add the following code anywhere in your theme template:

`<?php if (function_exists('blackhole_trigger')) blackhole_trigger(); ?>`



**Got a question?**

Send any questions or feedback via my [contact form](https://perishablepress.com/contact/)



== Support development of this plugin ==

I develop and maintain this free plugin with love for the WordPress community. To show support, you can [make a cash donation](http://m0n.co/donate), [bitcoin donation](http://m0n.co/bitcoin), or purchase one of my books: 

* [The Tao of WordPress](https://wp-tao.com/)
* [Digging into WordPress](https://digwp.com/)
* [.htaccess made easy](https://htaccessbook.com/)
* [WordPress Themes In Depth](https://wp-tao.com/wordpress-themes-book/)

And/or purchase one of my premium WordPress plugins:

* [BBQ Pro](https://plugin-planet.com/bbq-pro/) - Pro version of Block Bad Queries
* [SES Pro](https://plugin-planet.com/ses-pro/) - Super-simple &amp; flexible email signup forms
* [USP Pro](https://plugin-planet.com/usp-pro/) - Pro version of User Submitted Posts

Links, tweets and likes also appreciated. Thanks! :)



== Changelog ==

**1.2 (2016/03/28)**

* Updates URL for BBB_HOME
* Tweaks display of "Blocked Bots" in plugin settings
* Tests on WordPress 4.5 beta

**1.1 (2016/02/22)**

* Adds "baidu" to the search engine whitelist
* Adds credit to documentation for header image

**1.0 (2016/02/22)**

* Initial release