• 用例
• 要求
• 支持的语言和框架
• 多项目支持
  • 为安全代码扫描启用多项目支持
  • 误报检测
  • 高级漏洞跟踪
• 支持的发行版
  • FIPS-enabled 镜像
    • 每个级别的功能摘要
• 配置
  • 在 CI/CD YAML 中配置 SAST
  • 在 UI 中配置 SAST
  • 在 UI 中使用自定义配置 SAST
  • 在 UI 中仅使用默认设置 SAST
  • 覆盖 SAST 作业
  • 固定到镜像小版本
  • 使用 CI/CD 变量为私有仓库传递凭据
    • 使用 CI/CD 变量将用户名和密码传递给私有 Go 仓库
    • 使用 CI/CD 变量将用户名和密码传递给私有 Maven 仓库
  • 启用 Kubesec 分析器
  • 预编译
  • 可用的 CI/CD 变量
    • 日志级别
    • 自定义证书颁发机构
    • Docker 镜像
    • 漏洞过滤器
    • 分析器设置
    • 安全扫描器配置
    • 自定义 CI/CD 变量
• 报告 JSON 格式
• 在 SELinux 中运行 SAST
• 故障排除
  • SAST 调试日志记录
  • Error response from daemon: error processing tar file: docker-tar: relocation error
  • 收到警告信息 gl-sast-report.json: no matching files
  • 使用 rules:exists 的限制
  • SpotBugs UTF-8 无法映射的字符错误
  • SpotBugs Error: Project couldn't be built
  • Flawfinder 编码错误
  • Semgrep 缓慢、意外结果或其他错误
  • MobSF 作业失败，错误消息 Reading from Info.plist

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

在 13.3 版本中，所有开源 (OSS) 分析器都从旗舰版迁移到了免费版。

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

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

• 在合并请求中查看它们。
• 在审核工作流程中使用它们。
• 在安全仪表盘中查看它们。

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

结果按漏洞的优先级排序：

1. Critical
2. High
3. Medium
4. Low
5. Info
6. Unknown

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

用例

• 您的代码在类中具有潜在危险属性，或者可能导致意外代码执行的不安全代码。
• 您的应用程序容易受到跨站点脚本 (XSS) 攻击，这些攻击可用于未经授权访问会话数据。

要求

SAST 在 test 阶段运行，默认情况下可用。如果在 .gitlab-ci.yml 文件中重新定义阶段，则需要 test 阶段。

要运行 SAST 作业，默认情况下，您需要带有 docker 或 kubernetes 执行器。 如果您在 JihuLab.com 上使用共享 runner，则默认启用此功能。

支持的语言和框架

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

1. .NET 4 支持有限。分析器在 Linux 容器中运行，并且无法访问特定于 Windows 的库或功能。如果您需要 .NET 4 支持，请使用基于 Semgrep 的扫描程序。
2. 基于 SpotBugs 的分析器支持 Gradle、Maven 和 SBT。它还可以与 Gradle wrapper、Grails 和 Maven 包装器。但是，当用于基于 Ant 的项目时，SpotBugs 有局限性。我们建议对基于 Ant 的 Java 项目使用基于 Semgrep 的分析器。

多项目支持

引入于 13.7 版本。

SAST 可以扫描包含多个项目的仓库。

以下分析器具有多项目支持：

• Bandit
• ESLint
• Gosec
• Kubesec
• NodeJsScan
• MobSF
• PMD
• Security Code Scan
• Semgrep
• SpotBugs
• Sobelow

为安全代码扫描启用多项目支持

安全代码扫描中的多项目支持需要仓库根目录中的解决方案 (.sln) 文件。有关解决方案格式的详细信息，请参阅 Microsoft 解决方案 (.sln) 文件。

误报检测

引入于 14.2 版本。

已检测到且为误报的漏洞将在安全仪表板中标记为误报。

支持的语言和分析器的子集提供了误报检测：

• Ruby，在基于 Brakeman 的分析器中

高级漏洞跟踪

引入于 14.2 版本。

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

SAST 使用先进的漏洞跟踪算法来更准确地识别由于重构或无关更改而在文件中移动的相同漏洞。

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

• C，仅在基于 Semgrep 的分析器中
• Go，在基于 Gosec 和 Semgrep 的分析器中
• Java，仅在基于 Semgrep 的分析器中
• JavaScript，仅在基于 Semgrep 的分析器中
• Python，仅在基于 Semgrep 的分析器中
• Ruby，在基于 Brakeman 的分析器中

支持的发行版

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

FIPS-enabled 镜像

引入于 14.10 版本。

极狐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 镜像仅适用于基于 Semgrep 的分析器。

