静态应用程序安全测试（SAST）

静态应用程序安全测试（SAST）在源代码进入生产环境之前发现其中的漏洞。SAST 直接集成到您的 CI/CD 流水线中，在开发过程中识别安全问题，此时修复最容易且成本效益最高。

在开发后期才发现的安全漏洞会导致代价高昂的延迟和潜在的入侵风险。SAST 扫描会在每次提交时自动进行，为您提供即时反馈，而不会干扰您的工作流程。

使用极狐GitLab Duo 减少误报并解决漏洞#

SAST 扫描器可能会产生误报，在漏洞报告中制造噪音。极狐GitLab Duo 可协助进行漏洞管理。

误报检测#

极狐GitLab Duo 误报检测会自动分析严重级别和高危级别的 SAST 漏洞，以识别可能的误报。这有助于您的安全团队专注于真正的漏洞，并减少人工分类所花费的时间。

对于拥有极狐GitLab Duo 附加组件的旗舰版客户，误报检测会在每次安全扫描后自动运行，并为每次评估提供置信度评分和解释。

Agentic SAST 漏洞解决#

Agentic SAST 漏洞解决会自动生成合并请求，其中包含针对高危和严重级别 SAST 漏洞的上下文感知代码修复。这种 Agentic 方法使用多轮推理，以最少的人工干预解决漏洞。

对于旗舰版客户，当漏洞满足特定条件时，Agentic 漏洞解决会在每次安全扫描后自动运行。

功能#

下表列出了每个功能可用的极狐GitLab 版本。

快速入门#

通过使用 UI 或编辑项目的极狐GitLab CI/CD 配置文件，在您的项目中启用 SAST。

使用 UI 启用 SAST#

您可以使用 UI 启用和配置 SAST，既可以使用默认设置，也可以进行自定义。您可以使用的方法取决于您的极狐GitLab 许可证版本。

使用自定义配置启用 SAST#

先决条件：

• 项目需具有维护者或所有者角色。
• 基于 Linux 的极狐GitLab Runner，使用 Docker 或 Kubernetes 执行器。如果您使用 JihuLab.com 的托管 Runner，则默认启用 Docker 或 Kubernetes 执行器。
  • 不支持在 Windows Runner 上使用极狐GitLab Runner。
  • 不支持 AMD64 以外的 CPU 架构。
• 极狐GitLab CI/CD 配置（.gitlab-ci.yml）必须包含 test 阶段，该阶段默认包含。如果您在.gitlab-ci.yml 文件中重新定义了阶段，则必须包含 test 阶段。

要使用自定义配置启用和配置 SAST：

1. 在顶部栏中，选择搜索或跳转到并找到您的项目。

2. 在左侧边栏中，选择安全 > 安全配置。

3. 如果项目默认分支的最新流水线已完成并生成了有效的 SAST 产物，请选择配置 SAST，否则在静态应用程序安全测试（SAST）行中选择启用 SAST。

4. 输入自定义 SAST 值。

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

5. 选择创建合并请求。

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

流水线现在包含一个 SAST 作业。如果存在受支持的源代码，当流水线运行时，相应的分析器和默认规则会自动扫描漏洞。相应的作业会出现在项目流水线的 test 阶段下。

仅使用默认设置启用 SAST#

先决条件：

• 项目需具有维护者或所有者角色。
• 基于 Linux 的极狐GitLab Runner，使用 Docker 或 Kubernetes 执行器。如果您使用 JihuLab.com 的托管 Runner，则默认启用 Docker 或 Kubernetes 执行器。
  • 不支持在 Windows Runner 上使用极狐GitLab Runner。
  • 不支持 AMD64 以外的 CPU 架构。
• 极狐GitLab CI/CD 配置（.gitlab-ci.yml）必须包含 test 阶段，该阶段默认包含。如果您在.gitlab-ci.yml 文件中重新定义了阶段，则必须包含 test 阶段。

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

1. 在顶部栏中，选择搜索或跳转到并找到您的项目。

2. 在左侧边栏中，选择安全 > 安全配置。

