静态应用安全测试 (SAST)

静态应用安全测试 (SAST) 可在代码到达生产环境前发现其中的漏洞。它直接集成到你的 CI/CD 流水线中，能在开发期间识别安全问题，此时修复这些问题最容易且成本最低。

在开发后期发现的漏洞会导致昂贵的延迟和潜在的安全泄露。SAST 扫描会随每次提交自动执行，为你提供即时反馈而不干扰工作流程。

功能

下表列出了各功能在不同 GitLab 层级中的可用性。

开始使用

如果您是SAST的新手，以下步骤展示了如何为您的项目启用SAST。

先决条件：

• 基于Linux的GitLab Runner，使用docker 或 kubernetes 执行器。如果您使用的是GitLab.com托管的Runner，这会默认启用。
  • 不支持Windows Runner。
  • 不支持除amd64以外的CPU架构。
• GitLab CI/CD配置（.gitlab-ci.yml）必须包含test阶段，该阶段默认包含。如果在.gitlab-ci.yml文件中重新定义了阶段，则需要test阶段。

要启用SAST：

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

使用模板：

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

或者使用CI组件：

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

此时，SAST已在您的管道中启用。 如果存在支持的源代码，当管道运行时，相应的分析器和默认规则会自动扫描漏洞。 对应的作业将出现在管道的test阶段下。

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

• 了解更多关于如何理解结果的信息。
• 查看优化提示。
• 计划向更多项目推广。

有关其他配置方法的详细信息，请参阅配置。

理解结果

您可以在管道中查看漏洞：

1. 在左侧边栏中选择搜索或前往并找到您的项目。
2. 在左侧边栏中选择构建 > 管道。
3. 选择管道。
4. 选择安全标签页。
5. 要么下载结果，要么选择漏洞以查看其详情（仅限Ultimate），包括：
   • 描述：解释漏洞的原因、潜在影响及建议修复步骤。
   • 状态：指示漏洞是否已被分类或解决。
   • 严重程度：根据影响分为六个级别。 了解严重程度级别。
   • 位置：显示发现问题的文件名和行号。 选择文件路径会在代码视图中打开相应行。
   • 扫描器：识别检测到漏洞的分析器。
   • 标识符：用于分类漏洞的引用列表，例如CWE标识符和检测它的规则ID。

SAST漏洞是根据所发现漏洞的主要常见弱点枚举（CWE）标识符命名的。 阅读每个漏洞发现的描述，了解更多关于扫描器检测到的具体问题。 有关SAST覆盖范围的更多信息，请参见SAST规则。

在Ultimate中，您还可以下载安全扫描结果：

• 在管道的安全标签页中，选择下载结果。

有关更多细节，请参阅管道安全报告。

查看SAST结果的额外方式：

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

管道由多个作业组成，包括SAST和DAST扫描。如果任何作业因任何原因未能完成，安全仪表板不会显示SAST扫描器输出。例如，如果SAST作业完成但DAST作业失败，安全仪表板不会显示SAST结果。失败时，分析器会输出退出码。

合并请求小部件

如果目标分支有可用于比较的报告，SAST结果会显示在合并请求小部件区域。 合并请求小部件显示：

• 由MR引入的新SAST发现。
• 由MR解决的现有发现。

只要可用，结果就会使用高级漏洞跟踪进行比较。

合并请求更改视图

SAST 结果会显示在合并请求的 Changes 视图中。包含 SAST 问题的行会在侧边栏旁标记符号。选择该符号可查看问题列表，再选择一个问题查看其详情。

优化

若需根据需求优化 SAST，您可以：

• 禁用某条规则。
• 排除文件或路径不被扫描。

禁用规则

若要禁用某条规则（例如因产生过多误报）：

1. 在左侧边栏中，选择 搜索或前往 并找到您的项目。

2. 若项目中尚无此文件，请在项目根目录创建 .gitlab/sast-ruleset.toml 文件。

3. 在漏洞详情中，找到触发该发现的规则的 ID。

