Inference hooksを設定する — Shadow modeとサーキットブレーカー

この手順で設定できること

Inference hooksの設定は「有効化」→「エンドポイント接続」→「強制のオン」という3段階を踏みます。組織単位で機能を有効化してもEnforce verdictsは常に自動でオフになるため、有効化しただけで検査が始まることはありません。本記事はエンドポイントの接続からShadow modeでの検証、サーキットブレーカーが作動したときの挙動までを順に扱います。Inference hooks自体の仕組みはInference hooksとは、AIセキュリティサーバー本体の実装はverdict応答とWebhook署名検証を参照してください。

前提条件は3つです。

• Inference hooksは現在ベータ機能で、利用できるのはClaude Enterprise組織のみです
• claude.aiのorganization:manage権限。Team/Enterpriseの権限ロール一覧にあるとおり、組み込みのAdmin・Owner・Primary ownerロールがこれを保持し、この権限を付与された任意のカスタムロールも同じ権限を持ちます
• verdict(許可か拒否かの判定)リクエストを受け付けるAIセキュリティサーバーのHTTPSエンドポイント — ポート443のhttps://URL、公開ルーティング可能なホスト、リダイレクトなしで到達できること。ngrokなどのリバーストンネルサービスは非対応(Anthropicのネットワークポリシーがブロックする)

enforcement状態は3種類

設定を進める前に、Inference hooksが取り得る3状態を押さえておきます。

新規設定はoff → shadow → enforcingの順で進めるのが公式の推奨フローです。

組織でInference hooksを有効化する

claude.aiのOrganization settings > Data and privacyを開き、Inference hooksセクションでAllow for your organizationをオンにします。これでInference hooksの設定ページが開放されますが、Enforce verdictsは常に強制的にオフになるため、以前オンだった設定を持つ組織でも、最後にもう一度オンにするまで検査は始まりません。

設定ページ自体は独立したナビ項目ではなく、Data and privacy / Inference hooksというパンくずの下にあります。エンドポイントを保存するまでは「プロンプトはまだ検査されていません」という警告が表示され、Enforce verdictsはRequires endpointバッジ付きでオフのままです。

エンドポイントを設定してテストする

ConfigureをクリックするとConfigure endpointダイアログが開きます。入力するのは次の2項目です。

• Endpoint URL: verdictリクエストを受け取るhttps://のURL(https://以外は受け付けられません)
• Custom request headers: AIセキュリティサーバーが呼び出し元を認証するための静的ヘッダーを最大16個まで登録できます。値は暗号化されて保存され、保存後は名前しか表示されません。値は書き込み専用のため、ヘッダーを1つでも変更するときは全ヘッダーの値を再入力する必要があります。エンドポイントURLを変更すると保存済みのヘッダー値はすべてクリアされます(新しい送信先に古い認証情報が渡らないようにするため)

ヘッダー名は-区切りのHTTPトークン文字を使い、_は使えません。これらの予約名(Content-*やHostのようなリクエスト整形ヘッダー、プロキシ・クッキー系ヘッダー、X-Forwarded-*のようなクライアントアドレスヘッダー、webhook-*の署名ヘッダー、X-Anthropic-*プレフィックス)と同じ名前は使えません。値は印字可能なASCIIのみです。

入力を終えたらTest connectionをクリックします。Claudeは今フォームに入力されているURLとヘッダー(保存済みの値ではない)へ合成テストプロンプトを送り、AIセキュリティサーバーがallow(許可)とdeny(拒否)のどちらを返したかを結果に表示します。よくある失敗結果は次のとおりです。

# 管理画面でエンドポイントを保存する前に、自分のサーバーが
# 最小限のverdictを返せるか手元で確認しておくと手戻りが減る
curl -i -X POST https://your-security-server.example.com/verdict \
  -H "Content-Type: application/json" \
  -d '{"type":"prompt","request_id":"test_local","messages":[]}'

署名シークレットを保存する

エンドポイント設定を保存すると、初回保存時にWebhook署名シークレットが生成され、1回だけ画面に表示されます。この場で必ずコピーして安全な場所に控えてください。シークレットは後から再取得できず、ローテーションで差し替えるしかありません。AIセキュリティサーバーはこのシークレットを使って受信リクエストの署名を検証します(検証手順は署名検証の記事を参照)。

除外するロールを決める(Exclusions)

Exclusionsの下で、Inference hooksの対象から外すロールを選べます。選んだロールのメンバーが送るプロンプトはAIセキュリティサーバーへ送られません。除外できるのは組織が作成したカスタムロールだけで、組み込みロールは選択肢に出てきません。ロールセレクタのプレースホルダーはSelect roles to excludeで、各ロールの保有者管理はロール管理画面(Manage roles)で行い、除外リストの変更にはidentity management権限が必要です。既定ではリストは空で、除外ロールが無ければ組織の管理下にある全リクエストが検査対象になります。

