Scan Docker images in a GitLab continuous integration process (CI)

GitLab allows users to scan a container in a CI via an external scanner. This allows including a CI step in which Cyberwatch will generate the vulnerabilities list and the SBOM of the scanned Docker image. Users with access to the GitLab Ultimate features will be able to see directly in the GitLab interface the vulnerabilities detected in the scanned image, as well as the list of packages detected.

We will see how to configure and use this feature.

Prerequisites

In order to be able to use this feature, you must have previously configured a Docker Engine. Cyberwatch comes with an integrated Docker Engine. However, if you want to use your own Docker engine, the procedure is explained here.

Configuring a container scanner

In order to allow GitLab to connect to Cyberwatch, you have to configure a container scanner:

  1. Click on Administration.
  2. Click on External tools.
  3. Click on the Container scanners tab.
  4. Click on the Add button.
  5. Choose a name and select the “GitLab” target.
  6. Choose the source and, if you have registered many of them, the Docker Engine that will be used for the image scans.
  7. Save.

You will get the necessary data to add Cyberwatch as a container scanner in GitLab. Remember to save them, they will no longer be accessible later.

It is possible to create several credentials and thus define several scanners in several CI. This allows you to configure the scanner to use for each project. We can thus distribute Docker image scans between nodes in a multi-node instance or add concurrency on the same node.

It is also possible to adjust the delay between two API requests. This value corresponds at the interval between two API requests when creating the vulnerability report of a Docker image.

A value too small can cause API overload problems, whereas a value too big will unnecessarily extend the time needed to scan an image. The default is 30 seconds.

Adding Cyberwatch as a container scanner

You can now add Cyberwatch as a container scanner for your GitLab CI:

In order to tell GitLab that we use Cyberwatch as a container scanner, you have to modify the gitlab-ci.yml file of the project to integrate the following extract or a variation:

stages:
  - test # Required

include:
  - template: Jobs/Container-Scanning.gitlab-ci.yml # Required

container_scanning: # name MUST NOT be modified
  stage: test # Required
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event" # Modifiable
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH # Modifiable
  variables:
    CS_IMAGE: $CI_REGISTRY_IMAGE:$CI_COMMIT_REF_SLUG # Modifiable
    CS_ANALYZER_IMAGE: cyberwatch/ci-container-scanner # Required

Some required environment variables must be configured in order to allow the Docker image scanner to access Cyberwatch:

  • CYBERWATCH_SCANNER_ENDPOINT: Previously configured endpoint.
  • CYBERWATCH_SCANNER_USER: Username associated to the endpoint.
  • CYBERWATCH_SCANNER_PASSWORD: Password associated to the user.

In addition to required variables, some other variables can be used to configure the access to Cyberwatch:

  • CYBERWATCH_SCANNER_INSECURE: (default: unset). If the variable is configured, then the connection between the scanner container and Cyberwatch will be unsafe. Using this option is not recommended.

More information are available in the GitLab documentation on variables.

The Docker registry is automatically deduced from the scanned image. The access to the registry is made with credentials given as environment variables to the GitLab CI, as following:

  • CS_REGISTRY_USER: Identifier used for the registry login.
  • CS_REGISTRY_PASSWORD: Password used for the registry login.

The procedure for adding these environment variables to your project is as follows:

  1. Connect to GitLab with an account that can access the settings page of the project concerned.
  2. On the project page, unfold the “Settings” menu and go to the CI/CD part.
  3. Unfold the “Variables” section.
  4. Add the CYBERWATCH_SCANNER_ENDPOINT, CYBERWATCH_SCANNER_USER, CYBERWATCH_SCANNER_PASSWORD environment variables, and if needed, the CS_REGISTRY_USER and CS_REGISTRY_PASSWORD environment variables.

Once the environment variables are saved and the gitlab-ci.yml file is added, the $CS_IMAGE will be scanned by Cyberwatch. In the “container_scanning” job artifacts, you will find two files:

  • gl-container-scanning-report.json : The vulnerability report parsed by GitLab following the specification available here.
  • gl-sbom-report-cdx.json : The image SBOM in the CycloneDX format, of which the specification is available here.

Back to top