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

> SDKのブラウザツールセットはURLポリシーが未設定だとURLを一切検査しません。navigateだけを見る限界と、confirm・ファイルポリシー・egress制御の分担を整理します。

- Canonical: https://kuucorp.com/blog/claude-browser-toolset-sdk-url-policy-confirm-gate-design/
- Date: 2026-11-08
- Last modified: 2026-11-08
- Publisher: Kuu株式会社 (https://kuucorp.com)

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

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

## 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以外の通信はどう止めるのか

> ポリシーが見るのは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](/services/rde/)で扱っています。

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

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

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

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

導入計画や運用設計の相談は、[Kuuの伴走支援](/services/ai-ops/)で受け付けています。

## 参考

- [Browser and computer use with the SDK toolsets](https://platform.claude.com/docs/en/agents-and-tools/tool-use/browser-use-sdk)
- [Browser use tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/browser-use-tool)
- [Claude Platform release notes](https://platform.claude.com/docs/en/release-notes/overview)

## まとめ

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

ブラウザ型エージェントの権限設計や承認フローの整備は、[Kuu株式会社](https://kuucorp.com/services/ai-ops/)にご相談ください。