4. 用规则 ID 禁用该规则。例如，要禁用 gosec.G107-1，可在 .gitlab/sast-ruleset.toml 中添加以下内容：

   [semgrep]
     [[semgrep.ruleset]]
       disable = true
       [semgrep.ruleset.identifier]
         type = "semgrep_id"
         value = "gosec.G107-1"

有关自定义规则集的更多细节，请参阅 自定义规则集。

排除文件或路径不被扫描

若要排除文件或路径不被扫描（例如测试或临时代码），请设置 SAST_EXCLUDED_PATHS 变量。 例如，要跳过 rule-template-injection.go，可在 .gitlab-ci.yml 中添加以下内容：

variables:
  SAST_EXCLUDED_PATHS: "rule-template-injection.go"

有关配置选项的更多信息，请参阅 可用 CI/CD 变量。

推广实施

在对单个项目的 SAST 结果有信心后，您可将其实施范围扩展至其他项目：

• 使用 强制执行扫描 在群组间应用 SAST 设置。
• 通过 指定远程配置文件 共享并复用中心规则集。
• 若有特殊需求，SAST 可在 离线环境 或 SELinux 约束下运行。

支持的语言和框架

GitLab SAST 支持扫描以下语言和框架。

可用的扫描选项取决于 GitLab 版本：

• 在 Ultimate 版中，GitLab Advanced SAST 提供更精准的结果。对于其支持的语言，建议您使用该工具。
• 在所有版本中，您可以使用基于开源扫描器的 GitLab 提供的分析器来扫描代码。

有关 SAST 语言支持的更多计划信息，请参阅类别方向页面。

Footnotes:

1. 基于 SpotBugs 的分析器支持 Gradle、Maven 和 SBT。它也可与以下变体搭配使用：Gradle 包装器、Grails 及 Maven 包装器。不过，当针对基于 Ant 的项目使用时，SpotBugs 存在 限制。对于基于 Ant 的 Java 或 Scala 项目，建议使用 GitLab 高级 SAST 或基于 Semgrep 的分析器。
2. YAML 支持仅限以下文件模式：
   • application*.yml
   • application*.yaml
   • bootstrap*.yml
   • bootstrap*.yaml

SAST CI/CD 模板还包含一个分析器作业，可扫描 Kubernetes 清单和 Helm 图表；该作业默认处于关闭状态。 请参阅 启用 Kubesec 分析器，或考虑 IaC 扫描（支持更多平台）作为替代方案。

若想了解不再支持的 SAST 分析器的详细信息，请参阅 已达到支持终止期的分析器。

高级漏洞跟踪

源代码具有易变性；随着开发人员做出更改，源代码可能会在文件内部或文件之间移动。 安全分析工具可能已经报告了正在 vulnerability report 中跟踪的漏洞。 这些漏洞与特定的有问题的代码片段相关联，以便能够找到并修复它们。 如果代码片段在移动时没有被可靠地跟踪，漏洞管理会更困难，因为同一漏洞可能会被再次报告。

GitLab SAST 使用一种高级漏洞跟踪算法，以更准确地识别由于重构或不相关的更改而导致的同一漏洞在同一文件内的移动情况。

高级漏洞跟踪适用于 支持的语言 和 分析器 的子集：

• C，仅在基于 Semgrep 的分析器中
• C++，仅在基于 Semgrep 的分析器中
• C#，在 GitLab 高级 SAST 和基于 Semgrep 的分析器中
• Go，在 GitLab 高级 SAST 和基于 Semgrep 的分析器中
• Java，在 GitLab 高级 SAST 和基于 Semgrep 的分析器中
• JavaScript，在 GitLab 高级 SAST 和基于 Semgrep 的分析器中
• PHP，仅在基于 Semgrep 的分析器中
• Python，在 GitLab 高级 SAST 和基于 Semgrep 的分析器中
• Ruby，仅在基于 Semgrep 的分析器中

更多语言和分析器的支持情况记录在 this epic 中。

有关更多信息，请参阅机密项目 https://gitlab.com/gitlab-org/security-products/post-analyzers/tracking-calculator。该项目的内容仅对 GitLab 团队成员开放。

自动漏洞解决

为了帮助您专注于仍然相关的漏洞，当发生以下情况时，GitLab SAST 会自动解决漏洞：

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

