h5i：Agent 接过了 Burp 的活，也接过了它的规矩

一、速览：值不值得你花时间

推荐指数：★★★★☆（4 / 5）

先给定位，因为 h5i 很容易被误读成”又一个 AI 扫描器”。它不是。

h5i 是把 Burp Suite / Caido 干的那一层——驱动页面、抓流量、改包、重放、比对——重做成一个 Agent 原生的 CLI 工作台，再在旁边放了半边形式化验证。 仓库自己的话说得很准：“Find Bugs (Red-Teaming)” 和 “Prove Correctness (Formal Verification)” 是互补的两条路——测试找你没料到的 bug，证明你能陈述的性质。

它和第 002 期 Shannon（读源码 + 真打验证）、第 017 期 Cloudflare security-audit-skill（提示词编排审计）都不是一类东西：h5i 提供的是”手”，不是”脑”。 它不替 agent 做漏洞判断，它给 agent 一套可审计的操作原语，然后把判断权和纪律一起交还给使用者。

那为什么值 4 分？因为那份 SKILL.md 是我在这个赛道里见过的、把”agent 做安全测试的操作纪律”写得最完整的公开文本。 举几条原文：

No complete PoC, no vulnerability. Record it as info at most, and say what is missing to confirm it.

A denial is a policy result, not an obstacle. … Never disable a hook or edit policy from inside a box.

Never report a candidate as an endpoint that exists. Only confirmed means that.

“没有完整 PoC 就不算漏洞””被拒绝是策略在起作用、不是要你绕过的障碍””candidate 不等于存在”——这三条单独拿出来，每一条都能砍掉一类 agent 幻觉式报告。而 h5i 把它们写进了随二进制分发的 skill，不是写在博客里。

第二个反常识：skill 是编译进二进制的。 crates/h5i-core/src/skill.rs 用 include_str! 把 SKILL.md + 8 个 reference 页（boxes / browser / policy / export / troubleshooting / websec / recon / project）直接嵌进可执行文件，h5i skill install 或 npx skills add h5i-dev/h5i 再把它写出来。后果是skill 和 CLI 的版本永远不会漂移——对比第 017 期 Cloudflare 那套纯 Markdown skill（流程藏在 md 里、和任何运行时都可能不同步），h5i 这个设计从根上消掉了”文档说的命令和二进制支持的命令对不上”这类问题。

扣分项也明确：概念密度高（box / policy / export / receipt / mediated commit 一套术语，为人设计的 GUI 一个没有）；形式化验证那半边只对你用 h5i-app 新写的后端有效，存量应用吃不到；接口仍在动（0.4.x → 0.5.0，box 的外部仓库 clone 还停在 roadmap）；以及 macOS 上借道 Chromium 代理时会 --ignore-https-errors、让那个 Chromium 接受所有证书错误——这是它自己写明的权衡，但必须点名。

关键数据（截至 2026-10-14）

适合谁

二次开发

二、它是什么，不是什么

是：

• 一个 agent 原生的 Web 安全工作台：浏览器驱动、HTTP 流量捕获/改包/重放/比对、侦察爬取、沙箱 box、本地 dashboard，全部以 CLI + skill 暴露给 agent。
• 一套证据纪律的机器可读版本：SKILL.md 把”什么算漏洞、什么算候选、被拒绝怎么办、证据怎么引用”写成硬条款。
• 一个形式化验证框架（h5i-app）：Rust 写 kernel，Aeneas 翻 Lean 4，证授权 / 隔离 / 业务逻辑性质。
• 一个仍在快速迭代的年轻项目：v0.5.0，2026-03 创建，release 节奏以周计。

不是：

• 不是扫描器。 它不内置漏洞规则库去”扫”出 CVE 式结论；它给 agent 操作原语，漏洞判断在使用者。要规则化扫描看第 012 期 Vigolium / 第 013 期 garak。
• 不是 MCP server。 它对 agent 的接口是 skill + CLI。别按 MCP 的期望去找 tool schema。
• 不是 Burp / Caido 的 GUI 替代品。 仓库里甚至有 burp-vs-h5i / caido-vs-h5i 的对照图，但它的形态是”会话即证据”的命令行，不是人工交互的代理界面。
• 不是给存量应用做形式化验证的工具。 证明侧要求你用 h5i-app（Axum + kernel 模式）写后端。
• 不是成熟稳定 API。 0.4.x → 0.5.0 还在动，box 的外部仓库 clone / 空 box 仍在 roadmap（M2）没接线。

