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:
| File | References |
|---|---|
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/amd64unless 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
| Setting | What counts |
|---|---|
| Fail from severity (in the policy) | Vulnerabilities at or above it (low, medium, high or critical; default high) |
| Vulnerabilities without a fix | List 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 rating | Listed, 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 value | What it does |
|---|---|---|
| Off | off | The scan does not run. This is the default of a new policy |
| Report | report | The scan runs and its result is shown; it never holds the merge |
| Enforce | block | The merge gate waits while the scan runs, and is blocked while it fails |
What the control says
| Result | Shown as |
|---|---|
| Running, or not run yet for the head commit | Scanning the container images the change refers to. |
| No new images | The change refers to no new container images. |
| Nothing counts | No vulnerabilities of high severity or higher that hold the change in N new image(s); M other vulnerabilities listed. |
| Vulnerabilities count | N vulnerabilities of high severity or higher in M of the new image(s). |
| A reference cannot be resolved | N image reference(s) depend on a variable or template, so the image cannot be known and was not scanned. |
| The scan could not be completed | The container image scan could not be completed: … |
Settings
In the policy
| Setting (label in the UI) | Default | Allowed values | API field |
|---|---|---|---|
| Container images | Off | Off, Report, Enforce | controls.images.mode (off, report, block) |
| Fail from severity | high | low, medium, high, critical | controls.images.block_severity |
| Vulnerabilities without a fix | Company setting | List only, Count like the others | controls.images.overrides.block_unfixed |
| Image references that cannot be resolved | Company setting | Fail the check, List only | controls.images.overrides.unresolved (fail, note) |
| Vulnerabilities without a rating | Company setting | Listed, never held, Count them as high, Always hold | controls.images.overrides.unknown_severity (show, high, block) |
| Images not scanned | Company setting | Image names, * wildcards | controls.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) | Default | API field |
|---|---|---|
| Hold for vulnerabilities without a fix | Off | scanning.images.block_unfixed |
| Image references that cannot be resolved | Fail the scan | scanning.images.unresolved (fail, note) |
| Vulnerabilities without a rating | Listed, never held | scanning.images.unknown_severity (show, high, block) |
| Images not scanned | Empty | scanning.images.skipped_images |
| Platform | linux/amd64 | scanning.images.platform |
| Max new images per change | 20 (at most 100) | scanning.images.max_images |
| Internal hosts | Empty | scanning.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_scanjob 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}/rescanwith{"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_detectedwhen 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.
Related pages
Video tutorial
Short videos of this feature working on real GitLab and Jira projects. English audio, English and Turkish subtitles. All video tutorials →