← Bots / bots / additional-configurations

JavaScript Detections

JavaScript Detections is a type of challenge separate from Cloudflare’s Challenge Pages or Turnstile. JavaScript Detections helps Cloudflare's bot solutions identify automated requests.

While Challenge Pages and Turnstile rely on client-side signals to determine the authenticity of a request, Bot Management’s JavaScript Detections relies on client-side signals and runs on every single request made to your website.

JavaScript Detections is implemented on your website via a lightweight, invisible JavaScript code snippet that follows Cloudflare's privacy standards ↗.

JavaScript is injected only in response to requests for HTML pages or page views, excluding AJAX calls. API and mobile application traffic is unaffected.

JavaScript Detections has a lifespan of 15 minutes. However, the code is injected again before the session expires. After page load, the 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/…

Once JavaScript Detections is injected on the HTML page, the visitor's browser will run the JavaScript code snippet and a cf_clearance cookie is issued to the visitor. The information in JavaScript Detections is stored in the cf_clearance cookie and is used to populate js_detection.passed.

• If the visitor is verified and a cf_clearance cookie is issued, it will contain the outcome: cf.bot_management.js_detection.passed = true
• If the verification fails, the cookie will contain the outcome: cf.bot_management.js_detection.passed = false

When the visitor encounters a WAF custom rule on your website, the rule will check the outcome of the cf_clearance cookie. The outcome of the cf_clearance cookie determines whether the request passes, or is blocked or challenged.

Refer to the steps below to enable and enforce JavaScript Detections.

For Bot Fight Mode customers, JavaScript Detections is automatically enabled and cannot be disabled.

For Super Bot Fight Mode and Bot Management for Enterprise customers, JavaScript Detections is optional.

For more details on how to set up bot protection, refer to the Bots documentation.

Once you enable JavaScript detections, you must use the cf.bot_management.js_detection.passed field to create WAF custom rules (or the request.cf.botManagement.jsDetection.passed variable in Workers).

When adding this field to WAF custom rules, it is used 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 detection), and 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 applications).

• You must have an Enterprise Bot Management subscription.
• You must have JavaScript Detections enabled on your zone.
• You must have updated your Content Security Policy headers for JavaScript detections.
• You must not run this field on websocket endpoints.
• You must use the field in a custom rules expression that expects only browser traffic.
• The action should always be a managed challenge in case a legitimate user has not received the challenge for network or browser reasons.
• The path specified in the rule builder should never be the first HTML page a user visits when browsing your site.

The cf.bot_management.js_detection.passed field should never be used in a WAF custom rule that matches a visitor's first request to a site. It is necessary to have at least one HTML request before Cloudflare can inject JavaScript detection.

(http.request.uri.path eq "/api/v4/user/create" and http.request.method eq "POST" and not cf.bot_management.verified_bot)
and (cf.bot_management.score lt 30 or !cf.bot_management.js_detection.passed)

"botManagement": {
"jsDetection": {
    "passed": false
}
}

Refer to the WAF documentation for more information on creating a custom rule.

If you enable JavaScript Detections via the dashboard, Cloudflare will insert a script tag in all HTML pages served on your website. If you would prefer to limit where JavaScript Detections is served, you can do so with the JavaScript Detections API script.

The JavaScript Detections API allows you more granular control over when and where JavaScript Detections is injected on your website, as well as an option for callback handling (for logging or other additional actions).

You can explicitly add a script reference to /cdn-cgi/challenge-platform/scripts/jsd/api.js and your own code calling window.cloudflare.jsd.executeOnce on specific HTML pages of your website.

The following script must be added to every page that you wish to have JavaScript Detections enabled:

<script>

function jsdOnload(){
  window.cloudflare.jsd.executeOnce(
    {
      callback: function(result){
        console.log('jsd outcome', result);
      }
    }
  );
}
</script>
<script src="/cdn-cgi/challenge-platform/scripts/jsd/api.js?onload=jsdOnload" async>

JavaScript Detections does not guarantee a specific bot score.

• If the JavaScript Detections injection or execution fails and cf.bot_management.js_detection.passed = false, a separate Bot Management heuristic can still yield a 1 or higher bot score, independent of JavaScript Detections.
• If the JavaScript Detections passes, the final bot score may still be 1 due to other detection heuristics (for example, known malicious IP, signature detection, and more), resulting in js_detection.passed = true, but score = 1.

Customers who enabled Enterprise Bot Management before June 2020 do not have JavaScript Detections enabled by default (unless specifically requested). These customers can still enable the feature in the Cloudflare dashboard.

The first request from a new client to your website or application will generally not have JavaScript Detections data (cf.bot_management.js_detection.passed = false). This is because Cloudflare needs at least one HTML request before injecting JavaScript Detection and issuing the cf_clearance cookie.

Subsequent requests can include a cf_clearance cookie if JavaScript ran successfully.

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).
• For nonce script tags:

  • 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 Detections 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.

Enabling JavaScript Detections (JSD) will strip ETags from HTML responses where JSD is injected.

If the origin response includes a Cache-Control: no-transform directive, Cloudflare does not inject the JavaScript Detections script. The cf.bot_management.js_detection.passed field will show as missing for these requests.

To use JavaScript Detections, remove the no-transform directive from Cache-Control response headers on pages where you want JavaScript Detections to run. For more information, refer to Cache-Control directives.