OpenAI

18 novembre 2026

Ingénierie

Au cœur du bac à sable de Codex

Comment Codex exécute des commandes sur votre machine avec des limites que vous contrôlez.

Par Michael Bolin, membre de l’équipe technique

Chez OpenAI, nous adoptons une approche de défense en profondeur⁠(ouverture dans une nouvelle fenêtre) pour sécuriser les agents. Si nos investissements dans l’entraînement et l’alignement sont essentiels à cet effort, nous intégrons aussi des fonctionnalités à notre harnais agentique, Codex⁠(ouverture dans une nouvelle fenêtre), pour offrir des protections supplémentaires. L’une des actions les plus courantes (et potentiellement risquées) de Codex étant d’exécuter des commandes sur votre ordinateur, nous avons créé le bac à sable de Codex pour qu’il puisse travailler dans votre environnement existant, avec des limites d’accès au système de fichiers et au réseau que vous contrôlez.

Un ⁠(ouverture dans une nouvelle fenêtre)bac à sable⁠(ouverture dans une nouvelle fenêtre) limite ce à quoi un programme peut accéder pendant son exécution. Pour organiser des photos, vous pouvez configurer le bac à sable de Codex afin que les commandes puissent lire et modifier les fichiers dans ~/Pictures, tout en bloquant l’accès au réseau pour empêcher leur envoi. Pour une revue de code, vous pouvez autoriser l’accès à la documentation en ligne tout en gardant les fichiers sources en lecture seule. Les utilisateurs configurent le bac à sable de Codex au moyen de ⁠(ouverture dans une nouvelle fenêtre)profils d’autorisations⁠(ouverture dans une nouvelle fenêtre), qui définissent les restrictions d’accès au système de fichiers et au réseau pour une session Codex.

Dans cet article, nous commencerons par les compromis qui sous-tendent les paramètres par défaut du bac à sable de Codex, puis expliquerons sa conception et la façon dont le harnais l’utilise pour exécuter des commandes. Nous montrerons comment les utilisateurs finaux et les entreprises peuvent adapter ses autorisations à leurs besoins, et comment les développeurs peuvent réutiliser le bac à sable dans leurs propres outils. Enfin, nous examinerons comment ces restrictions sont appliquées sur macOS, Linux et Windows.

Choisir les limites du bac à sable

Pour Codex, notre philosophie consiste à définir des paramètres par défaut prudents pour le bac à sable, tout en permettant un travail utile. Par exemple, avec un dépôt Git comme racine de l’espace de travail, le profil d’autorisations intégré :workspace :

  • Autorise l’écriture dans l’espace de travail, tout en gardant des répertoires comme .git et .codex en lecture seule. Cela permet à Codex de modifier le code source sans demander d’autorisation à chaque changement, tout en empêchant les modifications directes de .codex/config.toml ou des hooks Git sous .git/hooks.

  • Autorise un accès étendu en lecture au système de fichiers, sous réserve des autorisations système existantes de l’utilisateur. Les compilateurs, environnements d’exécution et outils de compilation dépendent de SDK, de bibliothèques et de configurations situés hors du dépôt. Limiter la lecture à l’espace de travail empêcherait de nombreux workflows courants de fonctionner. En contrepartie, des fichiers sensibles situés ailleurs sur la machine peuvent aussi rester lisibles, comme des fichiers de configuration contenant des clés API.

  • Désactive l’accès au réseau. Cela bloque les envois directs vers des services externes, y compris les tentatives d’exfiltration de données que la commande peut lire. Cela empêche aussi des opérations légitimes comme le téléchargement de dépendances, qui nécessitent un accès supplémentaire.

Ces restrictions empêchent un large éventail de comportements indésirables, mais des actions nuisibles restent possibles. Par exemple, l’agent pourrait injecter du code malveillant dans un paquet installé localement, comme node_modules/prettier. Une telle modification pourrait ne pas apparaître dans git status, car node_modules est souvent ignoré par Git. Si l’éditeur de l’utilisateur exécute cette copie de Prettier à l’enregistrement, le simple fait d’enregistrer un fichier pourrait exécuter le code malveillant hors du bac à sable de Codex. C’est pourquoi nous adoptons une approche de défense en profondeur : le bac à sable limite les accès des commandes, tandis que l’entraînement et l’alignement aident le modèle à utiliser ces accès conformément à l’intention de l’utilisateur.

Pour savoir comment adapter les autorisations du bac à sable et les combiner avec d’autres protections en entreprise, consultez le guide pratique de sécurité de Codex⁠(ouverture dans une nouvelle fenêtre).

