插件总览

1140 字约 4 分钟

CNB 提供三个 SCA 流水线插件，用于检查依赖组件的漏洞、License 风险，以及生成组件清单（SBOM）。在 .cnb.yml 中配置插件，可执行 PR 增量扫描或 Commit 全量扫描，并按需启用门禁和报告附件。

平台内置的仓库级扫描配置见代码安全扫描。

插件列表

插件	镜像	说明
开源组件漏洞扫描	`cnbcool/sca-vulnerability:latest`	检查依赖漏洞，可配置质量门禁
License 扫描	`cnbcool/sca-license:latest`	检查 License 风险，可配置质量门禁
SBOM 生成	`cnbcool/sca-sbom:latest`	输出组件清单或组件变化

在 CNB 中使用

在业务仓库根目录的 .cnb.yml 中添加以下配置，在 push 时执行全量扫描并上传报告附件：

.cnb.yml
main:
  push:
    - stages:
        - name: 开源组件漏洞扫描
          image: cnbcool/sca-vulnerability:latest
          timeout: 30m
          settings:
            scanMode: full
            failOnSeverity: high
            publish: true

        - name: License 扫描
          image: cnbcool/sca-license:latest
          timeout: 30m
          settings:
            scanMode: full
            failOnSeverity: high
            publish: true

        - name: 生成 SBOM
          image: cnbcool/sca-sbom:latest
          timeout: 30m
          settings:
            scanMode: full
            publish: true

PR 增量门禁默认不上传附件：

.cnb.yml
main:
  pull_request.target:
    - stages:
        - name: 开源组件漏洞扫描
          image: cnbcool/sca-vulnerability:latest
          timeout: 30m
          settings:
            failOnSeverity: high

        - name: License 扫描
          image: cnbcool/sca-license:latest
          timeout: 30m
          settings:
            failOnSeverity: high

scanMode 默认为 diff、publish 默认为 false，因此上面的配置只做增量门禁，不上传附件。

任务超时通过 timeout 控制。任务失败是否影响后续流程和最终结果，通过 allowFailure 控制。

pull_request 与 pull_request.target 的区别

详细区别请参考代码版本选择。

扫描模式

三个插件都支持 scanMode，取值 diff（默认）或 full：

模式	取值	扫描对象	门禁作用范围
增量（默认）	`diff`	PR 新增风险，或新增及版本变化的组件	本次 PR 新增的风险
全量	`full`	当前 `CNB_COMMIT` 的全部依赖组件	当前 Commit 的全部风险

增量 SBOM 仅包含新增及版本变化的组件，需要完整组件清单时使用 full。

门禁说明

漏洞和 License 插件通过 failOnSeverity 设置触发门禁的最低风险等级。例如 failOnSeverity: high 会拦截 High 和 Critical 漏洞，以及 High License 风险。 SBOM 插件不执行门禁。

配置 failOnSeverity：命中阈值时检查失败，日志逐条展示达到阈值的风险；低于阈值的风险仍计入扫描结果。
未配置 failOnSeverity：不执行门禁，日志逐条展示扫描范围内的全部风险。

扫描完成后，插件先上传附件（publish: true 时）并写入 Commit 元数据，再输出门禁结果。门禁命中不会阻止报告发布；退出状态见退出码。

报告附件

publish 默认为 false，不生成、不上传报告附件；设为 true 时生成并上传。附件可在 Commit 详情页下载：增量扫描关联到 PR 的最新 Commit，全量扫描关联到当前 CNB_COMMIT。

插件	报告文件名
`sca-vulnerability`	`security-vulnerability-<scanMode>-<commit>.xlsx`
`sca-license`	`security-license-<scanMode>-<commit>.xlsx`
`sca-sbom`	`security-sbom-<scanMode>-<commit>.<ext>`

文件名中的 <scanMode> 为 diff 或 full，<commit> 为目标 Commit 的完整 SHA。 SBOM 的后缀由 format 决定，见 SBOM 生成。

Commit 元数据

插件把结果摘要写入 Commit Annotation，与报告附件关联到同一个 Commit：

sca.<capability>.<scanMode>.<field>=<value>

能力（`capability`）	固定计数 Key
`vulnerability`	`critical.count`、`high.count`、`medium.count`、`low.count`
`license`	`high.count`、`medium.count`、`low.count`
`sbom`	`total.count`（组件总数，无风险等级）

scanMode 对应 .cnb.yml 中的同名配置项，取值为 diff（增量）或 full（全量）。

字段（`field`）	说明
`reporter`	扫描报告下载地址
`gate`	门禁结果：`pass` 未配置门禁或未命中，`gate` 命中门禁
`<level>.count`	风险等级计数，取值见上表
`total.count`	SBOM 插件本次扫描的组件数量

退出码

退出码	说明
`0`	扫描成功，且未命中门禁或未配置门禁
`1`	风险命中门禁（仅漏洞、License 插件）
`2`	配置错误、扫描失败；`publish: true` 时附件或元数据发布失败

下一步

开源组件漏洞扫描 —— 插件参数、漏洞门禁与扫描模式
License 扫描 —— 插件参数与 License 风险门禁
SBOM 生成 —— 组件清单与标准格式