{{< details >}}

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

{{< /details >}}

以下故障排除场景是从客户支持案例中收集的。如果您遇到的问题未在此处解决，或者此处的信息未能解决您的问题，请参阅 极狐GitLab 支持 页面以获取帮助。

调试级别日志记录

调试级别日志记录可以在故障排除时提供帮助。有关详细信息，请参阅 调试级别日志记录。

CI/CD 模板中的更改

极狐GitLab 管理的 SAST CI/CD 模板 控制哪些 分析器 作业运行以及它们如何配置。在使用模板时，您可能会遇到作业失败或其他流水线错误。例如，您可能会：

  • 在查看受影响的流水线时看到类似 '你的作业' 需要 'spotbugs-sast' 作业，但 'spotbugs-sast' 不在任何先前阶段 的错误消息。
  • 体验到其他类型的意外问题与您的 CI/CD 流水线配置相关。

如果您遇到作业失败或看到与 SAST 相关的 yaml invalid 流水线状态，可以暂时恢复到旧版本的模板，以便在调查问题时保持流水线正常运行。要使用旧版本的模板，请将现有的 include 语句在您的 CI/CD YAML 文件中更改为引用特定的模板版本，例如 v15.3.3-ee：

include:
  remote: 'https://jihulab.com/gitlab-cn/gitlab/-/raw/v15.3.3-ee/lib/gitlab/ci/templates/Jobs/SAST.gitlab-ci.yml'

如果您的极狐GitLab 实例具有有限的网络连接，您也可以下载该文件并在其他地方托管。

您应仅临时使用此解决方案，并尽快返回 标准模板。

特定分析器作业中的错误

极狐GitLab SAST 分析器 作为容器镜像发布。如果您看到一个新的错误，而该错误似乎与 极狐GitLab 管理的 SAST CI/CD 模板 或您自己项目中的更改无关，您可以尝试 将受影响的分析器固定到特定的旧版本。

每个 分析器项目 都有一个 CHANGELOG.md 文件，列出了每个可用版本中所做的更改。

作业日志消息

SAST 作业的日志可能包含有助于确定根本原因的错误消息。以下是一些错误消息和推荐的操作。

可执行文件格式 

exec /bin/sh: exec format error` message in job log

极狐GitLab SAST 分析器 仅支持 在 amd64 CPU 架构上运行。此消息表明该作业正在不同的架构上运行，例如 arm。

Docker 错误 

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

有关此信息，请参阅 一般应用安全故障排除部分。

仅配置 

sast is used for configuration only, and its script should not be executed

有关此信息，请参阅 极狐GitLab Secure 故障排除部分。

SAST 作业意外运行

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

SpotBugs 错误

以下是最常见的 SpotBugs 错误及推荐的操作。

UTF-8 不可映射字符错误

当 UTF-8 编码未在 SpotBugs 构建中启用且源代码中有 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-sast 作业在构建步骤失败并显示 “项目无法构建” 消息，很可能是因为：

  • 您的项目要求 SpotBugs 使用其默认工具之外的工具进行构建。
  • 您的构建需要分析器的自动构建过程无法适应的自定义配置或额外依赖项。

基于 SpotBugs 的分析器仅用于扫描 Groovy 代码，但在其他情况下可能会触发，例如 当所有 SAST 作业意外运行时。

解决方案取决于您是否需要扫描 Groovy 代码：

  • 如果您没有任何 Groovy 代码，或者不需要扫描它，您应该 禁用 SpotBugs 分析器。
  • 如果您确实需要扫描 Groovy 代码，您应该使用 预编译。 预编译通过扫描您已在流水线中构建的产物来避免这些失败，而不是尝试在 spotbugs-sast 作业中编译它。

Java 内存不足错误

当 spotbugs-sast 作业运行时，您可能会收到一个错误，指出 java.lang.OutOfMemoryError。此问题发生在 Java 在扫描期间耗尽内存时。

要尝试解决此问题，您可以：

  • 选择较低的 努力级别。
  • 设置 CI/CD 变量 JAVA_OPTS 以替换默认的 -XX:MaxRAMPercentage=80，例如 -XX:MaxRAMPercentage=90。
  • 在您的 spotbugs-sast 作业中 标记一个更大的 runner。

分析异常

如果您的作业日志包含类似 “Exception analyzing … using detector …” 的消息后跟 Java 堆栈跟踪，这 不是 SAST 流水线的失败。

消息的第一个 “…” 部分是正在分析的类 - 如果它不是您项目的一部分，您可以忽略消息和随后的堆栈跟踪。

Flawfinder 编码错误

当 Flawfinder 遇到无效的 UTF-8 字符时会发生此错误。

您可以在每个 .gitlab-ci.yml 文件中配置 before_script 部分，或使用 流水线执行策略 来安装编码器并运行转换命令。例如，您可以向从安全扫描器模板生成的 flawfinder-sast 作业添加一个 before_script 部分，以转换所有具有 .cpp 扩展名的文件。

示例流水线执行策略 YAML 

---
pipeline_execution_policy:
- name: SAST
  description: 'Run SAST on C++ application'
  enabled: true
  pipeline_config_strategy: inject_ci
  content:
    include:
    - project: my-group/compliance-project
      file: flawfinder.yml
      ref: main

flawfinder.yml:

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

flawfinder-sast:
  before_script:
    - pip install cvt2utf
    - cvt2utf convert "$PWD" -i cpp

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

如果 Semgrep 运行缓慢，报告了太多误报或漏报，崩溃，失败或出现其他问题，请参阅 Semgrep 文档以了解极狐GitLab SAST 故障排查。

高级 SAST 扫描缓慢或超时

由于 高级 SAST 详细扫描您的程序，扫描有时可能需要较长时间才能完成，特别是对于大型存储库。如果您遇到性能问题，请考虑遵循此处的建议。

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

由于每个文件都根据所有适用的规则进行分析，您可以减少扫描的文件数量以缩短扫描时间。为此，请使用 SAST_EXCLUDED_PATHS 变量排除不需要扫描的文件夹。

使用多核扫描优化扫描

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

何时寻求支持

如果您已遵循这些优化步骤，但您的高级 SAST 扫描仍然运行时间超出预期，请联系极狐GitLab 支持以获得进一步协助，并提供以下信息：

生成性能调试产物

要生成 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 # Disable multi core when collecting memtrace

gitlab-advanced-sast:
  artifacts:
    paths:
      - '**/trace.ctf'  # Collects all trace.ctf files generated by this job
    expire_in: 1 week   # Sets retention for artifacts
    when: always        # Ensures artifact export even if the job fails
  variables:
    RUNNER_SCRIPT_TIMEOUT: 50m
  timeout: 1h