CycloneDX 文件的许可证扫描

为了检测正在使用的许可证，许可证合规性依赖于运行 依赖扫描作业， 并分析这些作业生成的 CycloneDX 软件物料清单 (SBOM)。 此扫描方法能够解析和识别超过 600 种不同类型的许可证，如 SPDX 列表 中所定义。 只要第三方扫描器为支持的语言生成 CycloneDX 报告产物并遵循 极狐GitLab 的 CycloneDX 属性分类法，就可以使用它们来生成依赖项列表。 提供对其他许可证的支持在 史诗 10861 中进行跟踪。

配置#

要启用 CycloneDX 文件的许可证扫描：

• 使用依赖扫描模板
  • 开启依赖扫描并确保满足其先决条件。
  • 在私有化部署的 极狐GitLab 上，您可以在 极狐GitLab 实例的 管理员 区域中选择要同步的软件包仓库元数据。为了使此数据同步正常工作，您必须允许从 极狐GitLab 实例到域 storage.googleapis.com 的出站网络流量。如果您的网络连接受限或不存在，请参阅在离线环境中运行的文档部分以获得进一步指导。
• 或者，为适用的软件包仓库使用 CI/CD 组件。

支持的语言和包管理器#

许可证扫描支持以下语言和包管理器：

支持的文件和版本与依赖扫描所支持的一致。

数据源#

受支持软件包的许可证信息从以下来源获取。极狐GitLab 会对原始数据进行额外处理，包括将变体映射到规范的许可证名称。

许可证表达式#

CycloneDX 文件的许可证扫描不支持复合许可证。 添加此功能在议题 336878 中进行跟踪。

基于检测到的许可证阻止合并请求#

用户可以通过配置许可证审批策略，要求对基于检测到的许可证的合并请求进行审批。

在离线环境中运行#

对于在通过互联网访问外部资源受限、受限或间歇性的环境中运行的实例，需要一些调整才能成功扫描 CycloneDX 报告以获取许可证信息。有关更多信息，请参阅离线快速入门指南。

使用 CycloneDX 报告作为许可证信息来源#

许可证扫描在可用时使用 CycloneDX JSON SBOM 的许可证字段。如果许可证信息不可用，将使用从外部许可证数据库导入的许可证信息（当前行为）。 许可证信息可以使用有效的 SPDX 标识符或许可证名称来提供。但是，不支持使用 SPDX 许可证表达式提供许可证。 有关许可证字段格式的更多信息，请参见 CycloneDX 规范。

提供许可证字段的兼容 CycloneDX SBOM 生成器可以在 CycloneDX 工具中心 找到。

目前仅支持提供 SPDX 标识符的许可证。将此功能扩展到 SPDX 许可证之外在议题 505677 中进行跟踪。

配置许可证信息来源#

当两个来源都可用时，选择要使用的许可证信息来源。

要为项目配置首选许可证信息来源：

1. 在顶部栏中，选择 搜索或跳转到 并找到您的项目。
2. 在左侧边栏中，选择 安全 > 安全配置。
3. 在 许可证信息来源 部分，选择以下任一选项：
   • SBOM（默认）- 使用来自 CycloneDX 报告的许可证信息。
     • 扫描器从项目中位于 /gl-sbom-*.cdx.json 的报告读取许可证信息。
     • 要覆盖许可证，请直接更新此文件中的许可证数据。
   • PMDB - 使用来自外部许可证数据库的许可证信息。

故障排除#

CycloneDX 文件未被扫描且似乎没有提供任何结果#

确保 CycloneDX 文件符合 CycloneDX JSON 规范。该规范不允许重复条目。包含多个 SBOM 文件的项目应将每个 SBOM 文件作为单独的 CI 报告产物上报，或者如果在 CI 流水线中合并了 SBOM，则应确保删除了重复项。

您可以按如下方式根据 CycloneDX JSON 规范 验证 CycloneDX SBOM 文件：

shell
$ docker run -it --rm -v "$PWD:/my-cyclonedx-sboms" -w /my-cyclonedx-sboms cyclonedx/cyclonedx-cli:latest cyclonedx validate --input-version v1_4 --input-file gl-sbom-all.cdx.json

正在验证 JSON BOM...
BOM 验证成功。

如果 JSON BOM 验证失败，例如，由于存在重复组件：

shell
验证失败：在以下索引对中发现重复项：“(A, B), (C, D)”
#/properties/components/uniqueItems

此问题可以通过更新 CI 模板以使用 jq 从 gl-sbom-*.cdx.json 报告中删除重复组件来解决，方法是覆盖产生重复组件的作业定义。例如，以下命令从 gemnasium-dependency_scanning 作业生成的 gl-sbom-gem-bundler.cdx.json 报告文件中删除重复组件：

yaml
1include:
2  - template: Jobs/Dependency-Scanning.gitlab-ci.yml
3
4gemnasium-dependency_scanning:
5  after_script:
6    - apk update && apk add jq
7    - jq '.components |= unique' gl-sbom-gem-bundler.cdx.json > tmp.json && mv tmp.json gl-sbom-gem-bundler.cdx.json

删除未使用的许可证数据#

许可证扫描的更改（在极狐GitLab 15.9 中发布）要求实例上有大量额外的磁盘空间可用。此问题已在极狐GitLab 16.3 中通过减少包元数据表的磁盘占用史诗解决。但如果您的实例在极狐GitLab 15.9 到 16.3 之间运行了许可证扫描，您可能希望删除不需要的数据。

要删除不需要的数据：

1. 检查 package_metadata_synchronization 功能标志当前是否启用或曾经启用，如果是，则禁用它。使用 Rails 控制台执行以下命令。

   ruby
   Feature.enabled?(:package_metadata_synchronization) && Feature.disable(:package_metadata_synchronization)

2. 检查数据库中是否存在已弃用的数据：

   ruby
   PackageMetadata::PackageVersionLicense.count
   PackageMetadata::PackageVersion.count

3. 如果数据库中存在已弃用的数据，请按顺序运行以下命令将其删除：

   ruby
   ActiveRecord::Base.connection.execute('SET statement_timeout TO 0')
   PackageMetadata::PackageVersionLicense.delete_all
   PackageMetadata::PackageVersion.delete_all

漏洞扫描对 CycloneDX SBOM 没有产生任何结果#

如果您的 CycloneDX 文件被扫描以获取许可证，但漏洞扫描没有产生任何结果，请参阅 漏洞扫描对自定义或合并的 CycloneDX SBOM 没有产生任何结果。

依赖项许可证未知#

开源许可证信息存储在数据库中，用于解析项目依赖项的许可证。如果许可证信息不存在或该数据尚不可用于数据库，则依赖项的许可证可能显示为 unknown。

依赖项许可证的查找在流水线完成时进行，因此如果当时该数据不可用，则会记录一个 unknown 许可证。此许可证会显示，直到执行后续流水线，此时会再次进行许可证查找。如果查找确认依赖项的许可证已更改，则此时会显示新的许可证。