Concevoir le bac à sable

Les machines virtuelles et les conteneurs⁠(ouverture dans une nouvelle fenêtre) sont deux mécanismes courants de mise en bac à sable, mais nous adoptons une approche différente pour celui de Codex. Au lieu de déplacer les calculs vers un environnement distinct pour assurer l’isolation, Codex utilise les mécanismes de mise en bac à sable de chaque plateforme pour restreindre les commandes exécutées dans l’environnement existant de l’utilisateur.

Pour de nombreux développeurs, leur ordinateur portable sert d’environnement de développement sur mesure, qu’ils peuvent modifier à leur guise. Reproduire cet environnement dans un conteneur Docker peut demander du travail, et certains workflows dépendent toujours d’outils exécutés sur l’hôte.

Prenons par exemple l’utilisation de Codex pour développer une application iOS sur un Mac. Si vous décidiez d’isoler Codex en l’exécutant dans Docker, il ne pourrait ni exécuter la chaîne de compilation iOS composée d’exécutables Mac natifs, ni lancer le simulateur iPhone pour exécuter le code. Un workflow fondé sur Docker pourrait déléguer les compilations et les opérations du simulateur au Mac hôte, mais ces opérations s’exécuteraient hors du bac à sable du conteneur et nécessiteraient leurs propres restrictions. Pour Codex, nous privilégions la simplicité en investissant fortement dans la mise en bac à sable propre à chaque système d’exploitation, afin qu’il puisse s’exécuter dans l’environnement le mieux adapté à la tâche.

Le harnais expose ces mécanismes de mise en bac à sable propres à chaque système via une API commune à macOS, Windows et Linux. Cette API prend une commande et un profil d’autorisations. Si le profil d’autorisations permet un accès limité au réseau, l’appelant doit fournir un proxy réseau pour faire respecter ces limites :

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:

Cette fonction démarre le processus dans un bac à sable et renvoie un handle Child que le harnais peut utiliser pour attendre sa fin. Chaque processus enfant hérite des contraintes du bac à sable de son parent. Ces restrictions s’appliquent donc à tout l’arbre des processus lancé par la commande, même aux descendants qui survivent au processus d’origine.

Le diagramme suivant montre comment ces éléments s’articulent, de la configuration à l’exécution d’une commande en bac à sable. Les sections suivantes expliquent chaque étape.

Diagramme de flux : la configuration et les exigences gérées définissent un profil d’autorisations de session ; le harnais Codex lance les commandes sous les restrictions du bac à sable propres à macOS, Linux ou Windows. Les processus enfants héritent de ces restrictions, et un proxy réseau facultatif applique les règles de domaine.

Comment le harnais utilise le bac à sable

Comme expliqué dans Dérouler la boucle de l’agent Codex, le harnais Codex est chargé d’exécuter les appels d’outils générés par le modèle. Pour les tâches de programmation, l’outil le plus utilisé est un outil shell, qui exécute des commandes comme le ferait un utilisateur dans un shell interactif tel que Bash. Nous examinerons ici l’outil shell ⁠(ouverture dans une nouvelle fenêtre)exec_command⁠(ouverture dans une nouvelle fenêtre) en une seule étape⁠(ouverture dans une nouvelle fenêtre) pour illustrer comment le harnais utilise le bac à sable afin d’obtenir les protections souhaitées.

Voici une version simplifiée de la manière dont l’appel à l’outil
exec_command serait traité par le harnais Codex sans mise en bac à sable :

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}

Pour isoler la commande dans le bac à sable, le harnais remplace l’appel à subprocess.Popen() par spawn_command_under_sandbox(). Le harnais fournit le profil d’autorisations et, si nécessaire, le proxy réseau :

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}

L’outil exec_command permet aussi au modèle de demander des autorisations différentes pour une commande donnée, mais le harnais décide s’il accepte la demande :

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

Lorsque use_default est spécifié, le harnais utilise la configuration de bac à sable par défaut pour le tour. with_additional_permissions demande un accès étendu dans le bac à sable, tandis que require_escalated demande une exécution à l’extérieur. Le harnais évalue la demande selon les préférences de l’utilisateur avant d’exécuter la commande. (Par exemple, Codex peut solliciter directement l’utilisateur ou transmettre la demande à l’examen automatique⁠(ouverture dans une nouvelle fenêtre).) Si l’exécution est autorisée, Codex transmet les valeurs appropriées de permission_profile et network_proxy à perform_exec_command_with_sandboxing(), avec les arguments de commande de l’ExecCommandToolCall d’origine.

