JavaScript detections

  3 min read

JavaScript detections are another method that help Cloudflare identify bot requests.

These detections are optional, but lead to greater overall accuracy.

​​ What are JavaScript detections

These detections are implemented via a lightweight, invisible code injection that honors Cloudflare’s strict privacy standards Open external link . A small amount of JavaScript is injected into client devices using Google’s Picasso fingerprinting technique Open external link . Picasso results are factored into bot scores and help Cloudflare classify traffic as automated or human. BotScoreSrc: Not Computed and a score of 0 are relevant to Picasso JavaScript Fingerprinting requests. These are exempt from being blocked by any firewall rules.

This detection technique gathers general data about the machines reaching Cloudflare. For example, Cloudflare might learn that a particular user is accessing Cloudflare via Google Chrome on a MacBook Pro. Because there are millions of people using Google Chrome on a MacBook Pro, Cloudflare cannot identify specific individuals. Cloudflare also takes steps to anonymize and phase out data for added privacy.

JavaScript is injected only in response to requests for HTML pages or page views, excluding AJAX calls. API and mobile app traffic is unaffected. Additionally, code is not injected again until its 30-minute session life expires. After page load, the Picasso script is deferred and utilizes a separate thread (where available) to ensure that performance impact is minimal.

The snippets of JavaScript will contain a source pointing to the challenge platform with paths that start with /cdn-cgi/challenge-platform/....

​​ Implement JavaScript detections

To enable JavaScript Detections:

1. Log in to your Cloudflare dashboard Open external link and select your account and domain.
2. Go to Security > Bots.
3. Select Configure Bot Management.
4. For JavaScript Detections, switch the toggle to On.

Once you enable JavaScript detections, you can use the cf.bot_management.js_detection.passed field in Firewall rules (or the request.cf.botManagement.js_detection.passed variable in Workers).

When adding this field to Firewall rules, use it:

• On endpoints expecting browser traffic (avoiding native mobile applications or websocket endpoints).
• After a user’s first request to your application (Cloudflare needs at least one HTML request before injecting JavaScript detections).
• With the Managed Challenge action, because there are legitimate reasons a user might not have passed a JavaScript detection challenge (network issues, ad blockers, disabled JavaScript in browser, native mobile apps).

​​ Content Security Policies (CSPs)

If you have a Content Security Policy (CSP), you need to take additional steps to implement JavaScript detections:

• Ensure that anything under /cdn-cgi/challenge-platform/ is allowed. Your CSP should allow scripts served from your origin domain (script-src self).
• If your CSP uses a nonce for script tags, Cloudflare will add these nonces to the scripts it injects by parsing your CSP response header.
• If your CSP does not use nonce for script tags and JavaScript Detection is enabled, you may see a console error such as Refused to execute inline script because it violates the following Content Security Policy directive: "script-src 'self'". Either the 'unsafe-inline' keyword, a hash ('sha256-b123b8a70+4jEj+d6gWI9U6IilUJIrlnRJbRR/uQl2Jc='), or a nonce ('nonce-...') is required to enable inline execution. We highly discourage the use of unsafe-inline and instead recommend the use CSP nonces in script tags which we parse and support in our CDN.