PSB Bot Traffic Controller sits in front of your WordPress site and classifies incoming traffic into five bot categories:<\/p>\n\n
Each category can be configured independently to block (HTTP 403), rate-limit (HTTP 429 once a configurable per-hour threshold is exceeded), or allow traffic. A global safety-net cap also applies to all detected bot traffic regardless of per-category policy.<\/p>\n\n
Detection runs via a free, zero-dependency regex\/User-Agent pattern engine, curated from third-party bot-pattern data (see Credits below).<\/p>\n\n
For performance, bot interception runs as early as possible via a small mu-plugin installed automatically into The bundled bot-pattern data ( No code from these projects is bundled \u2014 only pattern\/name\/category data, transformed at build time ( This plugin makes no outbound HTTP requests and does not integrate with any third-party or external service. Earlier versions of the bundled pattern data included a per-signature No \u2014 PSB Bot Traffic Controller runs inside WordPress (or, for the mu-plugin path, as early in WordPress's own bootstrap as possible) and cannot intercept traffic before it reaches your web server. It complements, rather than replaces, edge-level protection.<\/p><\/dd>\n An admin notice is shown with the filesystem error. The plugin still activates, but early interception won't run until the mu-plugin is successfully installed (retry by deactivating\/reactivating, or check file permissions on Add wp-content\/mu-plugins\/<\/code> \u2014 this avoids the cost of a full WordPress bootstrap for traffic that ends up being blocked.<\/p>\n\nCredits<\/h3>\n\n
includes\/detection\/regex\/data\/bot-patterns.php<\/code>) is built from three third-party sources, each under a GPL-compatible license:<\/p>\n\n\n
tools\/cmd\/build-patterns<\/code>) into this plugin's own runtime format.<\/p>\n\nproducer<\/code> field (an attribution URL crediting the upstream source of each entry); it has been removed entirely, since it was never fetched or otherwise dereferenced by the plugin at runtime.<\/p>\n\n\n\n
wp-content\/plugins\/psb-bot-traffic-controller\/<\/code>.<\/li>\nwp-content\/mu-plugins\/<\/code> (WordPress's \"must-use plugin\" mechanism) that performs early bot interception.<\/li>\n\n
Does this replace a WAF or CDN-level bot protection?<\/h3><\/dt>\n
What happens if the mu-plugin file can't be written on activation?<\/h3><\/dt>\n
wp-content\/mu-plugins\/<\/code>).<\/p><\/dd>\nHow do I reset rate-limit counters while testing?<\/h3><\/dt>\n
define( 'PSB_BTC_DEBUG', true );<\/code> to wp-config.php<\/code> on a staging\/test site. This enables a rotating-token reset URL shown on the Dashboard (valid for a few hours at a time, then automatically expires). It is disabled by default and should never be enabled on a production site.<\/p><\/dd>\n\n<\/dl>\n\n\n1.0.4<\/h4>\n\n
\n
User-agent<\/code>\/Disallow: \/<\/code> block in\nrobots.txt, sourced from the same curated bot-name data the detector already uses. Default\nmode is dynamic (WordPress's robots_txt<\/code> filter, nothing written to disk); an advanced,\nopt-in setting writes a physical robots.txt file instead, with a persistent warning (Settings\npage and Dashboard) whenever a physical file exists on disk, since it always takes precedence\nover the dynamic filter regardless of which mode is configured.<\/li>\n\\n<\/code> does not get\ncollapsed into a space. Fixed by joining each paragraph onto one logical line. Docs-only, no\ncode changes.<\/li>\nrobots_txt<\/code> filter\nis designed for multiple plugins to extend the same output, so this doesn't change behavior by\ndefault, it just surfaces the interaction. Our filter callback also now registers at a later\npriority to reduce the chance of being silently overwritten by another plugin's callback.<\/li>\n1.0.3<\/h4>\n\n
\n
CLAUDE.md<\/code>'s architecture\nnotes: WURFL.js is planned, not implemented). Docs-only correction, no code changes.<\/li>\n1.0.2<\/h4>\n\n
\n
phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared<\/code> annotations to the\nthree interpolated-table-name queries in class-ratelimit-store-db.php<\/code>\n(increment_and_get()<\/code>, get_count()<\/code>, cleanup_expired()<\/code>) \u2014 this file had none, unlike its\nsibling class-ratelimit-reset.php<\/code>, despite sharing the identical unfixable-by-design\npattern (table names can never be %s<\/code>\/%d<\/code> $wpdb->prepare()<\/code> placeholders).<\/li>\nclass-ratelimit-reset.php<\/code>'s existing phpcs:ignore<\/code> comment on its\n TRUNCATE TABLE query: it previously named the sniff WordPress.DB.PreparedSQL.NotPrepared<\/code>,\nwhich is not what actually fires there \u2014 fixed to name\n WordPress.DB.PreparedSQL.InterpolatedNotPrepared,PluginCheck.Security.DirectDB.UnescapedDBParameter,\nmatching what the checker actually reports, so the comment provides real suppression instead\nof none.<\/li>\n<\/ul>\n\n1.0.1<\/h4>\n\n
\n
psb_btc_mu_respond()<\/code>'s output (strip control characters before echoing) rather\nthan relying on every current call site happening to pass a hardcoded literal \u2014 all 3 call\nsites still do today, so this closes a latent gap rather than fixing a live exploit, but\nescaping at the point of output shouldn't depend on that staying true as the file is edited.<\/li>\nSUBMISSION.md<\/code> (non-atomic-counter flock()<\/code> locking has no WP_Filesystem<\/code>\nequivalent and must run pre-bootstrap; $wpdb->prepare()<\/code> placeholders the checker's static\nanalysis can't trace through) \u2014 nothing else new to fix.<\/li>\n<\/ul>\n\n1.0.0<\/h4>\n\n
\n
Botpolice_*<\/code> \u2192 PSB_BTC_*<\/code>,\n botpolice_* \u2192 psb_btc_*<\/code>, BOTPOLICE_*<\/code> \u2192 PSB_BTC_*<\/code>).<\/li>\nproducer<\/code> attribution field from the bundled bot-pattern data\n(includes\/detection\/regex\/data\/bot-patterns.php<\/code>) \u2014 it held a URL in most entries and\nwas flagged twice by review under two headings (\"calling files remotely\" and\n\"undocumented use of a 3rd party\/external service\"), even though it was never\ndereferenced as a URL anywhere in the runtime code. Removed entirely rather than\ndisclosed, since the plugin makes no outbound HTTP requests and integrates with no\nexternal service.<\/li>\npsb-btc-config-cache.json<\/code>,\nread via json_decode()<\/code>), per a review finding against writing executable code\nfiles into wp-content\/mu-plugins\/<\/code> outside the small set of core-defined drop-in\nexceptions. The mu-plugin bootstrap file itself and the (much larger) pattern-data\ncache were not affected \u2014 review did not flag either of those.<\/li>\nwp_cache_incr()<\/code> (atomic at the cache backend); the mu-plugin's\nflat-file counters now use flock()<\/code>-based exclusive locking around the\nread-modify-write.<\/li>\nif ( ! defined('ABSPATH') && ! defined('...STANDALONE') )<\/code>\ndirect-access guard (used to allow PHPUnit to load classes without a full WP\ninstall) with the literal bare if ( ! defined( 'ABSPATH' ) ) { exit; }<\/code> review\nexpects, across all affected files. Test-only standalone loading now works by\nhaving the PHPUnit bootstrap itself define ABSPATH<\/code>, rather than each production\nfile special-casing a second constant.<\/li>\n<\/ul>\n\n0.4.1<\/h4>\n\n
\n
class-mu-installer.php<\/code>'s version-stamp read and\n class-ratelimit-reset.php's counter-file cleanup off raw file-handle\/unlink()<\/code> calls,\ndocument the intentional nonce-free design of the (opt-in, off-by-default) debug reset\nendpoint, add a direct-access guard to the generated bot-patterns.php<\/code> (via\n tools\/cmd\/build-patterns, not by hand-editing the output), and correct \"Tested up to\"\nto the current WordPress release. See SUBMISSION.md<\/code> for a list of remaining Plugin\nCheck findings that are intentional design choices rather than defects (the\n BOTPOLICE_STANDALONE direct-access guard variant, the mu-plugin's necessarily-early\nfilesystem calls, and the reset endpoint's token-based-not-nonce-based auth).<\/li>\n<\/ul>\n\n0.4.0<\/h4>\n\n
\n
?botpolice_reset=<token><\/code>) is no longer loaded or\nregistered by default \u2014 it now requires define( 'BOTPOLICE_DEBUG', true );<\/code> in\n wp-config.php to become reachable at all, rather than being an unauthenticated endpoint\npresent on every install. uninstall.php<\/code> also now removes its secret option, if present.<\/li>\n0.3.2<\/h4>\n\n
\n
?botpolice_reset=<token><\/code>, shown on the\nDashboard for manual testing) was a single fixed value stored in wp_options<\/code> \u2014\nonce leaked (screenshot, shared log, browser history), it stayed valid forever.\nIt now rotates automatically every 4 hours: the displayed\/accepted token is an\nHMAC-SHA256 of a persistent random secret (never displayed) and the current\n4-hour time window, so a leaked token expires on its own without any manual\nrotation step, and reading the plugin's source alone is not enough to compute a\nvalid token (the algorithm is public; the secret it's keyed on is not). The\nDashboard now also shows how many minutes remain before the current URL expires.<\/li>\n<\/ul>\n\n0.3.1<\/h4>\n\n
\n
assets\/images\/logo.png<\/code>, shipped in the plugin zip) and WordPress.org-listing icon\nand banner assets (.wordpress-org\/<\/code>, not bundled into the plugin zip per WP.org\nconvention \u2014 those live in the SVN assets\/ directory of the plugin listing, separate\nfrom trunk\/).<\/li>\n<\/ul>\n\n0.3.0<\/h4>\n\n
\n
REMOTE_ADDR<\/code>), which is the reverse proxy's\/load balancer's own IP on any site\nrunning behind one (Cloudflare, nginx, AWS ALB\/ELB) \u2014 collapsing every distinct\nvisitor onto one shared rate-limit bucket. Added Botpolice_Client_Ip<\/code>\n(includes\/detection\/class-client-ip.php<\/code>, documented in CLIENT_IP.md<\/code>), which\nresolves the real public client IP by walking the Forwarded<\/code> (RFC 7239) and\n X-Forwarded-For headers before falling back to the raw peer address, and only\never returns an internet-routable address for rate-limiting purposes. Wired into\nboth enforcement layers: Botpolice_Request_Context<\/code> (full-WP path) and a\nduplicated botpolice_mu_client_ip()<\/code> in the self-contained mu-plugin hot path.<\/li>\n<\/ul>\n\n0.2.1<\/h4>\n\n
\n
Botpolice_Upgrade_Handler<\/code>, which resyncs\nthe mu-plugin on upgrader_process_complete<\/code> and via a cheap staleness check on every\nadmin page load, covering upgrade paths that bypass WordPress's upgrader (e.g. manual FTP\nreplacement) as well.<\/li>\n<\/ul>\n\n0.2.0<\/h4>\n\n
\n
Botpolice_Activity_Recorder<\/code> and the\nmu-plugin's own inline counter), surfaced on the dashboard's Recent Activity view.<\/li>\n?botpolice_reset=<token><\/code>) to clear rate-limit counters\nfor iterative live-site testing without waiting out hourly buckets.<\/li>\ntests\/live\/test-live-site.sh<\/code>,\n make test-live) verifying block\/limit\/allow enforcement against a real deployed site.<\/li>\n<\/ul>\n\n0.1.1<\/h4>\n\n
\n
function_exists()<\/code>\nguards) but called from a closure defined before those declarations executed \u2014 PHP only\nhoists unconditional top-level function declarations, so any request matching a bot pattern\nhit a fatal \"call to undefined function\" error, blocking all traffic on the plugin's\nhighest-risk hot path. Passed a plain php -l<\/code> lint check without complaint. Caught by a new\nsubprocess-based regression suite (tests\/php\/mu-bootstrap\/<\/code>), since PHPUnit cannot safely\nintercept exit()<\/code>-calling code in-process.<\/li>\n<\/ul>\n\n0.1.0<\/h4>\n\n
\n