h5i: Handing the Burp Layer to an Agent, Rules and All

1. At a Glance: Is It Worth Your Time

Rating: ★★★★☆ (4 / 5)

Start with the positioning, because h5i is easy to misfile as “yet another AI scanner.” It isn’t.

h5i takes the layer Burp Suite and Caido occupy — drive the page, capture the traffic, tamper with it, replay it, diff the results — and rebuilds it as an agent-native CLI workbench. Then it puts half a formal-verification framework next to it. The repo’s own framing is exact: “Find Bugs (Red-Teaming)” and “Prove Correctness (Formal Verification)” are complementary routes. Testing finds the bugs you didn’t anticipate; proving establishes the properties you can state.

This is a different species from issue 002’s Shannon (reads source, actually exploits to verify) and issue 017’s Cloudflare security-audit-skill (prompt-level audit orchestration). h5i supplies hands, not a brain. It doesn’t make vulnerability judgements for the agent. It gives the agent a set of auditable operating primitives, then hands judgement — and the discipline that goes with it — back to whoever is driving.

So why 4? Because that SKILL.md is the most complete public text I’ve seen on what an agent must actually do to test security honestly. A few clauses verbatim:

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.

“No PoC, no vulnerability.” “A denial means policy is working — it is not a thing to route around.” “A candidate is not an endpoint.” Each of these, on its own, kills a whole category of hallucinated agent report. And h5i puts them in a skill distributed inside the binary, not in a blog post.

Second counter-intuitive point: the skill is compiled in. crates/h5i-core/src/skill.rs uses include_str! to embed SKILL.md plus eight reference pages (boxes / browser / policy / export / troubleshooting / websec / recon / project) straight into the executable; h5i skill install or npx skills add h5i-dev/h5i writes them back out. The consequence is that the skill and the CLI can never drift apart. Compare issue 017’s Cloudflare skill, which is pure Markdown whose process lives in prose and can fall out of step with any runtime it drives. h5i’s design removes “the documented command doesn’t exist in this binary” as a failure mode at the root.

The deductions are just as concrete: high concept density (box / policy / export / receipt / mediated commit — a whole vocabulary, and not one GUI built for a human); the formal-verification half only reaches backends you write against h5i-app, so existing applications get nothing from it; the interface is still moving (0.4.x → 0.5.0, and cloning an external repo into a box is still on the roadmap); and on macOS, going through the Chromium proxy emits --ignore-https-errors, so that Chromium accepts every certificate error for the launch. That last one is a tradeoff the project states plainly, but it needs to be said out loud.

Key facts (as of 2026-10-14)

Who it’s for

Extending it

2. What It Is, and What It Isn’t

It is:

• An agent-native web security workbench: browser driving, HTTP capture / tamper / replay / diff, recon crawling, sandbox boxes, a local dashboard — all exposed to an agent as CLI plus skill.
• A machine-readable version of evidence discipline: SKILL.md turns “what counts as a vulnerability, what counts as a candidate, what to do when denied, how to cite evidence” into hard clauses.
• A formal verification framework (h5i-app): write the kernel in Rust, extract to Lean 4 with Aeneas, prove authorization / isolation / business-logic properties.
• A fast-moving young project: v0.5.0, created 2026-03, releases on a weekly cadence.

It is not:

• Not a scanner. There is no built-in rule base producing CVE-shaped conclusions. It gives the agent operating primitives; the vulnerability judgement stays with you. For rule-driven scanning see issue 012 Vigolium or issue 013 garak.
• Not an MCP server. The agent interface is skill + CLI. Don’t go looking for a tool schema.
• Not a GUI replacement for Burp / Caido. The repo even ships burp-vs-h5i / caido-vs-h5i comparison pages, but the form factor is “session as evidence” on the command line, not an interactive proxy UI.
• Not a way to formally verify your existing application. The proof side requires that you write the backend with h5i-app (Axum + kernel pattern).
• Not a stable API. 0.4.x → 0.5.0 is still moving, and cloning an external repo into a box / starting from an empty box are roadmap items (M2), not wired up.

One conceptual trap worth flagging: h5i’s “browser” and its “capture” are the same session. After h5i browser open --capture, the page you drive and the traffic it generates live in one session, and the req_42 you see in websec is the request that click just made. The join key is the message id — which is precisely why the evidence chain holds: recon tells you what exists, websec tests how it behaves, the two align by id, and every conclusion points back to readable bytes.