L’outil shell est le principal utilisateur de spawn_command_under_sandbox(), et le harnais réutilise aussi son infrastructure de mise en bac à sable pour des opérations comme la lecture et la modification de fichiers locaux. Cette réutilisation dépasse le harnais : la commande codex sandbox permet d’intégrer l’exécution de commandes en bac à sable à vos propres outils, comme nous le verrons plus loin. Voyons maintenant comment les profils d’autorisations sont définis.

Configurer le bac à sable

Un profil d’autorisations nommé permet de réutiliser les mêmes restrictions d’accès au système de fichiers et au réseau dans plusieurs projets. Vous pouvez définir vos propres profils sous [permissions] dans config.toml. Par exemple, la configuration suivante définit un profil nommé dev qui étend⁠(ouverture dans une nouvelle fenêtre) le profil intégré :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"

Le profil dev ajoute un accès en écriture à ~/build-cache et impose des restrictions supplémentaires aux fichiers de l’espace de travail. Les entrées du système de fichiers peuvent accorder un accès en lecture seule (read), en lecture et écriture (write), ou bloquer tout accès (deny).

La table :workspace_roots permet de définir des règles pour les chemins relatifs aux racines de l’espace de travail d’un projet. Par défaut, la CLI Codex utilise son répertoire de travail comme unique racine d’espace de travail, tandis que l’application de bureau ChatGPT utilise les dossiers sources du projet. Codex applique chaque règle à toutes les racines : l’entrée .vscode de dev rend donc le répertoire .vscode accessible en lecture seule sous chaque racine.

Outre ses propres règles, dev hérite des protections suivantes de :workspace :

TOML

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

Autorisations réseau

Pour configurer le réseau du bac à sable dans Codex, il existe essentiellement trois options :

  • Désactiver tout accès au réseau (par défaut pour le profil :workspace)

  • Activer un accès direct et complet au réseau (par défaut pour le profil :danger-full-access)

  • Limiter l’accès au réseau à un proxy, qui décide de ce qu’il laisse passer selon le profil d’autorisations


Pour donner à
dev un accès direct au réseau, définissez permissions.dev.network.enabled = true au premier niveau de config.toml. Cela accorde un accès complet au réseau lorsque le proxy réseau est désactivé.

Pour limiter dev à un ensemble de domaines, activez le proxy réseau et configurez ses règles de domaine :

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

Les règles de domaine acceptent les noms exacts et les motifs avec caractères génériques ; les règles de refus explicites prévalent sur les règles d’autorisation. Les requêtes vers d’autres domaines nécessitent une approbation ou sont bloquées, comme décrit dans la section Proxy réseau ci-dessous.

Superposer les configurations et imposer des limites

Les utilisateurs peuvent définir des paramètres par défaut communs à leurs projets et les remplacer pour un projet de confiance donné. Les administrateurs d’entreprise peuvent aussi vouloir définir des paramètres par défaut pour leurs utilisateurs et limiter les paramètres que ceux-ci peuvent modifier. Codex prend en charge ces deux besoins grâce à une configuration en couches et à des exigences gérées.

Comme décrit dans Priorité des configurations,⁠(ouverture dans une nouvelle fenêtre) Codex fusionne les paramètres de plusieurs fichiers config.toml. Les tables sont fusionnées récursivement ; en cas de conflit de valeurs, la source de priorité supérieure l’emporte. Les tableaux sont remplacés intégralement.

C’est pourquoi les profils d’autorisations utilisent des tables pour les chemins du système de fichiers et les domaines réseau. Une équipe peut ajouter ou remplacer des entrées individuelles dans sa propre configuration et hériter automatiquement des modifications de toutes les autres entrées de la configuration de base de l’organisation :

TOML

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

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

Les administrateurs peuvent aussi fournir des exigences gérées⁠(ouverture dans une nouvelle fenêtre) via requirements.toml pour limiter les choix de configuration des utilisateurs. Ces exigences peuvent provenir de plusieurs sources, notamment de fichiers système et de politiques fournies par le cloud. Un cas d’usage courant consiste à spécifier allowed_permission_profiles pour limiter l’ensemble des profils d’autorisations qu’un utilisateur d’entreprise peut sélectionner. Par exemple, un administrateur pourrait spécifier les exigences cloud suivantes :

TOML

1
default_permissions = ":read-only"
2

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

Les exigences du cloud prévaudraient sur le fichier d’exigences système situé dans /etc/codex/requirements.toml : une entrée de ce fichier ne peut donc pas remplacer le paramètre explicite ":danger-full-access" = false ci-dessus. Ne pas spécifier :workspace permet à une autre couche d’exigences de fournir cette entrée. Les profils dont les entrées valent false ou sont absentes de la table fusionnée finale ne sont pas disponibles.

Cette séparation permet aux organisations d’imposer des limites, tout en laissant les utilisateurs adapter leur configuration dans ces limites. Les profils d’autorisations obtenus peuvent être utilisés par le harnais ou appliqués directement à une commande, comme nous le verrons ensuite.

Utiliser la commande codex sandbox

La CLI Codex fournit une commande sandbox pour faciliter l’exécution de n’importe quelle commande sous un profil d’autorisations défini dans la configuration de Codex. Elle sert couramment à tester le profil pour vérifier que le bac à sable empêche bien les comportements qu’il est conçu pour bloquer.

Par exemple, la commande suivante tente de configurer VS Code pour exécuter un outil de formatage automatique malveillant à l’enregistrement. En supposant que .vscode existe déjà, le profil dev défini ci-dessus devrait bloquer cette écriture, car ce répertoire est en lecture seule (codex sandbox traite par défaut cwd comme une racine d’espace de travail) :

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

En effet, sur macOS, cette commande échoue avec le message suivant :

Texte brut

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

La commande codex sandbox rend le mécanisme de mise en bac à sable de Codex accessible indépendamment d’une session d’agent. Vous pouvez utiliser le même langage de configuration et les mêmes mécanismes d’application propres à chaque plateforme pour restreindre les commandes lancées par vos outils.

Exemple : isoler un serveur MCP dans un bac à sable

Pour un serveur MCP stdio configuré dans config.toml, le harnais Codex ne tente pas d’isoler dans un bac à sable la commande utilisée pour démarrer le serveur. Codex ne peut pas déduire de manière fiable les fichiers ou services réseau dont ce serveur a besoin. Appliquer un profil de bac à sable par défaut pourrait donc rendre inopérante une configuration pourtant valide.

Par exemple, voici la méthode standard pour configurer le serveur MCP @modelcontextprotocol/server-memory⁠(ouverture dans une nouvelle fenêtre) afin de l’utiliser avec Codex :

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"

Comme cette commande npx s’exécute hors d’un bac à sable, elle peut écrire des fichiers et effectuer des requêtes réseau avec les mêmes autorisations que l’utilisateur qui exécute Codex, ce qui est trop permissif. Pour la verrouiller, nous pouvons définir un profil d’autorisations nommé memory-mcp, puis encapsuler la commande npx d’origine avec codex sandbox --permission-profile memory-mcp pour limiter les emplacements où le serveur peut écrire et lui interdire l’accès au réseau :

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"

Avant de démarrer le serveur, créez son répertoire de données et placez la version fixée du paquet dans le cache npm. Cela permet à npx --offline de lancer le serveur sous un profil qui désactive l’accès au réseau :

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

Une fois le paquet en cache, Codex peut démarrer le serveur de mémoire sans accès au réseau, avec des écritures limitées au cache npm et au répertoire de données du serveur.

Implémentation du bac à sable de Codex

L’implémentation du bac à sable transforme un profil d’autorisations en restrictions appliquées par le système d’exploitation. La logique centrale de traitement des requêtes et d’application des politiques du proxy réseau est commune aux trois principaux systèmes d’exploitation, tandis que sa configuration et son intégration au bac à sable sont propres à chaque système. Nous examinerons d’abord le proxy commun, puis les implémentations pour macOS, Linux et Windows.

Proxy réseau

Pour appliquer les restrictions réseau d’un profil d’autorisations, le harnais démarre un proxy réseau et configure le bac à sable pour autoriser les connexions vers celui-ci tout en bloquant les connexions directes aux hôtes externes. Le proxy vérifie chaque requête au regard des règles de domaine du profil pour déterminer s’il doit la transmettre.

Dans le dépôt Codex, le proxy réseau est implémenté dans la crate codex-network-proxy⁠(ouverture dans une nouvelle fenêtre), que le harnais utilise comme bibliothèque, mais qui peut aussi être compilée en CLI autonome⁠(ouverture dans une nouvelle fenêtre). Lorsqu’il est activé, codex-network-proxy démarre par défaut un proxy HTTP et un proxy SOCKS5. Les adresses de ces proxys sont communiquées au processus lancé par le bac à sable via des variables d’environnement. Outre les variables d’environnement standard comme HTTP_PROXY, HTTPS_PROXY et ALL_PROXY, plusieurs variables d’environnement propres aux applications⁠(ouverture dans une nouvelle fenêtre) bien connues (comme PIP_PROXY) sont également injectées. Certes, tous les programmes ne tiennent pas compte de ces variables d’environnement. Si un programme tente de se connecter directement à un hôte externe, les restrictions du bac à sable imposées par le système d’exploitation le bloquent, comme décrit dans les sections propres à chaque plateforme ci-dessous.

