Help us learn about your current experience with the documentation. Take the survey.

GitLab Advanced SAST

Tier: Ultimate
Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

GitLab Advanced SAST 是一款静态应用安全测试（SAST）分析器，通过执行跨函数和跨文件的污点分析来发现漏洞。

GitLab Advanced SAST 是一个可选功能。启用后，GitLab Advanced SAST 分析器会使用预定义的规则集扫描所有支持语言的文件， Semgrep 分析器将不会扫描这些文件。

GitLab Advanced SAST 分析器发现的所有漏洞都会被报告，包括之前由基于 Semgrep 的分析器报告的漏洞。当 GitLab Advanced SAST 在与基于 Semgrep 的分析器相同的位置发现相同类型的漏洞时，会通过自动的转换流程去重发现的问题。

有关 GitLab Advanced SAST 的概述和工作原理，请参阅 GitLab Advanced SAST：加速漏洞解决。

有关产品演示，请查看 GitLab Advanced SAST 产品演示。

功能对比

功能	SAST	Advanced SAST
分析深度	检测复杂漏洞的能力有限；分析仅限于单个文件，并且在有限情况下仅限于单个函数。	使用跨文件、跨函数的污点分析检测复杂漏洞。
准确性	由于上下文有限，更容易产生误报结果。	通过使用跨文件、跨函数的污点分析专注于真正可利用的漏洞，减少误报结果。
修复指导	漏洞发现通过行号标识。	详细的代码流视图显示漏洞如何在程序中流动，便于更快修复。
与 GitLab Duo 漏洞解释和漏洞修复的兼容性	是。	是。
语言支持	更广泛。	更有限。

漏洞报告时机

GitLab Advanced SAST 使用跨文件、跨函数扫描结合污点分析来追踪用户输入在程序中的流动。通过跟踪用户输入的路径，分析器识别出潜在的不受信任数据可能以不安全方式影响应用程序执行的点，确保即使漏洞跨越多个函数和文件，也能检测到注入漏洞，如 SQL 注入和跨站脚本（XSS）。

为了减少噪音，GitLab Advanced SAST 仅在有可验证的流程将不受信任的用户输入源传递到敏感接收点时才报告基于污点的漏洞。其他产品可能会报告验证较少的漏洞。

GitLab Advanced SAST 经过优化，强调跨越信任边界的输入，例如源自 HTTP 请求的值。不受信任的输入源集合不包括命令行参数、环境变量或通常由程序操作用户提供的其他输入。

有关 GitLab Advanced SAST 检测的漏洞类型详情，请参阅 GitLab Advanced SAST CWE 覆盖范围。

从 Semgrep 迁移到 GitLab Advanced SAST

当您从 Semgrep 迁移到 GitLab Advanced SAST 时，自动转换流程会去重漏洞。此流程将先前检测到的 Semgrep 漏洞与相应的 GitLab Advanced SAST 发现关联起来，在找到匹配项时替换它们。

漏洞转换工作原理

在默认分支中启用 Advanced SAST 扫描后（参见启用 GitLab Advanced SAST 扫描），当扫描运行并检测到漏洞时，它会根据以下条件检查其中是否有任何漏洞应该替换现有的 Semgrep 漏洞。

去重条件

匹配标识符：
- GitLab Advanced SAST 漏洞的至少一个标识符（不包括 CWE 和 OWASP）必须与现有 Semgrep 漏洞的主要标识符匹配。
- 主要标识符是 SAST 报告中漏洞标识符数组中的第一个标识符。
- 例如，如果 GitLab Advanced SAST 漏洞包含 bandit.B506 标识符，而 Semgrep 漏洞的主要标识符也是 bandit.B506，则满足此条件。
匹配位置：
- 漏洞必须与代码中的相同位置关联。这是通过使用 SAST 报告中漏洞的以下字段之一确定的：
  - 跟踪字段（如果存在）
  - 位置字段（如果跟踪字段不存在）

漏洞变更

当满足条件时，现有的 Semgrep 漏洞会转换为 GitLab Advanced SAST 漏洞。此更新后的漏洞在漏洞报告中显示以下变更：

扫描器类型从 Semgrep 更新为 GitLab Advanced SAST。
添加 GitLab Advanced SAST 漏洞中存在的任何其他标识符到现有漏洞中。
漏洞的所有其他详细信息保持不变。

处理重复漏洞

在某些情况下，如果未满足去重条件，Semgrep 漏洞仍可能显示为重复。要在漏洞报告中解决此问题：

