=== Lubber – The Silent Bad Bot Blocker ===
Contributors: techpot
Tags: security, bot protection, spam, analytics, firewall
Requires at least: 6.2
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 1.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Silently intercepts scraper and bot traffic before WordPress finishes loading, keeping your Analytics and Ads numbers clean.

== Description ==

Most WordPress security plugins block bad traffic with a `403 Forbidden` page. That tells the bot operator "you've been caught" - so they change their fingerprint and come right back, and in the meantime a `403` still costs your server a full page load.

Lubber takes a different approach, adapted from a real six-figure-request bot-traffic investigation: matching requests get a normal `200 OK` response with a tiny, harmless-looking static page instead - no error, no signal for the bot to react to, and no database query or theme render for your server to pay for. Because the decoy page never loads Google Analytics, AdSense, or any tracking script, bot hits also stop polluting your traffic reports and ad impressions.

= What it does =

* **Named-crawler blocklist** - always blocks specific bots you list by name (SEO crawlers, AI scrapers, etc.), regardless of referrer.
* **No-referrer detection**, in three independently adjustable strengths - from a narrow "missing trailing slash" pattern up to a broad "any request with no referrer" rule for sites that know their traffic is overwhelmingly search-driven.
* **Built-in protection for real crawlers** - Google, Bing, and Apple's crawlers are recognized two independent ways (by name *and* by their official published IP ranges) so a bot can never bypass detection just by copying a real crawler's name.
* **Exclusions for genuine visitors** - Android traffic, AI-assistant referrals (ChatGPT/Perplexity/Claude/Gemini, which often strip the referrer for real human clicks), your own IP addresses, logged-in sessions, and WP-CLI are never touched.
* **An activity log** right in your dashboard - see what got blocked, by which rule, without needing server/SSH access.
* **Everything is a toggle.** No PHP editing required to enable, disable, or tune any rule.

= Performance =

The plugin hooks as early as a normal plugin can (`plugins_loaded`, priority 0) so a blocked request exits before the main query, before your theme, and before most other plugins run. An optional, off-by-default "Early Loading Mode" goes further, intercepting before WordPress core itself finishes loading, for sites that want the absolute lowest possible cost per blocked request.

= Privacy =

This plugin never sends any data anywhere, and by default it never makes any outbound network request at all. Everything - the block rules, the IP allowlist, the activity log - stays in your own database, and the bundled Google/Bing/Apple crawler IP ranges are used as-is out of the box. If you explicitly turn on "Auto-update crawler IP ranges" in the Advanced tab, the plugin makes up to three outbound requests per day - one each to Google, Bing, and Apple's own published IP range lists - to keep those ranges current; no data about your site or its visitors is included in any of those requests. The Advanced tab also shows exactly which ranges are currently active and whether they're the bundled defaults or a fetched copy.

== External services ==

This plugin connects to Google, Bing, and Apple to download their official
crawler/bot IP address ranges, used to build a verified allowlist so
legitimate search engine crawlers are never blocked by mistake. This is
opt-in and off by default ("Auto-update crawler IP ranges" in the Advanced
tab); when enabled, it runs on a daily schedule.

No user or visitor data is sent to these services - each is a one-way
download of a public IP range file, not a data submission.

* Google: fetches https://www.gstatic.com/ipranges/goog.json
  Terms: https://policies.google.com/terms - Privacy: https://policies.google.com/privacy
* Bing: fetches https://www.bing.com/toolbox/bingbot.json
  Terms: https://www.microsoft.com/en-us/servicesagreement - Privacy: https://privacy.microsoft.com/en-us/privacystatement
* Apple: fetches https://search.developer.apple.com/applebot.json
  Terms: https://www.apple.com/legal/internet-services/terms/site.html - Privacy: https://www.apple.com/legal/privacy/en-ww/

== Installation ==

1. Upload the plugin files to `/wp-content/plugins/lubber`, or install directly from the Plugins screen in your dashboard.
2. Activate the plugin.
3. Go to **Settings → Lubber** to review the default rules, add your own IP address to the allowlist, and turn on any additional rules you want.

== Frequently Asked Questions ==

= Will this block Google or Bing? =

No. Real Google, Bing, and Apple crawlers are checked two independent ways before any rule can apply - by their User-Agent and by their official, published IP ranges - so a configuration mistake in one layer can't expose the other.

= Will this block real visitors who don't send a referrer? =

The two rules enabled by default (named-crawler blocklist and missing-trailing-slash detection) are deliberately narrow and low-risk. The broader "any no-referrer request" rule is off by default and clearly labeled as aggressive - only enable it once you've confirmed most of your real traffic arrives via search engines or another referrer.

= Does this replace a full security plugin? =

No. This plugin does one thing - detect and quietly decoy bot/scraper traffic before it costs you server resources or pollutes your analytics. It is not a firewall, malware scanner, or login-hardening tool.

= Where is blocked traffic logged? =

In a dedicated database table, viewable under Settings → Lubber → Activity Log. Nothing is written to server log files, and old entries are pruned automatically based on your configured retention period.

== Screenshots ==

1. Rules tab - toggle each detection module independently.
2. Activity Log tab - see what's been blocked without SSH access.

== Changelog ==

= 1.0.0 =
* Initial release.

== Upgrade Notice ==

= 1.0.0 =
Initial release.
