XF Bot Guard 1.2.2
Release type: Major update
This release adds the new
XF Bot Guard Dashboard, a visual single-page overview designed to show what Bot Guard is doing, why traffic is being challenged, where suspicious activity is coming from, and whether the system is healthy.
This is not just a prettier log page.
The dashboard is designed to tell the full Bot Guard story:
- what protected traffic Bot Guard saw;
- what was handled before CAPTCHA;
- what reached the CAPTCHA;
- what passed, failed, or never completed the challenge;
- why sessions were considered suspicious;
- which routes are under pressure;
- what crawlers and edge systems are doing;
- whether the underlying telemetry and cleanup systems look healthy.
The screenshot above only shows part of it. There is quite a bit more further down the page, including traffic journey charts, challenge outcomes, interstitial/browser proof activity, risk signals, route pressure, CAPTCHA trust-window behaviour, crawler health, Cloudflare Edge Enforcement status, system health, and raw drill-down links.
After upgrading, go to:
Admin Control Panel -> Add-ons -> XF Bot Guard -> Dashboard
And enjoy.
Changes
- Added a new single-page visual Dashboard for XF Bot Guard.
- Added dashboard charts using locally bundled Apache ECharts.
- Added a clear overview section showing protected activity, challenged sessions, no CAPTCHA result sessions, CAPTCHA passes, current trusted sessions, crawler activity, and edge candidate/block counts.
- Added a traffic journey funnel showing the path from protected request through browser proof, risk checks, CAPTCHA challenge, CAPTCHA outcome, temporary trust, and rechallenge behaviour.
- Added challenge outcome reporting, including pass-only, fail-only, fail-then-pass, pending challenge, and no CAPTCHA result sessions.
- Added counter-based pressure trend charts for challenge/pass/fail activity.
- Added interstitial and browser validation reporting so site owners can see what is being handled before CAPTCHA.
- Added risk signal reporting, including top reason codes and risk score distribution.
- Added route pressure reporting to show which areas of the forum are attracting the most suspicious challenge activity.
- Added CAPTCHA trust-window reporting, including current trusted sessions and rechallenge behaviour after trust expiry.
- Added crawler health visibility, including known and verified crawler activity.
- Added Cloudflare Edge Enforcement visibility to the dashboard where the edge feature is available.
- Added system health and telemetry availability reporting.
- Added raw drill-down links from the dashboard back into the existing event log.
- Added configurable counter retention via the new Counter retention hours option.
- Changed counter cleanup so it now respects the configured counter retention option instead of always pruning after 48 hours.
- Improved handling of malformed requests with no User-Agent header so collector-token unavailability is handled cleanly without noisy server error logging.
- Improved dashboard table scrolling, chart spacing, chart expansion, and admin-page usability.
Why this matters
Before this release, XF Bot Guard already recorded a lot of useful information, but most of it lived in logs, counters, health pages, and specialised admin screens.
That was useful for debugging, but not ideal for quickly answering the big question:
Is Bot Guard working?
The new dashboard is intended to answer that quickly.
Instead of making you dig through raw events first, XF Bot Guard now gives you a visual summary of what it is seeing and how traffic is moving through the protection layers.
In plain terms, the dashboard helps show:
- how much protected traffic is being seen;
- how much suspicious traffic is reaching challenge logic;
- how much is failing or disappearing before completing CAPTCHA;
- which requests are likely automated, abandoned, or incompatible;
- which routes are attracting suspicious activity;
- which risk signals are causing challenges;
- whether crawlers and Cloudflare Edge Enforcement are behaving as expected;
- whether your telemetry is complete enough for each report.
Important: CAPTCHA pass is not treated as a human verdict
One important part of this dashboard is the wording.
XF Bot Guard does
not present a CAPTCHA pass as proof that a visitor is human.
A CAPTCHA pass means the session completed the proof step. It does not prove the session was human.
That distinction matters.
The dashboard deliberately uses wording such as:
- No CAPTCHA result
- Pending challenge
- Temporary trust window
- Maximum possible false-positive ceiling
- CAPTCHA pass is not a human verdict
This is more accurate than simply saying “humans passed” or “bots failed”.
Bot Guard is a layered system. Some weak bots are handled before CAPTCHA. Some suspicious JavaScript-capable sessions reach CAPTCHA. Some complete the proof step. Some fail. Some vanish. Some are temporarily trusted and later re-evaluated.
The new dashboard is built around that model.
The traffic journey is now much clearer
The new funnel chart is one of the most useful parts of the dashboard.
It shows the broad journey:
Code:
Protected activity
-> JS/browser interstitial
-> Browser proof collected
-> Risk checks triggered
-> CAPTCHA challenge shown
-> CAPTCHA passed / failed / no result
-> Temporary trust window
-> Rechallenged after trust expiry
This helps make clear that XF Bot Guard is not just a CAPTCHA wall.
The CAPTCHA layer only sees sessions that make it past the browser / JavaScript interstitial layer. Basic clients that cannot run JavaScript correctly may be removed earlier or may never produce a useful browser proof.
That is why the dashboard separates browser/interstitial activity from CAPTCHA challenge outcomes.
Data availability is now visible
The dashboard is telemetry-aware.
That means it does not silently pretend all reports are equally complete.
Some reports are based on counters. Some require retained event logs. Some use session state. Some use visitor/fingerprint state. Some depend on optional logging settings.
The dashboard now shows what data is available and how far back each source can reasonably report.
For example:
- counter-based reports are available up to the configured counter retention window;
- event-log reports depend on event logging and event retention;
- session-state reports depend on session retention;
- visitor/fingerprint reports depend on visitor retention;
- some drill-down reports may be partial if low-value allow events or browser validation allow events are not fully retained.
This matters because an empty chart is not always the same thing as “nothing happened”.
Sometimes it means the relevant telemetry was not retained, was sampled, or is outside the selected range.
The dashboard now makes that much clearer.
New configurable counter retention
Previous versions pruned counter data after 48 hours.
That worked, but it also meant counter-based charts were limited to a short window.
XF Bot Guard 1.2.2 adds a new configurable counter retention option.
You can now control how long counter data is retained, from 1 hour up to 720 hours.
This allows site owners to keep the previous lightweight short window, or extend counter retention for better dashboard trends.
No User-Agent collector-token log noise fixed
This release also cleans up an issue reported by Dragonfruit.
Some malformed bot requests were arriving with no User-Agent header at all. In that situation, XF Bot Guard could not generate the lightweight collector token because the token is intentionally bound to request characteristics, including the user agent.
The important part: normal visitors were not seeing a server error.
When this happened, Bot Guard already fell back to the normal challenge flow and sent the request to the CAPTCHA challenge page.
So this was not really a user-facing bug. It was an overly noisy server log entry for a malformed or obviously bot-like request.
XF Bot Guard now handles that condition cleanly.
No User-Agent still means no collector token, and the request still continues to the normal challenge path, but it no longer needs to be logged as a server error.
A quick note on the dashboard
This is the first major version of the new dashboard.
It is already much more useful than digging through raw logs for normal review work, but there will still be further improvements over time.
The goal is for the dashboard to become the main place you start when checking Bot Guard activity.
The raw event log is still there, and it still matters. But the normal workflow should now be:
Code:
Dashboard first
-> identify what looks interesting
-> drill down into logs only when needed
That should make day-to-day review much easier, especially on heavily botted forums.
Recommended after upgrading
After upgrading to XF Bot Guard 1.2.2:
- Go to Admin Control Panel -> Add-ons.
- Open XF Bot Guard -> Dashboard.
- Review the overview cards.
- Check the data availability section near the top.
- Scroll through the full dashboard, not just the screenshot area.
- Review the traffic journey funnel and challenge outcome charts.
- Check risk signals and routes under pressure.
- If you use Cloudflare Edge Enforcement, review the edge section as well.
- Adjust the new counter retention option if you want longer counter-based dashboard history.
Important notes
The dashboard is only as complete as the telemetry available to it.
If event logging is disabled, detailed event-log reports will not be available, but counter-based volume reports can still work.
If low-value allow events are sampled or not retained, ordinary allow-event drill-down may be incomplete.
If browser validation allow logging is disabled, volume charts may still be available from counters, but per-session browser-validation drill-down will be limited.
This is expected behaviour. The dashboard is designed to show these limitations rather than hide them.
Final note
This release is a significant admin visibility improvement for XF Bot Guard.
The protection has always been the important part, but visibility matters too. Site owners should be able to see what Bot Guard is doing, understand why it is happening, and follow the flow from protected traffic through to challenge outcomes and system health.
Upgrade, open the new Dashboard link, scroll through the full page, and enjoy.
