OpenAI

18 novembre 2026

Ingénierie

Au cœur du bac à sable Codex

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

Par Michael Bolin, membre du personnel technique

Chez OpenAI, nous adoptons une approche de défense en profondeur⁠(s'ouvre 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⁠(s'ouvre dans une nouvelle fenêtre), pour offrir des protections supplémentaires. Comme l’une des opérations les plus courantes (et potentiellement risquées) de Codex consiste à exécuter des commandes sur votre ordinateur, nous avons créé le bac à sable Codex pour qu’il puisse travailler dans votre environnement existant, selon les limites d’accès au système de fichiers et au réseau que vous contrôlez.

Un ⁠(s'ouvre dans une nouvelle fenêtre)bac à sable⁠(s'ouvre dans une nouvelle fenêtre) limite ce à quoi un programme peut accéder pendant son exécution. Pour une tâche d’organisation de photos, vous pourriez configurer le bac à sable Codex pour permettre aux commandes de lire et de modifier les fichiers dans ~/Pictures, tout en bloquant l’accès au réseau pour empêcher les téléversements. Pour la révision de code, vous pourriez permettre l’accès à la documentation en ligne tout en gardant les fichiers sources en lecture seule. Les utilisateurs configurent le bac à sable Codex au moyen de ⁠(s'ouvre dans une nouvelle fenêtre)profils de permissions⁠(s'ouvre dans une nouvelle fenêtre), qui définissent les restrictions de système de fichiers et de réseau pour une session Codex.

Dans cet article, nous commencerons par les compromis derrière les paramètres par défaut du bac à sable 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 permissions à 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

Dans 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 de permissions intégré :workspace :

  • Permet 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 la permission à chaque changement, tout en empêchant les modifications directes de .codex/config.toml ou des hooks Git dans .git/hooks.

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

  • Désactive l’accès au réseau. Cela bloque les téléversements 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 demeurent possibles. Par exemple, l’agent pourrait injecter du code malveillant dans un paquet installé localement comme node_modules/prettier. Un tel changement 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 à l’extérieur du bac à sable Codex. C’est pourquoi nous adoptons une approche de défense en profondeur : le bac à sable limite ce à quoi les commandes peuvent accéder, tandis que l’entraînement et l’alignement aident le modèle à utiliser cet accès conformément à l’intention de l’utilisateur.