有一个认知坑要点破：h5i 的”浏览器”和”抓包”是同一个会话。 h5i browser open --capture 之后，你驱动的页面和它产生的流量在同一个 session 里，websec 里看到的 req_42 就是刚才那次点击发的请求。join 的键是 message id——这正是它证据链能成立的原因：recon 说”有什么”，websec 测”它怎样”，两边靠 id 对齐，每条结论都能指回可读的字节。

三、核心机制：一条可审计的红队回路

SKILL.md 里给的回路就是它的骨架：

1
2
3
4
5
6
7
8
9

h5i browser open https://target.example --capture --script   # 一个会话同时持有页面和它的流量
h5i recon extract                            # 页面和 bundle 泄露了什么；不发请求
h5i recon known                              # robots.txt / sitemap.xml / security.txt
h5i recon crawl --max-requests 200 --rate 4  # 在当前登录态下有界地爬
h5i recon triage --calibrate                 # 折掉噪声，确认哪些是真的
h5i websec requests                          # 抓到的消息，按 id 列
h5i websec replay req_42 --set query.id=456  # 改包重放
h5i websec diff res_42 res_43                # 比对响应
h5i websec finding create --title '...' --evidence req_42,res_43   # 把结论写下来

拆开看，四个设计值得单独讲。

3.1 证据先于字节：request log 是 decision record

SKILL.md 原话：“the engine is the HTTP client, so the page you drove and the traffic you test are one session, and the request log is a decision record written before the bytes moved. Every message carries the id you cite it by.”

翻译过来：请求日志不是事后抓的包，是在字节发出之前就写下的决策记录，每条带 id。 这意味着：

• 你重放 req_42 时，引用的是当时真实发出过的那条，不是你记忆里的”大概是那个请求”；
• finding 必须 --evidence req_42,res_43，结论和字节绑定；
• 会话结束后，h5i project finding promote 把 finding 和它引用的消息（去掉凭证）拷进持久 store，h5i project report 出报告、h5i ui 里读、导出 PDF。

“A finding kept only in your reply is lost when the session ends.”——这句是对 agent 说的，但同样打脸所有”我在对话里说过结论了”的人工流程。

3.2 纪律条款：把反幻觉写进 skill

这是全项目我最想抄走的部分。逐条看：

这不是”最佳建议”，是写进随二进制分发的 skill 的操作条款。agent 读到它，就等于读到了一份带强制语气的作业规范。对比多数项目把这类话放在 README 的温馨提示里，h5i 把它放进了 agent 必然会加载的上下文。

3.3 box：沙箱是工作树，导出是提案

h5i box 不是”跑个容器”那么简单，它有一套生命周期：

1
2
3
4
5

h5i box --name review        # 建箱（base 在创建时冻结）
h5i box status review        # 父分支后来动了 = drift，会被报出来
h5i box run review -- <cmd>  # 箱内执行
h5i box diff review          # 看改动
h5i box export review        # 导出 = 提案：patch.diff + report.md + receipt.json

几个关键设计：

• base 在创建时冻结，父分支后续移动算 drift，h5i box rebase 是唯一 sanctioned 的重新 pin（3-way、遇冲突拒绝）——把”沙箱里的代码和我以为的代码不一致”这个经典坑显式化了。
• export 是提案不是应用：一个包含 patch.diff / report.md / receipt.json 的 proposal，要你审过 report、被拒的 egress、redaction、浏览器证据和 patch 才落地。
• fails closed：h5i box probe 说这台主机能强制什么，h5i box capabilities <name> --json 说这个箱实际拿到了什么；h5i 不会静默削弱你请求的策略，宁可失败也不降级。
• 箱 id 是 env/<agent>/<name>，agent 取自 $H5I_AGENT（Claude Code 里是 claude、Codex 里是 codex、裸 shell 是 human）——多 agent 并存时各自的箱互不串。

3.4 证明侧：kernel 是纯函数，信任边界画得很清

h5i-app 那半边的模型很干净：

• 业务逻辑写成一个纯函数 kernel：transition(actor, snapshot, command) -> (Option<Memory>, Reply)；
• 用 Aeneas 把 kernel 翻译成 Lean 4 去证性质（授权、隔离、业务逻辑、跨请求的提交顺序）；
• 服务端是普通 axum 应用，handler 不碰数据库；每个请求跑在 SERIALIZABLE 的 PostgreSQL 事务里，带重试和幂等键；
• schema! 宏一次声明表，同时得到 Rust 映射和 Lean 证明；
• 信任边界明示：axum/hyper 和 PostgreSQL 是 trusted，被提取去证明的是 kernel 和 storage 编译器（crate 表里一堆 extracted, proven）。

“they test the running application for what you did not anticipate, and h5i-app proves the properties you can state.” —— 红队找你没料到的，证明证你能说清的。这句话是理解整个项目世界观的钥匙。

四、设计上值得学的，和必须点名批评的

4.1 值得学

• skill 编译进二进制（include_str!）：skill 与 CLI 版本天然同步，消掉文档/实现漂移。这个做法值得所有”skill 型”项目抄。
• message id 作为 join 键：recon / browser / websec 三个面靠 id 对齐，证据链才成立。
• 纪律条款进 skill 上下文：反幻觉不是靠模型自觉，是靠加载进上下文的硬条款。
• export-as-proposal + fails closed：沙箱产物默认是”待审提案”，策略不静默降级。
• 信任边界写死在文档里：证明侧明确 axum/hyper + Postgres 为 trusted，不假装什么都证了。

4.2 必须点名批评

① 概念密度对人不友好。
box / policy / export / receipt / mediated commit / drift / rebase / capabilities / probe……这套术语是为 agent 设计的，人类上手要读 9 页 skill + MANUAL。它没有为”人直接用它做手工测试”做任何妥协——这既是特点也是门槛。

② 形式化验证只覆盖”h5i-app 写的后端”。
证明侧的前提是你用 h5i-app 的 kernel 模式写后端。存量应用（哪怕也是 Rust/Axum）要吃到证明，得把逻辑重写成 kernel。这不是缺点而是边界，但很容易被 README 的 “Formally verify properties” 误导成通用能力。

③ macOS 借道 Chromium 的证书权衡。
SKILL.md 明写：macOS 上 h5i browser proxy URL 产出的是 --ignore-https-errors，那个 Chromium 在本次启动接受所有证书错误。这是为了 MITM 抓 HTTPS 流量的现实妥协，但它意味着那条浏览器通道本身不做证书校验——在一个安全工具里，这条权衡必须被使用者清楚知道，而不是埋在 reference 里。

④ 捕获即敏感面。
skill 自己提醒：“a capture holds Authorization and session cookies in full.” 证据 store 里躺着完整凭证。promote 时会去凭证，但会话期间的 store 本身就是高价值目标，存放位置和权限要自己管好。

⑤ 接口还没定型，且它是”skill + CLI”这种最难稳定的形态。
CLI 的 flag、box 的生命周期语义、finding 的 schema，都还在 0.4.x → 0.5.0 之间移动。麻烦在于它的调用方是 agent：agent 侧写死的命令串、你团队沉淀的 skill 提示词、CI 里那段脚本，都会跟着 CLI 一起漂。相比之下普通库的 breaking change 至少会被编译器拦住，这里是自然语言指令，错了不会报错，只会跑偏。 生产化之前，把版本号 pin 死、并在升级时重跑一遍完整回路。

⑥ 插件分层意味着开箱能力有限。
websec / recon / test 是可选插件，安装时要显式 --websec --recon --test。只装核心的话，SKILL.md 里大半回路跑不起来。“装了但没装插件”是最常见的”这工具没用”误判来源。

⑦ box 的外部源还没接线。
克隆外部仓库 URL、从空 box 起步都在 roadmap（M2），当前 box 的 base 只能来自本仓库的 HEAD / 某个 rev / PR ref。想沙箱化第三方代码现在还做不到。

五、生态定位：它站在哪

h5i 的独特位置：唯一一个把”浏览器驱动 + 抓包重放 + 沙箱 containment + 证据纪律 + 形式化验证”做成一个 agent 原生工作台的公开项目。 Cloudflare 那套给了纪律但没有手（它指挥你的 agent 去 grep）；Shannon 有手但纪律体现在流水线闸门而非操作条款；Burp 有手但那是给人用的。h5i 是”给 agent 的手 + 给 agent 的作业规范”同时到位的那个。

而”skill 编译进二进制”这一点，让它和第 017 期形成鲜明对照：一个把流程写在 md 里靠 agent 自觉，一个把流程和工具焊死在同一份二进制里。 后者的工程含义是——你不可能拿到一个和 CLI 不同步的 skill。

六、部署：先装插件，再谈回路

安装

1
2
3
4
5
6
7
8

# 核心 + 三个可选插件（websec / recon / test）
curl -fsSL https://h5i.dev/install.sh | sh -s -- --websec --recon --test

# 不想加域名进信任链的话：
# curl -fsSL https://raw.githubusercontent.com/h5i-dev/h5i/main/install.sh | sh
# cargo install --path .          # 或从源码

h5i plugin list                   # 看装了什么

别忘了插件。 只装核心的话 SKILL.md 里 websec / recon 那些命令都不在。

把 skill 交给你的 agent

1
2
3