按 Advanced SAST 扫描器筛选漏洞并以 CSV 格式导出结果。
按 Semgrep 扫描器筛选漏洞。这些可能是未被去重的漏洞。
对于每个 Semgrep 漏洞，检查它在导出的 Advanced SAST 结果中是否有对应匹配项。
如果存在重复，适当解决 Semgrep 漏洞。

支持的语言

GitLab Advanced SAST 支持以下语言的跨函数和跨文件污点分析：

C#
Go
Java，包括 Java Server Pages (JSP)
JavaScript, TypeScript
PHP
Python
Ruby

PHP 已知问题

在分析 PHP 代码时，GitLab Advanced SAST 存在以下限制：

动态文件包含：本版本不支持使用变量作为文件路径的动态文件包含语句（include、include_once、require、require_once）。仅支持静态文件包含路径进行跨文件分析。参见 issue 527341。
大小写敏感性：PHP 函数名、类名和方法名的大小写不敏感特性在跨文件分析中未完全支持。参见 issue 526528。

配置

启用 GitLab Advanced SAST 分析器，通过执行跨函数和跨文件的污点分析来发现应用程序中的漏洞。然后，您可以使用 CI/CD 变量调整其行为。

可用的 CI/CD 变量

可以使用以下 CI/CD 变量配置 GitLab Advanced SAST。

CI/CD 变量	默认值	描述
`GITLAB_ADVANCED_SAST_ENABLED`	`false`	设置为 `true` 以启用 GitLab Advanced SAST 扫描，或设置为 `false` 以禁用。
`FF_GLAS_ENABLE_PHP_SUPPORT`	`true`	设置为 `true` 以分析 PHP 文件，或设置为 `false` 以禁用。

要求

与其他 GitLab SAST 分析器一样，GitLab Advanced SAST 分析器需要运行器和 CI/CD 管道；详细信息请参见 SAST 要求。

在 GitLab 自托管版中，您还必须使用支持 GitLab Advanced SAST 的 GitLab 版本：

如果可能，您应该使用 GitLab 17.4 或更高版本。GitLab 17.4 包含新的代码流视图、漏洞去重以及对 SAST CI/CD 模板的进一步更新。
SAST CI/CD 模板在以下版本中更新以包含 GitLab Advanced SAST：
- 稳定模板在 GitLab 17.3 或更高版本中包含 GitLab Advanced SAST。
- 最新模板在 GitLab 17.2 或更高版本中包含 GitLab Advanced SAST。不要在单个项目中混合使用最新和稳定模板。
GitLab Advanced SAST 最低要求版本为 17.1。

启用 GitLab Advanced SAST 扫描

GitLab Advanced SAST 包含在标准的 GitLab SAST CI/CD 模板中，但尚未默认启用。要启用它，请将 CI/CD 变量 GITLAB_ADVANCED_SAST_ENABLED 设置为 true。您可以根据管理 CI/CD 配置的方式以不同方式设置此变量。

手动编辑 CI/CD 管道定义

如果您已在项目中启用了 GitLab SAST 扫描，请添加 CI/CD 变量以启用 GitLab Advanced SAST。

此最小 YAML 文件包含稳定 SAST 模板并启用 GitLab Advanced SAST：

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

variables:
  GITLAB_ADVANCED_SAST_ENABLED: 'true'

在扫描执行策略中强制执行

要在扫描执行策略中启用 GitLab Advanced SAST，请更新策略的扫描操作，将 CI/CD 变量 GITLAB_ADVANCED_SAST_ENABLED 设置为 true。您可以通过以下方式设置此变量：

在策略编辑器的菜单中选择它。
将其添加到扫描操作中的 variables 对象。

使用管道编辑器

要使用管道编辑器启用 GitLab Advanced SAST：

在您的项目中，选择 Build > Pipeline editor。
如果不存在 .gitlab-ci.yml 文件，请选择 Configure pipeline，然后删除示例内容。
更新 CI/CD 配置以：
- 如果尚未包含，请包含一个 GitLab 管理的 SAST CI/CD 模板。
  - 在 GitLab 17.3 或更高版本中，您应该使用稳定模板 Jobs/SAST.gitlab-ci.yml。
  - 在 GitLab 17.2 中，GitLab Advanced SAST 仅在最新模板 Jobs/SAST.latest.gitlab-ci.yml 中可用。不要在单个项目中混合使用最新和稳定模板。
  - 在 GitLab 17.1 中，您必须手动将 GitLab Advanced SAST 作业的内容复制到您的 CI/CD 管道定义中。
- 将 CI/CD 变量 GITLAB_ADVANCED_SAST_ENABLED 设置为 true。
参见最小 YAML 示例。
选择 Validate 选项卡，然后选择 Validate pipeline。