3. The Core Mechanism: An Auditable Red-Team Loop

The loop SKILL.md lays out is the skeleton of the whole thing:

1
2
3
4
5
6
7
8
9

h5i browser open https://target.example --capture --script   # one session holds the page and its traffic
h5i recon extract                            # what the page and bundles leak; sends no requests
h5i recon known                              # robots.txt / sitemap.xml / security.txt
h5i recon crawl --max-requests 200 --rate 4  # bounded crawl under the current logged-in state
h5i recon triage --calibrate                 # fold away noise, confirm what's real
h5i websec requests                          # captured messages, listed by id
h5i websec replay req_42 --set query.id=456  # tamper and replay
h5i websec diff res_42 res_43                # diff the responses
h5i websec finding create --title '...' --evidence req_42,res_43   # write the conclusion down

Four design decisions in there deserve their own paragraphs.

3.1 Evidence precedes bytes: the request log is a decision record

SKILL.md, verbatim: “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.”

Unpacked: the request log is not a packet capture assembled after the fact — it is a decision record written before the bytes moved, and every entry carries an id. Which means:

• When you replay req_42, you’re citing the request that was actually sent, not your recollection of “roughly that one.”
• A finding must carry --evidence req_42,res_43. The conclusion is bound to the bytes.
• After the session, h5i project finding promote copies findings and the messages they cite (credentials stripped) into the persistent store; h5i project report produces the report, h5i ui renders it, PDF export ships it.

“A finding kept only in your reply is lost when the session ends.” That line is addressed to an agent, but it indicts every human workflow where the conclusion lives only in a chat thread.

3.2 Discipline clauses: anti-hallucination written into the skill

This is the part I’d steal from the project. Clause by clause:

These aren’t “best practices.” They are operating clauses inside a skill distributed with the binary. When the agent loads it, it loads a specification written in the imperative. Most projects put this kind of language in a README’s tips section; h5i puts it in the context the agent is guaranteed to load.

3.3 box: the sandbox is a worktree, and export is a proposal

h5i box isn’t “spin up a container.” It has a lifecycle:

1
2
3
4
5

h5i box --name review        # create (base is frozen at creation time)
h5i box status review        # parent branch moved since = drift, reported explicitly
h5i box run review -- <cmd>  # execute inside
h5i box diff review          # inspect changes
h5i box export review        # export = a proposal: patch.diff + report.md + receipt.json

The load-bearing design decisions:

• The base is frozen at creation. If the parent branch moves afterwards, that’s drift, and h5i box rebase is the only sanctioned way to re-pin (three-way, refuses on conflict). The classic trap — “the code in my sandbox isn’t the code I think it is” — is made explicit rather than silent.
• Export is a proposal, not an application. You get a bundle of patch.diff / report.md / receipt.json, and you are expected to review the report, the denied egress, the redactions, the browser evidence and the patch before it lands.
• It fails closed. h5i box probe tells you what this host can enforce; h5i box capabilities <name> --json tells you what this box actually got. h5i will not silently weaken the policy you asked for — it would rather fail.
• Box ids are env/<agent>/<name>, with the agent taken from $H5I_AGENT (claude under Claude Code, codex under Codex, human in a bare shell). Parallel agents get non-overlapping boxes.

3.4 The proof side: a pure-function kernel and an honestly drawn trust boundary

The h5i-app half has a clean model:

• Business logic is written as one pure-function kernel: transition(actor, snapshot, command) -> (Option<Memory>, Reply);
• Aeneas extracts that kernel into Lean 4, where you prove properties — authorization, isolation, business logic, cross-request commit ordering;
• The server is an ordinary axum app in which handlers never touch the database; each request runs inside a SERIALIZABLE PostgreSQL transaction with retries and an idempotency key;
• The schema! macro declares each table once and yields both the Rust mapping and the Lean proof;
• The trust boundary is stated outright: axum/hyper and PostgreSQL are trusted; what gets extracted and proven is the kernel and the storage compiler (the crate table is full of extracted, proven).

“they test the running application for what you did not anticipate, and h5i-app proves the properties you can state.” Red-teaming finds what you didn’t foresee; proving establishes what you can articulate. That sentence is the key to the project’s whole worldview.

4. What’s Worth Stealing, and What Deserves Criticism

4.1 Worth stealing

• Compiling the skill into the binary (include_str!): skill and CLI stay in lockstep by construction, and documentation drift stops being possible. Every “skill-shaped” project should copy this.
• The message id as the join key: recon / browser / websec align on ids, which is what makes an evidence chain feasible at all.
• Discipline clauses inside the skill context: anti-hallucination isn’t the model’s goodwill — it’s hard text loaded into context.
• Export-as-proposal + fails closed: sandbox output defaults to “pending review,” and policy never degrades silently.
• A trust boundary written down: the proof side names axum/hyper and Postgres as trusted instead of pretending everything is proven.

4.2 Deserves criticism

① The concept density is hostile to humans.
box / policy / export / receipt / mediated commit / drift / rebase / capabilities / probe… This vocabulary was designed for an agent. A human needs to read nine skill pages plus the MANUAL before they’re productive. The project makes no concession whatsoever to “a person doing manual testing” — that’s both its character and its barrier.

② Formal verification only covers backends written against h5i-app.
The proof side presupposes the kernel pattern. An existing application — even one already in Rust and Axum — has to be rewritten as a kernel before it can be proven. That’s a boundary, not a defect, but “Formally verify properties” on the front page reads like a general capability, and it isn’t.

③ The macOS Chromium certificate tradeoff.
SKILL.md says it directly: on macOS, h5i browser proxy URL produces --ignore-https-errors, so that Chromium accepts every certificate error for the launch. It’s a pragmatic compromise for MITM’ing HTTPS, but it means that browser channel performs no certificate validation at all. In a security tool, this tradeoff belongs in the user’s face, not buried in a reference page.

④ Capture is a sensitive surface by definition.
The skill warns you itself: “a capture holds Authorization and session cookies in full.” Full credentials sit in the evidence store. Promotion strips them, but the session store is a high-value target while it lives, and its location and permissions are your problem.

⑤ The interface isn’t settled, and “skill + CLI” is the hardest shape to keep stable.
CLI flags, box lifecycle semantics and the finding schema are all still moving between 0.4.x and 0.5.0. The awkward part is that the caller is an agent: command strings baked into an agent harness, prompt templates your team accumulated, that block in CI — all drift with the CLI. A breaking change in a normal library at least gets caught by the compiler. Here the interface is natural-language instruction, so it doesn’t error; it just goes wrong. Pin the version, and rerun the full loop when you upgrade.

⑥ Plugin layering means the out-of-the-box capability is thinner than it looks.
websec / recon / test are optional plugins, installed explicitly with --websec --recon --test. Core alone can’t run most of the loop in SKILL.md. “I installed it but not the plugins” is the single most common source of the “this tool is useless” misjudgement.

⑦ External sources aren’t wired into boxes yet.
Cloning an external repository URL and starting from an empty box are roadmap items (M2). Today a box’s base can only come from this repository’s HEAD, a given rev, or a PR ref. Sandboxing third-party code isn’t possible yet.

5. Where It Sits in the Ecosystem

h5i’s distinct position: the only public project that folds browser driving + capture/replay + sandbox containment + evidence discipline + formal verification into one agent-native workbench. Cloudflare’s skill supplies discipline but no hands — it directs your agent to grep. Shannon has hands, but its discipline lives in pipeline gates rather than operating clauses. Burp has hands, and they’re built for a person. h5i is the one where “hands for an agent” and “a code of conduct for an agent” both show up.

And “the skill is compiled into the binary” sets up a sharp contrast with issue 017: one keeps the process in markdown and trusts the agent to follow it; the other welds process and tooling into the same executable. The engineering consequence is that you cannot end up holding a skill that disagrees with the CLI.

6. Deployment: Install the Plugins First, Then Talk About the Loop

Install

1
2
3
4
5
6
7
8

# core + the three optional plugins (websec / recon / test)
curl -fsSL https://h5i.dev/install.sh | sh -s -- --websec --recon --test

# if you'd rather not add that domain to your trust chain:
# curl -fsSL https://raw.githubusercontent.com/h5i-dev/h5i/main/install.sh | sh
# cargo install --path .          # or build from source

h5i plugin list                   # see what's actually installed

Don’t skip the plugins. With core alone, none of the websec / recon commands in SKILL.md exist.

