Use in CI/CD
An SBOM is a point-in-time snapshot of dependencies, so it must be regenerated whenever dependencies change to stay in sync with the code. In CI it refreshes on every build and release, attaches to release artifacts, and becomes the basis for a vulnerability policy gate.
Important: a scan reports vulnerabilities and exits successfully unless you ask it to gate.
--fail-onmakes the scan itself exit non-zero when a condition you name is met (exit 4), or cannot be judged from what the scan produced (exit 5): a finding at a severity or worse, a known malicious package, a license conflict, a scan that found no software (empty-result), or license coverage below a percentage you set (license-coverage=<0-100>).--fail-on-conformancedoes the same for the conformance check report (exit 2). See Exit codes. No separate step that inspects the report files is needed.
To reduce load, split depth by trigger: on PRs generate the SBOM quickly (--generate-only --no-report); on main and releases generate everything (--all --generate-only) and apply the gate.
GitHub Actions
Section titled “GitHub Actions”name: SBOM
on: pull_request: push: branches: [main] release: types: [published]
jobs: # PR: lightweight SBOM only (no report) sbom-pr: if: github.event_name == 'pull_request' runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - run: git clone --depth 1 https://github.com/sktelecom/bomlens.git /tmp/bomlens - run: docker pull ghcr.io/sktelecom/bomlens:latest - name: Generate SBOM (lightweight) run: | /tmp/bomlens/scripts/scan-sbom.sh \ --project "${{ github.event.repository.name }}" \ --version "${{ github.sha }}" \ --generate-only --no-report - uses: actions/upload-artifact@v4 with: name: sbom-pr path: "*/*_bom.json"
# main/release: full generation + vulnerability gate sbom-full: if: github.event_name != 'pull_request' runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - run: git clone --depth 1 https://github.com/sktelecom/bomlens.git /tmp/bomlens - run: docker pull ghcr.io/sktelecom/bomlens:latest - name: Generate SBOM + reports run: | /tmp/bomlens/scripts/scan-sbom.sh \ --project "${{ github.event.repository.name }}" \ --version "${{ github.sha }}" \ --all --generate-only --fail-on-conformance \ --fail-on vulnerability=critical --fail-on malicious-package
# The scan above already failed this step if the conformance check report says # "fail" (exit 2), if a Critical finding or a malicious package was found # (exit 4), or if either could not be judged (exit 5). Add # `--license <SPDX id> --fail-on license-conflict` to gate on license # conflicts too. Outputs land in a {project}_{version}/ subfolder (see the # CLI reference), hence the */ glob below.
- uses: actions/upload-artifact@v4 if: always() # keep reports even when the gate fails with: name: sbom path: | */*_bom.json */*_security.* */*_risk-report.*GitLab CI
Section titled “GitLab CI”The scan itself gates, so the job needs no jq.
generate-sbom: stage: security image: docker:latest services: - docker:dind before_script: - apk add --no-cache git - git clone --depth 1 https://github.com/sktelecom/bomlens.git /tmp/bomlens script: - docker pull ghcr.io/sktelecom/bomlens:latest - /tmp/bomlens/scripts/scan-sbom.sh --project "$CI_PROJECT_NAME" --version "$CI_COMMIT_SHA" --all --generate-only --fail-on-conformance --fail-on vulnerability=critical --fail-on malicious-package # The scan already fails this job: exit 2 if the conformance check report says # "fail", 4 if a Critical finding or a malicious package was found, 5 if # either could not be judged. Outputs land in a {project}_{version}/ # subfolder (see the CLI reference), hence the */ globs below. artifacts: when: always paths: - "*/*_bom.json" - "*/*_security.*"Declared components in CI
Section titled “Declared components in CI”Your own executables, libraries and firmware, and the vendor binaries or copied sources a scan cannot find, are listed in a declaration file kept in the repository (see Declaring your own components). The scan reads the build outputs that file names, so the job builds first and scans after. This release job also checks the result against BSI TR-03183-2 and takes the version from the tag.
name: Release SBOM
on: push: tags: ['v*']
jobs: sbom: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Build run: make # writes the files sbom-declared.cdx.json names, e.g. out/bin/media-daemon - run: git clone --depth 1 https://github.com/sktelecom/bomlens.git /tmp/bomlens - run: docker pull ghcr.io/sktelecom/bomlens:latest - name: Generate SBOM run: | /tmp/bomlens/scripts/scan-sbom.sh \ --project "${{ github.event.repository.name }}" \ --version "${GITHUB_REF_NAME#v}" \ --components sbom-declared.cdx.json \ --conformance-profile bsi-tr-03183-2 --fail-on-conformance \ --supplier "Example Corp <https://example.com>" \ --sbom-author "Example Corp <sbom@example.com>" \ --license Apache-2.0 \ --generate-only
# A declaration file that is refused (a build output it names is missing, # a component has no bomlens:origin, and so on) fails this step with exit # 1. The SBOM is then kept as {project}_{version}_bom.refused.json, not # _bom.json, so nothing downstream takes the incomplete one. A BSI row # that fails ends the step with exit 2 (--fail-on-conformance).
- uses: actions/upload-artifact@v4 if: always() # keep the conformance report and a refused SBOM too with: name: sbom path: | */*_bom.json */*_conformance.* */*_bom.refused.json${GITHUB_REF_NAME#v} turns the tag v2.1.0 into 2.1.0, which a first-party component without its own version takes. --components names the file explicitly; without it, sbom-declared.cdx.json at the repository root is read anyway. --license takes an SPDX identifier.
When the runner has no Docker
Section titled “When the runner has no Docker”scan-sbom.sh starts containers, so it needs a Docker engine: a runner without one (a Kubernetes runner, a GitLab job without docker:dind) cannot use the examples above. Run the scanner image itself as the job image instead. A source scan inside it needs no Docker socket when a lock file covers the whole tree (a package-lock.json, npm-shrinkwrap.json, pnpm-lock.yaml, bun.lock or gradle.lockfile, with no other manifest below the root): it reads the lock file as it is and fills the licenses it lacks from the package registry. A tree without such a lock file is read by syft from its manifests, which gives direct dependencies only (a Node project with none is refused with guidance), so commit a lock file or use a runner that has Docker.
generate-sbom: stage: security image: name: ghcr.io/sktelecom/bomlens:latest entrypoint: [""] variables: MODE: SOURCE SOURCE_ROOT: $CI_PROJECT_DIR PROJECT_NAME: $CI_PROJECT_NAME PROJECT_VERSION: $CI_COMMIT_SHA GENERATE_NOTICE: "true" GENERATE_SECURITY: "true" UPLOAD_ENABLED: "false" HOST_OUTPUT_DIR: $CI_PROJECT_DIR/sbom-out FAIL_ON: "vulnerability=critical,malicious-package" script: - mkdir -p sbom-out && cd sbom-out - /usr/local/bin/run-scan # In a direct run the gate's verdict is a file, not an exit code: fail the job # when a condition was met (status "met") or could not be judged ("unjudged"). - '! grep -qE "^(met|unjudged)" *_gate.result' artifacts: when: always paths: - sbom-out/The variables are the ones of the direct docker run; the scan reads the project from SOURCE_ROOT and writes into the folder it runs in.
Related: CLI reference | Generate notice, security & risk reports | What the reports mean
OWASP BomLens, an OWASP Incubator Project ·Contributing
Copyright © 2026 SK Telecom Co., Ltd. ·Apache-2.0 ·Third-party licenses