Skip to content

Runners

Overview

A runner is a service dedicated to performing vulnerability scans on software components and reporting the results back to CVEScan Web.

CVEScan Web relies on two distinct types of backend services, each with a clearly defined responsibility:

  • The web backend is the central service. It exposes the API consumed by the WebUI, stores all application data (projects, components, scan results, users) in its database, and orchestrates the scanning work to be performed.
  • The runners are backend services responsible for executing the actual vulnerability scan operations. A runner does not have any access to the web backend database. It pulls scan jobs from the web backend, runs them, and submits the results back through the API. To perform its scans, a runner maintains its own local data store, which is essentially a local replica of external vulnerability databases such as the NVD. This data is kept entirely separate from the web backend database and is refreshed by the runner itself.

The WebUI is the frontend application served to your browser. It only communicates with the web backend, never directly with the runners.

This separation makes the scanning workload independent from the rest of the platform. Each runner is a self-contained service, and several runners can be deployed in parallel to increase scanning throughput. This horizontal scaling model lets you adjust scanning capacity to match your workload by adding or removing runners without any change to the web backend.

Only system administrators can view the runners page in the WebUI and register or delete runners.

How a runner works

Communication between a runner and the web backend follows a polling model. The runner is the one that initiates every exchange by repeatedly asking the web backend whether there is work to do. The web backend never pushes work to a specific runner and does not decide in advance which runner will execute which job. Instead, jobs are assigned on demand: when a runner asks for work, the web backend hands it the next pending job, if any. This keeps the system simple and naturally adapts to the number of runners currently available, whether that number changes because new runners are added or because some of them go offline.

Once a runner is started and connected to the web backend, it follows a simple loop:

  1. The runner asks the API if there is a pending scan job available.
  2. If a job is available, the API hands it over to the runner.
  3. The runner downloads the necessary information, mainly the SBOM to scan, runs the scan operation, and reports the results back to the API.
  4. If a job takes a long time, the runner periodically tells the API that it is working on the job.
  5. When the job is done, the runner asks for the next one and the loop continues.

If a runner crashes or loses connectivity in the middle of a scan, the web backend will stop receiving the periodic keep-alive signals mentioned in step 4. After some time, the job will be marked as failed. The end user will see the failed scan in the WebUI and can decide to start a new scan if needed.

All the coordination concerns that come with running multiple workers in parallel, such as job concurrency, idempotency and unexpected failures, are handled by the web backend transparently. As an end user, you do not need to manage any of this. You request scans, monitor progress, and consult results entirely from the WebUI, while the platform takes care of distributing the work across the available runners behind the scenes.

Where runners can be deployed

A runner only needs two things to operate:

  • Network access to the CVEScan Web API.
  • A token that proves it is allowed to talk to the API.

Because of this, runners can be installed in several places depending on your needs:

  • On the same machine as CVEScan Web. This is the simplest option. The runner joins the same internal Docker network as the API and communicates with it directly.
  • On a separate machine. This is useful when you want to keep the scanning workload away from the machine that hosts the WebUI, or when you need more scanning capacity than a single machine can provide. In this case, the runner connects to the API over the network, just like a regular client.

You can mix both approaches and run several runners across different machines at the same time. All connected runners receive their work from the same web backend, which will send the next pending scan to the next available runner.

Next steps

To learn how to register a new runner and start it, please refer to the Setting Up Runners section of the installation guide.