Overview

About 829 wordsAbout 3 min

Overview gathers the three SCA pipeline plugins CNB provides for checking dependency vulnerabilities and License risks, and generating a component inventory (SBOM).

When to use: when you need to wire dependency security checks into your own pipeline — for example running incremental PR scans or full Commit scans from .cnb.yml, with optional gates and report attachments. For the platform's built-in repository scans, see Code security scanning.

Plugin list

Plugin	Image	Description
Open-Source Component Vulnerability Scan	`cnbcool/sca-vulnerability:latest`	Checks dependency vulnerabilities; configurable gate
License Scan	`cnbcool/sca-license:latest`	Checks License risks; configurable gate
SBOM Generation	`cnbcool/sca-sbom:latest`	Outputs the component inventory or component changes

Usage in CNB

Add the following configuration to .cnb.yml at the root of your repository to run a full scan on push and upload the report attachments:

.cnb.yml
main:
  push:
    - stages:
        - name: Open-Source Component Vulnerability Scan
          image: cnbcool/sca-vulnerability:latest
          timeout: 30m
          settings:
            scanMode: full
            failOnSeverity: high
            publish: true

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

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

For a PR, the incremental gate uploads no attachment:

.cnb.yml
main:
  pull_request.target:
    - stages:
        - name: Open-Source Component Vulnerability Scan
          image: cnbcool/sca-vulnerability:latest
          timeout: 30m
          settings:
            failOnSeverity: high

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

scanMode defaults to diff and publish defaults to false, so the configuration above only gates the PR and uploads nothing.

Use timeout to control task duration, and allowFailure to control whether a task failure affects subsequent tasks and the final result.

Difference between pull_request and pull_request.target

For detailed differences, please refer to Code Version Selection.

Scan modes

All three plugins support scanMode, either diff (default) or full:

Mode	Value	Scan target	Gate scope
Incremental (default)	`diff`	Newly introduced risks, or components added or changed in version by the PR	Risks new to this PR
Full	`full`	All dependency components of the current `CNB_COMMIT`	All risks of the current Commit

An incremental SBOM contains only added components and components whose versions changed; use full for a complete inventory.

Gates

The vulnerability and License plugins use failOnSeverity to set the minimum risk level that fails the check: for example, failOnSeverity: high blocks High and Critical vulnerabilities and High License risks. The SBOM plugin runs no gate.

With failOnSeverity: matching risks fail the check. The log lists findings at or above the threshold; risks below it still count in the scan results.
Without failOnSeverity: no gate runs. The log lists all risks within the scan scope.

After scanning, the plugin uploads attachments (with publish: true) and writes Commit metadata before printing the gate result. A matched gate does not prevent report publishing; see Exit codes for the exit status.

Report attachments

publish defaults to false, so report attachments are neither generated nor uploaded. Set it to true to generate and upload them. Download attachments from the Commit details page: incremental scans attach them to the latest PR Commit, and full scans to the current CNB_COMMIT.

Plugin	Report file name
`sca-vulnerability`	`security-vulnerability-<scanMode>-<commit>.xlsx`
`sca-license`	`security-license-<scanMode>-<commit>.xlsx`
`sca-sbom`	`security-sbom-<scanMode>-<commit>.<ext>`

In the file name <scanMode> is diff or full, and <commit> is the full SHA of the publish target. The SBOM suffix is determined by format; see SBOM Generation.

Commit metadata

The plugin writes the result summary to Commit annotations, associated with the same Commit as the report attachments. Field format:

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

Capability (`capability`)	Fixed count keys
`vulnerability`	`critical.count`, `high.count`, `medium.count`, `low.count`
`license`	`high.count`, `medium.count`, `low.count`
`sbom`	`total.count` (total components, no risk levels)

scanMode corresponds to the setting of the same name in .cnb.yml: diff (incremental) or full (full scan).

Field (`field`)	Description
`reporter`	Scan report download URL
`gate`	Gate result: `pass` when no gate is configured or the gate is not matched, `gate` when it is matched
`<level>.count`	Count per risk level; keys are listed above
`total.count`	Number of components in the SBOM scan

Exit codes

Exit code	Description
`0`	Scan succeeded with no gate matched or no gate configured
`1`	A risk matched the gate (vulnerability and License plugins only)
`2`	Configuration error or scan failure; with `publish: true`, failure to publish the attachment or metadata

Next steps

Open-Source Component Vulnerability Scan — parameters, vulnerability gate, and scan modes
License Scan — parameters and License risk gate
SBOM Generation — component inventory and standard formats