Gardez les secrets hors de votre agent de code (5 minutes)

zn-gate garde les valeurs secrètes hors de ce que votre agent de code envoie à son modèle. L'agent travaille avec des marqueurs comme __ZN_GITHUB_TOKEN__ ; les vraies valeurs restent dans un coffre chiffré sur votre machine et ne sont insérées que là où vous l'avez autorisé. Tout s'exécute en local et aucun compte n'est nécessaire.

Cela fonctionne avec Claude Code, Codex CLI, Cursor (IDE) et OpenCode. Ce que chaque agent peut et ne peut pas faire est décrit dans Agents pris en charge ; les limites, dans le modèle de menaces.

1. Installez et déverrouillez le coffre

npm install -g zn-gate
zn unlock

Sous Windows PowerShell, npm et npx peuvent échouer avec « l'exécution de scripts est désactivée sur ce système ». Utilisez npm.cmd et npx.cmd, lancez les commandes depuis l'Invite de commandes, ou autorisez les scripts locaux pour votre compte avec Set-ExecutionPolicy -Scope CurrentUser RemoteSigned. Plus de détails dans Installer sous Windows.

Le premier zn unlock crée le coffre : une identité age conservée dans le trousseau de votre système (Trousseau macOS, Gestionnaire d'identification Windows ou Secret Service sous Linux), ou protégée par une phrase secrète s'il n'y a pas de trousseau. Le coffre reste déverrouillé 8 heures, ou jusqu'à 30 minutes sans utilisation, ou jusqu'à ce que vous lanciez zn lock.

Après une mise à jour de zn-gate, un coffre qui tourne encore avec l'ancienne version laisse les secrets sous forme de marqueurs dans les hooks de l'agent jusqu'à son redémarrage. zn vault status affiche la version du coffre en cours d'exécution et signale une version obsolète, et zn unlock le redémarre pour vous.

zn vous demande de confirmer certaines choses en dehors de l'agent (étape 4). Sur un poste de bureau, il affiche une boîte de dialogue du système. Sur un serveur ou en SSH, il n'y a pas de boîte de dialogue : lancez le coffre dans un terminal séparé et répondez-y.

zn unlock --foreground

2. Déplacez les valeurs de votre .env dans le coffre

zn env shadow .env

Chaque valeur sensible passe dans le coffre et .env ne garde que des marqueurs :

DATABASE_URL=postgres://app:__ZN_DATABASE_URL_PASSWORD__@db:5432/app
STRIPE_KEY=__ZN_STRIPE_KEY__
PORT=3000

Une copie chiffrée de l'original est conservée, et zn env unshadow la restaure. Pour ajouter un seul secret, saisissez-le dans une invite masquée (jamais en argument) :

zn secret set GITHUB_TOKEN --host api.github.com

3. Installez les hooks de votre agent

zn hooks install claude-code     # ou : codex, cursor, opencode

Désormais, chaque lecture de fichier, sortie de commande et prompt collé passe par le nettoyeur avant d'atteindre le modèle. Les valeurs connues, plus de 60 formats de secrets (clés cloud, jetons, clés privées, chaînes de connexion) et les données personnelles qui passent une somme de contrôle sont remplacés par des marqueurs. Les détails sont dans Masquage.

Ce que les hooks bloquent :

• Les lectures de fichiers .env qui contiennent de vraies valeurs.
• Les fichiers d'identifiants comme ~/.aws/credentials, ~/.ssh/id_* et ~/.npmrc, ainsi que le dossier ~/.zn de zn lui-même.
• Un prompt qui contient un secret : il n'est pas envoyé. Dans les prompts, zn bloque aussi une valeur de 8 caractères ou plus attribuée à un nom d'identifiant, même au milieu d'une phrase (my key is STRIPE_KEY=..., DB_PASSWORD=...). Il laisse passer une valeur factice (changeme123, <key>), une référence (${API_KEY}, __ZN_STRIPE_KEY__) ou du code. Enregistrez la valeur avec zn secret set NAME et écrivez __ZN_NAME__ dans le prompt.

Codex n'exécute les nouveaux hooks qu'après que vous leur avez fait confiance : ouvrez Codex et utilisez /hooks.

Sur un ordinateur géré par une organisation, Claude Code peut être configuré pour ignorer les hooks et les serveurs MCP que vous installez vous-même (disableAllHooks, allowManagedHooksOnly, managed-mcp.json, ou une liste d'autorisation ou de blocage MCP), sans vous prévenir. zn hooks install claude-code et zn-gate status lisent les fichiers de paramètres gérés de cet ordinateur et les vôtres, et signalent quand l'un d'eux arrête les hooks de zn ou son serveur secrets. Demandez à votre administrateur d'ajouter zn aux paramètres gérés. Une politique envoyée via claude.ai, la gestion d'appareils (MDM) ou le registre Windows n'est pas lue : quand une telle politique existe, Claude Code peut ignorer les fichiers de paramètres gérés. claude doctor et /status indiquent quelle source Claude Code a utilisée.

4. Laissez une commande utiliser un secret

Autorisez le programme qui a besoin de la valeur :

zn secret allow DATABASE_URL_PASSWORD --command psql

Quand l'agent exécute psql "postgres://app:__ZN_DATABASE_URL_PASSWORD__@db/app", le hook le fait passer par zn run. La valeur va uniquement dans ce processus et sa sortie est masquée : les formes brute, base64, hexadécimale et encodée en URL reviennent sous la forme du marqueur. La première fois, le coffre vous demande de confirmer dans sa boîte de dialogue ou son terminal, et l'invite affiche le programme exact qui va s'exécuter. Modifier la politique d'un secret (zn secret allow) se confirme de la même façon. L'agent ne peut pas répondre à ces invites depuis son propre terminal.

Autorisez un programme précis. node, python, npm, make et les autres interpréteurs exécutent n'importe quel code qu'on leur donne : en autoriser un permet à chaque script qu'il lance de lire le secret. zn vous avertit quand vous le faites.

5. Laissez l'agent appeler une API

Pour les API HTTP, utilisez le serveur MCP secrets plutôt que de placer la valeur dans un processus. zn hooks install indique comment l'enregistrer pour votre agent. L'agent appelle secrets_http_request avec le marqueur dans un en-tête :

{ "method": "GET", "url": "https://api.github.com/user",
  "headers": { "Authorization": "Bearer __ZN_GITHUB_TOKEN__" } }

zn envoie la requête uniquement aux hôtes autorisés du secret (allowHosts), uniquement avec la valeur dans les en-têtes (pour l'utiliser dans l'URL ou le corps, lancez zn secret allow NAME --in query|body), et renvoie la réponse avec les secrets remplacés par des marqueurs. Aucun outil ne renvoie une valeur.

Configurations MCP

Le serveur secrets ci-dessus est la façon sûre pour l'agent d'utiliser une clé. Une clé écrite en clair dans un fichier de configuration d'agent est le contraire : elle voyage avec le dépôt. zn audit signale une valeur secrète dans un fichier de configuration ou d'instructions d'agent (constat ZNA011) et n'affiche jamais la valeur. Voir Audit.

Référence des commandes

Si le coffre est verrouillé, les hooks masquent quand même ce qu'ils reconnaissent, mais avec des marqueurs qui ne peuvent pas être restaurés (__ZN_REDACTED_AWS_KEY__), et vous rappellent de lancer zn unlock.

Pour vérifier ce qui est protégé sur votre machine, lancez npx -y zn-gate check.