Install and run sbom-tools in your GitHub Actions workflows for semantic SBOM diff, validation, quality scoring, enrichment, verification, and license checking.
Downloads pre-built binaries with SHA-256 checksum verification and optional Sigstore/SLSA provenance verification. Supports Linux (x86_64, ARM64), macOS (x86_64, ARM64), and Windows (x86_64).
# Pin to commit SHA for maximum supply chain security (recommended)
- uses: sbom-tool/sbom-tools-action@c73f5ccd0e22e0797e1647d8abd57ba59e407472 # v1.2.0
with:
command: diff
args: old.json new.json
fail-on-vuln: true
enrich-vulns: true
output-format: sarif
output-file: results.sarif| Input | Description | Default |
|---|---|---|
version |
sbom-tools version ("0.1.16" or "latest") |
latest |
command |
Command to run: diff, validate, quality, view, query, enrich, verify, license-check, vex |
required |
args |
Arguments to pass to the command | "" |
fail-on-vuln |
Exit non-zero on new vulnerabilities (diff) | false |
fail-on-change |
Exit non-zero on any SBOM changes (diff) | false |
fail-on-vex-gap |
Exit non-zero on VEX coverage gaps (diff, vex) | false |
enrich-vulns |
Enrich with OSV/KEV vulnerability data | false |
output-format |
Output format: json, sarif, markdown, summary, table, csv, html, side-by-side |
"" |
output-file |
Write output to file | "" |
min-score |
Minimum quality score threshold (quality) | "" |
standard |
Compliance standard(s): ntia, cra, fda, ssdf, eo14028 |
"" |
profile |
Quality profile: minimal, standard, security, comprehensive, cra, license-compliance |
"" |
working-directory |
Working directory | . |
verify-provenance |
Provenance verification mode: warn (soft-fail), require (hard-fail), off (skip) |
require |
verify-slsa |
(Deprecated — use verify-provenance) Verify provenance of downloaded binary |
true |
| Output | Description |
|---|---|
exit-code |
Exit code from sbom-tools (0=success, 1=changes, 2=vulns, 4=vex-gaps) |
version |
Installed sbom-tools version |
slsa-verified |
Whether SLSA provenance was successfully verified (true/false) |
Always pin this action to a commit SHA, not a version tag. Tags are mutable pointers that can be force-pushed by an attacker with write access. SHAs are immutable.
# Recommended — immune to tag poisoning:
- uses: sbom-tool/sbom-tools-action@c73f5ccd0e22e0797e1647d8abd57ba59e407472 # v1.2.0
# NOT recommended — vulnerable to tag poisoning:
- uses: sbom-tool/sbom-tools-action@c73f5ccd0e22e0797e1647d8abd57ba59e407472 # v1.2.0.2.0This action implements multiple layers of verification for the downloaded sbom-tools binary:
-
SHA-256 checksum (always) -- verifies the downloaded archive matches the checksum published alongside the release. The checksum is compared by hash value only, not by filename (preventing filename-based attacks in checksum files).
-
Provenance verification (required by default) -- verifies Sigstore bundles via
gh attestation verify(v0.1.16+), falling back to SLSA Level 3 provenance via slsa-verifier for older releases. This cryptographically proves the binary was built by the sbom-tools CI pipeline from the expected source commit. -
Input validation -- all inputs are validated against strict whitelists or regex patterns before use. Shell metacharacters are rejected. Path traversal (
..) is blocked forworking-directoryandoutput-file. -
No expression injection -- user inputs are never interpolated via
${{ }}inrun:blocks. All values flow through environment variables exclusively. -
Archive extraction safety -- archives extract into an isolated subdirectory to prevent Zip Slip / tar path traversal. Symlinked binaries are rejected.
The verify-provenance input controls how provenance failures are handled:
| Mode | Behavior |
|---|---|
require (default) |
Hard-fail if provenance cannot be verified. Blocks compromised releases. |
warn |
Warn but continue if provenance fails. SHA-256 is still enforced. |
off |
Skip provenance verification entirely. |
| Scenario | require |
warn |
|---|---|---|
| Sigstore bundle verifies | slsa-verified=true |
slsa-verified=true |
| SLSA fallback verifies | slsa-verified=true |
slsa-verified=true |
| Provenance fails | Step fails | Warning, continues |
| No provenance in release | Step fails | Warning, continues |
# Default: hard-fail on provenance failure (recommended)
- uses: sbom-tool/sbom-tools-action@c73f5ccd0e22e0797e1647d8abd57ba59e407472 # v1.2.0
with:
command: quality
args: sbom.json
# Opt-in to soft-fail for older releases without provenance
- uses: sbom-tool/sbom-tools-action@c73f5ccd0e22e0797e1647d8abd57ba59e407472 # v1.2.0
with:
command: quality
args: sbom.json
verify-provenance: warnname: SBOM Check
on:
pull_request:
paths: ['sbom.json']
jobs:
sbom-diff:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 2
- name: Get previous SBOM
run: git show HEAD~1:sbom.json > /tmp/old-sbom.json
- name: Diff SBOM
uses: sbom-tool/sbom-tools-action@c73f5ccd0e22e0797e1647d8abd57ba59e407472 # v1.2.0
with:
command: diff
args: /tmp/old-sbom.json sbom.json
fail-on-vuln: true
enrich-vulns: true
output-format: sarif
output-file: results.sarif
- name: Upload SARIF
if: always()
uses: github/codeql-action/upload-sarif@v3
with:
sarif_file: results.sarif- uses: sbom-tool/sbom-tools-action@c73f5ccd0e22e0797e1647d8abd57ba59e407472 # v1.2.0
with:
command: quality
args: sbom.json
profile: security
min-score: '80'- uses: sbom-tool/sbom-tools-action@c73f5ccd0e22e0797e1647d8abd57ba59e407472 # v1.2.0
with:
command: validate
args: sbom.json
standard: cra
output-format: sarif
output-file: compliance.sarif- uses: sbom-tool/sbom-tools-action@c73f5ccd0e22e0797e1647d8abd57ba59e407472 # v1.2.0
with:
command: diff
args: old.json new.json
fail-on-vex-gap: true
enrich-vulns: true- uses: sbom-tool/sbom-tools-action@c73f5ccd0e22e0797e1647d8abd57ba59e407472 # v1.2.0
with:
version: '0.1.16'
command: quality
args: sbom.jsonThe action maps sbom-tools exit codes to GitHub annotations:
| Code | Meaning | Annotation |
|---|---|---|
0 |
Success | None |
1 |
Changes detected (--fail-on-change) |
Warning |
2 |
New vulnerabilities (--fail-on-vuln) |
Error |
4 |
VEX gaps found (--fail-on-vex-gap) |
Error |
Exit codes 1, 2, and 4 are captured in the exit-code output but do not fail the step, so you can use conditional logic:
- uses: sbom-tool/sbom-tools-action@c73f5ccd0e22e0797e1647d8abd57ba59e407472 # v1.2.0
id: sbom
with:
command: diff
args: old.json new.json
fail-on-vuln: true
- if: steps.sbom.outputs.exit-code == '2'
run: echo "New vulnerabilities found!"MIT