OpenAI

2026年11月18日

エンジニアリング

Codex サンドボックスの内部

ユーザーが管理する制限の下で、Codex がマシン上のコマンドを実行する仕組み

著者:Michael Bolin(技術スタッフ)

OpenAI では、エージェントの安全性を確保するために多層防御⁠(新しいウィンドウで開く)のアプローチを採用しています。学習とアラインメントへの投資がこの取り組みの基盤ですが、それに加え、エージェント用ハーネスである Codex⁠(新しいウィンドウで開く) にも保護機能を実装しています。Codex が最もよく行う操作の 1 つは、ユーザーのコンピューターでのコマンド実行であり、これにはリスクも伴います。そこで、ユーザーが管理するファイルシステムとネットワークの制限内で、Codex が既存の環境で作業できるように、Codex サンドボックスを構築しました。

⁠(新しいウィンドウで開く)サンドボックス⁠(新しいウィンドウで開く)は、実行中のプログラムがアクセスできる対象を制限します。写真を整理するタスクでは、~/Pictures 内のファイルの読み取りと変更をコマンドに許可する一方、アップロードを防ぐためにネットワークアクセスを遮断するよう Codex サンドボックスを設定できます。コードレビューでは、ソースファイルを読み取り専用に保ちながら、オンラインドキュメントへのアクセスを許可できます。ユーザーは ⁠(新しいウィンドウで開く)権限プロファイル⁠(新しいウィンドウで開く)を通じて Codex サンドボックスを設定します。権限プロファイルは、Codex セッションのファイルシステムとネットワークの制限を定義します。

この記事では、まず Codex のサンドボックスのデフォルト設定におけるトレードオフを紹介し、続いてサンドボックスの設計と、ハーネスがそれを使ってコマンドを実行する仕組みを説明します。また、エンドユーザーや企業がニーズに合わせて権限を調整する方法と、開発者が独自のツールでサンドボックスを再利用する方法を紹介します。最後に、これらの制限が macOS、Linux、Windows でどのように適用されるかを見ていきます。

サンドボックスの制限範囲の選定

Codex では、実用的な作業を可能にしつつ、安全性を重視したサンドボックスのデフォルト設定を採用する方針です。たとえば、Git リポジトリをワークスペースのルートにした場合、組み込みの :workspace 権限プロファイルは次のように動作します。

  • ワークスペース内の書き込みを許可しつつ、.git や .codex などのディレクトリを読み取り専用にします。これにより、Codex は変更のたびに許可を求めずにソースコードを編集できます。一方で、.codex/config.toml や .git/hooks 配下の Git フックを直接変更することはできません。

  • ユーザーの既存の OS 権限の範囲内で、ファイルシステムの広範な読み取りを許可します。コンパイラー、ランタイム、ビルドツールは、リポジトリ外の SDK、ライブラリ、設定に依存しています。読み取りをワークスペース内に限定すると、多くの一般的なワークフローが機能しなくなります。その代償として、マシン上の別の場所にある機密ファイル(API キーを含む設定ファイルなど)も読み取れる場合があります。

  • ネットワークアクセスを無効にします。これにより、コマンドが読み取れるデータを外部に持ち出そうとする試みを含め、外部サービスへの直接アップロードを阻止します。一方、依存関係のダウンロードなどの正当な操作もできなくなり、追加のアクセス権限が必要になります。

これらの制限で多くの不正な動作を防げますが、有害な操作の可能性がなくなるわけではありません。たとえば、エージェントは node_modules/prettier など、ローカルにインストールされたパッケージに悪意のあるコードを挿入できる可能性があります。node_modules は Git の追跡対象から除外されていることが多いため、この変更は git status に表示されない場合があります。ユーザーのエディターが保存時にその Prettier を実行する場合、ファイルを保存するだけで、悪意のあるコードが Codex サンドボックスの外で実行されるおそれがあります。だからこそ、私たちは多層防御を採用しています。サンドボックスでコマンドのアクセス範囲を制限し、学習とアラインメントによって、モデルがユーザーの意図に沿ってそのアクセス権限を使えるようにします。

企業環境でサンドボックスの権限を調整し、ほかの保護策と組み合わせる方法については、 Codex セキュリティクックブック⁠(新しいウィンドウで開く)をご覧ください。

サンドボックスの設計

仮想マシンとコンテナー⁠(新しいウィンドウで開く)は、サンドボックス化によく使われる 2 つの仕組みですが、Codex サンドボックスでは別のアプローチを採っています。Codex は、処理を別の環境に移して隔離するのではなく、各プラットフォームのサンドボックス機能を使い、ユーザーの既存環境で実行されるコマンドを制限します。

多くの開発者にとって、ノート PC は自分仕様に整えられ、いつでも自由に変更できる開発環境です。その環境を Docker コンテナー内に再現するには手間がかかり、ワークフローによってはホスト上で動くツールへの依存も残ります。

たとえば、Mac 上で Codex を使って iOS アプリを開発する場合を考えてみましょう。Docker 内で Codex を実行してサンドボックス化すると、Codex は Mac ネイティブの実行ファイルで構成される iOS ビルドツールチェーンを実行できず、iPhone シミュレーターを起動してコードを実行することもできません。Docker ベースのワークフローでも、ビルドやシミュレーターの操作を Mac ホストに委ねることはできます。ただし、その操作はコンテナーのサンドボックス外で実行されるため、別途制限が必要です。Codex では、目の前のタスクに最も適した環境で動作できるよう、OS 固有のサンドボックス機能に重点的に投資し、仕組みをシンプルに保つ方針を採っています。

