Candidates for fuzz test generation

This page is still under construction.

You can generate a list of suggested functions suitable for fuzz test generation with the cifuzz candidates command:

cifuzz candidates [flags] [--] [<build system arg>...]

Command options

Flag	Default	Description
--ast-compiler-arg <stringArray>		Additional compiler arguments passed to clang tooling when analyzing the source code.This flag can be used multiple times or by specifying 'ast-compiler-args' (list) in cifuzz.yaml.
-b, --build-dir <string>		Directory containing compilation database "compile_commands.json".
--build-jobs <uint>	8	Maximum number of concurrent processes used for building. If set to zero, the default of the native build tool is used. Defaults to the number of cores on your machine.
-i, --candidate-includes <stringArray>		Filter list of fuzzing candidates via source file glob patterns. By default, only the project directory is included. Any values provided here will overwrite the default pattern. To include the project directory again, add it using an absolute path. Multiple include glob patterns are possible by setting the flag several times or by using ";" as a separator. Example: To include only files in "<projectRoot>/src" and "/home/<user>/project" for all users in candidate analysis: --candidate-includes="src/**;/home/*/project/**" or by specifying 'candidate-includes' (list) in cifuzz.yaml.
--coverage-report <string>		LCOV coverage report to prioritize functions with low coverage.
--detect-system-includes	true	Automatically detect system include directories for the compiler.
-e, --file-excludes <stringArray>	**/*_test.*; test*/**; .cifuzz/**/_deps/**	Exclude files from analysis via glob patterns. Multiple exclude glob patterns are possible by setting the flag several times or by using ";" as a separator. Example: --file-excludes="examples/**;tests/**" or by specifying 'file-excludes' (list) in cifuzz.yaml.
-f, --format <string>	table	Output format of the candidates: "table", "json".
-n, --num-candidates <uint>	5	Number of candidates to select.

note

The source code analysis requires a compilation database. You have to add the path with the --build-dir flag if your project uses a build system other than CMake. CMake projects can generate this file with the CMAKE_EXPORT_COMPILE_COMMANDS option and cifuzz automatically detects and configures this.

Scoring

After building and analysing the source code, the command calculates a score between 0 and 1 for every function, with higher scores indicating a larger benefit of writing a fuzz test.

The score is calculated by analyzing the functions

• total lines of code reachable from the function
• total uncovered lines of code (if a coverage report is provided)
• cyclomatic complexity
• amount of dangerous function calls
• amount of dangerous expressions

These values can indicate the probability that fuzz tests for these functions detect vulnerabilities or significantly increase the code coverage in the project.

Include coverage information in score

You can include information about uncovered lines of code in your project with the --coverage-report flag. This flag takes a path to a LCOV coverage report and the information causes the score calculation to prioritize functions with low code coverage.

cifuzz.yaml

coverage-report: report/lcov.info

If you don't have a LCOV coverage report, you can create one with the following command:

Create coverage report

cifuzz coverage --format=lcov

Exclude files from analysis

You can exclude specific source code files from the analysis with the -e/--file-excludes flag. The flag expects a glob pattern. You can exclude multiple files either by using the flag multiple times or separate multiple glob patterns with a semicolon (";").

--file-excludes="examples/**" --file-excludes="tests/**"

--file-excludes="examples/**;tests/**"

You can also configure the flag in the projects cifuzz.yaml.

cifuzz.yaml

file-excludes:
  - examples/**
  - tests/**

Only analyse specific files

You can use the -i/--candidate-includes flag to restrict the source code analysis to specific source files. The flag expects a glob pattern. You can include multiple files either by using the flag multiple times or separate multiple glob patterns with a semicolon (";").

--candidate-includes="src/example/**" --candidate-includes="/home/project/**"

--candidate-includes="src/example/**;/home/project/**"

You can also configure the flag in the projects cifuzz.yaml.

cifuzz.yaml

candidate-includes:
  - src/example/**
  - /home/project/**

Additional information

Found multiple compile commands for the same source file

The static analysis relies on compile commands listed in the compilation database (compile_commands.json). If multiple entries exist for a single source file, the first entry is selected by default. However, the same file may be compiled with different options, such as varying pre-processor flags, which can impact the Abstract Syntax Tree (AST). This may lead to CI Fuzz analyzing an AST that does not accurately reflect the intended compilation context.

To mitigate this issue, it is recommended to investigate how the compilation database is generated and ensure that it correctly represents the intended build configuration.