License Scan

About 577 wordsAbout 2 min

The License Scan plugin identifies dependency License Expressions and supports risk-level gates. By default it checks License risks newly introduced by the PR; set scanMode: full to check all License risks of the current Commit.

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 attachment:

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

This configuration checks all License risks of the current Commit and fails the check for High risks. failOnSeverity is optional. If omitted, the plugin scans without applying a gate.

The following example gates a PR incrementally and uploads no report attachment:

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

The configuration above fails the check when the PR introduces a High License risk.

Difference between pull_request and pull_request.target

For detailed differences, please refer to Code Version Selection.

Parameters

Plugin parameters are passed through settings:

Parameter	Description	Default
`scanMode`	Scan mode: `diff` for an incremental PR scan, `full` for a full scan of the current `CNB_COMMIT`	`diff`
`failOnSeverity`	Minimum License risk level that fails the check: `low`, `medium`, or `high`; no gate runs if unset	none
`publish`	Whether to generate and upload report attachments; uploading requires a trusted event	`false`

To scan without blocking on License risks, omit failOnSeverity. The log will list all risks within the scan scope. See Scan modes and Gates for shared behavior.

Incremental rules

A component whose version changed but whose License Expression is unchanged is not blocked again;
A new component or a new License Expression forms a new risk;
A License risk that already exists on the target branch is not blocked again in the current PR.

Output

The following incremental scan log uses failOnSeverity: high and prints only High License risks:

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

With publish: true, the plugin also generates an XLSX report and uploads it as a Commit attachment named security-license-<scanMode>-<commit>.xlsx. The report contains the license, the normalized expression, risk level, component name and version, PURL, path, and the permissions/conditions/limitations. See Report attachments for file naming and download details.

Commit metadata

The plugin writes the risk counts and gate result to the annotations of the publish target Commit:

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

See Commit metadata for field descriptions.

Exit codes

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

Next steps

Overview — overall configuration and gates for the three plugins
Open-Source Component Vulnerability Scan — vulnerability gate and incremental rules
SBOM Generation — component inventory and standard formats