ハーネスは、macOS、Windows、Linux に共通の API を通じて、これらの OS 固有のサンドボックス機能を提供します。この API は、コマンドと権限プロファイルを受け取ります。権限プロファイルが制限付きのネットワークアクセスを許可している場合、呼び出し元はその制限を適用するネットワークプロキシを渡す必要があります。

Python

1
# This is a simplified version of the actual API.
2
def spawn_command_under_sandbox(
3
program_and_args: list[str],
4
cwd: Path,
5
env: dict[str, str],
6
permission_profile: PermissionProfile,
7
network_proxy: NetworkProxy | None,
8
) -> Child:

この関数は、サンドボックス内でプロセスを起動し、ハーネスがその終了を待つために使える Child ハンドルを返します。各子プロセスは、親プロセスのサンドボックス制約を継承します。そのため、制限はコマンドから始まるプロセスツリー全体に適用され、元のプロセスが終了した後も動き続ける子孫プロセスにも及びます。

次の図は、設定からサンドボックス内でのコマンド実行まで、これらの要素がどのように連携するかを示しています。以降のセクションで、各段階を説明します。

フロー図:設定と管理対象の要件からセッションの権限プロファイルを定義し、Codex ハーネスが macOS、Linux、Windows のプラットフォーム固有のサンドボックス制限の下でコマンドを起動します。子プロセスはこれらの制限を継承し、任意で有効にできるネットワークプロキシがドメインルールを適用します。

ハーネスによるサンドボックスの活用

Codex のエージェントループを解き明かすで説明したとおり、Codex ハーネスは、モデルが生成するツール呼び出しの実行を担います。コーディングタスクで最もよく使われるのは、シェルツールです。これは、ユーザーが Bash などの対話型シェルで操作するのと同じように、コマンドを実行します。ここでは、ワンショットの ⁠(新しいウィンドウで開く)exec_command⁠(新しいウィンドウで開く) シェルツール⁠(新しいウィンドウで開く)を例に、ハーネスがサンドボックスを使って必要な保護を実現する仕組みを見ていきます。

以下は、Codex ハーネスが
サンドボックスを使わずに exec_command のツール呼び出しを処理する場合の簡略版です。

Python

1
# Illustrative implementation of the exec_command tool call.
2

3
class ExecCommandToolCall:
4
cmd: str
5
workdir: str | None = None
6
shell: str | None = None
7
login: bool = True
8
timeout_ms: int = 10_000
9

10

11
def perform_exec_command(tool_call: ExecCommandToolCall):
12
program_and_args = [
13
tool_call.shell or os.environ.get("SHELL") or "/bin/sh",
14
"-lc" if tool_call.login else "-c",
15
tool_call.cmd,
16
]
17
child = subprocess.Popen(
18
program_and_args,
19
# workdir defaults to the turn's cwd, assumed here to be the process cwd.
20
cwd=Path(tool_call.workdir or ".").absolute(),
21
stdout=subprocess.PIPE,
22
stderr=subprocess.STDOUT,
23
)
24
output, exit_code = collect_output(child, timeout_ms=tool_call.timeout_ms)
25
return {"output": output, "exit_code": exit_code}

コマンドをサンドボックス化するには、ハーネスが subprocess.Popen() の呼び出しを spawn_command_under_sandbox() に置き換えます。ハーネスは、権限プロファイルと、必要に応じてネットワークプロキシを渡します。

Python

1
# Honoring the exec_command tool call while enforcing sandbox constraints.
2

3
def perform_exec_command_with_sandboxing(
4
tool_call: ExecCommandToolCall,
5
permission_profile: PermissionProfile,
6
network_proxy: NetworkProxy | None,
7
):
8
# ...build program_and_args as in the previous example...
9
child = spawn_command_under_sandbox(
10
program_and_args=program_and_args,
11
cwd=Path(tool_call.workdir or ".").absolute(),
12
env=os.environ.copy(),
13
permission_profile=permission_profile,
14
network_proxy=network_proxy,
15
)
16
output, exit_code = collect_output(child, timeout_ms=tool_call.timeout_ms)
17
return {"output": output, "exit_code": exit_code}

exec_command ツールでは、モデルが個々のコマンドに対して異なる権限を要求することもできます。ただし、その要求を許可するかどうかはハーネスが判断します。

Python

1
class ExecCommandToolCall:
2
# ...command-related fields...
3

4
# Per-command sandbox override. Defaults to "use_default".
5
sandbox_permissions: Literal[
6
"use_default",
7
"with_additional_permissions",
8
"require_escalated",
9
] = "use_default"
10

11
# User-facing approval question; only for "require_escalated".
12
justification: str | None = None
13

14
# Expand network or filesystem access; only for "with_additional_permissions".
15
# AdditionalPermissions supports fine-grained options.
16
additional_permissions: AdditionalPermissions | None = None