自动解决功能仅适用于来自 基于 Semgrep 的分析器 的结果。 漏洞管理系统会在自动解决的漏洞上留下评论，因此您仍能拥有该漏洞的历史记录。

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

支持的发行版

默认扫描器镜像构建于基础 Alpine 镜像之上，以实现大小和维护性。

启用 FIPS 的镜像

GitLab 提供了一个基于 Red Hat UBI 基础镜像的镜像版本，该版本使用经过 FIPS 140 认证的加密模块。若要使用启用了 FIPS 的镜像，您可以：

• 将 SAST_IMAGE_SUFFIX 设置为 -fips
• 向默认镜像名称添加 -fips 扩展名

例如：

variables:
  SAST_IMAGE_SUFFIX: '-fips'

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

符合 FIPS 标准的镜像仅适用于 GitLab 高级 SAST 和基于 Semgrep 的分析器。

下载 SAST 报告

每个 SAST 分析器都会输出一个 JSON 格式的报告作为作业工件。该文件包含所有检测到的漏洞的详细信息。您可以下载（../../../ci/jobs/job_artifacts.md#download-job-artifacts）该文件以在 GitLab 外部进行处理。

有关更多信息，请参阅：

• SAST 报告文件架构
• 示例 SAST 报告文件

配置

SAST 扫描在您的 CI/CD 管道中运行。 当您将 GitLab 管理的 CI/CD 模板添加到管道时，合适的 SAST 分析器 会自动扫描您的代码，并将结果保存为 SAST 报告工件。

要为项目配置 SAST，您可以：

• 使用 Auto SAST，该功能由 Auto DevOps 提供。
• 在 CI/CD YAML 中配置 SAST。
• 通过 UI 配置 SAST。

您可以通过 强制执行扫描 在多个项目中启用 SAST。

若要配置高级 SAST（仅在 GitLab Ultimate 中可用），请遵循以下 说明。

如有需要，您可以 修改配置变量 或 自定义检测规则，但 GitLab SAST 设计为默认配置即可使用。

在 CI/CD YAML 中配置 SAST

要启用 SAST，您需 包含 SAST.gitlab-ci.yml 模板。该模板作为 GitLab 安装的一部分提供。

将以下内容复制粘贴到 .gitlab-ci.yml 文件的底部。如果已存在 include 行，只需在其下方添加 template 行。

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

包含的模板会在您的 CI/CD 管道中创建 SAST 任务，并扫描项目的源代码以查找可能的漏洞。

结果会保存为 SAST 报告工件，您之后可以下载并分析。下载时，您始终会收到最新的 SAST 工件。

稳定版与最新版 SAST 模板

SAST 提供了两种用于将安全测试集成到 CI/CD 管道的模板：

• SAST.gitlab-ci.yml（推荐）

  稳定模板提供可靠且一致的 SAST 体验。对于大多数需要其 CI/CD 管道具有稳定性和可预测行为的项目，应使用稳定模板。

• SAST.latest.gitlab-ci.yml

  此模板适用于希望访问和测试前沿功能的用户。它不被视为稳定版本，可能包含计划在下一个主要版本中发布的破坏性变更。此模板允许您在新功能成为稳定发布之前尝试新功能和更新，非常适合那些能接受潜在不稳定状态并乐于对新功能提供反馈的用户。

通过 UI 配置 SAST

您可以使用 UI 启用和配置 SAST，无论是使用默认设置还是自定义设置。您可使用的方法取决于您的 GitLab 许可证级别。

带自定义设置的 SAST 配置

要启用并配置带自定义设置的 SAST：

1. 在左侧边栏中选择 搜索或前往 并找到您的项目。

2. 选择 Security > 安全配置。

3. 如果项目的默认分支的最新管道已完成并生成有效的 SAST 工件，选择 配置 SAST；否则，在静态应用安全测试（SAST）行中选择 启用 SAST。

4. 输入自定义 SAST 值。

   自定义值存储在 .gitlab-ci.yml 文件中。对于不在 SAST 配置页面中的 CI/CD 变量，其值继承自 GitLab SAST 模板。

5. 选择 创建合并请求。

6. 审核并合并合并请求。

现在管道中包含一个 SAST 任务。

仅使用默认设置配置SAST

要启用并使用默认设置配置SAST：

1. 在左侧边栏中，选择 搜索或前往 并找到您的项目。
2. 选择 安全 > 安全配置。
3. 在SAST部分，选择 通过合并请求进行配置。
4. 审核并合并该合并请求以启用SAST。

现在流水线中包含一个SAST作业。

覆盖SAST作业

若要覆盖作业定义（例如修改 variables、dependencies 或 rules 等属性），请声明一个与SAST作业同名的作业来覆盖。将该新作业放在模板包含之后，并在其下指定任何额外的键。例如，这将为 spotbugs 分析器启用 FAIL_NEVER：

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

spotbugs-sast:
  variables:
    FAIL_NEVER: 1

固定到次要镜像版本

GitLab管理的CI/CD模板指定了主要版本，并会自动拉取该主要版本内的最新分析器发布版。

在某些情况下，您可能需要使用特定版本。例如，您可能需要避免后续版本中的回归问题。

若要覆盖自动更新行为，请在包含 SAST.gitlab-ci.yml 模板 后，在CI/CD配置文件中设置 SAST_ANALYZER_IMAGE_TAG CI/CD变量。

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

您可以设置标签为：

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

以下示例使用了 semgrep 分析器的特定次要版本和 brakeman 分析器的特定补丁版本：

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

semgrep-sast:
  variables:
    SAST_ANALYZER_IMAGE_TAG: "3.7"

brakeman-sast:
  variables:
    SAST_ANALYZER_IMAGE_TAG: "3.1.1"

使用CI/CD变量传递私有仓库的凭证

某些分析器需要下载项目的依赖项才能执行分析。相应地，这些依赖项可能存在于私有Git仓库中，因此需要像用户名和密码这样的凭证来下载它们。根据分析器的不同，此类凭证可以通过自定义CI/CD变量提供。

使用CI/CD变量向私有Maven仓库传递用户名和密码

如果您的私有Maven仓库需要登录凭证，可以使用 MAVEN_CLI_OPTS CI/CD变量。

有关更多信息，请参阅如何使用私有Maven仓库。

启用Kubesec分析器

您需要将 SCAN_KUBERNETES_MANIFESTS 设置为 "true" 以启用Kubesec分析器。在 .gitlab-ci.yml 中定义：

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

variables:
  SCAN_KUBERNETES_MANIFESTS: "true"

使用基于Semgrep的分析器扫描其他语言

您可以自定义基于Semgrep的分析器来扫描未被支持的语言和框架的其他语言。但是，由于GitLab不为这些其他语言提供规则集，您必须提供一个自定义规则集来覆盖它们。您还必须修改 semgrep-sast CI/CD作业的 rules，以便在相关文件被修改时运行该作业。

扫描Rust应用

例如，要扫描Rust应用，您必须：

1. 为Rust提供自定义规则集。在仓库根目录下的.gitlab/目录中创建一个名为sast-ruleset.toml的文件。以下示例使用了Semgrep注册表的默认Rust规则集：

   [semgrep]
     description = "Rust规则集用于Semgrep"
     targetdir = "/sgrules"
     timeout = 60
   
     [[semgrep.passthrough]]
       type  = "url"
       value = "https://semgrep.dev/c/p/rust"
       target = "rust.yml"

   阅读更多关于自定义规则集的内容。

2. 覆盖semgrep-sast作业以添加检测Rust（.rs）文件的规则。在.gitlab-ci.yml文件中定义如下：

   include:
     - template: Jobs/SAST.gitlab-ci.yml
   
   semgrep-sast:
     rules:
       - if: $CI_COMMIT_BRANCH
         exists:
           - '**/*.rs'
           # 包含你需要的其他文件扩展名，这些扩展名来自semgrep-sast模板：Jobs/SAST.gitlab-ci.yml

SpotBugs分析器对JDK21的支持

SpotBugs分析器的版本6增加了对JDK21的支持并移除了JDK11。默认版本仍为5，详情可参见问题517169。 若要使用版本6，请按照Pinning to minor image version部分的说明手动固定版本。

