Architecture

Comment zn-gate est construit. Trois points de contrôle autour de chaque action de l'agent, et les principes qui les guident.

Voir le .md

zn-gate est un petit point de contrôle qui s'exécute sur votre machine, entre votre agent de code et tout ce qu'il lit et exécute. Il examine trois moments de chaque action et reste discret le reste du temps. Cette page explique la structure et les principes qui la guident. Pour le détail des composants, voir Comment fonctionne zn-gate.

Trois points de contrôle

Étape	Point de contrôle	Quand	Ce qu'il fait
1	`analyze_prompt`	Avant que l'agent n'agisse sur un prompt ou un contenu	Recherche les injections de prompt, les jailbreaks et les secrets collés dans le texte
2	`check_tool_call`	Avant l'exécution d'un outil	Vérifie les arguments : injection, schémas d'exfiltration, chemins sensibles. Un appel bloqué n'atteint jamais l'outil. Les secrets présents dans les arguments sont masqués
3	`check_tool_result`	Après l'exécution de l'outil, avant que le modèle ne lise la sortie	Expurge les secrets et neutralise l'injection de prompt indirecte. Un résultat qui contient une injection est remplacé par un court avis

Chaque point de contrôle répond allow ou block et indique la rule et le reason qui ont décidé. Les trois mêmes vérifications fonctionnent dans chaque façon de configurer zn-gate : hooks de l'agent, serveur MCP ou zn-gate shield devant vos autres serveurs MCP. Les configurations et ce que couvre chacune sont décrites dans Comment fonctionne zn-gate.

Principes

Peu de dépendances. Le paquet Python n'utilise que la bibliothèque standard. Le paquet npm a une seule dépendance d'exécution, age-encryption (avec ses bibliothèques @noble et @scure), qui chiffre le coffre à secrets. Elle est incluse dans le paquet aux versions figées dans package-lock.json, et rien n'est compilé sur votre machine.
D'abord local et prévisible. Les vérifications s'exécutent sur votre machine avec des règles fixes : correspondance de motifs et normalisation des caractères qui se ressemblent, des caractères de largeur nulle et du texte encodé. La même entrée donne la même réponse, et chaque réponse nomme sa règle. Les 2 048 derniers résultats sont mis en cache, donc un texte répété n'est vérifié qu'une fois. Les temps mesurés sont sur la page Performances.
Un second avis facultatif du cloud. Seule l'analyse de prompts peut interroger le classifieur cloud, et seulement après que vous l'avez activé : définissez ZN_API_KEY et ZN_CLOUD=1, ou lancez zn-gate connect. ZN_LOCAL_ONLY=true le désactive à nouveau. Le texte que les règles locales bloquent déjà n'est jamais envoyé, et les secrets du texte sont retirés sur votre machine avant tout envoi (pas les données personnelles). Les arguments d'outils, les sorties d'outils et les descriptions d'outils ne quittent jamais votre machine, quelle que soit la configuration. Détails : Ce qui quitte votre machine.
Un journal local qui révèle les altérations. Chaque décision enregistrée par zn-gate shield et les SDK est ajoutée à ~/.zn/evidence.jsonl avec un hash SHA-256 qui la relie à la précédente, avec un aperçu expurgé et jamais le secret. zn-gate evidence --verify vérifie la chaîne. Elle détecte les modifications accidentelles ou partielles, mais ne protège pas contre quelqu'un qui peut écrire dans le fichier, car il peut la recalculer. Voir Preuves.

Ce que cette structure ne fait pas

C'est une frontière, pas tout votre modèle de sécurité. Gardez des droits minimaux sur les outils et une relecture humaine pour les actions à fort impact.
Ce que voient les points de contrôle dépend de la configuration de zn-gate et de l'agent. Un serveur MCP seul ne voit que les appels que votre agent choisit de lui envoyer. Les hooks couvrent aussi les outils intégrés de l'agent, dans la mesure où chaque agent le permet. Voir le Modèle de menace.
Les règles locales ne sont pas un classifieur sémantique : des attaques reformulées peuvent passer.