Autorisations

Les profils d’autorisations permettent d’appliquer le principe du moindre privilège aux commandes locales que Codex exécute pour vous. Un profil est une politique nommée qui combine des règles d’accès au système de fichiers et au réseau. Les premières définissent ce que les commandes peuvent lire ou écrire, les secondes les destinations qu’elles peuvent atteindre.

Utilisez les profils pour accorder à Codex les accès nécessaires à la discussion en cours sans lui donner un accès étendu à votre machine ou à votre réseau. Par exemple, un profil en lecture seule permet à Codex d’examiner un projet sans le modifier. Un profil autorisant l’écriture peut limiter les modifications à certaines racines de l’espace de travail.

Les profils d’autorisations locaux sont pris en charge sur macOS, Linux, WSL et Windows en mode natif. Consultez la section Portée et application des règles pour connaître les particularités et les limites de chaque plateforme.

Pour les paramètres réseau actuels de Codex Cloud, consultez Connexion aux services. Pour Codex Cloud (ancienne version), consultez Accès à Internet.

Définir et sélectionner un profil

Codex propose trois profils d’autorisations intégrés :

• :read-only limite les commandes locales à la lecture seule.
• :workspace autorise l’écriture dans les racines actives de l’espace de travail et dans les répertoires temporaires du système.
• :danger-full-access lève les restrictions du bac à sable local. Utilisez-le uniquement si vous souhaitez accorder un accès aussi étendu.

Créez un profil nommé sous [permissions.<name>], puis attribuez à la clé de premier niveau default_permissions le nom de ce profil ou celui d’un des profils intégrés ci-dessus. Dans cet exemple, project-edit est le nom d’un profil défini par l’utilisateur et non une valeur intégrée.

Les administrateurs d’entreprise peuvent définir des profils et limiter ceux que les utilisateurs peuvent sélectionner au moyen du fichier géré requirements.toml. Dès que allowed_permission_profiles est présent, tous les profils absents de la liste sont interdits, y compris les profils intégrés omis et ceux ajoutés dans les futures versions de Codex. Consultez Contrôle des profils d’autorisations disponibles pour connaître la configuration gérée recommandée.

Les profils personnalisés utilisent deux paramètres complémentaires :

• [permissions.<name>.workspace_roots] ajoute les répertoires à considérer comme des racines de l’espace de travail pour ce profil.
• [permissions.<name>.filesystem.":workspace_roots"] définit les règles du système de fichiers que Codex applique dans chacune des racines effectives de l’espace de travail. Celles-ci comprennent les racines utilisées à l’exécution dans la session en cours et celles définies dans le profil ci-dessus.

Les profils suivent également le modèle habituel de configuration par couches. Une couche de priorité supérieure peut ajouter ou remplacer des entrées sous le même nom de profil sans avoir à redéfinir tout le profil.

Par exemple, la configuration de l’organisation et celle de l’utilisateur peuvent enrichir le même profil indépendamment l’une de l’autre :

# /etc/codex/config.toml
[permissions.server.workspace_roots]
"~/code/server" = true

# ~/.codex/config.toml
[permissions.server.workspace_roots]
"~/code/mobile-app" = true

Lorsque server est actif, le profil effectif comprend les deux racines de l’espace de travail.

default_permissions = "project-edit"

[features]
network_proxy = true

[permissions.project-edit.workspace_roots]
"~/code/app" = true
"~/code/shared-lib" = true

[permissions.project-edit.filesystem]
":minimal" = "read"

[permissions.project-edit.filesystem.":workspace_roots"]
"." = "write"
".devcontainer" = "read"
"**/*.env" = "deny"

[permissions.project-edit.network]
enabled = true

[permissions.project-edit.network.domains]
"api.openai.com" = "allow"
"objects.githubusercontent.com" = "allow"
"*.github.com" = "allow"
"tracking.example.com" = "deny"

Ce profil :

• Autorise la lecture des chemins strictement nécessaires à l’exécution des outils de développement courants.
• Applique les mêmes règles aux racines de l’espace de travail de la session en cours et à celles définies dans le profil.
• Maintient en lecture seule, sous chaque racine, les paramètres liés à l’IDE tels que .devcontainer/.
• Interdit l’accès aux fichiers d’environnement qui correspondent au motif glob.
• Autorise l’accès au réseau uniquement dans les limites des règles configurées pour les domaines.

