zn-gate

zn-gate

面向编码 Agent 的本地安全层。 使用 Claude Code、Codex CLI、Cursor 或 OpenCode 时，zn-gate 会保护你的机密、数据和系统。

zn-gate 是一个开源安全层，在你的设备上运行，介于 Agent 与其访问的工具和内容之间。它会检查 Agent 读取和调用的内容是否包含提示词注入，在模型看到工具输出前遮蔽其中的机密，并审计提示词、技能和配置。默认无需账户和网络连接，除 age-encryption（及其 @noble/@scure 依赖项）外没有运行时依赖；这些依赖用于机密保险库，已按 package-lock.json 中锁定的版本打包在软件包中。

适用对象： 使用 Claude Code、Codex CLI、Cursor、OpenCode 或任何 MCP 客户端的开发者。Python SDK：PyPI 上的 zn-gate。

安装

所有操作都在你的设备上运行；无需账户或 API 密钥。你需要 Node.js 18 或更高版本（nodejs.org 上的 LTS 版本）。如果 Node.js 版本较旧，zn-gate 和 zn 命令会停止运行，并说明如何安装。Claude Code 插件需要 Node.js 20.12 或更高版本。

快速上手：四个步骤，每步一条命令。 在你自己的终端中运行。

1. npx -y zn-gate reach 显示编码 Agent 在这台设备上可以访问的内容：.env 文件中的机密（仅显示名称）、凭据文件和 MCP 服务。此操作只读，不会发送任何内容。详情请参阅 docs/reach.md。
2. npx -y zn-gate init 会逐步为检测到的编码 Agent 设置防护，并在每次更改前征求你的同意。
3. npx -y zn-gate check 会在临时文件夹中使用虚构机密测试防护。init 也会在最后运行此命令。
4. npx -y zn-gate env shadow .env 会将 .env 中的真实值移入本地保险库，并在文件中留下标记。首次使用时，运行 npx -y zn-gate unlock 创建保险库。

一条命令即可为设备上的编码 Agent 设置防护：

npx -y zn-gate init

init 会执行以下操作：

• 检测设备上的 Claude Code、Codex CLI、Cursor 和 OpenCode。
• 对尚未受到保护的每个 Agent，显示设置步骤：Claude Code 使用 zn-gate 插件（如果你的 Node.js 版本低于 20.12，则使用 zn 的 hooks），其他 Agent 使用 zn 的 hooks。
• 仅在你确认后执行每个步骤。
• 最后运行 zn-gate check。

请在你自己的终端中手动运行此命令。当 AI Agent 或脚本运行它时，它只会打印操作步骤。

Windows PowerShell： npm 和 npx 可能会报错“此系统禁止运行脚本”，因为默认执行策略会阻止 npm.ps1。请改用 npm.cmd、npx.cmd 和 zn.cmd（例如 npm.cmd install -g zn-gate），在命令提示符中运行命令，或者使用 Set-ExecutionPolicy -Scope CurrentUser RemoteSigned 为你的账户允许本地脚本。

如果遇到问题：

• 出现 npx: command not found，或提示 Node.js 版本有问题：安装 Node.js 的 LTS 版本，打开新终端，然后重新运行命令。
• 在 Windows 上出现“此系统禁止运行脚本”：请参阅上文的 PowerShell 说明。
• init 只打印步骤，没有进行任何更改：这是 AI Agent 或脚本运行了它。请在自己的终端中手动运行。
• check 显示 NOT protected：该行会说明原因以及要运行的命令。输出含义。
• 想撤销 init 所做的更改：npx -y zn-gate init --revert。

然后将 .env 中的值保存在保险库中。 使用插件或钩子后，Agent 无法读取含真实值的 .env 文件；请将这些值移入 zn-gate 的加密保险库，文件中则保留 __ZN_STRIPE_KEY__ 之类的标记：

npx -y zn-gate unlock            # creates the vault the first time
npx -y zn-gate env shadow .env

完成后，你自己的应用也会读取 .env 中的标记：允许后，使用 zn-gate 的 run 命令启动应用一次即可（docs/secrets.md）。env shadow 会告诉你如何撤销此操作。

