OpenAI

18 November 2026

Teknik Rekayasa

Mengenal lebih dalam sandbox Codex

Cara Codex menjalankan perintah di mesin Anda dengan batasan yang Anda kendalikan.

Oleh Michael Bolin, Anggota Staf Teknis

Di OpenAI, kami menerapkan pendekatan pertahanan berlapis⁠(terbuka di jendela baru) untuk melindungi agen. Meski investasi kami dalam pelatihan dan penyelarasan merupakan landasan upaya ini, kami juga menerapkan fitur dalam harness agen kami, Codex⁠(terbuka di jendela baru), untuk memberikan perlindungan tambahan. Karena salah satu aktivitas Codex yang paling umum (dan berpotensi berisiko) adalah menjalankan perintah di komputer Anda, kami membangun sandbox Codex agar Codex dapat bekerja di lingkungan yang sudah Anda gunakan dengan batasan sistem file dan jaringan yang Anda kendalikan.

Sebuah ⁠(terbuka di jendela baru)sandbox⁠(terbuka di jendela baru) membatasi apa yang dapat diakses program saat berjalan. Untuk tugas penataan foto, Anda dapat mengonfigurasi sandbox Codex agar perintah dapat membaca dan mengubah file di ~/Pictures sekaligus memblokir akses jaringan untuk mencegah pengunggahan. Untuk peninjauan kode, Anda dapat mengizinkan akses ke dokumentasi online sambil mempertahankan file sumber sebagai hanya baca. Pengguna mengonfigurasi sandbox Codex melalui ⁠(terbuka di jendela baru)profil izin⁠(terbuka di jendela baru), yang menentukan batasan sistem file dan jaringan untuk sesi Codex.

Dalam artikel ini, kami akan mulai dari pertimbangan di balik pengaturan default sandbox Codex, lalu menjelaskan desain sandbox dan cara harness menggunakannya untuk menjalankan perintah. Kami akan menunjukkan cara pengguna akhir dan perusahaan menyesuaikan izinnya dengan kebutuhan mereka, serta cara developer menggunakan kembali sandbox dalam alat buatan mereka sendiri. Terakhir, kami akan membahas cara batasan ini ditegakkan di macOS, Linux, dan Windows.

Menentukan batasan sandbox

Di Codex, prinsip kami adalah menetapkan pengaturan default sandbox yang berhati-hati, tetapi tetap memungkinkan pekerjaan yang bermanfaat. Misalnya, dengan repositori Git sebagai root ruang kerja, profil izin bawaan :workspace:

  • Mengizinkan penulisan di dalam ruang kerja, tetapi mempertahankan direktori seperti .git dan .codex sebagai hanya baca. Dengan begitu, Codex dapat mengedit kode sumber tanpa meminta izin untuk setiap perubahan, sekaligus mencegah perubahan langsung pada .codex/config.toml atau hook Git di .git/hooks.

  • Mengizinkan pembacaan sistem file secara luas, dengan tetap tunduk pada izin OS pengguna yang ada. Compiler, runtime, dan alat build bergantung pada SDK, pustaka, serta konfigurasi di luar repositori. Membatasi pembacaan hanya pada ruang kerja akan mengganggu banyak alur kerja umum. Konsekuensinya, file sensitif di lokasi lain pada mesin juga mungkin tetap dapat dibaca (seperti file konfigurasi yang berisi kunci API).

  • Menonaktifkan akses jaringan. Ini memblokir pengunggahan langsung ke layanan eksternal, termasuk upaya mengekstraksi secara ilegal data yang dapat dibaca oleh perintah. Ini juga mencegah operasi yang sah seperti mengunduh dependensi, yang membutuhkan akses tambahan.

Batasan ini mencegah banyak jenis perilaku buruk, tetapi tindakan berbahaya masih mungkin terjadi. Misalnya, agen dapat menyisipkan kode berbahaya ke dalam paket yang terinstal secara lokal, seperti node_modules/prettier. Perubahan semacam itu mungkin tidak muncul di git status karena node_modules sering diabaikan oleh Git. Jika editor pengguna menjalankan salinan Prettier tersebut saat menyimpan, sekadar menyimpan file dapat mengeksekusi kode berbahaya di luar sandbox Codex. Itulah sebabnya kami menerapkan pendekatan pertahanan berlapis: sandbox membatasi apa yang dapat diakses perintah, sementara pelatihan dan penyelarasan membantu model menggunakan akses tersebut sesuai maksud pengguna.

Untuk panduan menyesuaikan izin sandbox dan menggabungkannya dengan perlindungan lain di lingkungan perusahaan, lihat panduan praktis keamanan Codex⁠(terbuka di jendela baru).

Merancang sandbox

