OpenAI

18 novembre 2026

Ingegneria

Dentro la sandbox di Codex

Come Codex esegue comandi sul tuo computer entro limiti che controlli tu.

Di Michael Bolin, membro dello staff tecnico

In OpenAI adottiamo un approccio di difesa in profondità⁠(si apre in una nuova finestra) per garantire la sicurezza degli agenti. Gli investimenti nell’addestramento e nell’allineamento sono fondamentali per questo obiettivo, ma implementiamo anche funzionalità nella nostra infrastruttura per agenti, Codex⁠(si apre in una nuova finestra), per offrire ulteriori protezioni. Poiché una delle attività più comuni (e potenzialmente rischiose) di Codex è eseguire comandi sul tuo computer, abbiamo creato la sandbox di Codex: permette a Codex di lavorare nell’ambiente che usi già, rispettando limiti di accesso al filesystem e alla rete che controlli tu.

Una ⁠(si apre in una nuova finestra)sandbox⁠(si apre in una nuova finestra) limita le risorse a cui un programma può accedere durante l’esecuzione. Per organizzare delle foto, potresti configurare la sandbox di Codex in modo che i comandi possano leggere e modificare i file in ~/Pictures, bloccando però l’accesso alla rete per impedire i caricamenti. Per la revisione del codice, potresti consentire l’accesso alla documentazione online mantenendo i file sorgente di sola lettura. Gli utenti configurano la sandbox di Codex tramite i ⁠(si apre in una nuova finestra)profili dei permessi⁠(si apre in una nuova finestra), che definiscono le restrizioni di accesso al filesystem e alla rete per una sessione di Codex.

In questo articolo partiremo dai compromessi alla base delle impostazioni predefinite della sandbox di Codex, per poi illustrarne la progettazione e spiegare come l’infrastruttura la utilizza per eseguire i comandi. Mostreremo come utenti finali e aziende possono adattarne i permessi alle proprie esigenze e come gli sviluppatori possono riutilizzare la sandbox nei propri strumenti. Infine, esamineremo come vengono applicate queste restrizioni su macOS, Linux e Windows.

Definire i confini della sandbox

La nostra filosofia per Codex è adottare impostazioni predefinite prudenti per la sandbox, che consentano comunque di svolgere un lavoro utile. Ad esempio, con un repository Git come radice dell’area di lavoro, il profilo dei permessi integrato :workspace:

  • Consente la scrittura nell’area di lavoro, mantenendo però directory come .git e .codex di sola lettura. Questo consente a Codex di modificare il codice sorgente senza chiedere il permesso a ogni modifica, impedendo però modifiche dirette a .codex/config.toml o agli hook di Git in .git/hooks.

  • Consente un ampio accesso in lettura al filesystem, nel rispetto dei permessi già assegnati all’utente dal sistema operativo. Compilatori, runtime e strumenti di build dipendono da SDK, librerie e configurazioni esterni al repository. Limitare la lettura all’area di lavoro impedirebbe il funzionamento di molti flussi di lavoro comuni. Il rovescio della medaglia è che anche file sensibili presenti altrove sulla macchina potrebbero rimanere leggibili, ad esempio file di configurazione contenenti chiavi API.

  • Disabilita l’accesso alla rete. Questo blocca i caricamenti diretti verso servizi esterni, inclusi i tentativi di esfiltrare dati che il comando può leggere. Impedisce anche operazioni legittime, come il download delle dipendenze, che richiedono permessi di accesso aggiuntivi.

Queste restrizioni impediscono un’ampia gamma di comportamenti indesiderati, ma restano possibili azioni dannose. Ad esempio, l’agente potrebbe inserire codice malevolo in un pacchetto installato localmente, come node_modules/prettier. Una modifica del genere potrebbe non comparire in git status, perché node_modules è spesso ignorato da Git. Se l’editor dell’utente esegue quella copia di Prettier al salvataggio, il semplice salvataggio di un file potrebbe eseguire il codice malevolo fuori dalla sandbox di Codex. Ecco perché adottiamo un approccio di difesa in profondità: la sandbox limita ciò a cui i comandi possono accedere, mentre l’addestramento e l’allineamento aiutano il modello a usare quell’accesso in linea con le intenzioni dell’utente.

Per indicazioni su come adattare i permessi della sandbox e combinarli con altre protezioni in un ambiente aziendale, consulta la guida pratica alla sicurezza di Codex⁠(si apre in una nuova finestra).

Progettare la sandbox

Le macchine virtuali e i container⁠(si apre in una nuova finestra) sono due meccanismi molto usati per il sandboxing, ma per la sandbox di Codex adottiamo un approccio diverso. Anziché spostare l’elaborazione in un ambiente separato per garantire l’isolamento, Codex usa le funzionalità di sandboxing di ciascuna piattaforma per limitare i comandi eseguiti nell’ambiente esistente dell’utente.

Per molti sviluppatori, il portatile è un ambiente di sviluppo su misura, che possono modificare quando vogliono. Riprodurre quell’ambiente in un container Docker può richiedere lavoro, e alcuni flussi di lavoro dipendono comunque da strumenti eseguiti sull’host.

Consideriamo, ad esempio, l’uso di Codex per sviluppare un’app iOS su un Mac. Se decidessi di isolare Codex eseguendolo in Docker, Codex non potrebbe eseguire la toolchain di build iOS, composta da eseguibili nativi per Mac, né avviare il simulatore iPhone per eseguire il codice. Un flusso di lavoro basato su Docker potrebbe delegare le build e le operazioni del simulatore al Mac host, ma queste verrebbero eseguite fuori dalla sandbox del container e richiederebbero restrizioni proprie. Per Codex preferiamo mantenere le cose semplici, investendo molto nel sandboxing specifico di ciascun sistema operativo, così che Codex possa operare nell’ambiente più adatto all’attività da svolgere.

L’infrastruttura espone questi meccanismi di sandboxing specifici del sistema operativo tramite un’API comune a macOS, Windows e Linux. Questa API riceve un comando e un profilo dei permessi. Se il profilo dei permessi consente un accesso limitato alla rete, il chiamante deve fornire un proxy di rete che faccia rispettare quei limiti:

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:

Questa funzione avvia il processo in una sandbox e restituisce un handle Child che l’infrastruttura può usare per attenderne la conclusione. Ogni processo figlio eredita i vincoli della sandbox del padre, quindi queste restrizioni si applicano all’intero albero dei processi avviato dal comando, anche ai discendenti che restano attivi dopo la conclusione del processo originale.

Il diagramma seguente mostra come si collegano questi elementi, dalla configurazione all’esecuzione di un comando in sandbox. Le sezioni successive illustrano ogni fase.

Diagramma di flusso: la configurazione e i requisiti gestiti definiscono il profilo dei permessi della sessione; l’infrastruttura di Codex avvia i comandi con restrizioni della sandbox specifiche per macOS, Linux o Windows. I processi figli ereditano queste restrizioni e un proxy di rete opzionale applica le regole sui domini.

Come l’infrastruttura sfrutta la sandbox

Come spiegato in Il ciclo dell’agente Codex, passo dopo passo, l’infrastruttura di Codex è responsabile dell’esecuzione delle chiamate agli strumenti generate dal modello. Per le attività di programmazione, lo strumento più usato è uno strumento shell, che esegue i comandi in modo analogo a un utente in una shell interattiva come Bash. Qui esamineremo lo strumento shell ⁠(si apre in una nuova finestra)exec_command⁠(si apre in una nuova finestra) one-shot⁠(si apre in una nuova finestra) per illustrare come l’infrastruttura utilizza la sandbox per ottenere le protezioni desiderate.

Questa è una versione semplificata di come l’infrastruttura di Codex gestirebbe la chiamata allo strumento
exec_command senza 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}

Per eseguire il comando in sandbox, l’infrastruttura sostituisce la chiamata a subprocess.Popen() con spawn_command_under_sandbox(). L’infrastruttura fornisce il profilo dei permessi e, quando necessario, il proxy di rete:

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}

Lo strumento exec_command consente anche al modello di richiedere permessi diversi per un singolo comando, ma è l’infrastruttura a decidere se accettare la richiesta:

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

Quando viene specificato use_default, l’infrastruttura usa la configurazione predefinita della sandbox per il turno. with_additional_permissions richiede un accesso più ampio all’interno della sandbox, mentre require_escalated richiede l’esecuzione al di fuori di essa. L’infrastruttura valuta la richiesta in base alle preferenze dell’utente prima di eseguire il comando. (Ad esempio, Codex può chiedere direttamente all’utente oppure inoltrare la richiesta alla revisione automatica⁠(si apre in una nuova finestra).) Se l’esecuzione viene autorizzata, Codex passa i valori appropriati di permission_profile e network_proxy a perform_exec_command_with_sandboxing(), insieme agli argomenti del comando della chiamata originale ExecCommandToolCall.

