Unleashing Medusa: Fast and scalable smart contract fuzzing

Josselin Feist, Anish Naik

February 14, 2025

Page content

The wait is over—we’re thrilled to introduce Medusa v1, a cutting-edge fuzzing framework designed to enhance smart contract security. Medusa is based on our first fuzzer, Echidna, and our experience performing countless security reviews on blockchain systems. With features that make fuzzing more scalable and efficient, Medusa represents a significant leap forward in how developers and security engineers approach smart contract fuzzing.

What is Medusa?

Medusa is an open-source EVM-based fuzzer built on top of Geth. Our first major release introduces powerful features that make fuzzing efficient and scalable:

Coverage-guided fuzzing: Enables efficient contract exploration and provides direct feedback via an HTML report
Parallel fuzzing: Scales seamlessly with your hardware to speed up fuzzing campaigns
Smart mutational value generation: Leverages runtime values and insights from Slither to optimize fuzzing inputs
On-chain fuzzing: Seeds the fuzzing state with values fetched directly from the blockchain, improving real-world vulnerability discovery
Enhanced debugging capabilities: Provides rich execution traces and advanced reporting capabilities for greater insight into the fuzzer’s execution

Medusa represents the state of the art in smart contract fuzzing. We have dedicated significant effort to ensure it is powerful and easy to use.

Using Medusa

Getting started with Medusa is simple:

Install Medusa on macOS via Homebrew:
```
brew install medusa
```
For information on precompiled binaries and custom builds, visit our installation page.
Initialize a new project by running this command:
```
medusa init
```
This command generates a medusa.json configuration file to tweak the fuzzing runs.
Start fuzzing with this command:
```
medusa fuzz
```

For detailed documentation, visit the Medusa page on our Building Secure Contracts website. You can also watch our fuzzing workshop and our Uniswap v4 invariant walkthrough next week (date and time will be announced on X) to learn how to write robust invariants.

What about Echidna?

With Medusa, we are exploring a new EVM implementation and language for smart contract fuzzing. While Echidna has been a powerful fuzzer, Medusa offers distinct advantages:

Written in Go: This improves Medusa’s maintainability and allows for a native API, facilitating its integration into other projects.
Built on Geth: This ensures strong EVM equivalence and eases code maintenance for Medusa.

To validate Medusa’s performance, we conducted an extensive internal benchmark against Echidna, fine-tuning Medusa’s value generation to ensure it delivers optimal results. For example, the following figure shows our benchmark’s output, where Medusa (dotted line) and Echidna (straight line) perform similarly in terms of coverage and corpus size:

Figure 1: Internal Echidna versus Medusa benchmark

While we will continue maintaining Echidna for minor bug fixes, our primary focus now shifts to Medusa’s evolution.

The future of smart contract security

Fuzzing is a critical technique in smart contract security, and with Medusa, we aim to make this technique the industry standard. By providing powerful heuristics, parallel execution, and on-chain insights, Medusa makes smart contract fuzzing more scalable and accessible than ever before, empowering developers to identify vulnerabilities faster and more effectively.

We invite you to join our community and help shape Medusa’s future:

Contribute on GitHub: Improve Medusa’s capabilities by submitting issues, PRs, or feedback.
Join our Slack: Connect with other security researchers and developers to share insights and best practices.