Using the CI Fuzz Server Installer

How to Set Up a Fuzz Test in CI Fuzz

The easiest way to start fuzzing is to use our SaaS solution. With this, you can fuzz your code in our cloud. We will take care of hosting the infrastructure so you can focus on fuzzing.

If you need to run the server on-premise or in your own cloud, you can use the CI Fuzz installer to set it up easily.

This guide covers the legacy CI Fuzz Go backend server. For the new Clojure server, visit this page.

We recommend using a server with at least:

  • 32 GB RAM
  • 16 or more CPU cores
  • 100 GB storage
  • A Linux operating system
  • ssh access
  • root privileges (if you want to use port 80/443)

For a more detailed overview of the hardware and software technical prerequisites see CI Fuzz Hardware and Software Technical Prerequisites.

Step 1: Install Dependencies

Since the CI Fuzz Server uses Docker containers to build your software and run the fuzz targets, docker needs to be installed. To install Docker, follow the official docker documentation. Most Linux distributions provide docker packages so that this can be easily done using your package manager.

Note: Podman on RedHat is not supported. It must be a regular docker.

Step 2: Create a New OAuth Application

CI Fuzz uses OAuth for authenticating users. Learn how to set up an OAuth app here.

Step 3: Get a TLS certificate.

For secure TLS connections to the fuzzing server, a TLS certificate is needed. Probably your company already uses a specific CA or maybe runs its own. If this is not the case, you can get free TLS certificates from Let's Encrypt.

Just install the command line tool certbot and request a certificate with a single command:

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

Step 4: Modifying the config file

A YAML config file configures the server. This config file has to be located at /root/ci-config.yaml or /etc/ci-fuzz/config.yaml. Just copy this example config file and modify what you need. The following settings are required:

  • OAuth application
  • Origin (enter IP or hostname, not the whole origin)
  • TLS certificate
    • Note: The TLS certificate needs to include the full chain of intermediate certificates. If you used certbot, the correct file ends with "fullchain.pem".
  • allowed users (unless you set on_premise: true)

All options are explained in more detail below.

# Sets up the authentication method
#
auth:
# The server cookies store secret
# These secrets will be generated automatically if not specified.
# server_secret:
# jwt_signing_key:
# One of the following methods would be required. Otherwise, the user has no way to login
github:
id: <app ID>
secret: <app Secret>
#gitlab:
#id: <app ID>
#secret: <app Secret>
# For on premise gitlabs
#domain: <gitlab custom installation domain>
#ca_path: <gitlab custom installation ca file>
# for cloud bitbucket.org
#bitbucket:
#id: <app ID>
#secret: <app Secret>
# for bitbucket server on-premise
#bitbucket_oauth1:
#url: http://ci-server.com:7990

ci:
# The address on which the http gatway receives requests on (public IP/domain)
# You can provide full origin or only the hostname. If you provide hostname, the server
# would be reachable with the https protocol if TLS is set. Otherwise, with http.
# The ports default to 80/443 for http/https and 6773 for GRPC. They can be overridden
#
# origin: https://example.com:443

origin:
# TLS server config.
cert_file: <path to crt file>
cert_key: <path to key file>


# Uncomment if a change is needed:
#http_port: 80
#https_port: 443

# if you want to use your own reverse proxy to terminate tls, then:
# - provide full origin of the reverse proxy (origin: https://hostname:port)
# - comment out cert_file and cert_key

users:
allowed:
# A list of allowed users either by email or ID used at the upstream VCS
# See backend: on_premise to allow everyone
- 12345678@github #developer1
- 23456789@github #developer2
- '{123456-79810-abcd-abcd-123a4b5c}@bitbucket' #developer3

backend:
# Set to true only if the installation is on premise and secure.
# Anyone with access to the webinterface will be able to log in.
# The above list of allowed users is ignored.
on_premise: false

