Heron:AI Agent 时代的 Wireshark,给 Agent 装上黑盒透视仪

原创作者：艾瑞Eric

一个场景：

你的安全团队要审批一个 AI Agent 的上线。你问开发人员："这个 Agent 能访问哪些系统？"他转头去问 Agent，Agent 说"我只读文件、不改配置、不会删数据"。

然后呢？没有然后了。这份口头保证进不了审计日志，进不了合规报告，第二天 Agent 更新了一版权限，文档还是错的。

Heron 解决的就是这个问题——它不是靠 Agent 的"自觉申报"，而是在 Agent 不知道的情况下，用确定性基础设施读数（runtime configs、OAuth scopes、MCP tool lists）来核实 Agent 到底能干什么。

一句话定义：给 AI Agent 装一台测谎仪，零 SDK，不改一行代码，让它说清楚自己有哪些权限，然后去系统里一条条验证。

一、问题：AI Agent 的观测盲区

1.1 今天的 Agent 都是黑盒

不管是 Claude Code、Cursor、Codex，还是用 LangChain 搭的智能客服系统，线上跑起来之后，你能看到的只有日志——而日志是 Agent 自己写的。

这带来一个根本性问题：日志可以被省略、可以被改写、可以不完整。

当 Agent 调用了错误的能力、访问了不该碰的数据、在生产环境里执行了未预期的操作，你能追溯到的是 Agent"愿意让你看到的"，而不是"实际发生的"。

对于确定性软件，SRE 有完整的可观测性工具链——APM、traces、metrics、logs。但 AI Agent 的可观测性工具，在 2026 年之前几乎是一片空白。

1.2 审计需求的三个真实场景

场景一：安全合规（Security & Compliance）

金融、医疗、政府场景部署 Agent，需要通过 ISO/IEC 42001、AI UC-1、NIST AI RMF、GDPR 等框架的合规审计。审计员问的问题是：Agent 能访问哪些数据？有没有不可逆写操作？权限边界在哪？——这些不能靠 Agent 自己的描述，要靠基础设施的确定性证据。

场景二：生产排障（Debugging）

Agent 崩了，日志面目全非，开发者需要知道 Agent 在崩溃前调了哪些 API、访问了哪些文件、产生了多少次模型交互。今天的开发者通常靠"加日志"来追踪，代价是改动代码、重新部署、时间窗口可能已经错过。

场景三：Agent 审批（Access Review）

安全团队审批一个新 Agent 上线，需要回答"它会碰哪些系统？"这个问题。传统做法是维护一份 Google Doc，然后发现这份文档在上线第二天就过时了——因为 Agent 的权限会随对话上下文动态变化，没人去更新文档。

二、Heron 的解法：MCP 访谈 + 确定性验证

2.1 核心架构

Heron 的设计思路很巧妙：先问，再核实，然后把两者分开报告。

Agent  ──MCP 访谈──> Heron
                        │
                   17 个核心问题
                （系统权限、数据敏感性、写操作、
                 影响半径、删除流程等）
                        │
                        ▼
              Deterministic Verification
           (runtime configs / OAuth scopes /
            MCP tool lists / credential key names)
                        │
                        ▼
                 Audit Report
           (Verified / Discrepancy / Could not verify /
            Self-attested)

整个过程零 SDK、零代码修改、MIT 协议。任何 MCP-native 的 Agent 都能被审计：Claude Code、Codex、Cursor、Continue，或者你自己开发的 Agent。

2.2 访谈阶段：17 个灵魂拷问

Heron 会对 Agent 提出 17 个核心问题，涵盖以下维度：

• • 系统和访问范围：Agent 能接触哪些外部系统？每个系统的数据敏感性等级是什么？
• • 写操作和可逆性：有没有不可逆写入？影响半径有多大？
• • 凭证和密钥：有哪些 credential key names 在工作区里存在？
• • OAuth Scopes：Agent 持有的是哪些权限范围？
• • MCP 工具清单：Agent 声明使用的工具和实际暴露的工具是否一致？
• • 决策机制：对涉及人员的决策，Agent 的判断依据是什么？
• • 删除流程：数据删除路径是否存在？