Dans un profil actif, les interdictions qui ciblent des chemins précis restent en vigueur même si un chemin plus général est accessible en lecture ou en écriture. Par exemple, un profil peut autoriser l’écriture dans les racines de l’espace de travail tout en attribuant à un chemin .env correspondant au motif la valeur deny.

Étendre un profil

Utilisez extends lorsqu’un profil reprend l’essentiel d’un profil intégré ou d’un autre profil nommé. Privilégiez l’extension d’un profil intégré pour conserver ses protections de base. Par exemple, si vous étendez :workspace, les chemins .git, .agents, .codex et .aws de la racine de l’espace de travail restent en lecture seule, sauf si vous remplacez explicitement ces règles. Définissez le profil parent une seule fois, puis ajoutez ou remplacez uniquement les règles qui diffèrent.

default_permissions = "project-edit"

[features]
network_proxy = true

[permissions.project-edit]
description = "Project editing with OpenAI API access."
extends = ":workspace"

[permissions.project-edit.filesystem.":workspace_roots"]
"**/*.env" = "deny"

[permissions.project-edit.network]
enabled = true

[permissions.project-edit.network.domains]
"api.openai.com" = "allow"

Ce profil reprend les règles de :workspace, maintient l’interdiction d’accès aux fichiers .env correspondant au motif et autorise les requêtes vers api.openai.com. Un profil peut étendre :read-only, :workspace ou un autre profil nommé. Il ne peut pas étendre :danger-full-access. Codex refuse également les profils parents inconnus et les cycles d’héritage.

Spécification de la configuration

Autorisations du système de fichiers

Les entrées du système de fichiers prennent la valeur read, write ou deny :

Les entrées les plus spécifiques l’emportent sur les entrées plus générales. Si deux entrées ciblent le même chemin, deny l’emporte sur write, et write l’emporte sur read.

Cet ordre de priorité permet de définir d’abord une zone de travail étendue, puis d’en exclure les fichiers ou répertoires qui doivent rester inaccessibles en lecture :

[permissions.project-edit.filesystem]
":minimal" = "read"

[permissions.project-edit.filesystem.":workspace_roots"]
"." = "write"
".devcontainer" = "read"
"**/*.env" = "deny"

Dans cet exemple, la racine de l’espace de travail reste accessible en écriture, .devcontainer/ reste en lecture seule et les commandes exécutées dans le bac à sable ne peuvent pas accéder aux fichiers d’environnement correspondant au motif.

Un chemin plus spécifique peut également rétablir l’accès à une sous-arborescence au sein d’une arborescence interdite :

[permissions.project-edit.filesystem]
"~/Documents" = "deny"
"~/Documents/codex" = "write"

Formes de chemins prises en charge :

Sur Windows en mode natif, les chemins relatifs au répertoire personnel peuvent également utiliser des barres obliques inverses, comme dans ~\work.

Utilisez :root uniquement si le profil doit expressément accorder un accès étendu en lecture :

[permissions.audit.filesystem]
":root" = "read"

Utilisez des entrées imbriquées sous :workspace_roots pour définir l’accès à des sous-chemins relatifs à chaque racine de l’espace de travail :

[permissions.project-edit.filesystem.":workspace_roots"]
"." = "write"          # each workspace root
"docs" = "read"        # each workspace-root docs directory
"generated" = "deny"   # each workspace-root generated directory

Les sous-chemins imbriqués doivent rester dans leur racine de l’espace de travail. Codex refuse les chemins qui remontent vers un répertoire parent, tels que ../other-repo.

Interdire la lecture à l’aide de chemins exacts ou de motifs glob

Utilisez deny pour les fichiers ou les sous-arborescences que Codex ne doit pas lire, même si une règle plus générale du profil autorise l’accès au répertoire qui les contient. Les chemins exacts conviennent aux emplacements fixes tels que ~/.ssh. Les motifs glob sont plus adaptés lorsqu’un profil doit couvrir un ensemble de fichiers sensibles dont l’emplacement varie d’un dépôt à l’autre.

