約 5 分で読めます

SDKブラウザツールセットのURLポリシーとconfirm設計

ブラウザを操作するエージェントは、読んだページの内容を根拠に次の操作を決めます。ページに仕込まれた指示文は、そのまま攻撃経路になります。2026年10月7日、Python SDK 1.12.0 と TypeScript SDK 0.132.0 にブラウザ用・デスクトップ用のツールセットクラスがベータで追加されました。ループ制御は SDK が担いますが、守りの大半は利用者側の実装です。

本記事はAIエージェントガバナンスの観点から、SDK が肩代わりする検査と、自前で用意すべき検査の境界を整理します。Computer Use 全般の導入はComputer Use の中小企業向け導入ガイド、バッチ実行の挙動はブラウザ操作ツールのバッチ実行設計を参照してください。

SDKのブラウザツールセットは何を引き受けるのか

SDKはツールループと、利用者が設定したURLポリシー・ファイルポリシー・承認コールバックを実行します。ブラウザ本体(ドライバ)は利用者が用意します。

公式ドキュメントによれば、利用者は BetaAbstractBrowserToolset20260801 を継承したドライバを用意し、navigate や screenshot など対応するメンバーだけを実装します。実装しないメンバーは無効としてAPIに送られ、Claude が呼んでもエラーになるだけでループは続きます。

SDK が行うのは、検査を通った呼び出しをドライバへ渡し、返り値から tool_result を組み立てることです。SDK に含まれないものも明記されています。

  • ブラウザ本体、ドライバ、URLポリシーは同梱されない
  • パートナー(Browser Use、Browserbase、Daytona、E2B)が独自のドライバを公開している
  • 公式の example driver は「本番コードではない」と注記されている

つまり「SDKを使えば安全」にはなりません。安全性は、渡すポリシーとデプロイ環境で決まります。

URLポリシーが未設定だと何が起きるのか

URLポリシーを渡さない場合、SDKはURLを検査せず、APIもClaudeが開くURLを絞りません。nullを明示すると全navigateが拒否されます。

ポリシーは navigate の直前に呼ばれる関数です。何も返さなければ許可、ToolError を投げれば拒否で、メッセージは Claude に読まれます。ドキュメントは次の点を警告しています。

  • SDK は URL のスキーム(javascript:、file:、data:、view-source:)を検査しない。ドライバ側で拒否する
  • file: はブラウザホストのファイル読取に、javascript: は javascript_exec が無効でもページ内スクリプト実行に使える
  • ポリシーの対象は navigate のみで、back・forward・reload では呼ばれない
  • url_policy=None(TypeScript は null)は「全 navigate を拒否」の意味になり、設定値の読み損ねで無検査になる事故を防ぐ。TypeScript の undefined は未指定と同じ扱いなので注意が必要

ホスト判定は文字列の分割ではなく、ブラウザと同じ方法でURLをパースして行います。公式の例は \ を / として読み替えてからパースしています。ホスト名の許可リストは example.com とそのサブドメインのように、必要最小限にします。

ポリシーが見るのはnavigateのURLだけです。クリック先・リダイレクト・ページ内リクエストは、ドライバのフックとコンテナのegress制御で止めます。

公式は防御を6段階で示しています。SDK が肩代わりするのは1・4・5です。

  1. URLポリシーを書く(SDK が実行)
  2. ドライバでリクエストを傍受し、同じ判定関数で検査する
  3. コンテナにegressポリシーを置く
  4. アップロードとダウンロードを閉じ込める(SDK が実行)
  5. 影響の大きいメンバーを confirm で関門にする(SDK が実行)
  6. セッションごとに専用のコンテナまたはVMへ隔離する

2・3・6はドライバとデプロイ側の責任です。傍受フックには穴があり、WebSocket のハンドシェイク、Service Worker のリクエスト、リダイレクトの途中経路は見えません。Service Worker はブロックし、残りは見えるフックで別途検査します。

