zn-gate（本地）

脱敏器与密钥保险库

zn-gate 1.5 让密钥值不会进入编码代理发送给模型的内容。代理只使用标记；真实值保存在你机器上的加密保险库中，并且仅在你允许的地方填入。

查看 .md

zn-gate 让密钥值不会进入编码代理发送给模型的内容。代理使用的是 __ZN_GITHUB_TOKEN__ 这样的标记；真实值保存在你机器上的加密保险库中，并且仅在你允许的地方才会被填入。检测、替换和保险库完全在本地运行：没有任何云服务（包括我们自己的）参与其中。

适用于 zn-gate 1.5.0 及更高版本（npm）；在 Windows 上请使用 1.5.1 或更高版本（GHSA-rf3f-ppm5-3xrx）。支持的代理：Claude Code、Codex CLI、Cursor（IDE）和 OpenCode。各代理允许钩子修改的内容有所不同：请参阅 compat.md，以及 threat-model.md 中的限制说明。

功能概述

  • 对模型可见的内容进行脱敏。 文件读取、命令输出、搜索结果、MCP 工具结果和粘贴的提示词，在到达模型之前都会经过脱敏器处理。已知值（来自保险库和你的 .env 文件）、约 30 种密钥格式（云密钥、令牌、私钥、连接字符串中的密码）以及个人数据（经校验和验证的银行卡号、IBAN、DNI/NIE 和社会安全号码；电子邮件、电话号码和 IPv4 地址）都会被替换为稳定的标记。同一个值始终获得相同的标记，因此模型仍可以对其进行推理，且该行的结构保持不变：DATABASE_URL=postgres://app:__ZN_DATABASE_URL_PASSWORD__@db:5432/app。在 Cursor 中，只有 MCP 输出可以被改写：那里的 shell 和文件输出不会被脱敏。
  • 阻止读取原始凭据。 包含真实值的 .env 文件、~/.aws/credentials 或 ~/.ssh/id_* 等凭据文件，以及 zn 自身的 ~/.zn：钩子会阻止代理的工具读取这些文件（这是一种防护措施，而不是沙箱）。
  • 将值保存在加密保险库中。 保险库使用 age 加密；其密钥保存在操作系统的钥匙串中（或受口令保护）。它绝不会离开你的机器，也从不同步。本地审计日志记录哪个密钥在何处被使用，但从不记录值。
  • 仅在你允许的地方填入值。 你允许的命令会通过 zn run 获得该值，且其输出会被遮蔽。HTTP API 通过 secrets MCP 服务器调用，该服务器只会将值发送到你允许的主机，并返回已将密钥替换为标记的响应。没有任何工具会把值返回给代理。
  • 由你而非代理来确认。 程序首次使用某个密钥，以及任何扩大密钥策略的更改，都会在系统对话框或保险库自身的终端中请求你确认。代理无法回答这些提示。

快速开始

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

要让某个命令使用密钥，请允许该程序：

zn secret allow DATABASE_URL_PASSWORD --command psql

允许特定程序：node、python、npm、make 以及其他解释器会运行所给的任何代码，因此允许其中任何一个，都会让它运行的每个脚本读取该密钥，并且你这样做时 zn 会发出警告。

要添加单个密钥，请在隐藏输入提示中输入，切勿作为参数传入：zn secret set GITHUB_TOKEN --host api.github.com。

完整的操作步骤见 密钥指南。

常用命令

命令 作用
zn secret list 列出名称、模式、主机和命令（从不显示值）
zn secret rm NAME 删除一个密钥
zn vault log 本地审计日志：谁在何处使用了哪个密钥，从不记录值
zn vault verify 检查审计日志是否未被篡改
zn lock 立即锁定保险库
zn hooks uninstall <agent> 移除钩子

如果保险库已锁定，钩子仍会对其能够识别的内容进行脱敏，并使用无法还原的标记（__ZN_REDACTED_AWS_KEY__），同时提醒你运行 zn unlock。

限制

  • 脱敏器能够发现已知值和可识别的格式。如果某个密钥没有已知格式，且既不在保险库中也不在 .env 文件中，它可能会漏过：请将你的密钥迁移到保险库中。
  • 在 Windows 上批处理文件（.cmd、.bat）的批准仅针对该文件本身，而不针对其按名称启动的程序。对于 HTTP API，请优先使用 secrets_http_request，或直接批准程序本身。
  • 保险库解锁期间，以你的操作系统用户身份运行的任何程序（包括代理运行的命令）都可以按名称向其请求密钥。不需要时请使用 zn lock 将其锁定。
  • 你允许的程序会持有该值，并可能将其发送到任何地方：请只允许特定程序，使用范围受限的令牌，并启用代理的沙箱。
  • 某些代理会保留自己的本地副本（Codex 的会话日志会保留原始输出）。
  • Python 包（PyPI）的库函数中包含密钥脱敏功能（redact_secrets、sanitize_tool_result、guard），但不包括保险库、钩子、zn run 或个人数据脱敏。

有关仅针对 MCP 工具输出和参数的脱敏，请参阅 密钥脱敏。

开源

与 zn-gate 的其他部分一样采用 MIT 许可：github.com/usezn/zn。变更记录见 CHANGELOG。