doc/user/application_security/iac_scanning/_index.md
{{< details >}}
{{< /details >}}
Infrastructure as Code (IaC) scanning runs in your CI/CD pipeline, checking your infrastructure definition files for known vulnerabilities. Identify vulnerabilities before they're committed to the default branch to proactively address the risk to your application.
The IaC scanning analyzer outputs JSON-formatted reports as job artifacts.
With GitLab Ultimate, IaC scanning results are also processed so you can:
If you are new to IaC scanning, follow these steps to enable it for your project.
Prerequisites:
.gitlab-ci.yml) must include the test stage. The test stage is included by
default, but if you redefine stages, you must explicitly add it.To enable IaC scanning:
In the top bar, select Search or go to and find your project.
Go to Build > Pipeline editor.
Add either the IaC scanning CI/CD template or component.
To use the template, add the following lines:
include:
- template: Jobs/SAST-IaC.gitlab-ci.yml
To use the CI/CD component, add the following lines:
include:
- component: gitlab.com/components/sast/iac-sast@main
Select the Validate tab, then select Validate pipeline.
The message Simulation completed successfully confirms the file is valid.
Select the Edit tab.
Complete the fields:
add-iac.Select the Start a new merge request with these changes checkbox, then select Commit changes.
The merge request page opens.
Complete the fields according to your standard workflow, then select Create merge request.
Review and edit the merge request according to your standard workflow, then select Merge.
At this point, IaC scanning is enabled in your pipeline:
The corresponding job appears under the test stage in your pipeline.
You can see a working example in IaC scanning example project.
After you enable IaC scanning, you can:
Prerequisites:
You can review vulnerabilities in a pipeline:
In Ultimate, you can also download the security scan results:
Prerequisites:
For more details, see Pipeline security report.
[!note] Findings are generated on feature branches. When they are merged into the default branch, they become vulnerabilities. This distinction is important when evaluating your security posture.
Additional ways to see IaC scanning results:
IaC scanning supports a variety of IaC configuration files. When any supported configuration files are detected in a project, they are scanned by using KICS. Projects with a mix of IaC configuration files are supported.
Supported configuration formats:
Ansible
AWS CloudFormation
Azure Resource Manager
[!note] IaC scanning can analyze Azure Resource Manager templates in JSON format. If you write templates in Bicep, you must use the Bicep CLI to convert your Bicep files into JSON before IaC scanning can analyze them.
Dockerfile
Google Deployment Manager
Kubernetes
OpenAPI
Terraform
[!note] Terraform modules in a custom registry are not scanned for vulnerabilities. For more information about the proposed feature, see issue 357004.
{{< details >}}
{{< /details >}}
You can optimize IaC scanning to reduce noise and focus on relevant findings:
sast-ruleset.toml file.sast-ruleset.toml file.Use a sast-ruleset.toml file to disable rules or override rule attributes. This approach provides the following:
Every IaC scanning rule is contained in a ruleset section, which contains the following:
type field for the rule. For IaC scanning, the identifier type is kics_id.value field for the rule identifier. KICS rule identifiers are alphanumeric strings.
To find the rule identifier:
You can disable specific IaC scanning rules. Findings previously detected by disabled rules are automatically resolved.
Prerequisites:
To disable analyzer rules:
.gitlab directory at the root of your project, if one doesn't already exist.sast-ruleset.toml in the .gitlab directory, if
one doesn't already exist.disabled flag to true in the context of a ruleset section.ruleset subsections, list the rules to disable.After you merge the sast-ruleset.toml file to the default branch, existing findings for disabled rules are automatically resolved.
In the following example sast-ruleset.toml file, the disabled rules are assigned to
the kics analyzer by matching the type and value of identifiers:
[kics]
[[kics.ruleset]]
disable = true
[kics.ruleset.identifier]
type = "kics_id"
value = "8212e2d7-e683-49bc-bf78-d6799075c5a7"
[[kics.ruleset]]
disable = true
[kics.ruleset.identifier]
type = "kics_id"
value = "b03a748a-542d-44f4-bb86-9199ab4fd2d5"
To disable scanning of a file, either entirely or for only a rule, use KICS annotations in that file.
This feature is only available for some types of IaC files. See the KICS documentation for a list of supported file types.
# kics-scan ignore as a comment at the top of the file.# kics-scan disable=<kics_id> as a comment at the top of the file.You can override specific IaC scanning rules to customize them. For example, assign a rule a lower severity, or link to your own documentation about how to fix a finding.
Prerequisites:
To override rules:
.gitlab directory at the root of your project, if one doesn't already exist.sast-ruleset.toml in the .gitlab directory, if
one doesn't already exist.ruleset.identifier subsections, list the rules to override.ruleset.override context of a ruleset section, provide the keys to override. Any
combination of keys can be overridden. Valid keys are:
In the following example sast-ruleset.toml file, rules are matched by the type and
value of identifiers and then overridden:
[kics]
[[kics.ruleset]]
[kics.ruleset.identifier]
type = "kics_id"
value = "8212e2d7-e683-49bc-bf78-d6799075c5a7"
[kics.ruleset.override]
description = "OVERRIDDEN description"
message = "OVERRIDDEN message"
name = "OVERRIDDEN name"
severity = "Info"
{{< details >}}
{{< /details >}}
An offline environment has limited, restricted, or intermittent access to external resources through the internet. For instances in such an environment, IaC requires some configuration changes. The instructions in this section must be completed together with the instructions detailed in offline environments.
By default, a runner tries to pull Docker images from the GitLab container registry even if a local
copy is available. You should use this default setting, to ensure Docker images remain current.
However, if no network connectivity is available, you must change the default GitLab Runner
pull_policy variable.
Configure the GitLab Runner CI/CD variable pull_policy to
if-not-present.
Use a local IaC analyzer image if you want to obtain the image from a local Docker registry instead of the GitLab container registry.
Prerequisites:
To use a local IaC analyzer image:
Import the default IaC analyzer image from registry.gitlab.com into your
local Docker container registry:
registry.gitlab.com/security-products/kics:6
The IaC analyzer's image is periodically updated so you should periodically update the local copy.
Set the CI/CD variable SECURE_ANALYZERS_PREFIX to the local Docker container registry.
include:
- template: Jobs/SAST-IaC.gitlab-ci.yml
variables:
SECURE_ANALYZERS_PREFIX: "localhost:5000/analyzers"
The IaC job should now use the local copy of the analyzer Docker image, without requiring internet access.
The GitLab-managed CI/CD template specifies a major version and automatically pulls the latest analyzer release in that major version. In some cases, you may need to use a specific version. For example, you might need to avoid a regression in a later release.
Prerequisites:
To use a specific analyzer version:
In the top bar, select Search or go to and find your project.
Select Build > Pipeline editor.
Add the SAST_ANALYZER_IMAGE_TAG CI/CD variable, after the line that includes the
SAST-IaC.gitlab-ci.yml template.
[!note] Only set this variable in a specific job. If you set it at the top level, the version you set is used for other SAST analyzers.
Set the tag to:
3. Your pipelines use any minor or patch updates that are released in this major version.3.7. Your pipelines use any patch updates that are released in this minor version.3.7.0. Your pipelines don't receive any updates.This example uses a specific minor version of the IaC analyzer:
include:
- template: Jobs/SAST-IaC.gitlab-ci.yml
kics-iac-sast:
variables:
SAST_ANALYZER_IMAGE_TAG: "3.1"
GitLab scanners are provided with a base Alpine image for size and maintainability.
GitLab provides FIPS-enabled Red Hat UBI versions of the scanners' images, in addition to the standard images.
To use the FIPS-enabled images in a pipeline, set the SAST_IMAGE_SUFFIX to -fips or modify the
standard tag plus the -fips extension.
The following example uses the SAST_IMAGE_SUFFIX CI/CD variable.
variables:
SAST_IMAGE_SUFFIX: '-fips'
include:
- template: Jobs/SAST-IaC.gitlab-ci.yml
{{< history >}}
sec_mark_dropped_findings_as_resolved.sec_mark_dropped_findings_as_resolved removed.{{< /history >}}
To help you focus on the vulnerabilities that are still relevant, IaC scanning automatically resolves vulnerabilities when:
If you re-enable the rule later, the findings are reopened for triage.
The vulnerability management system adds a note when it automatically resolves a vulnerability.
The IaC scanner outputs a JSON report file in the existing SAST report format. For more information, see the schema for this report.
The JSON report file can be downloaded from:
artifacts: paths to gl-sast-report.json.For more information see Downloading artifacts.
After validating the IaC scanning results for one project, you can implement the same approach across additional projects.
When working with IaC scanning, you might encounter the following issues.
No longer detected unexpectedlyIf a previously detected finding unexpectedly shows as No longer detected, it might
be due to an update to the scanner. An update can disable rules that are found to
be ineffective or false positives, and the findings are marked as No longer detected.
exec /bin/sh: exec format error in job logYou might get an error in the job log that states exec /bin/sh: exec format error. This issue
occurs when attempting to run the IaC scanning analyzer on an architecture other than AMD64
architecture. For details of IaC scanning prerequisites, see the prerequisites.