Infrastructure check
The infrastructure check looks for misconfigurations in the infrastructure files a merge request touches: a container running as root or privileged, a security group open to the internet, a storage bucket readable by anyone, a Dockerfile that never drops root. These are not bugs in code; they are settings that give an attacker a way in once the change is deployed.
In the policy it is the Infrastructure row of the Checks tab (API: controls.iac); the merge request's checklist calls it Infrastructure check.
What it reads
| Type | Files | What is checked |
|---|---|---|
| Terraform | *.tf, *.tf.json, *.tfvars | The whole directory of a changed file, as Terraform reads it |
| Kubernetes | .yaml, .yml, .json holding Kubernetes objects | The changed file |
| Helm | Any file inside a chart (a directory with a Chart.yaml) | The whole chart, rendered with its own values |
| Dockerfile | Dockerfile, Containerfile and their variants | The changed file |
| CloudFormation | .yaml, .yml, .json templates | The changed file |
| Azure ARM | .json templates | The changed file |
File types checked chooses the types (all by default). Files not checked lists file patterns left out.
- At most Max infrastructure files per change changed files (50 unless the company sets another number, at most 500); a merge request changing more fails the check. At most 1,000 files are read in all (Terraform directories and charts are read whole).
- When the VCS lists only part of the merge request's changed files, the check fails.
The first two follow the company's When a scan cannot see everything (see Scanning); a policy can set its own. With Check the first ones up to the limit or Check what was listed, the check looks at those and names what it did not look at in the control's reason (Not looked at: …). A check failed this way, or by the limit of 1,000 files read, is not retried by itself.
- A Terraform module from a remote address is downloaded for the check; one that cannot be reached is listed as checked without it. Module downloads follow the same network rule as image pulls (see Internal hosts).
Only what the change introduces
The files are checked at the merge request's head and at the merge base. A finding the target branch already has in the same file (the same check on the same resource) is not the change's doing: it is not reported, and the card says how many there were. A finding moving to another line is still the same finding.
Files that cannot be checked
A file that does not parse, or a Helm chart that does not render without the values it is installed with (required values, fail), cannot be checked. By default this fails the check: a file nobody could look at does not pass as clean. With Changed files that cannot be checked: List only it is listed on the merge request and does not count. A chart that needs install values can also be left out with Files not checked.
What holds the merge
Fail from severity (low, medium, high or critical; default high): findings at or above it count; lower ones are listed. Checks left out lists check IDs that are never reported (KSV-0017, AWS-*).
Modes
| Mode (label in the UI) | API value | What it does |
|---|---|---|
| Off | off | The check does not run. This is the default of a new policy |
| Report | report | The check runs and its result is shown; it never holds the merge |
| Enforce | block | The merge gate waits while the check runs, and is blocked while it fails |
What the control says
| Result | Shown as |
|---|---|
| Running, or not run yet for the head commit | Checking the changed infrastructure files. |
| Nothing introduced | No misconfigurations introduced in the changed infrastructure files. |
| Only lower findings | No misconfigurations of high severity or higher introduced; N lower-severity finding(s) reported. |
| Findings count | N misconfiguration(s) of high severity or higher introduced in the changed infrastructure files. |
| A file cannot be checked | N changed infrastructure file(s) could not be checked (see the merge request). |
| The check could not be completed | The infrastructure check could not be completed: … |
Settings
In the policy
| Setting (label in the UI) | Default | API field |
|---|---|---|
| Infrastructure | Off | controls.iac.mode (off, report, block) |
| Fail from severity | high | controls.iac.min_severity |
| File types checked | Company setting | controls.iac.overrides.types |
| Changed files that cannot be checked | Company setting | controls.iac.overrides.unchecked (fail, note) |
| Checks left out | Company setting | controls.iac.overrides.skipped_checks |
| Files not checked | Company setting | controls.iac.overrides.skipped_paths |
Company default
On the company page, Scanning tab, section Infrastructure:
| Setting (label in the UI) | Default | API field |
|---|---|---|
| File types checked | All | scanning.iac.types (absent or null: all; []: none) |
| Changed files that cannot be checked | Fail the check | scanning.iac.unchecked (fail, note) |
| Checks left out | Empty | scanning.iac.skipped_checks |
| Files not checked | Empty | scanning.iac.skipped_paths |
| Max infrastructure files per change | 50 (at most 500) | scanning.iac.max_files |
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
iac_scanjob runs (see Jobs). - Re-scan on the merge request's Infrastructure check card starts it again (
POST /api/v1/merge-requests/{id}/rescanwith{"scan": "iac"}). - When the check 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.
- On watched repositories it runs only when the company scans watched merge requests.
What the merge request shows
- The Infrastructure check card: each finding with its file and lines, severity, check (linked to its description), the problem and how to fix it; how many findings the target branch already had; files that could not be checked.
- One comment on the merge request, kept up to date.
- The audit log records
iac_problems_detectedwhen a check finds misconfigurations, and the notification Infrastructure problems in a merge request goes to the routes that take it and to the author (see Events).
The default branch's infrastructure
While the company's Follow the default branches' infrastructure files is on (the default, on the Scanning tab → Dependencies; see Scanning), each project analysis also checks the default branch's infrastructure files, whatever the policies' modes, (Terraform, Dockerfiles, YAML and Helm charts; JSON templates are left out there) and keeps their findings, from first seen until fixed, under Infrastructure on the Vulnerabilities page and on the project's Security tab:
- Only the directories, charts and files that changed since the last analysis are read and checked again.
- A finding is fixed when its file is checked again without it, or its file is gone from the branch. A part that could not be read keeps its findings.
- The first check of a project records what was already there as its baseline.
- The merge request a finding came with, and the one that fixed it, are named.
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 →