要以 FIPS-compliant 的方式使用 SAST，您必须排除其他分析器运行。

每个级别的功能摘要

不同的产品级别提供不同的功能，如下表所示：

配置

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

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

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

您可以通过强制扫描执行，在许多项目中启用 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 产物。

在 UI 中配置 SAST

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

• 在 UI 中使用自定义配置 SAST。
• 在 UI 中仅使用默认配置 SAST。

在 UI 中使用自定义配置 SAST

• 引入于 13.3 版本。
• 优化于 13.4 版本。
• 优化于 13.5 版本。

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

1. 在顶部栏上，选择 菜单 > 项目 并找到您的项目。
2. 在左侧边栏中，选择 安全与合规 > 配置。
3. 如果项目没有 .gitlab-ci.yml 文件，在静态应用程序安全测试（SAST）行选择 启用 SAST，否则选择 配置 SAST。

4. 输入自定义 SAST 值。

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

5. 或者，展开 SAST 分析器 部分，选择单个 SAST 分析器并输入自定义分析器值。
6. 选择 创建合并请求。
7. 查看并合并合并请求。

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

在 UI 中仅使用默认设置 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 变量。

启用 Kubesec 分析器

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

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

variables:
  SCAN_KUBERNETES_MANIFESTS: "true"

预编译

大多数 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。

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

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

variables:
  SAST_GOSEC_LEVEL: 2

日志级别

引入于 13.1 版本。

要控制日志的详细程度，请设置 SECURE_LOG_LEVEL 环境变量。输出此日志级别或更高级别的消息。

从最高到最低严重性，日志记录级别是：

• fatal
• error
• warn
• info（默认）
• debug

自定义证书颁发机构

要信任自定义证书颁发机构，请将 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 分析器镜像。

报告 JSON 格式

SAST 以 JSON 格式输出报告文件。报告文件包含所有发现的漏洞的详细信息。 要下载报告文件，您可以：

• 从 CI/CD 流水线页面下载文件。
• 在合并请求的流水线选项卡中，将 artifacts: paths 设置为 gl-sast-report.json。

有关信息，请参阅下载作业产物。

在 SELinux 中运行 SAST

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

故障排除

SAST 调试日志记录

将全局 CI 变量中的安全扫描器日志详细程度调整到 debug，以帮助排除 SAST 作业的故障。

variables:
  SECURE_LOG_LEVEL: "debug"

Error response from daemon: error processing tar file: docker-tar: relocation error

当运行 SAST 作业的 Docker 版本为 19.03.0 时会出现此错误。考虑更新到 Docker 19.03.1 或更高版本。旧版本不受影响。

收到警告信息 gl-sast-report.json: no matching files

有关这方面的信息，请参阅一般应用程序安全故障排除部分。

使用 rules:exists 的限制

SAST CI 模板使用rules:exists参数。出于性能原因，针对给定的 glob 模式进行最大匹配数。 果匹配数超过最大值，则 rules:exists 参数返回 true。根据仓库中的文件数量，即使扫描程序不支持您的项目，也可能会触发 SAST 作业。有关此问题的更多详细信息，请参阅 rules:exists 文档。

SpotBugs UTF-8 无法映射的字符错误

当 SpotBugs 构建中未启用 UTF-8 编码并且源代码中有 UTF-8 字符时，会发生这些错误。要修复此错误，请为项目的构建工具启用 UTF-8。

对于 Gradle 构建，将以下内容添加到您的 build.gradle 文件中：

compileJava.options.encoding = 'UTF-8'
tasks.withType(JavaCompile) {
    options.encoding = 'UTF-8'
}

对于 Maven 构建，将以下内容添加到您的 pom.xml 文件中：

<properties>
  <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
</properties>

SpotBugs Error: Project couldn't be built

如果您的作业在构建步骤中失败并显示 Project couldn't be built 消息，这很可能是因为您的作业要求 SpotBugs 使用不属于其默认工具的工具进行构建。

解决方案是使用预编译。预编译确保 SpotBugs 所需的图像在作业的容器中可用。

Flawfinder 编码错误

当 Flawfinder 遇到无效的 UTF-8 字符时会发生这种情况。要解决此问题，请将项目中的所有源代码转换为 UTF-8 字符编码。可以通过 cvt2utf 或 iconv，在整个项目或每个作业中使用 before_script 功能。

Semgrep 缓慢、意外结果或其他错误

如果 Semgrep 速度慢、报告太多误报或误报、崩溃、失败或以其他方式损坏，请参阅 Semgrep 文档以了解如何进行故障排除。

MobSF 作业失败，错误消息 Reading from Info.plist

当 Info.plist 文件缺少 CFBundleIdentifier 键和字符串值时，会发生此错误。