🍎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:

1. Installing the tools and Configure the API Key

2. Generating the Fuzzing configuration

3. Annotating and Instrumenting with Scribble

4. Deploying the contracts

5. Submitting the Campaign

Preparing and submitting a 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.

pip3 install diligence-fuzzing
npm i -g eth-scribble ganache

With the tools installed, you will need to generate an API for the CLI. The API keys menu is accessible here.

Creating an API Key

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:

echo FUZZ_API_KEY='your api key here' > .env

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.

Auto generating a fuzzing configuration file

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

fuzz config show

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:

diligence-fuzzing/docs/configuration.md at master · ConsenSysDiligence/diligence-fuzzingGitHub

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:

In-place testing with Scribble | Scribbledocs.scribble.codes

After annotating your contracts with Scribble, it's time to instrument them:

> fuzz arm

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.

Hardhat

npx hardhat compile
npx hardhat node

# then, on a separate terminal
npx hardhat run --network localhost scripts/deploy.ts

Truffle

Brownie

Step 5: Submit the Campaign

With the instrumented contract deployed, you are ready to submit the fuzzing campaign. To do so, simply run:

fuzz 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:

1. There is a link in the output of make fuzz that links directly to the results!

2. 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:

📄Campaign Reports