Run a Fuzz Test in a container

container run

You can build and execute a Fuzz Test locally in a container with the cifuzz container run command:

cifuzz container run [--option...] <fuzz test> [--] [<build system argument>...] [--] [<container argument>...]

For the syntax of the <fuzz test> argument see this section.

For an explanation of the <build system argument> see this section. Be aware that these arguments have to be passed before the <container argument>. The latter can be passed after the last -- at the end of the command.

Options

The cifuzz container run command supports the following command specific options:

Flag	Description
--add <source-path>;<target-path>	Add a file or directory to the bundle If <target-path> is missing the file gets copied to 'work_dir' This flag can be used multiple times
--branch <name>	Branch name to use in the config By default, the currently checked out git branch is used
--build-command <command>	The command to build the Fuzz Test for other build systems
--build-jobs uint[=0]	Maximum number of concurrent processes to use when building If argument is omitted the native build tool's default number is used
--build-only	Only build the container image, don't run it
--clean-command <command>	The command to clean the Fuzz Test and its dependencies for other build systems
--commit <name>	Commit to use in the config By default, the head of the currently checked out git branch is used
--container <path>	Path of an existing container to start a run with
--dict <path/to/file>	A file containing input language keywords or other interesting byte sequences This flag is only used if no default dictionary is found for the Fuzz Test See https://llvm.org/docs/LibFuzzer.html#dictionaries
--docker-image <name>	A Docker image which is used as the base for the container image The image must contain all the dependencies required to run the Fuzz Test By default, the image is chosen automatically based on the build system ("eclipse-temurin:20" for Java build systems, "cifuzz/cifuzz-ubuntu:latest" for others)
--engine-arg <argument>	Command-line argument to pass to the fuzzing engine See https://llvm.org/docs/LibFuzzer.html#options This flag can be used multiple times Not supported for Node.js projects
--env <VAR>=<value>	Set environment variable when executing Fuzz Tests To use the value of VAR in the local environment, use --env VAR This flag can be used multiple times
--interactive	Toggle interactive prompting in the terminal (default=true)
--json	Print output as JSON
-p, --project <name>	The name of the CI Fuzz project you want to start a fuzzing run for, e.g. "my-project-c170bc17"
--project-dir <dir>	The project root which is the parent for all the project sources Defaults to the directory containing the cifuzz.yaml
-r, --resolve	Argument of the command is a path to a source file instead of a test identifier. The path can be either absolute or relative to the current working directory and will be resolved to the identifier of the corresponding Fuzz Test.
-s, --seed-corpus <dir>	A directory containing sample inputs used as seeds for fuzzing the code under test This is used in addition to inputs found in the inputs directory of the Fuzz Test This flag can be used multiple times
--server <address>	Address of CI Sense (default="https://app.code-intelligence.com")
--timeout <duration>	Maximum time to run the Fuzz Test, e.g. "30m", "1h" The default is to run indefinitely
--tls-skip-verify	Disable TLS certificate verification This means TLS will accepts any certificate presented by the server and any host name in that certificate

All supported global options are documented in Learn CI Fuzz.

container remote run

You can build one or multiple Fuzz Tests in a container and push them to CI Sense with the cifuzz container remote-run command:

cifuzz container remote-run [--option...] [<fuzz test>]

The <fuzz test> argument is optional. If no argument is provided, all available Fuzz Tests will be used. For the syntax of the <fuzz test> argument see this section.

Options

The cifuzz container run command supports the following command specific options:

Flag	Description
--add <source-path>;<target-path>	Add a file or directory to the bundle If <target-path> is missing the file gets copied to 'work_dir' This flag can be used multiple times
--branch <name>	Branch name to use in the config By default, the currently checked out git branch is used
--build-command <command>	The command to build the Fuzz Test for other build systems
--build-jobs uint[=0]	Maximum number of concurrent processes to use when building If argument is omitted the native build tool's default number is used
--clean-command <command>	The command to clean the Fuzz Test and its dependencies for other build systems
--commit <name>	Commit to use in the config By default, the head of the currently checked out git branch is used
--dict <path/to/file>	A file containing input language keywords or other interesting byte sequences This flag is only used if no default dictionary is found for the Fuzz Test See https://llvm.org/docs/LibFuzzer.html#dictionaries
--docker-image <name>	A Docker image which is used as the base for the container image The image must contain all the dependencies required to run the Fuzz Test By default, the image is chosen automatically based on the build system ("eclipse-temurin:20" for Java build systems, "cifuzz/cifuzz-ubuntu:latest" for others)
--engine-arg <argument>	Command-line argument to pass to the fuzzing engine See https://llvm.org/docs/LibFuzzer.html#options This flag can be used multiple times Not supported for Node.js projects
--env <VAR>=<value>	Set environment variable when executing Fuzz Tests To use the value of VAR in the local environment, use '--env VAR' This flag can be used multiple times
--interactive	Toggle interactive prompting in the terminal (default=true)
--json	Print output as JSON
--min-finding-severity <severity>	Minimum severity of findings to report e.g. 'LOW', 'MEDIUM', 'HIGH', 'CRITICAL' Only works with --monitor-duration (default="LOW")
--monitor	Monitor the status of the container remote-run on CI Sense The default is to monitor indefinitely Use --monitor-duration to set a maximum duration
--monitor-duration <duration>	Duration of the monitoring of container remote runs e.g. "30m", "1h" Only works if --monitor is used
--monitor-interval <duration>	Interval between checks of the container remote run status e.g. "10s", "1m" Only works if --monitor is used (default=10s)
--monitor-keep-going	Don't exit the monitoring process if findings are found
-p, --project <name>	The name of the CI Fuzz project you want to start a fuzzing run for, e.g. "my-project-c170bc17"
--project-dir <dir>	The project root which is the parent for all the project sources Defaults to the directory containing the cifuzz.yaml
--registry <name>	The container registry to use for the upload of the container image e.g. ghcr.io/my-org/my-project
-r, --resolve	Argument of the command is a path to a source file instead of a test identifier. The path can be either absolute or relative to the current working directory and will be resolved to the identifier of the corresponding Fuzz Test.
-s, --seed-corpus <dir>	A directory containing sample inputs used as seeds for fuzzing the code under test This is used in addition to inputs found in the inputs directory of the Fuzz Test This flag can be used multiple times
--server <address>	Address of CI Sense (default="https://app.code-intelligence.com")
--timeout <duration>	Maximum time to run the Fuzz Test, e.g. "30m", "1h" The default is to run indefinitely
--tls-skip-verify	Disable TLS certificate verification This means TLS will accepts any certificate presented by the server and any host name in that certificate

All supported global options are documented in Learn CI Fuzz.