Document WordPress AI Bot Management

Add end-user and admin documentation for the WordPress-plugin AI Bot
Management feature (pre-WordPress bot classification and per-category
rate limiting):

- wordpress_plugin: new "AI Bot Management" section — how it works, bot
  categories, the Balanced/Strict/Monitor presets, the dashboard-widget
  row and detail pane (with screenshots), and the wp-config controls;
  add a version note. Also move the WAF version note out of Prerequisites
  into the WAF section's own opening note.
- config_file_description: document ai_bot_protection and
  ai_bot_protection_preset in the WORDPRESS section; move the stranded
  "Active Response" block up next to its active_response row.
- command_line_interface: add an AI Bot Management subsection with
  config-update examples (server-wide and per-account).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: Martin Krcho

docs/.vuepress/public/images/wordpress-plugin/bot-widget-pane.png

@@ -2822,3 +2822,40 @@ imunify360-agent wordpress-plugin rules list-disabled
 
 </div>
 
+### AI Bot Management
+
+<span class="notranslate">AI Bot Management</span> (bot classification and per-category rate limiting) is controlled through configuration keys rather than a dedicated subcommand. The plugin must be installed first (see <span class="notranslate">`security_plugin_enabled`</span>). Site owners can also manage it from the WordPress dashboard — see <span class="notranslate">[AI Bot Management](/wordpress_plugin/#ai-bot-management)</span>.
+
+Enable or disable it server-wide:
+
+<div class="notranslate">
+
+```
+imunify360-agent config update '{"WORDPRESS":{"ai_bot_protection": true}}'
+imunify360-agent config update '{"WORDPRESS":{"ai_bot_protection": false}}'
+```
+
+</div>
+
+Enable it for a single hosting account:
+
+<div class="notranslate">
+
+```
+imunify360-agent config update --user user1 '{"WORDPRESS":{"ai_bot_protection": true}}'
+```
+
+</div>
+
+Set the default preset applied to sites that have not chosen their own — one of <span class="notranslate">`balanced`</span>, <span class="notranslate">`strict`</span>, or <span class="notranslate">`monitor`</span>:
+
+<div class="notranslate">
+
+```
+imunify360-agent config update '{"WORDPRESS":{"ai_bot_protection_preset": "strict"}}'
+```
+
+</div>
+
+A site owner can override the server default from the WordPress dashboard, and a <span class="notranslate">`define()`</span> in <span class="notranslate">`wp-config.php`</span> overrides both.
+

docs/.vuepress/public/images/wordpress-plugin/bot-widget.png

@@ -373,6 +373,33 @@ If a non-eligible interval is configured, the agent will ignore it and keep the
 <tr><th colspan="2" align="left"><span class="notranslate">OSSEC:</span></th></tr>
 <tr><td><span class="notranslate">active_response: False</span></td>
 <td># block (<span class="notranslate">True</span>) access to a specific server port being attacked. The ports include FTP (21), SSH (any port) and SMTP (25, 465, 587). The default value is <span class="notranslate">False</span>.</td></tr>
+<tr>
+<td colspan="2">
+
+<span class="notranslate">Active Response</span> is an ossec-driven (IDS) feature of Imunify360 which has been re-engineered to make it capable of blocking access to a specific server port being attacked.
+
+The purpose of the feature is significantly reducing false positive rate while increasing its capabilities to detect and block aggressive brute force requests.
+
+In order to activate <span class="notranslate">Active Response, </span>the following lines should be added into <span class="notranslate">_/etc/sysconfig/imunify360/imunify360.config_</span>:
+<div class="notranslate">
+
+```
+OSSEC:
+  active_response: True
+```
+
+</div>
+and then restart Imunify360 service:
+<div class="notranslate">
+
+```
+systemctl restart imunify360
+```
+
+</div>
+
+</td>
+</tr>
 <tr><th colspan="2" align="left"><span class="notranslate">ADMIN_CONTACTS:</span></th></tr>
 <tr><td><span class="notranslate">emails: youremail@email.com</span></td>
 <td># your email to receive reports about critical issues, security alerts or system misconfigurations detected on your servers.</td></tr>
@@ -422,36 +449,18 @@ If a non-eligible interval is configured, the agent will ignore it and keep the
 <td># enable (<span class="notranslate">True</span>) the Malware Database Scanner - a database antivirus with automated malware detection and clean-up of web applications. Requires MariaDB/MySQL DB management system version 5.5. Recommended version is 5.6+. Note, that only WordPress, Joomla, and Magento databases are supported now.</td></tr>
 <tr><th colspan="2" align="left"><span class="notranslate">WORDPRESS:</span></th></tr>
 <tr><td><span class="notranslate">security_plugin_enabled: False</span></td>
-<td># installs the <span class="notranslate">Imunify Security</span> WordPress plugin on all WordPress sites. This is the master switch for the WordPress plugin and its WordPress WAF. Default is <span class="notranslate">False</span>.</td></tr>
+<td># installs the <span class="notranslate">Imunify Security</span> WordPress plugin on all WordPress sites. This is the master switch for the WordPress plugin, its WordPress WAF, and AI Bot Management. Default is <span class="notranslate">False</span>.</td></tr>
 <tr><td><span class="notranslate">waf_enabled: True</span></td>
 <td># enables the WordPress WAF (virtual patching) for WordPress sites on the server. When set to <span class="notranslate">False</span>, WAF rules are removed from all sites. Can also be set per hosting account. Default is <span class="notranslate">True</span>.</td></tr>
 <tr><td><span class="notranslate">waf_default: False</span></td>
 <td># whether the WordPress WAF is enabled automatically for newly created hosting accounts. Default is <span class="notranslate">False</span>.</td></tr>
+<tr><td><span class="notranslate">ai_bot_protection: False</span></td>
+<td># enables AI Bot Management (bot classification and per-category rate limiting) for WordPress sites on the server. Can also be set per hosting account; a site owner may override it from the WordPress dashboard. Default is <span class="notranslate">False</span>.</td></tr>
+<tr><td><span class="notranslate">ai_bot_protection_preset: balanced</span></td>
+<td># the default AI Bot Management preset applied to sites that have not chosen their own. One of <span class="notranslate">balanced</span>, <span class="notranslate">strict</span>, or <span class="notranslate">monitor</span>. Default is <span class="notranslate">balanced</span>.</td></tr>
 </tbody>
 </table>
 
-<span class="notranslate">Active Response</span> is an ossec-driven (IDS) feature of Imunify360 which has been re-engineered to make it capable of blocking access to a specific server port being attacked.
-
-The purpose of the feature is significantly reducing false positive rate while increasing its capabilities to detect and block aggressive brute force requests.
-
-In order to activate <span class="notranslate">Active Response, </span>the following lines should be added into <span class="notranslate">_/etc/sysconfig/imunify360/imunify360.config_</span>:
-<div class="notranslate">
-
-```
-OSSEC:
-  active_response: True
-```
-
-</div>
-and then restart Imunify360 service:
-<div class="notranslate">
-
-```
-systemctl restart imunify360
-```
-
-</div>
-
 #### How to apply changes from CLI
 
 In order to apply changes via command-line interface (CLI), you can use the following command:

docs/command_line_interface/README.md

@@ -13,10 +13,6 @@ The **Imunify Security plugin for WordPress** is available to all Imunify custom
 * **Imunify360**: 8.4.1 or higher
 * **ImunifyAV/AV+**: 8.6.0 or higher
 
-::: tip Note
-The <span class="notranslate">Web Application Firewall</span> (virtual patching) described below requires the <span class="notranslate">Imunify Security</span> WordPress plugin (<span class="notranslate">`imunify-wp-security`</span>) <span class="notranslate">`wp-3.0.1-2`</span> or later, together with a supported Imunify agent — <span class="notranslate">ImunifyAV/AV+</span> (<span class="notranslate">`imunify-antivirus`</span>) <span class="notranslate">`av-8.7.1-2`</span> or later, or <span class="notranslate">Imunify360</span> (<span class="notranslate">`imunify360-firewall`</span>) <span class="notranslate">`8.12.5-3`</span> or later.
-:::
-
 ## Installation
 
 The plugin is not available in the WordPress plugin repository. To install:
@@ -40,6 +36,7 @@ The plugin adds a dashboard widget that helps administrators keep track of their
 - Real-time security status
 - Proactive Defense status
 - Web Application Firewall status and recent WAF incidents (see <span class="notranslate">[Web Application Firewall](/wordpress_plugin/#web-application-firewall-virtual-patching)</span>)
+- Bot Protection status and recent bot activity (see <span class="notranslate">[AI Bot Management](/wordpress_plugin/#ai-bot-management)</span>)
 - Timestamps for last and next scheduled scans
 - Detailed list of detected and cleaned malware (file path, signature, detection or clean-up time)
 
@@ -88,6 +85,8 @@ ImunifyAV users are shown a limited interface and prompted to upgrade to Imunify
 The <span class="notranslate">Imunify Security</span> plugin includes a **Web Application Firewall (WAF)** that provides *virtual patching* for WordPress. It protects your sites against known vulnerabilities (CVEs) in WordPress plugins, themes, and core — **without modifying any of your site's files**. When a plugin or theme you use has a known security flaw, the WAF blocks attempts to exploit it, giving you time to apply the real update.
 
 ::: tip Note
+The <span class="notranslate">Web Application Firewall</span> (virtual patching) described below requires the <span class="notranslate">Imunify Security</span> WordPress plugin (<span class="notranslate">`imunify-wp-security`</span>) <span class="notranslate">`wp-3.0.1-2`</span> or later, together with a supported Imunify agent — <span class="notranslate">ImunifyAV/AV+</span> (<span class="notranslate">`imunify-antivirus`</span>) <span class="notranslate">`av-8.7.1-2`</span> or later, or <span class="notranslate">Imunify360</span> (<span class="notranslate">`imunify360-firewall`</span>) <span class="notranslate">`8.12.5-3`</span> or later.
+
 This WordPress WAF is a separate layer from the server-side <span class="notranslate">[WAF (ModSecurity)](/dashboard/#waf-settings)</span> and from <span class="notranslate">[WordPress Account Brute-force Protection](/dashboard/#wordpress-account-brute-force-protection)</span>. It runs inside the WordPress plugin and focuses on blocking exploit attempts against vulnerable plugins and themes. In the Imunify control panel it is presented on the <span class="notranslate">_CMS WAF_</span> tab.
 :::
 
@@ -188,3 +187,93 @@ The WordPress WAF requires the <span class="notranslate">Imunify Security</span>
 
 * **Server administrators** enable or disable the WAF server-wide, and can choose whether it is on by default for new hosting accounts. See <span class="notranslate">[WordPress plugin settings](/dashboard/#wordpress-plugin)</span> and the <span class="notranslate">[command-line reference](/command_line_interface/#wordpress-plugin)</span>.
 * **Hosting-account owners** can turn the WAF off for their own account, unless the administrator has locked it server-wide (shown as *This value is set by server administrator*).
+
+## AI Bot Management
+
+<span class="notranslate">Imunify Security</span> includes **AI Bot Management** — a layer that identifies automated traffic (search-engine crawlers, AI/LLM crawlers, scrapers, and malicious bots) *before WordPress finishes loading* and applies a per-minute request limit to each kind of bot, while leaving real visitors untouched. It protects sites from aggressive crawling and bot-driven resource abuse — increasingly from the wave of AI training and scraping crawlers — without slowing down legitimate users.
+
+::: tip Note
+AI Bot Management requires the <span class="notranslate">Imunify Security</span> WordPress plugin (<span class="notranslate">`imunify-wp-security`</span>) <span class="notranslate">`wp-4.0.2-2`</span> or later, together with a supported Imunify agent — <span class="notranslate">ImunifyAV/AV+</span> (<span class="notranslate">`imunify-antivirus`</span>) <span class="notranslate">`av-8.8.3-6`</span> or later, or <span class="notranslate">Imunify360</span> (<span class="notranslate">`imunify360-firewall`</span>) <span class="notranslate">`8.13.6-6`</span> or later. It is a separate layer from the server-side <span class="notranslate">[WAF (ModSecurity)](/dashboard/#waf-settings)</span>, from <span class="notranslate">[WordPress Account Brute-force Protection](/dashboard/#wordpress-account-brute-force-protection)</span>, and from the plugin's own <span class="notranslate">[Web Application Firewall](#web-application-firewall-virtual-patching)</span>. In the WordPress dashboard it appears as <span class="notranslate">_Bot Protection_</span>.
+:::
+
+### How it works
+
+The feature runs as a *must-use* plugin, so it evaluates each request before the rest of WordPress (and other plugins) load. For every request it:
+
+1. **Classifies** the visitor into one category — a verified search engine, a verified AI crawler, an unknown automated client, an unverified bot, a malicious bot, or a human. Clients that claim to be a known crawler (for example, Googlebot) are confirmed by *forward-confirmed reverse DNS*, so a spoofed user-agent does not earn a crawler's higher limit.
+2. **Applies the category's limit.** Each non-human category has a requests-per-minute allowance set by the active preset. Requests over the limit are refused with <span class="notranslate">HTTP 429 (Too Many Requests)</span> and a <span class="notranslate">`Retry-After`</span> hint; malicious bots are blocked outright with <span class="notranslate">HTTP 403 (Forbidden)</span>. Clients that keep exceeding their limit can be escalated to a temporary block.
+
+Human visitors are never rate-limited. The check is *fail-open*: if anything goes wrong (for example, the backing storage is unavailable), the request is allowed through, so the feature can never take a site down.
+
+### Bot categories
+
+| Category | What it is |
+|---|---|
+| <span class="notranslate">_Verified search engines_</span> | Crawlers confirmed by reverse DNS to belong to a search engine (Google, Bing, and similar). Given a high allowance so indexing is never disrupted. |
+| <span class="notranslate">_Verified AI crawlers_</span> | Confirmed crawlers from AI/LLM providers (training or retrieval). |
+| <span class="notranslate">_Unknown automated_</span> | Automated clients that do not match a known, verified crawler. |
+| <span class="notranslate">_Unverified bots_</span> | Clients claiming to be a known bot but failing reverse-DNS verification. |
+| <span class="notranslate">_Malicious bots_</span> | Known-bad clients, and clients caught by the honeypot. Blocked in every preset except <span class="notranslate">_Monitor only_</span>. |
+| <span class="notranslate">_Humans_</span> | Regular visitors. Never rate-limited. |
+
+### Protection presets
+
+The active **preset** decides the per-minute limits. <span class="notranslate">_Balanced_</span> is the default.
+
+| Category (requests / minute) | <span class="notranslate">_Balanced_</span> | <span class="notranslate">_Strict_</span> | <span class="notranslate">_Monitor only_</span> |
+|---|---|---|---|
+| Verified search engines | 300 | 300 | Not enforced |
+| Verified AI crawlers | 10 | 3 | Not enforced |
+| Unknown automated | 5 | 2 | Not enforced |
+| Unverified bots | 2 | 1 | Not enforced |
+| Malicious bots | Blocked | Blocked | Not enforced |
+
+* <span class="notranslate">_Balanced_</span> — sensible limits for a typical site. Recommended for most sites.
+* <span class="notranslate">_Strict_</span> — tighter limits for sites under heavy bot pressure.
+* <span class="notranslate">_Monitor only_</span> — classifies traffic but does not block or limit anything. Useful for trying the feature out before enforcing it.
+
+### In the WordPress dashboard widget
+
+Once your hosting provider has enabled AI Bot Management, the <span class="notranslate">Imunify Security</span> dashboard widget shows a <span class="notranslate">_Bot Protection_</span> row with the current status, the active preset, and the number of requests blocked in the last 24 hours.
+
+<img src="/images/wordpress-plugin/bot-widget.png" alt="The Imunify Security dashboard widget with the Bot Protection row" width="420">
+
+*The <span class="notranslate">Imunify Security</span> dashboard widget. The <span class="notranslate">_Bot Protection_</span> row shows the active preset and the number of requests blocked in the last 24 hours.*
+
+Click the row to open the detail pane, where you can:
+
+* see the current <span class="notranslate">_Status_</span> and <span class="notranslate">_Blocked (24h)_</span> count;
+* view the active **preset** and its live <span class="notranslate">_Rate limits (requests / minute)_</span> table, and switch preset with <span class="notranslate">_change_</span> → <span class="notranslate">_Save_</span>;
+* turn protection **off for this site** — or back on.
+
+<img src="/images/wordpress-plugin/bot-widget-pane.png" alt="The Bot Protection detail pane inside the Imunify Security widget" width="420">
+
+*The detail pane: status, the 24-hour blocked counter, the preset picker, and the per-category rate limits for the selected preset.*
+
+Only WordPress administrators (users who can <span class="notranslate">_manage options_</span>) can change these settings.
+
+::: tip Note
+If your site cannot reach itself over HTTP, the pane shows a <span class="notranslate">_"Your site can't reach itself"_</span> warning — scheduled tasks, including automatic bot-data updates, may not run. Fix the loopback connectivity (for example, a local DNS or firewall issue) and click <span class="notranslate">_Re-check_</span>.
+:::
+
+### Turning it on or off
+
+AI Bot Management is controlled at three levels:
+
+1. **Hosting provider (server-wide).** The provider enables the feature and sets the default preset. When it is off at the server level, the <span class="notranslate">_Bot Protection_</span> row does not appear. Providers control it from the command line — see the <span class="notranslate">[configuration file reference](/config_file_description/)</span> (<span class="notranslate">`ai_bot_protection`</span>, <span class="notranslate">`ai_bot_protection_preset`</span>) and the <span class="notranslate">[command-line reference](/command_line_interface/#wordpress-plugin)</span>.
+2. **Site owner (WordPress admin).** Once the provider has enabled it, the WordPress administrator turns it on or off for their own site and chooses the preset from the <span class="notranslate">_Bot Protection_</span> widget.
+3. **`wp-config.php` (advanced).** Definitions in <span class="notranslate">`wp-config.php`</span> override the widget:
+
+<div class="notranslate">
+
+```php
+// Force AI Bot Management off for this site (overrides the widget):
+define( 'IMUNIFY_AI_BOT_PROTECTION', false );
+
+// Force a specific preset (balanced | strict | monitor):
+define( 'IMUNIFY_AI_BOT_PROTECTION_PRESET', 'strict' );
+```
+
+</div>
+
+When AI Bot Management is disabled in <span class="notranslate">`wp-config.php`</span>, the widget shows <span class="notranslate">_Disabled in wp-config.php_</span> and the controls are locked.