审计

npx -y zn-gate audit ./some-repo

（如果你用 npm i -g zn-gate 安装了它，也可以直接运行 zn audit；zn-gate audit 是同一个命令。）

编程智能体会读取它所在仓库中的配置。其中不少文件会运行命令、启动 MCP 服务器、改变智能体发送 API 请求的目的地，或者扩大它无需询问就能做的事。更新智能体可以修复已知的漏洞，但这些文件仍留在仓库里，下一个智能体、使用旧版本的同事或某个 CI 任务仍可能照着它们行事。

zn audit 读取这些文件，不运行任何内容，告诉你会执行什么、请求会发往哪里、智能体会遵循哪些指令。它在本地运行，不会向任何地方发送任何内容。请在打开刚克隆的仓库之前运行它，也可以在 CI 中运行。

选项

zn audit [path] [--format text|json|sarif] [--output <file>]
         [--fail-on low|medium|high|critical|none]
         [--agents claude,codex,cursor,opencode,amazonq,copilot,gemini,all] [--include-home]

示例：

# 打开刚克隆的仓库之前
npx -y zn-gate audit ./some-repo

# 在 CI 中：为 GitHub 代码扫描写出 SARIF 文件，并且永不让任务失败
zn audit --format sarif --output zn-audit.sarif --fail-on none

# 只检查 Claude Code 和 Codex 会读取的内容；仅在 critical 时失败
zn audit --agents claude,codex --fail-on critical

在 1.5 中，zn audit 显示的是密钥使用的本地日志。该日志现在是 zn vault log（也可用 zn secret log）。zn audit log 和 zn audit --since DATE 会以退出码 2 结束，并提示你改用 zn vault log。

退出码

它读取什么

任意深度的项目文件，因为智能体在子目录中启动时，该子目录的配置会生效。智能体文件夹（.claude、.codex、.cursor、.github、skills 等）会优先读取。在这些文件夹之外，node_modules、vendor 以及构建和虚拟环境文件夹会被跳过。.git 永远不会被读取。

仓库所能控制的任何内容，都不能让文件悄悄从报告中消失：

• 指向仓库之外的符号链接会被报告（ZNA020），而不会被跟随。
• 超过 1 MB 的智能体文件会被报告（ZNA020），而不是被跳过。
• 扫描在 50,000 个目录条目或 120 秒后停止，并以 ZNA020 高严重度结果说明这一点，因此运行会在默认阈值下失败。
• 已提交的根目录 .env 如果把 CODEX_HOME 或 CLAUDE_CONFIG_DIR 设为仓库内的文件夹，zn audit 也会读取那里的配置。
• 根目录的 .env 即使被 .gitignore 列出也会被审计，因为在新克隆的仓库中，它只有在被提交过的情况下才会存在。它的结果会低一个级别，并说明这些结果不适用于你自己的本地 .env。

使用 --include-home 时，它还会读取 ~/.claude/settings.json、~/.claude.json、~/.codex/config.toml、~/.cursor/mcp.json、~/.cursor/hooks.json、~/.aws/amazonq/mcp.json、~/.config/opencode/opencode.json[c] 和 ~/.gemini/settings.json。它会像智能体一样遵循 CODEX_HOME 和 XDG_CONFIG_HOME。你自己配置的命令在这些文件中是预期之内的，所以只会报告风险更高的情形：下载后运行的代码、未固定版本的包、端点覆盖、密钥和宽泛的权限。端点、环境变量和权限相关的结果在这里最高为 medium。

规则

规则 id 是稳定的：规则可以改进，但它的 id 含义永远不变。严重程度为 critical、high、medium 和 low；当一条规则列出多个级别时，结果会取最符合具体情况的那个。

输出

文本

zn audit  ./some-repo  (zn-gate 1.12.0 或更高版本)

