• 功能
• 要求
• 支持的语言和框架
• 不再支持的分析器
• 高级漏洞追踪
• 自动漏洞解决
• 支持的发行版
  • FIPS-enabled 镜像
• 输出
• 查看 SAST 结果
  • 合并请求小部件
  • 合并请求变更视图
• 配置
  • 在 CI/CD YAML 中配置 SAST
  • 稳定版 vs 最新版 SAST 模板
  • 使用 UI 配置 SAST
    • 使用自定义配置 SAST
    • 仅使用默认设置 SAST
  • 覆盖 SAST 作业
  • 固定到镜像小版本
  • 使用 CI/CD 变量为私有仓库传递凭据
  • 扫描 Rust 应用程序
  • 预编译
  • 可用的 CI/CD 变量
    • 自定义证书颁发机构
    • Docker 镜像
    • 漏洞过滤器
    • 分析器设置
    • 安全扫描器配置
    • 自定义 CI/CD 变量
  • 从分析中排除代码
• 在离线环境中运行 SAST
  • 离线 SAST 的需求
  • 让极狐GitLab SAST 分析器镜像在您的 Docker 仓库中可用
    • 如果需要支持自定义的证书颁发机构
  • 将 SAST CI/CD 变量设置为使用本地 SAST 分析器
  • 配置软件包证书检查
• 在 SELinux 中运行 SAST

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

如果您使用极狐GitLab CI/CD，您可以使用静态应用程序安全测试 (SAST) 检查源代码中的已知漏洞。您可以在任何级别的版本中运行 SAST 分析器。分析器将 JSON 格式的报告作为作业产物输出。

使用旗舰版，还可以处理 SAST 结果以：

• 在审核工作流程中进行使用。
• 在安全仪表盘中进行审查。

有关更多详细信息，请参阅功能摘要。

功能

下面列出了不同级别的极狐GitLab 用户能用的 SAST 功能。

要求

在您的实例上运行 SAST 分析器之前，确保您有以下内容：

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

支持的语言和框架

极狐GitLab SAST 支持扫描多种编程语言和框架。 一旦您启用 SAST，即使您的项目使用多种语言，正确的分析器集也会自动运行。

脚注：

1. 基于 SpotBugs 的分析器支持 Gradle、Maven 和 SBT。它还可以与诸如 Gradle wrapper、Grails 和 Maven wrapper的变量一起使用。对于基于 Ant 的 Java 或 Scala 项目，我们建议使用基于 Semgrep 的分析器。

不再支持的分析器

如下极狐GitLab 分析器已经不再受支持而且也不会接受到更新。它们已经被具有极狐GitLab 管理规则的基于 Semgrep 的分析器取代。

当您升级到极狐GitLab 17.3.1 后，数据迁移会自动解决从不再支持的分析器中发现的漏洞。这会包含下表中列出的分析器，除了 SpotBugs，因为 SpotBugs 仍然扫描 Groovy 代码。迁移仅会解决您未确认或已忽略的漏洞，不会影响已自动被转换为基于 Semgrep 的扫描所发现的漏洞。

高级漏洞追踪

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

极狐GitLab SAST 使用高级漏洞追踪算法来更准确地识别当相同的漏洞由于重构或无关的更改而在文件内移动时。

高级漏洞追踪在 支持的语言和框架 和 分析器 的子集可用：

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

自动漏洞解决

• 引入于极狐GitLab 15.9，使用名为 sec_mark_dropped_findings_as_resolved 的项目级功能标志。
• 在极狐GitLab 15.10 中默认启用。
• 在极狐GitLab 16.2 中移除了功能标志。

To help you focus on the vulnerabilities that are still relevant, GitLab SAST automatically resolves vulnerabilities when:

要帮您聚焦在依旧相关的漏洞上，极狐GitLab SAST 在以下情况下自动解决漏洞：

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

自动解决仅对从基于 Semgrep 分析器中发现的漏洞可用。漏洞管理系统会在自动解决的漏洞上添加注释以便您仍然拥有漏洞的历史记录。

