Skip to main content

Setup CI Sense

This page walks you through installing CI Sense. Before you begin, you should have received:

  • the CI Sense on-prem installer (ci-fuzz-on-prem-installer-<version>-linux)
  • a Docker image bundle (ci-fuzz-on-prem-images-<version>-linux)

Prerequisites​

To use the provided install mechanism and the resulting docker-compose setup, you need to meet some prerequisites. Use a server with at least:

  • 32 GB RAM
  • 16 or more CPU cores
  • 100 GB storage (at least 256 GB recommended)
  • A Linux operating system
  • ssh access, or equivalent
  • Docker and Docker-Compose
  • root privileges, if you want to use port 80/443
  • Open ports. See Ports and Network Settings for details
  • Access to a container registry.

Linux​

The only supported operating system is Linux. Most linux distributions are fine, but using one that supports systemd is most comfortable. If in doubt, use an Ubuntu Server.

TLS​

Operating system's certificate store must be in the following location:

/etc/ssl/certs/ca-certificates.crt

This is the default on Ubuntu and Debian. On Centos, you need to create a hard link here:

ln /etc/pki/ca-trust/extracted/openssl/ca-bundle.trust.crt /etc/ssl/certs/ca-certificates.crt

Docker​

Docker-Compose relies on docker being installed on the host system. To do so, follow the provided instructions for your distribution as depicted in the docker engine documentation.

Additionally, CI Sense runs fuzz tests inside specific Docker containers. You specify these docker containers as part of the fuzz tests themselves, but the CI Sense server must have access to these docker images. You can either pull them from an internal or external container registry or place them otherwise on the CI Sense server.

Docker-compose​

In addition to the docker engine, the setup uses docker-compose to orchestrate its components. To setup docker-compose, follow the installation instructions.

The minimum supported docker-compose version is 1.27.0. CI Sense also supports the Compose plugin for Docker (docker compose).

Systemd​

Having docker-compose allows to easily start and stop the service. But to (re)started at boot, you need to do some additional work. The installer provides a shortcut by setting up a systemd system service.

Ports and network settings​

This table provides some details about potential port requirements you may need.

info

AUT is the Application Under Test and applies to Web API fuzzing only.

PortProtocolSourceDestinationPurposeComments
443TCPBrowserCI ServerAccess CI Sense web application to view and manage findingsPort is configurable in CI Sense
OAuth Provider PortTCPCI ServerOAuth ProviderCI Server contacts the OAuth provider during authentication.
443TCPcictlCI ServerStart fuzz tests, upload artifacts, monitor statusPort is configurable in CI Sense
443TCPCI/CD ServerCI ServerCI/CD server can initiate jobs on CI ServerPort is configurable in CI Sense
6777-7777TCPAUTCI ServerJava agent to contact CI Server with finding and coverage informationWeb API fuzzing only. Port range is configurable in CI Sense
AUT Listening PortTCPCI ServerAUTSend fuzzing inputs to AUTPort depends on listening port of AUT. Web API fuzzing only.

A DNS entry for your CI Sense server must exist, or you need a custom TLS certificate that's valid for an IP address.

Step 1: Get a TLS certificate​

For secure TLS connections to the fuzzing server, you need a TLS certificate. Your company may already use a specific CA or run its own. If not, you can get free TLS certificates from Let's Encrypt.

Install the command line tool certbot and request a certificate with the following command:

sudo apt install certbot
sudo certbot certonly --standalone --preferred-challenges http -d <your domain>

Step 2: Run the installer​

After receiving a link for the installer and a docker image bundle (CI Sense on-premise backend image bundle) from Code Intelligence, run the installer with the docker image bundle as shown here:

chmod +x ci-fuzz-on-prem-installer-<version>-linux
./ci-fuzz-on-prem-installer-<version>-linux --docker-images <path to your bundle>

You need at least 10 GB of free disk space to run the installer when using the image bundle, as it needs to create some temporary files.

Step 3: Configuration​

When CI Sense starts it loads all configuration variables found in /opt/ci-fuzz-<version>/cifuzz.env. It then searches for any .env files in /etc/cifuzz. Any variables defined there overwrite those originally taken from /opt/ci-fuzz-<version>/cifuzz.env. Below you find a template with some explanations and recommended values you can use as a starting point for your configuration.

Data storage locations​

The following table lists the standard locations and components for data for a CI Sense installation. This is a useful reference when planning your initial installation and how to handle upgrades and backups.

Data ItemDefault LocationPurposeConfigurableComments
CIFUZZ_DATA_DIR$HOME/.local/share/cifuzzDirectory containing fuzzing artifacts and corporaLocation can be configured in .env files in /etc/cifuzzThe directory can be a network share.
CI Sense Database/var/lib/docker/volumes/cifuzz_db-data/_dataPostGreSQL database for storing fuzzing results and user data.Not configurable in CI SenseBackup/tar this directory. See note below
Configuration files/etc/cifuzzConfiguration files for CI SenseCI Sense first looks for cifuzz.env and then applies any additional .env files that are found in the directory specified by cifuzz-server --env-files-from
CIFUZZ_WORKER_TEMP_DIR/tmp/ci-worker-tempFuzzing binaries are stored here temporarily on the host for execution in the docker containerLocation can be configured in .env files in /etc/cifuzzThis directory requires the execution permission
note

