Infrastructure as Code scanning

Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated

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:

  • See them in merge requests.
  • Use them in approval workflows.
  • Review them in the vulnerability report.

Enable the scanner

Prerequisites:

  • IaC scanning requires the AMD64 architecture. Microsoft Windows is not supported.
  • Minimum of 4 GB RAM to ensure consistent performance.
  • The test stage is required in the .gitlab-ci.yml file.
  • On GitLab self-managed you need GitLab Runner with the docker or kubernetes executor.
  • If you’re using SaaS runners on GitLab.com, this is enabled by default.

To enable IaC scanning of a project:

  1. On the left sidebar, select Search or go to and find your project.
  2. Select Build > Pipeline editor.

  3. Copy and paste the following to the bottom of the .gitlab-ci.yml file. If an include line already exists, add only the template line below it. 

    include:
  - template: Jobs/SAST-IaC.gitlab-ci.yml
  4. Select the Validate tab, then select Validate pipeline. The message Simulation completed successfully indicates the file is valid.
  5. Select the Edit tab.
  6. Select Commit changes.

Pipelines now include an IaC scanning job.

Supported languages and frameworks

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.

Customize rules

Tier: Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated

You can customize the default IaC scanning rules provided with GitLab.

The following customization options can be used separately, or together:

Ruleset definition

Every IaC scanning rule is contained in a ruleset section, which contains:

  • A type field for the rule. For IaC Scanning, the identifier type is kics_id.
  • A value field for the rule identifier. KICS rule identifiers are alphanumeric strings. To find the rule identifier:

Disable rules

You can disable specific IaC Scanning rules.

To disable analyzer rules:

  1. Create a .gitlab directory at the root of your project, if one doesn’t already exist.
  2. Create a custom ruleset file named sast-ruleset.toml in the .gitlab directory, if one doesn’t already exist.
  3. Set the disabled flag to true in the context of a ruleset section.
  4. In one or more 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"

Disable scanning using comments

You can use KICS annotations to control how the KICS-based GitLab IaC Scanning analyzer scans your codebase. For example:

  • To skip scanning an entire file, you can add # kics-scan ignore as a comment at the top of the file.
  • To disable a specific rule in an entire file, you can add # kics-scan disable=<kics_id> as a comment at the top of the file.
note
This feature is only available for some types of IaC files. See the KICS documentation for a list of supported file types.

Override rules

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.

To override rules:

  1. Create a .gitlab directory at the root of your project, if one doesn’t already exist.
  2. Create a custom ruleset file named sast-ruleset.toml in the .gitlab directory, if one doesn’t already exist.
  3. In one or more ruleset.identifier subsections, list the rules to override.
  4. In the ruleset.override context of a ruleset section, provide the keys to override. Any combination of keys can be overridden. Valid keys are:
    • description
    • message
    • name
    • severity (valid options are: Critical, High, Medium, Low, Unknown, Info)

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"

Offline configuration

Tier: Premium, Ultimate Offering: Self-managed

An offline environment has limited, restricted, or intermittent access to external resources through the internet. For self-managed GitLab 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.

Configure GitLab Runner

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 local IaC analyzer image

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:

  • Importing Docker images into a local offline Docker registry depends on your network security policy. Consult your IT staff to find an accepted and approved process to import or temporarily access external resources.

  1. Import the default IaC analyzer image from registry.gitlab.com into your local Docker container registry: 

    registry.gitlab.com/security-products/kics:5

    The IaC analyzer’s image is periodically updated so you should periodically update the local copy.

  2. 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.

Use a specific analyzer version

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.

To use a specific analyzer version:

  1. On the left sidebar, select Search or go to and find your project.
  2. Select Build > Pipeline editor.

  3. 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:

    • A major version, like 3. Your pipelines use any minor or patch updates that are released in this major version.
    • A minor version, like 3.7. Your pipelines use any patch updates that are released in this minor version.
    • A patch version, like 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"

Supported distributions

GitLab scanners are provided with a base Alpine image for size and maintainability.

Use FIPS-enabled images

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

Automatic vulnerability resolution

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.

Reports JSON format

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:

For more information see Downloading artifacts.

Troubleshooting

When working with IaC scanning, you might encounter the following issues.

IaC scanning findings show as No longer detected unexpectedly

If 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.

In GitLab 15.3, secret detection in the IaC scanner was disabled, so IaC findings in the “Passwords and Secrets” family show as No longer detected.

Message exec /bin/sh: exec format error in job log

You 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 Enable the scanner.