egress制御では、リンクローカルとプライベートのアドレス範囲(クラウドのメタデータアドレス 169.254.169.254 を含む)を IPv4・IPv6 の両方で遮断し、許可ホストだけに絞り、DNS はコンテナのリゾルバに限ります。コンテナ外のネットワークポリシーはコンテナ内のループバックを見ないため、DevTools ポートのように loopback で待ち受けるサービスには別の対策が要ります。

confirmとファイルポリシーで何を人間に残すのか

confirmは実行直前に毎回呼ばれる承認コールバックです。javascript_execとfile_uploadは既定で無効で、有効化にはconfirmが必須です。

javascript_exec と file_upload を有効にするとき confirm を渡さないと、コンストラクタが設定エラーを出します。承認画面には、メンバー名・ページのURL・入力値を出します。その前に、印字可能なASCII以外の文字をすべてエスケープします。ページ由来のテキストで承認画面を偽装されないためです。

注意点が3つあります。

  • 承認は「最後の状態レポート時点のページ」に対するもので、実行前にページが変わっても SDK は再確認しない
  • 購入・メッセージ送信・規約同意は left_click や type のような通常メンバーを通る。メンバー名だけでは判別できないため、人に承認させたい操作はそれらも承認対象にする
  • javascript: URLの navigate は confirm から見ると単なる navigate なので、URLポリシーで先に拒否しておく

ファイルポリシーは、アップロード元ディレクトリを1つに限り、シンボリックリンクを解決したうえで範囲外を拒否します。ダウンロード先はアップロード元と重ならない場所に置き、モード 0700 で作り、noexec,nosuid,nodev でマウントします。ダウンロードしたファイルは、人が判断するまで会話に読み込んだり実行したりしません。リモートやホスト型のブラウザには、この検査が効きません。ブラウザ側のファイルシステムは別物だからです。その場合は file_upload を無効のままにします。

規模別の留意点(SMB / エンタープライズ)

中小企業は、まず許可ホストを業務に必要な数サイトへ絞り、javascript_exec と file_upload を有効にしない構成から始めてください。承認はSlack通知など既存の経路に載せれば足ります。ドライバはパートナー製を使い、そのプロバイダのegress・録画保持の条件を確認します。ホスト型ブラウザでは自社のegress制御が効かず、傍受フックが唯一の検査になるためです。

大企業では、ポリシー関数を共通ライブラリとして配布し、設定の読み込み失敗が「無検査」にならないことをCIで検証します。ユーザーごとにツールセットを分け、承認キャッシュを共有しないことも要件です。全社展開の設計はRDEで扱っています。

導入前に何を確認すればよいか

確認の要点は5つです。ポリシーの有無、スキーム拒否、egress遮断、無効メンバーの維持、承認UIのエスケープです。

運用前のチェックリストです。

  • url_policy を渡し、None の読み込み時の挙動を試験した
  • javascript:・file:・data: を拒否するテストがある
  • 傍受フックが同じ判定関数を呼んでいる
  • コンテナのegressでメタデータアドレスとプライベート範囲を遮断した
  • 起動するブラウザプロファイルは、どのアカウントにもサインインしていない
  • API キーを持つ SDK 実行側は、ブラウザのコンテナの外で動かしている
  • 承認UIは非ASCIIをエスケープし、承認をURLと入力ごとに分けている

導入計画や運用設計の相談は、Kuuの伴走支援で受け付けています。

参考

まとめ

SDK のブラウザツールセットは、ループと3つの関門(URLポリシー、ファイルポリシー、confirm)を提供します。ただし URLポリシーは navigate しか見ず、傍受とegress制御、ホストの隔離は利用者側の仕事です。ポリシーなしで動く構成を残さないことが最初の一歩です。

ブラウザ型エージェントの権限設計や承認フローの整備は、Kuu株式会社にご相談ください。

関連記事

Web fetchツールの外向き通信を絞る4つの設定Files API GAのfile_id共有リスクと防ぎ方ClaudeのIP許可リストが守る範囲と守れない範囲Claude APIキーの種類と漏えい時の初動手順