use_default が指定されると、ハーネスはそのターンのデフォルトのサンドボックス設定を使用します。with_additional_permissions はサンドボックス内でのアクセス権限の拡大を要求し、require_escalated はサンドボックス外での実行を要求します。ハーネスはコマンドを実行する前に、ユーザーの設定に基づいて要求を評価します。たとえば、Codex はユーザーに直接確認する場合もあれば、要求を自動レビュー⁠(新しいウィンドウで開く)に回す場合もあります。実行が承認されると、Codex は適切な permission_profile と network_proxy を、元の ExecCommandToolCall のコマンド引数とともに perform_exec_command_with_sandboxing() に渡します。

spawn_command_under_sandbox() を主に利用するのはシェルツールですが、ハーネスはローカルファイルの読み取りや変更などの操作にも、同じサンドボックス基盤を再利用しています。この再利用はハーネスの外にも広がります。後述するとおり、codex sandbox コマンドを使えば、独自のツールにサンドボックス内でのコマンド実行を組み込めます。次に、権限プロファイルの定義方法を見ていきます。

サンドボックスの設定

名前付きの権限プロファイルを使うと、同じファイルシステムとネットワークの制限を複数のプロジェクトで再利用できます。config.toml の [permissions] 配下に、独自のプロファイルを定義できます。たとえば、以下では組み込みの :workspace プロファイルを拡張する⁠(新しいウィンドウで開く) dev というプロファイルを定義しています。

TOML

1
# Use the dev profile by default.
2
default_permissions = "dev"
3

4
[permissions.dev]
5
# This is displayed when /permissions is run in the Codex CLI.
6
description = "Development with extra read-only protections."
7

8
# A profile can be derived from an existing profile.
9
# Profiles starting with ":" are provided by Codex.
10
extends = ":workspace"
11

12
[permissions.dev.filesystem]
13
"~/build-cache" = "write"
14

15
[permissions.dev.filesystem.":workspace_roots"]
16
".devcontainer" = "read"
17
".vscode" = "read"
18
"**/*.env" = "deny"
19
"secrets" = "deny"

dev プロファイルは、~/build-cache への書き込み権限を追加し、ワークスペース内のファイルに追加の制限を設けます。ファイルシステムのエントリでは、読み取り専用アクセスの許可(read)、読み書きアクセスの許可(write)、アクセスの全面拒否(deny)を指定できます。

:workspace_roots テーブルでは、プロジェクトのワークスペースルートを基準とした相対パスに対してルールを定義できます。デフォルトでは、Codex CLI は作業ディレクトリを唯一のワークスペースルートとして使用し、ChatGPT デスクトップアプリはプロジェクトのソースフォルダーを使用します。Codex は各ルールをすべてのルートに適用します。そのため、dev の .vscode エントリによって、各ルート配下の .vscode ディレクトリが読み取り専用になります。

dev は独自のルールに加え、:workspace から以下の保護設定を継承します。

TOML

1
[permissions.":workspace".filesystem.":workspace_roots"]
2
".agents" = "read"
3
".aws" = "read"
4
".codex" = "read"
5
".git" = "read"

ネットワーク権限

Codex のサンドボックスのネットワーク設定には、大きく分けて 3 つの選択肢があります。

  • すべてのネットワークアクセスを無効化(:workspace プロファイルのデフォルト)

  • 制限のない直接ネットワークアクセスを有効化(:danger-full-access プロファイルのデフォルト)

  • ネットワークアクセスをプロキシ経由に限定し、権限プロファイルに基づいてプロキシが通信の可否を判断


dev に直接ネットワークアクセスを許可するには、config.toml の最上位に permissions.dev.network.enabled = true を設定します。ネットワークプロキシが無効な場合、これにより制限のないネットワークアクセスが許可されます。

dev のアクセス先を特定のドメイン群に制限するには、ネットワークプロキシを有効にし、ドメインルールを設定します。

TOML

1
[permissions.dev.network]
2
enabled = true
3

4
[permissions.dev.network.domains]
5
"*.openai.com" = "allow"
6
# Allow requests to local services by hostname or by IPv4/IPv6 loopback address.
7
"localhost" = "allow"
8
"127.0.0.1" = "allow"
9
"::1" = "allow"
10
"evil.example" = "deny"
11

12
[features]
13
# If neither local config nor managed requirements enable the proxy,
14
# this profile allows direct network access; domain rules are not enforced.
15
network_proxy = true

ドメインルールは、完全一致の名前とワイルドカードパターンに対応しています。明示的な拒否ルールは許可ルールより優先されます。ほかのドメインへのリクエストは、後述のネットワークプロキシで説明するとおり、承認が必要になるか、ブロックされます。

設定の階層化と制限の適用

個々のユーザーは、プロジェクト全体に適用するデフォルト設定を定め、信頼できる特定のプロジェクトではそれを上書きできます。企業の管理者も、ユーザー向けのデフォルト設定を定めたうえで、ユーザーが変更できる設定を制限したい場合があります。Codex は、階層化された設定と管理対象の要件によって、その両方に対応します。

設定の優先順位⁠(新しいウィンドウで開く)で説明するとおり、Codex は複数の config.toml ファイルから設定をマージします。テーブルは再帰的にマージされ、値が競合した場合は、優先順位の高い設定元の値が採用されます。配列は全体が置き換えられます。

このため、権限プロファイルでは、ファイルシステムのパスとネットワークのドメインにテーブルを使用しています。チームは独自の設定で個々のエントリを追加・上書きしつつ、それ以外のすべてのエントリについては、組織の基本設定の変更を自動的に継承できます。