如果您在随后重新启用了规则，发现将重新打开并重新进行追踪。

支持的发行版

默认扫描器镜像是在基本 Alpine 镜像的基础上构建的，以确保大小和可维护性。

FIPS-enabled 镜像

极狐GitLab 提供了一个基于 Red Hat UBI 基础镜像的镜像版本，它使用 FIPS 140-验证的密码模块。要使用 FIPS-enabled 的镜像，您可以：

• 将 SAST_IMAGE_SUFFIX 设置为 -fips。
• 将 -fips 扩展添加到默认图像名称。

variables:
  SAST_IMAGE_SUFFIX: '-fips'

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

FIPS-compliant 镜像仅适用于高级 SAST 和基于 Semgrep 的分析器。

输出

SAST 的输出文件 gl-sast-report.json 作为作业产物。该文件包含所有检测到的漏洞的详细信息。您可以下载 产物文件在极狐GitLab 之外进行处理。

更多详情可查看：

• SAST 报告文件格式
• SAST 报告文件示例

查看 SAST 结果

SAST 报告文件被极狐GitLab 处理，然后在 UI 中显示以下内容：

• 合并请求小部件
• 合并请求变更视图
• 漏洞报告

一个流水线可以包含多个作业，包含 SAST 和 DAST 扫描。如果由于任何原因导致任何作业失败，则安全仪表盘就不会显示 SAST 扫描输出。比如，如果 SAST 作业结束了但是 DAST 作业失败了，则安全仪表盘不会显示 SAST 结果。在失败情况下，分析器会输出一个 退出码。

合并请求小部件

如果从目标分支生成的报告可用于比较，则 SAST 结果会展示在合并请求的小部件区域中。合并请求小部件会展示 SAST 结果和在合并请求中的变更引入的解决方案。

合并请求变更视图

• 引入于极狐GitLab 16.6，使用名为 sast_reports_in_inline_diff 的功能标志。默认禁用。
• 在极狐GitLab 16.8 中默认启用。
• 在极狐GitLab 16.9 中移除功能标志。

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

配置

SAST 扫描在您的 CI/CD 流水线中运行。当您将极狐GitLab 管理的 CI/CD 模板添加到您的流水线时，正确的 SAST 分析器会自动扫描您的代码并将结果保存为 SAST 报告产物。

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

• 使用 Auto DevOps 提供的 Auto SAST。
• 在 CI/CD YAML 中配置 SAST。
• 使用 UI 配置 SAST（引入于 13.3 版本）。

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

要配置高级 SAST（仅在专业版及以上版本可用），请参阅 高级 SAST配置。

在 CI/CD YAML 中配置 SAST

要启用 SAST，您必须包括 SAST.gitlab-ci.yml 模板，模板作为极狐GitLab 安装实例的一部分提供。

将以下内容添加到您的 .gitlab-ci.yml 文件中：

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

包含的模板在您的 CI/CD 流水线中创建 SAST 作业，并扫描您项目的源代码以查找可能的漏洞。

结果保存为 SAST 报告产物，下载时，您始终会收到可用的最新 SAST 产物。

稳定版 vs 最新版 SAST 模板

SAST 提供了两个模板，用于将安全测试集成到您的 CI/CD 流水线中：

• SAST.gitlab-ci.yml (推荐)

  稳定的模板提供了一个可靠和一致的 SAST 经验。您应该使用稳定模板，对于大多数用户和项目，需要在 CI/CD 流水线中保持稳定性和可预测性。

• SAST.latest.gitlab-ci.yml

  此模板是为那些想访问和测试最新功能的用户设计的。它不被认为是稳定的，可能会包含计划在下一个主要版本发布的破坏性更改。此模板允许您在它们成为稳定版本的一部分之前尝试新功能和更新，使它非常适合那些能够容忍潜在不稳定性和渴望提供新功能反馈的用户。

使用 UI 配置 SAST

您可以使用默认设置或自定义在 UI 中启用和配置 SAST。 您可以使用的方法取决于您的极狐GitLab 产品级别。

使用自定义配置 SAST

• 从 UI 中移除个人 SAST 分析器配置选项于极狐GitLab 16.2。

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

Pipelines now include a SAST job.

1. 在左侧导航栏，选择 搜索或前往 并找到您的项目。
2. 选择 安全 > 安全配置。
3. 如果默认分支的流水线已经完成并生成了有效的 SAST 产物，请选择 配置 SAST，否则选择 启用 SAST。

4. 输入自定义 SAST 值。

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

5. 选择 创建合并请求。
6. 查看并合并合并请求。

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

仅使用默认设置 SAST

引入于 13.9 版本。

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

1. 在左侧边栏中，选择 搜索或转到 并找到您的项目。
2. 选择 安全 > 安全配置。
3. 在 SAST 部分中，选择 使用合并请求配置。
4. 查看并合并合并请求，来启用 SAST。

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

覆盖 SAST 作业

要覆盖作业定义（例如，更改 variables、dependencies 或规则等属性），请声明与要覆盖的 SAST 作业同名的作业。将此新作业放在模板包含之后，并在其下指定任何其他键。例如，为 spotbugs 分析器启用 FAIL_NEVER：

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

spotbugs-sast:
  variables:
    FAIL_NEVER: 1

固定到镜像小版本

极狐GitLab 管理的 CI/CD 模板指定一个主要版本，并自动在该主要版本中提取最新的分析器版本。

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

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

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

您可以将标签设置为：

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

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

include:
  - template: Security/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 变量将用户名和密码传递给私有 Go 仓库

如果您的 Go 项目依赖于私有模块，请参阅从私有项目中获取模块，了解如何通过 HTTPS 提供身份验证。

要通过 ~/.netrc 指定凭据，请提供包含以下内容的 before_script：

gosec-sast:
  before_script:
    - |
      cat <<EOF > ~/.netrc
      machine gitlab.com
      login $CI_DEPLOY_USER
      password $CI_DEPLOY_PASSWORD
      EOF
