🍎Fuzzing Non-Foundry Projects
Get started with fuzzing in a few minutes with Truffle, Hardhat, Brownie and Dapptools.
Don't have an account? To start Fuzzing, an account is required. Don't miss out and create one in less than a minute!🚀
This page will help you getting up to speed with Fuzzing in 5 simple steps:
Installing the tools and Configure the API Key
Generating the Fuzzing configuration
Annotating and Instrumenting with Scribble
Deploying the contracts
Submitting the Campaign
Prerequisites - Ethereum Project
Before getting started, ensure that you have a Truffle, Hardhat, Brownie, or Dapptools project that compiles successfully and has a can be deployed to a local node (such as Ganache or Hardhat).
Step 1: Install the tools and Configure the API Key
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.
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 2: Generate the Fuzzing configuration
On all but Foundry projects, a configuration file is required. The CLI can automatically generate a configuration file, by running fuzz config generate. You will then be guided through a process to get you going.
The fuzz config generate command will do its best to detect the framework you're using, find the sources and build directory and set some up parameters. You can then manually tweak the .fuzz.yml file to add or change any parameters.
You can also inspect the contents of the file with the command
Many of these parameters can be set through config parameters on the cli or through environment variables. An extensive list of the available settings can be found here:
Step 3: Annotating and Instrumenting with Scribble
Instrumentation is a crucial step in preparing your project for fuzzing. Modify the project's Solidity code by incorporating the necessary annotations using the Scribble language. These annotations define properties and invariants that specify desired behaviors or security properties of the contract. By annotating the code, you enable Diligence Fuzzing to verify these properties during the fuzzing campaign.
Here are some articles to get you started:
After annotating your contracts with Scribble, it's time to instrument them:
To revert the arm command you can always run `fuzz disarm`
Step 4: Deploying the contracts locally
Once the instrumentation is complete, compile and deploy the instrumented Solidity code using the chosen framework's compiler. Deploy the contract to a test network or a local blockchain environment like Ganache or Hardhat. This step sets up the environment for executing the fuzzing campaign.
Step 5: Submit the Campaign
With the instrumented contract deployed, you are ready to submit the fuzzing campaign. To do so, simply run:
Final Step: 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. Here's a sample report:
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.
To learn more about reports, check out this guide:
Last updated