If deploying CI Sense to a new system / image, you should first start CI Sense to initialize the docker volume directory. Then stop CI Sense, copy over the database backup, and restart CI Sense.

Pull docker images​

CI Sense runs fuzz tests in docker containers. By default, it attempts to pull docker images from Docker Hub for images that don't already exist on the server. You can also configure it to pull from private container registries.

To do this, add the following variable to your CI Sense configuration file : CIFUZZ_JOB_IMAGE_PULL_SECRETS. Format the value for this variable as an edn map of registry name to auth data.

An example of specifying the variable:

CIFUZZ_JOB_IMAGE_PULL_SECRETS='{"myregistry.mycomp.io" {"username" "some-user" "password" "some-password" "serveraddress" "myregistry.mycomp.io"} "myotherregistry.mycomp.io" {"username" "some-other-user" "password" "some-other-password" "serveraddress" "myotherregistry.mycomd.io"}}'
note

The value should be properly escaped for bash .env files and given in a single line. Double quotes are required and the server address given must match the registry name. If you don't configure credentials for a given registry, pulls perform without authentication. The system doesn't try to access registries for images already available locally.

First time installation​

If this is your first time installing CI Sense, you will need to create the /etc/cifuzz directory.

sudo mkdir /etc/cifuzz/

You can download this template to /etc/cifuzz/cifuzz.env and then fill in the values as described below. You can use the command:

sudo wget https://docs.code-intelligence.com/assets/files/cifuzz.env.template -O /etc/cifuzz/cifuzz.env
  • CIFUZZ_ARTIFACT_STORAGE_QUOTA - the maximum allowed storage space the artifacts are allowed to consume, before old artifacts get deleted. The default is 100 GB, but depending on the total storage available to the server hosting CI Sense, you may want to adjust this.
  • CIFUZZ_SERVER_ORIGIN - change to the hostname of the host where you are running CI Sense server. Please set full origin here - protocol (HTTPS), hostname and port. If you are using OAuth, then this must match the origin set in your OAuth app.
  • CIFUZZ_SERVER_PORT you can change the port if needed. Defaults to 8080 if not set.
  • CIFUZZ_CERT_FILE and CIFUZZ_CERT_KEY - absolute paths to the certificate and key that CI Sense should use.
  • CIFUZZ_INTER_SERVICE_AUTH_KEY - generate a random key using openssl rand -hex 32 or equivalent.
  • CIFUZZ_NUM_WORKER_THREADS - set to the number of CPU cores available.
  • CI Sense Authentication - there are several ways to configure authentication to the CI Sense Web Application. The template contains areas for various OAuth applications. You only need to fill in the values for one of them. See Authentication for details on different authentication options.

Upgrading CI Sense​

If you are upgrading CI Sense from a previous version, there is no need to adjust your configuration options in /etc/cifuzz/cifuzz.env unless you like to use newly added capabilities. To upgrade CI Sense stop the service, install the new CI Sense version with the new docker images, and then restart the service:

sudo systemctl stop cifuzz
chmod +x ci-fuzz-on-prem-installer-<version>-linux
./ci-fuzz-on-prem-installer-<version>-linux --docker-images <path to your bundle>
sudo systemctl start cifuzz
note

You may also need to reload the service files using sudo systemctl daemon-reload after installing the new version of CI Sense.

Step 4: Run server​

sudo systemctl start cifuzz
sudo systemctl enable cifuzz #to make it autostart after reboot

Confirm that you started CI Sense containers successfully:

sudo docker ps

The output should look similar to this:

CONTAINER ID   IMAGE                                                  COMMAND                  CREATED          STATUS         PORTS                                       NAMES
2833328092d9   f5d6e55758e0d08d.azurecr.io/cifuzz/ci-worker:2.42.0    "/usr/bin/java -cp /…"   11 seconds ago   Up 7 seconds   0.0.0.0:6778->6777/tcp, :::6778->6777/tcp   cifuzz-ci-worker-1
dba452af7e81   f5d6e55758e0d08d.azurecr.io/cifuzz/ci-backend:2.42.0   "/usr/bin/java -cp /…"   11 seconds ago   Up 7 seconds   0.0.0.0:6777->6777/tcp, :::6777->6777/tcp   cifuzz-ci-backend-1
bc3e5af64601   prometheuscommunity/postgres-exporter:v0.10.0          "/bin/postgres_expor…"   11 seconds ago   Up 7 seconds   0.0.0.0:9187->9187/tcp, :::9187->9187/tcp   cifuzz-db-metrics-1
909f0f946f26   f5d6e55758e0d08d.azurecr.io/cifuzz/reporting:2.42.0    "/usr/bin/java -cp /…"   11 seconds ago   Up 8 seconds                                               cifuzz-reporting-1
86d83d710634   postgres:12.7                                          "docker-entrypoint.s…"   11 seconds ago   Up 8 seconds   5432/tcp                                    cifuzz-db-1
6975de4d7388   f5d6e55758e0d08d.azurecr.io/cifuzz/gateway:2.42.0      "/app/cmd/gateway/ba…"   11 seconds ago   Up 8 seconds   0.0.0.0:443->443/tcp, :::443->443/tcp       cifuzz-gateway-1