Pour des conseils sur l’adaptation des permissions du bac à sable et leur combinaison avec d’autres protections en entreprise, consultez le guide pratique de sécurité de Codex⁠(s'ouvre dans une nouvelle fenêtre).

Concevoir le bac à sable

Les machines virtuelles et les conteneurs⁠(s'ouvre dans une nouvelle fenêtre) sont deux mécanismes courants de confinement, mais nous adoptons une approche différente avec le bac à sable Codex. Plutôt que de déplacer les calculs dans un environnement distinct pour assurer l’isolation, Codex utilise les mécanismes de confinement de chaque plateforme pour restreindre les commandes exécutées dans l’environnement existant de l’utilisateur.

Pour beaucoup de développeurs, leur 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 flux de travail dépendent encore 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 de confiner Codex en l’exécutant dans Docker, il ne pourrait ni exécuter la chaîne de compilation iOS composée d’exécutables natifs Mac, ni lancer le simulateur iPhone pour exécuter le code. Un flux de travail basé sur Docker pourrait déléguer les compilations et les opérations du simulateur à l’hôte Mac, mais ces opérations s’exécuteraient à l’extérieur du bac à sable du conteneur et nécessiteraient leurs propres restrictions. Pour Codex, nous préférons miser sur la simplicité en investissant fortement dans le confinement propre à chaque système d’exploitation, afin qu’il puisse s’exécuter dans l’environnement le plus approprié à la tâche.

Le harnais expose ces mécanismes de confinement propres à chaque système d’exploitation au moyen d’une API commune à macOS, Windows et Linux. Cette API reçoit une commande et un profil de permissions. Si le profil de permissions permet un accès limité au réseau, l’appelant doit fournir un mandataire réseau pour appliquer 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 retourne un handle Child que le harnais peut utiliser pour attendre sa fin. Chaque processus enfant hérite des contraintes de confinement de son parent. Ces restrictions s’appliquent donc à tout l’arbre de processus lancé par la commande, même aux descendants qui survivent au processus d’origine.

Le schéma suivant montre comment ces éléments s’articulent, de la configuration à l’exécution d’une commande confinée. Les sections suivantes expliquent chaque étape.

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

Comment le harnais utilise le bac à sable

Comme expliqué dans Décortiquer 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 les commandes comme le ferait un utilisateur dans un shell interactif comme Bash. Nous examinerons ici l’outil shell ⁠(s'ouvre dans une nouvelle fenêtre)exec_command⁠(s'ouvre dans une nouvelle fenêtre) en une seule étape⁠(s'ouvre 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 façon dont l’appel à l’outil
exec_command serait traité par le harnais Codex sans confinement :

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 confiner la commande, le harnais remplace l’appel à subprocess.Popen() par spawn_command_under_sandbox(). Le harnais fournit le profil de permissions et, au besoin, le mandataire 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 permissions différentes pour une commande individuelle, mais c’est le harnais qui décide d’accorder ou non 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 élargi dans le bac à sable, tandis que require_escalated demande une exécution à l’extérieur de celui-ci. Le harnais évalue la demande selon les préférences de l’utilisateur avant d’exécuter la commande. (Par exemple, Codex peut solliciter l’utilisateur directement ou acheminer la demande vers la révision automatique⁠(s'ouvre dans une nouvelle fenêtre).) Si l’exécution est autorisée, Codex transmet les paramètres permission_profile et network_proxy appropriés à perform_exec_command_with_sandboxing(), avec les arguments de commande de l’appel ExecCommandToolCall d’origine.

L’outil shell est le principal utilisateur de spawn_command_under_sandbox(), et le harnais réutilise aussi son infrastructure de confinement pour des opérations comme la lecture et la modification de fichiers locaux. Cette réutilisation va au-delà du harnais : la commande codex sandbox vous permet d’intégrer l’exécution de commandes confinées à vos propres outils, comme nous le verrons plus loin. Voyons maintenant comment les profils de permissions sont définis.

Configurer le bac à sable

Un profil de permissions nommé vous permet de réutiliser les mêmes restrictions de système de fichiers et de réseau dans plusieurs projets. Vous pouvez définir vos propres profils sous [permissions] dans config.toml. Par exemple, ce qui suit définit un profil nommé dev qui étend⁠(s'ouvre 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 l’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), un accès en lecture et en écriture (write), ou bloquer entièrement l’accès (deny).

La table :workspace_roots vous permet de définir des règles pour les chemins relatifs aux racines de l’espace de travail d’un projet. Par défaut, l’interface en ligne de commande de Codex utilise son répertoire de travail comme seule 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. Ainsi, l’entrée .vscode dans dev rend le répertoire .vscode accessible en lecture seule sous chaque racine.

En plus de 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"

Permissions 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 complet et direct au réseau (par défaut pour le profil :danger-full-access)

  • Limiter l’accès au réseau à un mandataire, qui décide quoi laisser passer selon le profil de permissions


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

Pour limiter dev à un ensemble de domaines, activez le mandataire 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 prennent en charge les noms exacts et les motifs avec caractères génériques; les règles de refus explicites ont priorité 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 Mandataire réseau ci-dessous.

Superposer la configuration et imposer des limites

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

Comme décrit dans Priorité de configuration,⁠(s'ouvre dans une nouvelle fenêtre) Codex fusionne les paramètres de plusieurs fichiers config.toml. Les tables sont fusionnées récursivement, la source de priorité supérieure l’emportant en cas de conflit entre les valeurs. Les tableaux sont remplacés en entier.

C’est pourquoi les profils de permissions 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 changements apportés à 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⁠(s'ouvre dans une nouvelle fenêtre) au moyen de 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 nuage. Un cas d’utilisation courant consiste à spécifier allowed_permission_profiles pour limiter l’ensemble des profils de permissions qu’un utilisateur d’entreprise peut sélectionner. Par exemple, un administrateur pourrait spécifier ces exigences infonuagiques :

TOML

1
default_permissions = ":read-only"
2

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

Les exigences infonuagiques auraient priorité sur le fichier d’exigences système /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. Laisser :workspace non spécifié permet à une autre couche d’exigences de fournir cette entrée. Les profils dont les entrées sont false ou absentes de la table fusionnée finale ne sont pas disponibles.

Cette séparation permet aux organisations d’imposer des limites, tandis que les utilisateurs adaptent leur configuration à l’intérieur de ces limites. Les profils de permissions obtenus peuvent être utilisés par le harnais ou appliqués directement à une commande, comme nous le verrons ensuite.

Utiliser la commande codex sandbox

L’interface en ligne de commande de Codex fournit une commande sandbox pour faciliter l’exécution d’une commande quelconque sous un profil de permissions 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. Si .vscode existe déjà, le profil dev défini plus haut devrait bloquer cette écriture, car ce répertoire est en lecture seule (codex sandbox traite cwd comme une racine d’espace de travail par défaut) :

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, l’opération échoue avec :

Texte brut

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

La commande codex sandbox rend le mécanisme de confinement de Codex disponible indépendamment d’une session d’agent. Vous pouvez utiliser le même langage de configuration et la même application des restrictions propre à chaque plateforme pour restreindre les commandes lancées par vos outils.

Exemple : confiner un serveur MCP

Pour un serveur MCP stdio configuré dans config.toml, le harnais Codex ne tente pas de confiner la commande utilisée pour démarrer le serveur. Codex ne peut pas déduire de façon fiable les fichiers ou services réseau dont ce serveur a besoin. L’application d’un profil de bac à sable par défaut pourrait donc empêcher une configuration autrement valide de fonctionner.

Par exemple, la façon standard de configurer le serveur MCP @modelcontextprotocol/server-memory⁠(s'ouvre dans une nouvelle fenêtre) pour l’utiliser avec Codex est la suivante :

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 sans confinement, elle peut écrire des fichiers et effectuer des requêtes réseau avec les mêmes permissions que l’utilisateur qui exécute Codex, ce qui est trop permissif. Pour la restreindre, nous pouvons définir un profil de permissions nommé memory-mcp, puis encapsuler la commande npx d’origine avec codex sandbox --permission-profile memory-mcp afin de limiter les emplacements où le serveur peut écrire et d’empêcher son 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 l’écriture limitée au cache npm et au répertoire de données du serveur.

Implémentation du bac à sable Codex

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

Mandataire réseau

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

Dans le dépôt Codex, le mandataire réseau est implémenté dans le crate codex-network-proxy⁠(s'ouvre dans une nouvelle fenêtre), que le harnais utilise comme bibliothèque, mais qui peut aussi être compilé en outil en ligne de commande autonome⁠(s'ouvre dans une nouvelle fenêtre). Lorsqu’il est activé, codex-network-proxy démarre par défaut un mandataire HTTP et un mandataire SOCKS5. Les adresses de ces mandataires sont communiquées au processus créé par le bac à sable au moyen de variables d’environnement. En plus des variables d’environnement standard comme HTTP_PROXY, HTTPS_PROXY et ALL_PROXY, plusieurs variables d’environnement propres à certaines applications⁠(s'ouvre dans une nouvelle fenêtre) bien connues (comme PIP_PROXY) sont aussi injectées. Il faut reconnaître que tous les programmes ne tiennent pas compte de ces variables d’environnement. Si un programme tente une connexion directe à un hôte externe, les restrictions de confinement du système d’exploitation la bloquent, comme décrit dans les sections propres à chaque plateforme ci-dessous.

Le mandataire réseau est chargé d’appliquer les restrictions réseau définies dans un profil de permissions. Par exemple, le profil dev présenté plus haut permet 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 mandataire peut la suspendre pendant qu’il délègue son approbation au harnais. Comme dans l’exemple de commande shell, Codex peut solliciter l’utilisateur directement ou acheminer la requête vers la révision automatique⁠(s'ouvre dans une nouvelle fenêtre). À la réception d’une décision, le mandataire laisse la requête se poursuivre ou la rejette avec une réponse d’erreur.

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

macOS

Sur macOS, Codex utilise Seatbelt⁠(s'ouvre dans une nouvelle fenêtre), le mécanisme de confinement d’Apple appliqué par le noyau. Les politiques Seatbelt sont écrites en Sandbox Profile Language (SBPL), un langage basé sur Scheme pour exprimer les restrictions du bac à sable. Codex appelle Seatbelt au moyen de la commande /usr/bin/sandbox-exec de macOS. Comme codex sandbox, elle reçoit 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 de SBPL contenant des 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 mandataire 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 demeurent donc bloquées, sauf si elles sont explicitement autorisées.

Enfin, le SBPL peut contenir des espaces réservés 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)))

qui sont remplis par les options -Dkey=value transmises à sandbox-exec.

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

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

Linux

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

Bash

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

Lorsque l’isolation du système de fichiers ou le routage par mandataire est requis, 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 deuxième 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 de système de fichiers du profil de permissions. Comme cet outil est essentiel à l’implémentation du bac à sable, Codex intègre sa propre copie de bwrap au cas où l’utilisateur n’en aurait pas installé, mais il privilégie une installation compatible de ⁠(s'ouvre dans une nouvelle fenêtre)bwrap⁠(s'ouvre dans une nouvelle fenêtre) trouvée dans PATH, lorsqu’elle est disponible. En pratique, certaines distributions Linux désactivent par défaut l’accès aux espaces de noms utilisateur⁠(s'ouvre dans une nouvelle fenêtre), mais accordent une exception au bwrap du système.

Tout comme sandbox-exec, bwrap reçoit une configuration de bac à sable suivie d’une commande à y exécuter. Plutôt qu’un langage de configuration personnalisé 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 vers /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 ajoutés automatiquement 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 sur l’hôte. L’effet de bubblewrap ne se limite donc pas à 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 mandataire 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 disponibles pour la commande.


Plus précisément, nous utilisons le
crate seccompiler⁠(s'ouvre dans une nouvelle fenêtre) pour compiler dynamiquement un programme BPF selon les filtres souhaités⁠(s'ouvre dans une nouvelle fenêtre) et l’appliquer à un processus lanceur dans le bac à sable, afin que tout l’arbre de processus hérite des contraintes. Ainsi, bwrap n’exécute pas la commande de l’utilisateur, mais plutôt 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⁠(s'ouvre dans une nouvelle fenêtre). Les processus enfants héritent de cet indicateur, qui les empêche d’obtenir des privilèges supplémentaires lorsqu’ils exécutent un autre programme, comme 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). Lorsque le mandataire réseau est activé dans le bac à sable, nous permettons toutefois les sockets IP pour que l’écouteur 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.

Connexion au mandataire réseau

Lorsque la configuration du bac à sable justifie l’utilisation du mandataire réseau, le harnais Codex crée une instance du mandataire réutilisable entre plusieurs appels de codex-linux-sandbox dans le même fil Codex. Chaque bac à sable doit pouvoir joindre ce mandataire partagé depuis son espace de noms réseau isolé. Codex fournit un écouteur TCP de bouclage dans cet espace de noms et fait en sorte qu’un processus à l’extérieur du bac à sable accepte ses connexions et les relaie au mandataire.

Les schémas suivants illustrent cette configuration pour un point de terminaison du mandataire; 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 processus enfant. Le processus enfant exécute run_host_bridge() et attend de recevoir le descripteur de fichier de l’écouteur sur ce canal :

Schéma du harnais Codex lançant codex-linux-sandbox, qui crée un processus relais connecté par un canal de contrôle utilisant un socket Unix.

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

Schéma montrant bwrap créant un espace de noms réseau de bac à sable et y lançant codex-linux-sandbox, avec un canal de contrôle par socket Unix vers le processus relais à l’extérieur du bac à sable.

Dans l’espace de noms réseau du bac à sable, le deuxième appel de codex-linux-sandbox crée un écouteur TCP de bouclage et transmet son descripteur de fichier par le socket. L’écouteur reste associé à l’espace de noms réseau du bac à sable, ce qui permet au processus enfant resté à l’extérieur d’accepter les connexions des programmes confiné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 de l’écouteur.

Une fois l’écouteur TCP prêt, le processus dans le bac à sable définit la valeur appropriée pour HTTP_PROXY⁠(s'ouvre dans une nouvelle fenêtre) et les variables d’environnement connexes afin qu’elles pointent vers cet écouteur. Il applique ensuite seccomp avant de créer un processus enfant et d’exécuter la commande de l’utilisateur :

Schéma montrant un programme confiné se connectant à un écouteur TCP de bouclage, avec un relais codex-linux-sandbox externe transmettant le trafic au mandataire réseau de Codex.

Le processus à l’extérieur du bac à sable garde l’écouteur ouvert. Pour chaque connexion acceptée, il ouvre une connexion au mandataire 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, y compris une interface de bouclage distincte. Sur macOS, Seatbelt permet à la commande de 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 écouteur dans son espace de noms isolé, et un processus à l’extérieur du bac à sable relaie ces connexions au mandataire 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 le confinement sur Windows et publié un article sur nos efforts en ce sens. Depuis, Microsoft a publié une bibliothèque nommé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⁠(s'ouvre 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 basé sur MXC sur les appareils Windows compatibles, en utilisant l’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 convivialité tout en corrigeant plusieurs limites de notre bac à sable Windows actuel :

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

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

  • É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⁠(s'ouvre dans une nouvelle fenêtre). Codex utilise le SDK MXC⁠(s'ouvre dans une nouvelle fenêtre) pour construire une requête d’exécution conforme à ce schéma et contenant la commande, le répertoire de travail, l’environnement et les permissions. Ces permissions 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.

Conversion de la politique en appel MXC

Codex utilise des paramètres fixes pour plusieurs contrôles afin d’équilibrer compatibilité et sécurité. Il permet 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 se rabattre sur la modification des permissions du système de fichiers de l’hôte.

Codex convertit les règles de système de fichiers et de réseau du profil de permissions en configuration MXC. Avec le profil dev présenté plus haut, 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 droits de lecture seule pour les racines des lecteurs locaux afin de fournir l’accès étendu en lecture permis par ce profil. Ces droits s’appliquent récursivement, sous réserve des permissions existantes de l’utilisateur dans le système d’exploitation.

Une particularité : les droits d’écriture à la racine des lecteurs ne s’appliquent pas récursivement. Codex les étend donc aux enfants immédiats existants du lecteur.

Droits contradictoires

Les chemins plus précis prévalent sur les droits des ancêtres. Ainsi, C:\work\demo peut être accessible en écriture sous un C:\ en lecture seule, tandis que C:\work\demo\.git demeure en lecture seule.

Lorsque différentes graphies de chemin ou des alias de liens symboliques ou de jonctions désignent le même chemin, MXC applique la permission la plus stricte : le refus prime sur la lecture seule, qui prime sur la lecture-écriture.

Motifs glob de refus

MXC n’accepte que des chemins de refus concrets. 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 ajoutés automatiquement 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 mandataire réseau partagé de Codex décrit plus haut. Codex exécute ce mandataire à l’extérieur du bac à sable et transmet ses adresses à la commande au moyen des mêmes variables d’environnement standard *_PROXY mentionnées précédemment. MXC bloque les connexions externes directes tout en permettant les connexions de bouclage vers l’hôte, y compris l’accès au mandataire. Les autres services locaux demeurent joignables.

Sur macOS, Linux et Windows, le harnais utilise la même API de bac à sable pour lancer les commandes sous un profil de permissions. Les implémentations propres à chaque plateforme gèrent la configuration nécessaire pour appliquer ces restrictions.

Tirer parti du bac à sable Codex

L’écriture et l’exécution de code offrent aux agents un moyen souple de résoudre des problèmes au-delà du développement logiciel. Le bac à sable 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. Il s’agit d’une primitive réutilisable dans le harnais, et la commande codex sandbox la rend accessible aux outils que vous créez vous-même.

À mesure que les agents accomplissent davantage de tâches, nous voulons rendre le confinement pratique pour un plus grand nombre d’outils et d’environnements. Cela signifie faciliter la configuration des permissions et tirer parti de meilleures protections du système d’exploitation à mesure qu’elles deviennent disponibles. Notre objectif est d’élargir les capacités des agents tout en laissant aux gens le contrôle de ce à quoi les agents peuvent accéder.

Auteur

OpenAI

Remerciements

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