- Compatible XF 2.x versions
- 2.3
Visible brandingNo
XF Bot Guard
Challenge suspicious bots before they scrape your forum.
XF Bot Guard is a XenForo-native anti-scraping and bot challenge layer for public forums. It identifies risky visitor behaviour, builds reputation from hashed browser/session/IP signals, and challenges suspicious traffic using XenForo’s own CAPTCHA system.
It is built for forum owners who want a practical application-layer defence against anonymous crawlers, content scrapers, aggressive bots, repeated automated visitors, and browser-like traffic that basic blocks do not catch.
This is not a “CAPTCHA everyone” add-on. XF Bot Guard watches first, scores behaviour, gives normal browsers a short chance to identify themselves, and challenges visitors when their risk profile reaches your configured threshold.
What it protects against
XF Bot Guard combines local browser fingerprint collection, collector proof validation, browser coherence checks, request velocity, route awareness, IP/session/fingerprint reputation, CAPTCHA history, and XenForo route context.
It is designed to detect and challenge traffic showing signs such as:
Built for XenForo
XF Bot Guard runs inside XenForo. It understands forum routes, request methods, sessions, users, content context, CAPTCHA state, online activity, and XenForo’s normal page flow.
It does not require a proxy challenge page, external SaaS bot platform, paid fingerprinting service, or third-party XenForo add-on.
Native XenForo CAPTCHA challenge
XF Bot Guard uses the CAPTCHA provider configured in XenForo.
That keeps the challenge experience native to your forum. Configure CAPTCHA in XenForo first, then enable XF Bot Guard.
After a visitor completes CAPTCHA, Bot Guard temporarily trusts that visitor for the configured trust duration and returns them to the originally requested safe page where possible. Unsafe return targets are rejected automatically.
Safe challenge behaviour
XF Bot Guard challenges safe public page views. Other request types can still be observed, counted, and used for reputation where appropriate, but the CAPTCHA redirect is kept away from sensitive flows.
This protects forum browsing without breaking forms, AJAX, API requests, login/register flows, payment callbacks, webhook-style paths, static assets, or XenForo CAPTCHA routes.
In practical terms:
You decide what Bot Guard protects:
Explainable risk scoring
XF Bot Guard uses an explainable risk score. You can see why a visitor was allowed, observed, challenged, trusted, or failed.
Risk can increase from missing fingerprint data, missing cookie continuity, invalid collector proof, browser coherence contradictions, automation markers, changing IP/fingerprint relationships, route probing, scraping-sensitive route families, high velocity, and CAPTCHA failures.
Risk can decrease for logged-in users, staff, recently verified visitors, and trusted known crawler requests when that feature is safely enabled.
You control the challenge threshold. Suggested starting points are shown in the options.
Browser collector and proof validation
XF Bot Guard includes a local browser collector using the bundled FingerprintJS library.
The collector posts a hashed visitor signal and lightweight browser continuity/coherence metadata back to XenForo. It also uses short-lived server-issued proof so collector submissions are tied to the current page, session, and timing window.
Invalid, expired, reused, missing, or mismatched proof is not accepted as trusted browser evidence. It is handled safely and can contribute to scoring/logging.
Operational counters without audit-log bloat
XF Bot Guard keeps short-window operational counters separately from retained audit logs.
That matters on real forums. Scoring and rate-limit decisions can continue to use recent activity counters even when routine low-value allow/skip rows are not written to the event log.
Security-relevant events remain available for review when audit logging is enabled, while normal safe browsing does not have to create a log row for every ordinary request.
Event log and decision visibility
The admin event log shows Bot Guard decisions and the reasons behind them.
Logged events can include:
Admin health/status page
XF Bot Guard includes a health/status page in the admin control panel.
It checks the add-on toggle, JavaScript collector status, XenForo CAPTCHA configuration, PAGE_CONTAINER template modification, bundled JavaScript assets, audit logging, low-value logging, event/session/visitor retention, counter retention, known crawler trust, origin-lockdown acknowledgement, event/counter table size, and hash-secret/globalSalt availability.
Current visitors visibility
Bot Guard verification routes appear clearly in XenForo’s Current visitors / Members online area.
Challenged visitors can also be separated into a Bot Guard “Bots” count, so they do not inflate normal online visitor totals while they are still pending verification.
The activity text does not expose return URLs, visitor hashes, IP hashes, fingerprint IDs, collector proof values, or challenge metadata.
Known crawler support
XF Bot Guard can trust known verified crawler headers when you explicitly enable that option.
Use this only when the headers come from trusted infrastructure and visitors cannot bypass that infrastructure to hit your origin directly. The health page includes an origin-lockdown acknowledgement check for this reason.
When trusted crawler handling is enabled and a request matches a known crawler header, Bot Guard can allow the request at the decision layer while still scoring and logging it for visibility.
Privacy-conscious storage
XF Bot Guard is designed not to store raw IP addresses or raw browser fingerprint IDs in its own tables.
It stores hashed identifiers for reputation and anti-abuse decisions. Browser fingerprint collection runs locally with the bundled FingerprintJS library. No external fingerprinting account is required.
Bot Guard stores compact anti-abuse metadata and browser-coherence signals. It does not store raw FingerprintJS component entropy by default, and raw collector proof values are not stored in the event log.
Site owners should still update their privacy policy because the add-on performs anti-abuse fingerprinting, behavioural monitoring, and challenge decisions.
No external service required
XF Bot Guard does not require:
Works alongside Cloudflare and server security
Cloudflare, WAF rules, server firewall rules, and rate limits can block traffic before it reaches XenForo.
XF Bot Guard works at the XenForo layer, where it can see forum routes, sessions, cookies, CAPTCHA trust, collector state, content context, and hashed visitor reputation.
Use it as an additional XenForo-native layer, not as a replacement for good server/CDN security.
What this is not
XF Bot Guard is not a firewall, reverse proxy, CDN, WAF, nginx rule, Apache rule, LiteSpeed rule, or iptables block.
It does not stop requests before they reach PHP.
A sophisticated scraper using a real browser, stable cookies, JavaScript execution, careful timing, and CAPTCHA solving can still pass. XF Bot Guard is built to stop, slow, and expose unwanted automated visitors by forcing risky traffic through an explainable XenForo challenge flow.
Requirements
XF Bot Guard
Challenge suspicious bots before they scrape your forum.
XF Bot Guard is a XenForo-native anti-scraping and bot challenge layer for public forums. It identifies risky visitor behaviour, builds reputation from hashed browser/session/IP signals, and challenges suspicious traffic using XenForo’s own CAPTCHA system.
It is built for forum owners who want a practical application-layer defence against anonymous crawlers, content scrapers, aggressive bots, repeated automated visitors, and browser-like traffic that basic blocks do not catch.
This is not a “CAPTCHA everyone” add-on. XF Bot Guard watches first, scores behaviour, gives normal browsers a short chance to identify themselves, and challenges visitors when their risk profile reaches your configured threshold.
What it protects against
XF Bot Guard combines local browser fingerprint collection, collector proof validation, browser coherence checks, request velocity, route awareness, IP/session/fingerprint reputation, CAPTCHA history, and XenForo route context.
It is designed to detect and challenge traffic showing signs such as:
- No JavaScript or fingerprint signal
- Missing or inconsistent Bot Guard cookies
- No browser proof signals at all
- Missing, expired, invalid, reused, or mismatched collector proof
- Browser identity, platform, screen, language, timezone, or request-header contradictions
- WebDriver, headless browser, automation, or browser-control artefacts
- Suspiciously thin rendering/resource-loading profiles
- One browser-like identity appearing across multiple IPs
- One IP appearing with many browser identities
- Unexpected User-Agent changes
- Country/ASN changes where trusted proxy headers provide that data
- Unusual request velocity
- Repeated sensitive-route or error-route hits
- Search, find-new, listing, member, profile, and deep-pagination patterns commonly associated with scraping
- Recent CAPTCHA failure
Built for XenForo
XF Bot Guard runs inside XenForo. It understands forum routes, request methods, sessions, users, content context, CAPTCHA state, online activity, and XenForo’s normal page flow.
It does not require a proxy challenge page, external SaaS bot platform, paid fingerprinting service, or third-party XenForo add-on.
Native XenForo CAPTCHA challenge
XF Bot Guard uses the CAPTCHA provider configured in XenForo.
That keeps the challenge experience native to your forum. Configure CAPTCHA in XenForo first, then enable XF Bot Guard.
After a visitor completes CAPTCHA, Bot Guard temporarily trusts that visitor for the configured trust duration and returns them to the originally requested safe page where possible. Unsafe return targets are rejected automatically.
Safe challenge behaviour
XF Bot Guard challenges safe public page views. Other request types can still be observed, counted, and used for reputation where appropriate, but the CAPTCHA redirect is kept away from sensitive flows.
This protects forum browsing without breaking forms, AJAX, API requests, login/register flows, payment callbacks, webhook-style paths, static assets, or XenForo CAPTCHA routes.
In practical terms:
- Suspicious behaviour can be monitored across safe request contexts.
- CAPTCHA challenges occur on safe primary page navigation requests.
- Visitors who pass CAPTCHA are trusted for the configured trust window.
- Visitors who fail or cannot complete CAPTCHA cannot continue freely through protected pages.
- Successful visitors are returned to the original safe page where possible.
You decide what Bot Guard protects:
- All public pages
- Threads only
- Threads plus forums
- Selected content types
- Selected route prefixes
- Custom path/route lists
- Guests only
- Guests plus registered users
- Guests plus registered users except staff
- Excluded user groups
- Excluded IPs/CIDRs
Explainable risk scoring
XF Bot Guard uses an explainable risk score. You can see why a visitor was allowed, observed, challenged, trusted, or failed.
Risk can increase from missing fingerprint data, missing cookie continuity, invalid collector proof, browser coherence contradictions, automation markers, changing IP/fingerprint relationships, route probing, scraping-sensitive route families, high velocity, and CAPTCHA failures.
Risk can decrease for logged-in users, staff, recently verified visitors, and trusted known crawler requests when that feature is safely enabled.
You control the challenge threshold. Suggested starting points are shown in the options.
Browser collector and proof validation
XF Bot Guard includes a local browser collector using the bundled FingerprintJS library.
The collector posts a hashed visitor signal and lightweight browser continuity/coherence metadata back to XenForo. It also uses short-lived server-issued proof so collector submissions are tied to the current page, session, and timing window.
Invalid, expired, reused, missing, or mismatched proof is not accepted as trusted browser evidence. It is handled safely and can contribute to scoring/logging.
Operational counters without audit-log bloat
XF Bot Guard keeps short-window operational counters separately from retained audit logs.
That matters on real forums. Scoring and rate-limit decisions can continue to use recent activity counters even when routine low-value allow/skip rows are not written to the event log.
Security-relevant events remain available for review when audit logging is enabled, while normal safe browsing does not have to create a log row for every ordinary request.
Event log and decision visibility
The admin event log shows Bot Guard decisions and the reasons behind them.
Logged events can include:
- Challenge required events
- CAPTCHA pass/fail/rate-limit events
- Known crawler allow decisions
- Collector submissions and collector proof failures
- Browser re-collection requests
- Route, controller, action, method, and path context
- Reason codes and risk score
- Hashed visitor, IP, session, URI, and referrer identifiers
- Decision timing metadata
Admin health/status page
XF Bot Guard includes a health/status page in the admin control panel.
It checks the add-on toggle, JavaScript collector status, XenForo CAPTCHA configuration, PAGE_CONTAINER template modification, bundled JavaScript assets, audit logging, low-value logging, event/session/visitor retention, counter retention, known crawler trust, origin-lockdown acknowledgement, event/counter table size, and hash-secret/globalSalt availability.
Current visitors visibility
Bot Guard verification routes appear clearly in XenForo’s Current visitors / Members online area.
Challenged visitors can also be separated into a Bot Guard “Bots” count, so they do not inflate normal online visitor totals while they are still pending verification.
The activity text does not expose return URLs, visitor hashes, IP hashes, fingerprint IDs, collector proof values, or challenge metadata.
Known crawler support
XF Bot Guard can trust known verified crawler headers when you explicitly enable that option.
Use this only when the headers come from trusted infrastructure and visitors cannot bypass that infrastructure to hit your origin directly. The health page includes an origin-lockdown acknowledgement check for this reason.
When trusted crawler handling is enabled and a request matches a known crawler header, Bot Guard can allow the request at the decision layer while still scoring and logging it for visibility.
Privacy-conscious storage
XF Bot Guard is designed not to store raw IP addresses or raw browser fingerprint IDs in its own tables.
It stores hashed identifiers for reputation and anti-abuse decisions. Browser fingerprint collection runs locally with the bundled FingerprintJS library. No external fingerprinting account is required.
Bot Guard stores compact anti-abuse metadata and browser-coherence signals. It does not store raw FingerprintJS component entropy by default, and raw collector proof values are not stored in the event log.
Site owners should still update their privacy policy because the add-on performs anti-abuse fingerprinting, behavioural monitoring, and challenge decisions.
No external service required
XF Bot Guard does not require:
- A paid subscription
- An API key
- A cloud account
- A CDN account
- An external bot-detection service
- A third-party XenForo add-on
Works alongside Cloudflare and server security
Cloudflare, WAF rules, server firewall rules, and rate limits can block traffic before it reaches XenForo.
XF Bot Guard works at the XenForo layer, where it can see forum routes, sessions, cookies, CAPTCHA trust, collector state, content context, and hashed visitor reputation.
Use it as an additional XenForo-native layer, not as a replacement for good server/CDN security.
What this is not
XF Bot Guard is not a firewall, reverse proxy, CDN, WAF, nginx rule, Apache rule, LiteSpeed rule, or iptables block.
It does not stop requests before they reach PHP.
A sophisticated scraper using a real browser, stable cookies, JavaScript execution, careful timing, and CAPTCHA solving can still pass. XF Bot Guard is built to stop, slow, and expose unwanted automated visitors by forcing risky traffic through an explainable XenForo challenge flow.
Requirements
- XenForo 2.1.0+
- PHP 7.2+
- A configured XenForo CAPTCHA provider for challenge use
- A theme that includes the standard PAGE_CONTAINER output
- Upload the add-on files to your XenForo installation.
- Install XF Bot Guard from the XenForo admin control panel.
- Configure XenForo CAPTCHA if it is not already configured.
- Review the Bot Guard options.
- Review the Bot Guard health/status page.
- Enable the add-on.
- Monitor the event log and adjust the threshold/scope as needed.
- Confirm XenForo CAPTCHA is configured and working.
- Confirm the Bot Guard JavaScript files are reachable.
- Confirm the PAGE_CONTAINER template modification is enabled.
- If using a proxy/CDN, confirm XenForo receives the correct real visitor IP.
- If trusting known crawler headers, confirm direct origin access is blocked first.
- Start with guests only and the default threshold before tightening.