Hand the skill to your agent

1
2
3

npx skills add h5i-dev/h5i        # when you don't have the binary yet
# or, with the binary present:
h5i skill install                 # writes it where your runtime looks

Then say this in your agent harness: “Audit https://.com with h5i.”

Sandbox and dashboard

1
2

h5i box --name review             # create a box when you need containment
h5i ui                            # local dashboard for browser and session activity

The authorization line (SKILL.md’s scope section)

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

Authorized targets only; widening any of origin / identity / rate / scope requires approval first. The tool provides capture, replay and evidence. Judging vulnerabilities and staying in bounds is your responsibility — it says so plainly, so don’t pretend you didn’t see it.

7. Limits and Risks

1. The learning curve is steep, and deliberately so.
It’s optimized for agents, not for GUI users. On your first pass, read all of SKILL.md’s “Scope is the discipline” and “The loop,” then the reference pages for what you’re about to use. Don’t guess flags — the skill itself says “Use h5i <command> --help before guessing flags.”

2. The proof side has a precondition.
It covers only the h5i-app kernel. Before you bring formal verification to an existing backend, price the rewrite; don’t get pulled in by the slogan “Formally verify properties of Rust codes.”

3. macOS and --ignore-https-errors.
See 4.2③. When you use the Chromium-proxy session, know that the channel doesn’t validate certificates.

4. The evidence store holds full credentials.
See 4.2④. Mind where it lives and who can read it. Promotion into a project strips credentials; the live session does not.

5. The caller is an agent, so interface drift has no compiler to catch it.
See 4.2⑤. CLI semantics, box lifecycle and the finding schema are all moving, while the command strings in your skill / prompts / CI won’t fail loudly — they’ll just go wrong. Pin versions and rerun the loop after upgrading.

6. It doesn’t judge vulnerabilities for you.
No rule base, no “scan out a CVE.” If you want an automated verdict stream, pair it with issue 013 garak (LLM probes) or issue 012 Vigolium (rule-based scanning). h5i’s job is operating on the target, auditably.

8. Getting Started (In This Order)

1. Read SKILL.md’s “Scope is the discipline” first, then “The loop.” These two sections decide whether you produce hallucinated reports. Reading them saves more time than running blind.
2. Install with --websec --recon --test. Missing plugins is the number-one cause of “this tool doesn’t work.”
3. Run the whole loop against a small target you’re authorized to test: browser open --capture → recon extract/known/crawl → websec requests/replay/diff → finding create --evidence .... Feel how the message id pins a conclusion back to bytes.
4. Create a box when you need containment, and make h5i box capabilities <name> --json a habit — don’t guess the enforcement level.
5. Always land findings with finding create, then project finding promote + project report before the session ends. Don’t let conclusions live only in the conversation.
6. Copy the SKILL.md clauses into your own agent guidelines. Even if you never touch h5i, “No complete PoC, no vulnerability,” “a denial is a policy result,” and “hunt two false positives before reporting” pay for themselves.
7. Approach formal verification through the calculator tutorial (examples/app/calculator/TUTORIAL.md). Understand the constraint — kernel is a pure function, handlers never touch the DB — before you decide whether to migrate a backend.
8. Don’t hand it to humans as a Burp replacement. Colleagues who need interactive GUI capture should keep using Burp / Caido. h5i is the layer for agents.

9. One-Line Verdict

h5i isn’t another AI scanner. It rebuilds the Burp/Caido layer — driving pages, capturing and replaying traffic — as an agent-native workbench, and bolts on half a Lean 4 formal-verification framework. It is concept-dense, offers no human GUI, its proof side only reaches its own framework, and its interface is still moving through 0.x. What’s genuinely scarce is the SKILL.md compiled into the binary: the message-id evidence chain, No complete PoC, no vulnerability, a denial is a policy result, never disable a hook from inside a box. It turns “how an agent must behave when testing security” into hard clauses shipped with the tool — and no public project does that as thoroughly.

Your one action: install with --websec --recon --test → read the discipline section of SKILL.md twice → run browser → recon → websec → finding once against a target you’re authorized to test → create a box when you need containment and confirm the enforcement level with capabilities --json. Even if you never point it at a target, those clauses are worth copying into your own agent security guidelines — the best part of h5i isn’t the feature set, it’s the insistence that an agent learn what evidence means before it touches anything.