Simulation completed successfully 消息确认文件有效。
选择 Edit 选项卡。
完成字段。不要为 Branch 字段使用默认分支。
选择 Start a new merge request with these changes 复选框，然后选择 Commit changes。
根据您的标准工作流程完成字段，然后选择 Create merge request。
根据您的标准工作流程审查和编辑合并请求，然后选择 Merge。

现在管道中包含 GitLab Advanced SAST 作业。

禁用 GitLab Advanced SAST 扫描

Advanced SAST 扫描默认未启用，但它可能在组级别或其他影响多个项目的方式中被启用。

要在项目中明确禁用 Advanced SAST 扫描，请将 CI/CD 变量 GITLAB_ADVANCED_SAST_ENABLED 设置为 false。您可以在任何可以配置 CI/CD 变量的地方设置此变量，包括您可以启用 Advanced SAST 扫描的相同方式。

漏洞代码流

对于特定类型的漏洞，GitLab Advanced SAST 提供代码流信息。漏洞的代码流是从用户输入（源）到易受攻击的代码行（接收点）的数据路径，经过所有赋值、操作和净化。此信息帮助您理解和评估漏洞的上下文、影响和风险。代码流信息适用于通过从源到接收点追踪输入检测到的漏洞，包括：

SQL 注入
命令注入
跨站脚本（XSS）
路径遍历

代码流信息显示在代码流选项卡中，包括：

从源到接收点的步骤。
相关文件，包括代码片段。

自定义 GitLab Advanced SAST

您可以禁用 GitLab Advanced SAST 规则或编辑其元数据，就像其他分析器一样。详细信息，请参阅自定义规则集。

请求 GitLab Advanced SAST 中 LGPL 许可组件的源代码

要请求有关 GitLab Advanced SAST 中 LGPL 许可组件源代码的信息，联系 GitLab 支持。

为确保快速响应，请在请求中包含 GitLab Advanced SAST 分析器版本。

由于此功能仅在 Ultimate 版本中可用，您必须与具有该级别支持权限的组织关联。

反馈

欢迎在专门的 issue 466322 中添加您的反馈。

故障排除

在使用 GitLab Advanced SAST 时，您可能会遇到以下问题。

Advanced SAST 扫描缓慢或超时

由于 Advanced SAST 详细扫描您的程序，有时扫描可能需要很长时间才能完成，特别是对于大型仓库。如果您遇到性能问题，请考虑遵循这里的建议。

通过排除文件减少扫描时间

由于每个文件都会根据所有适用的规则进行分析，您可以减少扫描的文件数量以缩短扫描时间。为此，使用 SAST_EXCLUDED_PATHS 变量排除不需要扫描的文件夹。有效的排除因情况而异，可能包括：

数据库迁移
单元测试
依赖目录，如 node_modules/
构建目录

使用多核扫描优化扫描

多核扫描在 Advanced SAST（分析器版本 v1.1.10 及更高版本）中默认启用。您可以增加运行器大小以提供更多资源用于扫描。对于自托管运行器，您可能需要在安全扫描器配置中自定义 --multi-core 标志。

何时寻求支持

如果您遵循了这些优化步骤，但 Advanced SAST 扫描仍然运行时间超过预期，请联系 GitLab 支持获取进一步帮助，并提供以下信息：

识别 GitLab Advanced SAST 分析器版本

要识别 GitLab Advanced SAST 分析器版本：

在左侧边栏，选择 Search or go to 并找到您的项目。
选择 Build > Jobs。
找到 gitlab-advanced-sast 作业。
在作业的输出中，搜索字符串 GitLab GitLab Advanced SAST analyzer。

您应该在该字符串的行尾找到版本号。例如：

[INFO] [GitLab Advanced SAST] [2025-01-24T15:51:03Z] ▶ GitLab GitLab Advanced SAST analyzer v1.1.1

在此示例中，版本为 1.1.1。

生成性能调试工件

要生成 trace.ctf 工件，请将以下内容添加到您的 .gitlab-ci.yml 中。

将 RUNNER_SCRIPT_TIMEOUT 设置为比 timeout 至少短 10 分钟，以确保工件有时间上传。

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

variables:
  GITLAB_ADVANCED_SAST_ENABLED: 'true'
  MEMTRACE: 'trace.ctf'
  DISABLE_MULTI_CORE: true # 收集 memtrace 时禁用多核

gitlab-advanced-sast:
  artifacts:
    paths:
      - '**/trace.ctf'  # 收集此作业生成的所有 trace.ctf 文件
    expire_in: 1 week   # 设置工件保留期
    when: always        # 即使作业失败也确保导出工件
  variables:
    RUNNER_SCRIPT_TIMEOUT: 50m
  timeout: 1h