TOML

1
[permissions.dev.filesystem.":workspace_roots"]
2
".idea" = "read"
3

4
[permissions.dev.network.domains]
5
"example.com" = "allow"

管理者は、requirements.toml を通じて管理対象の要件⁠(新しいウィンドウで開く)を指定し、ユーザーが選択できる設定を制限することもできます。これらの要件は、システムファイルやクラウドから提供されるポリシーなど、複数の設定元から取得できます。よくある用途は、allowed_permission_profiles を指定し、企業のユーザーが選択できる権限プロファイルを制限することです。たとえば、管理者はクラウド側で次の要件を指定できます。

TOML

1
default_permissions = ":read-only"
2

3
[allowed_permission_profiles]
4
":read-only" = true
5
":danger-full-access" = false

クラウドの要件は、/etc/codex/requirements.toml にあるシステム要件ファイルより優先されます。そのため、そのファイルのエントリで、上記の明示的な設定 ":danger-full-access" = false を上書きすることはできません。:workspace を指定せずにおくと、別の要件レイヤーでそのエントリを指定できます。最終的にマージされたテーブルで、エントリが false になっているか、存在しないプロファイルは利用できません。

このように分離することで、組織が制限を適用しつつ、ユーザーはその制限内で設定を調整できます。こうして得られた権限プロファイルは、ハーネスで使用できるほか、次に示すようにコマンドへ直接適用することもできます。

codex sandbox コマンドの使用

Codex CLI は、Codex の設定で定義した権限プロファイルの下で任意のコマンドを実行しやすくするために、sandbox コマンドを提供しています。これは主にプロファイルのテストに使われ、サンドボックスが意図した動作を確実にブロックできるかを確認します。

たとえば、次のコマンドは、保存時に悪意のある自動フォーマッターを実行するよう VS Code を設定しようとします。.vscode がすでに存在する場合、上で定義した dev プロファイルでは、このディレクトリが読み取り専用なので、書き込みがブロックされるはずです(codex sandbox はデフォルトで cwd をワークスペースのルートとして扱います)。

Bash

1
codex sandbox --permission-profile dev -- \
2
bash -c 'cat > .vscode/settings.json' <<'JSON'
3
{
4
"prettier.prettierPath": "./node_modules/evil-prettier",
5
"[typescript]": {
6
"editor.defaultFormatter": "esbenp.prettier-vscode",
7
"editor.formatOnSave": true
8
}
9
}
10
JSON

実際、macOS では次のエラーで失敗します。

プレーンテキスト

1
bash: .vscode/settings.json: Operation not permitted

codex sandbox コマンドにより、エージェントのセッションとは独立して Codex のサンドボックス機能を利用できます。同じ設定言語とプラットフォーム固有の制限適用機能を使って、独自のツールが起動するコマンドを制限できます。

例:MCP サーバーのサンドボックス化

config.toml に設定された stdio MCP サーバーについて、Codex ハーネスはサーバーの起動コマンドをサンドボックス化しません。Codex は、そのサーバーが必要とするファイルやネットワークサービスを確実には推定できません。そのため、デフォルトのサンドボックスプロファイルを適用すると、本来は有効な設定が機能しなくなるおそれがあります。

たとえば、Codex で @modelcontextprotocol/server-memory⁠(新しいウィンドウで開く) MCP サーバーを使用するための標準的な設定は、次のとおりです。

TOML

1
[mcp_servers.memory]
2
command = "npx"
3
args = [
4
"-y",
5
"@modelcontextprotocol/server-memory@1.0.0"
6
]
7

8
[mcp_servers.memory.env]
9
MEMORY_FILE_PATH = "~/mcp-data/memory.jsonl"

この npx コマンドはサンドボックス外で実行されるため、Codex を実行しているユーザーと同じ権限で、ファイルへの書き込みやネットワークリクエストを行えます。これは過剰な権限です。権限を絞るには、memory-mcp という権限プロファイルを定義し、元の npx コマンドを codex sandbox --permission-profile memory-mcp でラップします。これにより、サーバーの書き込み先を制限し、ネットワークアクセスを防げます。

TOML

1
[permissions.memory-mcp.filesystem]
2
# Allow broad reads for Node.js/npm dependencies and configuration.
3
":root" = "read"
4
"~/.npm" = "write"
5
"~/mcp-data" = "write"
6

7
[permissions.memory-mcp.network]
8
enabled = false
9

10
[mcp_servers.memory]
11
command = "codex"
12
args = [
13
"sandbox",
14
"--permission-profile",
15
"memory-mcp",
16
"--",
17
"npx",
18
"--offline",
19
"@modelcontextprotocol/server-memory@1.0.0"
20
]
21

22
[mcp_servers.memory.env]
23
MEMORY_FILE_PATH = "~/mcp-data/memory.jsonl"

サーバーを起動する前に、データディレクトリを作成し、バージョンを固定したパッケージを npm キャッシュに保存します。これにより、ネットワークアクセスを無効にしたプロファイルの下で、npx --offline によってサーバーを起動できます。

Bash

1
# The sandbox can write to this folder, but it cannot create it.
2
mkdir -p ~/mcp-data
3

4
# Installing the MCP server requires network access.
5
npx -y --package=@modelcontextprotocol/server-memory@1.0.0 -c true

