Fuzzing Solidity Smart Contracts Using Foundry: A Practical Guide

In contest environments, manual review tends to capture more reward than fuzzing bugs because manual bugs can be esoteric and subjective - some researchers recognize vulnerabilities while others don't. Fuzzing bugs are more objective as they can be consistently reproduced. To become an effective fuzzer, researchers should focus on learning tools (Echidna, Medusa, Foundry) and mastering invariant formulation, which is considered the most critical skill. Mastering these two areas can get a researcher approximately 70% of the way to becoming a top performer.

Stateful fuzzing differs from stateless fuzzing by testing multiple smart contract calls with randomized inputs and running assertions on top of contracts. The Chimera framework enables developers to write tests once with Foundry and run multiple specialized tools (Echidna, Medusa, Halmos) on the same tests. The framework separates target functions (contract entry points), properties (test assertions), and setup (contract deployment). Smart contract fuzzing differs from web2 fuzzing because tools lack native support for nested dependencies. When fuzzing complex systems like Uniswap pools, developers must deploy multiple contracts before reaching meaningful states. The Recon extension addresses this through actor managers and asset managers that abstract away the complexity of managing multiple contracts. Coverage in fuzzing refers to the ability to explore as many combinations as possible by covering every possible branch and line of the smart contract. Echidna operates in exploration mode, ignoring assertions to maximize state space exploration and build a corpus of successful call sequences. The coverage report shows green lines (executed) and red lines (not executed). Fail mode and catch mode are essential testing techniques: catch mode is used for functions that should never fail, while fail mode places assertion failures after handlers to trigger failures once the fuzzer finds successful calls.

Medusa is a parallel fuzzing tool from Trail of Bits that reuses Echidna test configurations, enabling faster and more efficient smart contract testing with clear, color-coded logs; to set it up, clone the repository, build with Go, add the binary to your PATH, configure the Medusa JSON file with appropriate settings (assertion testing true/false, property testing true/false), and run the tool to execute tests with multiple workers for improved performance.

Google launched Fuzz Bench as a fully automated open-source service for evaluating fuzzers. The platform addresses challenges in fuzzing research by providing reproducible evaluations that compare fuzzer performance across many trials and real-world benchmarks. Integrating a new fuzzer with Fuzz Bench requires less than 50 lines of Python code, and once integrated, fuzzers can test almost 250+ open-source fuzz projects out of the box. The platform already supports 10 fuzzers including AFL, Honggfuzz, and academic projects. Reports include statistical tests to determine whether performance differences between fuzzers are statistically significant rather than due to chance. Performance is measured primarily by the amount of program edges covered, with plans to add crash detection as a metric. This enables researchers to focus on improving techniques rather than setting up evaluation infrastructure.

Evaluating fuzzers requires measuring overlap (defects found by both tools) and effectiveness (defects per time unit). Comparing against tools integrated into development processes (like JSFuzz in Firefox) demands careful experimental setup: mining version control to identify testing windows before any bug fixes by the existing tool, then performing bisection to determine where bugs were introduced. This ensures fair comparison without bias toward the new tool's results.

Formal verification fundamentally differs from fuzz testing by mathematically representing the entire input range rather than sampling random cases. Tools like Halmos use cheat codes (svm.createUint256, etc.) to symbolically represent all possible values, enabling exhaustive property checking. The setup function initializes contracts before tests, while VM.assume filters impossible inputs. Low-level calls are essential for detecting reverts during external contract calls. Assert statements define properties that must hold; Halmos focuses on panic errors by default. Compiler versions >= 0.8.0 with proper panic handling are required. Loop unrolling bounds control exploration depth—the default of 2 may miss complex vulnerabilities, requiring increases to 256+ for thorough analysis.

Certora Prover is a formal verification tool that mathematically proves smart contract properties by taking contract code and specification files written in CVL (Certora Verification Language), then producing one of three outcomes: a mathematical proof of correctness, a counterexample showing a violation, or a timeout. The tool requires Python 3.8+, JDK 11+, and Solidity compiler, and uses a cloud-based dashboard for monitoring verification jobs. CVL specifications define properties like 'transfer doesn't revert' using unconstrained variables and required statements to model transaction scenarios, enabling developers to mathematically verify that critical security properties hold across all possible execution paths.