Mesin virtual dan container⁠(terbuka di jendela baru) adalah dua mekanisme populer untuk sandboxing, tetapi kami menggunakan pendekatan berbeda untuk sandbox Codex. Alih-alih memindahkan komputasi ke lingkungan terpisah untuk menyediakan isolasi, Codex menggunakan fasilitas sandboxing tiap platform untuk membatasi perintah yang berjalan di lingkungan yang sudah digunakan pengguna.

Bagi banyak developer, laptop mereka berfungsi sebagai lingkungan pengembangan yang disesuaikan dengan kebutuhan dan dapat diubah kapan saja. Mereplikasi lingkungan tersebut dalam container Docker dapat memerlukan upaya, dan sebagian alur kerja masih bergantung pada alat yang berjalan di host.

Sebagai contoh, bayangkan Anda menggunakan Codex untuk mengembangkan aplikasi iOS di Mac. Jika Anda memilih mengisolasi Codex dengan menjalankannya di dalam Docker, Codex tidak akan dapat menjalankan toolchain build iOS yang terdiri dari executable native Mac, ataupun membuka simulator iPhone untuk menjalankan kode. Alur kerja berbasis Docker dapat mendelegasikan build dan operasi simulator ke host Mac, tetapi operasi tersebut akan berjalan di luar sandbox container dan memerlukan batasannya sendiri. Untuk Codex, kami memilih menjaga kesederhanaan dengan berinvestasi besar pada sandboxing khusus OS agar Codex dapat berjalan di lingkungan yang paling sesuai dengan tugas yang sedang dikerjakan.

Harness menyediakan mekanisme sandboxing khusus OS ini melalui API yang seragam di macOS, Windows, dan Linux. API ini menerima perintah dan profil izin. Jika profil izin memperbolehkan akses jaringan terbatas, pemanggil harus menyediakan proxy jaringan untuk menegakkan batasan tersebut:

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:

Fungsi ini memulai proses dalam sandbox dan mengembalikan handle Child yang dapat digunakan harness untuk menunggu hingga proses selesai. Setiap proses anak mewarisi batasan sandbox induknya, sehingga batasan tersebut berlaku di seluruh pohon proses yang dimulai oleh perintah, bahkan pada proses turunan yang tetap berjalan setelah proses awal berakhir.

Diagram berikut menunjukkan hubungan antarbagian ini, mulai dari konfigurasi hingga menjalankan perintah dalam sandbox. Bagian selanjutnya menjelaskan setiap tahap.

Diagram alur: konfigurasi dan persyaratan terkelola menentukan profil izin sesi; harness Codex menjalankan perintah dengan batasan sandbox khusus platform di macOS, Linux, atau Windows. Proses anak mewarisi batasan tersebut, dan proxy jaringan opsional menegakkan aturan domain.

Cara harness memanfaatkan sandbox

Seperti dijelaskan dalam Mengurai Loop Agen Codex, harness Codex bertanggung jawab menjalankan panggilan alat yang dihasilkan oleh model. Untuk tugas pemrograman, alat yang paling umum digunakan adalah alat shell, yang menjalankan perintah seperti pengguna menjalankannya di shell interaktif seperti Bash. Di sini, kami akan membahas alat shell ⁠(terbuka di jendela baru)exec_command⁠(terbuka di jendela baru) one-shot⁠(terbuka di jendela baru) untuk menggambarkan cara harness menggunakan sandbox guna memberikan perlindungan yang diinginkan.

Berikut versi sederhana cara harness Codex menangani panggilan alat
exec_command tanpa sandboxing:

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}

Untuk menjalankan perintah dalam sandbox, harness mengganti panggilan ke subprocess.Popen() dengan spawn_command_under_sandbox(). Harness menyediakan profil izin dan, jika diperlukan, proxy jaringan:

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}

Alat exec_command juga memungkinkan model meminta izin berbeda untuk perintah individual, tetapi harness yang memutuskan apakah permintaan tersebut akan dikabulkan:

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

Saat use_default ditentukan, harness menggunakan konfigurasi sandbox default untuk giliran tersebut. with_additional_permissions meminta perluasan akses di dalam sandbox, sedangkan require_escalated meminta eksekusi di luarnya. Harness mengevaluasi permintaan berdasarkan preferensi pengguna sebelum menjalankan perintah. (Misalnya, Codex dapat meminta persetujuan pengguna secara langsung atau mengarahkan permintaan ke peninjauan otomatis⁠(terbuka di jendela baru).) Jika eksekusi diizinkan, Codex akan meneruskan permission_profile dan network_proxy yang sesuai ke perform_exec_command_with_sandboxing(), beserta argumen perintah dari ExecCommandToolCall asli.

