1. Documentation
  2. Continuous Fuzzing

cictl command line tool

The information in this article applies to cictl version 3.0.0 and newer. Check which version of cictl you have installed:

cictl --version

 

Cictl comes with an integrated help

cictl help

cictl-integated-help

 

The first thing you might want to do is to install the completion scripts. This teaches your shell to autocomplete cictl commands which save you most of the typing.

If you are using bash under Linux just run

cictl completion bash > /etc/bash_completion.d/cictl

If you are using a different shell you can use

cictl completion --help

to get a detailed manual on how to do this for every supported shell. Currently Bash, Zsh, fish, and PowerShell are supported.

The cictl tool needs a running ci-daemon it can connect to. You can start the local daemon using

ci-daemon -v1 --alsologtostderr

Alternatively, you can tell cictl to connect to the CI Fuzz Cloud to manage your projects and run your fuzz tests there. To login to the CI Fuzz cloud, first set the server address by running

cictl config set server grpc-api.code-intelligence.com:443

then run

cictl login

and enter your access token. For information about how to create an access token read Continous Fuzzing Setup

cictl-login_redacted

First lists all projects that are currently initialized.

cictl list projects

list-projects

To create a project use

cictl create project <path_to_project>

For this to work, the project directory needs to contain a valid ci_info file that specifies the build script and the docker image to be used. You can also use the VSCode plugin to set up a new project ( Project setup C/C++ and Project Setup Java Spring Boot).

{
"name": "projects/zint-006bf471",
"displayName": "zint-sf",
"buildScriptContent": "mkdir build\ncd build\ncmake ..\nmake -j$(nproc)",
"details": {
"buildSystem": "CMAKE"
},
"projectEnvironment": {
"dockerBuild": {
"name": "cifuzz/builders:zint"
},
"dockerRun": {
"name": "cifuzz/builders:zint"
}
}
}

 

cictl-create-project

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

 

Synchronize your local project with the server

The latest version of cictl supports downloading the corpus and findings from a CI-Fuzz server and to work with it locally. To do so, run

cd <project dir>
cictl config set sync.remote <server domain>:6773
cictl config set sync.project <remote project name>
cictl sync