cifuzz

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.

Getting started

If you are new to the world of fuzzing, we recommend you to take a
look at our Glossary.

Installation

Building from Source (Linux)

Prerequisites

• git
• make
• CMake >= 3.16
• LLVM >= 11
• go >= 1.18
• libcap

Ubuntu / Debian

sudo apt install git make cmake clang llvm golang-go libcap-dev 

Arch

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
cd cifuzz
make test
make install

If everything went fine, you will find the newly created directory
~/cifuzz. Do not forget to add ~/cifuzz/bin to your $PATH.

To verify the installation we recommend you to start a fuzzing run
in one of our example projects:

cd examples/cmake
cifuzz run my_fuzz_test

This should stop after a few seconds with an actual finding.

Setup / Create your first fuzz test

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.

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.

2. The next step is to create a fuzz test. Execute cifuzz create
   and follow the instructions given by the command. This will create a
   stub for your fuzz test, lets say it is called my_fuzz_test.cpp.

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.

4. Start the fuzzing by executing cifuzz run my_fuzz_test.
   cifuzz now tries to build the fuzz test and starts a fuzzing run.

Regression testing

Important: In general there are two ways to run your fuzz test:

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

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