Skip to content

非公式本サイトは非公式の日本語ドキュメントであり、Cloudflare 公式サイトではありません。最新情報はdevelopers.cloudflare.comをご確認ください。

JavaScript Detections

最終更新 Markdown で表示Agent セットアップ

JavaScript Detections は、Cloudflare の Challenge Pages や Turnstile とは別の Challenge です。Cloudflare の ボット対策 が、自動化されたリクエストを識別しやすくします。

Challenge Pages と Turnstile は、リクエストの正当性を判断するためにクライアントサイドのシグナルを使います。一方、Bot Management の JavaScript Detections はクライアントサイドのシグナルを使い、サイトへのすべてのリクエストで実行されます。

処理の流れ

JavaScript Detections は、Cloudflare の プライバシー基準 ↗ に沿った、軽量で不可視の JavaScript コード断片としてサイトに実装されます。

JavaScript が注入されるのは、HTML ページまたはページビューへのリクエストに対してだけです。AJAX 呼び出しは対象外です。API とモバイルアプリのトラフィックには影響しません。

JavaScript Detections の有効期間は 15 分です。ただし、セッションが切れる前にコードは再注入されます。ページ読み込み後、スクリプトは遅延実行され、利用できる場合は別スレッドを使うため、性能への影響は小さくなります。JavaScript 断片のソースは Challenge Platform を指し、パスは /cdn-cgi/challenge-platform/… で始まります。

HTML ページに JavaScript Detections が注入されると、訪問者のブラウザーが JavaScript コード断片を実行し、訪問者に cf_clearance Cookie が発行されます。JavaScript Detections の情報は cf_clearance Cookie に保存され、js_detection.passed の値に使われます。

  • 訪問者が検証され cf_clearance Cookie が発行された場合、結果は cf.bot_management.js_detection.passed = true です
  • 検証に失敗した場合、Cookie の結果は cf.bot_management.js_detection.passed = false です

訪問者がサイト上の WAF カスタムルールに当たると、ルールは cf_clearance Cookie の結果を確認します。この結果によって、リクエストが通過するか、ブロックまたは Challenge されるかが決まります。

JavaScript Detections の有効化と強制は、次の手順で行います。

1. JavaScript Detections を有効にする

Bot Fight Mode のお客様では、JavaScript Detections は automatically enabled and cannot be disabled です。

Super Bot Fight Mode and Bot Management for Enterprise のお客様では、JavaScript Detections は optional です。

  1. Cloudflare ダッシュボードで Security Settings ページを開きます。

    Settings を開く ↗

  2. ボットトラフィックプランの設定で、JS detections の編集アイコンを選び、JavaScript Detections をオンにします。

ボット対策の設定の詳細は、Bots のドキュメント を参照してください。

2. JavaScript Detections の実行を強制する

JavaScript Detections を有効にしたら、cf.bot_management.js_detection.passed フィールドで WAF カスタムルール を作成する必要があります（Workers では request.cf.botManagement.jsDetection.passed 変数）。

このフィールドを WAF カスタムルールに入れる場合は、ブラウザー向けトラフィックを想定するエンドポイントで使います（ネイティブモバイルアプリや WebSocket エンドポイントは避けます）。ユーザーの最初のリクエストより後に使い（JavaScript Detection を注入するには、Cloudflare に少なくとも 1 回の HTML リクエストが必要です）、アクションは Managed Challenge にします。ネットワーク障害、広告ブロッカー、ブラウザーで JavaScript が無効、ネイティブモバイルアプリなど、正当な理由で JavaScript Detection Challenge に合格していないことがあるためです。

前提条件

  • Enterprise Bot Management のサブスクリプションが必要です。
  • ゾーンで JavaScript Detections が有効である必要があります。
  • JavaScript Detections 向けに Content Security Policy ヘッダーを更新 している必要があります。
  • このフィールドを WebSocket エンドポイントで実行しないでください。
  • ブラウザー向けトラフィックだけを想定するカスタムルール式で、このフィールドを使ってください。
  • 正当なユーザーがネットワークやブラウザーの事情で Challenge を受け取っていない場合に備え、アクションは常に Managed Challenge にしてください。
  • ルールビルダーで指定するパスは、ユーザーがサイトを閲覧するときの最初の HTML ページにしないでください。

