TABLE OF CONTENTS

Overview

This topic explains how to configure your GitLab instance with Aqua scanner to scan images in the CI/CD pipeline. This process assumes that you already have a GitLab Runner on an existing Linux server that will execute the build. The same server will be used to invoke the Aqua scanner.


This integration procedure has the following four configurations:

  1. Add the Gitlab-runner user to the Docker group
  2. Add the scanner credentials as variables
  3. Modify the YAML script
  4. Verify the Aqua step in the pipeline


Prerequisite

Before you configure the Aqua with GitLab, make sure that:

  • You have scanner permission assigned by your Aqua admin.
  • You have added the registry to the image registry integrations in Aqua UI, from which you want to build and scan images in GitLab


Add the Gitlab-runner user to the Docker group

This section shows command to add Gitlab user to the Docker group in the server. This is required for the server to receive Docker commands from the specific user to scan images using Aqua scanner. 


You should pass the following command for the Runner to permit the gitlab-runner user to execute Docker commands.


sudo usermod -aG docker gitlab-runner


For more information, refer to GitLab document, GitLab Runner Executor.


Add the scanner credentials as variables

You can add CI/CD variables to a project’s settings. To keep a CI/CD variable secret, put it in the project settings, not in the .gitlab-ci.yml file.


To add variables in the project settings:

  1. In the GitLab application, open your required project.
  2. In the left pane, navigate to Settings > CI/CD page > Variables section.
  3. Click Add variable.



     3. In the Add variable dialog, create key-value pairs for User and Password by entering the following details:

  • Key
  • Value
  • Select Type, Environment scope, as required
  • Enable the Project variable and Mask variable checkboxes, as required.

     4. Click Add variable.



For more information, refer to GitLab document, Project CI/CD variables.


Pass the YAML script

This section shows the YAML script for integrating Aqua command line image scanner. Through this script, Aqua scanner is integrated with your CI/CD pipeline and images will be scanned, and results will be shared after next successful passing of the pipeline. Following is the sample .gitlab-ci.yaml script which includes Aqua scanner command line. You should edit the following script with correct parameters (such as scanner version, user, password, and so on) and pass this script in your project > pipeline. Before you proceed running the following YAML script, the registry from which you want to scan an image should be added in the Image Registry integrations in your Aqua UI.


Following script helps you scan an image from the specified registry:

customer_image_build:
  script:
  - echo "This represents your build of the Docker image"
  
scanner:
  script:
  - docker login registry.aquasec.com -u $USER -p $PASSWORD
  - docker pull registry.aquasec.com/scanner:6.2
  - docker run --rm -v /tmp:/tmp -v /var/run/docker.sock:/var/run/docker.sock registry.aquasec.com/scanner:6.2 scan --registry "Docker Hub" mongo:latest --host https://train.aquasec.com/ --user $USER --password $PASSWORD --show-negligible --html --htmlfile out.html --jsonfile out.json > /dev/null

    # Copy artifacts to local directory
    - cp /tmp/out.html /tmp/out.json
  artifacts:
    paths:
    - out.json
    - out.html


If you want to scan a local image, you should pull it first from Docker Hub and pass the --local flag to scan the specific image. Following script helps you scan a local image:


customer_image_build:
  script:
  - echo "This represents your build of the Docker image"
  
scanner:
  script:
  - docker login registry.aquasec.com -u $USER -p $PASSWORD
  - docker pull registry.aquasec.com/scanner:6.2
  - docker pull mongo:latest
  - docker run --rm -v /tmp:/tmp -v /var/run/docker.sock:/var/run/docker.sock registry.aquasec.com/scanner:6.2 scan --local mongo:latest --host https://train.aquasec.com/ --user $USER --password $PASSWORD --show-negligible --html --htmlfile out.html --jsonfile out.json > /dev/null

    # Copy artifacts to local directory
    - cp /tmp/out.html /tmp/out.json
  artifacts:
    paths:
    - out.json
    - out.html


Following screenshot shows the pipeline editing page from GitLab application:


Parameters that are shown in the script are just for reference only. You should replace them with correct values.



For more information on developing yaml script, refer to GitLab document, Keyword reference for the .gitlab-ci.yml file.


After passing the YAML script in the pipeline, you should run the pipeline, for Aqua to execute image scanning during build.


Verify the Aqua step in the pipeline

After running the pipeline with Aqua step, you can see that a new run in the pipeline called scanner as show below. To verify the Aqua step, you should navigate to CI/CD > Pipelines > select the required pipeline.



View scan output

After scanning image by running the job, you can see scan output by clicking the status icon of the scanner job at the CI/CD > Jobs page.



You can see the scan output as shown below: