Comment on page
Fuzzing Non-Foundry Projects
Get started with fuzzing in a few minutes with Truffle, Hardhat, Brownie and Dapptools.
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
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).
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
Creating an API Key
After generating the api key, the easiest way to configure it is by adding it to a
.envfile, which the cli will automatically read from. From the project's root directory run:
echo FUZZ_API_KEY='your api key here' > .env
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.ymlfile 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:
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:
> fuzz arm
To revert the arm command you can always run `fuzz disarm`
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.
npx hardhat compile
npx hardhat node
# then, on a separate terminal
npx hardhat run --network localhost scripts/deploy.ts
truffle migrate # confirm that the default network is set to the ganache node
brownie networks add Ethereum ganache-local host=http://127.0.0.1:7545 chainid=5777
brownie run scripts/deploy.py --network ganache-local
With the instrumented contract deployed, you are ready to submit the fuzzing campaign. To do so, simply run:
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: