基础设施即代码扫描

基础设施即代码（IaC）扫描在您的 CI/CD 流水线中运行，检查您的基础设施定义文件是否存在已知漏洞。在漏洞提交到默认分支之前识别它们，主动解决对应用程序的风险。

IaC 扫描分析器会输出 JSON 格式的报告，作为 作业产物。

使用 GitLab Ultimate，IaC 扫描结果也会被处理，因此您可以：

• 在合并请求中查看它们。
• 在审批工作流中使用它们。
• 在漏洞报告中查看它们。

入门指南

如果您是 IaC 扫描的新手，以下步骤展示了如何快速为您的项目启用 IaC 扫描。

先决条件：

• IaC 扫描需要 AMD64 架构。不支持 Microsoft Windows。
• 至少需要 4 GB RAM 以确保性能稳定。
• .gitlab-ci.yml 文件需要包含 test 阶段。
• 在 GitLab 自托管版中，您需要使用 docker 或 kubernetes 执行器的 GitLab Runner。
• 如果您在 GitLab.com 上使用 SaaS Runner，此功能默认启用。

要启用 IaC 扫描：

1. 在左侧边栏，选择 搜索或跳转至 并找到您的项目。
2. 如果您的项目还没有 .gitlab-ci.yml 文件，请在根目录创建一个。
3. 在 .gitlab-ci.yml 文件顶部，添加以下任一行：

使用模板：

include:
  - template: Jobs/SAST-IaC.gitlab-ci.yml

或使用 CI 组件：

include:
  - component: gitlab.com/components/sast/iac-sast@main

此时，IaC 扫描已在您的流水线中启用。 如果存在支持的 IaC 源代码，当流水线运行时，默认规则会自动扫描漏洞。 相应的作业将显示在您流水线的 test 阶段下。

您可以在 IaC 扫描示例项目 中查看工作示例。

完成这些步骤后，您可以：

• 了解如何 理解结果
• 查看 优化技巧
• 规划 扩展到更多项目

理解结果

您可以在流水线中查看漏洞：

1. 在左侧边栏，选择 搜索或跳转至 并找到您的项目。
2. 在左侧边栏，选择 构建 > 流水线。
3. 选择流水线。
4. 选择 安全 选项卡。
5. 选择一个漏洞查看其详细信息，包括：
   • 描述：解释漏洞的原因、潜在影响和推荐的修复步骤。
   • 状态：指示漏洞是否已分类或已解决。
   • 严重性：根据影响分为六个级别。 了解有关严重性级别的更多信息。
   • 位置：显示发现问题的文件名和行号。 选择文件路径将在代码视图中打开相应的行。
   • 扫描器：标识检测到漏洞的分析器。
   • 标识符：用于分类漏洞的引用列表，如 CWE 标识符和检测到它的规则 ID。

您还可以下载安全扫描结果：

• 在流水线的 安全 选项卡中，选择 下载结果。

有关更多详细信息，请参阅 流水线安全报告。

查看 IaC 扫描结果的其他方式：

• 合并请求小部件：显示新引入或已解决的发现。
• 合并请求变更视图：显示变更行的内联注释。
• 漏洞报告：显示默认分支上的已确认漏洞。

支持的语言和框架

IaC 扫描支持多种 IaC 配置文件。当在项目中检测到任何支持的配置文件时，将使用 KICS 进行扫描。支持包含混合 IaC 配置文件的项目。

支持的配置格式：

• Ansible

• AWS CloudFormation

• Azure Resource Manager

  IaC 扫描可以分析 JSON 格式的 Azure Resource Manager 模板。 如果您使用 Bicep 编写模板， 必须使用 Bicep CLI 将 Bicep 文件转换为 JSON， 然后 IaC 扫描才能分析它们。

• Dockerfile

• Google Deployment Manager

• Kubernetes

• OpenAPI

• Terraform

  自定义注册表中的 Terraform 模块不会扫描漏洞。 有关建议功能的更多信息，请参阅 issue 357004。

优化