3. 在 SAST 部分中，选择使用合并请求进行配置。

   合并请求页面将打开。

4. 填写字段。

5. 选择创建合并请求。

6. 审查并合并合并请求以启用 SAST。

流水线现在包含一个 SAST 作业。如果存在受支持的源代码，当流水线运行时，相应的分析器和默认规则会自动扫描漏洞。相应的作业会出现在项目流水线的 test 阶段下。

通过编辑 CI/CD 文件启用 SAST#

先决条件：

• 项目需具有开发者、维护者或所有者角色。
• 基于 Linux 的极狐GitLab Runner，使用 Docker 或 Kubernetes 执行器。如果您使用 JihuLab.com 的托管 Runner，则默认启用 Docker 或 Kubernetes 执行器。
  • 不支持在 Windows Runner 上使用极狐GitLab Runner。
  • 不支持 AMD64 以外的 CPU 架构。
• 极狐GitLab CI/CD 配置（.gitlab-ci.yml）必须包含 test 阶段，该阶段默认包含。如果您在.gitlab-ci.yml 文件中重新定义了阶段，则必须包含 test 阶段。

要在您的项目中启用 SAST：

1. 在顶部栏中，选择搜索或跳转到并找到您的项目。

2. 转到构建 > 流水线编辑器。

3. 添加 SAST CI/CD 模板或组件。

   要使用模板，请添加以下行：

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

   要使用 CI/CD 组件，请添加以下行：

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

4. 选择验证选项卡，然后选择验证流水线。

   消息模拟成功完成确认文件有效。

5. 选择编辑选项卡。

6. 填写字段：

   • 提交消息。
   • 分支。例如，add-sast。

7. 选中使用这些更改启动新的合并请求复选框，然后选择 提交更改。

   合并请求页面将打开。

8. 根据您的标准工作流程填写字段，然后选择 创建 合并请求。

9. 根据您的标准工作流程审查和编辑合并请求，然后选择合并。

流水线现在包含一个 SAST 作业。如果存在受支持的源代码，当流水线运行时，相应的分析器和默认规则会自动扫描漏洞。相应的作业会出现在项目流水线的 test 阶段下。

您可以在 SAST 示例项目中查看一个可用的示例。

后续步骤#

启用 SAST 后，您可以：

• 详细了解如何理解结果。
• 查看优化提示。
• 规划向更多项目推广。

理解结果#

先决条件：

• 项目需具有安全管理员、开发者、维护者或所有者角色。

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

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

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

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

先决条件：

• 项目需具有安全管理员、开发者、维护者或所有者角色。

1. 在顶部栏中，选择搜索或跳转到并找到您的项目。
2. 在左侧边栏中，选择构建 > 流水线。
3. 选择流水线。
4. 选择安全选项卡。
5. 在流水线的安全选项卡中，选择下载结果。

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

查看 SAST 结果的其他方式：

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

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

合并请求报告#

有关合并请求中的 SAST 结果，请参阅合并请求报告。

合并请求变更视图#

SAST 结果显示在合并请求的变更视图中。包含 SAST 问题的行会在行号旁标有一个符号。选择该符号可查看问题列表，然后选择一个问题查看其详细信息。

优化#

要根据您的要求优化 SAST，您可以：

• 禁用规则。
• 排除文件或路径，使其不被扫描。

禁用规则#

先决条件：

• 项目需具有开发者、维护者或所有者角色。

要禁用规则，例如因为它产生太多误报：

1. 在顶部栏中，选择搜索或跳转到并找到您的项目。

2. 如果项目根目录中尚不存在.gitlab/sast-ruleset.toml 文件，请创建一个。

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

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

   toml
   1[semgrep]
   2  [[semgrep.ruleset]]
   3    disable = true
   4    [semgrep.ruleset.identifier]
   5      type = "semgrep_id"
   6      value = "gosec.G107-1"

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

排除文件或路径，使其不被扫描#

先决条件：

• 项目需具有开发者、维护者或所有者角色。

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

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

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

推广#

在您对单个项目的 SAST 结果有信心后，可以将其实现扩展到其他项目：

• 使用强制扫描执行在群组中应用 SAST 设置。
• 通过指定远程配置文件共享和重用中央规则集。
• 如果您有独特的要求，SAST 可以在离线环境或 SELinux 约束下运行。

支持的语言和框架#

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

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

• 在旗舰版中，极狐GitLab Advanced SAST 提供更准确的结果。对于它支持的语言，您应该使用它。
• 在所有版本中，您都可以使用极狐GitLab 提供的分析器（基于开源扫描器）来扫描您的代码。

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

完全支持的语言#

这些语言同时受极狐GitLab Advanced SAST（旗舰版）和标准分析器（所有版本）支持：

仅支持标准分析器的语言#

这些语言受标准分析器（所有版本）支持，但不受极狐GitLab Advanced SAST 支持：

仅支持极狐GitLab Advanced SAST 的语言#

这些语言在测试版中受极狐GitLab Advanced SAST（旗舰版）支持，但不受标准分析器支持：

分析在单独的 gitlab-advanced-sast-ext CI/CD 作业中运行，该作业通过 GITLAB_ADVANCED_SAST_ENABLED CI/CD 变量与极狐GitLab Advanced SAST 一起启用。 有关更多信息，请参阅极狐GitLab Advanced SAST。

SAST CI/CD 模板还包含一个可以扫描 Kubernetes 清单和 Helm chart 的分析器作业；此作业默认关闭。请参阅启用 Kubesec 分析器，或考虑改用支持其他平台的 IaC 扫描。

要了解有关不再受支持的 SAST 分析器的更多信息，请参阅已达到支持终止的分析器。

高级漏洞跟踪#

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

极狐GitLab SAST 使用高级漏洞跟踪算法，以更准确地识别同一个漏洞何时因重构或不相关的更改而在同一文件中移动。

对高级漏洞跟踪的支持取决于所使用的语言和分析器。

同时受极狐GitLab Advanced SAST 分析器和基于 Semgrep 的分析器支持的语言：

• C
• C++
• C#
• Go
• Java
• JavaScript
• Python

仅受基于 Semgrep 的分析器支持的语言：

• PHP
• Ruby

对更多语言和分析器的支持在 史诗 5144中进行跟踪。

有关更多信息，请参阅机密项目 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 扩展名添加到默认镜像名称中。

例如：

yaml
variables:
  SAST_IMAGE_SUFFIX: '-fips'

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

符合 FIPS 的镜像仅适用于极狐GitLab Advanced SAST 和基于 Semgrep 的分析器。

下载 SAST 报告#

先决条件：

• 项目需具有开发者、维护者或所有者角色。

每个 SAST 分析器都会输出一个 JSON 报告作为作业产物。该文件包含所有检测到的漏洞的详细信息。您可以下载该文件，以便在极狐GitLab 之外进行处理。

有关更多信息，请参阅：

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

配置#

极狐GitLab SAST 设计为使用其默认配置。不过，您可以根据需要更改配置变量或自定义检测规则。

稳定版与最新版 SAST 模板#

SAST 提供 stable 模板，默认用于生产环境，以及 latest 模板，用于测试前沿功能。有关差异以及何时使用每个模板的详细信息，请参阅模板版本。

覆盖 SAST 作业#

当您想要自定义诸如 variables、dependencies 和 rules 等属性时，可以覆盖 SAST 作业。

先决条件：

• 对项目具有开发者、维护者或所有者角色。

要覆盖作业定义：

• 声明一个与要覆盖的 SAST 作业同名的作业。

  将此新作业放在模板包含之后，并在其下指定任何其他键。

在以下示例中，为 spotbugs 分析器启用了 CI/CD 变量 FAIL_NEVER：

yaml
1include:
2  - template: Jobs/SAST.gitlab-ci.yml
3
4spotbugs-sast:
5  variables:
6    FAIL_NEVER: 1

固定分析器镜像版本#

当您想要在流水线中使用特定分析器镜像版本时，请固定镜像版本。GitLab 管理的 CI/CD 模板指定主版本，并自动拉取该主版本内最新的分析器版本。在某些情况下，您可能需要使用特定版本。例如，您可能需要避免后续版本中的回归。

