Garder les clés d'API hors de Codex CLI

Ce que le modèle de Codex CLI peut voir, ce que les hooks de zn-gate vérifient dans Codex avant et après chaque étape et sur vos prompts, ce qu'ils ne peuvent pas faire, comment les configurer et un court test avec de fausses valeurs.

Voir le .md

Codex CLI envoie à son modèle tout ce qui entre dans la conversation : les prompts que vous écrivez, les fichiers que l'agent lit, la sortie des commandes shell et les résultats des outils MCP. Une clé d'API présente à l'un de ces endroits peut atteindre le modèle. zn-gate installe des hooks dans Codex qui vérifient ces points. Cette page explique ce que fait chaque hook d'après la documentation de zn-gate, ce qu'il ne peut pas faire, et vous propose un test à faire vous-même.

Par où une clé peut atteindre le modèle

Les hooks de zn-gate pour Codex surveillent quatre points d'une session :

  • Un prompt que vous écrivez. Un secret collé dedans peut être bloqué avant l'envoi.
  • Une commande shell ou un patch (apply_patch). Les lectures de fichiers .env contenant des valeurs et de fichiers d'identifiants peuvent être bloquées.
  • La sortie d'un outil. Elle peut être nettoyée avant que le modèle la voie.

Le journal de session propre à Codex conserve la sortie d'origine, quoi que fasse zn-gate sur ce que voit le modèle.

Ce que zn-gate vérifie dans Codex

zn hooks install codex écrit le hooks.json de Codex. Ce tableau suit le fichier compat.md du dépôt de zn-gate, qui liste chaque événement de hook de Codex et indique s'il a été exécuté sur un vrai Codex.

Événement de hook Ce que fait zn-gate
PreToolUse Vérifie les commandes shell et les patchs (Bash, apply_patch) avant leur exécution, et refuse l'appel avec un motif lorsqu'il trouve un secret, un fichier d'identifiants ou ~/.zn. Il ne vérifie pas les appels d'outils MCP. Vérifié sur Codex CLI 0.163.0.
PostToolUse Nettoie la sortie de l'outil : le résultat est remplacé par son texte nettoyé. Vérifié sur Codex CLI 0.163.0.

Un troisième événement, UserPromptSubmit, bloque un secret collé dans un prompt (vérifié sur Codex CLI 0.163.0).

Dans PreToolUse, zn-gate ne répond pas allow, donc votre propre politique d'approbation de Codex continue de s'appliquer.

Ce que zn-gate ne couvre pas dans Codex

  • Codex décrit ses hooks comme "a guardrail, not an enforcement boundary" (un garde-fou, pas une limite imposée). Si le hook de zn ne peut pas s'exécuter, Codex le signale comme échoué et l'appel ou le prompt continue.
  • Le nettoyage est avec perte. Codex n'a aucun champ qui réécrive le résultat d'un outil : le résultat est remplacé par le texte nettoyé de zn-gate et le modèle reçoit du texte au lieu du résultat structuré.
  • Le journal de session propre à Codex conserve la sortie d'origine.
  • Un secret sans format connu qui n'est ni dans le coffre ni dans un fichier .env peut passer le nettoyage.
  • Un serveur défini sur la ligne de commande de Codex avec -c mcp_servers.secrets..., ou dans un profil, n'est pas visible pour le hook.
  • La vérification PreToolUse de zn-gate couvre les commandes shell et les patchs, pas les appels d'outils MCP, et zn-gate n'utilise pas les autres événements de hook de Codex.
  • Sous Windows, la commande du hook a été lancée à la main depuis PowerShell et depuis l'invite de commandes, pas dans les tests automatisés.

Mettre en place

Il vous faut Node.js 18 ou une version ultérieure :

npm install -g zn-gate
zn hooks install codex

Ouvrez Codex et examinez les hooks nouveaux ou modifiés avec /hooks. Codex n'exécute les nouveaux hooks qu'une fois que vous leur faites confiance à cet endroit. Lancez ensuite zn-gate check dans un terminal. Il doit afficher OK pour Codex CLI (ce que signifie la sortie). Les étapes complètes figurent sur la page d'installation pour Codex CLI.

Pour sortir complètement les vraies valeurs de votre .env, placez-les dans le coffre de zn-gate. Votre .env contient alors des marqueurs comme __ZN_STRIPE_KEY__ :

zn unlock
zn env shadow .env

Plus de détails dans Scrubber. Pour annuler les hooks : zn hooks uninstall codex.

Testez sur votre propre machine

Ce test utilise de fausses valeurs. Certaines parties suivent ce que la documentation dit qu'il devrait se passer et nous ne les avons pas exécutées de bout en bout dans Codex : vérifiez donc chaque étape vous-même.

  1. Dans un nouveau dossier vide, créez un fichier .env avec de fausses valeurs uniquement :

    EXAMPLE_API_KEY=sk-test-EXAMPLE-not-a-real-key
EXAMPLE_URL=https://example.com

  2. Installez les hooks (zn hooks install codex), ouvrez Codex dans ce dossier, faites confiance aux hooks avec /hooks et lancez zn-gate check dans un autre terminal.

  3. Demandez à Codex : "Run cat .env and tell me what it prints." D'après compat.md, le hook PreToolUse de zn-gate a bloqué cat .env sur Codex CLI 0.163.0, et vous devriez voir un message du hook à la place des valeurs.

  4. Collez dans le prompt la clé d'exemple de la documentation AWS AKIAIOSFODNN7EXAMPLE. Si zn-gate reconnaît le format, le prompt devrait être bloqué. S'il ne l'est pas, le format n'est peut-être pas de ceux que zn-gate détecte.

  5. Facultatif : lancez zn unlock et zn env shadow .env, ouvrez le fichier et vérifiez qu'il contient des marqueurs. Demandez à Codex de le relire et comparez.

  6. Supprimez le dossier d'essai une fois terminé. Pour retirer les hooks : zn hooks uninstall codex.

Seuls vos propres résultats comptent ici. Si une étape se comporte autrement que ce que dit cette page, écrivez-nous en indiquant votre version de Codex CLI.

Questions fréquentes

Le modèle de Codex peut-il voir mes clés d'API ? Tout ce que l'agent lit, exécute ou reçoit peut atteindre le modèle : fichiers, sortie du shell, résultats MCP et prompts. Les hooks de zn-gate vérifient ces points, avec les limites indiquées plus haut.

zn-gate empêche-t-il Codex de lire .env ? Ses hooks bloquent les lectures de fichiers .env contenant des valeurs dans les commandes shell et les patchs. Codex appelle ses hooks un garde-fou, pas une limite imposée.

Pourquoi la sortie nettoyée est-elle du texte brut ? Codex n'a aucun champ qui réécrive le résultat d'un outil : zn-gate remplace donc tout le résultat par son texte nettoyé.

Comment annuler ? zn hooks uninstall codex.

Pages liées

Sources