diligence-fuzzing 0.13.4
A command line interface for the Diligence Fuzzing API
License: Apache-2.0 License
Requires Python: <4,>=3.8
Keywords: diligence-fuzzing

# A CLI for the Diligence Fuzzing API
This package aims to provide a simple to use command line interface for the [Diligence Fuzzing](https://consensys.net/diligence/fuzzing/) smart contract
security analysis API.

# What is Diligence Fuzzing?
Easy to use and powerful, Fuzzing as a Service enables users to find bugs immediately after writing their first specification!
Smart contracts are increasingly complex programs that often hold and manage large amounts of assets. Developers should use tools to analyze their smart contracts before deploying them to find vulnerabilities open to exploitation.

# Getting Started
If you're new to the Diligence Fuzzing tool or want to learn more about its capabilities, the 📚 [Fuzzing Docs](https://fuzzing-docs.diligence.tools/) is a great resource to get started.

These docs contain detailed instructions on how to configure the tool, best practices for integrating it into your development workflow, and more. You'll also find sample projects to help you test the Fuzzing CLI and get up to speed quickly. Whether you're just starting out or an experienced user, the 📚 [Fuzzing Docs](https://fuzzing-docs.diligence.tools/) have everything you need to make the most of the Diligence Fuzzing tool.

Table of Contents
=================

  - [Installing](#installing)
  - [Basic Usage](#basic-usage)
    - [Arm contracts](#arm-contracts)
    - [Disarm contracts](#disarm-contracts)
    - [Smart Mode](#smart-mode)
    - [Manual Mode](#manual-mode)
    - [Foundry Tests](#foundry-tests)
  - [Configuration](#configuration)
  - [Commands](#commands)
  - [Product Analytics Collection](#product-analytics-collection)

## Installing
The Diligence Fuzzing CLI runs on Python 3.8+, including PyPy.
### Linux and macOS
To get started, simply run

```console
$ pip3 install diligence-fuzzing
```

Alternatively, clone the repository and run

```console
$ pip3 install .
```
Or directly through Python's :code:`setuptools`:
```console
$ python3 setup.py install
```
> Don't forget to add the directory containing the `fuzz` executable to your system's PATH environment variable.

### Windows
> We recommend using Windows Subsystem for Linux (WSL) for a better experience
1. Install [Visual Studio Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/) for CLI's dependencies compilation
2. Run the following command to install the CLI
```console
$ pip3 install diligence-fuzzing
```

Alternatively, clone the repository and run

```console
$ pip3 install .
```
Or directly through Python's :code:`setuptools`:
```console
$ python3 setup.py install
```
> Don't forget to add the directory containing the `fuzz` executable to your system's PATH environment variable.

# Basic Usage
Fuzz is a command-line tool for smart contract fuzzing. It provides several modes of fuzzing, including smart mode, manual mode, and Foundry tests fuzzing.

## Create a configuration file

To automatically generate a configuration file run `fuzz config generate`. You will then be guided through a process to get you going.

## Arm contracts

`fuzz arm` is a command in the Diligence Fuzzing Toolset that instruments Solidity code with Scribble, a runtime verification tool, for property-based testing. This command runs `scribble --arm ...` on the given target files, instrumenting their code in-place with Scribble.

### 1. Annotate contracts

Before running `fuzz arm`, you need to annotate some code in a Solidity file using Scribble annotations. Here is an example:

   ```
   /// #if_succeeds {:msg "Transfer does not modify the sum of balances" } old(_balances[_to]) + old(_balances[msg.sender]) == _balances[_to] + _balances[msg.sender];
   function transfer(address _to, uint256 _value) external returns (bool) {
       ...
   }
   ```

   For more information on Scribble annotations, please refer to the [Scribble exercise repository](https://github.com/ConsenSys/scribble-exercise-1).


### 2. Running the Command

Run the `fuzz arm` command, followed by the path to the target file(s) or directory(ies).

   ```
   fuzz arm path/to/target_file.sol path/to/another_target_file.sol path/to/contracts
   ```
   > You can also provide targets in the [Config](#configuration)

The `fuzz arm` command will instrument the target file(s) with Scribble in-place, creating a backup of the original file(s) in a `.original` file.

### 3. Fuzz
Once you have run `fuzz arm` and have completed the testing process, you can fuzz the annotated contracts using either [Smart Mode](#smart-mode) or [Manual Mode](#manual-mode).

> You can also use the [`fuzz disarm` command](#disarm-contracts) to revert the target file(s) to their original, un-instrumented state.

## Disarm contracts

The `fuzz disarm` command reverts the target files to their original, un-instrumented state using the Scribble tool for Solidity runtime verification.

To run `fuzz disarm`, you should:

1. Have previously run the `fuzz arm` command on the target files.

2. Navigate to the directory where the target files are located.

3. Run the following command:

   ```
   fuzz disarm <target_files>
   ```

   Replace `<target_files>` with the path to the Solidity files that you want to revert to their original state.

   **Note:** If you do not provide any target files, the `fuzz disarm` command will run on all Solidity files in the current directory and its subdirectories.

After running `fuzz disarm`, the target files will be reverted to their original, un-instrumented state.

## Smart Mode

In this mode, fuzzing cli automatically collects all contracts in your project and submits campaigns to the Fuzzing API. To use smart mode, follow these steps:

### 1. Deploy Contracts

After installing `diligence-fuzzing`, you need to deploy your contracts to the RPC node. Depending on your IDE, there are different ways to deploy contracts. Here are some resources for different IDEs:

- Truffle: https://www.trufflesuite.com/docs/truffle/getting-started/running-migrations
- Dapptools: https://dapphub.com/guides/brownie-fundamentals/deploy-a-contract/
- Hardhat: https://hardhat.org/tutorial/deploying-to-a-live-network.html
- Brownie: https://eth-brownie.readthedocs.io/en/latest/deployment.html#deploying-to-a-public-network
- Foundry: https://docs.foundry.build/foundry-cli/#deploying-a-contract

### 2. Set API Key

To use Fuzz, you need to obtain an API key from https://consensys.net/diligence/fuzzing/. Once you have obtained an API key, you need to set it as an environment variable:

```bash
export FUZZ_API_KEY=<your_api_key>
```

### 3. Enable Smart Mode

Smart Mode will be enabled by default when you use the configuration generator. To enable Smart Mode manually, you need to set the `SMART_MODE` environment variable:

```bash
export FUZZ_SMART_MODE=1
```

For more information on Smart Mode and its configuration options, refer to the documentation.

### 4. Run Fuzz

Once you have deployed your contracts and set the appropriate environment variables, you can use `fuzz run` to start fuzzing your contracts:

```bash
fuzz run
```

## Manual Mode

Manual Mode is the default mode for Fuzz. Manual mode requires you to specify the target contracts and the addresses of the contracts under test. This mode can be useful if you want to fuzz specific contracts and test them against specific addresses. To use manual mode, follow these steps:

### 1. Deploy Contracts

You need to deploy your contracts to the RPC node. Depending on your IDE, there are different ways to deploy contracts. Here are some resources for different IDEs:

- Truffle: https://www.trufflesuite.com/docs/truffle/getting-started/running-migrations
- Dapptools: https://dapphub.com/guides/brownie-fundamentals/deploy-a-contract/
- Hardhat: https://hardhat.org/tutorial/deploying-to-a-live-network.html
- Brownie: https://eth-brownie.readthedocs.io/en/latest/deployment.html#deploying-to-a-public-network
- Foundry: https://docs.foundry.build/foundry-cli/#deploying-a-contract

### 2. Configure targets
First, you need to specify the targets for fuzzing. The targets are the source file paths of the contracts to be fuzzed. For example,
you can specify the targets in a YAML file:

```yaml
    fuzz:
      targets:
        - contracts/MyContract.sol
        - contracts/MyOtherContract.sol
```

### 3. Configure addresses under test
Second, you need to specify the addresses of the contracts under test. The addresses are the addresses of the deployed contracts on the RPC node. For example,
you can specify the addresses in a YAML file:

```yaml
    fuzz:
      deployed_contract_address: 0x1234567890123456789012345678901234567890
      additional_contracts_addresses:
        - 0x1234567890123456789012345678901234567890
        - 0x0987654321098765432109876543210987654321
```

### 4. Set API Key

To use Fuzz, you need to obtain an API key from https://consensys.net/diligence/fuzzing/. Once you have obtained an API key, you need to set it as an environment variable:

```bash
export FUZZ_API_KEY=<your_api_key>
```

For more information on Manual mode and its options, refer to the documentation.

### 5. Run Fuzz

Once you have deployed your contracts and set the appropriate environment variables, you can use `fuzz run` to start fuzzing your contracts:

```bash
fuzz run
```

## Foundry Tests

Fuzz provides a mode to automatically collect all Foundry unit tests from the project and submit a campaign without deploying them to the RPC node. To use the Foundry test fuzzing mode, follow these steps:

1. Set a `FUZZ_API_KEY` environment variable. You can obtain a free account from https://consensys.net/diligence/fuzzing/.
2. Navigate to the root directory of your project.
3. Run the following command:

   ```bash
   fuzz forge test
   ```

   This will automatically collect all Foundry unit tests from the project and submit a campaign without deploying them to the RPC node.

For more information on Foundry test fuzzing and its options, refer to the documentation.

## Configuration

The `fuzz` CLI tool allows configuration through 4 sources:

1. YAML config files
2. `.env` files
3. Environment variables
4. Command options

Consult the documentation for each command to learn about the available options.
For more information on `fuzz` configuration, refer to the [Configuration](docs/configuration.md) documentation.


## Commands
The `fuzz` CLI tool provides the following commands:
- `arm`: Prepares the target files for Diligence Fuzzing API submission.
- `auto`: Automatically annotates test contracts.
- `config`: Manages diligence-fuzzing configuration.
- `disarm`: Reverts the target files to their original, un-instrumented state.
- `forge`: Submits foundry unit tests to fuzzing.
- `lesson`: Manages fuzzing lessons.
- `run`: Submits contracts to the Diligence Fuzzing API.
- `version`: Shows diligence-fuzzing version.

Each command serves a specific purpose in the fuzzing process, and they can be used together to configure and execute fuzzing campaigns. For more information on each command, consult the corresponding documentation.

## Product Analytics Collection
This tool collects usage data to help us understand how the tool is being used and how we can improve it, but you can opt out of this data collection at any time.
Please have a look at the [Product Analytics Collection](docs/analytics.md) documentation for more information.

* Free software: Apache 2 license


# History

0.13.3 (2024-06-17)
--------------------
- Fix hardhat artifacts collection

0.13.2 (2024-06-17)
--------------------
- Fix hardhat artifacts collection

0.13.1 (2024-06-11)
--------------------
- Fix hardhat artifacts collection
- Add `output` option to `fuzz run --dry-run` command

0.13.0 (2024-06-04)
--------------------
- Add Windows support
- Drop support for Python 3.7
- Add support for Python 3.12

0.12.3 (2024-05-23)
--------------------
- Unlinked libraries detection for Foundry and Hardhat project
- Update checks for fuzzing cli. Now fuzzing cli will check for new versions and notify the user if a new version is available

0.12.2 (2024-04-23)
--------------------
- Fix hardhat artifacts collection
- Ignore library contracts by default

0.12.1 (2024-03-07)
--------------------
- Change `fuzz run` command behavior on contract targets absence (now it will emit warning instead of an error)
- Update documentation

0.12.0 (2024-03-04)
--------------------
- Analytics collection support
- Add new fuzzer options

0.11.3 (2023-08-28)
--------------------
- setUp method support for foundry tests
- Foundry profiles support
- Bump dependencies

0.11.2 (2023-05-17)
--------------------
- Add more verbose error messages
- Fix factory deployed contracts discovery

0.11.1 (2023-05-04)
--------------------
- Add config sources (.env, ENV variables, config file) parsing
- Add Foundry tests list to submitted campaign
- Fix foundry tests build arguments to include metadata
- Add Smart Mode and Auto Fixes to `fuzz`

0.11.0 (2023-04-07)
--------------------
- Make `no-assert` mode default for `fuzz arm` command
- Drop support for Python 3.6
- Update dependencies
- Fix various bugs
- Improve error messages
- Remove `key` parameter from fuzzing config. Only `FUZZ_API_KEY` environment variable or `--key` command line argument is supported now.
- Finalize Foundry seamless integration

0.10.2 (2023-02-13)
--------------------
- Fix quickcheck campaigns bug

0.10.1 (2023-02-13)
--------------------
- Add block data to transactions in corpus

0.10.0 (2023-02-13)
--------------------
- Add foundry unit tests submission command (`fuzz forge test`)
- Fix contracts searching logic to use both metadata hash comparison and the whole bytecode comparison
- Provide map-to-original-source flag to the backend

0.9.17 (2023-01-11)
--------------------
- Fix metadata hash collection

0.9.16 (2023-01-09)
--------------------
- Fix artifacts processing for `Hardhat` and `Foundry` which led to an error

0.9.15 (2022-11-16)
--------------------
- Add new fuzzer options

0.9.14 (2022-11-09)
--------------------
- Add `version` command
- Fix artifacts collection for `Foundry` and `Hardhat`

0.9.13 (2022-11-08)
--------------------
- Fix sources directory detection bug in `generate-config` command

0.9.12 (2022-11-02)
--------------------
- Add `Foundry` framework support

0.9.11 (2022-09-29)
--------------------
- Fix large stdout handling for truffle db queries

0.9.10 (2022-09-07)
--------------------
- Add support for fuzzing limits related response codes

0.9.9 (2022-08-25)
--------------------
- Fix project parameter passing

0.9.8 (2022-08-25)
--------------------
- Fix fuzzing lessons logic

0.9.7 (2022-08-24)
--------------------
- Add `quickcheck` campaigns support
- Add support for the incremental fuzzing
- Add support for fuzzing lessons
- Fix various bugs

0.9.6 (2022-04-13)
--------------------
- Add `time_limit` config option

0.9.5 (2022-04-05)
--------------------
- Add option to provide truffle executable path
- Add proper debugging to truffle errors
- Include raw results to an error output for truffle projects

0.9.4 (2022-03-11)
--------------------
- Improve error messages display
- Make `no-assert` default option on config generator
- Improve api error handling for better error messages on subscriptions

0.9.3 (2022-03-08)
--------------------
- Add no subscription error message
- Improve error message for free trial
- Remove short form of corpus-target parameter at `fuzz run`
- Add additional checks for a seed state generator
- Add `--no-assert` flag to `scribble arm` command

0.9.2 (2022-02-22)
--------------------
- Fix bugs

0.9.1 (2022-02-22)
--------------------
- Add `requests` dependency to requirements
- Fix various bugs

0.9.0 (2022-02-10)
--------------------
- Add `generate-config` command
- Improve development frameworks support
- Add `dapptools` framework support

0.8.2 (2022-01-19)
--------------------
- Fix `disarm` command related bugs

0.8.1 (2021-10-26)
--------------------
- Fix bugs
- Improve `Hardhat` support

0.7.2 (2019-09-13)
--------------------
- Add new format API Key support
- Add `project_name` config parameter

0.7.1 (2019-09-13)
--------------------
- Update Readme

0.6.22 (2021-08-20)
--------------------
- First release on PyPI.