Scanning container images with Trivy in GitLab CI

Wire Trivy into your pipeline, fail builds on criticals without blocking every merge, and cache the vuln DB so scans stay under 30 seconds.

Whether an image contains known vulnerabilities is not in doubt; every base image does. The question a pipeline decides is where you learn about them: in the merge request that introduced the base image, or in the incident channel after it has been the default deploy target for a month. The difference is entirely in job ordering. A scan that runs after docker push is a report; a scan that the push job depends on is a control.

The pipeline

Build saves the image as a tar artifact so the scan jobs read exactly the bytes that will be pushed, without pulling from a registry they are supposed to be protecting. The build job is shown with docker; on runners without a Docker socket, buildah build followed by buildah push … oci:image/ produces an OCI layout that trivy image --input reads the same way. The scanner image is pinned to a version; a floating tag on the tool that enforces policy is a supply-chain hole of its own. The vulnerability database is pulled as an OCI artifact from mirror.gcr.io/aquasec first and ghcr.io/aquasecurity second; caching TRIVY_CACHE_DIR under a project-wide key means one download per DB update instead of one per job, which also keeps a busy runner fleet away from registry rate limits.

variables:
  IMAGE: "$CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA"
  TRIVY_CACHE_DIR: .trivycache/
 
stages: [build, scan, push]
 
build:
  stage: build
  script:
    - docker build -t "$IMAGE" .
    - docker save "$IMAGE" -o image.tar
  artifacts:
    paths: [image.tar]
    expire_in: 1 day
 
.trivy:
  stage: scan
  image:
    name: aquasec/trivy:0.74.0
    entrypoint: [""]
  cache:
    key: trivy-db
    paths: [.trivycache/]
  needs: [build]
 
scan-report:
  extends: .trivy
  script:
    - trivy image --input image.tar --severity LOW,MEDIUM,HIGH,CRITICAL --exit-code 0
    - trivy image --input image.tar --format cyclonedx --output sbom.cdx.json
  artifacts:
    paths: [sbom.cdx.json]
 
scan-gate:
  extends: .trivy
  script:
    - trivy image --input image.tar --severity CRITICAL --ignore-unfixed --exit-code 1
 
push:
  stage: push
  needs: [build, scan-gate]
  script:
    - docker load -i image.tar
    - docker push "$IMAGE"

Why CRITICAL only, and why two passes

A gate that blocks on every HIGH in a freshly adopted base image is disabled within a month, usually with allow_failure: true and a comment promising to revisit. The report pass keeps the full list visible in every pipeline so the backlog is known; the gate pass blocks only on what a developer can fix now, so --ignore-unfixed is on it. Tightening is a per-project decision to make when the backlog is short: move HIGH into the gate pass for a service once its report has been clean at that level for a few weeks, not for the whole organisation on a date.

Two things make the gate a control rather than a report. scan-gate carries no allow_failure, so a red gate fails the pipeline and the push stage never starts. And push names the gate in needs, which makes the dependency explicit rather than a side effect of stage order: a job with needs runs only when every job it lists has succeeded, however the stages are rearranged later. When the gate is red, the image tagged with that commit exists only as an artifact that expires in a day.

When the gate is wrong: recovery in order of preference

The same two flags drive the dependency scan on the source tree one stage earlier, where the suppression file with reasons and expiry dates is described. After the gate, the natural next control is to sign the image that passed, so that admission in the cluster can distinguish an image this pipeline vouched for from one that merely has the same name.

Related posts

Quick reference