Package: diligence-fuzzing
A CLI for the Diligence Fuzzing APIThis package aims to provide a simple to use command line interface for theDiligence Fuzzingsmart 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 StartedIf you're new to the Diligence Fuzzing tool or want to learn more about its capabilities, the 📚Fuzzing Docsis 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 Docshave everything you need to make the most of the Diligence Fuzzing tool.Table of ContentsInstallingBasic UsageArm contractsDisarm contractsSmart ModeManual ModeFoundry TestsConfigurationCommandsInstallingThe Diligence Fuzzing CLI runs on Python 3.7+, including PyPy.To get started, simply run$pip3installdiligence-fuzzingAlternatively, clone the repository and run$pip3install.Or directly through Python's :code:setuptools:$python3setup.pyinstallDon't forget to add the directory containing thefuzzexecutable to your system's PATH environment variable.Basic UsageFuzz 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 fileTo automatically generate a configuration file runfuzz config generate. You will then be guided through a process to get you going.Arm contractsfuzz armis a command in the Diligence Fuzzing Toolset that instruments Solidity code with Scribble, a runtime verification tool, for property-based testing. This command runsscribble --arm ...on the given target files, instrumenting their code in-place with Scribble.1. Annotate contractsBefore runningfuzz 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 theScribble exercise repository.2. Running the CommandRun thefuzz armcommand, 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/contractsYou can also provide targets in theConfigThefuzz armcommand will instrument the target file(s) with Scribble in-place, creating a backup of the original file(s) in a.originalfile.3. FuzzOnce you have runfuzz armand have completed the testing process, you can fuzz the annotated contracts using eitherSmart ModeorManual Mode.You can also use thefuzz disarmcommandto revert the target file(s) to their original, un-instrumented state.Disarm contractsThefuzz disarmcommand reverts the target files to their original, un-instrumented state using the Scribble tool for Solidity runtime verification.To runfuzz disarm, you should:Have previously run thefuzz armcommand on the target files.Navigate to the directory where the target files are located.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, thefuzz disarmcommand will run on all Solidity files in the current directory and its subdirectories.After runningfuzz disarm, the target files will be reverted to their original, un-instrumented state.Smart ModeIn 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 ContractsAfter installingdiligence-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-migrationsDapptools:https://dapphub.com/guides/brownie-fundamentals/deploy-a-contract/Hardhat:https://hardhat.org/tutorial/deploying-to-a-live-network.htmlBrownie:https://eth-brownie.readthedocs.io/en/latest/deployment.html#deploying-to-a-public-networkFoundry:https://docs.foundry.build/foundry-cli/#deploying-a-contract2. Set API KeyTo use Fuzz, you need to obtain an API key fromhttps://consensys.net/diligence/fuzzing/. Once you have obtained an API key, you need to set it as an environment variable:exportFUZZ_API_KEY=<your_api_key>3. Enable Smart ModeSmart Mode will be enabled by default when you use the configuration generator. To enable Smart Mode manually, you need to set theSMART_MODEenvironment variable:exportFUZZ_SMART_MODE=1For more information on Smart Mode and its configuration options, refer to the documentation.4. Run FuzzOnce you have deployed your contracts and set the appropriate environment variables, you can usefuzz runto start fuzzing your contracts:fuzzrunManual ModeManual 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 ContractsYou 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-migrationsDapptools:https://dapphub.com/guides/brownie-fundamentals/deploy-a-contract/Hardhat:https://hardhat.org/tutorial/deploying-to-a-live-network.htmlBrownie:https://eth-brownie.readthedocs.io/en/latest/deployment.html#deploying-to-a-public-networkFoundry:https://docs.foundry.build/foundry-cli/#deploying-a-contract2. Configure targetsFirst, 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.sol3. Configure addresses under testSecond, 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:0x1234567890123456789012345678901234567890additional_contracts_addresses:-0x1234567890123456789012345678901234567890-0x09876543210987654321098765432109876543214. Set API KeyTo use Fuzz, you need to obtain an API key fromhttps://consensys.net/diligence/fuzzing/. Once you have obtained an API key, you need to set it as an environment variable:exportFUZZ_API_KEY=<your_api_key>For more information on Manual mode and its options, refer to the documentation.5. Run FuzzOnce you have deployed your contracts and set the appropriate environment variables, you can usefuzz runto start fuzzing your contracts:fuzzrunFoundry TestsFuzz 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:Set aFUZZ_API_KEYenvironment variable. You can obtain a free account fromhttps://consensys.net/diligence/fuzzing/.Navigate to the root directory of your project.Run the following command:fuzzforgetestThis 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.ConfigurationThefuzzCLI tool allows configuration through 4 sources:YAML config files.envfilesEnvironment variablesCommand optionsConsult the documentation for each command to learn about the available options.
For more information onfuzzconfiguration, refer to theConfigurationdocumentation.CommandsThefuzzCLI 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.Free software: Apache 2 licenseHistory0.11.2 (2023-05-17)Add more verbose error messagesFix factory deployed contracts discovery0.11.1 (2023-05-04)Add config sources (.env, ENV variables, config file) parsingAdd Foundry tests list to submitted campaignFix foundry tests build arguments to include metadataAdd Smart Mode and Auto Fixes tofuzz0.11.0 (2023-04-07)Makeno-assertmode default forfuzz armcommandDrop support for Python 3.6Update dependenciesFix various bugsImprove error messagesRemovekeyparameter from fuzzing config. OnlyFUZZ_API_KEYenvironment variable or--keycommand line argument is supported now.Finalize Foundry seamless integration0.10.2 (2023-02-13)Fix quickcheck campaigns bug0.10.1 (2023-02-13)Add block data to transactions in corpus0.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 comparisonProvide map-to-original-source flag to the backend0.9.17 (2023-01-11)Fix metadata hash collection0.9.16 (2023-01-09)Fix artifacts processing forHardhatandFoundrywhich led to an error0.9.15 (2022-11-16)Add new fuzzer options0.9.14 (2022-11-09)AddversioncommandFix artifacts collection forFoundryandHardhat0.9.13 (2022-11-08)Fix sources directory detection bug ingenerate-configcommand0.9.12 (2022-11-02)AddFoundryframework support0.9.11 (2022-09-29)Fix large stdout handling for truffle db queries0.9.10 (2022-09-07)Add support for fuzzing limits related response codes0.9.9 (2022-08-25)Fix project parameter passing0.9.8 (2022-08-25)Fix fuzzing lessons logic0.9.7 (2022-08-24)Addquickcheckcampaigns supportAdd support for the incremental fuzzingAdd support for fuzzing lessonsFix various bugs0.9.6 (2022-04-13)Addtime_limitconfig option0.9.5 (2022-04-05)Add option to provide truffle executable pathAdd proper debugging to truffle errorsInclude raw results to an error output for truffle projects0.9.4 (2022-03-11)Improve error messages displayMakeno-assertdefault option on config generatorImprove api error handling for better error messages on subscriptions0.9.3 (2022-03-08)Add no subscription error messageImprove error message for free trialRemove short form of corpus-target parameter atfuzz runAdd additional checks for a seed state generatorAdd--no-assertflag toscribble armcommand0.9.2 (2022-02-22)Fix bugs0.9.1 (2022-02-22)Addrequestsdependency to requirementsFix various bugs0.9.0 (2022-02-10)Addgenerate-configcommandImprove development frameworks supportAdddapptoolsframework support0.8.2 (2022-01-19)Fixdisarmcommand related bugs0.8.1 (2021-10-26)Fix bugsImproveHardhatsupport0.7.2 (2019-09-13)Add new format API Key supportAddproject_nameconfig parameter0.7.1 (2019-09-13)Update Readme0.6.22 (2021-08-20)First release on PyPI.