Le proxy réseau est chargé d’appliquer les restrictions réseau définies dans un profil d’autorisations. Par exemple, le profil dev présenté précédemment autorise les requêtes vers *.openai.com et refuse explicitement celles vers evil.example. Lorsqu’une requête vise un domaine qui ne correspond à aucune règle d’autorisation ou de refus, le proxy peut la suspendre pendant qu’il en délègue l’approbation au harnais. Comme dans l’exemple de commande shell, Codex peut solliciter directement l’utilisateur ou transmettre la demande à l’examen automatique⁠(ouverture dans une nouvelle fenêtre). Une fois la décision reçue, le proxy autorise la poursuite de la requête ou la rejette avec une réponse d’erreur.

L’ordre est important ici, car même une requête DNS peut divulguer des informations encodées dans un nom d’hôte. Le proxy ne résout donc le nom d’hôte demandé qu’après avoir déterminé qu’il est autorisé ou approuvé. Notez que des règles trop larges avec caractères génériques ou l’accès à des services DNS peuvent toujours permettre une exfiltration via DNS.

macOS

Sur macOS, Codex utilise Seatbelt⁠(ouverture dans une nouvelle fenêtre), le mécanisme de mise en bac à sable d’Apple appliqué par le noyau. Les politiques Seatbelt sont écrites en Sandbox Profile Language (SBPL), un langage fondé sur Scheme pour exprimer les restrictions du bac à sable. Codex appelle Seatbelt via la commande macOS /usr/bin/sandbox-exec. Comme codex sandbox, elle prend des options décrivant le bac à sable, suivies de la commande à exécuter :

Bash

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

PROFILE est une chaîne SBPL contenant les entrées qui configurent le bac à sable. Par exemple, l’extrait SBPL suivant rend /dev/null et /dev/zero accessibles en lecture et en écriture selon la politique du bac à sable :

Scheme

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

Lorsque le proxy réseau est activé lors d’un appel au bac à sable, des règles comme les suivantes sont injectées dans le profil pour limiter les connexions aux ports locaux appropriés :

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


Le profil de base de Codex commence par
(deny default) : les connexions sortantes restent donc bloquées sauf autorisation explicite.

Enfin, le SBPL peut contenir des paramètres substituables utilisant (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)))

dont les valeurs sont fournies par les options -Dkey=value transmises à sandbox-exec.

Pour implémenter sa propre API de bac à sable, Codex construit la liste des arguments⁠(ouverture dans une nouvelle fenêtre) de sandbox-exec à partir d’une politique de base⁠(ouverture dans une nouvelle fenêtre), puis utilise permission_profile et d’autres éléments de contexte pour l’adapter et produire le profil Seatbelt complet. Le profil obtenu et les arguments -D associés configurent les restrictions appliquées par Seatbelt, tandis que le proxy réseau impose des règles réseau supplémentaires. Une fois la liste complète des arguments assemblée, l’appel à sandbox-exec est simple.

Générer un SBPL correct est difficile, car Apple ne documente pas ce langage pour les usages tiers. En effet, man sandbox-exec indique The sandbox-exec command is DEPRECATED (tout comme la fonction de bibliothèque sandbox_init(), documentée via man 3 sandbox_init). Malgré cet avertissement d’obsolescence, macOS fournit toujours des profils Seatbelt dans /usr/share/sandbox, et des logiciels tiers, dont Google Chrome et Chromium⁠(ouverture dans une nouvelle fenêtre), continuent de s’appuyer sur Seatbelt. Nous prévoyons donc de continuer à utiliser Seatbelt dans un avenir prévisible.

Linux

Pour créer le bac à sable sur Linux, Codex associe bubblewrap⁠(ouverture dans une nouvelle fenêtre) (bwrap), un outil en ligne de commande pour construire des environnements isolés, à seccomp-bpf⁠(ouverture dans une nouvelle fenêtre), un mécanisme du noyau Linux qui filtre les appels système. Un utilitaire interne nommé codex-linux-sandbox coordonne la configuration. Comme sandbox-exec sur macOS, il prend une configuration de bac à sable, suivie d’une commande à exécuter :

Bash

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