パッケージをキャッシュすれば、Codex はネットワークアクセスなしでメモリーサーバーを起動でき、書き込み先は npm キャッシュとサーバーのデータディレクトリに限定されます。

Codex サンドボックスの実装

サンドボックスの実装は、権限プロファイルを OS によって強制適用される制限に変換します。ネットワークプロキシの中核となるリクエスト処理とポリシーロジックは、主要な 3 つの OS で共通です。一方、プロキシのセットアップとサンドボックスとの統合は OS ごとに異なります。まず共通のプロキシを確認し、その後で macOS、Linux、Windows 向けの実装を見ていきます。

ネットワークプロキシ

権限プロファイルのネットワーク制限を適用するため、ハーネスはネットワークプロキシを起動します。そして、プロキシへの接続は許可しつつ、外部ホストへの直接接続はブロックするようにサンドボックスを設定します。プロキシは各リクエストをプロファイルのドメインルールと照合し、転送するかどうかを判断します。

Codex リポジトリでは、ネットワークプロキシは codex-network-proxy⁠(新しいウィンドウで開く) クレートに実装されています。ハーネスはこれをライブラリとして使用しますが、スタンドアロンの CLI⁠(新しいウィンドウで開く) としてビルドすることもできます。有効にすると、codex-network-proxy はデフォルトで HTTP プロキシと SOCKS5 プロキシの両方を起動します。これらのプロキシのアドレスは、環境変数を通じてサンドボックスが起動したプロセスに渡されます。HTTP_PROXY、HTTPS_PROXY、ALL_PROXY などの標準的な環境変数に加え、PIP_PROXY など、広く使われているアプリケーション固有の環境変数⁠(新しいウィンドウで開く)も複数設定されます。ただし、すべてのプログラムがこれらの環境変数に従うわけではありません。プログラムが外部ホストへの直接接続を試みると、後述のプラットフォーム別のセクションで説明するように、OS のサンドボックス制限によってブロックされます。

ネットワークプロキシは、権限プロファイルで定義されたネットワーク制限の適用を担います。たとえば、前述の dev プロファイルは、*.openai.com へのリクエストを許可し、evil.example へのリクエストを明示的に拒否します。リクエスト先のドメインが許可ルールにも拒否ルールにも一致しない場合、プロキシはリクエストを保留し、承認判断をハーネスに委ねることができます。シェルコマンドの例と同様に、Codex はユーザーに直接確認する場合もあれば、リクエストを自動レビュー⁠(新しいウィンドウで開く)に回す場合もあります。判断結果を受け取ると、プロキシはリクエストの続行を許可するか、エラーレスポンスを返して拒否します。

ここでは処理の順序が重要です。DNS ルックアップだけでも、ホスト名に埋め込まれた情報が漏れる可能性があるためです。そのため、プロキシはリクエストが許可または承認されたことを確認してから、対象のホスト名を解決します。ただし、広範なワイルドカードルールや DNS サービスへのアクセスがあると、DNS を使ったデータの持ち出しが可能になる場合がある点には注意が必要です。

macOS

macOS では、Codex は Apple のカーネルによって制限が強制適用されるサンドボックス機能、Seatbelt⁠(新しいウィンドウで開く) を使用します。Seatbelt のポリシーは、サンドボックスの制限を記述する Scheme ベースの言語、Sandbox Profile Language(SBPL)で記述します。Codex は、macOS の /usr/bin/sandbox-exec コマンドを通じて Seatbelt を呼び出します。codex sandbox と同様に、サンドボックスを指定するオプションに続いて、実行するコマンドを受け取ります。

Bash

1
sandbox-exec -p PROFILE [-Dkey=value]* -- PROG ARGS...

PROFILE は、サンドボックスを設定するエントリを含む SBPL の文字列です。たとえば、次の SBPL スニペットは、サンドボックスポリシーの下で /dev/null と /dev/zero を読み書き可能にします。

Scheme

1
(allow file-read* file-test-existence file-write-data
2
(literal "/dev/null")
3
(literal "/dev/zero"))

サンドボックスの呼び出し時にネットワークプロキシを有効にすると、接続先を適切なローカルポートに限定するため、次のようなルールがプロファイルに追加されます。

Scheme

1
; local HTTP proxy launched by Codex
2
(allow network-outbound (remote ip "localhost:3128"))
3

4
; local SOCKS proxy launched by Codex
5
(allow network-outbound (remote ip "localhost:8081"))


Codex の基本プロファイルは
(deny default) で始まるため、外向きの接続は明示的に許可されない限りブロックされます。

また、SBPL には (param) を使ったプレースホルダーを含めることもできます。

Scheme

1
; Pass -DWRITABLE_ROOT_0=/path/to/dir to specify a folder that cannot be removed.
2
(deny file-write-unlink
3
(require-all
4
(literal (param "WRITABLE_ROOT_0"))
5
(vnode-type DIRECTORY)))

この値は、sandbox-exec に渡す -Dkey=value オプションで設定します。