五分钟快速指南：docs/secrets.md。限制：docs/threat-model.md。不熟悉的术语：glossary。

claude plugin marketplace add usezn/zn
claude plugin install zn-gate@usezn

npm install -g zn-gate
zn hooks install codex           # or: cursor, opencode

python3 -m venv .venv
.venv/bin/pip install zn-gate      # Windows: .venv\Scripts\pip install zn-gate

claude mcp add zn-gate -- npx -y zn-gate mcp     # Claude Code
codex mcp add zn-gate -- npx -y zn-gate mcp      # Codex CLI

init 会在你的 Agent 配置文件中查找 MCP 服务、写入备份，并使用 zn-gate shield 包装每个本地（stdio）服务：

npx -y zn-gate init --dry-run   # preview, changes nothing
npx -y zn-gate init --wrap-mcp  # wrap (a .bak.<timestamp> copy is written first)
npx -y zn-gate init --shadow    # log detections without blocking
npx -y zn-gate init --revert    # restore the latest backup

远程（URL）服务会保持原样。对于无法安全地读写往返的文件，init 绝不会重写：带注释的 OpenCode JSONC 文件和包含多行 args 的 Codex 条目会被报告为“手动包装”。

手动包装单个服务：

npx -y zn-gate shield -- uvx mcp-server-fetch

查看 zn-gate 做了什么

npx -y zn-gate report

查看这台电脑过去 7 天的简要摘要：被拦截的操作、被隐藏的密钥、新增的受保护 MCP 服务，以及等待你批准的工具变更。它只读取本地文件，无需账户，也不会发送任何内容。--since 30d 可更改时间范围，--json 会以脚本可用的格式输出。查看报告内容。

启用可选的云端检查

npx -y zn-gate connect

此操作是可选的，必须由你在自己的终端中亲自完成（Agent 无法代劳）。它会打开 usezn.com，让你创建仅用于分析的 API 密钥（该密钥无法读取你的使用情况或管理其他密钥），随后提示你在隐藏输入框中粘贴密钥。具有完整访问权限的密钥会被拒绝。密钥会保存在你的系统密钥链中（如果没有密钥链，则存入 zn 保管库），绝不会写入文件；zn 的钩子也会阻止 Agent 通过直接方式读取密钥。之后，你或 Agent 通过 analyze_prompt 发送的文本，在先移除检测到的密钥后，也会交由 usezn.com 上的 Galvanize 2 分类器检查。在你运行此操作之前，不会发送任何内容。zn-gate disconnect 会从这台电脑移除密钥，并询问是否也要在 usezn.com 上撤销密钥（默认选择否）。了解工作原理。

检查是否正常运行

npx -y zn-gate check

对于每个已为你的用户配置的 Agent，zn-gate 都会要求其钩子在临时文件夹中读取一个包含虚假密钥的 .env 文件和一个普通文件。它会显示会告知 Agent 的内容；如果某行显示 未受保护，则会说明如何修复。不会通过网络发送任何内容，也不会更改任何设置。了解输出含义。

npx -y zn-gate test

这会运行本地自检（51 个精选样例：26 个攻击样例、25 个良性样例），并显示这台机器上的每项判定延迟。这是冒烟测试，不代表检测率。不会通过网络发送任何内容。

开发者：手动查看脱敏效果。 将包含虚假 AWS 密钥（AWS 文档中的示例）和数据库密码的工具输出，通过 zn-gate 发送，发送方式与 Agent 使用时完全相同；然后查看输出中的 sanitized_content，该字段就是模型会看到的内容：

printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"check_tool_result","arguments":{"tool_name":"read_file","content":"AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE\nDATABASE_URL=postgres://app:hunter2@db:5432/main"}}}' \
  | npx -y zn-gate@latest mcp

各部分的作用

Scrubber：让机密信息远离模型上下文