您可以将标签设置为以下选项之一：

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

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

先决条件：

• 对项目具有开发者、维护者或所有者角色。

要将分析器镜像固定到特定版本：

• 在项目的 .gitlab-ci.yml 文件中设置 SAST_ANALYZER_IMAGE_TAG CI/CD 变量。此 CI/CD 变量必须在包含 SAST.gitlab-ci.yml 模板之后列出。

在以下示例中，设置了 semgrep 分析器的特定次要版本和 brakeman 分析器的特定补丁版本：

yaml
1include:
2  - template: Jobs/SAST.gitlab-ci.yml
3
4semgrep-sast:
5  variables:
6    SAST_ANALYZER_IMAGE_TAG: "3.7"
7
8brakeman-sast:
9  variables:
10    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中，定义：

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

variables:
  SCAN_KUBERNETES_MANIFESTS: "true"

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

您可以自定义基于 Semgrep 的 SAST 分析器，以扫描 GitLab 管理的规则集不支持的语言。但是，由于 GitLab 不提供这些其他语言的规则集，您必须替换或添加默认规则以覆盖它们。您还必须修改 semgrep-sast CI/CD 作业的 rules，以便在相关文件被修改时运行该作业。

扫描 OCaml 应用程序#

先决条件：

• 对项目具有开发者、维护者或所有者角色。

要扫描 OCaml 应用程序，请完成以下步骤：

1. 为 OCaml 提供自定义规则集。在代码仓库根目录的 .gitlab/ 目录中创建一个名为 sast-ruleset.toml的文件。

   以下示例使用 Semgrep 注册表中针对 OCaml 的规则集：

   toml
   1[semgrep]
   2  description = "OCaml ruleset for Semgrep"
   3  targetdir = "/sgrules"
   4  timeout = 60
   5
   6  [[semgrep.passthrough]]
   7    type  = "url"
   8    value = "https://semgrep.dev/c/p/ocaml"
   9    target = "ocaml.yml"

   有关更多详细信息，请参阅 替换或添加预定义规则。

2. 覆盖 semgrep-sast 作业以添加检测 OCaml（.ml）文件的规则。

   在 .gitlab-ci.yml 文件中定义以下内容：

   yaml
   1include:
   2  - template: Jobs/SAST.gitlab-ci.yml
   3
   4semgrep-sast:
   5  rules:
   6    - if: $CI_COMMIT_BRANCH
   7      exists:
   8        - '**/*.ml'
   9        # include any other file extensions you need to scan from the semgrep-sast template: Jobs/SAST.gitlab-ci.yml

SpotBugs 分析器的 JDK21 支持#

SpotBugs 分析器的 6 版本添加了对 JDK21 的支持，并移除了 JDK11。如议题 517169中所述，默认版本仍为 5。

要使用 6 版本，请固定分析器版本。有关详细信息，请参阅固定分析器镜像版本。

yaml
spotbugs-sast:
  variables:
    SAST_ANALYZER_IMAGE_TAG: "6"

在 SpotBugs 分析器中使用预编译#

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

在以下任一情况下，自动编译可能会失败：

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

要解决这些问题，请跳过分析器的编译步骤，改为直接提供流水线中较早阶段的产物。此策略称为预编译。

共享预编译产物#

先决条件：

• 对项目具有开发者、维护者或所有者角色。

要共享预编译产物，请对项目的 .gitlab-ci.yml 文件进行以下更改：

1. 使用编译作业（通常命名为 build）编译您的项目，并使用 CI/CD artifacts: paths 变量将编译输出存储为 job artifact。

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

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

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

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

yaml
1stages:
2  - build
3  - test
4
5include:
6  - template: Jobs/SAST.gitlab-ci.yml
7
8build:
9  image: gradle:7.6-jdk8
10  stage: build
11  script:
12    - gradle build
13  artifacts:
14    paths:
15      - build/
16
17spotbugs-sast:
18  dependencies:
19    - build
20  variables:
21    COMPILE: "false"
22    SECURE_LOG_LEVEL: debug