对模糊答案，Heron 会生成追问（每问题最多 6 次追问），并始终锚定在 Agent 实际说过的内容上。

2.3 验证阶段：确定性读数 diff

访谈结束后，在 Agent 同意的前提下，Heron 读取以下确定性基础设施数据：

关键设计：Heron 不看 secret 的值。它只枚举"有哪些 key 存在"，而不是读取 .env 里的 API_KEY=sk-xxxxx。OAuth scopes 也是通过 Agent 自己 transport 元数据——token 从不离开 Agent 的进程。

2.4 报告阶段：四种诚实状态

这是 Heron 最核心的设计理念：报告里的每个发现只落在四种状态之一，不多报，也不模糊：

风险分数量化公式：Blast Radius × Data Sensitivity × Decision-Making weight，采用 FIPS-199 风格的高水位线（high-water mark）。一个怀有恶意的 Agent 无法靠"说得好听"拿干净报告——因为说话不是证据。

三、报告结构：五个模块，评审者顺序阅读

Heron 的报告按评审者的阅读顺序排列为五个模块：

模块一：Header
风险等级（仅从 Verified 证据计算）、验证状态、一句话描述 Agent 在做什么。

模块二：Systems & Access
每个系统一行，包含访问等级、数据敏感性 tier、不可逆写操作计数、系统级风险，以及 Verified? 列（introspection 确认 / discrepancy / 发现于 .env / 无确定性证据）。

模块三：Credentials & Secrets
检测到多少 credential key names，在哪些位置。只有 key 名，无 value。

模块四：Findings
Verified discrepancies 优先（这些驱动风险），然后是"Could not verify"桶，最后是 self-attested findings。Self-attested 内容完整可读，但明确标注、不进风险分。当确定性读数确认了某个 self-attested 发现的事实时，卡片会做交叉引用。

模块五：Compliance Lens
按框架（EU AI Act、GDPR、ISO/IEC 42001、AIUC-1、NIST AI RMF）逐条映射控制覆盖率，每条控制给出同样四种诚实状态中的判决。"Out of scope"会单独计数，因为那部分需要企业级 artifact 或超出访谈范围的外置探针。

四、使用教程

4.1 快速安装

一行命令启动本地仪表盘：

npx heron-ai

首次运行会引导到 /setup 页面配置分析 LLM（支持 Anthropic / OpenAI / Gemini，以及 LiteLLM、OpenRouter 等 OpenAI 兼容网关）。凭证存在本地 ~/.heron/credentials.json。

Heron 自身暴露为一个 MCP server，监听在 http://127.0.0.1:3700/mcp。

4.2 开始审计

在仪表盘拿到 MCP server URL 后，把引导 prompt 粘贴进目标 Agent 的对话窗口：

Please configure Heron as an MCP server at http://127.0.0.1:3700/mcp,
then call the start_audit_session tool.
While status is awaiting_answer, answer pendingQuestion via submit_answer;
repeat until status is complete or analysis_failed.
Report the result.

Agent 会自动配置自己的 MCP config，然后在自身上运行审计——自己审计自己。仪表盘实时流式传输访谈记录，完成后报告落地到同一视图和 ~/.heron/sessions/。

验证阶段是独立、需授权的步骤：Agent 调用 start_verification，Heron 的确定性扫描只在这次明确调用后才运行。仪表盘的授权对话框会列出 Heron 可能读取的每个路径，在任何文件被触碰之前呈现。

4.3 报告导出

报告支持 Markdown 和自包含 HTML 两种导出格式，可直接提交给安全团队或合规审计。

五、真实案例：一个典型发现

想象这样一个场景（来自 Heron 官方示例）：

Agent 在访谈中说："我只使用 Google Drive API 读取文件，不做任何写入操作。"

Heron 验证阶段做的事：