spotbugs-sast:
  variables:
    SAST_ANALYZER_IMAGE_TAG: "6"

使用预编译配合SpotBugs分析器

基于SpotBugs的分析器会扫描Groovy项目的已编译字节码。默认情况下，它会自动尝试获取依赖并编译你的代码以便进行扫描。 自动编译可能会失败如果：

• 你的项目需要自定义构建配置
• 你使用的语言版本未内置在分析器中

要解决这些问题，你应该跳过分析器的编译步骤，而是直接从流水线的前置阶段提供工件。这种策略被称为预编译。

共享预编译工件

1. 使用编译作业（通常命名为build）来编译项目，并将编译输出作为job artifact存储，使用artifacts: paths。

   • 对于Maven项目，输出文件夹通常是target目录
   • 对于Gradle项目，通常是build目录
   • 如果你的项目使用自定义输出位置，请相应地设置artifacts路径

2. 通过在spotbugs-sast作业中设置COMPILE: "false" CI/CD变量来禁用自动编译。

3. 确保spotbugs-sast作业通过设置dependencies关键字依赖于编译作业。这允许spotbugs-sast作业下载并使用编译作业中创建的工件。

以下示例预编译了一个Gradle项目，并为分析器提供了已编译的字节码：

stages:
  - build
  - test

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

build:
  image: gradle:7.6-jdk8
  stage: build
  script:
    - gradle build
  artifacts:
    paths:
      - build/

spotbugs-sast:
  dependencies:
    - build
  variables:
    COMPILE: "false"
    SECURE_LOG_LEVEL: debug

指定依赖项（仅限Maven）

如果你的项目需要外部依赖被分析器识别，且你使用的是Maven，可以通过MAVEN_REPO_PATH变量指定本地仓库的位置。

指定依赖项仅支持Maven项目。其他构建工具（例如Gradle）没有等效机制来指定依赖项。在这种情况下，确保你的已编译工件包含所有必要的依赖。

以下示例预编译了一个Maven项目，并为分析器提供了已编译的字节码以及依赖项：

stages:
  - build
  - test

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

build:
  image: maven:3.6-jdk-8-slim
  stage: build
  script:
    - mvn package -Dmaven.repo.local=./.m2/repository
  artifacts:
    paths:
      - .m2/
      - target/

spotbugs-sast:
  dependencies:
    - build
  variables:
    MAVEN_REPO_PATH: $CI_PROJECT_DIR/.m2/repository
    COMPILE: "false"
    SECURE_LOG_LEVEL: debug

在合并请求管道中运行作业

参见在合并请求管道中使用安全扫描工具。

可用的CI/CD变量

SAST可以通过在.gitlab-ci.yml中使用variables参数进行配置。

以下示例包含了覆盖所有作业中SEARCH_MAX_DEPTH变量为10的SAST模板。该模板在流水线配置之前被评估，因此变量的最后一次提及优先。

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

variables:
  SEARCH_MAX_DEPTH: 10

自定义证书颁发机构

要将自定义证书颁发机构设为可信，请在SAST环境中将ADDITIONAL_CA_CERT_BUNDLE变量设置为要信任的CA证书包。ADDITIONAL_CA_CERT_BUNDLE值应包含X.509 PEM公钥证书的文本表示形式。例如，要在.gitlab-ci.yml文件中配置此值，请使用以下内容：

variables:
  ADDITIONAL_CA_CERT_BUNDLE: |
      -----BEGIN CERTIFICATE-----
      MIIGqTCCBJGgAwIBAgIQI7AVxxVwg2kch4d56XNdDjANBgkqhkiG9w0BAQsFADCB
      ...
      jWgmPqF3vUbZE0EyScetPJquRFRKIesyJuBFMAs=
      -----END CERTIFICATE-----

ADDITIONAL_CA_CERT_BUNDLE值也可以通过UI中的自定义变量进行配置，既可以作为file（需要证书路径），也可以作为变量（需要证书的文本表示形式）。

Docker镜像

以下是与Docker镜像相关的CI/CD变量。

漏洞过滤器

脚注:

