🏎️Example Project
Get started with fuzzing in a few minutes with this example project
Hey there! As you navigate through this fuzzing guide, remember we value your feedback. If you encounter any difficulties, kindly share your experience in our "Fuzzing Frustrations? Let's Debug Your Experience" form. Thanks, and happy fuzzing!
This page will help you getting up to speed with Fuzzing in 4 simple steps:
Installing the tools
Getting an API key
Starting a fuzzing campaign
Exploring the report
Prerequisites - Truffle
This tutorial requires Truffle to be installed on your system.
While we're focusing on Truffle, note that the tool is also compatible with other popular smart contract development frameworks such as Foundry, Hardhat, and Brownie
If you don't already have Truffle installed, run:
This will install Truffle and make it available system-wide.
Step 1: Install the tools
First things first, you will need to install our Fuzzing CLI and Scribble. We like to use recent versions of node and python, so make sure you’re at least python 3.6 and node 16.
Step 2: Configure the API Key
With the tools installed, you will need to generate an API for the CLI. The API keys menu is accessible here.
After generating the api key, the easiest way to configure it is by adding it to a .env file, which the cli will automatically read from. From the project's root directory run:
Step 3: Start Your First Fuzzing Campaign
You can’t fuzz without a smart contract. We've prepared one just for you!
In this directory there is a configuration file .fuzz.yml. In it you will find all of the settings that you can tweak. You can have a look at it, but for this tutorial the default settings will work just fine!
Now, lets add a Scribble property that we want the fuzzer to check to contracts/vulnerableToken.sol:
It will make sure that the total supply and balances mapping are in sync!
That’s it! Run the following command to start fuzzing:
Step 4: Explore the Report
Now, it’s time to give the fuzzer a minute or two to start up.
☕️ This is a great time to stand up, give your legs a stretch, and look out of the window for a minute.
There are two ways to get to the fuzzing campaign results:
There is a link in the output of make fuzz that links directly to the results!
Go to fuzzing.diligence.tools and look at the current campaigns section, it will be right there!
Once you’ve arrived on the campaign report you’ll see a lot of things.
The most important is the property section, it shows you which properties are being fuzzed, and more importantly, which properties are violated.
When the campaign is still fresh it’ll tell you it hasn’t found any problems (yet). However, once the fuzzer has had some time it will find the property doesn’t hold.
The fuzzer found a bug! Go ahead and click one of the location buttons.
This navigates you right to the location in the code with the property check. Now you probably want to know why the fuzzer thinks that the property can be violated.
Go ahead and click “Show steps to reproduce”. It shows us the fuzzer called transfer to trigger this violation.
Now click “show full data” right next to the transfer call. It will show you more information on the call that the fuzzer did to trigger the violation.
Notice something odd?
The origin and transfer _to arguments are the same! In other words, there is a vulnerability when someone sends tokens to themselves!
Go ahead and look in vulnerableERC20.sol to see if you can figure out what’s going wrong!
⚠️ Be sure to stop your fuzzing campaigns on time! Or set a time limit to be sure!
🎉 Finished! Congratulations for completing your first campaign!
Did everything go smoothly or did you hit some bumps along the way?
We'd really appreciate your feedback. If you've got a few spare minutes, please fill out this "Fuzzing Frustrations? Let's Debug Your Experience" form. It will help us identify any tricky spots and improve the guide for future users.
Thanks in advance for your help!
Last updated