Alat shell adalah pengguna utama spawn_command_under_sandbox(), dan harness juga menggunakan kembali infrastruktur sandboxing-nya untuk operasi seperti membaca dan mengubah file lokal. Penggunaan kembali ini juga berlaku di luar harness: perintah codex sandbox memungkinkan Anda mengintegrasikan eksekusi perintah dalam sandbox ke alat buatan Anda sendiri, seperti yang akan kita lihat nanti. Selanjutnya, kita akan melihat cara profil izin ditentukan.

Mengonfigurasi sandbox

Profil izin bernama memungkinkan Anda menggunakan kembali batasan sistem file dan jaringan yang sama di berbagai proyek. Anda dapat menentukan profil sendiri di bawah [permissions] dalam config.toml. Misalnya, konfigurasi berikut menentukan profil bernama dev yang memperluas⁠(terbuka di jendela baru) profil bawaan :workspace:

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"

Profil dev menambahkan akses tulis ke ~/build-cache dan menerapkan batasan tambahan pada file dalam ruang kerja. Entri sistem file dapat memberikan akses hanya baca (read), memberikan akses baca dan tulis (write), atau memblokir akses sepenuhnya (deny).

Tabel :workspace_roots memungkinkan Anda menentukan aturan untuk path yang relatif terhadap root ruang kerja proyek. Secara default, CLI Codex menggunakan direktori kerjanya sebagai satu-satunya root ruang kerja, sedangkan aplikasi desktop ChatGPT menggunakan folder sumber proyek. Codex menerapkan setiap aturan pada semua root, sehingga entri .vscode dalam dev menjadikan direktori .vscode di bawah setiap root hanya bisa dibaca.

Selain aturannya sendiri, dev mewarisi perlindungan berikut dari :workspace:

TOML

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

Izin jaringan

Secara garis besar, ada tiga opsi untuk mengonfigurasi jaringan sandbox di Codex:

  • Menonaktifkan semua akses jaringan (default untuk profil :workspace)

  • Mengaktifkan akses jaringan langsung dan penuh (default untuk profil :danger-full-access)

  • Membatasi akses jaringan melalui proxy, yang menentukan apa yang boleh diteruskan berdasarkan profil izin


Untuk memberi
dev akses jaringan langsung, tetapkan permissions.dev.network.enabled = true di tingkat teratas config.toml. Ini memberikan akses jaringan penuh saat proxy jaringan dinonaktifkan.

Untuk membatasi dev ke sejumlah domain, aktifkan proxy jaringan dan konfigurasikan aturan domainnya:

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

Aturan domain mendukung nama persis dan pola wildcard, dengan aturan penolakan eksplisit lebih diutamakan daripada aturan izin. Permintaan ke domain lain memerlukan persetujuan atau diblokir, seperti dijelaskan pada bagian Proxy jaringan di bawah.

Menyusun konfigurasi berlapis dan menegakkan batasan

Pengguna individu dapat mengonfigurasi pengaturan default yang berlaku di berbagai proyek dan menggantinya untuk proyek tepercaya tertentu. Administrator perusahaan mungkin juga ingin mengonfigurasi pengaturan default bagi pengguna mereka dan membatasi pengaturan yang dapat diubah pengguna tersebut. Codex mendukung keduanya melalui konfigurasi berlapis dan persyaratan terkelola.

Seperti dijelaskan dalam Prioritas konfigurasi,⁠(terbuka di jendela baru) Codex menggabungkan pengaturan dari beberapa file config.toml. Tabel digabungkan secara rekursif, dengan sumber berprioritas lebih tinggi diutamakan saat nilainya bertentangan. Array diganti secara keseluruhan.

Inilah alasan profil izin menggunakan tabel untuk path sistem file dan domain jaringan. Tim dapat menambahkan atau mengganti entri individual dalam konfigurasinya sendiri dan otomatis mewarisi perubahan pada semua entri lain dalam konfigurasi dasar organisasi:

TOML

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

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

Administrator juga dapat menyediakan persyaratan terkelola⁠(terbuka di jendela baru) melalui requirements.toml untuk membatasi pilihan konfigurasi pengguna. Persyaratan ini dapat berasal dari berbagai sumber, termasuk file sistem dan kebijakan yang disediakan melalui cloud. Salah satu penggunaan umum adalah menentukan allowed_permission_profiles untuk membatasi kumpulan profil izin yang dapat dipilih pengguna perusahaan. Misalnya, administrator dapat menentukan persyaratan cloud berikut:

TOML

1
default_permissions = ":read-only"
2

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

Persyaratan cloud akan lebih diutamakan daripada file persyaratan sistem di /etc/codex/requirements.toml, sehingga entri dalam file itu tidak dapat mengesampingkan pengaturan eksplisit ":danger-full-access" = false di atas. Membiarkan :workspace tidak ditentukan memungkinkan lapisan persyaratan lain menyediakan entri tersebut. Profil dengan entri bernilai false atau yang tidak ada dalam tabel gabungan akhir tidak tersedia.