Lorsqu’un motif glob figure sous :workspace_roots, Codex l’interprète par rapport à chaque racine effective de l’espace de travail. Par exemple :

[permissions.project-edit.filesystem.":workspace_roots"]
"**/*.env" = "deny"

Cette règle interdit la lecture des fichiers .env correspondant au motif sous chacune des racines de l’espace de travail utilisées à l’exécution ou définies dans le profil. Utilisez-la pour conserver les droits d’écriture habituels dans l’espace de travail tout en empêchant la lecture des fichiers d’environnement, des secrets générés et des autres fichiers susceptibles de contenir des identifiants.

Sur Linux et WSL, ainsi que sur Windows en mode natif avec MXC ou elevated, Codex recense les fichiers correspondant aux motifs glob d’interdiction de lecture au démarrage de chaque processus dans le bac à sable. Les fichiers correspondants créés ensuite ne sont pas ajoutés à la liste d’interdiction de ce processus et restent lisibles si ses autres autorisations le permettent. Par exemple, un shell, un script, un outil de surveillance ou un serveur de développement qui reste actif peut lire un fichier .env correspondant au motif si ce fichier a été créé après le démarrage du processus.

Cette liste est valable pendant toute la durée de vie du processus dans le bac à sable. Sa portée ne s’étend pas à toute la session Codex. Lorsque vous démarrez un nouveau processus dans le bac à sable via Codex, les fichiers correspondants sont de nouveau recensés. Si vous continuez à utiliser un processus déjà actif, sa liste d’interdiction n’est pas actualisée. Ne comptez pas sur un motif glob pour empêcher ce processus de lire des fichiers créés après son démarrage. Consultez la section Compatibilité de MXC sur Windows pour connaître les limites propres à Windows.

Les motifs glob deny sont pris en charge pour interdire la lecture. Les motifs glob read ou write sont moins portables dans les bacs à sable sur Linux, WSL et Windows en mode natif. Privilégiez si possible les chemins exacts ou les règles portant sur une sous-arborescence, comme "docs/**" = "read".

Sur Linux, WSL et Windows en mode natif, un motif ** qui interdit la lecture sans limite de profondeur peut nécessiter une recherche à profondeur limitée avant le démarrage du bac à sable. Définissez glob_scan_max_depth lorsque vous utilisez un motif de profondeur illimitée tel que "**/*.env" = "deny" :

[permissions.project-edit.filesystem]
glob_scan_max_depth = 3

[permissions.project-edit.filesystem.":workspace_roots"]
"**/*.env" = "deny"

glob_scan_max_depth doit valoir au moins 1. Une valeur plus élevée augmente la profondeur de recherche avant le démarrage du bac à sable, ce qui peut allonger le démarrage sur Linux, WSL et Windows en mode natif. Si vous préférez éviter ce développement préalable à profondeur limitée, indiquez explicitement les profondeurs voulues avec des motifs tels que *.env, */*.env et */*/*.env.

Ajoutez au profil des racines d’espace de travail réutilisables si les mêmes règles doivent s’appliquer au-delà de la racine de la session en cours :

[permissions.project-edit.workspace_roots]
"~/code/app" = true
"~/code/shared-lib" = true

Lorsque ce profil est actif, Codex applique les règles :workspace_roots aux racines de l’espace de travail utilisées à l’exécution dans la session en cours et à chacune des racines activées dans le profil.

Sur Windows en mode natif, les chemins comportant une lettre de lecteur, tels que D:\work, et les chemins UNC, tels que \\server\share, sont pris en charge comme chemins absolus.

Autorisations réseau

L’accès au réseau et le filtrage réseau se configurent séparément. Définissez permissions.<name>.network.enabled = true pour autoriser les commandes à accéder au réseau et activez features.network_proxy pour faire appliquer les règles du profil relatives aux domaines :

[features]
network_proxy = true

[permissions.project-edit.network]
enabled = true

[permissions.project-edit.network.domains]
"example.com" = "allow"      # exact host
"*.example.com" = "allow"    # subdomains only
"**.example.com" = "allow"   # apex and subdomains
"ads.example.com" = "deny"   # deny wins over allow

Le comportement dépend des deux paramètres :

• Réseau désactivé : les commandes ne peuvent pas accéder au réseau, que le proxy soit activé ou non.
• Réseau activé, proxy désactivé : les commandes accèdent directement au réseau sans restriction. Les règles du profil d’autorisations relatives aux domaines ne sont pas appliquées.
• Réseau activé, proxy activé : les commandes passent par le proxy, qui applique les règles du profil relatives aux domaines. Si aucun domaine n’est autorisé, le proxy actif bloque les destinations externes.

L’ajout de [permissions.<name>.network.domains] ou la définition de permissions.<name>.network.enabled = true n’active pas features.network_proxy. Les administrateurs peuvent aussi activer le proxy à l’aide de [experimental_network] dans requirements.toml. Consultez la section Configuration gérée.

Lorsqu’il est actif, le proxy réseau du bac à sable écoute par défaut sur des adresses locales :

[permissions.project-edit.network]
enabled = true
proxy_url = "http://127.0.0.1:3128"
enable_socks5 = true
socks_url = "http://127.0.0.1:8081"
enable_socks5_udp = true

Conservez les paramètres d’écoute par défaut, sauf si vous intégrez le proxy à un environnement d’exécution particulier. Les clés réseau dangerously_* permettent de contourner certaines restrictions dans des environnements spécialisés. Évitez de les utiliser pour le développement local courant.

Réseaux locaux et privés

Lorsque le proxy réseau est actif, Codex protège par défaut les réseaux locaux et privés contre les attaques par réassociation DNS et les accès accidentels aux services locaux. Pour autoriser expressément une destination locale indiquée littéralement, ajoutez le nom d’hôte exact ou l’adresse IP exacte à la liste des hôtes autorisés :

[permissions.project-edit.network.domains]
"localhost" = "allow"
"127.0.0.1" = "allow"

Définissez allow_local_binding = true uniquement si le profil doit permettre d’atteindre des hôtes autorisés dont les noms se résolvent en adresses locales ou privées :

[permissions.project-edit.network]
enabled = true
allow_local_binding = true

[permissions.project-edit.network.domains]
"localhost" = "allow"

Sockets Unix

L’accès aux sockets Unix via le proxy permet à des outils tels que Docker de contourner certaines restrictions locales. Utilisez cette possibilité avec parcimonie :

[permissions.project-edit.network.unix_sockets]
"/var/run/docker.sock" = "allow"
"/tmp/old.sock" = "deny"

Utilisez deny pour interdire un chemin de socket, même si une entrée héritée l’autorise. Les chemins interdits sont exclus de la liste effective des sockets autorisés.

Lorsque les sockets Unix sont activés, limitez l’écoute du proxy aux adresses de bouclage.

Migrer depuis les anciens paramètres du bac à sable

Les profils d’autorisations remplacent l’ancienne combinaison de sandbox_mode et de sandbox_workspace_write lorsque vous souhaitez définir dans un même profil réutilisable les règles du système de fichiers et du réseau. Pour chaque session, choisissez un seul des deux systèmes.

Points de départ recommandés :

• Pour un workflow en lecture seule, utilisez le profil intégré :read-only ou définissez un profil personnalisé qui autorise la lecture uniquement là où elle est nécessaire.
• Pour modifier des fichiers dans l’espace de travail, utilisez le profil intégré :workspace ou définissez un profil personnalisé qui autorise l’écriture via :workspace_roots. N’y ajoutez que les chemins temporaires ou de cache dont le workflow a besoin.
• Pour exécuter des commandes localement sans restriction, utilisez :danger-full-access uniquement si vous souhaitez accorder l’accès local le plus étendu possible.

Les profils définissent les autorisations locales par défaut d’une session. Les exigences gérées par l’organisation peuvent imposer des restrictions supplémentaires que la configuration de l’utilisateur ne doit pas assouplir. Consultez la section Configuration gérée pour connaître les contraintes que l’administrateur impose au système de fichiers et au réseau.

Portée et application des règles

Accès à l’ordinateur local avec Work Cloud et politiques des environnements

Vérifiez la politique de chaque environnement dans lequel Work Cloud accède à l’ordinateur local :

• Exigences de l’entreprise : pour le mode Work avec accès local et pour les dots, lorsque la gestion des politiques est activée, les règles globales prises en charge régissent l’orchestrateur cloud partagé. Les exigences applicables à l’exécution locale régissent l’ordinateur connecté.
• Exécution dans le cloud : les conteneurs cloud du mode Work utilisent les politiques existantes de Work Cloud.
• Ordre de priorité des politiques locales : les exigences MDM et les anciennes exigences relatives aux appareils gérés priment sur Agent Security. Les exigences définies dans le fichier système de l’appareil ont une priorité inférieure à celle d’Agent Security.
• Priorité des politiques : une politique de priorité supérieure l’emporte même si une politique de priorité inférieure est plus spécifique. Au sein d’une même politique, les règles dérogatoires de l’environnement propres à un système d’exploitation priment sur celles qui s’appliquent à tous les systèmes d’exploitation. Les règles globales viennent en dernier.

Certaines exigences suivent des règles de fusion propres à chaque champ. Consultez la Configuration gérée et la Référence de configuration pour connaître les champs pris en charge et les limites à l’exécution. Ne présumez pas que Work Cloud prend en charge les profils d’autorisations Codex présentés ici.

Les profils d’autorisations définissent les limites dans lesquelles les commandes locales peuvent s’exécuter dans le bac à sable. Utilisez-les conjointement avec les politiques d’approbation et les contrôles distincts de la recherche web, des connecteurs, des serveurs MCP, du navigateur intégré, de la fonctionnalité Utilisation de l’ordinateur et de Codex Cloud.

Ce que contrôlent les profils

• Exécution de commandes locales : les profils d’autorisations régissent les commandes exécutées dans le bac à sable sur votre machine. Les connecteurs, les serveurs MCP, les interfaces de navigation ou d’utilisation de l’ordinateur, les paramètres des environnements Codex Cloud et les élévations de privilèges approuvées disposent de leurs propres contrôles.
• Écriture dans le système de fichiers : un profil autorisant l’écriture peut apporter des modifications persistantes. Traitez avec précaution les écritures dans les scripts, les étapes de compilation, les hooks des gestionnaires de paquets, les fichiers de démarrage du shell et les répertoires partagés. D’autres outils ou utilisateurs pourront ensuite exécuter ces fichiers hors du bac à sable d’origine.
• Destinations sortantes : les règles relatives aux domaines limitent les destinations du trafic des commandes exécutées dans le bac à sable uniquement lorsque le proxy réseau est actif. Elles ne garantissent pas la fiabilité d’une destination autorisée. Les règles d’autorisation qui utilisent des caractères génériques conservent une portée étendue.
• Services locaux : un proxy réseau actif bloque par défaut les destinations des réseaux locaux et privés. Ajouter localhost, des adresses IP privées ou des sockets Unix à la liste des autorisations, ou définir allow_local_binding = true, ouvre explicitement l’accès à des services locaux.

Ce qui échappe au contrôle du proxy réseau

Le proxy réseau filtre uniquement le trafic des commandes locales exécutées dans le bac à sable. Il n’applique pas la liste des domaines autorisés du profil aux fonctionnalités suivantes :

• Recherche web : l’outil de recherche hébergé dispose de ses propres paramètres d’accès. Utilisez web_search et, pour les clients gérés, allowed_web_search_modes pour le contrôler. tools.web_search.allowed_domains filtre les résultats de recherche sans agir sur l’accès des commandes au réseau.
• Applications et connecteurs : les outils qui s’appuient sur des connecteurs utilisent leurs propres connexions côté service, les autorisations de leur espace de travail et les paramètres de l’application ou de l’outil.
• Serveurs MCP : les serveurs MCP locaux et distants utilisent leur propre processus ou mécanisme de transport. Contrôlez-les à l’aide de la configuration mcp_servers et des listes gérées de serveurs autorisés.
• Navigateur et Utilisation de l’ordinateur : la navigation et les actions effectuées sur l’ordinateur disposent de leurs propres contrôles d’activation et d’approbation.
• Trafic des services Codex : les requêtes du client destinées aux modèles, à l’authentification et aux autres services utilisent les paramètres HTTP et de proxy système distincts du client.
• Codex Cloud : ces tâches utilisent les paramètres réseau de leur environnement. Codex Cloud (ancienne version) dispose de paramètres d’accès à Internet distincts.

Pour restreindre ces fonctionnalités, configurez chacune d’elles directement. La liste des destinations réseau autorisées pour les commandes ne constitue pas une politique réseau globale couvrant toutes les actions de Codex.

Application des restrictions selon la plateforme

• Sur macOS, Codex utilise les profils de bac à sable Seatbelt. Si le bac à sable de la plateforme ne peut pas faire respecter la politique sélectionnée, Codex refuse d’exécuter la commande au lieu de l’exécuter hors du bac à sable sans avertissement.
• Sur Linux et WSL, Codex utilise bubblewrap et seccomp pour appliquer les restrictions du système de fichiers. L’ancienne option Landlock ne peut pas isoler les sockets Unix d’app-server. Codex la refuse donc pour les politiques qui restreignent l’accès au système de fichiers. Désactivez features.use_legacy_landlock lors de la mise à niveau. Les hôtes qui bloquent les opérations requises par bubblewrap ne peuvent pas appliquer ces politiques.
• Sur Windows, MXC utilise l’isolation des processus pour appliquer les autorisations du système de fichiers et du réseau. Vérifiez la compatibilité de MXC avant de l’activer. L’ancien mode de repli elevated s’appuie sur des comptes dédiés au bac à sable aux privilèges réduits, des restrictions d’accès au système de fichiers et des règles de pare-feu. L’ancien mode de repli unelevated offre une isolation réseau plus faible et ne peut pas appliquer toutes les exceptions qui distinguent lecture et écriture. Codex refuse donc les politiques non prises en charge. Utilisez WSL si vous avez besoin du modèle de bac à sable de Linux.

Conseils d’utilisation

Choisissez le profil le plus restrictif qui permette de mener la tâche à bien, en particulier si vous autorisez l’écriture ou l’accès sortant au réseau. Adaptez la politique d’approbation, la gestion des secrets et les règles d’autorisation à ce niveau d’accès.

Profils courants

Lecture seule avec une liste de domaines réseau autorisés

default_permissions = "readonly-net"

[features]
network_proxy = true

[permissions.readonly-net.filesystem]
":minimal" = "read"

[permissions.readonly-net.filesystem.":workspace_roots"]
"." = "read"

[permissions.readonly-net.network]
enabled = true

[permissions.readonly-net.network.domains]
"api.openai.com" = "allow"

Accès aux fichiers limité à l’espace de travail

Ce profil d’autorisations permet à Codex d’écrire dans les répertoires de votre espace de travail tout en lui interdisant de lire le reste du système de fichiers, à quelques exceptions près définies par :minimal.

default_permissions = "workspace-only"

[permissions.workspace-only]
# By extending the :workspace profile, you get Codex's safeguards to ensure
# paths such as .git/, .agents/, .codex/, and .aws/ within a workspace root
# are read-only while the rest of the folder is writable.
extends = ":workspace"

[permissions.workspace-only.filesystem]
# By default, deny read access to all files on disk.
":root" = "deny"

# Though in practice, a software agent needs to be able to read folders that
# contain common tools, such as `/usr/bin`, to get work done, so grant access
# to a "minimal" set of files and folders, as determined by Codex.
":minimal" = "read"

# By extending the :workspace profile, :tmpdir and :slash_tmp are "write" by
# default, though you can deny access to them altogether, if desired.
":tmpdir" = "deny"
":slash_tmp" = "deny"

Écriture dans l’espace de travail sans accès au réseau

default_permissions = "project-edit"

[permissions.project-edit.filesystem]
":minimal" = "read"

[permissions.project-edit.filesystem.":workspace_roots"]
"." = "write"

[permissions.project-edit.network]
enabled = false

Écriture dans l’espace de travail avec accès au Web public

default_permissions = "workspace-net"

[features]
network_proxy = true

[permissions.workspace-net.filesystem]
":minimal" = "read"

[permissions.workspace-net.filesystem.":workspace_roots"]
"." = "write"

[permissions.workspace-net.network]
enabled = true

[permissions.workspace-net.network.domains]
"*" = "allow"

Utilisez la règle d’autorisation globale "*" uniquement si vous souhaitez autoriser l’accès au réseau public. Des règles d’interdiction permettent de restreindre la portée d’une liste d’autorisations étendue.