Using the CI Fuzz server installer

 

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 server installer to set it up easily.

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 here.

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

To use SSO with GitHub, GitLab, or bitbucket, you need to create an OAuth app. We will use GitHub and bitbucket as examples. For GitLab , it works similarly.

At GitHub, open the developer settings to register a new OAuth application. As Authorization callback URL use:

https://<my domain>/auth/github/callback

<my domain> is a placeholder for the server's domain that will run the CI-Fuzz Server. GitHub will generate a Client ID and a Client Secret. We will need those later.

create-github-oauth-app

github-oauth-app-secret

In bitbucket, go to any workspace, click settings, oauth consumers, add consumer. As the callback url, use:

https://<my domain>:<port>/auth/bitbucket/callback

Port is mandatory, even if it's the default port 443. Give it the email and read permissions in Account.

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:

  • server secret
  • 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:
# Required
# The server cookies store secret
# Change me!
server_secret: ieGah7kaairiiv6Enahm9OhvTheich7g #Change me!
# 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>
#bitbucket:
#id: <app ID>
#secret: <app Secret>

ci:
# The address on which the http gatway receives requests on (public IP/domain)
# The server would be reachable with the https protocol if TLS is set. Otherwise, wiht http
# the ports are default to 80/443 for http/https and 6773 for GRPC. They can be overridden
# origin: example.com
origin: <your domain>
# 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

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:

This is a security-critical secret used for cookies and session management. 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 look up your GitHub id, go to https://api.github.com/users/your_github_user_name.

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.

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 configure the systemd service read the next section manually.

 

run-server-installer

 

Use systems to check if the server is up and running:

sudo systemctl status ci-server

server-installer-verfiy-installation

Step 6:  Configure systemd (optional)

If you select to install systemd services when running the server installer, a systemd unit file is created at /etc/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 systems, 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.