---
url: /zh/security/sca-sbom.md
description: >
  SBOM 生成插件（cnbcool/sca-sbom）用法，比较 PR Base/Head 依赖组件生成变化清单， 支持 JSON
  Delta、SPDX、CycloneDX 和 SWID。
---
SBOM 生成插件比较 Pull Request 的 Base 和 Head 依赖组件，输出组件变化清单（Delta）。
它只生成报告，不设置质量门禁，退出码只反映生成是否成功。

## 功能特性

* **组件增量分析**：输出新增、删除和版本变化的组件；
* **多种输出格式**：支持 JSON Delta、SPDX、CycloneDX 和 SWID；

## 插件镜像

```text
cnbcool/sca-sbom:latest
```

## 参数说明

插件参数通过 `settings` 传递：

| 参数 | 说明 | 默认 |
|---|---|---|
| `output` | 输出文件路径 | `${CNB_BUILD_WORKSPACE}/.cnb-sca/sbom-delta.json` |

输出格式由 `output` 后缀决定：

| 后缀 | 格式 |
|---|---|
| `.json` | `cnb-sbom-delta/v1` JSON |
| `.spdx` | SPDX 2.3 Tag-Value |
| `.spdx.json` | SPDX 2.3 JSON |
| `.cyclonedx.json` | CycloneDX JSON |
| `.cyclonedx.xml` | CycloneDX XML |
| `.swid.xml` | SWID XML |

## 在 CNB 中使用

```yaml title=".cnb.yml"
main:
  pull_request:
    - stages:
        - name: 生成 SBOM Delta
          image: cnbcool/sca-sbom:latest
          settings:
            output: ${CNB_BUILD_WORKSPACE}/.cnb-sca/sbom-delta.json
```

### 输出 SPDX

```yaml title=".cnb.yml"
main:
  pull_request:
    - stages:
        - name: 生成 SPDX
          image: cnbcool/sca-sbom:latest
          settings:
            output: ${CNB_BUILD_WORKSPACE}/.cnb-sca/report.spdx
```

## JSON Delta 输出说明

```json
{
  "schema": "cnb-sbom-delta/v1",
  "complete": false,
  "base_ref": "base-commit-sha",
  "head_ref": "head-commit-sha",
  "summary": {
    "added": 1,
    "removed": 0,
    "updated": 1
  },
  "components": [
    {
      "type": "added",
      "component_id": "golang/github.com/example/library",
      "name": "library",
      "head_version": "v1.2.0",
      "head_path": "go.mod",
      "evidence": "gomod"
    }
  ]
}
```

组件变化类型：

* `added`：组件只存在于 Head；
* `removed`：组件只存在于 Base；
* `updated`：组件身份和来源路径相同，但版本不同。

`updated` 只表示版本变化，不区分升级或降级。

## 标准格式说明

SPDX、CycloneDX 和 SWID 输出包含：

* 新增组件的 Head 版本；
* 更新组件的 Head 版本。

## 退出码

| 退出码 | 说明 |
|---:|---|
| `0` | 报告生成成功，包括没有组件变化的空报告 |
| `2` | 配置错误或扫描失败 |

## 下一步

* [插件总览](./sca-plugins.md) —— 三个插件的整体配置与门禁说明
* [开源组件漏洞扫描](./sca-vulnerability.md) —— 漏洞门禁与增量规则
* [License 扫描](./sca-license.md) —— License 风险门禁