Skip to main content

​
What it is

Ultrafuzz is an open-source tool from the Monad Foundation security team that points a swarm of AI agents at your Solidity repo. The agents map your actors and flows, write down the properties your contracts should hold, hunt for bugs, and write fuzz tests. When they finish, Ultrafuzz gives you a deduplicated, triaged report. Ultrafuzz finds different bugs than a manual read or an AI scan. In the pilot, three runs surfaced 27 issues, from Low to High, in a protocol that had already been through several AI security scans. The best time to run it is once your core contracts stop changing and before you deploy.

​
Before you start

Never run Ultrafuzz on your laptop. Its agents run with all permission checks off: they can run any command, read any file your user can, and use the network. If your deployer key, seed phrase, or .env is on that machine, assume an agent can read it. See the security docs.
  1. Spin up a throwaway cloud VM. Ubuntu, 8+ vCPUs, 16+ GB RAM. Clone your repo onto it. Put no wallet keys or production secrets on it, and delete the VM when you’re done.
  2. Use a fresh API key with a spend cap. Create a new OpenAI API key (the default agent is Codex) and set a hard monthly limit in the provider dashboard. If you use Claude Code with an Anthropic API key instead, do the same in the Anthropic Console. Check spend mid-run with ultrafuzz stats <run-id>, and revoke the key after the run.
  3. Install the toolchain (or let your agent do it; see Run it): Git, Node.js 22.19+, pnpm 11.1.1, Bun 1.3+, Foundry, and the Codex or Claude Code CLI. See the prerequisites.
  4. Freeze your contracts first. Run it once your core contracts are stable. Findings on code you’re still rewriting go stale quickly.
Budget. One full-depth campaign in the pilot cost about $150 with gpt-5.5 at xhigh reasoning and took about 4 hours. The low-cost profile runs one strategy pass instead of two, with fewer agents in parallel and no retries, so expect a fraction of that. The smoke profile is cheaper still, but it is meant for checking that your setup works, not for an audit.

​
Run it: paste this into your agent

On the VM, open Codex or Claude Code in your project folder and paste:
Prefer to drive it yourself? The First Campaign tutorial has every command. The short version is init → validate → references sync → run → report.

​
While it runs

A campaign runs in four stages: setup (it maps your actors, flows, and Foundry harness), properties (what should always hold), strategies (20+ specialized bug hunts), and review (dedupe, a judging panel, severity, final report). Expect it to run for hours, so start it at the end of your day and check back. If the provider hits a quota limit, the run pauses instead of failing. Raise the limit or wait, then run ultrafuzz resume <run-id>.

​
Reading the report

Open it with ultrafuzz report <run-id>. The file is at .ultrafuzz/runs/<run-id>/artifacts/final-report/report.md. Treat every finding as a lead, not a verdict.
  1. Check whether it’s real. A false positive here usually means the generated test is wrong, not your contract. Read the failing test and ask whether a real user or attacker could reach that state.
  2. Don’t dismiss Lows. Many Lows flag behavior your docs never pinned down. Either fix them or write down the intended behavior.
  3. Fix in your own code. Ultrafuzz never edits your contracts. To keep a useful generated test, preview it with ultrafuzz materialize <run-id> --dry-run --copy <src>:<dest>, then rerun without --dry-run and with --confirm, and review the git diff.
  4. Run it again if you have time. Each run samples different bugs. In the pilot, the unique findings went from 11 after one run to 27 after three.

​
Docs and help