Codex は独自のサンドボックス API を実装するため、基本ポリシー⁠(新しいウィンドウで開く)を出発点として、sandbox-exec に渡す引数リストを組み立てます⁠(新しいウィンドウで開く)。その後、permission_profile やその他のコンテキストに基づいて調整し、完全な Seatbelt プロファイルを生成します。生成されたプロファイルと付随する -D 引数が、Seatbelt の適用する制限を設定します。さらに、ネットワークプロキシが追加のネットワークルールを適用します。引数リストがすべて揃えば、sandbox-exec の呼び出し自体は単純です。

難しいのは正しい SBPL の生成です。Apple は、この言語のサードパーティー向けドキュメントを公開していません。実際、man sandbox-exec には The sandbox-exec command is DEPRECATED と記載されています(man 3 sandbox_init で説明されているライブラリ関数 sandbox_init() も同様に非推奨です)。非推奨の警告はあるものの、macOS は現在も /usr/share/sandbox に Seatbelt プロファイルを同梱しており、Google Chrome や Chromium を含む⁠(新しいウィンドウで開く)サードパーティーのソフトウェアも、引き続き Seatbelt を利用しています。そのため、私たちも当面は Seatbelt の使用を続ける予定です。

Linux

Linux 上でサンドボックスを作成するため、Codex は、隔離環境を構築するコマンドラインツールの bubblewrap⁠(新しいウィンドウで開く)(bwrap)と、システムコールをフィルタリングする Linux カーネルの仕組みである seccomp-bpf⁠(新しいウィンドウで開く) を組み合わせて使用します。codex-linux-sandbox という内部ヘルパーが、セットアップを調整します。macOS の sandbox-exec と同様に、サンドボックス設定に続いて、実行するコマンドを受け取ります。

Bash

1
codex-linux-sandbox SANDBOX_ARGS... -- PROG ARGS...

ファイルシステムの隔離やプロキシルーティングが必要な場合、codex-linux-sandbox は bwrap を呼び出して、初期のサンドボックス環境を作成します。次に bwrap が、その内部で codex-linux-sandbox --apply-seccomp-then-exec を起動します。この 2 回目の呼び出しでは、seccomp-bpf を使って追加の制限を適用してから、ユーザーのコマンドを実行します。

初期のサンドボックス環境を構築するため、Codex は bubblewrap を使い、権限プロファイルのファイルシステムルールを反映したファイルシステムビューを、独立したマウント名前空間に作成します。これはサンドボックス実装の基盤となるため、ユーザーが bwrap をインストールしていない場合に備え、Codex は独自のコピーを同梱しています。ただし、PATH 上に互換性のある bwrap⁠(新しいウィンドウで開く) が見つかれば、そのインストール済みのものを優先します⁠(新しいウィンドウで開く)。実際、一部の Linux ディストリビューションでは、ユーザー名前空間へのアクセスがデフォルトで無効になっています⁠(新しいウィンドウで開く)が、システムの bwrap は例外として許可されています。

また、sandbox-exec と同様に、bwrap はサンドボックス設定に続いて、その内部で実行するコマンドを受け取ります。bwrap は、SBPL のような独自の設定言語ではなく、個別のフラグで設定を指定します。Codex は、以下のオプションを使ってファイルシステムビューを作成します。

  • --bind:書き込み可能なファイルやディレクトリを指定

  • --ro-bind:読み取り専用のファイルやディレクトリを指定

  • --perms 000 --tmpfs DIR --remount-ro DIR:DIR へのアクセスを拒否

  • --perms 000 --ro-bind-data FD FILE:FILE へのアクセスを拒否(FD は /dev/null を開いたファイルディスクリプター)

これらのオプションで拒否用の glob パターンを適用するため、Codex は各コマンドを起動する前に、パターンを具体的なパスに展開します。新たにパターンに一致したパスは、そのコマンドのサンドボックス制限に自動では追加されません。

Codex は --unshare-ipc や --unshare-pid などのオプションも指定し、サンドボックスがホスト上のほかの種類のリソースにアクセスできないようにします。そのため、bubblewrap の作用はファイルの可視性だけにとどまりません。

bubblewrap の使用時、ネットワークが無効になっている場合や、ネットワークプロキシ経由での接続が必要な場合は、Codex が --unshare-net を渡し、サンドボックス用の新しいネットワーク名前空間を作成します。続いて seccomp-bpf を使い、コマンドが利用できるネットワーク関連のシステムコールとソケットファミリーに追加の制限を適用します。


具体的には、
seccompiler クレート⁠(新しいウィンドウで開く)を使って必要なフィルターに基づく BPF プログラムを動的にコンパイル⁠(新しいウィンドウで開く)し、サンドボックス内のランチャープロセスに適用します。これにより、制約がプロセスツリー全体に継承されます。そのため、bwrap はユーザーのコマンドを直接実行せず、codex-linux-sandbox ランチャーを実行します。その引数には、ランチャー用の設定引数に続いてユーザーのコマンドを指定します。

Bash

1
bwrap BWRAP_ARGS... -- \
2
codex-linux-sandbox --apply-seccomp-then-exec CODEX_LINUX_SANDBOX_ARGS... -- \
3
PROG ARGS...

昇格権限なしで seccomp フィルターを適用するため、ランチャーは Linux の no_new_privs フラグを設定します⁠(新しいウィンドウで開く)。このフラグは子プロセスに継承され、setuid 実行ファイルなどの別のプログラムを実行する際に、追加の権限を取得できないようにします。