目前，自定义默认 IaC 扫描规则是优化 GitLab 中 IaC 扫描的唯一支持方式。

以下自定义选项可以单独使用，也可以组合使用：

• 禁用预定义规则。
• 覆盖预定义规则。

规则集定义

每个 IaC 扫描规则都包含在一个 ruleset 部分中，该部分包含：

• 规则的 type 字段。对于 IaC 扫描，标识符类型为 kics_id。
• 规则标识符的 value 字段。KICS 规则标识符是字母数字字符串。 要查找规则标识符：
  • 在 JSON 报告产物 中找到它。
  • 在 KICS 查询列表 中搜索规则名称并复制显示的字母数字标识符。 当检测到规则违规时，规则名称显示在 漏洞页面 上。

禁用规则

您可以禁用特定的 IaC 扫描规则。

要禁用分析器规则：

1. 如果项目根目录还没有 .gitlab 目录，请创建一个。
2. 如果 .gitlab 目录中还没有自定义规则集文件，请创建一个名为 sast-ruleset.toml 的文件。
3. 在 ruleset 部分的上下文中将 disabled 标志设置为 true。
4. 在一个或多个 ruleset 子部分中，列出要禁用的规则。

当您将 sast-ruleset.toml 文件合并到默认分支后，已禁用规则的现有发现将 自动解决。

在以下 sast-ruleset.toml 文件示例中，禁用的规则通过匹配标识符的 type 和 value 分配给 kics 分析器：