Lo strumento shell è il principale utilizzatore di spawn_command_under_sandbox() e l’infrastruttura riutilizza i propri meccanismi di sandboxing anche per operazioni come la lettura e la modifica di file locali. Questo riutilizzo si estende oltre l’infrastruttura: il comando codex sandbox consente di integrare l’esecuzione di comandi in sandbox nei tuoi strumenti, come vedremo più avanti. Ora vediamo come vengono definiti i profili dei permessi.

Configurare la sandbox

Un profilo dei permessi con un nome consente di riutilizzare le stesse restrizioni sul filesystem e sulla rete in più progetti. Puoi definire i tuoi profili nella sezione [permissions] di config.toml. Ad esempio, la configurazione seguente definisce un profilo chiamato dev che estende⁠(si apre in una nuova finestra) il profilo integrato :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"

Il profilo dev aggiunge l’accesso in scrittura a ~/build-cache e impone ulteriori restrizioni ai file nell’area di lavoro. Le voci relative al filesystem possono concedere l’accesso in sola lettura (read), in lettura e scrittura (write) o bloccare del tutto l’accesso (deny).

La tabella :workspace_roots consente di definire regole per i percorsi relativi alle radici dell’area di lavoro di un progetto. Per impostazione predefinita, la CLI di Codex usa la propria directory di lavoro come unica radice dell’area di lavoro, mentre l’app desktop di ChatGPT usa le cartelle sorgente del progetto. Codex applica ogni regola a tutte le radici: la voce .vscode in dev rende quindi la directory .vscode di sola lettura sotto ciascuna radice.

Oltre alle proprie regole, dev eredita da :workspace le seguenti protezioni:

TOML

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

Permessi di rete

Per configurare la rete della sandbox in Codex, ci sono sostanzialmente tre opzioni:

  • Disabilitare ogni accesso alla rete (impostazione predefinita per il profilo :workspace)

  • Abilitare l’accesso completo e diretto alla rete (impostazione predefinita per il profilo :danger-full-access)

  • Limitare l’accesso alla rete a un proxy, che decide cosa lasciar passare in base al profilo dei permessi


Per dare a
dev accesso diretto alla rete, imposta permissions.dev.network.enabled = true al livello principale di config.toml. Questo concede l’accesso completo alla rete quando il proxy di rete è disabilitato.

Per limitare dev a un insieme di domini, abilita il proxy di rete e configurane le regole sui domini:

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

Le regole sui domini supportano nomi esatti e pattern con caratteri jolly; le regole di divieto esplicite hanno la precedenza su quelle di autorizzazione. Le richieste verso altri domini richiedono approvazione o vengono bloccate, come descritto nella sezione Proxy di rete più avanti.

Configurazione a livelli e applicazione dei limiti

I singoli utenti possono configurare impostazioni predefinite valide per tutti i progetti e sovrascriverle per uno specifico progetto attendibile. Anche gli amministratori aziendali possono voler configurare impostazioni predefinite per i propri utenti e limitare quelle che gli utenti possono modificare. Codex supporta entrambe le esigenze tramite una configurazione a livelli e requisiti gestiti.

Come descritto in Precedenza della configurazione,⁠(si apre in una nuova finestra) Codex unisce le impostazioni di più file config.toml. Le tabelle vengono unite ricorsivamente; in caso di valori in conflitto, prevale la fonte con precedenza maggiore. Gli array vengono sostituiti per intero.

Ecco perché i profili dei permessi usano tabelle per i percorsi del filesystem e i domini di rete. Un team può aggiungere o sovrascrivere singole voci nella propria configurazione ed ereditare automaticamente le modifiche a tutte le altre voci della configurazione di base dell’organizzazione:

TOML

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

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

Gli amministratori possono anche fornire requisiti gestiti⁠(si apre in una nuova finestra) tramite requirements.toml per limitare le scelte di configurazione degli utenti. Questi requisiti possono provenire da più fonti, tra cui file di sistema e policy fornite dal cloud. Un caso d’uso comune consiste nello specificare allowed_permission_profiles per limitare l’insieme di profili dei permessi selezionabili da un utente aziendale. Ad esempio, un amministratore potrebbe specificare questi requisiti cloud:

TOML

1
default_permissions = ":read-only"
2

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

