XF Bot Guard 1.1.5

XF Bot Guard

Challenge suspicious bots before they scrape your forum.

XF Bot Guard is a XenForo-native anti-scraping and bot challenge layer designed to identify suspicious visitor behaviour, build reputation over time, and challenge risky traffic using XenForo’s own CAPTCHA system.

It is built for forum owners who are tired of anonymous crawlers, scrapers, aggressive bots, and repeat automated visitors quietly consuming content, increasing server load, and bypassing basic protections.

This is not just a “show CAPTCHA to everyone” add-on. XF Bot Guard watches behaviour first, builds a picture of the visitor, and only challenges when the risk profile crosses your configured threshold.

What it does

XF Bot Guard combines browser fingerprinting, behavioural heuristics, IP/session reputation, route awareness, request velocity, and native XenForo CAPTCHA challenges.

It can help detect and challenge visitors showing signs such as:

• No JavaScript/fingerprint signal
• Missing or inconsistent cookies
• No browser proof signals at all
• Repeated access from changing IPs
• One fingerprint appearing across multiple IP addresses
• One IP appearing with multiple fingerprints
• Unusual request velocity
• Repeated probing of sensitive or error routes
• User agent changes
• Country/ASN changes where proxy headers are available
• Failed CAPTCHA attempts

The aim is simple:

Let normal visitors browse. Challenge suspicious visitors before they freely scrape protected forum pages.

It gets smarter as behaviour builds

XF Bot Guard does not need to instantly block or challenge every visitor on their very first request.

Instead, it monitors visitor behaviour and builds reputation using hashed browser, IP, and session signals. This means it can become more effective as the same bot, scraper, or crawler continues interacting with your forum.

This is especially useful for slower or more careful crawlers. A bot that avoids obvious high-speed scraping may still become suspicious over time as its fingerprint, IP usage, session continuity, route activity, and request history develop.

Native XenForo CAPTCHA challenge

XF Bot Guard uses XenForo’s configured CAPTCHA provider.

That means the challenge experience remains native to XenForo, instead of relying on an external challenge page, iframe, proxy, or third-party SaaS layer.

For best results, configure CAPTCHA in XenForo before enabling XF Bot Guard.

Challenge behaviour

XF Bot Guard challenges primary public page views. Other request types may still be observed and recorded where safe, but CAPTCHA challenges are intentionally performed on normal page navigation requests.

This avoids breaking forms, AJAX requests, payment callbacks, API requests, login/register flows, and other sensitive XenForo behaviour.

In practical terms:

• Suspicious behaviour can be monitored across multiple request types.
• The actual CAPTCHA challenge occurs on a safe page-view request.
• Visitors who cannot complete the challenge are effectively blocked from continuing through protected pages.

Protection modes

You can configure what Bot Guard protects, including:

• All public pages
• Threads only
• Threads and forums
• Selected content types
• Selected routes
• Custom paths

You can also configure who is in scope:

• Guests only
• Guests and registered users
• Guests and registered users except staff
• Excluded user groups

Transparent risk scoring

XF Bot Guard uses an explainable risk scoring system rather than a black box.

Risk can increase due to signals such as missing fingerprint data, no cookie continuity, unusual fingerprint/IP relationships, route probing, high request velocity, failed CAPTCHA attempts, and other suspicious behaviour.

Risk can decrease for trusted visitors, logged-in users, staff, and visitors who recently completed a CAPTCHA challenge.

You control the challenge threshold.

Event logging

XF Bot Guard includes an admin-side event log so you can inspect decisions and understand why traffic was allowed, monitored, skipped, challenged, or trusted.

Logged information can include:

• Decision type
• Event type
• Risk score
• Reason codes
• Route/controller/action context
• Request method
• Path
• Hashed visitor/IP/session identifiers
• CAPTCHA pass/fail events
• Bootstrap/grace events

Identifiers such as IP address, user agent, request URI, referrer, and fingerprint ID are hashed before storage.

Privacy-conscious by design

XF Bot Guard is designed to avoid storing raw IP addresses or raw browser fingerprint IDs in its own tables.

Instead, it stores hashed identifiers for reputation and abuse-detection purposes.

Browser fingerprint collection is performed locally using the bundled FingerprintJS library. No external fingerprinting service account is required.

Site owners should still update their privacy policy as appropriate, because this add-on performs anti-abuse fingerprinting and behavioural monitoring.

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
• Any third-party XenForo add-on

Everything runs inside XenForo.

Works well alongside Cloudflare or other edge protection

Cloudflare and similar services can block a lot of bad traffic before it reaches your server.

XF Bot Guard works at the XenForo layer, where it can see forum routes, sessions, cookies, fingerprints, content context, and XenForo-specific behaviour that a generic edge layer may not fully understand.

It is not a replacement for good server/CDN security. It is an additional XenForo-native layer.

What this is not

XF Bot Guard is not a firewall, reverse proxy, CDN, or web-server-level blocker.

It does not claim to stop every possible bot before the request reaches PHP.

A highly sophisticated scraper using a real browser, stable cookies, JavaScript execution, slow request patterns, and CAPTCHA solving may still be able to pass.

The goal is to stop or frustrate the majority of unwanted automated visitors by detecting suspicious behaviour and forcing them through a challenge before they can continue freely browsing protected content.

For most practical scrapers, failing the challenge means they are blocked.

Default behaviour

The default configuration is intended to be a sensible starting point:

• Protect public pages
• Scope to guests by default
• Use browser fingerprinting
• Use behavioural scoring
• Use XenForo CAPTCHA for challenges
• Allow a short bootstrap grace period so normal browsers have time to run JavaScript
• Prevent high-risk traffic with no browser proof from receiving initial bootstrap grace
• Trust visitors for a configurable period after a successful challenge
• Log security events for review

Beta notice

This is a beta release.

It is ready for testing and real-world use, but site owners should review the settings carefully and monitor the event log after installation.

Recommended approach:

• Install on a test/staging forum first if possible.
• Make sure XenForo CAPTCHA is configured.
• Start with the default settings.
• Test it using the test script shared in the FAQ.
• Review the event log.
• Adjust the challenge threshold and protection scope as needed.

Installation

1. Upload the add-on files to your XenForo installation.
2. Install XF Bot Guard from the XenForo admin control panel.
3. Configure XenForo CAPTCHA if it is not already configured.
4. Review the Bot Guard options.
5. Enable the add-on.
6. Monitor the Bot Guard log and adjust settings if required.

Recommended before enabling

• Confirm CAPTCHA is enabled in XenForo.
• Confirm your theme includes the standard PAGE_CONTAINER body output.
• Confirm JavaScript files are accessible from your forum.
• If using a CDN/proxy, make sure your real visitor IP handling is configured correctly in XenForo/server settings.
• If trusting verified bot headers, only do this when those headers come from infrastructure you control or trust, and your origin is not directly reachable.

License

Proprietary freeware.

This resource is free to use, but it is not open source. Redistribution, resale, sublicensing, publishing modified versions, or removing copyright/license notices is not permitted without written permission from the developer.

Summary

XF Bot Guard gives XenForo forums a native, configurable, explainable challenge layer for suspicious bots and scrapers.

It watches first, scores behaviour, builds reputation over time, and challenges risky visitors before they can continue freely browsing protected content.