Royal AI Firewall Documentation
See every AI agent hitting your WordPress site, then decide who gets in. Free WordPress plugin with per-bot policy controls, Content Signals enforcement, Web Bot Auth signature verification, Cloudflare integration guide, and a bundled catalog of 72 recognized AI bots.
Overview
Royal AI Firewall is a free, GPL-licensed WordPress plugin that classifies and controls AI bot traffic at the WordPress application layer. It identifies AI agents by their User-Agent header, cryptographically verifies signed operator requests (Web Bot Auth), tracks whether bots respect your declared Content Signals, and lets you set a policy for each one (always allow, log only, rate limit, paywall, or block) with a one-click dropdown.
This is the entire plugin. There is no Pro version, no premium tier, no upgrade prompts. Every feature ships on wordpress.org. A fresh install makes no outbound network calls. Three are possible, all off until you turn them on: a weekly refresh of published Web Bot Auth signing keys (only while a Web Bot Auth toggle is on), a daily bot catalog fetch, and a weekly anonymous usage report. The key refresh and the catalog fetch send no site data, and the usage report carries no site URL, IP addresses, or customer information.
The dashboard: 4-card hero (Total Hits, Blocked, Allowed, Distinct Bots for the last 24 hours), MCP / Abilities API activity widget, per-bot list with hit counts, and a one-click policy dropdown per row.
Getting Started
Walk through the first-run setup in 60 seconds. The wizard is skippable from every screen if you want to dive straight into the dashboard.
Install from WordPress.org
In wp-admin, go to Plugins → Add New and search for Royal AI Firewall. Click Install Now, then Activate. WordPress redirects you to the 4-step setup wizard automatically.
Welcome screen
Step 1 explains what the plugin does and asks you to continue. No fields to fill in. Hit Let’s go.
Environment detection
Step 2 scans your install for CDNs (Cloudflare, Bunny CDN, Fastly, KeyCDN, Sucuri, StackPath, Akamai) and 23 popular security / caching plugins, then shows a checklist of what was found. The next step depends on whether any CDN is detected.
CDN dial-down (if detected)
If any of the seven supported CDNs sits in front of your site, step 3 names it. For Cloudflare specifically, the wizard lists exactly which CF settings to turn off so Royal AI Firewall can take over the AI-bot layer, plus which to leave on. Other CDNs get a compatibility note confirming Royal AI Firewall coexists with your edge layer. See Cloudflare Setup for the full CF breakdown.
Pick a default policy
The last step asks how the plugin should handle AI bots until you decide per-bot rules. Three options: Log only (recommended for the first 24h), Block training bots, allow retrieval bots, or Block all AI bots except verified search engines. You can change this in Settings any time.
Open the dashboard
Click Finish setup. The plugin lands you on the dashboard. Bot hits start populating as AI agents visit your site, typically 2–6 hours on a public, indexed site, or you can fire a quick test from the command line:
curl -A "GPTBot/1.2" https://your-site.com/Refresh the dashboard and you should see a GPTBot hit recorded.
The plugin ships with a bundled catalog of 72 AI bots. You do not need to enable any outbound update to use the plugin, classification works offline from day one. The optional daily catalog refresh is for users who want fresher catalogs between plugin releases. See Catalog Updates for details.
What each wizard step looks like
Requirements
| Requirement | Minimum | Notes |
|---|---|---|
| WordPress | 6.4 | Tested up to 7.1. Multisite-compatible. |
| PHP | 8.0 | Requires libsodium for Web Bot Auth Ed25519 signature verification (bundled with PHP 7.2+; universally available on PHP 8+ hosts). |
| MySQL / MariaDB | 5.7 / 10.4 | Whatever WordPress 6.4 requires. Plugin uses %i placeholders (available in WP 6.2+). |
| Disk | small | Five custom DB tables, all small. Invocation logs are pruned after 7 days by default. |
| WP-Cron | working | Always scheduled: hourly rollup, daily log prune, daily Bot Access baseline, and a twice-daily Bot Access check. Scheduled only while the matching feature is on: daily bot catalog update, 6-hour Content Signals auto-block sweep, weekly Web Bot Auth key refresh, and weekly anonymous usage report. |
| HTTPS | recommended | Not required for the plugin itself. The Web Bot Auth key refresh, the optional bot catalog endpoint, and the optional usage report all use HTTPS. |
AI Bot Catalog
The plugin ships with a bundled catalog of 72 recognized AI bots, organized into 6 categories. Each entry includes the bot’s identifier, owner, intended purpose, default policy, an AI-purpose classification (ai-train / ai-input / search / mixed / none) used for Content Signals matching, and the blocking consequences (for example, “blocking GPTBot may remove your site from ChatGPT search results”).
Training crawlers
Bots that scrape content to build and improve foundation models. Blocking these removes you from future model training datasets but does not affect on-demand retrieval.
Retrieval bots (on-demand)
Bots that fetch your content when an end user explicitly asks an AI assistant about your site. Blocking these means you don’t show up in chat responses when users mention your URL.
AI search engines
Bots that index your content for AI-native search results pages. Blocking these removes you from Perplexity, OAI-SearchBot results, etc.
Traditional search engine crawlers
Well-known SEO crawlers that predate the AI wave. Eight of the fourteen are protected by the search engine guard whenever their identity is proven. The per-bot dropdown is disabled for them and blocking requires an explicit Settings override with a warning.
Also recognized, no guard: BingPreview · Storebot-Google · Mediapartners-Google · AdsBot-Google · adidxbot · Baiduspider
Agent browsers (newer category)
The newest class. AI agents acting as their human user’s browser, navigating your site on the user’s behalf. Treat these similar to retrieval bots unless you have a reason otherwise.
Dataset scrapers
Bots that build publicly-distributed datasets (Common Crawl, etc.) that other AI vendors then use as training input. Blocking these is one upstream from training crawlers.
How identification works
Every request goes through two layers of identification:
- User-Agent matching (all bots). The plugin matches the UA header against the bundled fingerprint catalog. A spoofed User-Agent will match a real bot’s record, so on its own this answers “what’s claiming to be each bot” rather than verifying identity.
- Cryptographic verification (Web Bot Auth, where supported). When an operator signs its requests per the IETF Web Bot Auth draft (built on RFC 9421), Royal AI Firewall verifies the signature against the operator’s published keys (OpenAI out of the box, more operators as they publish key directories) and records the result on every invocation:
verified,invalid_signature,unknown_operator, orno_signature. See Web Bot Auth. - Reverse-DNS forward-confirm (search engines). For Googlebot and its Image, Video and News variants, Google-InspectionTool, Bingbot, Applebot, Applebot-Extended, and YandexAdditional, the plugin also runs reverse-DNS + forward-DNS to distinguish real search-engine IPs from spoofed UAs. Bots with no published reverse-DNS domain, such as DuckDuckBot, are identified by user agent. See Bot Access Monitor.
The search-engine guard protects a search crawler only when its identity is proven: reverse DNS confirmed it, or, for crawlers with no published reverse-DNS domain, its user agent matched. A request that claims to be Googlebot but fails reverse DNS gets no protection: your default policy applies, so Block training and Block all AI bots both block it. Managing the actual edge layer (Cloudflare, your CDN, or a security plugin running before WordPress) remains the right place to enforce identity at the network level.
Policy Modes
Two layers of policy. The default policy applies to every recognized AI bot unless you set a per-bot override on that specific bot.
Default policy (global)
| Mode | What it does | When to use |
|---|---|---|
| Log only | Records every AI bot hit but blocks nothing. The dashboard fills with data; the bots reach your content. | The recommended starting point. Run for 24–48h to see what’s actually hitting your site before deciding what to block. |
| Block training, allow retrieval | Blocks training crawlers and dataset scrapers (GPTBot, ClaudeBot, Bytespider, CCBot, etc.), plus requests that claim to be a search engine but fail reverse DNS. Allows retrieval bots (ChatGPT-User, Claude-Web, Perplexity-User). | If you want to stay discoverable when users explicitly ask AI assistants about your site, but don’t want your content fed to model training pipelines. |
| Block all AI bots | Blocks every bot in the catalog except the eight protected search engines (Googlebot and its variants, Google-InspectionTool, Bingbot, Applebot, DuckDuckBot), which the always-allow guard keeps allowed when their identity is proven. | Maximum AI-bot lockdown. SEO crawlers still get through. Useful for membership sites, paywalled content, or anything you specifically don’t want AI agents reading. |
Per-bot override
Each bot row in the dashboard has a six-option dropdown that takes precedence over the default mode for that specific bot:
- Use default policy: falls back to the global default mode you picked above.
- Always allow: the bot is allowed regardless of default mode. Use this for a specific training bot you trust.
- Log only: the bot is allowed and recorded; never blocked. Use this when you want visibility on a specific bot but aren’t ready to block.
- Rate limit: enter a number of requests per minute. Requests over the limit get a 429 response with a
Retry-Afterheader. - Paywall (402 / redirect): enter a redirect URL to send the bot there with a 302, or leave it empty to answer 402 Payment Required. Requests for the paywall page itself are served normally.
- Block: the bot receives a 403 response immediately, before WordPress runs any heavy work.
The master “Block all” panic button
Every dashboard load shows a one-click Block all AI bots button at the top. Clicking it switches the default policy to Block all. While Block all is on, the same button reads Stop blocking — return to log only. The search-engine guard still applies in Block all mode, so verified Googlebot et al. stay allowed.
Policy Priority Order
Multiple policy sources can apply to a single request: your manual per-bot override, the Web Bot Auth per-operator toggles, the Content Signals auto-block engine, and the global default mode. RAIF resolves them in a fixed 6-tier order, and every PolicyDecision carries a source field naming which tier fired so you can audit exactly why any single request was allowed or blocked.
| Tier | When it fires | PolicyDecision::source |
|---|---|---|
| 1. Always-allow guard | Bot has always_allow: true in the catalog (the eight protected search engines) and its identity is proven (reverse DNS confirmed, or a user-agent match for bots with no reverse-DNS domain). With the raif_allow_search_engine_block option on, a manual per-bot policy can still block it; the automated tiers and the default mode never do. | always-allow-guard |
| 2. Manual per-bot | A row exists in raif_bot_policy with policy_source = 'manual'. Customer choice always wins over automated tiers. | per-bot-manual |
| 3. WBA trust-verified | Customer enabled trust_verified for the operator AND the request’s Web Bot Auth signature validated. Bypasses lower tiers (including any Content Signals auto-block for the same bot). | wba-trust-verified |
| 4. WBA block-unverified | Customer enabled block_unverified for the operator, the request claims that operator (via verified signature or bot-owner match), and the signature did NOT verify. Catches UA spoofers of a specific operator. | wba-block-unverified |
| 5. Auto per-bot | A row exists in raif_bot_policy with policy_source = 'auto-cs-violation', written by the Content Signals auto-block engine. | per-bot-auto |
| 6. Default mode | No earlier tier applied. Uses raif_default_policy: log-only, block-training, or block-all. | default |
Hook raif_policy_decided and inspect $decision->source to see exactly which tier fired for a given request. Every tier writes a human-readable $decision->reason too (for example, "Web Bot Auth: unverified request claiming openai (invalid_signature)").
Why this order
- Always-allow guard first so search engines are never accidentally blocked, no matter what other policies say.
- Manual second so your explicit choices always beat automation.
- WBA verified-operator trust before block-unverified so an operator you have opted-in trusted can bypass everything else in a single decision.
- Auto-block last before default so the Content Signals engine can catch violators without ever overriding customer choice.
Search Engine Guard
Eight bots are protected from accidental blocking by default: Googlebot, Googlebot-Image, Googlebot-Video, Googlebot-News, Google-InspectionTool, Bingbot, Applebot, and DuckDuckBot. The dashboard dropdown is disabled for these, and the REST API endpoints reject block, rate-limit, and paywall attempts on them with a 409 Conflict response.
The guard applies only when the bot’s identity is proven: reverse DNS confirmed it (Google, Bing, and Apple crawlers), or its user agent matched (bots with no published reverse-DNS domain, such as DuckDuckBot). A spoofed Googlebot gets no protection: your default policy applies, and Block training and Block all AI bots both block it.
If you genuinely want to block a search engine, flip the Search engine override toggle in Settings (“Allow per-bot policies to block major search engines”). The toggle ships with a warning that “blocking Googlebot removes your site from Google Search”. Once enabled, the per-bot dropdowns become active for the guarded bots and the REST endpoints accept block requests. Only a per-bot policy you set can then block a verified search engine; the default mode and the automated tiers still never do.
This guard is independent of the default policy mode. Even in Block all AI bots mode, verified search engines stay allowed, with or without the override.
Content Signals
Content Signals (contentsignals.org) is an advisory spec published by Cloudflare that lets a site declare, in robots.txt, how AI operators may use its content. Three signals:
- ai-train: whether the content may be used to train AI models.
- ai-input: whether the content may be fetched on demand by an AI assistant on behalf of a user.
- search: whether the content may be indexed for AI search results.
Each signal takes yes or no. Compliant bots respect the declaration. Non-compliant bots ignore it and keep training, retrieving, or indexing anyway. RAIF turns that gap into an enforceable defense layer.
How RAIF reads your declared signals
The reader has two source paths:
- SEObolt Pro installed + Content Signals enabled: read directly from the SEObolt options. No HTTP fetch, fastest path.
- Otherwise: read the robots.txt your site serves, in-process: the physical
robots.txtfile if one exists, or WordPress’s virtual robots.txt including lines other plugins add. Each bot is compared with the user-agent group that names it, otherwise the*group, and that group’sContent-Signal:line is used. Parsed groups are cached for 6 hours. No HTTP request is made.
The reader is called synchronously in the Classifier hot path, so every bot invocation is stamped with a violation status at the moment it happens. Site declarations are cached per request, meaning only the first bot invocation of a request pays the read cost.
If Elementor’s Agent Ready feature writes robots.txt rules that allow bots this plugin blocks, the Settings page lists the contradiction and can apply your choice through Elementor’s own setting. See Elementor Agent Ready.
Per-invocation violation status
Every bot hit lands in raif_invocation_log with one of four statuses in content_signal_honored:
| Status | Meaning |
|---|---|
honored | The bot’s declared AI-purpose matches a signal that’s declared yes on your site. |
violated | The bot’s declared AI-purpose matches a signal that’s declared no. The specific signal is recorded in content_signal_violation_type. |
not_applicable | Either the site has no Content Signals declared, or the bot’s purpose is operational (e.g. Google AdsBot, marked ai_purpose: none in the catalog). |
unknown | The bot matched the catalog but its AI-purpose is unclear or unclassified. |
Dashboard widget + Violations tab
The main RAIF dashboard shows a Content Signals widget with your declared preferences as three colored pills (green Allowed / red Not allowed / neutral Not declared), a 4-cell stats block for the last 7 days (total AI bot hits, honored, violated, unknown), and a top-3 violators table showing which bots crossed which signal, with a Status column that reads “Auto-blocked” or “Blocked” when a matching policy exists.
The Activity Log page has a dedicated Content Signals violations tab that filters the full invocation log to only content_signal_honored = 'violated' rows. This is the evidence surface for support conversations and for reviewing the auto-block engine’s decisions.
Auto-block engine (opt-in)
Turn on the Auto-block repeat violators toggle in Settings and a WP-Cron sweep runs every 6 hours (via a custom raif_6hours schedule). For each bot with 3 or more Content Signals violations in the last 24 hours, the sweep creates a per-bot block policy tagged policy_source = 'auto-cs-violation'.
Invariants the sweep respects:
- Off by default. Requires explicit opt-in via the Settings toggle. The cron is only scheduled after opt-in.
- Never clobbers a manual policy. If
raif_bot_policyalready has a row for the bot (manual OR prior auto-block), the sweep skips it. Customer choice always wins. - Always-allow bots exempt. Search engines never get auto-blocked, even on violation.
- Unknown bots skipped. If the bot ID isn’t in the catalog, the sweep doesn’t write a policy for it.
Auto-block policies carry a human-readable auto_reason like Auto-blocked: violated ai-train signal (12 hits in 24 hours), visible in the dashboard’s top-3 violators table (Status column) and in the policy row itself. To revert an auto-block, set the bot’s dropdown in the dashboard to Log only or Always allow. Choosing Use default policy removes the policy row, so the next sweep can block the bot again if it keeps ignoring your signals.
Tuning thresholds
Two filters override the default 3 violations / 24 hours cadence:
// Require 10 violations before auto-blocking
add_filter( 'raif_auto_block_threshold', fn() => 10 );
// Detection window in hours (default 24)
add_filter( 'raif_auto_block_window_hours', fn() => 48 );Both filters have a floor guard: values below 1 fall back to the default. Threshold of 0 would auto-block on any single violation, which we refuse.
How AI-purpose is decided per bot
The bundled catalog carries an ai_purpose field on every bot entry. Values: ai-train, ai-input, search, mixed:X+Y (e.g. mixed:ai-input+search for Perplexity-Comet), none (operational bots like AdsBot), or unknown. The classification is derived from the bot’s existing category with per-bot overrides for the hybrid and edge cases. See AI Bot Catalog.
Web Bot Auth
Web Bot Auth is an IETF draft that lets AI operators cryptographically prove which requests come from them, built on RFC 9421 (HTTP Message Signatures). Operators publish signing keys at /.well-known/http-message-signatures-directory on their domain. Sites verify inbound Signature-Input and Signature headers against those keys and get an authoritative answer to “is this really OpenAI?” instead of relying on a spoof-able User-Agent.
Supported operators
RAIF ships with the operator that publishes a key directory today: OpenAI. More operators are added as they publish key directories, and you can add one yourself with a filter (see below).
| Operator ID | Name | Directory URL |
|---|---|---|
openai | OpenAI | https://chatgpt.com/.well-known/http-message-signatures-directory |
Weekly key refresh (only while a toggle is on)
A WP-Cron event on the weekly schedule fetches each operator’s directory, parses the JWK Set (RFC 7517), keeps only Ed25519 and ECDSA-P256 keys, and caches the full per-operator key map in raif_web_bot_auth_keys (autoload OFF). Individual operator failures are non-fatal: a 404, timeout, or malformed body marks that operator temporarily-unavailable and the sweep continues to the next. No site data is sent in the fetch.
The refresh runs on the raif_web_bot_auth_refresh cron hook. It is scheduled only while at least one Web Bot Auth toggle is on, because it calls the operators’ key servers. Turning on a toggle schedules the first run one minute later, then weekly; turning every toggle off removes the event, and no further request is made.
Signature verification per request
The Classifier hot path runs signature verification on every http-source bot request (skipped for MCP and Abilities API paths, which carry their own auth). The result lands in web_bot_auth_status on the invocation log as one of:
| Status | Meaning |
|---|---|
verified | Signature was cryptographically valid against a known operator key. |
invalid_signature | Signature parsed but did not verify (tampered, wrong key, or the request drifted from the signed content). |
unknown_operator | The keyid claimed by the signature is not in the local key registry. |
no_signature | Request carried no Signature-Input and Signature headers. |
Supported algorithms: Ed25519 (verified via libsodium’s sodium_crypto_sign_verify_detached) and ECDSA-P256 (verified via OpenSSL after JOSE-flat-to-DER conversion and JWK-to-PEM SubjectPublicKeyInfo construction). Other algorithms (RSA, HMAC, ECDSA-P384) return invalid_signature.
Per-operator policy toggles
On the Settings page, each operator gets two independent toggles:
- Trust verified requests: when on, a request with
web_bot_auth_status = 'verified'against this operator is allowed unconditionally, bypassing Content Signals auto-block and default policy. UsesPolicyDecision::source = 'wba-trust-verified'. - Block unverified claims: when on, a request that claims this operator (via verified signature or bot-owner match on UA) but does NOT have a valid signature is blocked. Catches UA spoofers of that specific operator. Uses
PolicyDecision::source = 'wba-block-unverified'.
The two toggles are independent. Trust verified alone is a common configuration for sites that mostly want the signal but don’t care about spoofers. Block unverified alone is more aggressive: any request pretending to be, say, OpenAI without proof gets a 403. Enable both for the strongest per-operator posture. Block unverified takes effect only once that operator’s keys have been fetched; until then nothing can verify, so no request is blocked by it.
If you have set a manual per-bot override for a specific bot, that override takes precedence over both WBA toggles for that bot. See Policy Priority Order.
Adding custom operators
The default registry ships with OpenAI. When a new operator starts publishing keys, add them via the raif_web_bot_auth_operators filter:
add_filter( 'raif_web_bot_auth_operators', function( $operators ) {
$operators['newco'] = array(
'name' => 'NewCo AI',
'directory_url' => 'https://newco.ai/.well-known/http-message-signatures-directory',
);
return $operators;
} );Per-operator toggles for custom operators appear in the Settings table automatically. While any toggle is on, the weekly refresh (or an on-demand run of KeyDirectoryReader::refresh_all()) fetches and caches the new operator’s keys.
Bot Access Monitor
The Bot Access page (AI Firewall → Bot Access in wp-admin) answers one question in one place: can real search-engine bots still reach my site? It runs a passive check against your invocation log, an active probe from your server, and a reverse-DNS self-test on every render.
Bot Access page after clicking Re-check now, combined verdict at top, per-bot passive table, three-part verification self-test (A/B/C), and the active probe truth table.
Combined verdict badge
Aggregates the passive and active checks into a single status: All Clear, Warning, Fail, High-confidence Fail, or Collecting baseline. Passive Fail + Active Pass = high-confidence Fail (site is up but verified bots have stopped reaching origin, the most damaging real-world scenario).
Per-bot passive detection
Four watched bots by default: google-googlebot, microsoft-bingbot, apple-applebot, duckduckgo-bot. Extend the list via the raif_bot_access_watched_bots filter. Each row shows:
- Verdict pill: Pass / Alert / Warning / Skipped / Collecting baseline (day X / 7). New installs stay in Collecting for the first 7 days of aggregator runs so the baseline has enough data to reason about.
- 24h verified: count of forward-confirmed reverse-DNS matches from real vendor IPs in the last 24 hours.
- Baseline avg: rolling 30-day average verified hits per hit-day (zero-hit days and today’s partial are both excluded from the average, so the ALERT threshold does not fire falsely on non-crawl days).
- Baseline days: count of observed days including today, growing regardless of hit cadence.
Verification self-test
Three sub-panels below the passive table:
- A. Reverse-DNS resolver test: live
gethostbyaddron a known Googlebot IP (66.249.66.1) with suffix and forward-confirm checks. The verdict row tells you at a glance whether your host’s resolver can verify search bots at all. If this section fails, no amount of real Googlebot traffic will ever be marked verified until the host fixes DNS. - B. Per-bot verification breakdown: last 24h invocation-log rows grouped by verification status (verified / spoofed / unverified / ua_match / other) with a plain-English reading per row. Distinguishes “no bot traffic” from “bots hit but failed verification”.
- C. Raw evidence: 5 most-recent log rows across watched bots showing occurred_at, bot_id, verification_status, IP, response status, and policy action. Lets you cross-check the aggregate against the actual log content.
Active probe: dual-request truth table
Every 12 hours (via WP-Cron), and on demand via Re-check now, the plugin fires two self-requests against home_url(): one with a browser user-agent and one with a Googlebot user-agent. It reads the response code, cf-mitigated header, and body for known challenge signatures (Cloudflare, Sucuri, Imunify360). The truth table interprets the pair:
- Pass: both probes returned 200 with no mitigation signature.
- Pass with CF: Cloudflare challenged the server-side probe but real search bots from Google IPs are allowed through at the edge. Confirm with Google Search Console URL Inspection.
- Warning: browser passed but Googlebot got a hard 403 from a WAF or Sucuri or Imunify360 rule.
- Fail: both probes were blocked, site is unreachable to non-verified clients.
Diagnostic bundle
A copy-to-clipboard textarea at the bottom of the page dumps the whole verdict, combined, passive per-bot, active probe result, and site metadata, in one paste-ready block for support tickets.
What triggers an alert
Alerts fire on state transitions, not on repeated status. If verified hits collapse below 10% of the 30-day baseline (and the baseline is non-trivial), a dismissible admin notice appears and an optional email fires. Once acknowledged, the alert stays quiet until the state changes back.
Import & Export Policies
Policy import/export lets you back up your per-bot overrides or move them between sites. The controls live in a Backup + portability section on the Settings page.
Export
Under Export policies, click Download policy JSON to download a JSON file containing:
- Every custom per-bot policy row (bot ID, action, and optional rate-limit / paywall-URL fields when set)
- The global default policy value (
log-only,block-training, orblock-all) - The current state of the Search engine override toggle (exported for portability, see the import section below for how it’s handled)
What’s not included: invocation log data, daily rollups, wizard progress, or any version or licensing metadata. Policy state only.
The filename follows raif-policies-{site-slug}-{YYYY-MM-DD}.json. The file itself carries a top-level _schema field so the importer can confirm compatibility on the way back in.
Import
Under Import policies, pick a previously-exported JSON file and click Upload + preview. The plugin runs an eight-gate validator before it touches anything:
- Extension check: must end in
.json - Upload type check: WordPress accepts the file only as
application/json - Size cap: 500 KB max (real exports are a few KB; the cap blocks abuse)
- JSON parse: invalid JSON is rejected with a clear error
- Schema check:
_schemamust be a known-compatible version - Structure validation:
policiesarray, a validglobal_default, and a valid action (allow,log-only,rate-limit,paywall-redirect,block) on every entry - Bot ID lookup: unknown bot IDs are silently skipped and counted in the summary (bot catalogs evolve; an old export may reference a bot that’s since been removed, that shouldn’t hard-fail the whole import)
- Capability + nonce check:
manage_optionsrequired
If any gate fails, nothing is applied. The uploaded temp file is deleted as soon as it has been read.
Preview before applying
Passing the validator does not apply the file. You see a preview panel first with:
- Total policies in the file
- How many will overwrite existing per-bot policies
- How many will be added new
- How many were skipped as unknown bot IDs
- Whether the global default in the file differs from the current site
Confirm with Apply import and the plugin writes the changes through the same code path the dashboard dropdown uses, so all the usual guard rails (search-engine protection, action-enum validation) still apply. The apply handler is one-shot, the preview transient is invalidated the moment it runs.
If the imported file has the Search engine override flag set, the importer displays the file’s value in the preview and tells you that enabling it is a separate, deliberate step in Settings. Any per-bot block rows targeting always-allow bots (Googlebot, Bingbot, etc.) are skipped and reported in the summary until you flip the override manually. This is intentional, the override is a foot-gun (blocking Googlebot removes your site from Google Search), and no import should ever silently arm it.
Use cases
- Multi-site sync. Agencies running Royal AI Firewall across many client sites can maintain one canonical policy set and re-import it per site.
- Staging → production. Tune per-bot policies on a staging install, export, then import on production once you’re happy.
- Backup before experimenting. Export first, tweak freely, re-import the original file if the experiment doesn’t pan out.
Cloudflare Setup
Cloudflare and Royal AI Firewall both have opinions about AI bots. To get the per-bot dashboard and one-click controls in Royal AI Firewall to work, you need to dial down Cloudflare’s AI-specific features so requests reach WordPress where this plugin can see and decide on them.
Cloudflare’s general protections (DDoS, managed WAF, SSL, Bot Fight Mode) are fine to leave on, they don’t conflict with the WordPress-layer controls.
On September 15, 2026, Cloudflare rolled out three new AI-bot categories (Search, Training, and Agent) that replace the older “Block AI Bots” and “Managed Robots.txt” single toggles. Sites that had either legacy toggle enabled prior to September 15 were auto-migrated (per Cloudflare’s customer email) to Search: Allow, Training: Disallow AI Training, and Agent: Block on pages with ads. The dashboard UI is rolling out gradually over the week following September 15, so you may still see the old toggle names for a bit. Whichever UI is showing in your account, the Royal AI Firewall recommendation stays the same: set every AI-bot control in Cloudflare to Allow, so requests reach WordPress where this plugin’s per-bot decisions can run.
Turn OFF in Cloudflare
| Setting | Where to find it | Set to |
|---|---|---|
| Search category (new taxonomy) | Security → Bots | Allow |
| Training category (new taxonomy) | Security → Bots | Allow (Royal AI Firewall makes the per-bot training decision at WordPress) |
| Agent category (new taxonomy) | Security → Bots | Allow (so MCP tool calls and on-demand retrieval bots reach WordPress) |
| Block AI Bots (legacy toggle, if still visible) | Security → Bots | OFF |
| Managed Robots.txt (legacy toggle, if still visible) | Security → Bots | OFF |
| AI Audit | Security → Settings → AI Audit | Allow |
| AI Labyrinth | Security → Bots → AI Labyrinth | OFF |
| Custom WAF rules blocking AI bots | Security → WAF → Custom rules | DELETE (per-bot controls in this plugin replace them) |
| Security Level | Security → Settings → Security Level | Medium or Low |
Leave ON in Cloudflare
These don’t conflict with Royal AI Firewall and provide real value:
- DDoS protection: keep on.
- Managed WAF rules: keep on.
- SSL/TLS: keep on.
- Bot Fight Mode (basic tier): keep on. Blocks well-known abusive crawlers that aren’t AI agents.
- Browser Integrity Check: keep on.
- Caching: keep on. The plugin’s REST endpoints set
Cache-Control: no-storeheaders and triggerDONOTCACHEPAGEto opt out of caching where it matters.
How Cloudflare detection works
Royal AI Firewall detects Cloudflare on every wp-admin page load by checking for the cf-ray, cf-connecting-ip, or CDN-Loop: cloudflare headers on the incoming request. A persistent 24-hour state ensures the dashboard UI stays stable even when an occasional admin request doesn’t pass through CF.
When Cloudflare is detected, the wizard’s step 3 surfaces the dial-down guide above and the Cloudflare visibility status card appears on the dashboard with an honest estimate of how many AI bots may have been filtered at the edge before reaching WordPress.
Other CDNs
Royal AI Firewall also recognizes Bunny CDN, Fastly, KeyCDN, Sucuri, StackPath, and Akamai by their vendor-forwarded request headers (CDN-PullZone, Fastly-Client-IP, X-Pull, X-Sucuri-*, X-SP-Edge-Host, Akamai-Edgescape, and RFC 8586 CDN-Loop where the CDN honors it). Detection is header-sniff only (no outbound HTTP, no DNS lookups), and each detected CDN is cached for 24 hours the same way Cloudflare is.
The Cloudflare-specific dial-down walkthrough above stays the primary content in the wizard because Cloudflare’s AI controls are the most common source of operator confusion. Other CDNs show a compatibility note confirming Royal AI Firewall sees whatever traffic reaches WordPress, if you have edge-side AI-bot rules configured on your CDN, consult its documentation, as the two layers can coexist.
Some shared hosting providers run their own Cloudflare layer in front of every site they host. If your CF dashboard shows no AI bot filtering but Royal AI Firewall’s dashboard still shows zero hits after 24 hours, your host may be filtering at a separate CF layer you can’t configure. Check the cf-mitigated response header on a curl probe to your site, if it’s present and you didn’t configure it, that’s the host’s Cloudflare. Contact host support.
Security Plugin Compatibility
Royal AI Firewall coexists cleanly with other security plugins. It detects common security plugins and shows compatibility notes on the dashboard and Settings page.
Edge-firewall security plugins
Popular edge-firewall plugins run their own firewall before WordPress loads. AI bots they block at their layer won’t appear in Royal AI Firewall’s dashboard, you only see the bots that reach WordPress. The two layers don’t conflict; they just sit at different points in the request path.
Practical impact: if your other security plugin already blocks GPTBot at its edge, you won’t see GPTBot hits in Royal AI Firewall’s dashboard either way. To get full visibility, allow AI bots at the edge-firewall layer and use Royal AI Firewall’s per-bot controls for the decision instead.
WordPress-layer security plugins
Security plugins that run their checks inside WordPress (after the request reaches PHP) coexist cleanly with Royal AI Firewall. Both layers see every request and can apply their own rules. AI-bot decisions made by Royal AI Firewall happen at parse_request priority 1, before most other plugins run, so blocked bots receive their 403 before any heavy WordPress work fires.
Royal Plugins integrations
- GuardPress: detected automatically. Royal AI Firewall shows a first-party compatibility status. The two plugins handle different layers (GuardPress = login + general security, Royal AI Firewall = AI-bot identification + policy) and run side-by-side with no overlap.
- Royal MCP 1.4.33+: detected automatically. A first-party bridge captures every MCP tool call into the MCP Activity widget on the Royal AI Firewall dashboard, with full tool name and result status. See MCP / Abilities API for details.
auth.txt Discovery
Royal AI Firewall publishes a text file at /auth.txt on your site root. It’s a discovery document that tells AI operators which authentication methods your site accepts, following the companion spec to Web Bot Auth. Operators can read it to learn how your site expects them to authenticate.
What’s in it
The default body:
# Royal AI Firewall — declared AI auth methods
Web-Bot-Auth: supported
Preferred-Auth: web-bot-auth
Last-Updated: 2026-09-09T12:00:00ZLast-Updated is the current UTC time when the file is served. A Contact: line appears only when you set a contact address (below).
Response headers include Content-Type: text/plain; charset=utf-8, Cache-Control: public, max-age=3600, and X-Robots-Tag: noindex (so the discovery doc doesn’t get search-indexed as a site page). The request handler runs on parse_request priority 0, so the file is served synthetically without touching WordPress’s template stack. No physical file is written; no rewrite rule is registered.
Customize the Contact address
Empty by default, so no Contact: line is published. Enter an address in Settings → Web Bot Auth → auth.txt contact (stored in the raif_auth_txt_contact option) and the file gains a Contact: line. Developers can also set it with a filter:
add_filter( 'raif_auth_txt_contact', function() {
return 'ai-operators@your-site.com';
} );The value is sanitized as an email. An invalid value is dropped, and no Contact: line is published.
Full body override
Return your own array of lines to fully rewrite the body:
add_filter( 'raif_auth_txt_lines', function( $lines ) {
$lines[] = 'X-Site-Policy: https://your-site.com/ai-policy/';
return $lines;
} );The line-safety pass runs after the filter: CR/LF are stripped, each line is capped at 1024 chars, and empty lines are dropped. This protects against injection even if the filter output is user-controlled.
MCP / Abilities API Logging
Royal AI Firewall records what AI agents do through MCP, separate from the HTTP-layer bot dashboard. Authenticated Royal MCP connections are never blocked by bot policies; Royal MCP checks the token and records each tool call. Other MCP servers’ requests follow your bot policies like any other request. See Royal MCP and the firewall.
What gets logged
For each ability invocation, the plugin records:
- Ability ID or tool name (e.g.
core:create-post) - Caller’s User-Agent and IP (when present in the request context)
- Response status (success, or an error status when the call failed)
- Timestamp
- For Royal MCP 1.4.33+: the tool name and whether the call succeeded. Calls from a client that is not a recognized AI bot are logged under the bot ID
unknown-mcp-client.
Abilities API calls are logged when the caller is a recognized AI bot.
What is not logged: tool and ability arguments. Neither argument keys nor values are stored, because they can contain arbitrary customer data (post content, search queries, etc.). No MCP client ID is recorded.
Where to see it
The dashboard shows an MCP / Abilities API activity widget when Royal MCP is active or MCP / ability calls were logged in the last 24 hours. It lists the top 20 tools and abilities by call count, with an error count where calls failed; the total shown is the sum of those top 20 rows. Otherwise the widget stays hidden, so non-MCP sites don’t see a noisy empty panel.
Compatible MCP server plugins
Royal AI Firewall logs ability calls made by a recognized AI agent outside a REST request, through the WordPress Abilities API hooks (wp_before_execute_ability and wp_after_execute_ability, WordPress 6.9+). Calls that arrive over REST are logged once, as the request itself.
If Royal MCP 1.4.33 or later is installed, an additional first-party bridge captures every MCP tool call from that server with full tool name and result status, not just the WordPress Abilities API subset.
Privacy & Telemetry
Royal AI Firewall is privacy-first by default. The plugin makes zero outbound HTTP calls on a fresh install. Telemetry is off. The catalog auto-update is off. The Web Bot Auth key refresh stays off until you turn on a Web Bot Auth toggle. There is no license check, no analytics call, no traffic beacon.
What never leaves your server
Regardless of any toggle state, the following are never sent anywhere:
- Your site URL or domain
- Customer email addresses
- Invocation log contents (which bots hit, which URLs, when)
- Specific IP addresses
- Specific bot identities or hit counts
- User-Agent strings of visitors
Anonymous usage data (opt-in)
The Settings page has an Anonymous usage data toggle. It is off by default and can also be set from the setup wizard’s final step. When enabled, the plugin schedules a weekly WP-Cron event (raif_telemetry_report) that POSTs one small JSON payload to telemetry.royalplugins.com.
What the payload contains:
- Plugin version, WordPress version, PHP version
- An opaque one-way site fingerprint: SHA-256 of your site URL plus a per-install random salt that never leaves your site. Used only to count unique installs; the URL itself cannot be recovered from the hash.
- Whether you have completed the setup wizard
- Count of custom per-bot policy overrides you have configured
- A bucketed range for AI bot hits in the last 24 hours (e.g.
11-50)
What is never sent matches the “What never leaves your server” list above, no site URL, no email addresses, no IPs, no per-bot identities, no visitor User-Agents, no log contents. The endpoint accepts the payload or rejects it with a schema error; no response body is returned.
Data retention: raw payloads are retained for 90 days. Aggregated statistics are retained indefinitely. Per-site fingerprints are purged after 12 months with no reports. Disable the toggle at any time in Settings, the plugin unschedules the weekly cron immediately, and no further payloads are sent.
WordPress Privacy Policy Guide integration: when the toggle is on, the plugin registers a disclosure block via wp_add_privacy_policy_content(). From Tools → Privacy in your WordPress admin, you can pull the disclosure directly into your own site’s privacy policy in one click.
Log retention
Invocation logs default to 7-day retention. Logs older than 7 days are pruned by the daily raif_log_prune cron event. To customize retention, use the raif_log_retention_days filter:
add_filter( 'raif_log_retention_days', function( $days ) {
return 30; // Keep logs for 30 days instead of 7
} );Valid range: 1 to 365 days. Values below 1 fall back to the default 7; values above 365 clamp to 365.
Catalog Updates
Royal AI Firewall ships with a bundled bot fingerprint catalog. That catalog refreshes automatically every time you update the plugin through wp-admin → Plugins. No opt-in required, no outbound network call.
How the per-release refresh works
Each plugin release includes a fresh data/fingerprints-bundled.json with any new bots or User-Agent string changes since the last release. When you update the plugin, Royal AI Firewall checks the bundled catalog’s database_version against what’s currently cached. If the bundled snapshot is newer, the cache is replaced with the new catalog. This happens silently on plugins_loaded after the version bump. You don’t need to reactivate or do anything.
The optional daily refresh (opt-in)
If you want catalogs fresher than the per-release cadence (typically 2–4 weeks between plugin releases, faster after major AI-vendor launches), tick the Keep catalog updated between releases toggle on the final wizard step or in Settings → Bot fingerprint database.
The Settings page: default policy, Content Signals auto-block toggle, Web Bot Auth per-operator toggles (OpenAI) with the auth.txt contact field, Cloudflare detection status, security plugin compatibility notes, the “Keep catalog updated between releases” opt-in toggle (unchecked by default), log retention, uninstall behaviour, and the opt-in anonymous telemetry toggle.
When enabled, the plugin schedules a daily WP-Cron event (raif_fingerprint_update) that makes one HTTPS GET to fingerprints.royalplugins.com/v1/index.json. The request body is empty. Only the plugin version in the User-Agent header (e.g. royal-ai-firewall/X.Y.Z) and a standard If-None-Match cache validator are sent.
The toggle is off by default. Unticking the toggle immediately unschedules the cron. No outbound call will ever fire again unless you re-enable it. The bundled catalog continues to refresh on plugin updates regardless.
How to disable the daily update entirely
Three ways:
- Recommended: Untick the Keep catalog updated between releases toggle in Settings.
- Code: Use the
raif_fingerprint_endpointfilter to return an empty string:add_filter( 'raif_fingerprint_endpoint', '__return_empty_string' ); - Site-wide: Set
WP_HTTP_BLOCK_EXTERNALin yourwp-config.phpto block all external HTTP requests from WordPress (affects every plugin, not just this one).
Uninstall Behavior
By default, data is preserved on uninstall. Your invocation logs, daily rollups, per-bot policy overrides, and all plugin options survive the uninstall so a reinstall picks up where you left off.
To delete everything on uninstall
Tick the Delete all logs, tables, and options when the plugin is uninstalled toggle in Settings → Data before deactivating. Then deactivate and delete the plugin through wp-admin → Plugins.
When the toggle is on, the uninstall script drops the five custom tables (wp_raif_invocation_log, wp_raif_daily_rollup, wp_raif_bot_policy, wp_raif_bot_access_baseline, wp_raif_page_type_daily) and deletes every raif_* option, except the self-check signing key shared with SEObolt Pro while SEObolt Pro is installed. Changes you applied to other plugins’ settings (for example Elementor Agent Ready) stay as they are.
Deactivating the plugin (without deleting) unschedules its cron events and removes its user-agent entries from supported page caches (WP Rocket, W3 Total Cache, WP Super Cache, LiteSpeed Cache). Data stays put. Reactivate any time to resume where you left off.
Dashboard Shows Zero Hits
If the dashboard shows zero AI bot hits even though you’re sure AI bots are visiting your site, work through these in order.
Fire a manual test
From a terminal with internet access (not from the WordPress server itself):
curl -A "GPTBot/1.2" https://your-site.com/Refresh the dashboard. If GPTBot now shows 1 hit, the plugin is working, you just hadn’t had real bot traffic yet. New / low-traffic sites can take 2–6 hours to see the first organic AI bot hit.
Check Cloudflare
If you’re behind Cloudflare and the manual curl test above doesn’t register, Cloudflare may be blocking AI bots at the edge before they reach WordPress. Walk through the Cloudflare setup dial-down guide and run the test again.
Check the REST API response
The dashboard reads its data via the /wp-json/royal-ai-firewall/v1/dashboard-data REST endpoint. From your wp-admin dashboard, open the browser’s Network tab and reload, you should see a 200 response with JSON data. If you see a 401, your session expired (refresh the page). If you see a 500, check the WordPress error log.
Check for caching plugins serving stale responses
Some cache plugins intercept REST API responses. The plugin sends Cache-Control: no-store headers and the DONOTCACHEPAGE constant, but exotic configurations (Cloudflare APO, server-side fastcgi cache, Varnish) may still cache. Exclude /wp-json/royal-ai-firewall/* from any REST API caching in your cache plugin’s settings.
Check that the WP-Cron is running
The hit counts and per-bot list read the invocation log directly, so they don’t depend on WP-Cron. WP-Cron does run the hourly rollup (raif_rollup_build) behind the page-type views, the daily log prune, and the Bot Access checks; if it is broken, those fall behind. From wp-admin → Tools → Site Health, check the Loopback test, if it fails, your site can’t fire WP-Cron events.
Blocking Not Working
If you’ve set a bot to Block but it still shows up with successful 200 responses in the dashboard, the blocking layer isn’t firing for one of these reasons:
Search engine guard
If the bot you’re trying to block is one of the eight protected search engines (Googlebot and its variants, Google-InspectionTool, Bingbot, Applebot, DuckDuckBot), the search engine guard is overriding your block attempt by design. The Settings page has a toggle to override the guard with a clear warning. See Search Engine Guard.
Edge layer is allowing through
The blocking happens at WordPress’s parse_request priority 1, before WordPress runs most of its work, but after Cloudflare, your CDN, and any edge-layer security plugins have already let the request through. The bot is, at this point, already inside WordPress; we’re just returning a 403 before any of the heavy work runs.
That’s the right place for an AI-bot policy plugin to live. If you need to block at a different layer entirely, before the request hits PHP at all, configure that in your CDN or edge-firewall settings.
Server-side cache is serving the response
If your server-side cache (nginx fastcgi cache, Varnish, or similar) was warmed by a previous unblocked hit, the cached 200 response may be served back even after you set the policy to Block. Clear the cache for the URLs the bot is hitting and re-test. Royal AI Firewall adds blocked bots to the “do not cache for these user agents” setting of WP Rocket, W3 Total Cache, WP Super Cache, and LiteSpeed Cache automatically; server and CDN caches need their own bypass rule. See Page caches.
Per-bot override is set to “Use default policy”
Double-check the dropdown on the bot row. If it says Use default policy, the bot inherits whatever your global default is (Log only, by default). To block this specific bot regardless of default, set the dropdown to Block explicitly.
Bot Access Shows Alert or Fail
The Bot Access page has flipped from All Clear to Alert, Fail, or High-confidence Fail. Something between the internet and your WordPress origin is blocking verified search-engine bots. Work through the sections top-to-bottom, the page is designed to answer each question in order.
1. Check Section A: Reverse-DNS resolver test
If the verdict row says ✗ This host CANNOT verify search bots, the problem is at the operating-system DNS resolver level on your web host. No amount of real Googlebot traffic will ever be marked verified until the host fixes it. Contact your host with the exact error from the PTR lookup row.
Temporary workaround: add the filter raif_disable_reverse_dns_verification and return true. RAIF falls back to plain UA-match. You’ll lose spoof-detection but the ALERT will clear.
2. Check Section B: Per-bot verification breakdown
Look at the Read this row as column for each watched bot:
- “No hits with this bot’s UA in 24h”: that bot genuinely isn’t reaching origin. Move to step 4 (Active probe).
- “Hits arrived but reverse-DNS says spoofed”: requests with a Googlebot UA are hitting from non-Google IPs. Real Googlebot may still be blocked upstream; check step 4.
- “Hits arrived but DNS forward-confirm failed”: transient DNS issue on this host; usually clears within a day. Re-check tomorrow.
3. Check Section C: Raw evidence
Cross-check the aggregate in Section B against actual log rows. If Section C shows recent verified hits but Section B says total = 0 for that bot, screenshot both sections and open a support ticket, that’s an aggregate bug.
4. Check the Active probe truth table
The bottom of the page shows the last dual-request probe result:
- Pass with CF: Cloudflare challenges the server-side probe but real search bots from Google IPs are usually allowed through at the edge. Confirm with Google Search Console → URL Inspection → Test Live URL. If GSC reports the URL is available to Google, real Googlebot is passing; the ALERT is probably a low-traffic false positive that will clear next 24h.
- Warning: browser passed but Googlebot got a hard 403. Likely a WAF, Sucuri, or Imunify360 rule. Check the Signature match column for the specific mitigation layer.
- Fail: both probes were blocked. Site is genuinely unreachable to non-verified clients. Check host status, WAF rules, and hosting-layer “under attack” toggles first.
5. Contact your host with the diagnostic bundle
Scroll to the Diagnostic bundle textarea at the bottom of the Bot Access page. Click to select, copy, and paste the whole block into the support ticket. It contains the combined verdict, per-bot verified counts, active probe interpretation, and site metadata, everything an L2 host engineer needs to reproduce the diagnosis without walking your site owner through each panel.
If Section A is ✓, the active probe returns 403 with a Cloudflare challenge signature, and your host is on the Endurance stack (HostGator, Bluehost, iPage, HostMonster, FatCow, Domain.com), the host may be running a hidden Cloudflare partner layer above your own Cloudflare zone. Standard CF settings changes won’t fix it because that layer is invisible from your dashboard. Insist on L2 escalation and ask the host to whitelist verified search bots at their CF-partner layer. Contact support if you hit this.
If none of the above resolves the ALERT, open a support ticket with the diagnostic bundle plus a screenshot of the Bot Access page. We can usually spot the pattern within a few minutes of seeing the bundle.
FAQ
Is there a Pro version?
No. Every feature ships in the free release on WordPress.org. There’s no upgrade prompt, no license key field, no paid tier on the roadmap.
Does the plugin call home?
Not on a fresh install. Three outbound calls are possible, all HTTPS and all off until you turn them on: the weekly Web Bot Auth key refresh (only while a Web Bot Auth toggle is on; it fetches OpenAI’s published signing keys and sends no site data), the daily bot catalog refresh (opt-in, sends no site data), and the weekly anonymous usage report (opt-in). See Privacy & Telemetry, Web Bot Auth, and Catalog Updates.
Will this block Googlebot?
Not the real one. Googlebot and its variants, Google-InspectionTool, Bingbot, Applebot, and DuckDuckBot are protected by the search engine guard whenever their identity is proven. Override requires explicit Settings toggle with a warning. A fake Googlebot that fails reverse DNS gets no protection. See Search Engine Guard.
Does it work on multisite?
Yes. Activate per-site or network-wide. Each site maintains its own bot catalog, log, and per-bot policy overrides.
What WordPress and PHP versions does it require?
WordPress 6.4 minimum (tested up to 7.1). PHP 8.0 minimum. See Requirements.
Does it slow down my site?
The classifier runs in-process against a small pre-compiled UA pattern list. Non-bot traffic is not logged at all. Reverse-DNS results for search-engine checks are cached. Logging is buffered and flushed on the WordPress shutdown hook, after the page has been generated, so database writes don’t sit in the middle of building the page.
What if I have Wordfence / iThemes Security / etc.?
They coexist cleanly. The plugin detects popular security plugins and notes the compatibility on the dashboard. See Security Plugin Compatibility.
How do I get support?
The WordPress.org plugin support forum at wordpress.org/support/plugin/royal-ai-firewall/. We monitor and reply there.
Options Reference
User-facing WordPress options written by the settings UI. All keys are prefixed raif_. Every value is sanitized on write; unknown keys are ignored.
| Option key | Type | Purpose |
|---|---|---|
raif_default_policy | string | Global default action for classified bot traffic. One of log-only (default), block-training, block-all. Overridden per-bot by raif_bot_policy table entries. |
raif_allow_search_engine_block | bool | When true, per-bot policies may block the eight protected search engines (the dashboard dropdown unlocks for them). The default mode, the “Block all AI bots” button, and the automated tiers still never block a verified search engine. Off by default. |
raif_auto_block_enabled | bool | Opt-in to the Content Signals auto-block engine. Off by default. When on, a 6-hour cron sweep creates a block policy for any bot that has violated declared Content Signals 3 or more times in the last 24 hours. Manual per-bot policies are never overwritten. See Content Signals. |
raif_wba_operator_policies | array | Per-operator Web Bot Auth toggles. Keyed by operator id (openai by default, plus any operator added through raif_web_bot_auth_operators). The weekly key refresh is scheduled only while at least one toggle is on. Each value has two booleans: trust_verified (allow verified traffic unconditionally) and block_unverified (block requests that spoof the operator’s UA without a valid signature). See Web Bot Auth. |
raif_auth_txt_contact | string | Contact address published in /auth.txt. Empty by default; when empty, no Contact: line is published. See auth.txt Discovery. |
raif_telemetry_opt_in | bool | Opt-in to the weekly anonymous usage report. Off by default. Unticking immediately unschedules the cron. |
raif_fingerprint_auto_update | bool | Opt-in to daily catalog auto-updates from fingerprints.royalplugins.com. Off by default. Unticking immediately unschedules the cron. |
raif_delete_data_on_uninstall | bool | Opt-in to full data deletion (all five raif_* tables + all raif_* options) when the plugin is uninstalled. Off by default. Data is preserved for reinstall. |
raif_fingerprint_db_version | string | Read-only. Current bot catalog version installed (bundled or last-fetched). |
raif_web_bot_auth_keys | array | Read-only cache. Operator-keyed JWK sets fetched by the weekly refresh cron. Autoload OFF (can be tens of KB). |
raif_web_bot_auth_last_refresh | array | Read-only diagnostic. Timestamp of the last successful refresh per operator, keyed by operator id. |
raif_cf_detection_state | array | Diagnostic. Timestamp and header-signal that fired the most recent Cloudflare detection. Surfaced in Settings; not user-writable. |
| User meta (per-user, not options): | ||
raif_whats_new_seen_version | string (user meta) | Plugin version the current user last dismissed the What’s New modal at. Auto-open re-fires on the next admin page view after a plugin version bump. Reset the meta key for a user to force a re-show. |
Table Schema
Five custom tables, all prefixed {$wpdb->prefix}raif_. Created via dbDelta on activation. Dropped only when raif_delete_data_on_uninstall is opted in. Schema version bumps run additive migrations on plugin update; existing data is never rewritten in place.
raif_invocation_log
Every request from a recognized bot, plus MCP tool calls captured via the Royal MCP bridge and Abilities API invocations. Traffic that matches no bot is not logged. Pruned daily to the raif_log_retention_days filter (default 7).
| Column | Type | Notes |
|---|---|---|
id | BIGINT UNSIGNED PK | Auto-increment. |
occurred_at | DATETIME | Indexed. UTC. |
bot_id | VARCHAR(64) | Indexed with occurred_at. Catalog identifier; unknown-mcp-client for Royal MCP calls from a client that is not a recognized bot. |
bot_category | VARCHAR(32) | One of training-crawler, retrieval-on-demand, ai-search-index, search-index, dataset-scraper, agent-browser. |
verification_status | VARCHAR(16) | Reverse-DNS + forward-DNS result for verifiable bots. |
ip | VARBINARY(16) | Indexed with occurred_at. IPv4/IPv6 packed. |
ua | VARCHAR(512) | Truncated at 512 chars. |
request_method, request_uri, response_status, response_bytes | Request-response metadata. | |
page_type | VARCHAR(64) | Page type of the requested URL. Empty until classified. |
policy_action, policy_reason | VARCHAR | What the policy engine decided and why. Action is one of allow, log-only, block, rate-limit, paywall-redirect. |
source | VARCHAR(16) | Indexed with occurred_at. One of http, mcp-server, abilities. |
ability_id, mcp_client_id | VARCHAR | ability_id holds the tool or ability name when source is mcp-server or abilities. mcp_client_id is currently left empty. |
content_signal_honored | VARCHAR(16) | Indexed with occurred_at via idx_cs_honored_occurred. One of honored, violated, not_applicable, unknown, or NULL (rows written before the 1.0.8 migration). See Content Signals. |
content_signal_violation_type | VARCHAR(16) | When content_signal_honored = 'violated', which signal was crossed: ai-train, ai-input, or search. |
web_bot_auth_status | VARCHAR(20) | Indexed with occurred_at via idx_wba_status_occurred. One of verified, invalid_signature, unknown_operator, no_signature, or NULL. See Web Bot Auth. |
web_bot_auth_operator | VARCHAR(32) | When a signature was matched (verified or invalid), the operator id (for example openai). NULL for no_signature and unknown_operator. |
raif_daily_rollup
Per-bot per-day aggregate. Rebuilt hourly by cron for today and yesterday; unique on (rollup_date, bot_id). The dashboard’s hit counts read the invocation log directly, not this table.
| Column | Type | Notes |
|---|---|---|
id | BIGINT UNSIGNED PK | Auto-increment. |
rollup_date | DATE | Indexed. |
bot_id, bot_category | VARCHAR | Same values as raif_invocation_log. |
hits, blocked, rate_limited | INT UNSIGNED | Counts within the day. |
bytes_total | BIGINT UNSIGNED | Sum of response bytes served to this bot on this day. |
unique_ips, unique_paths | INT UNSIGNED | Distinct-count within the day. |
raif_bot_policy
Per-bot overrides. Small table with one row per customized bot. Absence of a row means the global raif_default_policy applies.
| Column | Type | Notes |
|---|---|---|
id | BIGINT UNSIGNED PK | Auto-increment. |
bot_id | VARCHAR(64) UNIQUE | Catalog identifier. Unique. One override per bot. |
action | VARCHAR(16) | One of allow, log-only, rate-limit, paywall-redirect, block. |
rate_limit_per_min | SMALLINT UNSIGNED | Requests per minute for the rate-limit action. Also enforced as a rate limit when set on an allow or log-only row. NULL disables. |
paywall_url | VARCHAR(2048) | Redirect target for the paywall-redirect action. Empty means a 402 response instead of a redirect. |
policy_source | VARCHAR(32) | Indexed via idx_policy_source. One of manual (customer-set, default), auto-cs-violation (written by the Content Signals auto-block engine). Rows written before the 1.0.8 migration are treated as manual. |
auto_reason | VARCHAR(255) | For auto-generated rows only. Human-readable explanation displayed in the policy list (for example, Auto-blocked: violated ai-train signal (12 hits in 24 hours)). |
updated_at, updated_by_user_id | DATETIME, BIGINT | Audit trail. |
raif_bot_access_baseline
Rolling per-bot-per-day verified-hit counts backing the Bot Access monitor’s passive check. Small table capped at ~150 rows (30 days × ~5 watched bots).
| Column | Type | Notes |
|---|---|---|
id | BIGINT UNSIGNED PK | Auto-increment. |
bot_id | VARCHAR(64) | Indexed. Watched bot from raif_bot_access_watched_bots filter. |
day | DATE | Unique with bot_id via uk_bot_day. |
verified_hits | INT UNSIGNED | Count of forward-DNS-confirmed hits from this bot on this day. |
byte_total, updated_at | BIGINT, DATETIME | Bandwidth on this day; last update timestamp. |
raif_page_type_daily
Bot hits grouped by day, page type, and bot. Rebuilt hourly by the same cron as raif_daily_rollup and read by the dashboard’s page-type views. Unique on (rollup_date, page_type, bot_id).
| Column | Type | Notes |
|---|---|---|
id | BIGINT UNSIGNED PK | Auto-increment. |
rollup_date, page_type, bot_id | DATE, VARCHAR(64), VARCHAR(64) | Indexed as (page_type, rollup_date) and (bot_id, rollup_date). |
hits, blocked, rate_limited | INT UNSIGNED | Counts within the day. |
bytes_total | BIGINT UNSIGNED | Sum of response bytes. |
unique_ips | INT UNSIGNED | Distinct-count within the day. |
content_signal_violations, verified_hits, spoofed_hits | INT UNSIGNED | Content Signals violations and reverse-DNS outcomes within the day. |
Filters & Actions (for developers)
Royal AI Firewall exposes a small set of filters and actions for developers who want to customize behavior or hook into events.
Filters
| Filter | Returns | Purpose |
|---|---|---|
raif_log_retention_days | int (1–365) | Change the invocation log retention window. Default 7. |
raif_fingerprint_endpoint | string (URL) | Change the bot catalog endpoint, or return empty string to disable the daily fetch entirely (when opt-in is on). |
raif_should_skip_classification | bool | Return true to skip classification and logging for the current request. Useful for private admin areas or specific routes you never want in the log. |
raif_capture_response_bytes | bool | Return false to disable output-buffer response-size capture. Default true. Set false if a plugin/theme needs the OB layer for streaming or other purposes. |
raif_bot_access_watched_bots | string[] | Bot IDs the Bot Access monitor tracks for passive-decay detection. Default ['google-googlebot', 'microsoft-bingbot', 'apple-applebot', 'duckduckgo-bot']. |
raif_auto_block_threshold | int (≥1) | Content Signals violations required in the detection window before the auto-block engine creates a block policy. Default 3. Values below 1 fall back to default. |
raif_auto_block_window_hours | int (≥1) | Content Signals detection window in hours. Default 24. Values below 1 fall back to default. |
raif_web_bot_auth_operators | array | Full operator registry for Web Bot Auth key fetching. Add or replace entries keyed by operator id with {name, directory_url}. See Web Bot Auth. |
raif_auth_txt_contact | string (email) | Override the Contact address published in /auth.txt. Defaults to the raif_auth_txt_contact option (empty = no Contact line). |
raif_auth_txt_lines | string[] | Full override of the /auth.txt body. Return an array of lines; the plugin then applies line-safety (strip CR/LF, cap at 1024 chars per line, drop empty). |
Actions
| Action | Fires when | Args |
|---|---|---|
raif_request_classified | After every request is classified (bot or not; requests the plugin skips, such as wp-admin and authenticated Royal MCP calls, are not classified). | Classification $classification |
raif_policy_decided | After the policy engine decides on an action for a classified request. | PolicyDecision $decision, Classification $classification |
raif_request_blocked | Just before a blocked bot request is short-circuited with a 403. | Classification $classification, PolicyDecision $decision |
raif_policy_override_set | After a per-bot override is created or updated via the REST API, import handler, or auto-block engine. | string $bot_id, string $action, string $policy_source (the third arg was added in 1.0.8; 'manual' for customer writes, 'auto-cs-violation' for auto-block writes) |
raif_policy_override_cleared | After a per-bot override is deleted via the REST API. | string $bot_id |
raif_fingerprint_db_updated | After the bot catalog cache is replaced with a fresher snapshot. | string $new_version, string $old_version |
raif_log_pruned | After the daily retention prune runs. | int $deleted_count, string $cutoff |
raif_mcp_tool_logged | After a Royal MCP tool call is captured via the first-party bridge. | string $tool_name, string $status, Classification $classification |
raif_auto_blocked | Each time the Content Signals auto-block engine creates a new block policy. | string $bot_id, string $violation_type, int $hits |
raif_auto_block_swept | After the 6-hour auto-block sweep completes. | int $created (count of new auto-block policies written this sweep) |
raif_web_bot_auth_refreshed | After the Web Bot Auth key-directory refresh completes (weekly, while a toggle is on). | array $results (per-operator {status, keys} map) |
Example: log classification events to your own table
add_action( 'raif_request_classified', function( $classification ) {
if ( $classification->is_bot() && 'training-crawler' === $classification->category ) {
// Your own custom logging here
my_plugin_log_training_bot( $classification->bot_id, $classification->ip );
}
} );What’s New Modal
Royal AI Firewall ships a per-user, per-version release-news modal that auto-opens once on the next admin page load after a plugin update. It sits in the admin footer and never competes with WP’s admin_notices stack.
How auto-open works
Each user carries a user_meta key raif_whats_new_seen_version stamped with the plugin version they last dismissed the modal at. On every RAIF admin page load, the plugin compares that value against ROYAL_AI_FIREWALL_VERSION. If the stored value is empty or older, the modal auto-opens with a small delay after page paint. Dismissal (via the X, backdrop click, or Escape key) POSTs an AJAX request to stamp the current version onto user_meta, so it won’t auto-open again for that user until the next plugin release.
Re-opening on demand
A What’s New? button in the RAIF admin header (sitting alongside View Docs and Support) re-opens the modal at any time. Useful for reviewing release notes after dismissal, or for showing customers what changed without shipping a new version.
Reset for a user
Force the modal to re-show for a specific user by clearing their user_meta key:
delete_user_meta( $user_id, 'raif_whats_new_seen_version' );Or reset it for every admin at once:
global $wpdb;
$wpdb->delete( $wpdb->usermeta, array( 'meta_key' => 'raif_whats_new_seen_version' ) );The modal template at templates/admin/whats-new.php carries a Whats-New-For-Version: X.Y.Z marker in its docblock that matches the plugin version the modal content describes.
Community Support
Connect with other Royal AI Firewall users, ask questions, and share bot-blocking patterns on the WordPress.org support forums.
Visit WordPress.org Forums