IMPORTANT: This project is under active development. Be aware that the behavior of the commands or the configuration can change.
cifuzz is a CLI tool that helps you to integrate and run fuzzing based tests into your project.
If you are new to the world of fuzzing, we recommend you to take a look at our Glossary.
Building from Source (Linux)
CMake >= 3.16
LLVM >= 11
go >= 1.18
Ubuntu / Debian
sudo apt install git make cmake clang llvm golang-go libcap-dev
sudo pacman -S git make cmake clang llvm go libcap
To build cifuzz from source you have to execute the following steps:
git clone https://github.com/CodeIntelligenceTesting/cifuzz.git
If everything went fine, you will find the newly created directory
~/cifuzz. Do not forget to add
~/cifuzz/bin to your
To verify the installation we recommend you to start a fuzzing run in one of our example projects:
cifuzz run my_fuzz_target
This should stop after a few seconds with an actual finding.
Setup / Create your first fuzz target
cifuzz commands will interactively guide you through the needed options and show next steps. You can find a complete list of the available commands with all supported options and parameters by calling
cifuzz command --help or here.
Step 1: To initialize your project with cifuzz just execute
cifuzz init in the root directory of your project. This will create a file named
cifuzz.yaml containing the needed configuration.
Step 2: The next step is to create a fuzz target. Execute
cifuzz create and follow the instructions given by the command. This will create a stub for your fuzz test (aka fuzz target), lets say it is called
Step 3: Edit
my_fuzz_test.cpp so it actually calls the function you want to test with the input generated by the fuzzer. To learn more about writing fuzz tests, you can take a look at our Tutorial or one of the example projects.
Step 4: Start the fuzzing by executing
cifuzz run my_fuzz_test. cifuzz now tries to build the fuzz test and starts a fuzzing run.
Important: In general there are two ways to run your fuzz test:
An actual fuzzing run by calling:
cifuzz run my_fuzz_test. The fuzzer will rapidly generate new inputs and feed them into your fuzz test. Any input that covers new parts of the fuzzed project will be added to the generated corpus. cifuzz will run until a crash occurs and report detailed information about the finding.
As a regression test, by invoking it through your IDE/editor or by directly executing the replayer binary (see here on how to build that binary). This will use the replayer to apply existing input data from the seed corpus, which has to be stored in the directory
<fuzz-test-name>_seed_corpus beside your fuzz test. Note that this directory has to be created manually. In this case the fuzz test will stop immediately after applying all input or earlier if a regression occurs.
On Linux, cifuzz runs the fuzz tests in a sandbox by default, to avoid the fuzz test accidentally harming the system, for example by deleting files or killing processes. It uses Minijail for that.
If you experience problems when running fuzz tests via cifuzz and you don't expect your fuzz tests to do any harm to the system (or you're already running cifuzz in a container), you might want to disable the sandbox via the
--use-sandbox=false flag or the
use-sandbox: false config file setting.