This course teaches how the Solidity compiler translates high-level code into EVM opcodes, and how to write smart contracts directly using Assembly and Yul. Learners will gain hands-on experience in low-level Ethereum Virtual Machine programming by constructing contracts in Assembly. The curriculum includes building three practical projects: a Horse Store, Math Masters, and a Gas-Optimized NFT Marketplace. Beyond writing code, the course covers formal verification techniques to mathematically prove that contract invariants hold under all conditions. Tools such as Certora and Halmos are introduced and used to write formal verification tests that ensure correctness and security properties of the deployed contracts. The course structure is divided into four sections, beginning with an introduction and progressing through increasingly complex contract implementations. Resources, code examples, and a support forum are provided via GitHub, and community discussions are hosted on GitHub Discussions and Discord. The instructor emphasizes practical application over theory, guiding learners through real-world contract development and verification workflows. The content assumes familiarity with Solidity and blockchain fundamentals, focusing on advanced topics in EVM internals and formal methods.

Formal verification mathematically proves smart contract correctness rather than testing. Three key truths: it finds bugs, proves properties like solvency, and doesn't require PhDs. The process translates Solidity and CDL specs into logical formulas, then uses solvers to find counterexamples or prove properties. CDL uses mathematical integers (unbounded) to catch overflows, with 'assert' defining properties that must never fail. Specifications verify correctness for all possible contract states and input values.

Formal verification tools like Halmos use the same underlying logic as Foundry's test framework to prove that certain conditions are always true or false in smart contracts. Halmos automatically generates test cases that attempt to fail the contract, making it easier to understand and reproduce vulnerabilities. The tool is pre-installed in the toolbox, eliminating separate installation. Testing tools like Medusa and Foundry's test framework allow auditors to write tests using familiar Solidity syntax, with Halmos providing formal verification capabilities.

Implementing continuous fuzzing involves four key steps: (1) Write a fuzz target function within the package being tested that takes byte input and returns 1 for valid inputs or 0 for invalid ones; (2) Manually gather and prepare an initial seed corpus of diverse valid inputs; (3) Set up Fuzzit account and configure targets; (4) Create integration scripts that call Gophers with Libfuzzer options and trigger Fuzzit jobs. In CI platforms like TeamCity, add steps to run both local regression jobs (checking current PR against corpus) and long-running fuzzing jobs (continuously testing for crashes). Every PR submission triggers this workflow, ensuring code quality through automated, expanding test coverage.

This section demonstrates practical fuzzing integration through a VS Code plugin. The plugin interacts with a backend using gRPC and requires only knowing how to build the project. It generates fuzz target templates with all necessary includes automatically resolved using a compilation database that tracks dependencies. Developers write code that calls the API with generated inputs. Configuration includes runtime settings like run duration and fuzzer selection. The plugin builds projects with instrumentation automatically. When crashes are found, the fuzzer reports code coverage, concrete inputs, and stack traces. Debugging features allow developers to click on crashes and automatically start debuggers with stack traces, making bug analysis much easier. For CI integration, developers configure which system to use (e.g., GitLab CI), select test collections, and specify notifications. The plugin generates CI configuration files that automatically run fuzzing on each commit. Fuzzers run in Docker containers within Kubernetes clusters, storing seed corpus in shared storage for reuse across runs.

The complete fuzzing integration workflow involves: initial setup, triggering fuzzing on each commit, instrumenting code, generating reports, and analyzing bugs. A key advantage is that fuzzing provides concrete inputs that trigger bugs, enabling developers to start debugging sessions from the CI/CD pipeline with few clicks. The platform supports multiple CI tools including GitHub Actions, GitLab CI, and Jenkins, making it agnostic to specific CI solutions.

Integrating fuzzing into CI/CD pipelines requires balancing overhead with effectiveness. Coverage-based fuzzing generates valuable test cases that can be replayed in CI/CD without additional overhead, providing free regression testing while maintaining coverage. Fuzzing-generated test cases cover code paths that might not be tested by manual testing. A notable example is an SSH vulnerability where a regression test detected a data use-after-free issue introduced in a recent commit. Web browsers represent sophisticated fuzzing targets with extensive security measures including address sanitizers and memory sanitizers. Automated fuzzing tools like Domato can discover vulnerabilities persisting for extended periods, with one example finding 15 new CVEs a year after initial release. In-memory persistent fuzzing optimizes execution speed by keeping programs in memory between iterations, increasing rates from 10 to 1000+ executions per second. Differential fuzzing compares outputs of different implementations by feeding same random inputs and checking for differences. Snapshot fuzzing captures memory and register state before execution, restoring between iterations for rapid testing.

Configure GitHub Actions using YAML files in .github/workflows directory. Define workflows with jobs that run on specific events (push, pull_request). Use matrix strategies to test across multiple OS and Python versions concurrently. tox-gh-actions package bridges tox configurations with GitHub Actions environments, mapping GitHub's predefined runners to tox environment names. This enables automated testing on every commit and pull request.