[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"

使用注释禁用扫描

您可以使用 KICS 注释 来控制基于 KICS 的 GitLab IaC 扫描分析器如何扫描您的代码库。例如：

• 要跳过扫描整个文件，可以在文件顶部添加 # kics-scan ignore 作为注释。
• 要在整个文件中禁用特定规则，可以在文件顶部添加 # kics-scan disable=<kics_id> 作为注释。

覆盖规则

您可以覆盖特定的 IaC 扫描规则来自定义它们。例如，为规则分配较低的严重性，或链接到您自己的有关如何修复发现的文档。

要覆盖规则：

1. 如果项目根目录还没有 .gitlab 目录，请创建一个。
2. 如果 .gitlab 目录中还没有自定义规则集文件，请创建一个名为 sast-ruleset.toml 的文件。
3. 在一个或多个 ruleset.identifier 子部分中，列出要覆盖的规则。
4. 在 ruleset 部分的 ruleset.override 上下文中，提供要覆盖的键。可以覆盖任何键组合。有效键为：
   • description
   • message
   • name
   • severity（有效选项：Critical, High, Medium, Low, Unknown, Info）

在以下 sast-ruleset.toml 文件示例中，规则通过标识符的 type 和 value 匹配，然后被覆盖：

[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"

离线配置

离线环境对通过互联网访问外部资源有有限、受限或间歇性的访问权限。对于此类环境中的实例，IaC 需要一些配置更改。本节中的说明必须与 离线环境 中详细说明的指令一起完成。

配置 GitLab Runner

默认情况下，即使本地副本可用，Runner 也会尝试从 GitLab 容器注册表中拉取 Docker 镜像。您应该使用此默认设置，以确保 Docker 镜像保持最新。但是，如果没有网络连接，您必须更改默认的 GitLab Runner pull_policy 变量。

将 GitLab Runner CI/CD 变量 pull_policy 配置为 if-not-present。

使用本地 IaC 分析器镜像

如果您想从本地 Docker 注册表而不是 GitLab 容器注册表获取镜像，请使用本地 IaC 分析器镜像。

先决条件：

• 将 Docker 镜像导入本地离线 Docker 注册表取决于您的网络安全策略。请咨询您的 IT 人员，以找到导入或临时访问外部资源的可接受和批准的流程。

1. 将默认的 IaC 分析器镜像从 registry.gitlab.com 导入到您的 本地 Docker 容器注册表：

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

   IaC 分析器的镜像会 定期更新，因此您应该定期更新本地副本。

2. 将 CI/CD 变量 SECURE_ANALYZERS_PREFIX 设置为本地 Docker 容器注册表。

   include:
     - template: Jobs/SAST-IaC.gitlab-ci.yml
   
   variables:
     SECURE_ANALYZERS_PREFIX: "localhost:5000/analyzers"

IaC 作业现在应该使用分析器 Docker 镜像的本地副本，而无需互联网访问。

使用特定分析器版本

GitLab 管理的 CI/CD 模板指定主版本并自动拉取该主版本中的最新分析器发布版本。在某些情况下，您可能需要使用特定版本。例如，您可能需要避免后续版本中的回归问题。

要使用特定分析器版本：

1. 在左侧边栏，选择 搜索或跳转至 并找到您的项目。

2. 选择 构建 > 流水线编辑器。

3. 在包含 SAST-IaC.gitlab-ci.yml 模板的行之后，添加 SAST_ANALYZER_IMAGE_TAG CI/CD 变量。

   仅在特定作业中设置此变量。如果在顶层设置它，您设置的版本将用于其他 SAST 分析器。

   将标签设置为：

   • 主版本，如 3。您的流水线将使用此主版本中发布的任何次要或补丁更新。
   • 次要版本，如 3.7。您的流水线将使用此次要版本中发布的任何补丁更新。
   • 补丁版本，如 3.7.0。您的流水线不会收到任何更新。

此示例使用 IaC 分析器的特定次要版本：

include:
  - template: Jobs/SAST-IaC.gitlab-ci.yml

kics-iac-sast:
  variables:
    SAST_ANALYZER_IMAGE_TAG: "3.1"

支持的发行版

GitLab 扫描器提供基础 Alpine 镜像，以实现大小和可维护性。

使用启用了 FIPS 的镜像

除了标准镜像外，GitLab 还提供扫描器镜像的 启用了 FIPS 的 Red Hat UBI 版本。

要在流水线中使用启用了 FIPS 的镜像，将 SAST_IMAGE_SUFFIX 设置为 -fips 或修改标准标签并添加 -fips 后缀。

以下示例使用 SAST_IMAGE_SUFFIX CI/CD 变量。

variables:
  SAST_IMAGE_SUFFIX: '-fips'

include:
  - template: Jobs/SAST-IaC.gitlab-ci.yml

自动漏洞解决

为了帮助您专注于仍然相关的漏洞，IaC 扫描会在以下情况下自动 解决 漏洞：

• 您 禁用预定义规则。
• 我们从默认规则集中移除规则。

如果您稍后重新启用该规则，发现将重新打开以进行分类。

漏洞管理系统在自动解决漏洞时会添加注释。

报告 JSON 格式

IaC 扫描器以现有的 SAST 报告格式输出 JSON 报告文件。有关更多信息，请参阅此报告的 架构。

JSON 报告文件可以从以下位置下载：

• CI 流水线页面。
• 通过 设置 artifacts: paths 为 gl-sast-report.json，从合并请求的流水线选项卡下载。

有关更多信息，请参阅 下载产物。

扩展部署

在为一个项目验证了 IaC 扫描结果后，您可以在更多项目中实施相同的方法。

• 使用 强制扫描执行 在组范围内应用 IaC 扫描设置。
• 通过 指定远程配置文件 共享和重用中心规则集。

故障排除

在使用 IaC 扫描时，您可能会遇到以下问题。

IaC 扫描发现意外显示为 “不再检测”

如果先前检测到的发现意外显示为 “不再检测”，可能是由于扫描器的更新。更新可能会禁用发现无效或误报的规则，并将这些发现标记为 “不再检测”。

在 GitLab 15.3 中，IaC 扫描器中的密钥检测被禁用，因此 “密码和密钥” 家族中的 IaC 发现显示为 “不再检测”。

作业日志中出现 exec /bin/sh: exec format error 消息

您可能会在作业日志中收到错误消息 exec /bin/sh: exec format error。当尝试在 AMD64 架构以外的架构上运行 IaC 扫描分析器时，会发生此问题。有关 IaC 扫描先决条件的详细信息，请参阅 先决条件。