Integrating Trivy Vulnerability Scanner with GitLab CI/CD Pipelines

What is Trivy?

Trivy is a simple open‑source vulnerability scanner developed by aquasecurity that scans containers and other artifacts using static analysis, and is commonly integrated into CI pipeline stages.

What does Trivy do?

It detects container‑level vulnerabilities and dependency issues by scanning CVEs. Trivy can be run as a standalone binary or integrated into CI systems.

How to install Trivy?

The official GitHub repository provides clear installation instructions. For example:

curl -sfL https://raw.githubusercontent.com/aquasecurity/trivy/master/contrib/install.sh | sh -s -- -b /usr/local/bin

Scanning an image

Scanning a Docker image is straightforward:

trivy image <image name>

In this tutorial we scan the deliberately vulnerable image knqyf263/vuln-image:1.2.3 to demonstrate the output.

Saving results

The scan output can be saved in various formats. To store results as JSON:

trivy image -f json -o trivy.json <image>

The -f flag selects the format and -o specifies the output file.

CI/CD pipeline integration

Below is a minimal .gitlab-ci.yml that integrates Trivy into a GitLab pipeline. It builds a Docker image, downloads Trivy, and runs two scans with different severity thresholds.

stages:
  - test
trivy:
  stage: test
  image: docker:stable-git
  before_script:
    - docker build -t trivy-ci-test .
    - wget https://github.com/aquasecurity/trivy/releases/download/v0.1.6/trivy_0.1.6_Linux-64bit.tar.gz
    - tar zxvf trivy_0.1.6_Linux-64bit.tar.gz
  variables:
    DOCKER_DRIVER: overlay2
  allow_failure: true
  services:
    - docker:stable-dind
  script:
    - ./trivy --exit-code 0 --severity HIGH --no-progress --auto-refresh trivy-ci-test
    - ./trivy --exit-code 1 --severity CRITICAL --no-progress --auto-refresh trivy-ci-test

The first command exits with code 0 if only high‑severity issues are found; the second exits with code 1 for critical issues, causing the pipeline to fail when such vulnerabilities are detected.

Understanding the exit codes

According to Trivy documentation, any non‑zero exit code marks the job as failed. In our example, the presence of critical vulnerabilities triggers a failure.

Demonstration of failing and passing builds

When both scan commands are present, the pipeline fails and the GitLab job shows the vulnerability list. By removing the second command (the critical‑severity scan) and keeping only the high‑severity scan, the pipeline succeeds.

Conclusion

Trivy is a lightweight, well‑documented open‑source vulnerability scanner. This guide shows how to use Trivy locally and how to embed it in a GitLab CI/CD pipeline for automated security checks. For full details, refer to the official GitHub documentation and the example repository at https://gitlab.com/ironspideytrip/trivy-test/ .