I requisiti cloud avrebbero la precedenza sul file dei requisiti di sistema in /etc/codex/requirements.toml, quindi una voce in quel file non può sovrascrivere l’impostazione esplicita ":danger-full-access" = false riportata sopra. Lasciare :workspace non specificato consente a un altro livello di requisiti di fornire quella voce. I profili le cui voci sono false o assenti dalla tabella finale risultante dall’unione non sono disponibili.

Questa separazione consente alle organizzazioni di imporre limiti e agli utenti di personalizzare la configurazione entro quei limiti. I profili dei permessi risultanti possono essere usati dall’infrastruttura o applicati direttamente a un comando, come vedremo ora.

Usare il comando codex sandbox

La CLI di Codex offre un comando sandbox per facilitare l’esecuzione di un comando qualsiasi con un profilo dei permessi definito nella configurazione di Codex. Viene comunemente usato per testare il profilo e verificare che la sandbox impedisca il comportamento che è stata progettata per bloccare.

Ad esempio, il comando seguente tenta di configurare VS Code per eseguire un formattatore automatico malevolo al salvataggio. Supponendo che .vscode esista già, il profilo dev definito sopra dovrebbe bloccare questa scrittura perché la directory è di sola lettura (per impostazione predefinita, codex sandbox considera cwd una radice dell’area di lavoro):

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

Infatti, su macOS l’operazione non riesce e restituisce:

Plain text

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

Il comando codex sandbox rende disponibile il meccanismo di sandboxing di Codex indipendentemente da una sessione dell’agente. Puoi usare lo stesso linguaggio di configurazione e gli stessi meccanismi di applicazione specifici della piattaforma per limitare i comandi avviati dai tuoi strumenti.

Esempio: isolare un server MCP in una sandbox

Per un server MCP stdio configurato in config.toml, l’infrastruttura di Codex non tenta di isolare in una sandbox il comando usato per avviarlo. Codex non può dedurre in modo affidabile quali file o servizi di rete servano a quel server, quindi applicare un profilo sandbox predefinito potrebbe compromettere una configurazione altrimenti valida.

Ad esempio, il modo standard per configurare il server MCP @modelcontextprotocol/server-memory⁠(si apre in una nuova finestra) per l’uso con Codex è il seguente:

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"

Poiché questo comando npx viene eseguito fuori da una sandbox, può scrivere file ed effettuare richieste di rete con gli stessi permessi dell’utente che esegue Codex, un livello di accesso eccessivo. Per limitarlo, possiamo definire un profilo dei permessi chiamato memory-mcp ed eseguire il comando npx originale tramite codex sandbox --permission-profile memory-mcp, così da limitare dove il server può scrivere e impedirgli di accedere alla rete:

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"

Prima di avviare il server, crea la sua directory dei dati e inserisci nella cache npm la versione fissata del pacchetto. In questo modo npx --offline può avviare il server con un profilo che disabilita l’accesso alla rete:

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

Una volta che il pacchetto è nella cache, Codex può avviare il server di memoria senza accesso alla rete, limitando la scrittura alla cache npm e alla directory dei dati del server.

Implementazione della sandbox di Codex

L’implementazione della sandbox traduce un profilo dei permessi in restrizioni applicate dal sistema operativo. La logica di base del proxy di rete per la gestione delle richieste e delle policy è condivisa tra i tre principali sistemi operativi, mentre la configurazione del proxy e l’integrazione con la sandbox sono specifiche del sistema operativo. Esamineremo prima il proxy condiviso, poi le implementazioni per macOS, Linux e Windows.

Proxy di rete

Per far rispettare le restrizioni di rete di un profilo dei permessi, l’infrastruttura avvia un proxy di rete e configura la sandbox per consentire le connessioni al proxy, bloccando quelle dirette verso host esterni. Il proxy verifica ogni richiesta rispetto alle regole sui domini del profilo per stabilire se inoltrarla.

Nel repository di Codex, il proxy di rete è implementato nel crate codex-network-proxy⁠(si apre in una nuova finestra), che l’infrastruttura usa come libreria, ma che può anche essere compilato come CLI autonoma⁠(si apre in una nuova finestra). Quando è abilitato, codex-network-proxy avvia per impostazione predefinita sia un proxy HTTP sia un proxy SOCKS5. Gli indirizzi di questi proxy vengono comunicati al processo avviato dalla sandbox tramite variabili d’ambiente. Oltre alle variabili d’ambiente standard come HTTP_PROXY, HTTPS_PROXY e ALL_PROXY, vengono inserite anche diverse variabili d’ambiente specifiche delle applicazioni⁠(si apre in una nuova finestra) di uso comune, come PIP_PROXY. Va detto che non tutti i programmi rispettano queste variabili d’ambiente. Se un programma tenta una connessione diretta a un host esterno, le restrizioni della sandbox applicate dal sistema operativo la bloccano, come descritto più avanti nelle sezioni dedicate alle singole piattaforme.