Pemisahan ini memungkinkan organisasi menegakkan batasan sementara pengguna menyesuaikan konfigurasi mereka di dalam batasan tersebut. Profil izin yang dihasilkan dapat digunakan oleh harness atau diterapkan langsung pada perintah, seperti yang akan kita lihat berikutnya.

Menggunakan perintah codex sandbox

CLI Codex menyediakan perintah sandbox untuk memudahkan menjalankan perintah apa pun dengan profil izin yang ditentukan dalam konfigurasi Codex. Ini umumnya digunakan untuk menguji profil, guna memastikan sandbox mencegah perilaku yang memang dirancang untuk diblokirnya.

Misalnya, perintah berikut mencoba mengonfigurasi VS Code agar menjalankan pemformat otomatis berbahaya saat menyimpan. Dengan asumsi .vscode sudah ada, profil dev yang ditentukan di atas seharusnya memblokir penulisan ini karena direktori tersebut hanya bisa dibaca (secara default, codex sandbox memperlakukan cwd sebagai root ruang kerja):

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

Benar saja, di macOS perintah ini gagal dengan pesan:

Teks polos

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

Perintah codex sandbox memungkinkan mekanisme sandboxing Codex digunakan secara terpisah dari sesi agen. Anda dapat menggunakan bahasa konfigurasi dan penegakan khusus platform yang sama untuk membatasi perintah yang dijalankan oleh alat buatan Anda sendiri.

Contoh: menjalankan server MCP dalam sandbox

Untuk server MCP stdio yang dikonfigurasi dalam config.toml, harness Codex tidak mencoba menjalankan perintah yang digunakan untuk memulai server dalam sandbox. Codex tidak dapat menyimpulkan secara andal file atau layanan jaringan mana yang dibutuhkan server tersebut, sehingga menerapkan profil sandbox default dapat mengganggu konfigurasi yang sebenarnya valid.

Misalnya, cara standar untuk mengonfigurasi server MCP @modelcontextprotocol/server-memory⁠(terbuka di jendela baru) agar dapat digunakan dengan Codex adalah sebagai berikut:

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"

Karena perintah npx ini berjalan tanpa sandbox, perintah tersebut dapat menulis file dan membuat permintaan jaringan dengan izin yang sama seperti pengguna yang menjalankan Codex. Cakupan izin ini terlalu luas. Untuk membatasinya, kita dapat menentukan profil izin bernama memory-mcp, lalu membungkus perintah npx asli dengan codex sandbox --permission-profile memory-mcp untuk membatasi lokasi penulisan server dan mencegahnya mengakses jaringan:

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"

Sebelum memulai server, buat direktori datanya dan isi cache npm dengan paket yang versinya telah dikunci. Dengan begitu, npx --offline dapat menjalankan server dengan profil yang menonaktifkan akses jaringan:

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

Setelah paket tersimpan dalam cache, Codex dapat memulai server memori tanpa akses jaringan, dengan penulisan terbatas pada cache npm dan direktori data server.

Implementasi sandbox Codex

Implementasi sandbox mengubah profil izin menjadi batasan yang ditegakkan oleh sistem operasi. Logika inti penanganan permintaan dan kebijakan proxy jaringan digunakan bersama di ketiga sistem operasi utama, sementara penyiapan proxy dan integrasinya dengan sandbox bersifat khusus OS. Kami akan membahas proxy bersama terlebih dahulu, diikuti implementasi untuk macOS, Linux, dan Windows.

Proxy jaringan

Untuk menegakkan batasan jaringan dalam profil izin, harness memulai proxy jaringan dan mengonfigurasi sandbox agar mengizinkan koneksi ke proxy tersebut sambil memblokir koneksi langsung ke host eksternal. Proxy memeriksa setiap permintaan berdasarkan aturan domain profil untuk menentukan apakah permintaan itu akan diteruskan.

Dalam repositori Codex, proxy jaringan diimplementasikan dalam crate codex-network-proxy⁠(terbuka di jendela baru), yang digunakan harness sebagai pustaka, meski juga dapat dibangun sebagai CLI mandiri⁠(terbuka di jendela baru). Saat diaktifkan, codex-network-proxy secara default memulai proxy HTTP sekaligus proxy SOCKS5. Alamat proxy ini disampaikan ke proses yang dibuat oleh sandbox melalui variabel lingkungan. Selain menyisipkan variabel lingkungan standar seperti HTTP_PROXY, HTTPS_PROXY, dan ALL_PROXY, sejumlah variabel lingkungan khusus aplikasi⁠(terbuka di jendela baru) yang umum dikenal (seperti PIP_PROXY) juga disisipkan. Memang, tidak semua program mematuhi variabel lingkungan ini. Jika program mencoba membuat koneksi langsung ke host eksternal, batasan sandbox sistem operasi akan memblokirnya, seperti dijelaskan pada bagian khusus platform di bawah.