1. 您可能需要排除构建工具使用的临时目录，因为这些目录可能会产生误报。若要排除路径，请复制并粘贴默认排除路径，然后添加您自己的要排除的路径。如果您未指定默认排除路径，则默认设置将被覆盖，仅您指定的路径将从 SAST 扫描中排除。

2. 对于这些分析器，SAST_EXCLUDED_PATHS 是作为预过滤实现的，它在扫描执行前应用。

   分析器会跳过任何其路径与逗号分隔模式之一匹配的文件或目录。

   例如，如果 SAST_EXCLUDED_PATHS 设置为 *.py,tests：

   • *.py 会忽略以下内容：
     • foo.py
     • src/foo.py
     • foo.py/bar.sh
   • tests 会忽略：
     • tests/foo.py
     • a/b/tests/c/foo.py

   每个模式都是使用与 gitignore 相同语法的 glob 样式模式。

3. 对于这些分析器，SAST_EXCLUDED_PATHS 是作为后过滤实现的，它在扫描执行后应用。

   模式可以是 glob（有关支持的模式，请参阅 doublestar.Match），也可以是文件或文件夹路径（例如 doc,spec）。父目录也会匹配模式。

   SAST_EXCLUDED_PATHS 的后过滤实现适用于所有 SAST 分析器。一些 SAST 分析器（如带有上标 2 的那些）同时实现了 SAST_EXCLUDED_PATHS 作为预过滤和后过滤。预过滤更高效，因为它减少了需要扫描的文件数量。

   对于同时支持 SAST_EXCLUDED_PATHS 作为预过滤和后过滤的分析器，先应用预过滤，

then the post-filter is applied to any vulnerabilities that remain.

1. 对于此变量，路径模式可以是通配符模式（有关支持的模式，请参阅 doublestar.Match）。如果路径模式与受支持的构建文件匹配，则该目录将从构建过程中排除：

   • build.sbt
   • grailsw
   • gradlew
   • build.gradle
   • mvnw
   • pom.xml
   • build.xml

   例如，要排除构建和扫描包含路径为 project/subdir/pom.xml 的构建文件的 maven 项目，可传递一个显式匹配构建文件的通配符模式，如 project/*/*.xml 或 **/*.xml，或精确匹配如 project/subdir/pom.xml。

   传递模式的父目录（如 project 或 project/subdir）不会将目录排除在构建之外，因为在这种情况下，构建文件未被模式明确匹配。

2. SAST CI/CD 模板 会搜索仓库以检测所用的编程语言，并选择匹配的分析器。随后，每个分析器会搜索代码库，找到其应扫描的具体文件或目录。设置 SEARCH_MAX_DEPTH 的值来指定分析器的搜索阶段应跨越多少个目录层级。

分析器设置

部分分析器可通过 CI/CD 变量进行自定义。

安全扫描器配置

SAST 分析器内部使用开源安全扫描器来执行分析。我们为安全扫描器设置了推荐配置，这样您就不必担心调整它们。但是，在某些罕见情况下，我们的默认扫描器配置可能不适合您的需求。

为了允许对扫描器行为进行一些自定义，您可以向底层扫描器添加一组有限的标志。在 SAST_SCANNER_ALLOWED_CLI_OPTS CI/CD 变量中指定这些标志。这些标志会被添加到扫描器的 CLI 选项中。

自定义 CI/CD 变量

除了上述 SAST 配置 CI/CD 变量外，如果使用了 vendored 模板，所有 自定义变量 都会传播到底层的 SAST 分析器镜像中。

排除代码分析

你可以标记单个行或块中的代码，使其不被分析漏洞。你应该通过漏洞管理来管理所有漏洞，或者在开始使用这种按发现注释的方法之前，使用SAST_EXCLUDED_PATHS调整扫描的文件路径。

当使用基于Semgrep的分析器时，还提供了以下选项：

• 忽略一行代码 —— 在行末添加// nosemgrep:注释（前缀根据开发语言而定）。

  Java 示例：

  vuln_func(); // nosemgrep

  Python 示例：

  vuln_func(); # nosemgrep