Lorsqu’une isolation du système de fichiers ou un routage via proxy est nécessaire, codex-linux-sandbox appelle bwrap pour créer l’environnement initial du bac à sable. bwrap y lance ensuite codex-linux-sandbox --apply-seccomp-then-exec. Ce second appel utilise seccomp-bpf pour appliquer des restrictions supplémentaires avant d’exécuter la commande de l’utilisateur.

Pour construire cet environnement initial, Codex utilise bubblewrap afin de créer une vue du système de fichiers dans un espace de noms de montage distinct, qui reflète les règles du profil d’autorisations relatives au système de fichiers. Ce composant étant essentiel à l’implémentation du bac à sable, Codex intègre sa propre copie de bwrap au cas où l’utilisateur ne l’aurait pas installé, mais privilégie une installation compatible de ⁠(ouverture dans une nouvelle fenêtre)bwrap⁠(ouverture dans une nouvelle fenêtre) trouvée dans PATH, si elle existe. En pratique, certaines distributions Linux désactivent par défaut l’accès aux espaces de noms utilisateur⁠(ouverture dans une nouvelle fenêtre), mais accordent une exception au bwrap du système.

Comme sandbox-exec, bwrap prend une configuration de bac à sable, suivie d’une commande à y exécuter. Au lieu d’un langage de configuration spécifique comme SBPL, bwrap utilise des options individuelles pour sa configuration. Codex utilise les options suivantes pour créer la vue du système de fichiers :

  • --bind pour spécifier un fichier ou un répertoire accessible en écriture

  • --ro-bind pour spécifier un fichier ou un répertoire en lecture seule

  • --perms 000 --tmpfs DIR --remount-ro DIR pour refuser l’accès à DIR

  • --perms 000 --ro-bind-data FD FILE pour refuser l’accès à FILE (où FD est un descripteur de fichier ouvert sur /dev/null)

Pour appliquer les motifs glob de refus avec ces options, Codex les développe en chemins concrets avant de lancer chaque commande. Les nouveaux chemins correspondants ne sont pas automatiquement ajoutés aux restrictions du bac à sable de cette commande.

Codex spécifie aussi des options comme --unshare-ipc et --unshare-pid pour empêcher le bac à sable d’accéder à d’autres types de ressources de l’hôte. L’action de bubblewrap va donc au-delà de la visibilité des fichiers.

Avec bubblewrap, Codex transmet --unshare-net chaque fois que le réseau est désactivé ou que les connexions doivent passer par le proxy réseau, ce qui crée un nouvel espace de noms réseau pour le bac à sable. Nous utilisons ensuite seccomp-bpf pour appliquer des restrictions supplémentaires aux appels système réseau et aux familles de sockets accessibles à la commande.


Plus précisément, nous utilisons la
crate seccompiler⁠(ouverture dans une nouvelle fenêtre) pour compiler dynamiquement un programme BPF à partir des filtres souhaités⁠(ouverture dans une nouvelle fenêtre) et l’appliquer à un processus de lancement dans le bac à sable, afin que tout l’arbre des processus hérite des contraintes. Ainsi, bwrap n’exécute pas la commande de l’utilisateur, mais le lanceur codex-linux-sandbox avec ses propres arguments de configuration, suivis de la commande de l’utilisateur :

Bash

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

Pour appliquer les filtres seccomp sans privilèges élevés, le lanceur active l’indicateur no_new_privs de Linux⁠(ouverture dans une nouvelle fenêtre). Les processus enfants héritent de cet indicateur, qui les empêche d’obtenir des privilèges supplémentaires en exécutant un autre programme, tel qu’un exécutable setuid.

Les filtres seccomp dépendent de la configuration réseau. Lorsque l’accès au réseau est désactivé, nous bloquons plusieurs appels système liés au réseau, comme connect(2) et bind(2). En revanche, lorsque le proxy réseau est activé dans le bac à sable, nous autorisons les sockets IP pour que le point d’écoute TCP créé par codex-linux-sandbox soit joignable, mais bloquons par défaut la création de sockets de domaine Unix autonomes, qui pourraient permettre un accès involontaire aux ressources de l’hôte.

Se connecter au proxy réseau

Lorsque la configuration du bac à sable justifie l’utilisation du proxy réseau, le harnais Codex crée une instance du proxy réutilisable pour plusieurs appels à codex-linux-sandbox au sein d’un même fil Codex. Chaque bac à sable doit pouvoir joindre ce proxy partagé depuis son espace de noms réseau isolé. Codex fournit un point d’écoute TCP sur l’interface de bouclage de cet espace de noms et fait en sorte qu’un processus hors du bac à sable accepte ses connexions et les relaie vers le proxy.

