Integrating Trivy vulnerability scanner for containers into GitLab CI/CD pipeline

Trivy is a simple and comprehensive open source tool from Aqua Security to scan container images for vulnerabilities in OS packages and language-specific dependencies.

Trivy Vulnerability Scanner joined the Aqua Security last year. Unlike other open source scanners, Trivy covers both OS packages and language-specific dependencies and is extremely easy to integrate into CI/CD pipelines.

Features

Detect comprehensive vulnerabilities

• OS packages (Alpine, Red Hat Universal Base Image, Red Hat Enterprise Linux, CentOS, Oracle Linux, Debian, Ubuntu, Amazon Linux, openSUSE Leap, SUSE Enterprise Linux, Photon OS and Distroless)
• Application dependencies (Bundler, Composer, Pipenv, Poetry, npm, yarn and Cargo)

Simple

• Specify only an image name or artifact name

Fast

• The first scan will finish within 10 seconds (depending on your network). Consequent scans will finish in single seconds.

Easy installation

• No pre-requisites such as installation of DB, libraries, etc.

High accuracy

• Especially Alpine Linux and RHEL/CentOS

DevSecOps

• Suitable for CI such as Travis CI, CircleCI, Jenkins, GitLab CI, etc.

Support multiple formats

• container image
• local filesystem
• remote git repository

GitLab Integration

This part of the post documents requirements and guidelines for writing CI jobs that implement a Trivy vulnerability scanner for containers, as well as requirements and guidelines for the Docker image.

Job definition

Include the CI job in your existing .gitlab-ci.yml file. For consistency, scanning jobs should be named after the scanner, in lower case. The job name is suffixed after the type of scanning: trivy_container_scanning.

Stage

For consistency, scanning jobs should belong to the test stage when possible. The stage keyword can be omitted because test is the default value.

Image

The image keyword is used to specify the Docker image containing the security scanner.

stages:
  - test

trivy_container_scanning:
  stage: test
  image: docker:stable
  services:
    - name: docker:dind
      entrypoint: ["env", "-u", "DOCKER_HOST"]
      command: ["dockerd-entrypoint.sh"]
  variables:
    DOCKER_HOST: tcp://docker:2375/
    DOCKER_DRIVER: overlay2
    DOCKER_TLS_CERTDIR: ""
    IMAGE: nginx:1.14.0

Variables

All CI variables are passed to the scanner as environment variables.

Fail-safe

Scanning jobs should not block the pipeline whether it’s not defined explicitly, so the allow_failure parameter should be set to true.

allow_failure: true

Script

It is common practice to use before_script to install required components before performing container scanning.

before_script:
  - export TRIVY_VERSION=$(wget -qO - "https://api.github.com/repos/aquasecurity/trivy/releases/latest" | grep '"tag_name":' | sed -E 's/.*"v([^"]+)".*/\1/')
  - echo $TRIVY_VERSION
  - wget --no-verbose https://github.com/aquasecurity/trivy/releases/download/v${TRIVY_VERSION}/trivy_${TRIVY_VERSION}_Linux-64bit.tar.gz -O - | tar -zxvf -

The script keyword is used to specify the commands to run the scanner.

script:
  # Build image
  - docker build -t $IMAGE .
  # Build report
  - ./trivy --exit-code 0 --cache-dir .trivycache/ --no-progress --format template --template "@contrib/gitlab.tpl" -o gl-container-scanning-report.json $IMAGE
  # Print report
  - ./trivy --exit-code 0 --cache-dir .trivycache/ --no-progress --severity HIGH $IMAGE
  # Fail on critical vulnerability
  - ./trivy --exit-code 1 --cache-dir .trivycache/ --severity CRITICAL --no-progress $IMAGE
cache:
  paths:
    - .trivycache/

Exit Code

Following the POSIX exit code standard, the scanner will exit with 0 for success and any number from 1 to 255 for anything else. Success also includes the case when vulnerabilities are found.

Artifacts

Scanning jobs must declare a report that corresponds to the type of scanning they perform, using the artifacts:reports keyword. Valid reports are: dependency_scanning, container_scanning, dast, and sast.

artifacts:
    reports:
      container_scanning: gl-container-scanning-report.json

Output

Like any artifact uploaded to the GitLab CI/CD, the Secure report generated by the scanner must be written in the project directory, given by the CI_PROJECT_DIR environment variable.

Trivy is now available under the Apache 2 license, allowing royalty-free use, modification, and distribution of the software. Trivy will be included as the default scanner in Harbor, a popular open source container image registry project under the Cloud Native Computing Foundation.