Proxy jaringan bertanggung jawab menerapkan batasan jaringan yang ditentukan dalam profil izin. Misalnya, profil dev yang ditampilkan sebelumnya mengizinkan permintaan ke *.openai.com dan secara eksplisit menolak permintaan ke evil.example. Saat permintaan menargetkan domain yang tidak cocok dengan aturan izin maupun penolakan, proxy dapat menangguhkan permintaan tersebut sambil menyerahkan keputusan persetujuannya kepada harness. Seperti contoh perintah shell, Codex dapat meminta persetujuan pengguna secara langsung atau mengarahkan permintaan ke peninjauan otomatis⁠(terbuka di jendela baru). Setelah menerima keputusan, proxy akan mengizinkan permintaan berlanjut atau menolaknya dengan respons kesalahan.

Urutan ini penting karena bahkan pencarian DNS dapat membocorkan informasi yang dikodekan dalam nama host. Karena itu, proxy baru melakukan resolusi nama host yang diminta setelah memastikan bahwa permintaan tersebut diizinkan atau disetujui. Perlu diingat bahwa aturan wildcard yang luas atau akses ke layanan DNS masih dapat memungkinkan eksfiltrasi berbasis DNS.

macOS

Di macOS, Codex menggunakan Seatbelt⁠(terbuka di jendela baru), mekanisme sandboxing Apple yang ditegakkan oleh kernel. Kebijakan Seatbelt ditulis dalam Sandbox Profile Language (SBPL), bahasa berbasis Scheme untuk menyatakan batasan sandbox. Codex memanggil Seatbelt melalui perintah /usr/bin/sandbox-exec di macOS. Seperti codex sandbox, perintah ini menerima opsi yang menjelaskan sandbox, diikuti perintah yang akan dijalankan:

Bash

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

PROFILE adalah string SBPL yang berisi entri untuk mengonfigurasi sandbox. Misalnya, cuplikan SBPL berikut membuat /dev/null dan /dev/zero dapat dibaca dan ditulisi berdasarkan kebijakan sandbox:

Scheme

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

Ketika proxy jaringan diaktifkan sebagai bagian dari pemanggilan sandbox, aturan seperti berikut disisipkan ke dalam profil untuk membatasi koneksi ke port lokal yang sesuai:

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"))


Profil dasar Codex dimulai dengan
(deny default), sehingga koneksi keluar tetap diblokir kecuali diizinkan secara eksplisit.

Terakhir, SBPL dapat berisi placeholder yang menggunakan (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)))

yang diisi oleh opsi -Dkey=value yang diteruskan ke sandbox-exec.

Untuk mengimplementasikan API sandbox-nya sendiri, Codex menyusun daftar argumen⁠(terbuka di jendela baru) untuk sandbox-exec mulai dari kebijakan dasar⁠(terbuka di jendela baru), lalu menggunakan permission_profile dan konteks lain untuk menyesuaikannya hingga menghasilkan profil Seatbelt lengkap. Profil yang dihasilkan beserta argumen -D yang menyertainya mengonfigurasi batasan yang ditegakkan Seatbelt, sementara proxy jaringan menegakkan aturan jaringan tambahan. Setelah daftar argumen lengkap tersusun, pemanggilan sandbox-exec menjadi sederhana.

Menghasilkan SBPL yang benar cukup menantang karena Apple tidak mendokumentasikan bahasa ini untuk penggunaan pihak ketiga. Bahkan, man sandbox-exec menyatakan The sandbox-exec command is DEPRECATED (demikian pula fungsi pustaka sandbox_init() yang didokumentasikan melalui man 3 sandbox_init). Meskipun ada peringatan penghentian penggunaan, macOS masih menyertakan profil Seatbelt di /usr/share/sandbox, dan perangkat lunak pihak ketiga, termasuk Google Chrome dan Chromium⁠(terbuka di jendela baru), tetap mengandalkan Seatbelt. Karena itu, kami berencana tetap menggunakan Seatbelt untuk beberapa waktu ke depan.

Linux

Untuk membuat sandbox di Linux, Codex menggunakan kombinasi bubblewrap⁠(terbuka di jendela baru) (bwrap), alat baris perintah untuk membangun lingkungan terisolasi, dan seccomp-bpf⁠(terbuka di jendela baru), mekanisme kernel Linux untuk memfilter panggilan sistem. Komponen pembantu internal bernama codex-linux-sandbox mengoordinasikan penyiapannya. Seperti sandbox-exec di macOS, komponen ini menerima konfigurasi sandbox yang diikuti perintah untuk dijalankan:

Bash

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

Ketika isolasi sistem file atau perutean proxy diperlukan, codex-linux-sandbox memanggil bwrap untuk membuat lingkungan sandbox awal. bwrap lalu menjalankan codex-linux-sandbox --apply-seccomp-then-exec di dalamnya. Pemanggilan kedua ini menggunakan seccomp-bpf untuk menerapkan batasan tambahan sebelum menjalankan perintah pengguna.

Untuk membangun lingkungan sandbox awal tersebut, Codex menggunakan bubblewrap guna membuat tampilan sistem file dalam namespace mount terpisah yang mencerminkan aturan sistem file pada profil izin. Karena ini merupakan bagian mendasar dari implementasi sandbox, Codex menyertakan salinan bwrap sendiri jika pengguna belum menginstalnya, tetapi mengutamakan instalasi yang kompatibel dari ⁠(terbuka di jendela baru)bwrap⁠(terbuka di jendela baru) yang ditemukan di PATH, jika tersedia. Dalam praktiknya, beberapa distribusi Linux menonaktifkan akses ke namespace pengguna secara default⁠(terbuka di jendela baru), tetapi memberikan pengecualian untuk bwrap sistem.

Seperti sandbox-exec, bwrap juga menerima konfigurasi sandbox yang diikuti perintah untuk dijalankan di dalam sandbox. Alih-alih menggunakan bahasa konfigurasi khusus seperti SBPL, bwrap menggunakan flag individual untuk konfigurasi. Codex menggunakan opsi berikut untuk membuat tampilan sistem file:

  • --bind untuk menentukan file atau direktori yang dapat ditulisi

  • --ro-bind untuk menentukan file atau direktori hanya baca

  • --perms 000 --tmpfs DIR --remount-ro DIR untuk menolak akses ke DIR

  • --perms 000 --ro-bind-data FD FILE untuk menolak akses ke FILE (dengan FD sebagai deskriptor file yang terbuka untuk /dev/null)

Untuk menerapkan pola glob penolakan dengan opsi ini, Codex menguraikannya menjadi path konkret sebelum menjalankan setiap perintah. Path baru yang cocok tidak otomatis ditambahkan ke batasan sandbox perintah tersebut.

Codex juga menetapkan opsi seperti --unshare-ipc dan --unshare-pid untuk mencegah sandbox mengakses jenis sumber daya lain di host, sehingga bubblewrap tidak hanya memengaruhi visibilitas file.

Saat menggunakan bubblewrap, Codex meneruskan --unshare-net setiap kali jaringan dinonaktifkan atau koneksi harus melalui proxy jaringan. Ini akan membuat namespace jaringan baru untuk sandbox. Kami lalu menggunakan seccomp-bpf untuk menerapkan batasan tambahan pada panggilan sistem jaringan dan keluarga soket yang tersedia bagi perintah.


Secara khusus, kami menggunakan
crate seccompiler⁠(terbuka di jendela baru) untuk mengompilasi program BPF secara dinamis berdasarkan filter yang diinginkan⁠(terbuka di jendela baru) dan menerapkannya pada proses peluncur di dalam sandbox agar batasannya diwarisi oleh seluruh pohon proses. Karena itu, bwrap tidak menjalankan perintah pengguna, melainkan menjalankan peluncur codex-linux-sandbox dengan argumen konfigurasinya sendiri, diikuti perintah pengguna:

Bash

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

Untuk menerapkan filter seccomp tanpa hak istimewa yang lebih tinggi, peluncur menetapkan flag no_new_privs Linux⁠(terbuka di jendela baru). Flag ini diwarisi oleh proses anak dan mencegahnya memperoleh hak istimewa tambahan saat menjalankan program lain, seperti executable setuid.

Filter seccomp bergantung pada konfigurasi jaringan. Saat akses jaringan dinonaktifkan, kami memblokir sejumlah panggilan sistem terkait jaringan, seperti connect(2) dan bind(2). Namun, saat proxy jaringan diaktifkan dalam sandbox, kami mengizinkan soket IP agar listener TCP yang dibuat oleh codex-linux-sandbox dapat dijangkau, tetapi secara default memblokir pembuatan soket domain Unix mandiri karena soket tersebut dapat memungkinkan akses yang tidak disengaja ke sumber daya host.

Menghubungkan ke proxy jaringan

Ketika konfigurasi sandbox memerlukan proxy jaringan, harness Codex membuat satu instans proxy yang dapat digunakan kembali oleh beberapa pemanggilan codex-linux-sandbox dalam thread Codex yang sama. Setiap sandbox membutuhkan cara untuk menjangkau proxy bersama tersebut dari namespace jaringannya yang terisolasi. Codex menyediakan listener TCP loopback di dalam namespace tersebut dan mengatur proses di luar sandbox untuk menerima koneksinya serta meneruskannya ke proxy.

Diagram berikut menggambarkan pengaturan ini untuk satu endpoint proxy, dengan satu koneksi yang melaluinya ditampilkan pada diagram terakhir. Sebelum menjalankan bubblewrap, codex-linux-sandbox membuat sepasang soket Unix sebagai saluran kontrol dan melakukan fork terhadap dirinya sendiri. Proses anak menjalankan run_host_bridge() dan menunggu untuk menerima deskriptor file listener melalui saluran tersebut:

Diagram harness Codex yang membuat proses codex-linux-sandbox, yang melakukan fork untuk membuat proses penerus yang terhubung melalui saluran kontrol soket Unix.

Dalam contoh ini, proses induk menggunakan exec untuk mengganti citra programnya dengan bwrap. Ini menyiapkan sandbox dan menjalankan codex-linux-sandbox --apply-seccomp-then-exec di dalamnya, sambil meneruskan FD untuk saluran kontrol:

Diagram yang menunjukkan bwrap membuat namespace jaringan sandbox dan menjalankan codex-linux-sandbox di dalamnya, dengan saluran kontrol soket Unix ke proses penerus di luar sandbox.

Di dalam namespace jaringan sandbox, pemanggilan kedua codex-linux-sandbox membuat listener TCP loopback dan meneruskan deskriptor filenya melalui soket. Listener tetap terikat pada namespace jaringan sandbox, sehingga proses anak yang tetap berada di luar sandbox dapat menerima koneksi dari program di dalam sandbox sambil membuka koneksi upstream-nya di namespace jaringan host. Setelah penyerahan, kedua proses menutup deskriptor saluran kontrolnya, dan proses di dalam sandbox menutup salinan listener miliknya.

Setelah listener TCP siap, proses di dalam sandbox menetapkan nilai yang sesuai untuk HTTP_PROXY⁠(terbuka di jendela baru) dan variabel lingkungan terkait agar mengarah ke listener tersebut. Proses tersebut lalu menerapkan seccomp sebelum melakukan fork dan menjalankan perintah pengguna:

Diagram yang menunjukkan program dalam sandbox terhubung ke listener TCP loopback, dengan proses penerus codex-linux-sandbox eksternal yang meneruskan lalu lintas ke proxy jaringan Codex.

Proses di luar sandbox menjaga listener tetap terbuka. Untuk setiap koneksi yang diterima, proses ini membuka koneksi ke proxy yang dikonfigurasi dan meneruskan data ke kedua arah.

Mekanisme tambahan ini memberi perintah namespace jaringannya sendiri, termasuk antarmuka loopback yang terpisah. Di macOS, Seatbelt memungkinkan perintah terhubung langsung ke port yang ditentukan pada antarmuka loopback host. Di Linux, perintah terhubung ke listener di dalam namespace terisolasinya, lalu proses di luar sandbox meneruskan koneksi tersebut ke proxy yang dikonfigurasi. Penyerahan deskriptor memungkinkan koneksi ini tanpa memberikan akses ke namespace jaringan host kepada perintah.

Windows

Awal tahun ini, kami menerapkan dan menulis tentang upaya kami membangun sandbox di Windows. Sejak itu, Microsoft telah merilis pustaka bernama MXC beserta fitur baru untuk isolasi proses di dalam sistem operasi Windows. Saat ini, kami sedang mengganti sandbox yang ada dengan sandbox yang memanfaatkan pustaka MXC.

Apa itu MXC?

MXC (Microsoft eXecution Container) adalah sistem eksekusi kode dalam sandbox⁠(terbuka di jendela baru) dari Microsoft yang mendukung beberapa backend isolasi di Windows, Linux, dan macOS. Codex mendukung sandbox berbasis MXC pada perangkat Windows yang kompatibel, menggunakan isolasi proses bawaan untuk membatasi perintah di lingkungan yang sudah digunakan pengguna.

Kami beralih ke MXC untuk meningkatkan keamanan dan kemudahan penggunaan sekaligus mengatasi beberapa keterbatasan sandbox Windows kami saat ini:

  • Perlunya hak akses lebih tinggi/admin untuk menyiapkan sandbox

  • Operasi pemeriksaan dan pengaturan ACL yang boros sumber daya/lambat

  • Status penyiapan sandbox yang menetap di mesin host, termasuk

    • ACL

    • Aturan firewall

    • Pengguna sandbox

    • File bidang kontrol

MXC menyediakan skema konfigurasi JSON⁠(terbuka di jendela baru). Codex menggunakan MXC SDK⁠(terbuka di jendela baru) untuk menyusun permintaan eksekusi yang mengikuti skema tersebut dan berisi perintah, direktori kerja, lingkungan, serta izin. Izin tersebut mencakup akses sistem file dan jaringan, serta sumber daya Windows seperti desktop dan clipboard.

Menerjemahkan kebijakan menjadi pemanggilan MXC

Codex menggunakan pengaturan tetap untuk beberapa kontrol guna menyeimbangkan kompatibilitas dan keamanan. Codex mengizinkan pembacaan registri dan mempertahankan akses Win32k serta desktop yang dibutuhkan PowerShell saat mulai berjalan. Akses clipboard, injeksi input, serta kontrol desktop dan pengaturan sistem dinonaktifkan. Terakhir, MXC dicegah menggunakan perubahan izin sistem file host sebagai mekanisme cadangan.

Codex menerjemahkan aturan sistem file dan jaringan dalam profil izin menjadi konfigurasi MXC. Dengan profil dev sebelumnya, dan dengan asumsi:

  • C:\, D:\, dan Z:\ adalah satu-satunya drive lokal di mesin tersebut.

  • Root ruang kerja dan direktori kerja berada di C:\work\demo.

  • Direktori home pengguna adalah D:\Users\dev, sehingga ~/build-cache merujuk ke D:\Users\dev\build-cache.

  • Pola glob penolakan hanya cocok dengan C:\work\demo\config\dev.env dan C:\work\demo\config\prod.env.

Pengaturan MXC yang sesuai akan mencakup:

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
}

Akses root drive

Kebijakan sistem file MXC menolak akses secara default. Karena itu, Codex menambahkan izin hanya baca untuk root drive lokal guna menyediakan akses baca luas yang diizinkan profil ini. Izin ini berlaku secara rekursif, dengan tetap tunduk pada izin OS pengguna yang ada.

Ada satu hal khusus: izin tulis pada root drive tidak berlaku secara rekursif, sehingga Codex memperluasnya agar mencakup file dan direktori yang sudah ada tepat di bawah root drive.

Izin yang bertentangan

Path yang lebih spesifik mengesampingkan izin direktori di atasnya, sehingga C:\work\demo dapat ditulisi di bawah C:\ yang hanya bisa dibaca, sementara C:\work\demo\.git tetap hanya bisa dibaca.

Jika penulisan path yang berbeda atau alias symlink/junction merujuk ke path yang sama, MXC menerapkan izin yang lebih ketat: penolakan akses lebih diutamakan daripada hanya baca, yang lebih diutamakan daripada baca-tulis.

Pola glob penolakan

MXC hanya menerima path penolakan konkret, sehingga Codex menguraikan pola glob penolakan menjadi file dan direktori yang cocok sebelum menjalankan perintah. Path baru yang cocok dengan pola glob tidak otomatis ditambahkan saat perintah sedang berjalan.

Akses jaringan

Aturan domain seperti *.openai.com ditegakkan oleh proxy jaringan Codex bersama yang dijelaskan sebelumnya. Codex menjalankan proxy tersebut di luar sandbox dan meneruskan alamatnya ke perintah melalui variabel lingkungan standar *_PROXY yang sama seperti disebutkan sebelumnya. MXC memblokir koneksi eksternal langsung sambil mengizinkan koneksi loopback host, termasuk akses ke proxy. Layanan lokal lainnya tetap dapat dijangkau.

Di macOS, Linux, dan Windows, harness menggunakan API sandbox yang sama untuk menjalankan perintah dengan profil izin. Implementasi khusus platform menangani penyiapan yang diperlukan untuk menerapkan batasan tersebut.

Membangun dengan sandbox Codex

Menulis dan menjalankan kode memberi agen cara yang fleksibel untuk memecahkan masalah di luar pengembangan perangkat lunak. Sandbox Codex memungkinkan agen menggunakan kemampuan tersebut di lingkungan yang sudah digunakan pengguna, dengan batasan eksplisit pada akses sistem file dan jaringan. Sandbox merupakan komponen dasar yang dapat digunakan kembali dalam harness, dan perintah codex sandbox membuatnya tersedia untuk alat yang Anda bangun sendiri.

Seiring agen menangani lebih banyak tugas, kami ingin menjadikan sandboxing praktis untuk lebih banyak alat dan lingkungan. Artinya, kami perlu mempermudah konfigurasi izin dan memanfaatkan perlindungan sistem operasi yang lebih baik saat tersedia. Tujuan kami adalah memperluas kemampuan agen sekaligus memastikan pengguna tetap memegang kendali atas apa yang dapat diakses agen.

Penulis

OpenAI

Ucapan terima kasih

Terima kasih khusus kepada David Wiesen, Charlie Weems, Viyat Bhalodia, dan Fotis Chantzis atas kontribusi mereka pada tulisan ini.