除外が効くのはユーザーの対話セッションに限られ、機械認証(サービスアカウント等)のトラフィックは常に検査されます。Claudeがリクエスト元のロール所属を解決できない場合は、検査なしで通すのではなくretryable error(再試行可能なエラー)としてfail closed(処理を止める側)に倒れます。除外リストへの変更は監査証跡に記録されます。

ブロック時のメッセージをカスタムする(Custom blocked prompt message)

Custom blocked prompt messageでは、AIセキュリティサーバーがリクエストを拒否したときにエンドユーザーへ表示されるエラーに追記する文言を、最大500字まで設定できます(問い合わせ先や例外申請の案内などが典型です)。最終的な表示は、AIセキュリティサーバーがリクエストごとに返すdeny_reason(存在する場合)、空行、このカスタム文言の順に連結されます。カスタム文言を設定しなければ管理者への連絡を促す既定文言が表示され、この追記自体をオフにしてユーザーにdeny_reasonだけを見せることもできます。

失敗時の挙動とタイムアウトを選ぶ

Failure handlingの下でModeを選び、AIセキュリティサーバーが到達不能・タイムアウトのときの挙動を決めます。

• Block the request: verdictが得られないとき推論を止める(fail closed)
• Allow the request: 検査なしでリクエストをモデルへ通す(fail open)
• Shadow mode: これは失敗時ポリシーではなくロールアウト用のモードです(後述)

続けてPrompt verdict timeout (ms)を1〜10,000msの範囲で設定します(既定5,000ms)。このタイムアウトは接続・TLSハンドシェイク・リクエスト・応答の往復すべてを含み、遅い応答は到達不能なサーバーと同じ扱いになります。サーバーが確実に守れる範囲で最も低い値を選ぶのが安全です。このセクションの変更は入力するそばから保存され、初回保存時の既定値はAllow the requestと5,000msです。

ロールアウト率を決める

Rolloutの下、Requests inspected (%)でAIセキュリティサーバーを立ち上げている間に検査するリクエストの割合を決められます。0〜100の範囲で、100なら全件検査、0なら検査オフです。検査するかどうかの抽選は会話のターンごとに1回だけ行われるため、1つの会話の中でもターンによって検査されたりされなかったりします。サンプル対象外のリクエストは、Failure handlingがBlock the requestでも検査なしで通過します。

Shadow modeで実トラフィックを検証する

Shadow modeは、生のトラフィックに対してフックを走らせながら何もブロックしない状態です。AIセキュリティサーバーは検査対象のプロンプトを受け取りverdictを返しますが、サーバーがdenyを返しても、あるいは到達できなくても、全リクエストはそのままモデルへ進み、エンドユーザーには何も表示されません。強制を始める前に、自組織の実トラフィックに対してポリシーを調整する目的で使います。

Shadow modeを使うには、Failure handlingのModeをShadow modeに設定してからEnforce verdictsをオンにし、プロンプトがAIセキュリティサーバーへ流れるようにします。有効な間、設定ページにはShadow mode — not blockingバッジが表示されます。Shadow modeを抜けるにはModeをAllow the requestかBlock the requestに戻します。強制がオンなら、その時点から改めてverdictが実際に効き始めます。

検証結果はエンドポイント健全性パネルで見る

Shadow modeで走らせた検証結果は、設定ページのMonitor your AI security server欄にあるエンドポイント健全性パネルに表示されます。パネルの項目は次のとおりです。

• Endpoint status: Healthy / Tripped / Not enforcing / Not configured(エンドポイント未保存時)の4種
• Failures per minute: 直近2分間のWebhook失敗を平均した値
• Block rate: AIセキュリティサーバーが返したverdictに占める拒否の割合。ロールアウト率が100%未満のときだけ表示される
• Circuit breaker tripped: サーキットブレーカーが最後に作動した日時(作動歴があれば)
• Recent errors: 各エントリはタイムスタンプ・エラー種別・一行の理由に縮約され、本文やエンドポイントURLは含まれません

このパネルはbest-effort(ベストエフォート)です。Anthropicがカウンタを読み取れない場合はエラーを出さず「失敗0件・エラーなし」と表示するため、健全に見える表示それ自体はサーバーが健全である証明にはなりません。Failures per minuteはサーキットブレーカーを作動させないネットワーク・DNSエラーも含めて数えるので、Circuit breaker trippedが空のまま高い値を示すこともあります。

Enforce verdictsをオンにする

Enforce verdictsをオンにすると、組織の管理下にある全プロンプトがAIセキュリティサーバーのverdictでゲートされるようになります。確認ダイアログにはFailure handlingの選択内容が改めて表示されます。設定変更が全Anthropicサーバーへ行き渡るまでおよそ1分かかり、すでに処理中のリクエストは旧設定のまま完了します。オフに戻すときも同様に約1分でプロンプト送信が止まりますが、設定自体は保持されます。

サーキットブレーカーが作動したときの挙動

AIセキュリティサーバー側に起因するWebhook失敗が続くと、サーキットブレーカーが作動して強制を止めます。作動するとサーバーへの接続自体が止まり、検査対象だった全リクエストにFailure handlingの設定が適用されます。Block the requestを選んでいる組織では、ブレーカーがリセットされるまでユーザーがブロックされ続けるので注意してください。作動時は管理者にclaude.aiの通知センターで通知が届きます。

作動は組織のActivity Feedにinference_hooks_circuit_breaker_trippedとして記録されます(1回の作動につき1件。影響を受けたリクエストごとではありません)。記録にはCompliance APIの有効化が必要です。復旧させるには、まずサーバー側の問題を直してからEnforce verdictsを入れ直します。

ブレーカーは自動でも復旧を試みます。作動から10分後を起点に、Anthropicはおよそ1分に1回、組織の通常トラフィックの中からテスト用のリクエストを1件サーバーへ送ります。このテストリクエストは、サーバーが応答するかどうかに関わらずユーザーに対して処理が進みます。サーバーが有効なverdict(allowまたはdeny)を返せばブレーカーはリセットされ、強制が再開します。それ以外の結果はWebhook失敗として扱われ、ブレーカーは作動したままテストが続きます。自動復旧が働くのは作動後に設定を変えていない場合だけです。署名シークレットのローテーションを含め、作動後にInference hooksの設定を何か変更すると自動テストは止まり、サーバーを直したら手動でEnforce verdictsを入れ直す必要があります。

署名シークレットをローテーションする

Request signingの下のRotate secretをクリックすると署名シークレットを差し替えられます。ローテーションは即座の切り替えで、新しいシークレットが生成・1回だけ表示され、古いシークレットは二度と取得できません。両方のシークレットで同時に署名されるリクエストは存在せず、重複期間はありません。ただし切り替え直後しばらくは、旧シークレットで署名されたリクエストが届く可能性があるため、AIセキュリティサーバー側は新旧両方の署名を受け付ける実装にしておく必要があります。

監査とオフの手順

Inference hooksの活動(設定変更・拒否・サーキットブレーカー作動・Failure handlingで検査なしに通過したリクエスト)は組織のActivity Feedに記録されます。ブレーカーが作動している間は個々のリクエスト単位の記録は残らず、作動イベント自体がその期間の唯一の記録になります。

オフには2段階あります。Inference hooks設定ページでEnforce verdictsをオフにすると、約1分でプロンプト送信が止まりますが設定ページ自体は使い続けられます(サーバー側の作業中に一時停止する用途)。Data and privacy設定でAllow for your organizationをオフにすると、検査自体が止まり設定ページも使えなくなります。どちらの場合もエンドポイント設定・カスタムヘッダー・署名シークレットは保持され、再度オンにするとEnforce verdictsは強制的にオフに戻り、作動していたサーキットブレーカーもクリアされます。

よくあるつまずき

• ngrokなどのトンネル経由でテストしてしまう: Anthropicのネットワークポリシーがリバーストンネルをブロックするため、自分が管理するドメインでホストしたサーバーでなければ接続テストが通りません
• ヘッダー変更で認証が壊れる: ヘッダー値は書き込み専用なので、1つの値を直すつもりでも全ヘッダーの再入力が必要です。エンドポイントURLを変えると全ヘッダー値がクリアされることも忘れがちです
• 200以外のステータスでdeny扱いにしようとしてもエラーステータスでdenyは表現できません。200以外はすべてWebhook失敗としてFailure handling側の設定が適用されます
• ロールアウト率が100%未満のまま強制で運用していると、サンプル対象外のリクエストはBlock the request設定でも無条件で通過してしまいます
• ブレーカー作動後に設定を触ってしまう: 署名シークレットのローテーションを含む設定変更は自動復旧のテストを止めるので、サーバー復旧の確認は先に済ませてから設定変更する順序が安全です

まとめ

Inference hooksの設定は、組織単位での有効化、エンドポイントの接続とテスト、除外ロールとブロックメッセージの設定、署名シークレットの保存、Failure handlingとタイムアウトの選択、ロールアウト率の決定、Shadow modeでの検証(結果はエンドポイント健全性パネルで確認)を経て、最後にEnforce verdictsをオンにする流れです。管理者はサーキットブレーカーの挙動(作動条件・Block the requestとの組み合わせ・10分後からの自動復旧テスト)を理解したうえで、作動後は設定変更よりも先にサーバー側の復旧を確認する運用に倒すのが安全です。