指定依赖项（仅限 Maven）#

先决条件：

• 对项目具有开发者、维护者或所有者角色。

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

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

要指定 Maven 依赖项，请对项目的 .gitlab-ci.yml 文件进行以下更改：

1. 将 MAVEN_REPO_PATH 变量设置为指向您的本地 Maven 代码仓库。
2. 确保您的构建作业在该路径创建代码仓库（例如，通过运行 mvn package -Dmaven.repo.local=./.m2/repository）。
3. 配置 spotbugs-sast 作业以依赖于您的构建作业并禁用编译。

以下示例预编译一个 Maven 项目，并将编译后的字节码连同依赖项一起提供给分析器：

yaml
1stages:
2  - build
3  - test
4
5include:
6  - template: Jobs/SAST.gitlab-ci.yml
7
8build:
9  image: maven:3.6-jdk-8-slim
10  stage: build
11  script:
12    - mvn package -Dmaven.repo.local=./.m2/repository
13  artifacts:
14    paths:
15      - .m2/
16      - target/
17
18spotbugs-sast:
19  dependencies:
20    - build
21  variables:
22    MAVEN_REPO_PATH: $CI_PROJECT_DIR/.m2/repository
23    COMPILE: "false"
24    SECURE_LOG_LEVEL: debug

分析器现在可以在扫描期间识别您项目的依赖项。

可用的 CI/CD 变量#

可以使用 .gitlab-ci.yml中的 variables 参数配置 SAST。

使用极狐GitLab SAST 模板时，所有标准 SAST 配置 CI/CD 变量和自定义变量都会传播到底层 SAST 分析器镜像。

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

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

variables:
  SEARCH_MAX_DEPTH: 10

自定义证书颁发机构#

以下分析器版本中引入了对自定义证书颁发机构（CA）的支持。

使用自定义证书颁发机构#

先决条件：

• 对项目具有维护者或开发者角色。

• X.509 PEM 公钥证书的文本表示形式。

  您可以通过以下任一方法提供证书：

  • 直接在项目的 .gitlab-ci.yml 文件中添加证书。
  • 创建一个 file CI/CD 变量，提供证书的路径。
  • 在 UI 中设置一个自定义变量，其中包含证书的文本表示形式。

要信任自定义 CA 证书：

• 将 ADDITIONAL_CA_CERT_BUNDLE 变量设置为您希望在 SAST 环境中信任的 CA 证书包。

例如，要在项目的 .gitlab-ci.yml 文件中配置此值，请使用以下内容：

yaml
1variables:
2  ADDITIONAL_CA_CERT_BUNDLE: |
3      -----BEGIN CERTIFICATE-----
4      MIIGqTCCBJGgAwIBAgIQI7AVxxVwg2kch4d56XNdDjANBgkqhkiG9w0BAQsFADCB
5      ...
6      jWgmPqF3vUbZE0EyScetPJquRFRKIesyJuBFMAs=
7      -----END CERTIFICATE-----

Docker 镜像#

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

漏洞过滤器#

SAST 可以配置为根据文件路径和搜索深度排除代码。以下 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

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

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

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

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

   对于同时支持 SAST_EXCLUDED_PATHS 作为预过滤器和后过滤器的分析器，先应用预过滤器，然后对剩余的任何漏洞应用后过滤器。

4. 对于此变量，路径模式可以是 glob（有关支持的模式，请参阅 doublestar.Match）。如果路径模式与受支持的构建文件匹配，则目录会被排除在构建过程之外：

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

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

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

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

分析器设置#

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

安全扫描器配置#

SAST 分析器内部使用 OSS 安全扫描器执行分析。极狐GitLab 为安全扫描器设置了推荐配置，因此您无需担心调优它们。但是，在极少数情况下，我们的默认扫描器配置可能不适合您的要求。

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

从分析中排除代码#

您可以将单行或代码块标记为排除在漏洞分析之外。在使用这种逐项发现的注释标注方法之前，您应该通过漏洞管理来管理所有漏洞，或者使用 SAST_EXCLUDED_PATHS 调整扫描的文件路径。

