# Fuzzing Non-Foundry Projects

{% hint style="info" %}
**Don't have an account?** To start Fuzzing, an account is required. Don't miss out and  [create one](/master.md) in less than a minute!🚀
{% endhint %}

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

<figure><img src="/files/G84sFgR5PzBtGF08KAAy" alt=""><figcaption><p>Preparing and submitting a campaign</p></figcaption></figure>

#### 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).&#x20;

#### Step 1: Install the tools and Configure the API Key <a href="#step-1-install-the-tools" id="step-1-install-the-tools"></a>

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](https://fuzzing.diligence.tools/keys).&#x20;

<figure><img src="/files/xKnAjb9eF4AUwWzPURFw" alt=""><figcaption><p>Creating an API Key</p></figcaption></figure>

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:&#x20;

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

#### Step 2: Generate the Fuzzing configuration <a href="#step-3-start-your-first-fuzzing-campaign" id="step-3-start-your-first-fuzzing-campaign"></a>

On all but[ Foundry projects](/getting-started/fuzzing-foundry-projects.md), 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.

<figure><img src="/files/FMaPIz8o1vbDnaKvTEMC" alt=""><figcaption><p>Auto  generating a fuzzing configuration file</p></figcaption></figure>

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:

{% embed url="<https://github.com/Consensys/diligence-fuzzing/blob/master/docs/configuration.md>" %}

#### Step 3: Annotating and Instrumenting with Scribble <a href="#step-3-start-your-first-fuzzing-campaign" id="step-3-start-your-first-fuzzing-campaign"></a>

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:

{% embed url="<https://docs.scribble.codes/tutorials/in-place-testing-with-scribble>" %}

{% content-ref url="/pages/rU3NpDQg87CqTUfwIj6w" %}
[Broken mention](broken://pages/rU3NpDQg87CqTUfwIj6w)
{% endcontent-ref %}

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

```
> fuzz arm
```

{% hint style="info" %}
To revert the arm command you can always run \`fuzz disarm\`
{% endhint %}

#### Step 4: Deploying the contracts locally <a href="#step-3-start-your-first-fuzzing-campaign" id="step-3-start-your-first-fuzzing-campaign"></a>

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.

{% tabs %}
{% tab title="Hardhat" %}

```bash
npx hardhat compile
npx hardhat node

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

{% endtab %}

{% tab title="Truffle" %}

```bash
truffle compile
truffle migrate # confirm that the default network is set to the ganache node
```

{% endtab %}

{% tab title="Brownie" %}

```bash
brownie compile
brownie networks add Ethereum ganache-local host=http://127.0.0.1:7545 chainid=5777
brownie run scripts/deploy.py --network ganache-local
```

{% endtab %}
{% endtabs %}

#### Step 5: Submit the Campaign <a href="#step-1-install-the-tools" id="step-1-install-the-tools"></a>

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:

<figure><img src="/files/smvev4KnW3utJtR2aFbc" alt=""><figcaption></figcaption></figure>

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.

<figure><img src="/files/UdS8sEiTFNjIgviEV5qC" alt=""><figcaption></figcaption></figure>

To learn more about reports, check out this guide:

{% content-ref url="/pages/-MY4zpliqosQEdWUQMgd" %}
[Campaign Reports](/general/reports.md)
{% endcontent-ref %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://fuzzing-docs.diligence.tools/getting-started/fuzzing-non-foundry-projects.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.