npx skills add h5i-dev/h5i        # 还没有二进制时
# 或已有二进制：
h5i skill install                 # 写到当前 runtime 找得到的位置

然后在你的 agent harness 里直接说：“Audit https://.com with h5i.”

沙箱与仪表盘

1
2

h5i box --name review             # 需要 containment 时先建箱
h5i ui                            # 本地 dashboard，看浏览器和会话活动

授权红线（SKILL.md 的 scope 段）

Test only authorized targets. Keep every request inside the granted origin, identity, rate and scope, and get approval before widening any of them.

只打授权目标；origin / 身份 / 速率 / scope 四个边界任何一个要放宽，先拿批准。 工具提供捕获、重放和证据，漏洞判断和 staying in bounds 是你的责任——这句话它写得很清楚，别装没看见。

七、边界与风险

1. 学习曲线陡，且是故意的。
它为 agent 优化，不为人类 GUI 用户优化。第一次用请完整读 SKILL.md 的 “Scope is the discipline” 和 “The loop”，再读你要用的那几页 reference，别直接猜 flag（skill 里甚至写了 “Use h5i <command> --help before guessing flags”）。

2. 证明侧有前提。
只覆盖 h5i-app kernel。想给存量后端上形式化验证，先评估重写成本，别被 “Formally verify properties of Rust codes” 一句口号带进去。

3. macOS 的 --ignore-https-errors。
见 4.2③。用借道 Chromium 的会话时，清楚那条通道不校验证书。

4. 证据 store 含完整凭证。
见 4.2④。管好存放位置和权限；promote 进 project 时会去凭证，但会话期间不会。

5. 调用方是 agent，接口漂移没有编译器兜底。
见 4.2⑤。CLI 语义、box 生命周期、finding schema 都还在动，而你写进 skill / 提示词 / CI 的命令串不会报错，只会跑偏。pin 版本，升级后重跑一遍完整回路。

6. 它不替你判断漏洞。
没有规则库、没有”扫出 CVE”。想要自动化结论流，搭配第 013 期 garak（LLM 探针）或第 012 期 Vigolium（规则扫描）；h5i 负责的是”可审计地操作目标”。

八、上手建议（按这个顺序来）

1. 先读 SKILL.md 的 “Scope is the discipline”，再读 “The loop”。 这两节决定了你会不会用它做出幻觉报告。比直接跑省一倍时间。
2. 安装时带上 --websec --recon --test。 漏装插件是”这工具没用”误判的头号来源。
3. 拿一个你自己授权的小目标跑完整回路：browser open --capture → recon extract/known/crawl → websec requests/replay/diff → finding create --evidence ...。体会 message id 是怎么把结论钉回字节的。
4. 需要 containment 就先建 box，并养成 h5i box capabilities <name> --json 看实际强制等级的习惯——不要靠猜。
5. finding 一律 finding create 落盘，会话结束前 project finding promote + project report。别让结论只活在对话里。
6. 把 SKILL.md 的纪律条款抄进你自己的 agent 规范。 哪怕你不用 h5i，”No complete PoC, no vulnerability””denial 是策略结果””报前找两次假阳性”这三条也值回票价。
7. 想碰形式化验证，从 calculator tutorial 入手（examples/app/calculator/TUTORIAL.md），先理解 kernel 是纯函数、handler 不碰库这个约束，再决定要不要迁移后端。
8. 别拿它当 Burp 替代品给人工用。 团队里需要 GUI 交互抓包的同事，继续用 Burp / Caido；h5i 是给 agent 的那一层。

九、一句话结论

h5i 不是又一个 AI 扫描器，而是把 Burp/Caido 那一层”驱动页面 + 抓包重放”重做成 agent 原生工作台、再补上半边 Lean 4 形式化验证的 Rust 项目——概念密度高、没有为人类设计的 GUI、证明侧只覆盖自家框架、接口仍在 0.x 阶段移动。但它真正稀缺的是那份编译进二进制的 SKILL.md：message id 证据链、No complete PoC no vulnerability、denial 是策略结果、禁止在 box 里自解除武装——它把”agent 做安全测试该怎么守纪律”写成了随工具分发的硬条款，这是目前公开项目里做得最彻底的一个。

给你的一句话动作：装上 --websec --recon --test → 把 SKILL.md 的纪律段读两遍 → 拿自己授权的小目标跑一遍 browser→recon→websec→finding 回路 → 需要 containment 就建 box 并用 capabilities --json 确认强制等级。 即便你最后不用它打目标，那份纪律条款也值得抄进你自己的 agent 安全作业规范——它最好的部分不是功能，是它坚持让 agent 在动手之前先学会什么叫证据。