License 扫描

824 字约 3 分钟

License 扫描插件识别依赖组件的许可证表达式（License Expression），并支持按风险等级设置门禁。默认检查 PR 新增 License 风险，设置 scanMode: full 可检查当前 Commit 的全部 License 风险。

在 CNB 中使用

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

.cnb.yml
main:
  push:
    - stages:
        - name: License 全量扫描
          image: cnbcool/sca-license:latest
          timeout: 15m
          settings:
            scanMode: full
            failOnSeverity: high
            publish: true

以上配置检查当前 Commit 的全部 License 风险，发现 High 风险时判定检查失败。 failOnSeverity 为可选参数，未配置时只执行扫描，不执行门禁。

以下为 PR 增量扫描示例，只做门禁，不上传报告附件：

.cnb.yml
main:
  pull_request.target:
    - stages:
        - name: License 扫描
          image: cnbcool/sca-license:latest
          timeout: 15m
          settings:
            failOnSeverity: high

以上配置会在 PR 新增 High License 风险时使检查失败。

pull_request 与 pull_request.target 的区别

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

参数说明

插件参数通过 settings 传递：

参数	说明	默认
`scanMode`	扫描模式：`diff` 为 PR 增量，`full` 为当前 `CNB_COMMIT` 全量	`diff`
`failOnSeverity`	触发门禁的最低 License 风险等级：`low`、`medium`、`high`；未配置时不执行门禁	无
`publish`	是否生成并上传报告附件；上传需要在可信事件中执行	`false`

不需要因 License 风险阻断流水线时，省略 failOnSeverity，插件会在日志中列出扫描范围内的全部风险。通用行为见扫描模式和门禁说明。

增量规则

组件版本变化但 License Expression 不变时，不会重复阻断；
新组件或新的 License Expression 会带来新风险；
目标分支已存在的同一 License 风险不会在当前 PR 重复阻断。

输出说明

以下为 failOnSeverity: high 的增量扫描日志示例，只输出 High License 风险：

service/pom.xml: HIGH GPL-3.0-only
  component: example:library@2.0.0
  license: GPL-3.0-only
  message: component uses GPL-3.0-only

SCA gate failed: 1 new risk findings, 1 matched gate

publish: true 时还会生成 XLSX 报告并作为 Commit 附件上传，文件名为 security-license-<scanMode>-<commit>.xlsx。报告包含 License、标准化表达式、风险等级、组件名称与版本、PURL、Path 以及权限/条件/限制等信息。文件名规则和下载位置见报告附件。

Commit 元数据

插件把风险数量和门禁结果写入本次扫描的目标 Commit 的 Annotation：

sca.license.full.reporter=https://...
sca.license.full.gate=gate
sca.license.full.high.count=2
sca.license.full.medium.count=1
sca.license.full.low.count=0

字段含义见Commit 元数据。

退出码

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

下一步

插件总览 —— 三个插件的整体配置与门禁说明
开源组件漏洞扫描 —— 漏洞门禁与增量规则
SBOM 生成 —— 组件清单与标准格式