静态应用程序安全测试 (SAST)

  • Tier: 基础版,专业版,旗舰版
  • Offering: JihuLab.com, 私有化部署

静态应用程序安全测试 (SAST) 在代码投入生产之前发现代码中的漏洞。SAST 直接集成到您的 CI/CD 流水线中,在开发阶段识别安全问题,此时修复问题是最简单和最具成本效益的。

在开发后期发现的安全漏洞会导致昂贵的延误和潜在的漏洞。SAST 扫描会在每次提交时自动进行,提供即时反馈而不打乱您的工作流程。

特性#

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

功能在基础版和专业版中可用在旗舰版中可用
使用开源分析器进行基础扫描
可下载的 SAST JSON 报告
使用极狐GitLab高级SAST进行跨文件、跨功能扫描
合并请求小部件中的新发现
合并请求更改视图中的新发现
漏洞管理
基于 UI 的扫描器配置
规则集定制
高级漏洞跟踪

要求#

在您的实例中运行 SAST 分析器之前,请确保您具备以下条件:

  • 基于 Linux 的极狐GitLab Runner,使用 dockerkubernetes 执行器。如果您使用极狐GitLab.com的托管 runner,这会默认启用。
    • Windows Runners 不支持。
    • 不支持 amd64 以外的 CPU 架构。
  • 极狐GitLab CI/CD 配置 (.gitlab-ci.yml) 必须包含 test 阶段,默认情况下已包含。如果您在 .gitlab-ci.yml 文件中重新定义阶段,则需要 test 阶段。

支持的语言和框架#

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

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

  • 在旗舰版中,极狐GitLab高级SAST 提供更准确的结果。您应该为它支持的语言使用它。
  • 在所有版本中,您可以使用基于开源扫描器的极狐GitLab提供的分析器来扫描您的代码。
语言极狐GitLab高级SAST (仅限旗舰版) 支持由其他 分析器 支持 (所有版本)
Apex (Salesforce) 是: PMD-Apex
C 否; 是: Semgrep 使用 极狐GitLab管理的规则
C++ 否; 是: Semgrep 使用 极狐GitLab管理的规则
C# 是: Semgrep 使用 极狐GitLab管理的规则
Elixir (Phoenix) 是: Sobelow
Go 是: Semgrep 使用 极狐GitLab管理的规则
Groovy 是: SpotBugs 使用 find-sec-bugs 插件1
Java 是,包括 Java Server Pages (JSP) 是: Semgrep 使用 极狐GitLab管理的规则 (包括 Android)
JavaScript, 包括 Node.js 和 React 是: Semgrep 使用 极狐GitLab管理的规则
Kotlin 否; 是: Semgrep 使用 极狐GitLab管理的规则 (包括 Android)
Objective-C (iOS) 是: Semgrep 使用 极狐GitLab管理的规则
PHP 否; 是: Semgrep 使用 极狐GitLab管理的规则
Python 是: Semgrep 使用 极狐GitLab管理的规则
Ruby, 包括 Ruby on Rails 是: Semgrep 使用 极狐GitLab管理的规则
Scala 否; 是: Semgrep 使用 极狐GitLab管理的规则
Swift (iOS) 是: Semgrep 使用 极狐GitLab管理的规则
TypeScript 是: Semgrep 使用 极狐GitLab管理的规则
YAML2 是: Semgrep 使用 极狐GitLab管理的规则
Java Properties 是: Semgrep 使用 极狐GitLab管理的规则

脚注:

  1. 基于 SpotBugs 的分析器支持 Gradle、Maven 和 SBT。它也可以用于变体,如 Gradle wrapper、Grails 和 Maven wrapper。然而,SpotBugs 在针对 Ant-based 项目时有一些限制。您应该使用极狐GitLab高级SAST或基于 Semgrep 的分析器用于 Ant-based Java 或 Scala 项目。

  2. YAML 支持仅限于以下文件模式:

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

SAST CI/CD 模板还包括一个分析器作业,可以扫描 Kubernetes 清单和 Helm charts;此作业默认关闭。 请参阅启用 Kubesec 分析器或考虑基础设施即代码扫描,它支持其他平台。

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

