1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
|
---
stage: Secure
group: Static Analysis
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments
---
# Infrastructure as Code scanning **(FREE ALL)**
> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/6655) in GitLab 14.5.
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](../../../ci/yaml/artifacts_reports.md#artifactsreportssast).
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`](https://docs.gitlab.com/runner/executors/docker.html) or
[`kubernetes`](https://docs.gitlab.com/runner/install/kubernetes.html) executor. On GitLab.com this
is enabled by default on the shared runners. The analyzer images provided are for the Linux/amd64
architecture.
To enable IaC scanning of a project:
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Build > Pipeline editor**.
1. Copy and paste the following to the bottom of the `.gitlab-ci.yml` file.
```yaml
include:
- template: Security/SAST-IaC.gitlab-ci.yml
```
1. Select the **Validate** tab, then select **Validate pipeline**.
The message **Simulation completed successfully** indicates the file is valid.
1. Select the **Edit** tab.
1. 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](https://kics.io/). Projects with a mix
of IaC configuration files are supported.
Supported configuration formats:
- Ansible
- AWS CloudFormation
- Azure Resource Manager <sup>1</sup>
- Dockerfile
- Google Deployment Manager
- Kubernetes
- OpenAPI
- Terraform <sup>2</sup>
<html>
<small>Footnotes:
<ol>
<li>IaC Scanning can analyze Azure Resource Manager templates in JSON format. If you write templates in the <a href="https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/overview">Bicep</a> language, you must use the <a href="https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/bicep-cli">bicep CLI</a> to convert your Bicep files into JSON before IaC scanning can analyze them.</li>
<li>Terraform modules in a custom registry are not scanned for vulnerabilities. You can follow <a href="https://gitlab.com/gitlab-org/gitlab/-/issues/357004">issue 357004</a> for the proposed feature.</li>
</ol>
</small>
</html>
## Customize rules **(ULTIMATE ALL)**
> Support for overriding rules [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/235359) in GitLab 14.8.
You can customize the default IaC scanning rules provided with GitLab.
The following customization options can be used separately, or together:
- [Disable predefined rules](#disable-rules).
- [Override predefined rules](#override-rules).
### 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:
- Find it in the [JSON report artifact](#reports-json-format).
- Search for the rule name in the [list of KICS queries](https://docs.kics.io/latest/queries/all-queries/)
and copy the alphanumeric identifier that's shown. The rule name is shown on the
[Vulnerability Page](../vulnerabilities/index.md) when a rule violation is detected.
### 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.
1. Create a custom ruleset file named `sast-ruleset.toml` in the `.gitlab` directory, if
one doesn't already exist.
1. Set the `disabled` flag to `true` in the context of a `ruleset` section.
1. 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](#automatic-vulnerability-resolution).
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:
```toml
[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"
```
### 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.
1. Create a custom ruleset file named `sast-ruleset.toml` in the `.gitlab` directory, if
one doesn't already exist.
1. In one or more `ruleset.identifier` subsections, list the rules to override.
1. 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:
```toml
[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"
```
## 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.
1. Select **Build > Pipeline editor**.
1. 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:
```yaml
include:
- template: Security/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
> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/6479) in GitLab 14.10.
GitLab provides [FIPS-enabled Red Hat UBI](https://www.redhat.com/en/blog/introducing-red-hat-universal-base-image)
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.
```yaml
variables:
SAST_IMAGE_SUFFIX: '-fips'
include:
- template: Security/SAST-IaC.gitlab-ci.yml
```
## Automatic vulnerability resolution
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/368284) in GitLab 15.9 [with a project-level flag](../../../administration/feature_flags.md) named `sec_mark_dropped_findings_as_resolved`.
> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/375128) in GitLab 16.2. Feature flag `sec_mark_dropped_findings_as_resolved` removed.
To help you focus on the vulnerabilities that are still relevant, IaC scanning automatically
[resolves](../vulnerabilities/index.md#vulnerability-status-values) vulnerabilities when:
- You [disable a predefined rule](#disable-rules).
- We remove a rule from the default ruleset.
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](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/blob/master/dist/sast-report-format.json).
The JSON report file can be downloaded from:
- The CI pipelines page.
- The pipelines tab on merge requests by
[setting `artifacts: paths`](../../../ci/yaml/index.md#artifactspaths) to `gl-sast-report.json`.
For more information see [Downloading artifacts](../../../ci/jobs/job_artifacts.md).
## 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](https://gitlab.com/gitlab-org/gitlab/-/issues/346181),
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](#enable-the-scanner).
|