Les diagrammes suivants illustrent cette configuration pour un point de terminaison du proxy ; le dernier montre une connexion qui le traverse. Avant de lancer bubblewrap, codex-linux-sandbox crée une paire de sockets Unix servant de canal de contrôle, puis se duplique en un processus enfant. L’enfant exécute run_host_bridge() et attend de recevoir le descripteur de fichier du point d’écoute sur ce canal :

Diagramme du harnais Codex lançant codex-linux-sandbox, qui crée un processus relais relié par un canal de contrôle sur socket Unix.

Dans cet exemple, le processus parent utilise exec pour remplacer son image de programme par bwrap. Celui-ci configure le bac à sable et y lance codex-linux-sandbox --apply-seccomp-then-exec, en transmettant le descripteur de fichier du canal de contrôle :

Diagramme montrant bwrap créant un espace de noms réseau pour le bac à sable et y lançant codex-linux-sandbox, avec un canal de contrôle sur socket Unix vers le processus relais situé hors du bac à sable.

Dans l’espace de noms réseau du bac à sable, le second appel à codex-linux-sandbox crée un point d’écoute TCP sur l’interface de bouclage et transmet son descripteur de fichier via le socket. Le point d’écoute reste associé à l’espace de noms réseau du bac à sable. Le processus enfant resté à l’extérieur peut ainsi accepter les connexions des programmes isolés, tout en ouvrant ses connexions en amont dans l’espace de noms réseau de l’hôte. Après le transfert, les deux processus ferment leurs descripteurs du canal de contrôle, et le processus dans le bac à sable ferme sa copie du point d’écoute.

Une fois le point d’écoute TCP prêt, le processus dans le bac à sable définit la valeur appropriée de HTTP_PROXY⁠(ouverture dans une nouvelle fenêtre) et des variables d’environnement associées pour qu’elles pointent vers ce point d’écoute. Il applique ensuite seccomp avant de créer un processus enfant et d’exécuter la commande de l’utilisateur :

Diagramme montrant un programme en bac à sable se connectant à un point d’écoute TCP sur l’interface de bouclage, avec un relais codex-linux-sandbox externe transmettant le trafic au proxy réseau de Codex.

Le processus hors du bac à sable maintient le point d’écoute ouvert. Pour chaque connexion acceptée, il ouvre une connexion au proxy configuré et relaie les données dans les deux sens.

Ce mécanisme supplémentaire donne à la commande son propre espace de noms réseau, avec une interface de bouclage distincte. Sur macOS, Seatbelt autorise la commande à se connecter directement aux ports spécifiés sur l’interface de bouclage de l’hôte. Sur Linux, la commande se connecte plutôt à un point d’écoute dans son espace de noms isolé, et un processus hors du bac à sable relaie ces connexions vers le proxy configuré. Le transfert du descripteur rend cette connexion possible sans exposer l’espace de noms réseau de l’hôte à la commande.

Windows

Plus tôt cette année, nous avons mis en œuvre et présenté nos travaux sur la mise en bac à sable sous Windows. Depuis, Microsoft a publié une bibliothèque appelée MXC ainsi que de nouvelles fonctionnalités d’isolation des processus dans le système d’exploitation Windows. Nous remplaçons actuellement notre bac à sable existant par un autre qui utilise la bibliothèque MXC.

Qu’est-ce que MXC ?

MXC (Microsoft eXecution Container) est un système d’exécution de code en bac à sable⁠(ouverture dans une nouvelle fenêtre) de Microsoft qui prend en charge plusieurs moteurs de confinement sur Windows, Linux et macOS. Codex prend en charge un bac à sable fondé sur MXC sur les appareils Windows compatibles, avec une isolation native des processus pour restreindre les commandes dans l’environnement existant de l’utilisateur.

Nous passons à MXC pour améliorer la sécurité et la facilité d’utilisation, tout en remédiant à plusieurs limites de notre bac à sable Windows actuel :

  • Nécessité de privilèges élevés ou administrateur pour configurer le bac à sable

  • Opérations de vérification et de définition des ACL coûteuses et lentes

  • État de configuration du bac à sable persistant sur la machine hôte, notamment :

    • ACL

    • Règles de pare-feu

    • Utilisateurs du bac à sable

    • Fichiers du plan de contrôle

