Modèle de menaces

zn-gate garde les valeurs secrètes hors du contexte du modèle. En mode env, une commande que vous avez autorisée détient toujours la valeur : limitez sa portée et activez le sandbox de votre agent.

Cette page porte sur le Scrubber et le coffre à secrets (détails). Elle décrit zn-gate 1.12.0 ou plus récent. Pour savoir ce qui quitte votre machine, voir Ce qui quitte votre machine.

Ce contre quoi zn-gate protège

L'objectif : qu'une valeur secrète n'atteigne jamais le modèle, ni les journaux et caches du fournisseur derrière lui, par les chemins d'outils habituels de l'agent. Cela couvre les lectures de fichiers, la sortie des commandes, les résultats de recherche, les résultats MCP et les prompts collés.

Ce contre quoi zn-gate ne protège pas

Les hooks sont un garde-fou, pas un sandbox : un processus déterminé peut trouver un autre moyen de lire un fichier. L'essentiel est que les outils habituels de l'agent ne remettent pas de valeurs au modèle.

Les hooks empêchent aussi les outils de fichiers et les commandes shell de l'agent d'écrire dans ~/.zn et dans les réglages de hooks et de plugins des agents eux-mêmes (par exemple .claude/settings*.json, les fichiers .codex/, .cursor/hooks.json et opencode.json, et les répertoires qui les contiennent). C'est un effort de bonne foi : une écriture que les hooks ne peuvent pas lire comme un mot de la commande (un chemin construit dans un script, du code en ligne comme python -c "open(...)", ou une variable définie plus tôt dans la même commande) n'est pas vue.

Ce que protège le processus du coffre

Le processus du coffre (zn unlock) garde le coffre déchiffré pour la session et répond aux requêtes sur un socket privé (un tube nommé sous Windows). Chaque connexion doit prouver qu'elle peut lire ~/.zn/run/session.key.

• Il protège contre les autres utilisateurs du système. Ils ne peuvent pas lire la clé de session, donc ne peuvent pas se connecter.
• Il ne vérifie pas quel programme de votre utilisateur fait la demande. Tout processus exécuté sous votre compte peut demander au coffre déverrouillé un secret stocké, par son nom. Cela inclut une commande lancée par l'agent, qu'elle contienne ou non un marqueur que les hooks peuvent voir. Les contrôles ci-dessus (liste de commandes autorisées, confirmation à la première utilisation, empreinte du programme, allowHosts et allowIn) protègent les chemins qu'offre zn-gate lui-même, zn run et le serveur MCP secrets. Ils ne sont pas appliqués à une demande directe au processus du coffre.
• Que faire : gardez le coffre verrouillé (zn lock) quand vous n'utilisez pas de secrets, laissez-le se verrouiller seul après inactivité (30 minutes par défaut), et utilisez le sandbox ou les règles de permissions de votre agent pour qu'il ne puisse pas lancer de programmes arbitraires sans vous demander.

La frontière est le processus du même utilisateur, comme pour ssh-agent. Vérifier le programme appelant et appliquer la politique dans le processus du coffre n'est pas fait dans la 1.12.0.

Lancement du programme approuvé

zn run résout le nom de la commande une seule fois, vers le chemin réel d'un fichier. Il ouvre ce fichier, le vérifie par rapport à votre approbation, le vérifie de nouveau juste avant de le lancer, et lance ce chemin. Il ne recherche jamais le nom dans PATH une seconde fois. Le degré de rigueur dépend du programme et du système :

