CI/CD

SBOMs in CircleCI

One job in .circleci/config.yml that generates, scores and uploads an SBOM on every push and release tag. The token lives in a CircleCI context, so you can restrict who can use it, and the CLI attaches the branch, commit and build number by itself.

Before you start

Keyless sign-in, which needs no stored token, is available on GitHub Actions and GitLab CI only. On other systems the token is the credential, so treat it like any other deploy secret: limit who can read it and rotate it on your usual schedule.

Add the pipeline

Commit this .circleci/config.yml and put in your project ID:

# .circleci/config.yml
version: 2.1

jobs:
  sbom:
    docker:
      - image: cimg/python:3.12
    environment:
      SBOMBOX_PROJECT: 0193c0de-...   # your project ID (not a secret)
      SBOMBOX_FAIL_UNDER: "7"         # minimum score, 0 turns the gate off
    steps:
      - checkout
      - run:
          name: Install SBOMBox CLI
          command: |
            curl -fsSL https://sbombox.com/install.sh | SBOMBOX_NO_MODIFY_PATH=1 sh
            echo 'export PATH="$HOME/.local/bin:$PATH"' >> "$BASH_ENV"
      - run:
          name: Generate and score SBOM
          command: |
            sbombox generate --output sbom.json
            sbombox score sbom.json --format detailed
      # Upload before enforcing the gate, so failing runs are on record too.
      - run:
          name: Upload to SBOMBox
          command: |
            if [ -z "${SBOMBOX_TOKEN:-}" ]; then
              echo "No SBOMBOX_TOKEN (for example a pull request from a fork). Skipping upload."
              exit 0
            fi
            sbombox push sbom.json ${CIRCLE_TAG:+--version "$CIRCLE_TAG"}
      - run:
          name: Enforce minimum score
          command: sbombox score sbom.json --fail-under "$SBOMBOX_FAIL_UNDER"
      - store_artifacts:
          path: sbom.json

workflows:
  sbom:
    jobs:
      - sbom:
          context: sbombox          # holds SBOMBOX_TOKEN
          filters:
            tags:
              only: /^v.*/          # also run for release tags

What each run does

Uploads made with a token are recorded at provenance level P1: the branch, commit, build number and repository are attached as reported by the CI system. Keyless uploads from GitHub Actions and GitLab CI reach P2, where SBOMBox verifies the repository, commit and run itself.

Pull requests vs releases

To check a compliance ruleset on releases, add sbombox compliance sbom.json -p cra-readiness to a job that runs only on tags. See the end-to-end guide for the full flow.

Monorepos

Give the job a service parameter and run it once per service, each with its own context holding that project's token and ID:

jobs:
  sbom:
    parameters:
      service:
        type: string
    docker:
      - image: cimg/python:3.12
    steps:
      - checkout
      # ... install step as above, then:
      - run:
          name: Generate and score SBOM
          command: |
            sbombox generate --dir "services/<< parameters.service >>" --output sbom.json
            sbombox score sbom.json --format detailed
      # ... upload, gate and store_artifacts steps as above

workflows:
  sbom:
    jobs:
      - sbom:
          name: sbom-api
          service: api
          context: sbombox-api      # SBOMBOX_TOKEN and SBOMBOX_PROJECT for api
      - sbom:
          name: sbom-web
          service: web
          context: sbombox-web

To report the services as one product, combine the uploads in SBOMBox. See Unify SBOMs.

Options

Set these in the job's environment, in the context, or in Project Settings.

Environment variables
VariableDefaultWhat it does
SBOMBOX_TOKEN-Project API token. Store it as a secret, never in the repository. Without it the upload step is skipped.
SBOMBOX_PROJECT-Project ID to upload to. Not a secret.
SBOMBOX_FAIL_UNDER7 in these examplesMinimum quality score, 0-10. The job fails below it, after the upload. 0 turns the gate off.
SBOMBOX_GENERATORSBOMBox choosesForce which generator runs, comma-separated in order of preference, e.g. npm-sbom or cyclonedx-npm,syft.
SBOMBOX_VERSIONcurrent versionInstaller: pin the CLI version, e.g. 0.2.0, for reproducible builds. Versions below the supported minimum are refused.
SBOMBOX_GENERATORSautoInstaller: generators to install - syft, cyclonedx-py, cyclonedx-npm, cdxgen, auto, all or none. Add cdxgen for Java and Gradle.
SBOMBOX_SYFT_VERSIONv1.57.1Installer: the syft version to install. It is checked against its published SHA-256.
SBOMBOX_NO_MODIFY_PATH-Installer: set to 1 so CI shell profiles are left alone. Add $HOME/.local/bin to PATH yourself, as the examples do.
SBOMBOX_API_URLhttps://api.sbombox.comSelf-hosted SBOMBox: the API address, for both the installer and the CLI.

Put installer variables in front of sh in the install step, e.g. SBOMBOX_VERSION=0.2.0. Runners that cannot reach sbombox.com can run a copy of the installer from an internal mirror; it still downloads its tools, so allow those downloads or mirror them too.

Troubleshooting

Common problems
SymptomCauseFix
No SBOMBOX_TOKEN ... Skipping upload. on your own branchesThe job does not use the context, or the person who triggered it is outside the context's security group.Check the context: line and the context's restrictions.
The job never runs for tagsNo tag filter on the job.Add filters: tags: only: /^v.*/ to the job in the workflow, and to every job it requires.
Authentication failed: No CI identity token available. Set SBOMBOX_TOKEN, or run sbombox login. (exit 5)SBOMBOX_TOKEN is not reaching the upload step.Check the secret's name and that it is exposed to this job, as described in Before you start.
Upload failed: Authentication failed: ... (exit 5)The token was revoked, or belongs to another project.Create a new token for this project and replace the secret.
No project specified. (exit 2)SBOMBOX_PROJECT is not set.Set it in the pipeline file or as a CI variable.
Network error: ... (exit 3)The runner cannot reach the SBOMBox API.Allow outbound HTTPS to api.sbombox.com, or set SBOMBOX_API_URL for a self-hosted deployment.
Could not detect project ecosystem in <dir>: no supported manifest or lockfile. (exit 4)The scan ran in a directory without a manifest.Pass the right directory with sbombox generate --dir <path>. In a monorepo, run one job per service.
No lockfile for npm: transitive dependencies may be missingThe lockfile is not committed, so versions are guessed.Commit the lockfile (package-lock.json, uv.lock, go.sum and so on). See Languages.
Generation failed: No SBOM generator found for ecosystems [...] (exit 4)No generator for this ecosystem is installed on the runner.Run the installer in the same job, or add one with SBOMBOX_GENERATORS, e.g. cdxgen for Java.
Generation failed: SBOMBOX_GENERATOR names unknown generator(s) ... (exit 4)A typo in SBOMBOX_GENERATOR.Use a name from the list the message prints.
Score 6.4 is below threshold 7.0. (exit 1)The quality gate failed. The SBOM was already uploaded, so the run is on record.Run sbombox score sbom.json --format detailed to see the weakest checks, or lower SBOMBOX_FAIL_UNDER while you improve it.
Exit 6, upgrade requiredThe pinned CLI version is below the minimum SBOMBox accepts.Raise or remove SBOMBOX_VERSION.