cf.bot_management.js_detection.passed フィールドは、訪問者のサイトへの最初のリクエストに一致する WAF カスタムルールでは使わないでください。Cloudflare が JavaScript Detection を注入するには、少なくとも 1 回の HTML リクエストが必要です。

(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
}
}

カスタムルールの作成については、WAF のドキュメント を参照してください。

API

ダッシュボードで JavaScript Detections を有効にすると、Cloudflare はサイトで配信するすべての HTML ページに script タグを挿入します。JavaScript Detections を出す場所を絞りたい場合は、JavaScript Detections API スクリプトを使えます。

JavaScript Detections API を使うと、サイトのどこでいつ JavaScript Detections を注入するかを細かく制御でき、コールバック処理（ログ記録や追加処理）も選べます。

特定の HTML ページで、/cdn-cgi/challenge-platform/scripts/jsd/api.js へのスクリプト参照と、window.cloudflare.jsd.executeOnce を呼び出す独自コードを明示的に追加できます。

JavaScript Detections を有効にしたい各ページに、次のスクリプトを追加します。

<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 は、特定のボットスコアを保証しません。

  • JavaScript Detections の注入または実行が失敗し、cf.bot_management.js_detection.passed = false でも、別の Bot Management ヒューリスティックが、JavaScript Detections とは独立してボットスコア 1 以上を出すことがあります。
  • JavaScript Detections に合格しても、ほかの検出ヒューリスティック（既知の悪意ある IP、シグネチャ検出など）により最終ボットスコアが 1 になることがあり、js_detection.passed = true でも score = 1 になります。

制限事項

2020 年 6 月より前に Bot Management を有効にした場合

2020 年 6 月より前に Enterprise Bot Management を有効にしたお客様は、特別な依頼がない限り、JavaScript Detections はデフォルトで有効になりません。これらのお客様は、Cloudflare ダッシュボードで機能を有効にできます。

サイトへの最初のリクエストの場合

新しいクライアントからサイトまたはアプリケーションへの最初のリクエストには、通常 JavaScript Detections のデータがありません（cf.bot_management.js_detection.passed = false）。Cloudflare が JavaScript Detection を注入して cf_clearance Cookie を発行するには、少なくとも 1 回の HTML リクエストが必要なためです。

以降のリクエストでは、JavaScript が正常に実行されていれば cf_clearance Cookie が付くことがあります。

Content Security Policy（CSP）がある場合

Content Security Policy（CSP） を使っている場合、JavaScript Detections を実装するには追加の手順が必要です。

  • /cdn-cgi/challenge-platform/ 以下をすべて許可します。CSP では、オリジンドメインから配信されるスクリプトを許可する必要があります（script-src self）。
  • nonce 付きの script タグについて:

    • CSP が script タグに nonce を使っている場合、Cloudflare は CSP レスポンスヘッダーを解析し、注入するスクリプトにこれらの nonce を追加します。

    • CSP が script タグに nonce を使っておらず、JavaScript Detections が有効な場合、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. のようなコンソールエラーが出ることがあります。unsafe-inline の使用は強く非推奨です。代わりに、CDN で解析・対応している CSP の nonce を script タグで使うことを推奨します。

ETag がある場合

JavaScript Detections（JSD）を有効にすると、JSD が注入される HTML レスポンスから ETag が取り除かれます。

オリジンが no-transform ヘッダーを送る場合

オリジンのレスポンスに Cache-Control: no-transform ディレクティブがある場合、Cloudflare は JavaScript Detections スクリプトを注入しません。これらのリクエストでは、cf.bot_management.js_detection.passed フィールドは missing になります。

JavaScript Detections を使うには、実行したいページの Cache-Control レスポンスヘッダーから no-transform ディレクティブを外します。詳細は Cache-Control ディレクティブ を参照してください。

役に立ちましたか？