Skip to content

Latest commit

 

History

History
126 lines (92 loc) · 5.35 KB

Getting-Started.md

File metadata and controls

126 lines (92 loc) · 5.35 KB
Raw

Getting started

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 read about them in the wiki.

  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 and print out any necessary steps to set up your project.

  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, for example my_fuzz_test_1.cpp and tell you how to integrate it into your project. You will find more detailed information in our Tutorial.

  3. Edit the fuzz test stub 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 fuzzing by executing cifuzz run my_fuzz_test_1. cifuzz now builds the fuzz test and starts a fuzzing run.

Java/Kotlin:

For Java/Kotlin projects, users need to specify the fuzz target identifier in reverse domain name notation, e.g., com.example.FuzzTestCase. For this example, it means that the package name is com.example and the class name is FuzzTestCase.

Example: cifuzz run com.example.FuzzTestCase.

By default, cifuzz will try to find a single fuzz test for a given JVM class. If you want to have multiple fuzz tests in a single JVM class, use the :: notation to specify the named fuzz test.

Example: cifuzz run com.example.FuzzTestCase::myNamedFuzzTest

This will look for the class name FuzzTestCase in the package com.example and run the myNamedFuzzTest method. We provide tab completion for named fuzz test methods if cifuzz finds more than one fuzz test in the JVM class.

Javascript/Typescript:

For Javascript/Typescript projects, users need to specify a fuzz target identifier consisting of a regex path pattern that is matched against all test paths. The first test, that is matched by that pattern, gets executed.

As an example, consider the case of two fuzz tests:

  • project-root/tests/FuzzTestCase1.fuzz.js
  • project-root/tests/FuzzTestCase2.fuzz.js

cifuzz run FuzzTestCase executes the first fuzz test, whose path contains FuzzTestCase. The evaluation order is determined by the jest test runner. FuzzTestCase2 can be executed explicitely by running cifuzz run FuzzTestCase2.

By default, the first fuzz test in that file will by executed. If a test file contains multiple fuzz tests, one specific fuzz test can be selected by specifying a regex test name pattern. The regex is matched against the full name, which is a combination of the test name and all its surrounding describe blocks.

Example: cifuzz run FuzzTestCase1:"My fuzz test"

The first fuzz test in FuzzTestCase1.fuzz.js matching "My fuzz test" will be executed.

Generate coverage report

Once you executed a fuzz test, you can generate a coverage report which shows the line coverage of the fuzzed code:

cifuzz coverage my_fuzz_test_1

See coverage IDE integrations for instructions on how to generate and visualize coverage reports right from your IDE.

Regression testing

If you are interested in running your fuzz tests as regression tests to maintain a fast and responsive development cycle, you can check out our regression testing guide.

Sandboxing

On Linux, cifuzz runs fuzz tests in a sandbox by default to prevent them from accidentally harming the system, for example by deleting files or killing processes. Minijail is used for this purpose.

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.

If your fuzz test needs to access some files or directories which are not accessible in the sandbox, you can add bindings for those via the CIFUZZ_MINIJAIL_BINDINGS environment variable. The bindings must be separated by colon and be specified in the same format that is supported by the --bind-mount flag of minijail0:

CIFUZZ_MINIJAIL_BINDINGS=<src>[,[dest][,<writeable>]], where <src> must be an absolute path and <writeable> is either 0 or 1. For example:

CIFUZZ_MINIJAIL_BINDINGS=/tmp/foo,/tmp/foo,1:/home/user/foo,/home/user/foo,1

Intro to cifuzz (live stream)

Check out @jochil's live session for a walkthrough of how to get started with cifuzz. The event is freely accessible on YouTube and Linkedin.

Also, watch Going Beyond Unit Testing | How to Uncover Blind Spots in your Java Code with Fuzzing on YouTube.