seccomp フィルターの内容は、ネットワーク設定によって変わります。ネットワークアクセスが無効な場合は、connect(2) や bind(2) など、多数のネットワーク関連システムコールをブロックします。一方、サンドボックスでネットワークプロキシが有効な場合は、codex-linux-sandbox が作成した TCP リスナーに到達できるよう IP ソケットを許可します。ただし、独立した Unix ドメインソケットの作成は、ホストのリソースへの意図しないアクセスにつながるおそれがあるため、デフォルトでブロックします。

ネットワークプロキシへの接続

サンドボックス設定でネットワークプロキシが必要な場合、Codex ハーネスはプロキシのインスタンスを 1 つ作成します。このインスタンスは、同じ Codex スレッド内での複数回の codex-linux-sandbox 呼び出しで再利用できます。各サンドボックスには、隔離されたネットワーク名前空間から、その共有プロキシに到達する手段が必要です。Codex は、その名前空間内にループバック TCP リスナーを用意し、サンドボックス外のプロセスが接続を受け入れてプロキシに中継するようにします。

以下の図は、1 つのプロキシエンドポイントについてこの構成を示したものです。最後の図では、そのエンドポイントを経由する 1 つの接続を示しています。bubblewrap を起動する前に、codex-linux-sandbox は制御チャネル用の Unix ソケットペアを作成し、自身をフォークします。子プロセスは run_host_bridge() を実行し、そのチャネルを通じてリスナーのファイルディスクリプターが届くのを待ちます。

Codex ハーネスが codex-linux-sandbox を起動し、そこから Unix ソケットの制御チャネルで接続された中継プロセスがフォークされる様子を示す図。

この例では、親プロセスが exec を使い、自身のプログラムイメージを bwrap に置き換えます。これによりサンドボックスをセットアップし、制御チャネルの FD を引き渡して、内部で codex-linux-sandbox --apply-seccomp-then-exec を起動します。

bwrap がサンドボックス用のネットワーク名前空間を作成し、その内部で codex-linux-sandbox を起動する様子を示す図。サンドボックス外の中継プロセスとは、Unix ソケットの制御チャネルで接続されています。

サンドボックスのネットワーク名前空間内では、2 回目に呼び出された codex-linux-sandbox がループバック TCP リスナーを作成し、そのファイルディスクリプターをソケット経由で渡します。リスナーはサンドボックスのネットワーク名前空間に関連付けられたままです。そのため、サンドボックス外に残った子プロセスは、サンドボックス内のプログラムからの接続を受け入れつつ、ホストのネットワーク名前空間で上流への接続を開けます。受け渡し後、両プロセスは制御チャネルのディスクリプターを閉じ、サンドボックス内のプロセスは自身が持つリスナーのコピーも閉じます。

TCP リスナーの準備が整うと、サンドボックス内のプロセスは、そのリスナーを指すように HTTP_PROXY と関連する環境変数に適切な値を設定します⁠(新しいウィンドウで開く)。その後、seccomp を適用してからフォークし、ユーザーのコマンドを実行します。

サンドボックス内のプログラムがループバック TCP リスナーに接続し、外部の codex-linux-sandbox 中継プロセスがトラフィックを Codex ネットワークプロキシに転送する様子を示す図。

サンドボックス外のプロセスは、リスナーを開いたままにします。接続を受け入れるたびに、設定されたプロキシへの接続を開き、双方向にデータを中継します。

この追加の仕組みにより、コマンドには独立したループバックインターフェースを含む専用のネットワーク名前空間が与えられます。macOS では、Seatbelt により、コマンドはホストのループバックインターフェース上の指定ポートに直接接続できます。一方、Linux では、コマンドは隔離された名前空間内のリスナーに接続し、サンドボックス外のプロセスがその接続を設定済みのプロキシに中継します。ディスクリプターの受け渡しにより、ホストのネットワーク名前空間をコマンドに公開せずに、この接続を実現できます。

Windows

今年初め、私たちは Windows 向けのサンドボックスを実装し、その取り組みを記事で紹介しました。その後、Microsoft は Windows OS 内でのプロセス隔離の新機能とともに、MXC というライブラリをリリースしました。現在、既存のサンドボックスを MXC ライブラリを利用するものに置き換えています。

MXC とは

MXC(Microsoft eXecution Container)は、Microsoft が提供するサンドボックス型のコード実行システム⁠(新しいウィンドウで開く)で、Windows、Linux、macOS 上の複数の隔離バックエンドをサポートしています。Codex は、対応する Windows デバイスで MXC ベースのサンドボックスをサポートし、ネイティブのプロセス隔離を使って、ユーザーの既存環境内でコマンドを制限します。

セキュリティと使いやすさを向上させ、既存の Windows サンドボックスにある以下の制約を解消するため、MXC への移行を進めています。

  • サンドボックスのセットアップに昇格権限や管理者権限が必要

  • ACL の確認・設定処理の負荷が高く、時間がかかる

  • ホストマシンに以下のサンドボックス設定状態が残存

    • ACL

    • ファイアウォールルール

    • サンドボックス用ユーザー

    • コントロールプレーンのファイル

MXC は JSON 設定スキーマ⁠(新しいウィンドウで開く)を公開しています。Codex は MXC SDK⁠(新しいウィンドウで開く) を使い、そのスキーマに従って、コマンド、作業ディレクトリ、環境、権限を含む実行リクエストを構築します。これらの権限は、ファイルシステムとネットワークへのアクセスに加え、デスクトップやクリップボードなどの Windows リソースも対象とします。