MXC expose un schéma de configuration JSON⁠(ouverture dans une nouvelle fenêtre). Codex utilise le SDK MXC⁠(ouverture dans une nouvelle fenêtre) pour construire une requête d’exécution conforme à ce schéma, contenant la commande, le répertoire de travail, l’environnement et les autorisations. Ces autorisations couvrent l’accès au système de fichiers et au réseau, ainsi qu’aux ressources Windows comme le bureau et le presse-papiers.

Traduire une politique en appel MXC

Codex utilise des paramètres fixes pour plusieurs contrôles afin de concilier compatibilité et sécurité. Il autorise la lecture du registre et conserve les accès à Win32k et au bureau dont PowerShell a besoin au démarrage. L’accès au presse-papiers, l’injection d’entrées et les contrôles du bureau et des paramètres système sont désactivés. Enfin, MXC ne peut pas modifier les autorisations du système de fichiers de l’hôte comme solution de repli.

Codex traduit les règles du profil d’autorisations relatives au système de fichiers et au réseau en configuration MXC. Avec le profil dev présenté précédemment, et en supposant que :

  • C:\, D:\ et Z:\ sont les seuls lecteurs locaux de la machine.

  • La racine de l’espace de travail et le répertoire de travail sont C:\work\demo.

  • Le répertoire personnel de l’utilisateur est D:\Users\dev, donc ~/build-cache correspond à D:\Users\dev\build-cache.

  • Le motif glob de refus ne correspond qu’à C:\work\demo\config\dev.env et C:\work\demo\config\prod.env.

Les paramètres MXC correspondants comprendraient :

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
}

Accès à la racine des lecteurs

La politique de système de fichiers de MXC refuse l’accès par défaut. Codex ajoute donc des autorisations de lecture seule pour les racines des lecteurs locaux afin de fournir l’accès étendu en lecture permis par ce profil. Ces autorisations s’appliquent récursivement, sous réserve des autorisations système existantes de l’utilisateur.

Une particularité : les autorisations d’écriture à la racine d’un lecteur ne s’appliquent pas récursivement. Codex les étend donc aux enfants directs existants du lecteur.

Autorisations contradictoires

Les chemins plus précis prévalent sur les autorisations de leurs ancêtres : C:\work\demo peut donc être accessible en écriture sous C:\ en lecture seule, tandis que C:\work\demo\.git reste en lecture seule.

Lorsque différentes écritures de chemin ou des alias par lien symbolique ou jonction désignent le même chemin, MXC applique l’autorisation la plus stricte : le refus prévaut sur la lecture seule, qui prévaut sur la lecture-écriture.

Motifs glob de refus

MXC n’accepte que des chemins concrets à bloquer. Codex développe donc les motifs glob de refus en fichiers et répertoires correspondants avant le lancement. Les nouveaux chemins correspondant au motif glob ne sont pas automatiquement ajoutés pendant l’exécution de la commande.

Accès au réseau

Les règles de domaine comme *.openai.com sont appliquées par le proxy réseau commun de Codex décrit précédemment. Codex exécute ce proxy hors du bac à sable et transmet ses adresses à la commande via les mêmes variables d’environnement standard *_PROXY que celles mentionnées précédemment. MXC bloque les connexions externes directes tout en autorisant les connexions à l’interface de bouclage de l’hôte, y compris l’accès au proxy. Les autres services locaux restent accessibles.

Sur macOS, Linux et Windows, le harnais utilise la même API de bac à sable pour lancer des commandes sous un profil d’autorisations. Les implémentations propres à chaque plateforme assurent la configuration nécessaire à l’application de ces restrictions.

S’appuyer sur le bac à sable de Codex

L’écriture et l’exécution de code offrent aux agents un moyen flexible de résoudre des problèmes au-delà du développement logiciel. Le bac à sable de Codex leur permet d’utiliser cette capacité dans l’environnement existant de l’utilisateur, avec des limites explicites d’accès au système de fichiers et au réseau. C’est une primitive réutilisable au sein du harnais, et la commande codex sandbox la rend accessible aux outils que vous créez vous-même.

À mesure que les agents prennent en charge davantage de tâches, nous voulons rendre la mise en bac à sable pratique pour un plus grand nombre d’outils et d’environnements. Cela implique de simplifier la configuration des autorisations et de tirer parti des meilleures protections des systèmes d’exploitation à mesure qu’elles deviennent disponibles. Notre objectif est d’élargir les capacités des agents tout en laissant aux utilisateurs le contrôle de leurs accès.

Auteur

OpenAI

Remerciements

Un grand merci à David Wiesen, Charlie Weems, Viyat Bhalodia et Fotis Chantzis pour leur contribution à cet article.