Setting Up Runners

Setting up a runner is optional, since scan reports generated by the CVEScan CLI can always be imported manually through the WebUI or the HTTP API. You only need to install a runner if you want CVEScan Web to execute scans on its own, for example by running them on a recurring schedule or by triggering them on demand directly from the WebUI or the HTTP API, which provides a seamless and transparent automation experience while keeping the manual import workflow available at any time as a complementary option.

If you are not yet familiar with what a runner is and what it does, please read the Runners concept page before continuing.

Step 1. Register a runner from the WebUI

The first step is to register a new runner from the WebUI in order to obtain the authentication token that the runner will use to talk to the API.

1. Open your browser and log in to the WebUI at (protocol)://(domain_name)/webui using your system administrator account.
2. Click on your profile picture located at the bottom of the left sidebar. This will navigate you to the system level pages.
3. In the sidebar, click on Runners. You can also reach this page directly at (protocol)://(domain_name)/webui/-/runners.
4. On the runners page, click the button to register a new runner. You will be asked to provide a name and an optional description so you can recognize this runner later.
5. Once the runner is created, the WebUI will display an authentication token. Copy this token and store it in a safe place right away.

Step 2. Make sure the runner image can be pulled

The source code of the runner lives in a separate repository from CVEScan Web. To make installation easier, a pre-built image of the runner is published on the same container registry as the rest of the platform, so you can deploy it directly without having to clone or build anything yourself.

What this means for you depends on how you have been deploying CVEScan Web so far:

• If you are already using the pre-built images for the rest of the platform, there is nothing extra to do. The CVESCAN_REGISTRY and CVESCAN_IMAGE_TAG variables are already defined in your .env file, you have already logged in to the registry, and the runner image will be pulled the same way as the other images.
• If you have been building the other services from source, you need to set the CVESCAN_REGISTRY and CVESCAN_IMAGE_TAG variables in your .env file and log in to the registry on the host that will run the runner. The exact variables and login command are the same ones described in the Starting Services section, under the Using pre-built images instructions.

Step 3. Choose where the runner will run

A sample docker-compose-runner.yml file is provided in the root directory of the CVEScan Web repository. You can use it in two different ways depending on your infrastructure:

• Alongside CVEScan Web, on the same host as the API, the WebUI and the database. This is the simplest setup, and the runner can communicate with the API directly over the internal Docker network.
• On a separate machine, for example to keep the scanning workload away from the host that runs the WebUI, or to scale horizontally by spreading several runners across multiple machines.

Pick the option that matches your needs and follow the corresponding step below. You can also combine both approaches and run additional runners on separate machines later on, simply by repeating the standalone setup as many times as needed.

Step 4. Start the runner

Option A. Run the runner alongside CVEScan Web

This is the simplest setup. The runner runs on the same host as the rest of CVEScan Web and joins the same internal Docker network. Because everything is on the same network, the runner can talk to the API over plain HTTP without needing to go through the reverse proxy.

To do this, add the runner service from docker-compose-runner.yml to the services section of your main docker-compose.yml file. Do the same with the volumes, by adding them to the existing volumes section of docker-compose.yml.

You can keep CVESCAN_RUNNER_ENDPOINT set to http://api:3100, since api is the name of the API service inside the Docker network and it listens on port 3100. Change this value only if you changed the name and/or port of the API service.

Then, add the runner token you obtained in step 1 to your .env file:

CVESCAN_RUNNER_TOKEN="paste-your-runner-token-here"

Finally, restart your services so that the new runner is created and started:

docker compose up -d

If you are not using Keycloak as the identity provider, remember to pass the same overrides as in the previous sections:

docker compose -f docker-compose-no-keycloak.yml -f compose-no-keycloak.override.yml up -d

Option B. Run the runner on a separate machine

On the machine that will host the runner, install Docker, copy the docker-compose-runner.yml file to that machine, and create a .env file next to it with the following content:

CVESCAN_RUNNER_TOKEN="paste-your-runner-token-here"

You then need to make a few adjustments to docker-compose-runner.yml:

1. Change the CVESCAN_RUNNER_ENDPOINT value. Since the runner is no longer on the same Docker network as the API, it cannot reach it using its service name. You need to replace this value with the public URL of your CVEScan Web instance.
2. Remove the depends_on section. It refers to services that do not exist on this host.
3. Remove the networks section. The cvescan-internal network only exists on the host where CVEScan Web is deployed. On a standalone host, the runner does not need to join any specific network and can use the default one.

Once these changes are made, start the runner with:

docker compose -f docker-compose-runner.yml up -d

You can repeat this process on as many machines as you want. Each runner needs its own token, so make sure to register a new runner from the WebUI for every machine you deploy.

Step 5. Verify that the runner is connected

Once the runner is started, go back to the runners page in the WebUI. Each runner displays its last activity time, which is updated every time it contacts the API. If the value is recent and keeps refreshing, your runner is correctly connected and ready to pick up scan jobs.