XF Bot Guard 1.2.0
Release type: Major update
This release adds
Cloudflare Edge Enforcement, an optional new protection layer that allows XF Bot Guard to feed high-confidence application-level abuse intelligence back into Cloudflare.
For heavily botted forums using Cloudflare, this is a significant step forward. XF Bot Guard can now detect repeat abusive behaviour inside XenForo, promote the worst offending public IPs into a managed Cloudflare IP list, and have Cloudflare issue a Managed Challenge before those requests continue reaching XenForo.
In plain terms: XF Bot Guard still performs the intelligent application-level detection, but Cloudflare can now help enforce against repeat offenders at the edge.
Changes
- Added optional Cloudflare Edge Enforcement, allowing XF Bot Guard to escalate repeat high-confidence abusive IPs to Cloudflare.
- Added automatic Cloudflare IP list and WAF rule management, so repeat offenders can receive a Cloudflare Managed Challenge before reaching XenForo.
- Added local edge-candidate tracking so XF Bot Guard can identify, score, expire, and sync abusive IPs safely.
- Added dry-run mode, enabled by default, so site owners can review what would be synced before XF Bot Guard writes anything to Cloudflare.
- Added safety protections to avoid promoting staff, logged-in users, verified crawlers, excluded IPs, private/internal IPs, and manually protected IPs.
- Added Cloudflare setup, connection testing, health checks, manual sync, sync logs, candidate review, repair, and disable tools in the Admin Control Panel.
- Added encrypted storage for the Cloudflare API token.
- Added a manual never-export list for IPs that should not be synced to Cloudflare.
- Updated FingerprintJS from 5.1.0 to 5.2.0.
Why this matters
Before this release, XF Bot Guard could detect, score, challenge, deny, and log suspicious traffic once that traffic had already reached XenForo.
That is still useful, but repeat abusive traffic can still consume origin resources. The request still reaches Cloudflare, then your server, then PHP, then XenForo, then XF Bot Guard.
With Cloudflare Edge Enforcement enabled, XF Bot Guard can escalate the worst repeat offenders back to Cloudflare.
Before Cloudflare Edge Enforcement:
Code:
Bot or abusive client
-> Cloudflare
-> XenForo / PHP / database
-> XF Bot Guard detects, challenges, denies, or logs
After promotion and Cloudflare sync:
Code:
Bot or abusive client
-> Cloudflare Managed Challenge
-> usually never reaches XenForo
This is the important part of 1.2.0.
XF Bot Guard is no longer only protecting at the application layer after the request reaches XenForo. For suitable forums using Cloudflare, it can now contribute application-level intelligence back into the edge protection layer.
For heavily botted sites, this can be extremely valuable. Repeat abusive traffic can be challenged before it continues hitting PHP, XenForo routing, sessions, challenge pages, counters, logs, and database-backed behaviour checks.
This is not intended to replace XF Bot Guard's normal protection. It is an escalation layer. XF Bot Guard identifies the behaviour inside XenForo, then Cloudflare helps absorb repeat abuse earlier in the request path.
How IP promotion works
XF Bot Guard does not send every challenged visitor to Cloudflare.
Promotion is deliberately conservative.
An IP generally needs to be an anonymous public IP showing repeated or high-confidence abusive behaviour. XF Bot Guard looks for signals such as excessive request velocity, repeated failed validation, repeated CAPTCHA failure or rate limiting, suspicious automation behaviour, invalid collector/proof activity, abnormal fingerprint behaviour, and other strong bot-like patterns.
Some severe events may be promoted faster than weaker signals, but XF Bot Guard still applies safety checks first.
XF Bot Guard is designed to avoid promoting:
- staff members;
- logged-in users;
- verified crawlers;
- private, reserved, or internal IP ranges;
- IPs excluded from XF Bot Guard handling;
- IPs added to the never-export list.
This matters because Cloudflare Edge Enforcement is intended for repeat anonymous abuse, not normal members, staff, or legitimate crawlers.
What happens when a promoted IP returns
When a promoted IP has been synced to Cloudflare, Cloudflare applies a Managed Challenge before the request reaches XenForo.
This does not mean the IP is permanently banned.
A Cloudflare Managed Challenge is intentionally softer than a hard block. Many real human visitors can pass it. Many bots, scripts, scrapers, headless clients, and low-quality automated requests cannot.
That is the balance XF Bot Guard is aiming for: move repeat abuse away from the origin, without turning the feature into a blunt permanent firewall ban.
Cloudflare rule used
XF Bot Guard manages a Cloudflare WAF rule using its managed IP list.
The rule is based on this logic:
Code:
(ip.src in $xf_bot_guard_edge_ips and not cf.client.bot)
The action is:
This means requests from IPs in the XF Bot Guard managed list receive a Cloudflare Managed Challenge, while Cloudflare-recognised verified bots are excluded.
A quick note on the Admin Control Panel pages
Before the setup instructions, a fair warning: the Cloudflare Edge Enforcement ACP pages are functional, but they are still very much first-pass admin pages.
They do what they need to do: setup, health checks, candidate review, sync logs, repair actions, and disable tools are all there. But, like some of XF Bot Guard's existing reports and tables, they are not yet as tidy or polished as I want them to be.
The protection layer is the important part of this release, and that is where the focus has been. The next minor releases will be concentrating heavily on admin quality-of-life improvements, tidier tables, clearer reports, better page flow, and generally making the ACP feel less like it was assembled during a bot attack.
Which, to be fair, parts of it probably were.
Setup
Cloudflare Edge Enforcement is optional and disabled by default.
Dry-run mode is enabled by default. In dry-run mode, XF Bot Guard can evaluate and queue local candidates, but it will not write changes to Cloudflare.
To set it up:
- Upgrade XF Bot Guard to 1.2.0.
- Review your privacy policy before enabling raw IP storage.
- In the Admin Control Panel, go to Add-ons.
- Open XF Bot Guard -> Cloudflare Edge Enforcement.
- Open Setup using the top-right button.
- Enable raw IP storage.
- Enable Cloudflare Edge Enforcement.
- Leave Dry-run mode enabled for now.
- In a new browser tab, log in to Cloudflare.
- Copy your Cloudflare Account ID and Cloudflare Zone ID into the XF Bot Guard setup page. Cloudflare documentation: Find account and zone IDs
- Back in the XF Bot Guard setup page, click Create Cloudflare API token.
- Create the Cloudflare API token using the pre-filled permissions.
- Copy the Cloudflare API token into the XF Bot Guard setup page.
- Press Save.
- After saving, scroll down and click Set up Cloudflare automatically.
- Return to the Cloudflare Edge Enforcement overview.
- Click Sync now.
- Review the health checks.
- Periodically open Candidates to review what XF Bot Guard would sync while dry-run mode is still enabled.
- Once you are happy with what Cloudflare Edge Enforcement would have enforced, go back to Setup and disable dry-run mode.
- Run Sync now again, or allow the cron to perform the next sync automatically.
After that, the integration is active. The cron will keep the Cloudflare list in sync automatically.
At the time of this release, XF Bot Guard expects Cloudflare permissions for account rule lists, zone read access, and zone WAF editing. The setup page provides guidance and the API token link is pre-filled with the required permissions.
Important notes
This is a major update.
The Cloudflare Edge Enforcement layer is optional. If you do not use Cloudflare, or do not want XF Bot Guard to manage a Cloudflare IP list and WAF rule, you can leave this feature disabled.
This feature is most valuable for forums that are already behind Cloudflare and receive heavy bot, scraper, spam, automation, or abusive guest traffic.
Raw IP storage is required for Cloudflare Edge Enforcement. XF Bot Guard cannot sync an IP to Cloudflare if it is only storing hashed IP data. Before enabling raw IP storage, review your own privacy policy and local requirements.
Dry-run is enabled by default for a reason. Use it first. It allows you to see what XF Bot Guard would do before it starts writing to Cloudflare.
You should be reasonably comfortable with Cloudflare before enabling this feature. You do not need to be a Cloudflare expert, and XF Bot Guard provides setup, test, sync, health check, repair, and disable tools. However, this feature does interact with Cloudflare account-level lists and zone WAF rules, so it should be enabled carefully rather than blindly switched on.
As noted above, the next minor releases will focus heavily on admin quality-of-life improvements across XF Bot Guard.
Cloudflare Edge Enforcement should be treated as an escalation layer, not a replacement for XF Bot Guard's normal protection. XF Bot Guard still performs the application-level detection. Cloudflare simply helps enforce against the worst repeat offenders earlier, before they continue consuming XenForo resources.