CRITICAL  ZNA007  .claude/settings.json:4  [claude]
          Model API endpoint overridden by the project
          ANTHROPIC_BASE_URL points to https://agent-proxy.example.invalid
          evidence: "ANTHROPIC_BASE_URL": "https://agent-proxy.example.invalid"
          fix: Remove the override; set it in your user settings if you need a gateway.

1 finding (1 critical, 0 high, 0 medium, 0 low) in 3 files. Failing: severity >= high.

只有在终端中才会使用颜色，设置了 NO_COLOR 时绝不使用。来自仓库的控制字符和转义序列会以 \x1b 的形式打印，绝不会发送到你的终端。

JSON

--format json 输出一个包含 findings 和 summary 的对象：

{
  "version": 1,
  "tool": "zn-gate",
  "toolVersion": "1.12.0",
  "root": "/home/me/some-repo",
  "findings": [
    {
      "id": "ZNA007",
      "severity": "critical",
      "agent": "claude",
      "file": ".claude/settings.json",
      "line": 4,
      "title": "Model API endpoint overridden by the project",
      "detail": "ANTHROPIC_BASE_URL points to https://agent-proxy.example.invalid ...",
      "evidence": "\"ANTHROPIC_BASE_URL\": \"https://agent-proxy.example.invalid\"",
      "fix": "Remove the override ...",
      "references": []
    }
  ],
  "summary": {
    "files": 3,
    "findings": 1,
    "bySeverity": { "critical": 1, "high": 0, "medium": 0, "low": 0 },
    "failOn": "high",
    "failed": true,
    "agents": ["claude", "codex", "cursor", "opencode", "amazonq", "copilot", "gemini"]
  }
}

file 相对于 root，使用正斜杠；来自 --include-home 的文件以 ~/ 开头。agent 是读取该文件的智能体，多个智能体都会读取时为 any。evidence 是匹配的那一行，截断为 160 个字符，其中的密钥会被替换为 [REDACTED:<TYPE>]。URL 中的用户名、密码、查询字符串和片段都会被去掉。

SARIF

--format sarif 为 GitHub 代码扫描写出 SARIF 2.1.0：每个 ZNA id 对应一条规则，带有帮助文本和严重度分数，结果的位置相对于仓库根目录。每个结果都带有指纹，因此行号移动后告警依然保留。来自 --include-home 的结果会被标记为来自主目录，GitHub 会忽略它们，所以请在 CI 中不要使用该选项。

在 CI 中使用

最简单的方式是使用 zn-gate 的 GitHub Action，并设置 mode: audit。见 GitHub Actions。

如果想自己运行命令行，请写出 SARIF 文件并上传到代码扫描：

- run: npx -y zn-gate@1.12.0 audit --format sarif --output zn-audit.sarif --fail-on none
- uses: github/codeql-action/upload-sarif@v4
  with:
    sarif_file: zn-audit.sarif

如果希望任务在出现 high 和 critical 结果时失败，请去掉 --fail-on none（默认值是 high）。只有在上传 SARIF 时，才需要给任务添加 security-events: write。

局限

• 它只读取文件；不会运行它们、启动服务器或解析包。固定了版本的包仍可能是恶意的，调用本地脚本的钩子只会被报告为钩子，而不会根据脚本的实际行为来判断。
• 指令规则逐行匹配模式。有决心的作者可以写出任何模式都检测不到的指令，而引用危险命令的文档同样会被报告，例如带有 curl ... | sh 的安装指南。请在采取行动前查看证据。
• 工作流规则逐行读取 YAML。它了解常见的智能体 action 以及触发器和权限的键，但不了解可复用工作流或组合 action。
• Git 配置（.git/config、.gitattributes 过滤器）和编辑器扩展不在检查范围内。
• 智能体经常更改配置格式。未知的键会被忽略，而不会被报告。
• 密钥是按格式和敏感键名来发现的。没有已知格式、且放在普通键名之下的密钥不会被发现，用文字写出的密码也不会在证据中被隐去。