• 当前：对所有经过 zn-gate 的内容（check_tool_result、check_tool_call，以及由 shield / init 包装的服务的输出）进行脱敏，包括 AWS 密钥、OpenAI 和 Anthropic 密钥、GitHub 令牌、JWT、私钥和数据库 URL 密码。
• 当前未覆盖：Agent 内置的工具（例如 Claude Code 中原生的文件读取），除非它们的输出经过 zn-gate。
• 规划中：个人数据（PII）检测；为 Agent 内置工具提供钩子；由本地加密保险库支持的稳定占位符。

Galvanize：提示词注入检测

• 当前，本地：采用确定性规则引擎，并针对同形异义字符、零宽字符、双向文本覆盖（CVE-2021-42574）、注释拼接和 Base64 进行规范化处理。它会检查提示词、工具参数、工具输出和 MCP 工具描述。
• 当前，可选云端：Galvanize 2 分类器（开放权重，Apache-2.0）也可以检查发送到 analyze_prompt 的提示词，但只有设置 ZN_CLOUD=1 和 ZN_API_KEY 时才会启用。
• 规划中：在 zn-gate 内本地运行 Galvanize。

Scan：审计 Agent 即将信任的内容

• 当前：npx -y zn-gate scan <path> 会审计提示词模板、AGENTS.md / SKILL.md 文件和配置，查找注入陷阱和泄露的机密信息。发现问题时会以代码 1 退出，适用于 CI。可在网页 usezn.com/scan 上检查 MCP 服务。
• 规划中：在添加 MCP 服务和技能之前，通过命令行对其进行审计。

MCP 工具

哪些内容会离开你的设备

默认情况下，不会有任何内容离开。

单独设置 ZN_API_KEY 不会启用任何功能。另一种选择加入的方式是 zn-gate connect：你在自己的终端中运行该命令，它会将密钥保存在系统密钥链或 zn 保险库中，绝不会保存到文件（运行 zn-gate disconnect 可撤销连接；如果你确认，还可以在 usezn.com 撤销密钥；详情）。ZN_LOCAL_ONLY=true（或 --local-only）会覆盖 ZN_CLOUD=1 和已连接的密钥。npx -y zn-gate status 会显示当前启用的检测引擎，以及可选的云端检查是否开启。使用统计共享默认关闭，并有独立的状态查询命令：npx -y zn-gate stats share status。数据流示意图：仓库 README。

**1.4.0 及更早版本：**设置 ZN_API_KEY 后，本地未拦截的工具输出和工具调用参数会未经脱敏就发送到 api.usezn.com。1.4.1 移除了这条数据发送路径。请参阅 CHANGELOG。

性能（本地规则引擎，不联网）

测量日期为 2026-10-11，测试环境为 2 vCPU Intel Xeon Platinum 8259CL（AWS）、Node 24、zn-gate 1.4.1，输入未缓存。p50 为 3 次运行的中位数；p99 为 3 次运行中的最差值。

check_tool_result 包含机密信息脱敏。延迟大致随输入大小线性增长。在同一主机上，4 KB check_tool_result 的 MCP stdio 往返延迟 p50 为 0.5 ms。

在仓库中运行 node bench/bench_by_size.js 即可复现。欢迎把你的数据发给我们。

准确性：本地规则能检测什么，以及不能检测什么

本地引擎是一个确定性的特征签名和规范化层。它速度快、可解释，但不是语义分类器。

• **自测：**51 个精选测试向量全部通过。这只是冒烟测试，并不代表检测率或误报率。
• **已知局限：**对于完整源文件（check_tool_result 所看到的内容），规则可能会标记普通代码注释。1.5.0 减少了对代码和文档的误报，但代价是一些措辞较宽泛的覆盖尝试可能绕过本地规则。对于网页和第三方内容，优先使用 check_tool_result，而不是检查自己的仓库文件。
• **检测率：**在包含 3,309 个示例的私有留出集上，Galvanize 2 的召回率为 83.4%，误报率为 0.81%（服务阈值为 0.662）；这些数据针对云分类器，而非本地规则引擎。方法、各语言结果、已知薄弱环节和可复现的基准测试见模型卡和公告。它只是防御的一环，并非保证。

配置

• ZN_CLOUD：设为 1 后，analyze_prompt / zn-gate analyze 也会查询云分类器。需要 ZN_API_KEY。默认关闭。
• ZN_API_KEY：usezn.com/dashboard 中的 API 密钥。未设置 ZN_CLOUD=1 时无效。（zn-gate connect 会为你保存密钥并开启云端检查。）
• ZN_LOCAL_ONLY：设为 true 后强制仅使用本地检查，即使设置了 ZN_CLOUD=1 也是如此。
• ZN_STRICT：设为 1 后，也会拦截默认仅发出警告的规则（见下文）。
• ZN_LONG_INPUT：指定如何将长文本（超过 1,000 个字符）发送给云分类器。windows（默认）会让分类器检查最多 20 个相互重叠的 512 词元窗口，避免漏掉长文档中间或末尾的注入内容；off 则只检查前 512 个词元。也可以使用 --long-input windows|off。窗口检查速度较慢，也稍微更容易将长篇无害文本标记出来；无论是否使用窗口，云端检查都按文本长度计费，因此 off 不会减少计费次数（最多 2,000 个字符时为 1 次调用，此后每增加 1,000 个字符再增加 1 次；结果中的 billed_calls）；详见更新日志。
• ZN_STAGE：v30（默认，当前生产 API）或 prod（旧版端点）。ZN_API_URL 可覆盖两者。
• NO_COLOR（任意非空值）或 TERM=dumb：命令输出不显示颜色、符号或框线；状态词（ALLOWED、BLOCKED、PASSED 等）仍会显示。输出不是终端时也会关闭颜色。

要为某个 MCP 服务启用云端检查，请在其条目中添加："env": { "ZN_CLOUD": "1", "ZN_API_KEY": "zn_live_..." }。

自定义规则（.znrules 或 zn.config.json）

# .znrules
path:.env.production
path:/etc/secrets
CONFIDENTIAL_INTERNAL_PROJECT_[A-Z0-9]+

本地审计日志

zn-gate shield 会将每项决策追加到 ~/.zn/evidence.jsonl，作为包含秘密信息脱敏预览的哈希链（SHA-256）记录。它可以检测意外或局部修改。但对于拥有该文件写入权限、能够重新计算整个哈希链的人来说，它无法防止篡改。

npx -y zn-gate evidence --verify
npx -y zn-gate evidence --ui        # local dashboard on http://localhost:3100
npx -y zn-gate evidence --tail 20

哪些内容会被拦截，哪些只会触发警告

zn-gate 会拦截几乎可以确定属于攻击或信息泄露的内容：读取凭据文件（.env、~/.aws/credentials、SSH 密钥），索要 API 密钥或密码，通过隐藏图片链接发送数据，在 Base64 或不可见字符中隐藏指令，“忽略之前的所有指令”，以及危险命令。

还有一些模式也会出现在普通文本中，例如 YAML 中的 system: 键、“绕过缓存”，或介绍什么是越狱的文章。对于这些内容，zn-gate 会放行，并附上一条简短警告（结果中的 advisory），以便你或你的 Agent 查看。

要拦截这些内容，请启用严格模式：设置 ZN_STRICT=1，或在项目的 zn.config.json 中添加 "strict": true，或在 .znrules 中添加一行 strict。

常见问题

我需要账号或 API 密钥吗？ 不需要。所有本地功能都无需账号或密钥。

它会拦截合法内容吗？ 有时会。在 init 或 shield 中使用 --shadow，即可在评估期间记录检测结果而不进行拦截。

如何移除它？ npx -y zn-gate init --revert 会从备份中恢复你的配置。对于独立服务，请从 Agent 配置中移除 zn-gate 条目。

安全

请将漏洞报告发送至 [email protected]。相关政策和安全港说明：SECURITY.md。

许可证

MIT © usezn

此软件包包含 age-encryption（BSD-3-Clause）及其 @noble / @scure 依赖项（MIT）；请参阅 THIRD_PARTY_NOTICES.md。