# h5i

> h5i ("high-five") is an open-source red-teaming browser for AI agents. An agent drives a browser session by id, reads the page as an outline with @ref handles, and then works the traffic that session produced: read a captured message byte for byte, change one field, send it again, compare the answers. The engine is the HTTP client, so every request is checked against the session policy and written down before the bytes move, and a fetch that cannot be recorded is refused. A request that is not in the log did not happen. Replay travels that same path, so it is not a side channel around scope. Sessions run on the host by default with no containment claimed, and one flag places the same session inside a sandbox, which adds an egress allowlist enforced outside the browser. Use h5i only against systems you own or are explicitly authorized to test.

## Start here

- [Features](https://h5i.dev/features/): Product overview: automated browsing, reconnaissance, HTTP capture and editing, the limits you place around the agent, and the review surface.
- [Run an authorized web security test](https://h5i.dev/guides/authorized-web-security-testing/): Scope a session to one target, inventory its endpoints, replay one request, and close with the evidence intact.
- [Drive a browser session](https://h5i.dev/guides/drive-a-browser-session/): Open a session, read the page, act on it, and read back what it reached.
- [AI pentesting tools compared](https://h5i.dev/blog/ai-pentesting-tools/): Burp Suite, OWASP ZAP, Caido, and h5i, chosen by what you delegate to AI.
- [Manual](https://h5i.dev/manual/): Authoritative command, policy, receipt, and limitation reference.

## The web security tutorial

Ten articles that walk the 42 runnable labs in h5i-dev/h5i-tutorial, from recon to a complete exploit chain. Part 1 of the series is on Medium; these are the rest.

1. [Recon and IDOR](https://h5i.dev/guides/recon-and-idor/): Discover hidden endpoints, then test object-level authorization and why an unguessable URL is not an access control.
2. [Broken Access Control](https://h5i.dev/guides/broken-access-control/): Test authorization with the least privileged account you hold, and find the fields a user interface never sends.
3. [JWT Attacks](https://h5i.dev/guides/jwt-attacks/): alg confusion, a weak HMAC secret, and a key identifier turned into a path traversal.
4. [SQL Injection](https://h5i.dev/guides/sql-injection/): A union read, then boolean and timing oracles when the application reveals almost nothing.
5. [Injection Beyond SQL](https://h5i.dev/guides/injection-beyond-sql/): NoSQL operators, shell commands, server-side templates, XML entities, and second-order input.
6. [The Browser as a Weapon](https://h5i.dev/guides/browser-as-a-weapon/): Reflected and stored XSS, CSRF, CORS misconfiguration, and an OAuth redirect_uri leak.
7. [SSRF and File Attacks](https://h5i.dev/guides/ssrf-and-file-attacks/): Internal services, filter bypasses, encoded traversal, upload writes, and log poisoning.
8. [HTTP Protocol Attacks](https://h5i.dev/guides/http-protocol-attacks/): Request smuggling, CRLF injection, host header poisoning, cache poisoning, WebSocket frames.
9. [Business Logic, Time, and Crypto](https://h5i.dev/guides/logic-time-and-crypto/): Races, coupon stacking, predictable tokens, length extension, MFA state, and a pickled cookie.
10. [Building Exploit Chains](https://h5i.dev/guides/exploit-chains/): Carry fresh values between requests and turn small findings into one reproducible compromise.
11. [Cheatsheet](https://h5i.dev/guides/cheatsheet/): The loop, every --set target, the replay flags, probe values by class, and how to read a sweep.

## Tool comparisons

- [AI pentesting tools: Burp Suite, ZAP, Caido, or h5i?](https://h5i.dev/blog/ai-pentesting-tools/): Four tools compared through AI-assisted manual testing, AI-authored scan automation, and agent-led investigation.
- [Burp Suite vs h5i for AI agents](https://h5i.dev/blog/burp-suite-vs-h5i-for-ai-agents/): A complete web-testing platform versus fully automated penetration testing driven by an external AI agent.
- [OWASP ZAP vs h5i for AI agents](https://h5i.dev/blog/owasp-zap-vs-h5i-for-ai-agents/): Automated DAST and scanner findings versus an AI agent that directs the complete testing loop.
- [Caido vs h5i for AI agents](https://h5i.dev/blog/caido-vs-h5i-for-ai-agents/): A full proxy workspace and agent API versus an external AI agent driving the investigation end to end.

## Design essays

- [Sandbox the entire workflow: browse, develop, review, apply](https://h5i.dev/blog/the-h5i-loop/): Put the browser, checkout, agent, tools, tests, and dev server in one box, then review the evidence before the patch crosses out.
- [Why sandbox the entire AI agent workload](https://h5i.dev/blog/the-environment-is-the-sandbox/): Coding tasks execute dependencies, build tools, tests, servers, and pages—not only the agent process.
- [How to choose an AI agent sandbox](https://h5i.dev/blog/choosing-agent-isolation/): Choose process, supervised, container, or microVM isolation by the failure it must prevent.
- [Review AI-generated code with execution evidence](https://h5i.dev/blog/evidence-for-agent-work/): Check the diff alongside observed test results, denied actions, browser errors, and explicit gaps in collection.
- [How to protect a coding agent from prompt injection](https://h5i.dev/blog/prompt-injection-is-a-boundary-problem/): Restrict host files, reusable credentials, network destinations, local sockets, browser state, and writes to the parent repository.

## The browser session

- A browser session holds one page state, one cookie jar, one request log, and one policy, addressed by an id.
- The engine is the HTTP client: policy first, record second, wire third. A fetch that cannot be recorded is refused.
- open grants the page it was given and nothing else remote. --allow names the origins beyond it, such as an API the page calls or a CDN it pulls from.
- An off-origin subresource is refused even though the page loaded, and the refusal is in the request log.
- Loopback is reachable by default because it is the dev server, and --no-loopback takes that back.
- A credentialed cross-origin request whose answer nobody can read is refused by default. --permissive-cors lifts that for one session, is part of its policy digest, and is named on the open banner and in status.
- Denials are recorded with their reason, so the log shows what was attempted and not only what succeeded.
- A redirect out of the allowlist is refused at the hop, not followed and explained afterwards.
- h5i browser audit merges verbs, fetch decisions, control handovers, and the ending into one ordered timeline.
- Every audit row carries its lane: the engine's own account, or what h5i observed from outside. They are never merged.
- An audit reports each source as read, empty, or unavailable, because an unwatched log is not a quiet session.
- A fetch carries caused_by naming the verb the page was under; links come from the source, never from timing.
- Snapshots arrive fenced as untrusted page content; escape sequences and control characters never reach the terminal.
- Relayed strings, arrays, and nesting are capped, and the truncation is stated in the value.
- Page JavaScript is off unless requested, which removes the page-borne injection delivery channel.
- Session states are live, closed, died, expired, evicted. A verb on a non-live session exits 69 and never restarts it.
- Session ids are never reused; --restore inherits storage into a new id and records the inheritance.
- Sessions live under $H5I_BROWSER_HOME or $XDG_STATE_HOME/h5i/browser, never under a git repository.
- The engine is pure Rust with no Chromium and no V8.

## The HTTP workbench

- websec is a plugin rather than part of the default build: h5i plugin install websec, or install.sh -s -- --websec.
- h5i websec requests, show --raw, replay --set, diff, match, and sitemap read and work the messages a session captured.
- Capture is opt-in with --capture, because the message store holds request and response bodies in full.
- The message store is never included in an export unless it is named.
- Replay goes through the same broker as browsing: the policy decides, the receipt is written first, and an off-scope replay is refused rather than sent.
- A replay cannot widen its session's allowlist. Changing scope means a new session with a new policy, which is a visible act.
- Hop-by-hop headers the client owns are recomputed, and an attempt to set them is reported as overridden rather than accepted silently.
- match exits 0 when the condition holds, 1 for a miss, and 2 when it could not look.
- h5i websec sitemap folds observed receipts into origins and endpoints, carrying methods, statuses, parameter names, and hit counts, with refused URLs listed apart. Disclosed but unvisited URLs are not in it.
- h5i browser rpc --stdio is the same verbs over one process, so a loop that sends hundreds of requests pays process startup once.

## The recon ledger

- recon is a plugin as well: h5i plugin install recon, or install.sh -s -- --recon.
- Discovery is kept apart from testing. Recon records what a target exposes and how it knows; calling a difference a vulnerability stays the agent's claim.
- Every endpoint carries a state: candidate, observed, confirmed, refused, or gone.
- candidate means something disclosed it and no request was ever sent. observed means a request answered, and the row names the message.
- confirmed means the answer differs from the calibrated missing-path baseline for that directory. It does not mean interesting.
- refused means policy declined it, and the row is kept, because that is a fact about the scope.
- Confirmation happens only in triage --calibrate, which learns what a missing path looks like in each directory. Against an application that answers 200 for everything, nothing is confirmed without it.
- recon extract reads what the session already fetched; recon known checks robots.txt, sitemap.xml, security.txt, and .well-known/openid-configuration.
- robots.txt is a source of candidates and not an authorisation oracle. Scope comes from policy.
- recon crawl walks the target under this session's login, bounded by --max-requests and --rate.
- h5i ships no wordlist: paths --wordlist takes a list you bring, and --reuse-words uses the words the session has already seen.
- recon import reads urls, katana, subfinder, httpx, or openapi output as candidates that stay candidates until an h5i request answers.
- Runs that spend requests are jobs, with jobs list, show, and resume. The ledger is written as a run goes, so a run that is killed keeps what it found.
- Recon sends through the engine's own verbs. There is no second HTTP client, no --all-origins, and no spawning of third-party security tools.

## The box

- A box is a complete disposable development environment for one agent.
- Five tiers: workspace, process, supervised, container, microvm.
- Explicit isolation requests fail closed; h5i never silently downgrades.
- supervised and microvm enforce egress at L3/L4. container uses an L7 proxy allowlist.
- engine-claimed is the engine's own fail-closed account. host-observed means a box boundary saw it too.
- A box upgrades the lane only when something outside the engine enforces egress; being boxed is not enough.
- The control lock is enforced for a boxed session, because every verb is carried in from the host, and advisory otherwise.
- Model credentials remain host-side and are injected by a runtime-scoped proxy.
- h5i box export produces patch.diff, report.md, and receipt.json, and writes browser/<id>.json for each session placed in the box.
- h5i is local-first, Apache-2.0, and requires no hosted sandbox or SaaS account.

## Honest limits

- h5i cannot grant authorization or infer scope from a URL. Record the permitted hosts, accounts, techniques, request rate, and time window before running an agent.
- h5i is not a vulnerability scanner. It ships no exploit library, payload generator, fingerprint database, or wordlist.
- Recon produces no verdicts and no severities. confirmed means distinguishable from the not-found baseline, nothing more.
- A response diff is evidence of a difference, not proof of impact. Severity and exploitability still require review.
- The capture store can hold credentials and personal data in full. Treat it as sensitive test evidence and redact it before sharing an artifact.
- With the default cross-origin refusal in force h5i cannot act as the victim, so a negative CSRF result means h5i declined, not that the target is safe.
- A session on the host is not sandboxed and h5i does not claim it is. Containment is the --in flag.
- The engine is not a complete browser: canvas, WebSockets, Workers, and IndexedDB are absent. Of twenty single-page applications measured, eighteen read usefully and one not at all.
- For a target the engine cannot read, run Chromium inside a box and accept the tier's boundary in place of engine-level capture.
- h5i does not classify page content. It bounds what a persuaded agent can reach rather than detecting persuasion.
- A boxed session needs a tier that can hold a resident process, and not every tier that enforces egress can.
- Containment cannot stop source code from being included in an allowed model request.
- Every tier below microvm shares the host kernel.
- Container egress scoping binds proxy-respecting software only.
- Box-claimed receipt data can be omitted or fabricated; h5i keeps it distinct from host-observed evidence.
- A local receipt is protected from the box, not notarized against the host owner.