Il proxy di rete è responsabile dell’applicazione delle restrizioni di rete definite in un profilo dei permessi. Ad esempio, il profilo dev mostrato prima consente le richieste a *.openai.com e nega esplicitamente quelle a evil.example. Quando una richiesta è diretta a un dominio che non corrisponde a una regola di autorizzazione o divieto, il proxy può sospenderla mentre ne delega l’approvazione all’infrastruttura. Come nell’esempio del comando shell, Codex può chiedere direttamente all’utente oppure inoltrare la richiesta alla revisione automatica⁠(si apre in una nuova finestra). Ricevuta la decisione, il proxy lascia proseguire la richiesta oppure la rifiuta con una risposta di errore.

L’ordine è importante, perché anche una query DNS può rivelare informazioni codificate nel nome di un host. Il proxy risolve quindi il nome host richiesto solo dopo aver stabilito che è consentito o approvato. Tieni presente che regole con caratteri jolly molto ampie o l’accesso ai servizi DNS possono comunque consentire l’esfiltrazione tramite DNS.

macOS

Su macOS, Codex usa Seatbelt⁠(si apre in una nuova finestra), il meccanismo di sandboxing di Apple le cui restrizioni sono applicate dal kernel. Le policy di Seatbelt sono scritte in Sandbox Profile Language (SBPL), un linguaggio basato su Scheme per esprimere le restrizioni della sandbox. Codex invoca Seatbelt tramite il comando /usr/bin/sandbox-exec di macOS. Come codex sandbox, riceve opzioni che descrivono la sandbox seguite dal comando da eseguire:

Bash

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

PROFILE è una stringa SBPL che contiene le voci di configurazione della sandbox. Ad esempio, il seguente frammento SBPL rende /dev/null e /dev/zero leggibili e scrivibili secondo la policy della sandbox:

Scheme

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

Quando il proxy di rete è abilitato durante un’invocazione della sandbox, nel profilo vengono inserite regole come le seguenti per limitare le connessioni alle porte locali appropriate:

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


Il profilo di base di Codex inizia con
(deny default), quindi le connessioni in uscita rimangono bloccate se non sono esplicitamente consentite.

Infine, il codice SBPL può contenere segnaposto definiti tramite (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)))

che vengono valorizzati dalle opzioni -Dkey=value passate a sandbox-exec.

Per implementare la propria API della sandbox, Codex costruisce l’elenco degli argomenti⁠(si apre in una nuova finestra) di sandbox-exec a partire da una policy di base⁠(si apre in una nuova finestra), poi usa permission_profile e altre informazioni di contesto per modificarla e produrre il profilo Seatbelt completo. Il profilo risultante e i relativi argomenti -D configurano le restrizioni applicate da Seatbelt, mentre il proxy di rete applica ulteriori regole di rete. Una volta composto l’elenco completo degli argomenti, invocare sandbox-exec è semplice.

Generare codice SBPL corretto è complesso, perché Apple non documenta il linguaggio per l’uso da parte di terzi. Infatti, man sandbox-exec riporta The sandbox-exec command is DEPRECATED (lo è anche la funzione di libreria sandbox_init(), documentata tramite man 3 sandbox_init). Nonostante l’avviso di deprecazione, macOS include ancora profili Seatbelt in /usr/share/sandbox e il software di terze parti, tra cui Google Chrome e Chromium⁠(si apre in una nuova finestra), continua a usare Seatbelt. Per questo prevediamo di continuare a usare Seatbelt nel prossimo futuro.

Linux

Per creare la sandbox su Linux, Codex usa una combinazione di bubblewrap⁠(si apre in una nuova finestra) (bwrap), uno strumento da riga di comando per costruire ambienti isolati, e seccomp-bpf⁠(si apre in una nuova finestra), un meccanismo del kernel Linux per filtrare le chiamate di sistema. Un programma ausiliario interno chiamato codex-linux-sandbox coordina la configurazione. Come sandbox-exec su macOS, riceve una configurazione della sandbox seguita da un comando da eseguire:

Bash

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

Quando serve l’isolamento del filesystem o l’instradamento tramite proxy, codex-linux-sandbox invoca bwrap per creare l’ambiente iniziale della sandbox. bwrap avvia quindi codex-linux-sandbox --apply-seccomp-then-exec al suo interno. Questa seconda invocazione usa seccomp-bpf per applicare ulteriori restrizioni prima di eseguire il comando dell’utente.

Per costruire l’ambiente iniziale della sandbox, Codex usa bubblewrap per creare una vista del filesystem in un namespace di mount separato che rispecchi le regole del profilo dei permessi relative al filesystem. Poiché è fondamentale per l’implementazione della sandbox, Codex include una propria copia di bwrap nel caso in cui l’utente non ne abbia installata una, ma preferisce un’installazione compatibile di ⁠(si apre in una nuova finestra)bwrap⁠(si apre in una nuova finestra) presente in PATH, quando disponibile. Abbiamo osservato che alcune distribuzioni Linux disabilitano per impostazione predefinita l’accesso ai namespace utente⁠(si apre in una nuova finestra), ma prevedono un’eccezione per il bwrap di sistema.

Come sandbox-exec, anche bwrap riceve una configurazione della sandbox seguita da un comando da eseguire al suo interno. Invece di un linguaggio di configurazione dedicato come SBPL, bwrap usa singoli flag per la configurazione. Codex usa le seguenti opzioni per creare la vista del filesystem:

  • --bind per specificare un file o una directory scrivibile

  • --ro-bind per specificare un file o una directory di sola lettura

  • --perms 000 --tmpfs DIR --remount-ro DIR per negare l’accesso a DIR

  • --perms 000 --ro-bind-data FD FILE per negare l’accesso a FILE (dove FD è un descrittore di file aperto su /dev/null)

Per applicare i pattern glob di esclusione con queste opzioni, Codex li espande in percorsi concreti prima di avviare ogni comando. I nuovi percorsi corrispondenti non vengono aggiunti automaticamente alle restrizioni della sandbox di quel comando.

Codex specifica anche opzioni come --unshare-ipc e --unshare-pid per impedire alla sandbox di accedere ad altri tipi di risorse sull’host: l’effetto di bubblewrap, quindi, non si limita alla visibilità dei file.

Quando usa bubblewrap, Codex passa --unshare-net ogni volta che la rete è disabilitata o le connessioni devono passare dal proxy di rete, creando così un nuovo namespace di rete per la sandbox. Usiamo poi seccomp-bpf per applicare ulteriori restrizioni alle chiamate di sistema di rete e alle famiglie di socket disponibili al comando.


In particolare, usiamo il
crate seccompiler⁠(si apre in una nuova finestra) per compilare dinamicamente un programma BPF in base ai filtri desiderati⁠(si apre in una nuova finestra) e applicarlo a un processo di avvio nella sandbox, affinché i vincoli vengano ereditati dall’intero albero dei processi. Di conseguenza, bwrap non esegue il comando dell’utente, ma il programma di avvio codex-linux-sandbox con i propri argomenti di configurazione seguiti dal comando dell’utente:

Bash

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

Per applicare i filtri seccomp senza privilegi elevati, il programma di avvio imposta il flag no_new_privs di Linux⁠(si apre in una nuova finestra). Questo flag viene ereditato dai processi figli e impedisce loro di acquisire privilegi aggiuntivi quando eseguono un altro programma, ad esempio un eseguibile setuid.

I filtri seccomp dipendono dalla configurazione di rete. Quando l’accesso alla rete è disabilitato, blocchiamo diverse chiamate di sistema legate alla rete, come connect(2) e bind(2). Quando invece il proxy di rete è abilitato nella sandbox, consentiamo i socket IP per rendere raggiungibile il listener TCP creato da codex-linux-sandbox, ma blocchiamo per impostazione predefinita la creazione di socket di dominio Unix autonomi, che potrebbero consentire un accesso involontario alle risorse dell’host.

Connessione al proxy di rete

Quando la configurazione della sandbox richiede l’uso del proxy di rete, l’infrastruttura di Codex crea un’istanza del proxy riutilizzabile tra più invocazioni di codex-linux-sandbox all’interno dello stesso thread di Codex. Ogni sandbox deve poter raggiungere quel proxy condiviso dal proprio namespace di rete isolato. Codex fornisce un listener TCP di loopback all’interno di quel namespace e fa sì che un processo esterno alla sandbox ne accetti le connessioni e le inoltri al proxy.