高级漏洞跟踪#

  • Tier: 旗舰版
  • Offering: JihuLab.com, 私有化部署

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

极狐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 的分析器

自动漏洞解决#

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

为了帮助您关注仍然相关的漏洞,极狐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高级SAST和基于 Semgrep 的分析器。

要以 FIPS 合规的方式使用 SAST,您必须[排除其他分析器运行](analyzers.md#customize-analyzers)。如果您在[非 root 用户](https://gitlab.cn/docs/runner/install/kubernetes_helm_chart_configuration.html#run-with-non-root-user)的 runner 中使用 FIPS 启用的镜像运行高级 SAST 或 Semgrep,您必须更新 `runners.kubernetes.pod_security_context` 下的 `run_as_user` 属性,以使用由镜像[创建的 gitlab 用户](https://jihulab.com/gitlab-cn/security-products/analyzers/semgrep/-/blob/a5d822401014f400b24450c92df93467d5bbc6fd/Dockerfile.fips#L58)的 ID,即 `1000`。

漏洞详情#

SAST 漏洞根据发现的漏洞的主要通用弱点枚举 (CWE) 标识符命名。 阅读每个漏洞发现的描述,以了解扫描器检测到的具体问题。

有关 SAST 覆盖范围的更多信息,请参阅 SAST 规则

下载 SAST 报告#

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

查看 SAST 结果#

  • Tier: 旗舰版
  • Offering: JihuLab.com, 私有化部署

在旗舰版中,SAST 报告文件由极狐GitLab处理,详细信息显示在 UI 中:

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

合并请求小部件#

如果目标分支有可供比较的报告,SAST 结果会显示在合并请求小部件区域中。 合并请求小部件显示:

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

结果在可用时使用高级漏洞跟踪进行比较。

安全合并请求小部件

合并请求更改视图#

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

SAST 结果显示在合并请求 更改 视图中。包含 SAST 问题的行在边栏旁边标记为符号。选择符号查看问题列表,然后选择一个问题查看其详细信息。

SAST 行内指示器

贡献您的扫描器#

安全扫描器集成文档解释了如何将其他安全扫描器集成到极狐GitLab。

配置#

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

要为项目配置 SAST,您可以:

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

要配置高级 SAST(仅在极狐GitLab旗舰版中提供),请按照这些说明

您可以更改配置变量自定义检测规则,如果需要,但极狐GitLab SAST 设计为在其默认配置中使用。

在您的 CI/CD YAML 中配置 SAST#

要启用 SAST,您可以包含 SAST.gitlab-ci.yml 模板。 该模板作为极狐GitLab安装的一部分提供。

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

yaml
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#

  • Tier: 旗舰版
  • Offering: JihuLab.com, 私有化部署

在极狐GitLab 16.2 中移除 UI 中的单独 SAST 分析器配置选项。

配置工具在没有现有 `.gitlab-ci.yml` 文件或具有最小配置文件时效果最佳。如果您有一个复杂的极狐GitLab配置文件,它可能无法成功解析,并可能发生错误。

要启用和配置 SAST 以及自定义设置:

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

  2. 选择 安全 > 安全配置

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

  4. 输入自定义 SAST 值。

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

  5. 选择 创建合并请求

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

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

仅使用默认设置配置 SAST#

配置工具在没有现有 `.gitlab-ci.yml` 文件或具有最小配置文件时效果最佳。如果您有一个复杂的极狐GitLab配置文件,它可能无法成功解析,并可能发生错误。

要启用并仅使用默认设置配置 SAST:

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

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

覆盖 SAST 作业#

要覆盖作业定义(例如,更改 variablesdependenciesrules 等属性),声明一个与 SAST 作业名称相同的作业进行覆盖。在模板包含之后放置此新作业,并在其下指定任何其他键。例如,这为 spotbugs 分析器启用 FAIL_NEVER

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

固定次要镜像版本#

极狐GitLab管理的 CI/CD 模板指定一个主要版本,并自动拉取该主要版本内的最新分析器发布。

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

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

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

您可以将标签设置为:

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

此示例使用 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 的分析器来扫描极狐GitLab管理的规则集不支持的语言。然而,由于极狐GitLab不提供这些其他语言的规则集,您必须提供一个自定义规则集来覆盖它们。您还必须修改 semgrep-sast CI/CD 作业的 rules,使作业在相关文件被修改时运行。

扫描 Rust 应用程序#

例如,要扫描 Rust 应用程序,您必须:

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

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

    了解有关自定义规则集的更多信息。

  2. 覆盖 semgrep-sast 作业以添加检测 Rust (.rs) 文件的规则。在 .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 - '**/*.rs' 9 # 包含来自 semgrep-sast 模板的任何其他需要扫描的文件扩展名: Jobs/SAST.gitlab-ci.yml

使用 SpotBugs 分析器进行预编译#

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

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

自动编译可能会失败。

为了解决这些问题,您应该跳过分析器的编译步骤,直接提供流水线中较早阶段的产物。 这种策略称为_预编译_。

共享预编译产物#

  1. 使用编译作业(通常名为 build)编译您的项目,并使用 artifacts: paths 存储编译输出为 作业产物

    • 对于 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 项目,并将编译后的字节码连同依赖项一起提供给分析器:

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 模板,以在所有作业中覆盖 SEARCH_MAX_DEPTH 变量为 10。模板在流水线配置之前被评估,因此变量的最后一次提及优先。

yaml
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 文件中配置此值,请使用以下内容:

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

ADDITIONAL_CA_CERT_BUNDLE 值也可以在 UI 中配置为自定义变量,可以作为 文件,这需要证书的路径,或者作为变量,这需要证书的文本表示。

Docker 镜像#

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

CI/CD 变量描述
SECURE_ANALYZERS_PREFIX覆盖提供默认镜像的 Docker 注册表名称(代理)。阅读更多关于自定义分析器
SAST_EXCLUDED_ANALYZERS永远不应运行的默认镜像名称。阅读更多关于自定义分析器
SAST_ANALYZER_IMAGE_TAG覆盖分析器镜像的默认版本。阅读更多关于固定分析器镜像版本
SAST_IMAGE_SUFFIX添加到镜像名称的后缀。如果设置为 -fips,则使用 FIPS 启用镜像进行扫描。请参阅FIPS 启用镜像了解更多详细信息。

漏洞过滤器#

CI/CD variableDescriptionDefault ValueAnalyzer
SAST_EXCLUDED_PATHS Comma-separated list of paths for excluding vulnerabilities. The exact handling of this variable depends on which analyzer is used.1
text
,[object Object],
Semgrep2,3
GitLab Advanced SAST2,3
All other SAST analyzers3
SAST_SPOTBUGS_EXCLUDED_BUILD_PATHS Comma-separated list of paths for excluding directories from being built and scanned. None SpotBugs4
SEARCH_MAX_DEPTH The number of directory levels the analyzer will descend into when searching for matching files to scan.5
text
,[object Object],
Semgrep
GitLab Advanced SAST
text
,[object Object],
All other SAST analyzers

脚注:

  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 实现为一个后过滤器,在扫描执行之后应用。

    模式可以是 globs,或者文件或文件夹路径(例如,doc,spec)。父目录也与模式匹配。

    SAST_EXCLUDED_PATHS 的后过滤器实现可用于所有 SAST 分析器。某些 SAST 分析器,例如那些具有上标 2 的分析器,既实现为预过滤器又实现为后过滤器。预过滤器更为高效,因为它减少了需要扫描的文件数量。

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

  4. 对于此变量,路径模式可以是 globs(参见 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

    为模式传递父目录,例如 projectproject/subdir,_不会_排除该目录,因为在这种情况下,构建文件_没有_被模式显式匹配。

  5. SAST CI/CD 模板 搜索存储库以检测使用的编程语言,并选择匹配的分析器。然后,每个分析器在代码库中搜索其应扫描的特定文件或目录。设置 SEARCH_MAX_DEPTH 的值以指定分析器的搜索阶段应跨越多少目录级别。

分析器设置#

某些分析器可以通过 CI/CD 变量进行定制。

CI/CD 变量分析器描述
GITLAB_ADVANCED_SAST_ENABLED极狐GitLab Advanced SAST设置为 true 以启用极狐GitLab Advanced SAST 扫描(仅适用于极狐GitLab 旗舰版)。默认值:false
SCAN_KUBERNETES_MANIFESTSKubesec设置为 "true" 以扫描 Kubernetes manifests。
KUBESEC_HELM_CHARTS_PATHKubesec可选路径,helm 使用此路径生成 kubesec 扫描的 Kubernetes manifest。如果定义了依赖项,应该在 before_script 中运行 helm dependency build 以获取必要的依赖项。
KUBESEC_HELM_OPTIONSKubesechelm 可执行文件的附加参数。
COMPILESpotBugs设置为 false 以禁用项目编译和依赖项获取。
ANT_HOMESpotBugsANT_HOME 变量。
ANT_PATHSpotBugsant 可执行文件的路径。
GRADLE_PATHSpotBugsgradle 可执行文件的路径。
JAVA_OPTSSpotBugsjava 可执行文件的附加参数。
JAVA_PATHSpotBugsjava 可执行文件的路径。
SAST_JAVA_VERSIONSpotBugs使用哪个 Java 版本。自极狐GitLab 15.0 开始,支持的版本是 1117(默认)。在极狐GitLab 15.0 之前,支持的版本是 8(默认)和 11
MAVEN_CLI_OPTSSpotBugsmvnmvnw 可执行文件的附加参数。
MAVEN_PATHSpotBugsmvn 可执行文件的路径。
MAVEN_REPO_PATHSpotBugsMaven 本地存储库的路径(maven.repo.local 属性的快捷方式)。
SBT_PATHSpotBugssbt 可执行文件的路径。
FAIL_NEVERSpotBugs设置为 1 以忽略编译失败。
SAST_SEMGREP_METRICSSemgrep设置为 "false" 以禁用向 r2c 发送匿名扫描指标。默认值:true
SAST_SCANNER_ALLOWED_CLI_OPTSSemgrep在运行扫描操作时传递给底层安全扫描器的 CLI 选项(带值的参数或标志)。只有有限的一组选项被接受。使用空格或等号 (=) 字符分隔 CLI 选项及其值。例如:name1 value1name1=value1。多个选项必须用空格分隔。例如:name1 value1 name2 value2。在 GitLab 15.3 中引入。
SAST_RULESET_GIT_REFERENCE全部定义自定义规则集配置文件的路径。如果项目中提交了 .gitlab/sast-ruleset.toml 文件,则该本地配置优先于 SAST_RULESET_GIT_REFERENCE 中的文件。此变量仅适用于旗舰版。
SECURE_ENABLE_LOCAL_CONFIGURATION全部启用使用自定义规则集配置的选项。如果 SECURE_ENABLE_LOCAL_CONFIGURATION 设置为 false,则项目中的自定义规则集配置文件 .gitlab/sast-ruleset.toml 会被忽略,而 SAST_RULESET_GIT_REFERENCE 中的文件或默认配置优先。

安全扫描器配置#

SAST 分析器内部使用开源安全扫描器进行分析。我们为安全扫描器设置了推荐的配置,因此您无需担心调整它们。然而,在某些罕见情况下,我们的默认扫描器配置可能不符合您的要求。

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

分析器CLI 选项描述
极狐GitLab Advanced SAST --include-propagator-files WARNING: 此标志可能导致显著的性能下降。
此选项启用扫描连接源文件和汇文件的中间文件,而这些文件本身不包含源或汇。虽然在较小的存储库中进行全面分析时很有用,但在大型存储库中启用此功能会大大影响性能。
--multi-core 多核扫描默认启用,自动检测并利用基于容器信息的可用 CPU 核心。在私有化部署的 runner 上,核心数量最多限制为 4。您可以通过显式设置 --multi-core 为特定值来覆盖自动核心检测。多核执行需要比单核执行更多的内存。要禁用多核扫描,请设置环境变量 DISABLE_MULTI_CORE。请注意,超出可用核心或内存资源可能导致资源争用和性能不佳。
Semgrep --max-memory 设置运行规则时单个文件使用的最大系统内存,以 MB 为单位。
--max-target-bytes

要扫描的文件的最大尺寸。任何超过此尺寸的输入程序都会被忽略。设置为 0 或负值以禁用此过滤器。字节可以指定是否带有单位,例如:12.5kb1.5MB123。默认值为 1000000 字节。

**注意:** 您应该将此标志设置为默认值。此外,避免更改此标志以扫描缩小的 JavaScript,这可能不会很好地工作,DLLsJARs 或其他二进制文件,因为二进制文件不会被扫描。

--timeout 运行规则时单个文件的最大时间,以秒为单位。设置为 0 表示没有时间限制。超时值必须是整数,例如:1015。默认值为 5
SpotBugs -effort 设置分析努力级别。有效值是按精度和检测更多漏洞能力递增的顺序排列的minlessmoremax。默认值设置为 max,这可能需要更多的内存和时间来完成扫描,具体取决于项目的大小。如果您遇到内存或性能问题,可以将分析努力级别降低为较低的值。例如:-effort less

自定义 CI/CD 变量#

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

从分析中排除代码#

您可以标记单个行或块代码,以排除它们不会被分析漏洞。您应该通过漏洞管理管理所有漏洞,或在使用这种逐项注释方法之前调整扫描的文件路径,使用 SAST_EXCLUDED_PATHS

在使用基于 Semgrep 的分析器时,还可以使用以下选项:

  • 忽略代码行 - 在行尾添加 // nosemgrep: 注释(前缀根据开发语言而定)。

    Java 示例:

    java
    vuln_func(); // nosemgrep

    Python 示例:

    python
    vuln_func(); # nosemgrep
  • 为特定规则忽略代码行 - 在行尾添加 // nosemgrep: RULE_ID 注释(前缀根据开发语言而定)。

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

在离线环境中运行 SAST#

  • 级别:基础版、专业版、旗舰版
  • 提供:极狐GitLab 私有化部署

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

离线 SAST 的要求#

要在离线环境中使用 SAST,您需要:

  • 极狐GitLab Runner 和 dockerkubernetes executor
  • Docker 容器注册表中有本地可用的 SAST 分析器镜像副本。
  • 配置软件包的证书检查(可选)。

极狐GitLab Runner 有一个 默认的 pull_policyalways,意味着 runner 尝试从极狐GitLab 容器注册表拉取 Docker 镜像,即使本地副本可用。极狐GitLab Runner pull_policy 可以在离线环境中设置为 if-not-present,如果您更愿意只使用本地可用的 Docker 镜像。但是,我们建议在非离线环境中保持拉取策略设置为 always,因为这使您的 CI/CD 流水线能够使用更新的扫描器。

在您的 Docker 注册表中提供极狐GitLab SAST 分析器镜像#

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

plaintext
1registry.gitlab.com/security-products/gitlab-advanced-sast:1 2registry.gitlab.com/security-products/kubesec:5 3registry.gitlab.com/security-products/pmd-apex:5 4registry.gitlab.com/security-products/semgrep:5 5registry.gitlab.com/security-products/sobelow:5 6registry.gitlab.com/security-products/spotbugs:5

将 Docker 镜像导入到本地离线 Docker 注册表的过程取决于您的网络安全策略。请咨询您的 IT 人员以找到可以接受和批准的过程,以便导入或暂时访问外部资源。这些扫描器会定期更新新的定义,您可能可以自行进行偶尔的更新。

有关保存和传输 Docker 镜像作为文件的详细信息,请参阅 Docker 文档中的 docker savedocker loaddocker exportdocker import

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

自定义证书颁发机构的支持是在以下版本中引入的。

分析器版本
kubesecv2.1.0
pmd-apexv2.1.0
semgrepv0.0.1
sobelowv2.2.0
spotbugsv2.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#

默认情况下,SAST 分析器支持在 SELinux 上托管的极狐GitLab 实例。添加 before_script覆盖的 SAST 作业可能无法正常工作,因为托管在 SELinux 上的 runner 有受限的权限。