Most analytics trust what a visitor says it is. Attack tools know that, so they call themselves Chrome, or Googlebot, or an AI crawler, and walk straight past. SM Bot Flagger checks what they actually do: a request for your cloud credentials is an attack, whatever name it gives.<\/p>\n\n
Each front-end request is written to its own table with:<\/p>\n\n
Nothing is written to postmeta, and there is one INSERT per request.<\/p>\n\n
Traffic is sorted into six buckets:<\/p>\n\n
Cache warming is the site requesting its own pages, so it is not a visit and it\nis not really a bot either. Keeping it separate stops preload runs from inflating\nthe traffic numbers. Filter the log to Caching to check a preload actually ran.<\/p>\n\n
Settings has a \"Do not log\" row where you can tick categories to discard. Those\nrequests are still classified, then dropped before anything is written, so they\ncost one pass over the rules and no database queries at all. This is worth doing\nfor Caching on a busy site, where a preload run can easily be the largest source\nof requests. Nothing is stored, so skipped traffic cannot be recovered later and\nwill not show up in the log, the charts or the API.<\/p>\n\n
A rule matches on one of three things: the user agent, the request path, or the\nIP address. User agent and path patterns match anywhere in the value, with *\nas a wildcard and an optional regular expression. Address patterns understand an\nexact address, a prefix such as 203.0.113, a wildcard such as 203.0.113.*, and\nCIDR ranges such as 203.0.113.0\/24 or 2001:db8::\/32. Prefixes only match on a\nboundary, so 192.168.1 will not match 192.168.10.4.<\/p>\n\n
This is how you handle a crawler that lies about its user agent, or a scraper\nrunning from one hosting range: match the address instead. It is also how you\nmark an internal monitoring path or a staging endpoint as something other than\nreal traffic.<\/p>\n\n
Rules live under SM Bot Flagger \u2192 Classification. Each rule matches a substring\nor a regular expression against the user agent, the path or the IP. They are\nevaluated top to bottom and the first match wins, so put narrow rules above broad\nones. You can edit, reorder, disable, delete and restore them.<\/p>\n\n
SM Bot Flagger processes personal data in the sense of the GDPR, because an IP\naddress is personal data. The defaults are chosen to keep as little as\npossible:<\/p>\n\n
The plugin adds suggested text to your site's privacy policy guide under\nSettings > Privacy > Policy Guide. Adapt it to your configuration. If you\nstore full addresses or keep entries longer, say so there, and check your\nlegal basis: for most sites that is a legitimate interest in security, which\nshould be recorded in your processing register.<\/p>\n\n
The optional MCP endpoint lets a tool you connect read the log. Whoever holds\na token can read the same data you can, so treat tokens as passwords and\nrevoke the ones you no longer use.<\/p>\n\n
Enable it under Settings, then create a token under MCP API.<\/p>\n\n
Endpoint: Tools:<\/p>\n\n Read tokens can only read. Give a token write access only if you want the client\nto change how traffic is categorised.<\/p>\n\n If Authorization never arrives, add this to .htaccess on Apache:<\/p>\n\n Extension points for add-ons:<\/p>\n\n rules editor, the charts, the filters and the MCP schemas automatically.\n sm_bot_flagger_classification (array) \u2014 override the category, label or rule for a\nrequest, after the rules have run.\n sm_bot_flagger_mcp_tools (array) \u2014 register MCP tools. Include a caches it, so an add-on can act on a crawler early rather than at shutdown.<\/p>\n\n array to drop it. Useful for adding a country lookup.\n sm_bot_flagger_mcp_tools (array) \u2014 add your own MCP tools. Give each one a handler named\n tool_ on a class of your choosing and hook A write-scoped MCP token can change classification rules, and those rules run on\nevery front-end request. Treat a write token as trusted, and hand out read\ntokens for anything that only needs to look at the numbers.<\/p>\n\n Pattern rules judge a request on what it looks like. Behaviour rules judge a\nclient on what it has been doing. They run at log time, because they need the\nresponse status and a short memory, and they need a stored IP address, so they\ndo nothing when IP storage is off. Confirmed search and AI crawlers are never\ndemoted by them.<\/p>\n\n Random paths. A 404 on a single path segment of 4 to 12 alphanumeric characters\nwith no vowels and mixed case, such as \/6bXX29bt, is treated as scanning. Real\nslugs contain vowels; generated tokens do not. The 404 is required, so a short\nconsonant heavy page of your own is never caught.<\/p>\n\n Repeated 404s. Flagged on both a count and a share: by default 8 misses within\n10 minutes, and at least half of that client's requests in the window missing.\nThe share is what makes this safe. A busy legitimate client can collect a\nhandful of 404s among hundreds of good requests, and counting alone would flag\nit. Scanners miss on almost everything they ask for.<\/p>\n\n Login attempts. A cumulative count of requests to wp-login.php and xmlrpc.php,\n10 per hour by default. Deliberately not a rate: credential stuffing is usually\nslow and spread over many addresses, so a per-second limit never sees it.<\/p>\n\n Request rate, off by default. On real traffic the fastest clients are usually\nlegitimate, while scanners and credential stuffing run slowly enough to pass any\nthreshold worth setting. Counting 404s separates the two far better than\ncounting requests. Measure your own traffic before switching this on.<\/p>\n\n Once a client trips a rule it stays flagged for an hour by default, and what it\nalready did in that window is recategorised too.<\/p>\n\n A user agent is a claim the client makes about itself. Anything can send\n\"OAI-SearchBot\" or \"Googlebot\", and plenty of attack tooling does, because it\ngets past naive filtering.<\/p>\n\n Settings has \"Trust the path\", on by default, which tests path and address rules\nbefore user agent rules. A request for \/root\/.aws\/credentials is then recorded\nas an attack whatever it claims to be, and your genuine crawler rules stay\ncorrect for genuine crawlers.<\/p>\n\n Turn it off if you would rather rules were evaluated strictly in the order shown\non the Classification screen.<\/p>\n\n Dashboard tiles toggle categories, and several can be combined. Rows in the top\nlists are links: click a page, landing page, status code, client or referring\ndomain to open the traffic log filtered to it.<\/p>\n\n The log itself filters on category, status family (2xx to 5xx), an exact status\ncode, a page path, landing pages only, and a free text search across path, user\nagent, referrer, IP and client. Combining a path with \"landing pages only\" gives\nyou the entry traffic for one page. Filters survive paging and are applied to\nCSV exports.<\/p>\n\n Open the Traffic log and click the client name on any row. You get the user\nagent as an editable pattern, a name, and a category. Shorten the pattern to the\ndistinctive part before saving, for example Saving puts the rule first in the evaluation order, so it beats the shipped\ndefaults. Tick the box to also rewrite requests that are already in the log,\nwhich is matched on the user agent containing your pattern.<\/p>\n\n The chart above the table follows the filters, and can be grouped by category,\nby client or by the raw user agent. The eight busiest values get their own band\nand the rest are folded into \"Everything else\". \"Show full user agent\" prints\nthe whole string under each client name.<\/p>\n\n\n Logging happens at the very end of each request, as one database write.\nBehaviour rules only keep counters for clients that have already requested a\nmissing page.<\/p><\/dd>\n Pages served straight from a cache never reach WordPress, so they are not\nlogged. On a heavily cached site, read the numbers as a floor rather than a\ntotal. Your cache plugin's own warming requests are recognised and kept out\nof your visitor numbers.<\/p><\/dd>\n It is built to keep as little as possible: masked addresses, a visitor hash\nthat changes daily, secrets removed from URLs, administrators excluded, and\n90-day retention. See the Privacy section. Compliance also depends on how you\nrun your site: adapt the suggested privacy policy text, and record your legal\nbasis.<\/p><\/dd>\n No. There is no tracking script, no external service and no call home. The\nplugin author never sees your traffic.<\/p><\/dd>\n A small server inside WordPress that lets an AI assistant or any MCP client\nread the traffic log and ask questions in plain language. It is off by\ndefault, needs a token you create, and read-only tokens cannot change\nanything.<\/p><\/dd>\n Yes. Click a client in the traffic log, choose the category, and optionally\nmatch on the path or address instead of the user agent. Past requests are\ncorrected too.<\/p><\/dd>\n Yes. The Pro add-on adds verified crawlers, so a fake Googlebot is caught by\nDNS rather than by name; blocking by category, behaviour or address, with a\nmonitor mode; and priority support. See https:\/\/seomarketeer.eu.<\/p><\/dd>\n In this plugin's support forum on WordPress.org, or through\nhttps:\/\/seomarketeer.eu.<\/p><\/dd>\n\n<\/dl>\n\n\nhttps:\/\/your-site.tld\/wp-json\/sm-bot-flagger\/v1\/mcp<\/code>\nTransport: streamable HTTP, JSON-RPC 2.0 over POST\nAuth: Authorization: Bearer <token><\/code>, or X-MCP-Token: <token><\/code> if a proxy\nstrips the Authorization header<\/p>\n\n\n
get_traffic_summary<\/code> \u2014 totals and the category split for a period<\/li>\nget_timeseries<\/code> \u2014 hourly or daily counts per category<\/li>\nget_top<\/code> \u2014 ranks pages, landing pages, referrers, referring domains, user\nagents, clients, categories, status codes, IPs, rules or hour of day<\/li>\nsearch_hits<\/code> \u2014 individual requests, with filters<\/li>\nclassify_user_agent<\/code> \u2014 test a user agent against the current rules<\/li>\nlist_classification_rules<\/code> \u2014 the rules in evaluation order<\/li>\nupsert_classification_rule<\/code> \u2014 add or change a rule, write token only<\/li>\ndelete_classification_rule<\/code> \u2014 remove a rule, write token only<\/li>\n<\/ul>\n\nSetEnvIf Authorization \"(.*)\" HTTP_AUTHORIZATION=$1\n<\/code><\/pre>\n\nHooks<\/h4>\n\n
sm_bot_flagger_categories (array) \u2014 add your own traffic categories. They appear in the\n<\/code><\/pre>\n\ncallback<\/code> key and the\nfree plugin will dispatch to it.\n sm_bot_flagger_stats_where (array) \u2014 append conditions to every stats query.\n sm_bot_flagger_admin_menu (action) \u2014 add a submenu page under SM Bot Flagger.\n sm_bot_flagger_dashboard_cards \/ sm_bot_flagger_dashboard_panels<\/code> (actions) \u2014 add to the dashboard.\n sm_bot_flagger_log_columns (array) and sm_bot_flagger_log_column<\/code> (action) \u2014 add columns to the log.\n sm_bot_flagger_settings_fields (action) and sm_bot_flagger_sanitize_settings<\/code> (array) \u2014 add settings.<\/p>\n\nSM_Bot_Flagger_Logger::current_classification() classifies the current request once and\n<\/code><\/pre>\n\nsm_bot_flagger_should_log (bool) \u2014 return false to skip logging a request.\nsm_bot_flagger_hit_data (array) \u2014 change the row before it is written, or return an empty\n<\/code><\/pre>\n\ntools\/call<\/code> accordingly.<\/p>\n\nNotes on accuracy<\/h4>\n\n
\n
shutdown<\/code>, so requests served entirely from a page cache\nor a CDN never reach PHP and are not counted. On a cached site, treat these\nnumbers as a lower bound.<\/li>\nSecurity notes<\/h4>\n\n
\n
Behaviour rules<\/h4>\n\n
Path precedence<\/h4>\n\n
Filtering<\/h4>\n\n
Correcting a classification<\/h4>\n\n
MyScraper\/2.<\/code> rather than the whole\nstring, so the rule catches other versions too.<\/p>\n\n\n
\n
Will it slow my site down?<\/h3><\/dt>\n
Does it work with page caching?<\/h3><\/dt>\n
Is it GDPR compliant?<\/h3><\/dt>\n
Does any data leave my server?<\/h3><\/dt>\n
What is the MCP endpoint?<\/h3><\/dt>\n
Can I correct a classification?<\/h3><\/dt>\n
Is there a paid version?<\/h3><\/dt>\n
Where do I get help?<\/h3><\/dt>\n
1.0.0<\/h4>\n\n
\n