diligence-fuzzing 0.13.1

A command line interface for the Diligence Fuzzing API

A CLI for the Diligence Fuzzing API

This package aims to provide a simple to use command line interface for the 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 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 have everything you need to make the most of the Diligence Fuzzing tool.

Table of Contents

• Installing
• Basic Usage
  • Arm contracts
  • Disarm contracts
  • Smart Mode
  • Manual Mode
  • Foundry Tests
• Configuration
• Commands
• Product Analytics Collection

Installing

The Diligence Fuzzing CLI runs on Python 3.8+, including PyPy.

Linux and macOS

To get started, simply run

$ pip3 install diligence-fuzzing

Alternatively, clone the repository and run

$ pip3 install .

Or directly through Python's :code:setuptools:

$ 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 for CLI's dependencies compilation
2. Run the following command to install the CLI

$ pip3 install diligence-fuzzing

Alternatively, clone the repository and run

$ pip3 install .

Or directly through Python's :code:setuptools:

$ 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.

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

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 or Manual Mode.

You can also use the fuzz disarm command 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:

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:

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:

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:

    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:

    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:

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:

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:

   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 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 documentation for more information.

• Free software: Apache 2 license

History

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.