I diagrammi seguenti illustrano questa configurazione per un endpoint del proxy; l’ultimo mostra una connessione che lo attraversa. Prima di avviare bubblewrap, codex-linux-sandbox crea una coppia di socket Unix da usare come canale di controllo ed esegue un fork di sé stesso. Il processo figlio esegue run_host_bridge() e attende di ricevere il descrittore di file del listener su quel canale:

Diagramma dell’infrastruttura di Codex che avvia codex-linux-sandbox, il quale crea tramite fork un processo di inoltro collegato attraverso un canale di controllo su socket Unix.

In questo esempio, il processo padre usa exec per sostituire la propria immagine di programma con bwrap. Quest’ultimo configura la sandbox e avvia codex-linux-sandbox --apply-seccomp-then-exec al suo interno, passando il descrittore di file del canale di controllo:

Diagramma in cui bwrap crea un namespace di rete per la sandbox e avvia codex-linux-sandbox al suo interno, con un canale di controllo su socket Unix verso il processo di inoltro esterno alla sandbox.

Nel namespace di rete della sandbox, la seconda invocazione di codex-linux-sandbox crea un listener TCP di loopback e ne passa il descrittore di file tramite il socket. Il listener resta associato al namespace di rete della sandbox, consentendo al processo figlio rimasto all’esterno di accettare connessioni dai programmi nella sandbox e di aprire le proprie connessioni verso monte nel namespace di rete dell’host. Dopo il passaggio, entrambi i processi chiudono i propri descrittori del canale di controllo e il processo nella sandbox chiude la propria copia del listener.

Una volta pronto il listener TCP, il processo all’interno della sandbox imposta il valore appropriato per HTTP_PROXY⁠(si apre in una nuova finestra) e le relative variabili d’ambiente, in modo che puntino a quel listener. Applica quindi seccomp prima di eseguire il fork e avviare il comando dell’utente:

Diagramma di un programma in sandbox che si connette a un listener TCP di loopback, con un processo di inoltro codex-linux-sandbox esterno che invia il traffico al proxy di rete di Codex.

Il processo esterno alla sandbox mantiene aperto il listener. Per ogni connessione accettata, apre una connessione al proxy configurato e inoltra i dati in entrambe le direzioni.

Questo meccanismo aggiuntivo assegna al comando un namespace di rete dedicato, con un’interfaccia di loopback separata. Su macOS, Seatbelt consente al comando di connettersi direttamente a porte specifiche dell’interfaccia di loopback dell’host. Su Linux, invece, il comando si connette a un listener nel proprio namespace isolato e un processo esterno alla sandbox inoltra quelle connessioni al proxy configurato. Il passaggio del descrittore rende possibile questa connessione senza esporre al comando il namespace di rete dell’host.

Windows

All’inizio di quest’anno abbiamo implementato il sandboxing su Windows e descritto il nostro lavoro in un articolo. Da allora, Microsoft ha rilasciato una libreria chiamata MXC insieme a nuove funzionalità per l’isolamento dei processi nel sistema operativo Windows. Stiamo sostituendo la sandbox esistente con una che utilizza la libreria MXC.

Che cos’è MXC?

MXC (Microsoft eXecution Container) è un sistema di esecuzione del codice in sandbox⁠(si apre in una nuova finestra) di Microsoft che supporta diversi backend di isolamento su Windows, Linux e macOS. Codex supporta una sandbox basata su MXC sui dispositivi Windows compatibili, utilizzando l’isolamento nativo dei processi per limitare i comandi all’interno dell’ambiente esistente dell’utente.

Stiamo passando a MXC per migliorare sicurezza e usabilità, superando al contempo diversi limiti della nostra attuale sandbox per Windows:

  • Necessità di privilegi elevati o di amministratore per configurare la sandbox

  • Operazioni di verifica e impostazione delle ACL lente e onerose

  • Stato di configurazione della sandbox persistente sulla macchina host, tra cui

    • ACL

    • Regole del firewall

    • Utenti della sandbox

    • File del piano di controllo

MXC espone uno schema di configurazione JSON⁠(si apre in una nuova finestra). Codex utilizza l’SDK di MXC⁠(si apre in una nuova finestra) per costruire una richiesta di esecuzione conforme a quello schema, contenente il comando, la directory di lavoro, l’ambiente e i permessi. Questi permessi riguardano l’accesso al filesystem e alla rete, oltre a risorse di Windows come il desktop e gli appunti.

Dalle policy all’invocazione di MXC

Codex usa impostazioni fisse per diversi controlli, così da bilanciare compatibilità e sicurezza. Consente la lettura del registro e mantiene l’accesso a Win32k e al desktop necessario a PowerShell durante l’avvio. L’accesso agli appunti, l’iniezione di input e i controlli del desktop e delle impostazioni di sistema sono disabilitati. Infine, a MXC viene impedito di ricorrere alla modifica dei permessi del filesystem dell’host come soluzione alternativa.

Codex traduce le regole del profilo dei permessi relative al filesystem e alla rete nella configurazione di MXC. Usando il profilo dev precedente e supponendo che:

  • C:\, D:\ e Z:\ siano le uniche unità locali della macchina.

  • La radice dell’area di lavoro e la directory di lavoro siano C:\work\demo.

  • La directory home dell’utente sia D:\Users\dev, quindi ~/build-cache corrisponda a D:\Users\dev\build-cache.

  • Il pattern glob di esclusione corrisponda solo a C:\work\demo\config\dev.env e C:\work\demo\config\prod.env.

Le impostazioni MXC corrispondenti includerebbero:

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
}

Accesso alla radice delle unità

La policy del filesystem di MXC nega l’accesso per impostazione predefinita. Codex aggiunge quindi permessi di sola lettura per le radici delle unità locali, così da offrire l’ampio accesso in lettura consentito da questo profilo. Questi permessi si applicano ricorsivamente, nel rispetto dei permessi già assegnati all’utente dal sistema operativo.

C’è una particolarità: i permessi di scrittura sulla radice di un’unità non si applicano ricorsivamente, quindi Codex li estende agli elementi già presenti direttamente al suo interno.

Permessi in conflitto

I percorsi più specifici prevalgono sui permessi delle directory superiori: C:\work\demo può quindi essere scrivibile sotto una radice C:\ di sola lettura, mentre C:\work\demo\.git rimane di sola lettura.

Quando diverse forme di un percorso o alias tramite link simbolici o junction si riferiscono allo stesso percorso, MXC applica il permesso più restrittivo: il divieto di accesso prevale sulla sola lettura, che a sua volta prevale sulla lettura e scrittura.

Pattern glob di esclusione

MXC accetta solo percorsi concreti a cui negare l’accesso, quindi Codex espande i pattern glob di esclusione nei file e nelle directory corrispondenti prima dell’avvio. I nuovi percorsi che corrispondono al pattern glob non vengono aggiunti automaticamente durante l’esecuzione del comando.

Accesso alla rete

Le regole sui domini, come *.openai.com, vengono applicate dal proxy di rete condiviso di Codex descritto in precedenza. Codex esegue il proxy fuori dalla sandbox e ne passa gli indirizzi al comando tramite le stesse variabili d’ambiente standard *_PROXY menzionate prima. MXC blocca le connessioni dirette verso l’esterno, consentendo invece quelle sull’interfaccia di loopback dell’host, incluso l’accesso al proxy. Gli altri servizi locali restano raggiungibili.

Su macOS, Linux e Windows, l’infrastruttura usa la stessa API della sandbox per avviare comandi con un profilo dei permessi. Le implementazioni specifiche di ciascuna piattaforma gestiscono la configurazione necessaria per applicare quelle restrizioni.

Sviluppare a partire dalla sandbox di Codex

Scrivere ed eseguire codice offre agli agenti un modo flessibile per risolvere problemi che vanno oltre lo sviluppo software. La sandbox di Codex permette loro di usare questa capacità nell’ambiente esistente dell’utente, con limiti espliciti all’accesso al filesystem e alla rete. È una primitiva riutilizzabile all’interno dell’infrastruttura e il comando codex sandbox la rende disponibile agli strumenti che sviluppi tu.

Man mano che gli agenti svolgono più attività, vogliamo rendere il sandboxing praticabile per un numero sempre maggiore di strumenti e ambienti. Questo significa semplificare la configurazione dei permessi e sfruttare le migliori protezioni dei sistemi operativi man mano che diventano disponibili. Il nostro obiettivo è ampliare ciò che gli agenti possono fare, lasciando alle persone il controllo su ciò a cui possono accedere.

Autore

OpenAI

Ringraziamenti

Un ringraziamento speciale a David Wiesen, Charlie Weems, Viyat Bhalodia e Fotis Chantzis per il loro contributo a questo articolo.