• 忽略特定规则的代码行 —— 在行末添加// nosemgrep: RULE_ID注释（前缀根据开发语言而定）。

• 忽略文件或目录 —— 在你的仓库根目录或项目工作目录中创建一个.semgrepignore文件，并在其中添加文件和文件夹的模式。GitLab Semgrep分析器会自动将你的自定义.semgrepignore文件与GitLab内置忽略模式合并。

了解更多详情，请参阅Semgrep文档。

在离线环境中运行SAST

对于在网络访问受限、受限制或间歇性访问外部资源的实例环境，要使SAST作业成功运行，需要进行一些调整。更多信息，请参见离线环境。

离线SAST的要求

要在离线环境中使用SAST，你需要：

• 具有docker或kubernetes执行器的GitLab Runner。详见先决条件了解详情。
• 本地可用的Docker容器注册表，包含SAST分析器镜像的本地副本。
• 配置包的证书检查（可选）。

GitLab Runner默认的pull_policy是always，这意味着即使本地有副本，Runner也会尝试从GitLab容器注册表中拉取Docker镜像。在离线环境中，如果偏好仅使用本地可用的Docker镜像，可以将GitLab Runner的pull_policy设置为if-not-present。不过，如果不是在离线环境中，我们建议保持拉取策略设置为always，因为这能让CI/CD管道中使用更新的扫描器。

让GitLab SAST分析器镜像在你自己的Docker注册表中可用

对于支持所有支持的编程语言和框架的SAST，从registry.gitlab.com导入以下默认SAST分析器镜像到你的本地Docker容器注册表：

registry.gitlab.com/security-products/gitlab-advanced-sast:1
registry.gitlab.com/security-products/kubesec:5
registry.gitlab.com/security-products/pmd-apex:5
registry.gitlab.com/security-products/semgrep:5
registry.gitlab.com/security-products/sobelow:5
registry.gitlab.com/security-products/spotbugs:5

将Docker镜像导入本地离线Docker注册表的过程取决于你的网络安全策略。咨询IT人员，找到允许的外部资源导入或临时访问的认可流程。这些扫描器会定期更新新定义，你可能可以自行偶尔更新。

有关以文件形式保存和传输Docker镜像的详细信息，请参阅Docker文档中关于docker save、docker load、docker export和docker import的内容。

#### 如果需要自定义证书颁发机构的支持

以下版本引入了对自定义证书颁发机构的支持。

| 分析器     | 版本       |
|------------|------------|
| `kubesec`  | [v2.1.0](https://gitlab.com/gitlab-org/security-products/analyzers/kubesec/-/releases/v2.1.0) |
| `pmd-apex` | [v2.1.0](https://gitlab.com/gitlab-org/security-products/analyzers/pmd-apex/-/releases/v2.1.0) |
| `semgrep`  | [v0.0.1](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep/-/releases/v0.0.1) |
| `sobelow`  | [v2.2.0](https://gitlab.com/gitlab-org/security-products/analyzers/sobelow/-/releases/v2.2.0) |
| `spotbugs` | [v2.7.1](https://gitlab.com/gitlab-org/security-products/analyzers/spotbugs/-/releases/v2.7.1) |

### 设置SAST CI/CD变量以使用本地SAST分析器

将以下配置添加到您的 `.gitlab-ci.yml` 文件中。您必须将 `SECURE_ANALYZERS_PREFIX` 替换为指向您本地Docker容器注册表的地址：

```yaml
include:
  - template: Jobs/SAST.gitlab-ci.yml

variables:
  SECURE_ANALYZERS_PREFIX: "localhost:5000/analyzers"

SAST作业现在应使用SAST分析器的本地副本来扫描您的代码并生成安全报告，而无需互联网访问。

配置包的证书检查

如果SAST作业调用了包管理器，则必须配置其证书验证。在离线环境中，无法与外部源进行证书验证。要么使用自签名证书，要么禁用证书验证。请参阅包管理器的文档了解具体说明。

在SELinux中运行SAST

默认情况下，GitLab实例托管在SELinux上的SAST分析器是被支持的。在覆盖的SAST作业中添加 before_script 可能无效，因为SELinux托管的runner具有受限权限。