Welcome to Support Portal

TABLE OF CONTENTS

• Introduction
• Applicability
• Prerequisites
• Steps/Procedure
• Tips and Tricks
• Troubleshooting
• Conclusion
• Additional Resources

Introduction

This article explains how to integrate GitLab CI/CD with Aqua Security Scanner to perform container image scanning as part of a CI/CD pipeline in an Aqua Enterprise On-Prem deployment (2022.4.x).

This guide demonstrates how to:

• Install and configure a GitLab Runner

• Integrate Aqua Scanner into GitLab pipeline

• Scan container images from a private registry

• Register scanned images in Aqua Console

• Validate scan results in Aqua UI

This KB applies to Aqua On-Prem environments.
For Aqua SaaS environments, token-based authentication must be used instead of username/password.

Applicability

• Aqua Enterprise (On-Prem) 2022.4.x

• GitLab Enterprise

• GitLab Runner 15.0.1 (Self-hosted)

• Docker-based image builds

• Images hosted in private registries (Azure ACR / Support registry)

Prerequisites

Before proceeding, ensure the following components are available: 

1. Aqua Environment

• Aqua Console installed and accessible

                http://<AQUA_CONSOLE_IP>:8080 

• Scanner image available: 

                registry.aquasec.com/scanner:2022.4.868   

•  Valid Aqua credentials:

                AQUA_USER

                AQUA_PASSWORD

 2. GitLab Runner Options Overview

             GitLab supports multiple runner deployment models:

? In this KB, we focus on:

✅ Self-Hosted GitLab Runner (Version 15.0.1) using Docker Executor

3️. System Requirements

• Linux VM for runner installation

• Docker installed:

  docker --version

• GitLab registration token available

Steps/Procedure

Step 1 – Login to GitLab

Access your GitLab instance:

https://gitlab.<domain>.com

Step 2 – Install Self-Hosted GitLab Runner (v15.0.1)

Download runner binary:

curl -L "https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh" -o script.deb.sh

chmod +x script.deb.sh
./script.deb.sh
sudo apt-get install gitlab-runner=15.11.0
gitlab-runner --version
gitlab-runner status

Step 3 – Register the Runner

sudo gitlab-runner register

Provide:

• GitLab URL

• Registration Token

• Description: aqua-scan

• Tags: local-docker

• Executor: docker

• Default image: docker:24

Fetch the registration token from Gitlab GUI as shown below:

Step 4 – Configure Runner (Important)

Edit:

/etc/gitlab-runner/config.toml

Ensure:

[runners.docker]
  privileged = true
  volumes = ["/var/run/docker.sock:/var/run/docker.sock", "/cache"]

Restart runner:

sudo gitlab-runner restart

Step 5 – Validate Runner

From local VM:

sudo gitlab-runner status
sudo gitlab-runner verify

From GitLab GUI:

Project → Settings → CI/CD → Runners
Confirm runner is:

• Active

• Online

• Tagged correctly

Step 6 – Create New GitLab Project

• Create new blank project

• Initialize repository

Step 7 – Configure CI/CD Variables

Navigate to:

Project → Settings → CI/CD → Variables

Add:

Mark as:

• Masked

• Protected

Step 8 – Create .gitlab-ci.yml

Add at repository root:

stages:
  - scan

aqua_scan:
  stage: scan
  tags: ["local-docker"]
  image: docker:24.0.5

  variables:
    DOCKER_HOST: "unix:///var/run/docker.sock"
    FULL_IMAGE_PATH: "aquasupport.azurecr.io/kalingo-0307:libavif-fp-test-v1"
    AQUA_SCANNER: "registry.aquasec.com/scanner:2022.4.868"

  script:
    - docker version
    - echo "$AQUA_REGISTRY_PASSWORD" | docker login -u "$AQUA_REGISTRY_USER" --password-stdin registry.aquasec.com
    - echo "$AZURE_REGISTRY_PASSWORD" | docker login -u "$AZURE_REGISTRY_USER" --password-stdin aquasupport.azurecr.io
    - docker pull "$FULL_IMAGE_PATH"

    - |
      docker run --rm \
        -v /var/run/docker.sock:/var/run/docker.sock \
        "$AQUA_SCANNER" \
        scan \
        --host "$AQUA_SERVER" \
        --user "$AQUA_USER" \
        --password "$AQUA_PASSWORD" \
        --registry "aquasupport" \
        --local "$FULL_IMAGE_PATH"     \
        --register \
        --hide-base \
        --show-negligible

Step 9 – Execute Pipeline

• Commit and push

• Navigate to CI/CD → Pipelines

• Open scan job

Step 10 – Validate Scan Logs

Confirm in job output:

• Docker login successful

• Image pulled

• Scanner connected to Aqua

• Image registered successfully

Step 11 – Validate in Aqua Console

Login to Aqua Console:

http://<AQUA_CONSOLE_IP>:8080

Navigate to:

Images → Registries → Scanned Images

Verify:

• Image appears

• Scan result status

• Vulnerability breakdown

Tips and Tricks

Enable Debug Mode

Add:

-e SCALOCK_LOG_LEVEL=DEBUG

Use Token Authentication (SaaS Only)

Replace:

--user / --password

With:

--token <SCANNER_TOKEN>

Troubleshooting

Issue: Cannot connect to Docker daemon

Cause:

• Missing docker.sock mount

• DOCKER_HOST incorrectly set

Fix:

• Update runner config volumes

• Set:

  DOCKER_HOST=unix:///var/run/docker.sock

Issue: Scan results not uploaded

Reference: Scan results not uploaded

Verify:

• Aqua server URL

• Authentication

• Network connectivity

Conclusion

By following this guide, you have successfully:

• Deployed a self-hosted GitLab Runner

• Integrated Aqua Scanner into GitLab CI/CD

• Scanned and registered images in Aqua Console

• Validated results within Aqua UI

This setup enables automated container security scanning in CI/CD pipelines and enforces image assurance policies early in the development lifecycle.

Additional Resources

• GitLab CI Quick Start
  https://gitlab.aquasec.com/help/ci/quick_start/README

• Scan artifact troubleshooting
  https://support.aquasec.com/support/solutions/articles/16000142275-gitlab-ci-cd-pipeline-does-not-upload-scan-artifacts

• Scanner authentication (SaaS token)
  https://support.aquasec.com/support/solutions/articles/16000199156-saas-scanner-in-ci-cd-pipeline-requires-token-for-authentication-instead-of-user-password-for-on-prem