Skip to main content
Video tutorial · 1:12

Container image scan

The container image scan checks the container images a merge request starts referring to for packages with known vulnerabilities. A Dockerfile's base image, or an image a Kubernetes manifest deploys, brings its operating system packages and libraries with it: a vulnerability in them ships with the change even though no line of the project's own code has one. The project's own dependencies are covered by the dependency scan; this control covers the images.

In the policy it is the Container images row of the Checks tab (API: controls.images); the merge request's checklist calls it Container image scan.

What it reads​

The scan reads the files the merge request adds or changes, as they are at its head commit, and finds the image references in them:

FileReferences
Dockerfile, Containerfile, *.Dockerfile, Dockerfile.*FROM lines (with --platform), and COPY --from= naming an image. ARG defaults are filled in; build stages named with AS and scratch are not images
Kubernetes manifests (.yaml, .yml with apiVersion and kind)The image of every container, init container and ephemeral container, in any kind of workload, also in files holding several documents
Helm values (values*.yaml)image: <name>, and image: blocks with repository and, optionally, registry, tag and digest (global.imageRegistry fills an empty registry)
Compose files (docker-compose*.yml, compose*.yaml)services.<name>.image; a ${VAR:-default} is filled in with its default

Each reference is written out in full before it is compared or scanned: nginx is docker.io/library/nginx:latest, a tag or digest is kept.

Only new references are scanned. The same files are read at the merge base, and an image the target branch already refers to in them is not scanned again: a change that touches a Dockerfile without changing its base image is not held for that image. When the merge request targets the default branch and the company follows its images (Follow the container images the default branches refer to), an image the default branch already uses in any file, as its last analysis read it, is not new either: a new manifest deploying an image the branch already builds from is not held for it. Other images that the branch's last analysis did not see are scanned. The default branch's images are followed in the vulnerability inventory instead.

  • At most 100 changed files are read for references; a merge request changing more fails the scan.
  • At most Max new images per change images are scanned (20 unless the company sets another number, at most 100); a merge request referring to more fails the scan.
  • When the VCS lists only part of the merge request's changed files, the scan fails: a changed reference may have been missed.

These three follow the company's When a scan cannot see everything (see Scanning): with Check the first ones up to the limit or Check what was listed, the scan checks those and names what it did not look at in the control's reason (Not looked at: …). A scan failed this way is not retried by itself, and says Trying again would not change this.

References that cannot be resolved​

A reference that depends on something only known when the image is built or deployed (FROM ${BASE} without a default, image: {{ .Values.image }} in a template, image: $IMAGE) cannot be scanned. By default it fails the scan, so an image nobody could see does not pass as clean. With Image references that cannot be resolved: List only it is listed on the merge request and does not count.

Images not scanned​

