zn-gate 1.16.0 有什么新变化:更清晰的 check、zn why、智能体历史中的密钥、软件包审计、更严格的命令检查
John Silver10 分钟阅读
zn-gate 1.16.0 让 check 更易读,也更易于用脚本处理。zn-gate check --hooks 会列出所有已安装的钩子,并说明它们是正常、过期还是已损坏;普通的 check 末尾新增一行钩子摘要和每次工具调用的决策耗时;check --json 则把同样的结果提供给脚本和 CI。zn why 用通俗的话解释最近一次拦截。此外还新增了四个在你主动开启之前保持关闭的功能,让命令检查读懂 shell 实际运行的更多内容,并检查钩子加载的每一个 zn-gate 文件。zn-gate 仍然不需要账号,默认也不发送任何内容。使用 npm install -g zn-gate@1.16.0 和 pip install -U zn-gate 更新。
check 现在能告诉我更多信息吗?
能。共有四项新增内容,全部在本地完成:
zn-gate check --hooks(也可用doctor --hooks)会列出每个已安装的 zn 钩子,包括它所属的智能体、设置文件、事件和它运行的命令。每个钩子的状态是正常、过期(由旧版 zn-gate 写入)或已损坏(无法运行、已被关闭、被写入了两次,或位于 zn 无法读取的设置文件中),过期或已损坏的那一行会附上修复它的命令。它只读取文件:不会运行、修改或发送任何内容。- 钩子摘要。 普通的
check和doctor末尾会多出一行,例如Hooks: 3 OK, 1 stale, 0 broken. Run zn-gate check --hooks for details.。它只在安装了钩子时才显示,不会改变退出码。当某个钩子由旧版 zn-gate 写入时,zn-gate status也会给出警告,指明是哪个智能体,并给出刷新它的命令。 - 决策耗时。
check末尾会显示最近 100 次工具调用的 p50 和 p95,在你的机器上测得。它不包括进程启动、写出响应以及保存统计和证据的时间。它以纯数字形式保存在~/.zn/stats.json中,在 zn 检查过工具调用之前显示为no data yet。 zn-gate check --json(也可用doctor --json)会输出一个 JSON 对象,供脚本、CI 和支持请求使用:包括每个智能体的防护状态及原因、版本和退出码。退出码与文本形式相同,你的主文件夹显示为~。
zn why 有什么用?
zn why 会用通俗的话解释决策日志中最近一次拦截,或你指定 id 的那条记录(zn why <id>):被拦截的是什么(只显示日志中已有的简短预览)、触发了哪条规则、为什么重要,以及有的话,你可以在自己的终端里运行以继续的命令。它只读取日志,从不使用网络。它包含在 npm 包中。
六条拦截消息现在遵循同一种格式:写明规则名称,说明为什么重要,说明谁可以放行,并在可能时给出要运行的那条命令。它们涵盖破坏性命令、.env 文件和其他密钥文件、会发送个人数据的请求、过长而无法检查的命令,以及不可用的密钥保管库。这些消息的开头仍与以前相同。当 ls * 或 cat * 这样的通配符因为也会匹配 .env 文件而被拦截时,消息现在会就该模式作出说明,并提示你写出你需要的文件名。
有哪些新功能,且除非我开启否则默认关闭?
- 智能体历史中的密钥:
zn-gate reach --history。 它会逐行读取你主文件夹中 Claude Code 和 Codex 的历史文件,并输出智能体、文件、密钥类型、出现次数以及应当采取的措施(轮换密钥、删除会话)。它从不输出具体的值。--json为脚本提供同样的内容。它不写入任何内容,不发送任何内容,也不跟随任何链接,当达到时间限制(--max-seconds,默认 120)时,它会说明哪些文件没有处理完。它无法看到已经发送给你的模型提供商的内容。Python 包也有此功能,报告、标志和退出码都相同。 - 添加之前先审计软件包:
zn-gate scan --package <name>[@version]。 zn-gate 会从注册表下载 npm MCP 服务器或技能,对照其校验和进行检查,解压到临时文件夹,并读取带有受扫描扩展名的文件,同时执行智能体配置审计。不会按名称跳过任何文件夹,因此软件包内的node_modules、dist和build也会被扫描。在给出结果之前,报告会列出安装时 npm 将会运行的内容:它的preinstall、install和postinstall脚本及其命令,以及它的bin命令。软件包中的任何内容都不会被安装或运行。发现问题时退出码为1,软件包有部分内容无法读取时为3,无法获取软件包或软件包被拒绝时(例如校验和不匹配)为2。它不会扫描该软件包所依赖的软件包。 - 检查智能体安装的软件包。 它涵盖
npm install、pnpm add、yarn add、bun add、pip install、uv add和pipx install,并且从不拦截命令。在~/.zn/config.json中把hooks.packageInstallCheck设为"offline"(或设置ZN_PACKAGE_CHECK=offline),当名称看起来像某个知名软件包时(差一个字母、两个字母互换、外形相似的字符、不同的分隔符,或模仿知名软件包的 npm 作用域),你的智能体会在安装前先询问你。设为"online"(仅限配置文件)时,对于普通安装,zn-gate 还会向公共的 npm 或 PyPI 注册表查询该名称是否存在,只发送软件包名称,并在名称不存在或首次发布不足 14 天时询问你。无法显示提问的智能体(Codex CLI、OpenCode、Gemini CLI)会直接运行该命令,所有发现都会写入决策日志。对发布不足 72 小时的版本的提示,以及对可能更新锁文件的项目中npm install的提示,是单独的另一项可选开启功能(hooks.packageInstallNotices)。 - 限制命令可以访问的主机:
zn run --egress-allow HOST[:PORT],...。 zn 会为该命令在 127.0.0.1 上设置一个本地代理,对其他主机的请求会得到 403。它涵盖读取代理变量的程序(curl、gh、requests、axios),在 Node 中则只涵盖遵循NODE_USE_ENV_PROXY的版本。旧版 Node 的fetch、忽略这些变量的程序、原始套接字和 DNS 都不在涵盖范围内。
检查现在会读取哪些命令?
破坏性命令检查会拦截对你的主文件夹、文件系统根目录或系统文件夹的递归删除。1.16.0 在做出决定之前,会读取 shell 实际运行的更多内容:
- 文件夹切换。 它会跟随同一行前面的
cd和pushd,以及env -C、env --chdir、sudo -D和sudo --chdir。cd ~ && rm -rf .、env -C ~ rm -rf .和sudo -D / rm -rf .会像rm -rf ~一样被拦截,嵌套的 shell 则从这一行已到达的文件夹开始。对项目文件夹执行的相同命令(cd build && rm -rf .、env -C ~/projects/app rm -rf .)仍然允许,cd ~ && rm -rf .cache也是如此。 - shell 关键字和反引号。
{ rm -rf ~; }、if true; then rm -rf ~; fi、while ...; do ...; done、! rm -rf ~以及反引号中的命令,都会被当作单独写出的同一条命令来读取。 - 下载并运行。 该检查现在还会拦截:从输入端的替换中读取程序的 shell(
bash < <(curl URL)、sh <<< "$(curl URL)")、以另一种方式写出的下载器或 shell(/bin/sh -c "$(curl ...)"、bash <(\curl ...))、通过管道送入命令组或下一行的下载(curl URL | (sh)),以及同一行中先前赋值的字面变量(X=curl; $X URL | sh)。bash < <(echo hi)、diff <(curl ...) <(curl ...)和curl URL | jq .仍然允许。 .env的各种写法。 带路径前缀的.env文件(./.env、app/.env、/srv/app/.env)、出现在 PowerShell 列表中的(cat .env.example,.env)、带 PowerShell 参数的(Get-Content -Path:.env)、通过 cmd.exe 写出的(type .e^nv、%NAME%单元),或通过可能补全该名称的 shell 展开写出的,都会被拦截。.env.example这类示例文件仍然允许,而.env.dist、.env.defaults和.env.schema会被拦截。- 启动器检查每一个文件。 安装时,钩子启动器会记录
lib/下的代码和数据、package.json以及bin/cli.js的 SHA-256。钩子加载这些文件中的每一个时都会进行检查,被编辑过、不在列表中、是链接或位于软件包之外的文件会让钩子停止。zn-gate check会指出被更改的文件。启动器脚本本身、Node.js 二进制文件、作为数据读取的文件,以及 Windows 上的内联 PowerShell 钩子(Codex CLI、Cursor、Gemini CLI、Antigravity)不在涵盖范围内。
完整列表请参见破坏性命令。
团队、zn audit 和 Python 方面有什么变化?
- 团队。
zn team status --rules会用通俗的话输出你所在组织当前生效的已签名策略中的规则:版本、密钥 id、过期时间,以及每条规则拦截、警告或限制的内容和原因。它不发起任何网络调用,也不显示来自无法验证或已过期副本的规则。zn team join -从标准输入读取加入令牌,因此它不会出现在你的 shell 历史记录和进程列表中(printf %s "$TOKEN" | zn team join -,或设置ZN_TEAM_JOIN_TOKEN)。作为参数传入的令牌仍然有效。 zn audit。zn audit --approve会记录项目的可执行配置(MCP 服务器、钩子、权限、辅助命令、安装脚本等)。之后的审计会把更改、新增或移除的条目报告为 ZNA023,只给出名称。批准由你来决定:该命令只能在终端中运行,当智能体写出audit --approve时,zn 会将其拦截。新规则 ZNA022 会标记把工具事件发送到某个地址的http类型钩子。- Claude Code。
zn hooks install claude-code还会注册ConfigChange和InstructionsLoaded钩子。再次运行它即可添加。 - GitHub Copilot 不再标记为实验性。
zn hooks install copilot会设置 VS Code、GitHub Copilot 应用和 Copilot CLI 共用的钩子。这些钩子只用 Copilot CLI 做过端到端运行,VS Code 部分只有文档说明,没有在应用中测试过。 - Python。 本地检查的启动时间缩短到原来的一半以下,因为
import zn_gate不再预先编译所有规则。Python 包也会像 Node.js 包一样对相同形态的密钥进行脱敏,并且python -m zn_gate会运行zn-gate命令。
有什么不兼容的变化吗?
对大多数人来说没有。以下是可能让以前能用的功能停止工作的变化:
- 不认识的选项会报错。
check、doctor、status、version、test、evidence、logs、export、team status、scan和analyze遇到不认识的选项时会以2退出,消息中会列出该命令接受的选项。以前,这个选项会被忽略。 zn.json中拼错的设置。security或audit部分中 zn 不认识的设置现在会报错,并指出该设置和最接近的有效设置。在其他部分中仍然只是警告。- 过期的钩子。 如果
check提示某个钩子已过期,或某个启动器只记录了运行器,请再次运行zn hooks install <agent>。 - 不认识的钩子事件(本版本不认识的名称或形态)现在会在能够拦截的钩子上被拦截,涉及 Claude Code、Codex CLI、ZCode 和 Cursor,并附带一条提示更新的消息。运行
zn hooks install <agent>来获取新的启动器。 - 如果你设置了
ZN_HOME。 到目前为止,设置了ZN_HOME时,决策日志、config.json中的钩子设置以及密钥请求列表仍然留在~/.zn,而统计、固定项、密钥保管库和云端密钥则跟随它。现在 zn 的所有状态都跟随ZN_HOME。如果没有设置该变量,则没有任何变化。
如何更新?
npm install -g zn-gate@1.16.0
pip install -U zn-gate
npx -y zn-gate@1.16.0 check
更新会刷新由它写入的钩子启动器。如果你的包管理器跳过安装脚本(npm install --ignore-scripts、pnpm 或 bun),或者你是用 sudo 更新的,请对你使用的每个智能体再次运行 zn hooks install <agent>。check 会告诉你哪些智能体需要这样做。如果你使用 Claude Code 插件,请运行 claude plugin update zn-gate@usezn 并开启新会话。
如果你已经设置过 ZN_HOME,请把 evidence.jsonl 和 requests.jsonl 从 ~/.zn 移到该文件夹,并把 config.json 中的钩子部分也复制过去。这三者以前都留在 ~/.zn,而 zn 现在会在 ZN_HOME 文件夹中查找它们。
完整列表见更新日志。