Candidates for fuzz test generation
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. |
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.
coverage-report: report/lcov.info
If you don't have a LCOV coverage report, you can create one with the following command:
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
.
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
.
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.