Project Setup

Project Creation

To create a project use the following. 

cictl create project <path_to_project>

Hint:It is recommended to create a git repository or pull the project with to the <path_to_project> directory. Thus, changes by cictl can be optionally pushed to a git server afterwards.

 

The above cictl command will create project.yaml in <path_to_project>/.code_intelligence/.  The project.yaml will contain some pre-configured information that is necessary by the CI server.

## Configuration for a CI Fuzz project
## Generated on 2021-11-16 with CI Fuzz 2.26.1
##
## Lines that start with "##" are explanations for the following
## setting, lines that start with "#" are settings that can be enabled
## by removing the "#".

## The fuzz targets are built and run in Docker containers. This setting
## allows you to specify the Docker image that should be used for
## building this project. It must contain all the dependencies required
## to build the project.
## If you're running ci-daemon on your local system, you can leave this
## setting empty, in which case a distroless image is used and several
## directories (/lib, /bin/, /usr, ...) from the host system are
## automatically mounted into the container, effectively creating a
## build environment from the host.
#build_container: ubuntu:20.04

## The name of the container image used for running the fuzz tests. If
## unspecified, the image of the build container is used.
#run_container: ubuntu:20.04

## A list of paths which should be mounted from the host into the
## build and run containers. The format is SOURCE-DIR:DEST-DIR, where
## SOURCE-DIR will be bind-mounted from the host filesystem to DEST-DIR
## in the container.
## Environment variables in the paths are expanded from the host's
## environment.
#mounts:
#  - $HOME/build:/build

## The relative path to a script that builds the project. This script
## be will automatically copied into the build container and executed to
## build the project.
## The path must be relative to the root of the project directory.
#build_script: ".code-intelligence/build.sh"



## Paths to the fuzz targets to execute.
#fuzz_tests:
#  - .code-intelligence/fuzz_targets/*

## Paths to web app fuzz target configs.
#web_app_target_configs:
#  - .code-intelligence/fuzz_targets/*.yaml

## The sanitizers to use for the fuzz tests. Only applies to C/C++
## targets. Note that the Undefined Behavior Sanitizer (UBSan) is
## always used, regardless of this setting. By default, only
## Address Sanitizer (and Undefined Behavior Sanitizer) is used.
#sanitizers:
#  - address
#  - memory
#  - thread

## The fuzzing engines to use for the fuzz tests. By default, only
## libfuzzer is used. Only valid for C/C++ targets.
#engines:
#  - libfuzzer
#  - afl
#  - afl_llvm_mode

## The run time after which the fuzz tests are cancelled and
## considered as having passed. The default is 30 minutes.
#max_runtime: 2h

## The number of parallel executions per fuzz test. The default is 1,
## which means for each combination of fuzzing engine and sanitizer,
## each fuzz target is executed once.
#parallel_executions: 2

## By default, fuzz targets are seeded with an initial input corpus,
## which consists of files of various data formats. This often improves
## results, but could take a long time for slow fuzz targets. Set to
## true if you don't want to use the initial input corpus.
#no_initial_corpus: true

The command output should be similar to the following.

cictl_create_project

The missing build.sh file error can be ignored. 

Fuzz Test Creation

 The cictl tool supports the creation of different Fuzz targets:

Java Web App Fuzz Target

For the web application fuzz target creation it is recommended to use the web interface of the CI Server in addition for the connection setup between the target application and the CI server. The article Connecting Web Applications  can be used as a reference to generate a java agent command in the web interface.

 

After connection setup it is important to use the same web service name for the fuzz target. You can get the web service name by:

cictl list webservices

Afterwards a fuzz target can be created by the following cictl command:

cictl create webapptarget <fuzz_test_name> --web_services=<project_name>

Additional options: 

  • --openapi - path to an OpenAPI spec (yaml or json) which will be used to generate seeds and guide the mutations
  • --base_url - URL at which the application under test is reachable (defaults to 127.0.0.1:8080)

After fuzz test creation fuzz target configurations are created in .code-intelligence. All changes in .code-intelligence can be pushed to a git server afterwards to be added persistent to a CI/CD integration of CI fuzz.

Java gRPC Fuzz Target

For the java-gRPC fuzz target creation it is also recommended to use the web interface of the CI Server in addition for the connection setup between the target application and the CI server. The article Connecting Web Applications  can be used as a reference to generate a java agent command in the web interface.

After connection setup it and before fuzz target creation it is also necessary to compile the .proto files of the target application and to create a shared object file stub.so. You can follow Project Setup (Java gRPC Applications) for this.

Afterwards you can create a fuzz target with:

cictl create webapptarget <fuzz_test_name> --web_services=<project_name> --base_url=<target_url:target_port> --protocol=grpc --run_extra_args="--proto_stub_path=<PATH_TO_STUB.so>"

 

 

Fuzz Test Investigation & Usage

To see all fuzz tests use

cictl list campagigns -p <project_name>

Make sure you use the full name as it is shown by cictl list projects. The display name will not work.

list_campaigns

Make sure you use the full name as it is shown by cictl list projects. The display name will not work.

To run a fuzz test, use

cictl start <fuzz_test_name>

Again, make sure not to use the display name.

cictl_start_campaign_1cictl_start_campaign_2

You can see the build log of the fuzz test. When building is finished, the last line tells you the name of the run. If you want to get informed about the progress and state of a fuzz target, use cictl monitor to subscribe to updates.

cictl monitor <campaign_run>

 

cictl_monitor_campaign_run

When a bug is discovered, it will be shown there as well.

To see all bugs and other findings that have been discovered, you can use

cictl list findings

 

cictl-list-findings

Using cictl overview, you can get detailed code coverage information as well as an overview about all fuzz tests and findings

cictl overview -p <project_name>

 

cictl_project_ovrview_1cictl_project_overview_2