• Les programmes natifs sous Linux sont lancés via le fichier que zn-gate a ouvert et vérifié : ce qui s'exécute est exactement ce qui a été vérifié.
• Les scripts (#!) sur tout système sont exécutés par leur interpréteur, qui rouvre le script par son chemin après la dernière vérification. Un processus de votre utilisateur pouvant écrire dans le répertoire du script pourrait le remplacer pendant cette courte fenêtre. Une ligne #!/usr/bin/env X cherche X dans le PATH de l'appelant, et la vérification porte sur le script, pas sur l'interpréteur trouvé là.
• Tous les programmes sous macOS et Windows sont lancés par chemin juste après la dernière vérification : la même courte fenêtre existe.
• Les variables du chargeur (LD_*, DYLD_*) et les variables de glibc qui chargent des fichiers ou modules au choix de l'appelant sont retirées de l'environnement du programme chaque fois que des valeurs secrètes sont injectées, et zn run le signale une fois. Sous Windows, un programme qui charge des DLL depuis son propre répertoire n'est pas couvert.
• Les variables de démarrage des interpréteurs (comme NODE_OPTIONS, PYTHONPATH, PERL5OPT, RUBYOPT, JAVA_TOOL_OPTIONS et BASH_ENV) sont aussi retirées, depuis la 1.5.1. Un interpréteur exécute toujours le code qu'on lui donne : n'approuvez donc des interpréteurs qu'en en ayant conscience. zn-gate avertit qu'ils exécutent n'importe quel code qu'on leur donne.

zn-gate avertit quand vous approuvez un programme si votre utilisateur peut écrire dans le programme ou dans un répertoire au-dessus. Les gestionnaires de versions comme nvm, volta, pipx ou Homebrew installent des outils dans de tels répertoires, donc il avertit au lieu de refuser. Pour éviter la fenêtre, approuvez des programmes natifs installés dans des répertoires où votre utilisateur ne peut pas écrire (par exemple des paquets système), pas des scripts de votre dossier personnel.

Copies locales, par agent

zn-gate contrôle ce qui atteint le modèle. Certains agents conservent aussi leurs propres enregistrements locaux :

• Claude Code : la transcription de session conserve la sortie des outils déjà nettoyée. Deux choses y restent en clair : un prompt que zn-gate a bloqué (la documentation de Claude Code elle-même le dit), et la commande affichée dans une boîte de confirmation quand zn-gate restaure une valeur détectée pour une commande locale. Ni l'un ni l'autre n'est envoyé au modèle, y compris à la reprise de la session.
• Codex : Codex ne peut pas réécrire la sortie des outils, donc zn-gate remplace par « block » le résultat que voit le modèle. Le journal de sessions propre à Codex (~/.codex/sessions) et les événements --json conservent la sortie d'origine.
• OpenCode : la sortie des outils et son aperçu sont réécrits. La sortie en direct qu'OpenCode enregistre pendant qu'une commande s'exécute encore est écrite avant que zn-gate puisse la voir, donc elle reste dans la base de données locale d'OpenCode.
• Cursor : Cursor ne peut pas du tout réécrire la sortie des commandes shell ni des lectures de fichiers. Les valeurs des fichiers que vous laissez l'agent lire, ou affichées par des commandes, atteignent le modèle. Gardez les secrets dans le coffre et les fichiers .env masqués par des marqueurs.

Canal de confirmation

La première utilisation d'un secret avec une commande, et les changements de politique qui élargissent un secret, sont confirmés par le processus du coffre :

• zn unlock --foreground : dans le terminal propre du coffre. Le shell d'un agent a un autre terminal.
• Sinon une boîte de dialogue système : osascript sous macOS, une fenêtre contextuelle sur « Non » par défaut sous Windows, zenity ou kdialog sous Linux (seulement avec une session de bureau). Une boîte sans réponse compte pour « non » après 120 secondes.
• Aucun canal (sans écran, SSH, processus détaché) : refusé, avec des instructions.

Ces confirmations arrêtent la prompt injection qui pilote les outils de l'agent. Elles n'arrêtent pas un logiciel malveillant exécuté sous le même utilisateur.

Quand quelque chose tourne mal

• Coffre verrouillé : les hooks exécutent toujours le scrubber sans lui. Ils masquent les motifs, les données personnelles et les valeurs trouvées dans les fichiers locaux avec des marqueurs irréversibles. Le broker refuse de remplir toute valeur.
• Erreur du scrubber : échec fermé. L'appel d'outil est refusé, la sortie retenue ou le prompt bloqué. Un moteur manquant échoue aussi en mode fermé, et le message explique comment le réinstaller. Vous pouvez laisser passer les événements pendant qu'il manque avec {"hooks": {"whenUnavailable": "allow"}} dans ~/.zn/config.json (les hooks empêchent les outils de fichiers de l'agent d'y écrire). La variable ZN_HOOK_FAIL_MODE ne peut que le rendre plus strict.
• Un événement illisible est refusé : quand l'entrée du hook est vide ou n'est pas du JSON, le hook écrit la raison et termine avec le code 2. Claude Code et Codex bloquent l'appel avec ce code avant l'exécution de l'outil. Une fois l'outil exécuté, le code 2 n'annule rien.
• Le processus du hook ne démarre pas du tout (par exemple, Node a changé d'emplacement après une mise à jour et la commande du hook pointe vers l'ancien chemin, ou le hook expire) : les appels d'outils de la plupart des agents passent alors sans contrôle. Relancez zn hooks install après avoir déplacé ou mis à jour Node. Les agents qui bloquent les prompts quand le hook échoue (Claude Code, Cursor, OpenCode) bloquent chaque prompt jusque-là : voir If your agent blocks every prompt (en anglais).

Limites connues et choix de conception

• Un secret avec allowHosts peut être utilisé en HTTP quel que soit son mode. La liste d'hôtes est l'autorisation explicite.
• Les fichiers versionnés gardent les marqueurs. zn-gate n'écrit jamais une valeur dans un fichier suivi par git. Restaurer une valeur dans un fichier suivi qui la contient déjà n'est pas pris en charge : le jeton y reste.
• Le tube nommé de Windows n'a pas de liste d'accès explicite. Chaque connexion s'authentifie dans les deux sens par un contrôle à clé sur une clé de session que seul votre utilisateur peut lire, donc un autre compte ne peut pas l'utiliser.
• Restaurer une ancienne copie authentique de secrets.age est accepté et rétablit les approbations et la politique qu'elle avait. Gardez privées les sauvegardes de ~/.zn.
• Chaque hook est un court processus Node : environ 78 ms en médiane par appel d'outil, mesurées sur un ordinateur de bureau Windows.
• Les commandes de monitor s'exécutent comme bash -c derrière le tube du scrubber. Les fonctions et alias du shell de l'agent n'y sont pas chargés.

Le texte complet, conservé avec le code, est docs/threat-model.md (en anglais).