Images not scanned lists image names that are never scanned, with * wildcards (registry.example.com/base/*).

How an image is scanned​

Each new image is pulled from its registry and its operating system packages and language libraries are looked up for known vulnerabilities. The vulnerability data is downloaded by Merge Pilot and kept up to date (twice a day by default); an image scanned once is not pulled again the same day, whichever merge request refers to it.

  • Platform: an image built for several platforms is scanned for Platform (linux/amd64 unless the company sets another).
  • Private registries: an image in a registry the company has a sign-in for (Company → Scanning → Container registries, see Scanning) is pulled with that sign-in; the sign-in is used for that registry only. Public images need none.
  • An image that cannot be scanned (not found, the registry refused the sign-in, the registry could not be reached, no vulnerability data yet) makes the scan fail. The merge request shows why for each image.
  • A vulnerability exploited in the wild (on the CISA KEV list) counts as critical when the company's dependency scan setting does so (the default), and is marked either way.
  • A vulnerability an active exception accepts does not count; exceptions granted after the scan apply at once.

What holds the merge​

SettingWhat counts
Fail from severity (in the policy)Vulnerabilities at or above it (low, medium, high or critical; default high)
Vulnerabilities without a fixList only (the default): a vulnerability with no fixed version yet is listed but does not count, since a developer cannot fix it by updating the image. Count like the others: it counts too
Vulnerabilities without a ratingListed, never held (the default); Count them as high; Always hold: an unrated vulnerability always holds, with or without a fix, whatever Vulnerabilities without a fix says

The scan fails (and holds the merge in Enforce mode) when at least one vulnerability counts, when an image could not be scanned, or when a reference could not be resolved and the company or policy does not list them only.

Modes​

Mode (label in the UI)API valueWhat it does
OffoffThe scan does not run. This is the default of a new policy
ReportreportThe scan runs and its result is shown; it never holds the merge
EnforceblockThe merge gate waits while the scan runs, and is blocked while it fails

What the control says​

ResultShown as
Running, or not run yet for the head commitScanning the container images the change refers to.
No new imagesThe change refers to no new container images.
Nothing countsNo vulnerabilities of high severity or higher that hold the change in N new image(s); M other vulnerabilities listed.
Vulnerabilities countN vulnerabilities of high severity or higher in M of the new image(s).
A reference cannot be resolvedN image reference(s) depend on a variable or template, so the image cannot be known and was not scanned.
The scan could not be completedThe container image scan could not be completed: …

Settings​

In the policy​

Setting (label in the UI)DefaultAllowed valuesAPI field
Container imagesOffOff, Report, Enforcecontrols.images.mode (off, report, block)
Fail from severityhighlow, medium, high, criticalcontrols.images.block_severity
Vulnerabilities without a fixCompany settingList only, Count like the otherscontrols.images.overrides.block_unfixed
Image references that cannot be resolvedCompany settingFail the check, List onlycontrols.images.overrides.unresolved (fail, note)
Vulnerabilities without a ratingCompany settingListed, never held, Count them as high, Always holdcontrols.images.overrides.unknown_severity (show, high, block)
Images not scannedCompany settingImage names, * wildcardscontrols.images.overrides.skipped_images

Policy managers, company admins and platform admins change them.

Company default​

On the company page, Scanning tab, section Container images:

Setting (label in the UI)DefaultAPI field
Hold for vulnerabilities without a fixOffscanning.images.block_unfixed
Image references that cannot be resolvedFail the scanscanning.images.unresolved (fail, note)
Vulnerabilities without a ratingListed, never heldscanning.images.unknown_severity (show, high, block)
Images not scannedEmptyscanning.images.skipped_images
Platformlinux/amd64scanning.images.platform
Max new images per change20 (at most 100)scanning.images.max_images
Internal hostsEmptyscanning.images.internal_hosts

Internal hosts are hosts on private networks the scans may reach besides the registries (for example a registry whose sign-in service runs on another internal host). The scans never reach an address on a private network that is not one of these or a registry's host, nor cloud metadata or loopback addresses: an image reference or a Terraform module address in a merge request cannot make Merge Pilot call into your network. The list is the company's only; a policy cannot widen it.

When it runs​

  • When a merge request is opened or gets a new head commit and its policy has the control in Report or Enforce, an image_scan job runs (see Jobs); the merge request is evaluated again when it ends.
  • Re-scan on the merge request's Container image scan card starts it again (POST /api/v1/merge-requests/{id}/rescan with {"scan": "image"}); refused when the policy does not run the scan.
  • When the scan cannot finish, what happens next follows An image, infrastructure or CI configuration scan could not complete under When a scan cannot see everything (company, or the policy's own): wait for a re-scan (the default) or retry after a pause. A scan failed by a limit or a cut-short file list is not retried.
  • On watched repositories it runs only when the company scans watched merge requests.

What the merge request shows​

  • The Container image scan card: each new image with where it is referred to (file:line), its vulnerabilities by severity, with and without a fix, the exploited ones, and the full list of vulnerable packages on request; references that could not be resolved; why an image could not be scanned.
  • One comment on the merge request (on the VCS), kept up to date, with the same table.
  • The audit log records image_vulnerabilities_detected when a scan finds vulnerabilities, and the notification Vulnerable container images in a merge request goes to the routes that take it and to the author (see Events).

The default branch's images​

While the company's Follow the container images the default branches refer to is on (the default, on the Scanning tab → Dependencies; see Scanning), each project analysis also reads the images the default branch refers to (the same files as above, every one of them), whatever the policies' modes, and puts their vulnerable packages in the vulnerability inventory, beside the dependencies:

  • Their ecosystem is image/ and the package type (image/alpine, image/debian, image/python-pkg, ...), and where they are used is the image.
  • They are scanned again with each analysis and each advisory check, so a vulnerability published for an image already in use appears without a change.
  • A finding is fixed when the branch no longer refers to the image, or the image no longer has the package version. An image that could not be scanned keeps its findings.
  • The first analysis that reads a project's images records what was already there as its baseline: nothing is announced. The same holds for an image whose scans failed until now: when it can be scanned, what it has was already there.
  • Exceptions work for them as for dependencies.

Video tutorial

Short videos of this feature working on real GitLab and Jira projects. English audio, English and Turkish subtitles. All video tutorials →

Container Images and Infrastructure ChecksYouTube ↗