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

2.1 GitHub

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

2.2 Bitbucket.org

In bitbucket cloud (bitbucket.org), 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.

2.3 Bitbucket On-Premise

In bitbucket server on-premise the administrator need to go to settings and select option application links. Then a new application link to the ci-server need to be created. 

bitbucket_configure_application_links

In the first dialog window you can just continue. In the second dialog window an application name need to be typed in, a generic application need to be selected and the create incoming link checkbox need to be selected.

Screenshot from 2021-06-23 12-46-56

 

In the next dialog window, use the following values:

  • Consumer Key: "OAuthKey"
  • Consumer Name: "CI Fuzz"
  • Public Key: The public key from below

For the authentication of the ci-fuzz server a RSA key need to be generated. You can either first do steps 3 to 6 to generate it automatically by starting ci-fuzz server.  After start up of ci-fuzz server the files oauth1.pub and oauth1.pcks8 are created in /root/.local/share/code-intelligence. You can also create them manually. To create them manually you can use the following openssl commands:

openssl genrsa -out oauth1.pem 4096
openssl pkcs8 -topk8 -nocrypt -in oauth1.pem -out oauth1.pkcs8
openssl req -newkey rsa:4096 -x509 -key oauth1.pem -out oauth1.cer -days 365
openssl x509 -pubkey -noout -in oauth1.cer -out oauth1.pub

Afterwards they need to be and placed in /root/.local/share/code-intelligence on the ci-fuzz server. The pubic key then can be used in the third dialog window.

Screenshot from 2021-06-23 12-46-13


2.4 GitLab

Go to Applications in your User Settings. Choose a name, set the Redirect URI and make sure to enable the read_user scope.

gitlab-create-oauth-app

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
# Change me!
# server_secret:
# jwt_signing_key:
# These secrets will be generated automatically if not specified.
# 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. 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 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 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.