Règles

Utilisez des règles pour contrôler les commandes que Codex peut exécuter hors du bac à sable.

Créer un fichier de règles

Pour l’accès à l’ordinateur local avec Work Cloud, configurez les règles de commande gérées prises en charge à l’aide du champ TOML rules dans les paramètres de sécurité des agents. Ces règles s’appliquent aux exécuteurs locaux. Les conteneurs cloud de Work utilisent les politiques Work Cloud existantes.

Les instructions ci-dessous sur les fichiers .rules locaux s’appliquent à Codex. Ne supposez pas que la fonctionnalité d’accès à l’ordinateur local de Work Cloud lit ces fichiers. Consultez la documentation sur la configuration gérée et la référence de configuration pour connaître les exigences applicables aux configurations gérées de Work.

1. Créez un fichier .rules dans le dossier rules/ d’une couche de configuration active (par exemple, ~/.codex/rules/default.rules).

2. Ajoutez une règle. Dans cet exemple, Codex demande votre approbation avant d’autoriser l’exécution de gh pr view hors du bac à sable.

   # Prompt before running commands with the prefix `gh pr view` outside the sandbox.
   prefix_rule(
       # The prefix to match.
       pattern = ["gh", "pr", "view"],
   
       # The action to take when Codex requests to run a matching command.
       decision = "prompt",
   
       # Optional rationale for why this rule exists.
       justification = "Viewing PRs is allowed with approval",
   
       # `match` and `not_match` are optional "inline unit tests" where you can
       # provide examples of commands that should (or should not) match this rule.
       match = [
           "gh pr view 7888",
           "gh pr view --repo openai/codex",
           "gh pr view 7888 --json title,body,comments",
       ],
       not_match = [
           # Does not match because the `pattern` must be an exact prefix.
           "gh pr --repo openai/codex view 7888",
       ],
   )

3. Redémarrez Codex.

Au démarrage, Codex parcourt le dossier rules/ de chaque couche de configuration active, y compris aux emplacements de la configuration d’équipe et dans le dossier ~/.codex/rules/ de la couche utilisateur. Codex ne charge les règles propres au projet dans <repo>/.codex/rules/ que si la couche .codex/ du projet est approuvée.

Lorsque vous ajoutez une commande à la liste des commandes autorisées dans l’interface du terminal, Codex enregistre la règle dans le fichier ~/.codex/rules/default.rules de la couche utilisateur. Il peut ainsi exécuter la commande sans redemander votre approbation.

Lorsque les approbations intelligentes sont activées (réglage par défaut), Codex peut vous proposer une prefix_rule lorsqu’il demande des permissions supplémentaires. Examinez attentivement le préfixe proposé avant de l’accepter.

Les administrateurs peuvent également imposer des règles prefix_rule restrictives dans requirements.toml.

Comprendre les champs d’une règle

prefix_rule() accepte les champs suivants :

• pattern (obligatoire) : liste non vide qui définit le préfixe de commande à reconnaître. Chaque élément peut être :
  • Une chaîne littérale (par exemple, "pr").
  • Un ensemble de valeurs littérales (par exemple, ["view", "list"]) pour accepter plusieurs valeurs possibles à cette position dans la liste des arguments.
• decision (valeur par défaut : "allow") : action à effectuer lorsque la commande correspond à la règle. Si plusieurs règles correspondent, Codex applique la décision la plus restrictive (forbidden > prompt > allow).
  • allow : exécuter la commande hors du bac à sable sans demander d’approbation.
  • prompt : demander une approbation avant chaque invocation qui correspond à la règle.
  • forbidden : bloquer la demande sans solliciter d’approbation.
• justification (facultatif) : texte non vide qui explique la raison d’être de la règle. Codex peut l’afficher dans les demandes d’approbation ou les messages de refus. Si vous utilisez forbidden, indiquez une solution de remplacement dans la justification, le cas échéant (par exemple, "Use \rg` instead of `grep`.“`).
• match et not_match (valeur par défaut : []) : exemples que Codex vérifie lorsqu’il charge vos règles. Utilisez-les pour détecter les erreurs avant qu’une règle ne prenne effet.

Avant d’exécuter une commande, Codex compare sa liste d’arguments à pattern. En interne, Codex traite la commande comme une liste d’arguments semblable à celle que reçoit execvp(3).

Appels au shell et commandes composées

Certains outils regroupent plusieurs commandes shell en un seul appel, par exemple :

["bash", "-lc", "git add . && rm -rf /"]

Comme ce type de commande peut dissimuler plusieurs actions dans une seule chaîne, Codex traite de manière particulière bash -lc, bash -c et leurs équivalents pour zsh et sh.

Quand Codex peut décomposer le script en toute sécurité

Codex peut décomposer un script shell si celui-ci est une suite linéaire de commandes composée uniquement des éléments suivants :

• des mots simples (sans expansion de variables ni éléments tels que VAR=..., $FOO, *, etc.)
• des opérateurs sûrs pour relier les commandes (&&, ||, ; ou |)

Codex analyse alors le script avec tree-sitter et le décompose en commandes individuelles avant d’appliquer vos règles.

Codex traite le script ci-dessus comme deux commandes distinctes :

• ["git", "add", "."]
• ["rm", "-rf", "/"]

Codex évalue ensuite chaque commande au regard de vos règles et retient la décision la plus restrictive.

Même si vous autorisez pattern=["git", "add"], Codex n’autorise pas automatiquement git add . && rm -rf /, car il évalue rm -rf / séparément.

Cette vérification empêche de faire passer une commande dangereuse en l’associant à une commande sûre.

Quand Codex conserve le script entier

Un script peut utiliser des fonctionnalités plus avancées du shell, par exemple :

• les redirections (>, >>, <)
• les substitutions ($(...), ...)
• les variables d’environnement (FOO=bar)
• les motifs à caractères génériques (*, ?)
• les structures de contrôle (if, for, && avec des affectations, etc.)

Si le script utilise de telles fonctionnalités, Codex ne tente ni de l’interpréter ni de le décomposer.

Dans ces cas, Codex traite l’appel dans son ensemble sous la forme suivante :

["bash", "-lc", "<full script>"]

Il applique vos règles à cet unique appel.

Codex évalue ainsi chaque commande séparément lorsqu’il peut le faire en toute sécurité. Dans les autres cas, il évalue l’appel dans son ensemble par précaution.

Tester un fichier de règles

Utilisez codex execpolicy check pour vérifier comment vos règles s’appliquent à une commande :

codex execpolicy check --pretty \
  --rules ~/.codex/rules/default.rules \
  -- gh pr view 7888 --json title,body,comments

La commande renvoie au format JSON la décision la plus restrictive et toutes les règles correspondantes, avec la valeur de justification pour celles qui en ont une. Répétez l’option --rules pour combiner plusieurs fichiers et ajoutez --pretty pour mettre en forme la sortie.

Comprendre le langage des règles

Le format de fichier .rules utilise Starlark (voir la spécification du langage). Sa syntaxe ressemble à celle de Python. Le langage est conçu pour que le moteur de règles puisse exécuter le code en toute sécurité, sans effets de bord tels qu’une modification du système de fichiers.