# Optional for email notifications
#notification:
#smtp:
#server: smtp.mydomain.com
#port: 587
#sender_identity: smtp_identity
#sender_username: smtp_username
#sender_password: smtp_password
#email_notifier_sender_address: test@mydomain.com
#email_notifier_sender_name: CI/CD notifier

 

auth: server_secret/jwt_signing_key:

One is a security-critical secret used for cookies and session management, the second one is used to sign Json Web Tokens. These will be generated automatically if you leave them commented. If you need to specify them manually, use at least 30 random alphanumeric characters. To generate a good secret, use pwgen or a similar tool.

auth: id:

Use the client ID from the step before.

auth: secret:

Use the client secret from the step before.

users: allowed:

Github/Gitlab/Bitbucket users on this list will be able to log in. Adding a user by email only works if the email address is set to be publicly visible. If you don't want to make your email public, you can use the GitHub id instead. 

To find your own bitbucket ID (called uuid), go to bitbucket.org in a web browser and press ctr+u to view page source. Look for uuid.

Modifiying the config file

To see uuids of users of a workspace, use:

https://api.bitbucket.org/2.0/teams/xxxx/members?fields=values.display_name,values.uuid,page,next

replace xxxx with the name of your workspace.

 

backend: on_premise:

If set to true, everybody who has access to the web interface can log in. The server will ignore the list of allowed users (users: allowed: ). Be aware of the security implications.

 

Step 5: Run the Installer

Now you need to run the CI Fuzz server installer. Use wget or curl to download it from the download link we provide to you.

The installer will ask you if you want to install the Visual Studio Code extension. Since you will probably not want to run Visual Studio Code on the fuzzing server, select no.

The installer offers to install systemd services for the server and dashboard. If you want to modify the systemd service, read Step 6.

./ci-fuzz-installer-2.23.0-linux
Please enter the installation directory. [Default: /opt/ci-fuzz-2.23.0]
Extracting archive to /opt/ci-fuzz-2.23.0... ]
Creating symlinks...
Do you want to install the Visual Studio Code extension? [Y/n] N
Importing Docker images...
Installation completed

If you want to use CI Fuzz locally, use the systemd user service:

systemctl --user start ci-daemon.service

To automatically start it at boot:

systemctl --user enable ci-daemon.service

If you want CI Fuzz to listen for connections from other hosts, start the systemd system service:

sudo systemctl start ci-server.service

To automatically start it at boot:

sudo systemctl enable ci-daemon.service

Start the server as indicated, then use systemd to check if the server is up and running:

systemctl status ci-server
● ci-server.service - CI Fuzz Continuous Fuzzing Server
Loaded: loaded (/usr/local/lib/systemd/system/ci-server.service; disabled; vendor preset: enabled)
Active: active (running) since Fri 2021-08-20 11:51:34 CEST; 1s ago
Main PID: 62708 (ci-daemon)
Tasks: 8 (limit: 38277)
Memory: 13.7M
CGroup: /system.slice/ci-server.service
└─62708 /opt/ci-fuzz-2.23.0/bin/ci-daemon --ci_server --alsologtostderr -v=2

Step 6:  Configure Systemd (Optional)

If you select to install systemd services when running the server installer, a systemd unit file is created at /usr/local/lib/systemd/system/ci-server.service. This will start the ci server automatically when booting the machine. If you want to change this behavior, you can do it here.

[Unit]
After=docker.service docker.socket
Description=Code Intelligence Security Suite Daemon
Requires=docker.service docker.socket

[Service]
Type=simple
ExecStart=/opt/ci-2.18.4/bin/ci-daemon --ci_server --alsologtostderr -v=2

[Install]
WantedBy=default.target

To start the ci server, systemd starts the ci-daemon in the server mode by passing the --ci_server argument. If you do not want to use systemd, you can start the server manually with the shell command:

/opt/ci-2.18.4/bin/ci-daemon --ci_server --alsologtostderr -v=2

Step 7: Start Fuzzing

Now the dashboard should be reachable at port 80/443. To learn how to use the web app read

Using the CI Fuzz Web Interface.