``` -->

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

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

<!--
Read more on [how to use private Maven repositories](../index.md#using-private-maven-repositories).
-->

### 启用 Kubesec 分析器

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

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

variables:
  SCAN_KUBERNETES_MANIFESTS: "true"

扫描 Rust 应用程序

要扫描 Rust 应用程序，您必须：

1. 提供一个自定义的 Rust 规则集。在项目库更目录的 .gitlab/ 下创建一个名为 sast-ruleset.toml 的文件，添加以下内容：

   [semgrep]
     description = "Rust ruleset for Semgrep"
     targetdir = "/sgrules"
     timeout = 60
   
     [[semgrep.passthrough]]
       type  = "url"
       value = "https://semgrep.dev/c/p/rust"
       target = "rust.yml"
   

   此配置使用了开源的 Smgrep 规则集。更多请阅读自定义规则集。

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

   include:
     - template: Jobs/SAST.gitlab-ci.yml
   
   semgrep-sast:
     rules:
       - if: $CI_COMMIT_BRANCH
         exists:
           - '**/*.rs'
           # include any other file extensions you need to scan from the semgrep-sast template: Jobs/SAST.gitlab-ci.yml
   

预编译

大多数 SAST 分析器直接扫描您的源代码，而无需先编译它。但是，出于技术原因，一些分析器只能扫描编译后的代码。

默认情况下，这些分析器会自动尝试获取依赖项并编译您的代码，以便对其进行扫描。如果出现以下情况，自动编译可能会失败：

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

要解决这些问题，您可以跳过分析器的编译步骤，而是直接提供流水线早期阶段的产物。这种策略称为预编译。

预编译可用于支持 COMPILE CI/CD 变量的分析器。 有关当前列表，请参阅分析器设置。

要使用预编译：

1. 将项目的依赖输出到项目工作目录中的一个目录，然后通过设置 artifacts:paths 配置，将该目录保存为产物。
2. 向分析器提供 COMPILE: "false" CI/CD 变量，禁用自动编译。
3. 将您的编译阶段添加为分析器作业的依赖项。

要允许分析器识别编译的产物，您必须明确指定 vendored 目录的路径。 此配置可能因分析仪而异。对于 Maven 项目，您可以使用 MAVEN_REPO_PATH。 有关可用选项的完整列表，请参阅分析器设置。

以下示例预编译了一个 Maven 项目并将其提供给 SpotBugs SAST 分析器：

stages:
  - build
  - test

include:
  - template: Security/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"
  artifacts:
    reports:
      sast: gl-sast-report.json

可用的 CI/CD 变量

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

以下示例包含用于将 SEARCH_MAX_DEPTH 变量覆盖为 10 的 SAST 模板。模板是之前评估的流水线配置，因此最后提及的变量优先。

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

variables:
  SEARCH_MAX_DEPTH: 10

自定义证书颁发机构

要信任自定义证书颁发机构，请将 ADDITIONAL_CA_CERT_BUNDLE 变量设置为您希望在 SAST 环境中信任的 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 变量。

漏洞过滤器

一些分析器可以过滤掉特定阈值下的漏洞。

分析器设置

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

安全扫描器配置

SAST 分析器在内部使用 OSS 安全扫描器来执行分析。我们为安全扫描程序设置了推荐配置，这样您就不必担心调整它们。但是，在极少数情况下，我们的默认扫描器配置不符合您的要求。

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

自定义 CI/CD 变量

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

从分析中排除代码

您可以标记单独的代码行或块以将它们排除在漏洞分析之外。您应该通过漏洞管理来管理所有的漏洞或在使用此方法之前用 SAST_EXCLUDED_PATHS 调整扫描文件的路径。

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

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

  Java 示例：

  vuln_func(); // nosemgrep
  

  Python 示例：

  vuln_func(); # nosemgrep
  

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

• 忽略文件或目录 - 在仓库的根目录或项目的工作目录中创建 .semgrepignore 文件，并添加文件和文件夹的模式。

在离线环境中运行 SAST

对于在受限环境中搭建的私有化部署实例，要成功运行 SAST 作业需要做一些调整。更多详情，可以查看离线环境。

离线 SAST 的需求

要使用 SAST 在离线环境中运行，您需要：

• 极狐GitLab Runner 采用 docker 或 kubernetes 执行器。
• 一个具有 SAST 分析器镜像副本的本地 Docker 镜像仓库。
• 配置软件包证书检查（可选）。

极狐GitLab Runner 有一个 默认的 pull_policy 为 always，意味着 runner 会尝试从 GitLab 容器注册表拉取 Docker 镜像，即使本地有可用的镜像副本。在离线环境中，您可以将 pull_policy 设置为 if-not-present，以仅使用本地可用的 Docker 镜像。然而，我们建议在非离线环境中保持 pull_policy 设置为 always，以启用 CI/CD 流水线中的更新扫描器。

让极狐GitLab SAST 分析器镜像在您的 Docker 仓库中可用

对于所有支持语言和框架的 SAST，会将如下默认的 SAST 分析器镜像从 registry.gitlab.com 导入到您的本地 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 管理员来找到可接受且可被批准的能够让外部资源被临时访问的流程。这些扫描器会用新的定义周期性更新，因此您也需要定期更新。

For details on saving and transporting Docker images as a file, see the Docker documentation on docker save, docker load, docker export, and docker import.

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

对于自定义证书颁发机构的支持引入于如下版本：

将 SAST CI/CD 变量设置为使用本地 SAST 分析器

在您的 .gitlab-ci.yml 文件中添加如下配置。您必须将 SECURE_ANALYZERS_PREFIX 替换为您的本地 Docker 容器仓库：

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

variables:
  SECURE_ANALYZERS_PREFIX: "localhost:5000/analyzers"

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

配置软件包证书检查

如果 SAST 作业涉及软件包管理器，您必须配置其证书验证。在离线环境中，无法使用外部来源进行证书验证。要么使用自签名证书，要么禁用证书验证。请参考软件包管理器的文档以获取说明。

在 SELinux 中运行 SAST

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