1. 1. 读取工作区的 runtime config，发现 Agent 配置了 drive.file 和 drive.metadata scopes
2. 2. 让 Agent 对自己的 OAuth token 做 introspection，发现实际 granted scopes 是 drive.file、drive.metadata 和
3. 3. 对比访谈声明与实际 scopes，发现 被声明了但没在访谈中提及

这就是一个 Discrepancy 发现。它不会被忽略，也不会因为"Agent 忘了提"就混进 self-attested 桶。它在报告中独立一行，标注来源 diff，进风险分。

六、设计哲学归纳

哲学一：说谎的 Agent 拿不到干净报告

这是 Heron 最核心的安全假设：Agent 的自我声明不等于证据。任何绕过确定性验证的"好听描述"都无法提升风险评分；任何 Discrepancy 都会被如实呈现在报告中，不会被稀释或模糊处理。

这解决了一个根本问题：恶意 Agent 无法通过"社交工程"（说得好听）来获取干净的安全报告。

哲学二：只读确定性事实，不碰 secret

Heron 在设计上永远不读取 .env 的 value，永远不让 token 离开 Agent 进程。这不仅是安全实践，也是合规要求——一个审计工具如果本身需要高权限才能运行，它自己就是攻击面。Heron 的 credential contract（只读 key names，不读 values）把这个问题降到了最低。

哲学三：诚实优于完整

"Could not verify" 和 "Self-attested" 这两种状态的存在，本质上是对"我不知道"这件事的尊重。很多审计工具会倾向于填满所有字段，制造一种虚假的完整感。Heron 相反——它把"不知道"明确标出来，不计入风险分，让评审者基于真实的不确定性做决策。

哲学四：自己审计自己，Agent 参与 consent

Heron 让 Agent 自己运行审计，而不是在旁边被动监控。这个设计有深意：它把 Agent 变成了审计过程的参与者，而不是被动被监控的对象。Consent 机制（验证阶段必须显式调用 start_verification）让整个过程对 Agent 透明，也符合 SOC 2 和 ISO 42001 的变更管理要求。

哲学五：零侵入性是企业级采用的前提

零 SDK、零代码修改、MIT 协议——这是 Heron 的战略选择。企业级 Agent 部署通常有严格的变更管理流程，任何需要"改代码加 SDK"的方案都需要额外的安全审批。Heron 把部署成本降到了零：只要 Agent 支持 MCP，审计就开始了。

七、对比：同类工具一览

Heron 的定位是安全审计与合规，不是性能监控。两者互补：Heron 告诉你"Agent 能做什么"，AgentSight 告诉你"Agent 实际做了什么"。

八、关键结论

1. 1. AI Agent 的可观测性不等于日志。日志是 Agent 自己写的，可以省略、可以改写、可以不完整。真正的可观测性需要来自 Agent 外部的确定性证据。
2. 2. "不可信调用"的审计是企业级 Agent 部署的刚需。金融、医疗、政府场景的合规要求决定了 Agent 必须能回答"你能访问哪些数据"这个问题，而且答案必须可核实、不可伪造。
3. 3. Heron 的核心价值是"诚实"：把每个发现放进正确的桶里（Verified / Discrepancy / Could not verify / Self-attested），不为了完整性而模糊边界。这是它与其他 APM/Langfuse 类工具的本质区别——后者告诉你"发生了什么"，Heron 告诉你"Agent 声称会发生什么，和实际验证结果对比是什么"。
4. 4. 零侵入性是企业级 AgentOps 的门槛。能进企业级部署的工具，必须做到装完就能跑，不需要改一行代码，不需要额外的安全审批流程。Heron 的 MCP-native 设计直接满足这一点。
5. 5. 商业上，可观测性天然是付费点。企业安全团队、合规团队、审计团队——这三类角色都需要 Agent 可观测性，但不需要 Agent 本身的"功能"——这是 AgentOps 的独立价值链。

项目地址：https://github.com/theonaai/Heron

在线 Demo 报告：https://heron.ing