ポリシーから MXC 呼び出しへの変換

Codex は、互換性とセキュリティを両立させるため、いくつかの制御項目に固定の設定値を使用します。レジストリの読み取りを許可し、PowerShell が起動時に必要とする Win32k とデスクトップへのアクセスを維持します。クリップボードへのアクセス、入力の注入、デスクトップやシステム設定の操作は無効です。また、MXC が代替手段としてホストのファイルシステム権限を変更することも禁止します。

Codex は、権限プロファイルのファイルシステムルールとネットワークルールを MXC の設定に変換します。先ほどの dev プロファイルを使用し、以下を前提とします。

  • マシンのローカルドライブは C:\、D:\、Z:\ のみです。

  • ワークスペースのルートと作業ディレクトリは C:\work\demo です。

  • ユーザーのホームディレクトリは D:\Users\dev なので、~/build-cache は D:\Users\dev\build-cache に解決されます。

  • 拒否用の glob パターンは、C:\work\demo\config\dev.env と C:\work\demo\config\prod.env にのみ一致します。

対応する MXC の設定には、以下が含まれます。

JSON

1
{
2
...
3
"filesystem": {
4
"readwritePaths": [
5
"C:\\work\\demo",
6
"D:\\Users\\dev\\build-cache",
7
...
8
],
9
"readonlyPaths": [
10
"C:\\",
11
"D:\\",
12
"Z:\\",
13
"C:\\work\\demo\\.agents",
14
"C:\\work\\demo\\.aws",
15
"C:\\work\\demo\\.codex",
16
"C:\\work\\demo\\.devcontainer",
17
"C:\\work\\demo\\.git",
18
"C:\\work\\demo\\.vscode",
19
...
20
],
21
"deniedPaths": [
22
"C:\\work\\demo\\config\\dev.env",
23
"C:\\work\\demo\\config\\prod.env",
24
"C:\\work\\demo\\secrets"
25
]
26
},
27
"network": {
28
"egress": {
29
"default": "deny",
30
"allow": [{
31
"to": [
32
{"cidr": "127.0.0.0/8"},
33
{"cidr": "::1/128"}
34
]
35
}]
36
},
37
"ingress": {
38
"default": "deny",
39
"hostLoopback": "allow"
40
}
41
},
42
...
43
}

ドライブルートへのアクセス

MXC のファイルシステムポリシーは、デフォルトでアクセスを拒否します。そのため Codex は、ローカルドライブのルートに読み取り専用権限を追加し、このプロファイルで許可される広範な読み取りを可能にします。これらの権限は、ユーザーの既存の OS 権限の範囲内で再帰的に適用されます。

ただし、ドライブルートの書き込み可能権限は再帰的に適用されません。そのため Codex は、ドライブ直下にある既存のファイルやディレクトリも含めるように権限を展開します。

権限の競合

より具体的なパスの権限が上位階層の権限を上書きします。そのため、読み取り専用の C:\ 配下でも C:\work\demo を書き込み可能にしつつ、C:\work\demo\.git は読み取り専用にできます。

異なるパス表記やシンボリックリンク、ジャンクションによる別名が同じパスを指す場合、MXC はより厳しい権限を適用します。拒否は読み取り専用より優先され、読み取り専用は読み書き可能より優先されます。

拒否用の glob パターン

MXC が受け取れる拒否対象は具体的なパスのみです。そのため Codex は起動前に、拒否用の glob パターンを、一致するファイルやディレクトリに展開します。コマンドの実行中に新たに glob パターンに一致したパスは、自動では追加されません。

ネットワークアクセス

*.openai.com などのドメインルールは、前述の共通の Codex ネットワークプロキシによって適用されます。Codex はそのプロキシをサンドボックス外で実行し、前述と同じ標準の *_PROXY 環境変数を通じて、プロキシのアドレスをコマンドに渡します。MXC は外部への直接接続をブロックする一方、プロキシへのアクセスを含むホストのループバック接続を許可します。ほかのローカルサービスにも引き続きアクセスできます。

macOS、Linux、Windows のいずれでも、ハーネスは同じサンドボックス API を使い、権限プロファイルの下でコマンドを起動します。制限の適用に必要なセットアップは、プラットフォーム固有の実装が担当します。

Codex サンドボックスを基盤とした開発

コードの作成と実行は、ソフトウェア開発の枠を超えて、エージェントに柔軟な問題解決手段をもたらします。Codex サンドボックスにより、エージェントはファイルシステムとネットワークへの明確なアクセス制限の下で、ユーザーの既存環境でその能力を活用できます。これはハーネス内で再利用できる基本機能であり、codex sandbox コマンドを通じて、自作のツールでも利用できます。

エージェントが担うタスクが増える中、より多くのツールや環境でサンドボックスを実用的に使えるようにしたいと考えています。そのために、権限設定を簡単にし、OS により優れた保護機能が登場した際には、それを活用していきます。私たちの目標は、人がエージェントのアクセス範囲を管理できる状態を保ちながら、エージェントにできることを広げることです。

著者

OpenAI

謝辞

本記事に協力してくれた David Wiesen、Charlie Weems、Viyat Bhalodia、Fotis Chantzis に心より感謝します。