---
url: /en/security/sca-sbom.md
description: >
  Usage of the SBOM Generation plugin (cnbcool/sca-sbom). It compares the
  Base/Head dependencies of a PR to produce a change list, supporting JSON
  Delta, SPDX, CycloneDX, and SWID.
---
The SBOM Generation plugin compares the Base and Head dependencies of a Pull Request and outputs a
component change list (Delta). It only produces a report; it sets no gate, and its exit code reflects
only whether generation succeeded.

## Features

* **Incremental component analysis**: outputs added, removed, and version-changed components;
* **Multiple output formats**: supports JSON Delta, SPDX, CycloneDX, and SWID.

## Plugin image

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

## Parameters

Plugin parameters are passed through `settings`:

| Parameter | Description | Default |
|---|---|---|
| `output` | Output file path | `${CNB_BUILD_WORKSPACE}/.cnb-sca/sbom-delta.json` |

The output format is determined by the `output` suffix:

| Suffix | Format |
|---|---|
| `.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 |

## Usage in CNB

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

### Output SPDX

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

## JSON Delta output

```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"
    }
  ]
}
```

Component change types:

* `added`: the component exists only in Head;
* `removed`: the component exists only in Base;
* `updated`: the component identity and source path are the same, but the version differs.

`updated` only indicates a version change; it does not distinguish an upgrade from a downgrade.

## Standard formats

SPDX, CycloneDX, and SWID output include:

* the Head version of added components;
* the Head version of updated components.

## Exit codes

| Exit code | Description |
|---:|---|
| `0` | Report generated successfully, including an empty report with no component changes |
| `2` | Configuration error or scan failure |

## Next steps

* [Overview](./sca-plugins.md) — overall configuration and gates for the three plugins
* [Open-Source Component Vulnerability Scan](./sca-vulnerability.md) — vulnerability gate and incremental rules
* [License Scan](./sca-license.md) — License risk gate