Scrubber et coffre-fort de secrets

zn-gate empêche les valeurs secrètes de se retrouver dans ce que votre agent de code envoie à son modèle. L'agent travaille avec des marqueurs tels que __ZN_GITHUB_TOKEN__ ; les valeurs réelles restent dans un coffre-fort chiffré sur votre machine et ne sont remplies que là où vous l'avez autorisé. La détection, le remplacement et le coffre-fort sont 100 % locaux : aucun service cloud, le nôtre compris, n'intervient.

Disponible dans zn-gate 1.5.0 et versions ultérieures (npm) ; sous Windows, utilisez la version 1.5.1 ou ultérieure (GHSA-rf3f-ppm5-3xrx). Agents pris en charge : Claude Code, Codex CLI, Cursor (IDE) et OpenCode. Ce que chaque agent permet de modifier via les hooks varie : voir compat.md et les limites décrites dans threat-model.md.

Ce qu'il fait

• Nettoie ce que voit le modèle. Les lectures de fichiers, les sorties de commandes, les recherches, les résultats des outils MCP et les prompts collés passent par le scrubber avant d'atteindre le modèle. Les valeurs connues (provenant du coffre-fort et de vos fichiers .env), environ 30 formats de secrets (clés cloud, jetons, clés privées, mots de passe dans les chaînes de connexion) et les données personnelles (numéros de carte, IBAN, DNI/NIE et numéros de sécurité sociale américains avec validation de somme de contrôle ; adresses e-mail, numéros de téléphone et adresses IPv4) deviennent des marqueurs stables. Une même valeur reçoit toujours le même marqueur, de sorte que le modèle peut encore raisonner à son sujet et que la ligne conserve sa forme : DATABASE_URL=postgres://app:__ZN_DATABASE_URL_PASSWORD__@db:5432/app. Dans Cursor, seules les sorties MCP peuvent être réécrites : les sorties du shell et des fichiers ne sont pas nettoyées à ce niveau.
• Bloque la lecture des identifiants bruts. Les fichiers .env contenant de vraies valeurs, les fichiers d'identifiants tels que ~/.aws/credentials ou ~/.ssh/id_*, ainsi que le dossier ~/.zn de zn : les hooks empêchent les outils de l'agent de les lire (un garde-fou, pas un bac à sable).
• Conserve les valeurs dans un coffre-fort chiffré. Le coffre-fort est chiffré avec age ; sa clé est stockée dans le trousseau de votre système d'exploitation (ou protégée par une phrase de passe). Il ne quitte jamais votre machine et n'est jamais synchronisé. Un journal d'audit local enregistre quel secret a été utilisé à quel endroit, sans jamais enregistrer les valeurs.
• Ne remplit les valeurs que là où vous l'avez autorisé. Une commande autorisée reçoit la valeur via zn run, et sa sortie est masquée. Les API HTTP sont appelées via le serveur MCP secrets, qui n'envoie la valeur qu'aux hôtes autorisés et renvoie la réponse avec les secrets remplacés par des marqueurs. Aucun outil ne renvoie une valeur à l'agent.
• Vous demande, pas à l'agent. La première utilisation d'un secret par un programme, ainsi que toute modification élargissant la politique d'un secret, doivent être confirmées dans une boîte de dialogue système ou dans le terminal propre au coffre-fort. L'agent ne peut pas répondre à ces demandes.

Démarrage

npm install -g zn-gate
zn unlock                         # creates the vault the first time
zn env shadow .env                # moves the values into the vault; .env keeps markers
zn hooks install claude-code      # or: codex, cursor, opencode

Pour permettre à une commande d'utiliser un secret, autorisez ce programme :

zn secret allow DATABASE_URL_PASSWORD --command psql

Autorisez un programme précis : node, python, npm, make et les autres interpréteurs exécutent tout code qu'on leur donne ; en en autorisant un, vous permettez à chaque script qu'il lance de lire le secret, et zn vous en avertit lorsque vous le faites.

Pour ajouter un seul secret, saisissez-le dans une invite masquée, jamais en argument : zn secret set GITHUB_TOKEN --host api.github.com.

Le guide complet se trouve dans le guide des secrets.

Commandes utiles

Si le coffre-fort est verrouillé, les hooks continuent de masquer ce qu'ils reconnaissent, avec des marqueurs qui ne peuvent pas être restaurés (__ZN_REDACTED_AWS_KEY__), et vous rappellent d'exécuter zn unlock.

Limites

• Le scrubber détecte les valeurs connues et les formats reconnaissables. Un secret sans format connu qui ne figure ni dans le coffre-fort ni dans un fichier .env peut passer à travers : placez vos secrets dans le coffre-fort.
• Approuver un fichier batch (.cmd, .bat) sous Windows approuve ce fichier, pas les programmes qu'il lance par leur nom. Privilégiez secrets_http_request pour les API HTTP, ou approuvez le programme lui-même.
• Tant que le coffre-fort est déverrouillé, tout programme s'exécutant sous votre utilisateur système, y compris une commande lancée par l'agent, peut lui demander un secret par son nom. Verrouillez-le avec zn lock lorsque vous n'en avez pas besoin.
• Un programme que vous avez autorisé détient la valeur et peut l'envoyer n'importe où : autorisez des programmes précis, utilisez des jetons à portée restreinte et le bac à sable de votre agent.
• Certains agents conservent leurs propres copies locales (le journal de session de Codex conserve la sortie d'origine).
• Le paquet Python (PyPI) propose le masquage des secrets dans ses fonctions de bibliothèque (redact_secrets, sanitize_tool_result, guard), mais ni le coffre-fort, ni les hooks, ni zn run, ni le nettoyage des données personnelles.

Pour le masquage uniquement dans les sorties et arguments des outils MCP, voir Masquage des secrets.

Open source

MIT, comme le reste de zn-gate : github.com/usezn/zn. Les modifications sont listées dans le CHANGELOG.