使用基于 Semgrep 的分析器时，还可以使用以下选项：

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

  Java 示例：

  java
  vuln_func(); // nosemgrep

  Python 示例：

  python
  vuln_func(); # nosemgrep

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

• //nosemgrep 注释也可以添加到紧接检测之前的那一行。忽略注释和检测到的代码之间不应有其他行（包括其他注释）。

• 忽略文件或目录 - 在代码仓库的根目录或项目的工作目录中创建一个 .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，请将以下默认 SAST 分析器镜像从 registry.gitlab.cn 导入到您的本地 Docker 容器镜像仓库：

plaintext
1registry.gitlab.cn/security-products/clangsa:1
2registry.gitlab.cn/security-products/gitlab-advanced-sast:2
3registry.gitlab.cn/security-products/gitlab-advanced-sast-ext:0
4registry.gitlab.cn/security-products/kubesec:6
5registry.gitlab.cn/security-products/pmd-apex:6
6registry.gitlab.cn/security-products/semgrep:6
7registry.gitlab.cn/security-products/sobelow:6
8registry.gitlab.cn/security-products/spotbugs:5

将 Docker 镜像导入本地离线 Docker 镜像仓库的过程取决于您的网络安全策略。请咨询您的 IT 人员，以找到可接受且经批准的外部资源导入或临时访问流程。这些扫描器会定期更新新定义，您或许可以偶尔自行更新。

有关将 Docker 镜像保存为文件并传输的详细信息，请参阅 Docker 文档中关于以下内容的说明：

• docker save
• docker load
• docker export
• docker import

使用本地 SAST 分析器#

先决条件：

• 对项目具有开发者、维护者或所有者角色。

要使用本地 SAST 分析器：

• 在项目的 .gitlab-ci.yml 文件中，将 CI/CD 变量 SECURE_ANALYZERS_PREFIX 定义为指向您的本地 Docker 容器镜像仓库。

例如：

yaml
variables:
  SECURE_ANALYZERS_PREFIX: "localhost:5000/analyzers"

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

配置软件包的证书检查#

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

在 SELinux 中运行 SAST#

默认情况下，SAST 分析器支持在 SELinux 上托管的极狐GitLab 实例中运行。在覆盖的 SAST 作业中添加 before_script 可能不起作用，因为 SELinux 上托管的 runner 权限受限。

Footnotes#

1. 极狐GitLab Advanced SAST - 仅限旗舰版。 ↩

2. 所有版本。除非另有说明，使用 Semgrep 分析器和 GitLab 管理的规则。 ↩

3. 包括 Java Server Pages (JSP) 和 Android。 ↩

4. 包括 Node.js 和 React。 ↩

5. 极狐GitLab Advanced SAST 对 Swift 和 Objective-C 的支持处于 测试版阶段。分析作为单独的 gitlab-advanced-sast-ext 作业运行，该作业通过共享的 GITLAB_ADVANCED_SAST_ENABLED 变量与极狐GitLab Advanced SAST 一起启用。有关更多信息，请参阅 Swift 和 Objective-C 配置。 ↩ ↩²

6. 包括 Ruby on Rails。 ↩

7. YAML 支持仅限于以下文件模式：

   • application*.yml
   • application*.yaml
   • bootstrap*.yml
   • bootstrap*.yaml
   ↩

8. 所有版本。除非另有说明，使用 Semgrep 分析器和 GitLab 管理的规则。 ↩

9. 所引用的史诗提议为这些语言提供极狐GitLab Advanced SAST 支持。 ↩

10. 带有 find-sec-bugs 插件的 SpotBugs。支持 Gradle、Maven 和 SBT。它也可以与 Gradle wrapper、Grails 和 Maven wrapper 等变体一起使用。但是，SpotBugs 在用于基于 Ant 的项目时存在 限制。对于基于 Ant 的 Java 或 Scala 项目，您应该使用极狐GitLab Advanced SAST 或基于 Semgrep 的分析器。 ↩

11. 包括 Android。 ↩