SBOM软件物料清单生成指南，基于极狐GitLab的自动化产出
SBOM软件物料清单生成指南，基于极狐GitLab的自动化产出
SBOM（软件物料清单）是一份记录软件所有组件、依赖及其来源与版本的结构化清单，是软件供应链安全治理、漏洞响应与交付合规的基础数据。
客户要求你交付一份 SBOM，或者采购方的安全问卷里白纸黑字写着"请提供软件物料清单"，你打开仓库翻了一眼：三百多个依赖，横跨五门语言，锁文件格式各不相同。手写？不现实。这活儿本来就该由流水线自动干完——极狐GitLab 的依赖扫描已经把它做成了开箱即用的能力，一条 include 就能让每条流水线产出符合 CycloneDX 标准的 SBOM。
一、SBOM 为什么成了交付硬指标
SBOM 的价值不在"生成"这个动作，而在它成为下游一切治理工作的数据底座：漏洞比对、许可证审查、恶意软件包识别、交付物存档，全都建立在一份准确的组件清单之上。没有 SBOM，上面这些动作都只能靠人肉翻依赖表。
极狐GitLab 对此的官方定位很明确：依赖扫描的长期方向就是 SBOM。官方文档中写道，"将依赖扫描分析器在您的流水线中生成的 CycloneDX SBOM 产物与 GitLab 安全公告数据库进行比对扫描。这是新项目的推荐方法，也是极狐GitLab 中依赖扫描的长期方向。"
目前流水线里有四种依赖扫描方法，各有分工：
方法 | 状态 | 触发方式 | 适用场景 |
|---|---|---|---|
使用 SBOM 的依赖扫描 | 正式发布 | 流水线 | 新项目、以 SBOM 为先的工作流 |
持续依赖扫描 | 正式发布 | 安全公告数据库更新 | 无需重跑流水线即可捕获新披露漏洞 |
使用 Gemnasium 的依赖扫描 | 已弃用（17.9 起，计划 20.0 移除） | 流水线 | 等待迁移的现有项目 |
分析依赖的行为（Libbehave） | 实验 | 流水线 | 检测恶意软件包行为 |
一句话结论：新项目直接上 SBOM 方法，老项目尽早把 Gemnasium 迁移掉——按官方迁移指南的节奏，20.0 版本就要移除了。
二、一条 include 产出标准 SBOM
在 .gitlab-ci.yml 中加入官方 v2 模板，是开启 SBOM 自动产出的最小改动：
include:
- template: Jobs/Dependency-Scanning.v2.gitlab-ci.yml运行后流水线会产出两类产物：每个检测到的锁文件对应一份 CycloneDX SBOM，命名规则为 gl-sbom-<包类型>-<包管理器>.cdx.json，生成在锁文件同目录；外加一份汇总的依赖扫描报告 gl-dependency-scanning-report.json。SBOM 通过 cyclonedx 报告类型上传，作为作业产物保留。
几个写配置前值得知道的默认行为，全部出自官方 SBOM 依赖扫描文档：
模板默认在合并请求流水线中运行（
AST_ENABLE_MR_PIPELINES默认为"true"），不使用合并请求流水线的项目应显式设为"false"，避免流水线翻倍；扫描范围为根目录及其直接子目录（
DS_MAX_DEPTH默认 2），开发与测试依赖默认包含（DS_INCLUDE_DEV_DEPENDENCIES默认"true"）；找不到受支持的锁文件时作业照样成功并输出警告，可用
DS_SKIP_IF_NO_SUPPORTED_FILES: "true"改为直接跳过；SBOM API 使用默认
CI_JOB_TOKEN认证，手动覆盖该变量会直接吃 403 Forbidden。
支持的语言覆盖面足够主流团队用：Java（Maven/Gradle）、Go、Python（pip/poetry/uv/pipenv）、JavaScript（npm/pnpm/yarn/Bun）、Ruby、PHP、Rust、C#（NuGet）等均在列，完整对照表见官方文档。
三、SBOM 生成之后，流水线之外还在持续工作
SBOM 产出的真正意义在于：它会被注册进极狐GitLab，成为持续漏洞扫描（CVS）的数据源。官方文档的表述是：持续依赖扫描"每当 GitLab 安全公告数据库更新时，持续重新扫描默认分支最近一次成功流水线中的 SBOM 组件，因此新披露的漏洞无需重新运行流水线即可显现。"
维度 | 流水线内扫描 | 持续漏洞扫描（CVS） |
|---|---|---|
执行方式 | CI/CD 流水线作业 | 后台作业（Sidekiq） |
触发时机 | 代码提交/合并请求 | 安全公告发布后自动 |
产物 | CycloneDX SBOM + 扫描报告 | 不生成报告产物，直接更新漏洞报告 |
公告范围 | 全量比对 | 仅考虑过去 14 天内发布的公告 |
两者的关系不是替代，而是接力：流水线负责生成最新清单，CVS 负责在不占流水线资源的前提下盯梢新公告。前提只有一条——默认分支上至少跑过一次依赖扫描，SBOM 注册过组件即可。
四、私有化部署的两个前置检查
私有化部署的团队在开启前有两件事必须核对，否则会出现"扫描跑完但漏洞识别不了"的尴尬：
软件包元数据同步：所有待扫描 PURL 类型的软件包元数据必须在实例中同步，路径为管理区域 > 设置 > 安全与合规 > 许可证合规，选择要同步的软件包仓库元数据，且需允许实例到 storage.googleapis.com 的出站流量，离线实例另有专门说明；
Runner 执行器：需带 docker 或 kubernetes 执行器的 Runner，扫描作业跑在容器里。
另外注意容量层面的边界：SBOM 扫描 API 有"每个项目每条流水线每小时 50 次"的软性限流，超额扫描会被降级处理，monorepo 等高流量项目可能感知到扫描时长变长，此限流不可配置（详见安全与合规设置文档）。
FAQ
Q1：SBOM 产物是什么格式，能直接给到外部交付吗？
产物为 CycloneDX 格式的 JSON 文件（gl-sbom-*.cdx.json），符合 CycloneDX 规范 1.4、1.5 或 1.6 版本。第三方生成的 SBOM 只要符合相同规范及极狐GitLab 的 CycloneDX 属性分类法，也可以导入使用。
Q2：流水线跑完后没有生成 SBOM 文件，最常见的原因是什么？
项目根目录及其直接子目录（默认深度 2）内没有受支持的锁文件。检查锁文件是否提交、语言是否在支持列表内；若确实无需扫描，可设置 DS_SKIP_IF_NO_SUPPORTED_FILES: "true" 让作业显式跳过。
Q3：旧项目用 Gemnasium 的依赖扫描，需要立刻迁移吗？
建议尽快。该分析器在极狐GitLab 17.9 中已弃用，计划在 20.0 中移除，官方提供了迁移指南。新项目则无需犹豫，直接使用 Dependency-Scanning.v2.gitlab-ci.yml 模板。
结语
SBOM 不是又一个新概念，而是软件供应链治理的"资产负债表"。与其在交付前突击手拼一份清单，不如让流水线每次构建顺手产出来——一条 include 的成本，换漏洞响应、许可证审查、交付合规三条线的自动化底座。
想在自己的项目里跑通第一条 SBOM 流水线？免费试用极狐GitLab，或前往文档中心查看依赖扫描完整配置说明；拿不准私有化部署方案的，可以预约一次产品演示。
