CircleCI

Customers using CircleCI should use the Kusari CLI to integrate SBOM ingestion into their pipeline.

note

You need an API key to set this up.

Adding Secrets to CircleCI

You can store secrets either in Project Settings or in a Context (for sharing across projects).

Option 1: Project Environment Variables

Go to your CircleCI project
Navigate to Project Settings → Environment Variables
Click Add Environment Variable and add the following:

First Variable: Client ID

Name: KUSARI_CLIENT_ID
Value: your-client-id-here

Second Variable: Client Secret

Name: KUSARI_CLIENT_SECRET
Value: your-client-secret-here

Option 2: Using Contexts (Recommended for Multiple Projects)

Go to Organization Settings → Contexts
Click Create Context and name it (e.g., kusari-credentials)
Add the environment variables KUSARI_CLIENT_ID and KUSARI_CLIENT_SECRET
Reference the context in your workflow configuration

Secret Masking

CircleCI automatically masks environment variables in job output when using Project Settings or Contexts. Values less than 4 characters will not be masked.

Basic Usage

Here's a basic example of integrating Kusari SBOM upload into your CircleCI pipeline:

.circleci/config.yml excerpt
version: 2.1

jobs:
  build-and-upload-sbom:
    docker:
      - image: cimg/base:2024.12
    environment:
      KUSARI_CLI_VERSION: "0.17.1"
      KUSARI_TENANT_ENDPOINT: https://[tenant_name].api.us.kusari.cloud
    steps:
      - checkout
      - setup_remote_docker:
          version: docker24

      # Install dependencies
      - run:
          name: Install dependencies
          command: |
            sudo apt-get update
            sudo apt-get install -y wget tar ca-certificates curl jq

      # Install kusari CLI
      - run:
          name: Install Kusari CLI
          command: |
            wget https://github.com/kusaridev/kusari-cli/releases/download/v${KUSARI_CLI_VERSION}/kusari-cli_${KUSARI_CLI_VERSION}_linux_amd64.tar.gz
            wget https://github.com/kusaridev/kusari-cli/releases/download/v${KUSARI_CLI_VERSION}/kusari-cli_${KUSARI_CLI_VERSION}_checksums.txt
            grep kusari-cli_${KUSARI_CLI_VERSION}_linux_amd64.tar.gz kusari-cli_${KUSARI_CLI_VERSION}_checksums.txt | sha256sum -c -
            tar -xzf kusari-cli_${KUSARI_CLI_VERSION}_linux_amd64.tar.gz
            chmod +x kusari
            sudo mv kusari /usr/local/bin/
            kusari --version

      # Install syft for SBOM generation
      - run:
          name: Install Syft
          command: |
            curl -sSfL https://raw.githubusercontent.com/anchore/syft/main/install.sh | sh -s -- -b /usr/local/bin

      # Build your application
      - run:
          name: Build Docker image
          command: |
            docker build --tag myapp:latest --file Dockerfile .

      # Login to Kusari
      - run:
          name: Login to Kusari
          command: |
            kusari auth login --client-id="${KUSARI_CLIENT_ID}" --client-secret="${KUSARI_CLIENT_SECRET}"

      # Generate SBOM
      - run:
          name: Generate SBOM
          command: |
            syft myapp:latest -o cyclonedx-json --file sbom.json

      # Upload SBOM to Kusari Platform
      - run:
          name: Upload SBOM to Kusari
          command: |
            kusari platform upload \
              --file-path="sbom.json" \
              --tenant-endpoint="${KUSARI_TENANT_ENDPOINT}" \
              --component-name="${CIRCLE_PROJECT_REPONAME}"

      - store_artifacts:
          path: sbom.json
          destination: sbom

workflows:
  build_and_upload:
    jobs:
      - build-and-upload-sbom:
          context: kusari-credentials  # If using contexts

Required Parameters

--file-path: Path to the SBOM file to upload
--tenant-endpoint: Kusari Platform tenant API endpoint (e.g., https://demo.api.us.kusari.cloud)
Client credentials: Set via kusari auth login using KUSARI_CLIENT_ID and KUSARI_CLIENT_SECRET environment variables

Optional Parameters

--component-name: Component name for grouping multiple SBOM subjects. If a component with this name does not exist, it will be created. Default: uses the subject name from the SBOM
--check-blocked-packages: Check if SBOMs contain dependencies from your blocked package list. If found, the program exits with non-zero status
--document-type: Type of SBOM: source, build, or image
--alias: Alias for the package for grouping
--sbom-subject-name-override: Override the SBOM subject name extracted from the document
--sbom-subject-version-override: Override the SBOM subject version extracted from the document

Complete Example with Multiple SBOMs

This example shows how to generate and upload both image and build SBOMs:

Complete CircleCI config.yml
version: 2.1

jobs:
  build-image:
    docker:
      - image: cimg/go:1.23
    environment:
      KUSARI_CLI_VERSION: "0.17.1"
      KUSARI_TENANT_ENDPOINT: https://[tenant_name].api.us.kusari.cloud
    steps:
      - checkout
      - setup_remote_docker:
          version: docker24

      # Install dependencies
      - run:
          name: Install dependencies
          command: |
            sudo apt-get update
            sudo apt-get install -y wget tar ca-certificates curl jq

      # Install kusari CLI
      - run:
          name: Install Kusari CLI
          command: |
            wget https://github.com/kusaridev/kusari-cli/releases/download/v${KUSARI_CLI_VERSION}/kusari-cli_${KUSARI_CLI_VERSION}_linux_amd64.tar.gz
            wget https://github.com/kusaridev/kusari-cli/releases/download/v${KUSARI_CLI_VERSION}/kusari-cli_${KUSARI_CLI_VERSION}_checksums.txt
            grep kusari-cli_${KUSARI_CLI_VERSION}_linux_amd64.tar.gz kusari-cli_${KUSARI_CLI_VERSION}_checksums.txt | sha256sum -c -
            tar -xzf kusari-cli_${KUSARI_CLI_VERSION}_linux_amd64.tar.gz
            chmod +x kusari
            sudo mv kusari /usr/local/bin/
            kusari --version

      # Install syft for image SBOM generation
      - run:
          name: Install Syft
          command: |
            curl -sSfL https://raw.githubusercontent.com/anchore/syft/main/install.sh | sh -s -- -b /usr/local/bin

      # Install cyclonedx-gomod for build SBOM generation
      - run:
          name: Install cyclonedx-gomod
          command: |
            go install github.com/CycloneDX/cyclonedx-gomod/cmd/cyclonedx-gomod@latest

      # Build and push Docker image
      - run:
          name: Build Docker image
          command: |
            docker build --tag myapp:latest --file Dockerfile .

      # Login to Kusari
      - run:
          name: Login to Kusari
          command: |
            kusari auth login --client-id="${KUSARI_CLIENT_ID}" --client-secret="${KUSARI_CLIENT_SECRET}"

      # Generate image SBOM
      - run:
          name: Generate image SBOM
          command: |
            syft myapp:latest -o cyclonedx-json --file cyclonedx_image.sbom.json

      # Generate build SBOM
      - run:
          name: Generate build SBOM
          command: |
            cyclonedx-gomod app -licenses -json -output cyclonedx_build.sbom.json -main ./src

      # Upload image SBOM
      - run:
          name: Upload image SBOM to Kusari
          command: |
            kusari platform upload \
              --file-path="cyclonedx_image.sbom.json" \
              --tenant-endpoint="${KUSARI_TENANT_ENDPOINT}" \
              --document-type="image" \
              --component-name="${CIRCLE_PROJECT_REPONAME}"

      # Upload build SBOM
      - run:
          name: Upload build SBOM to Kusari
          command: |
            kusari platform upload \
              --file-path="cyclonedx_build.sbom.json" \
              --tenant-endpoint="${KUSARI_TENANT_ENDPOINT}" \
              --document-type="build" \
              --component-name="${CIRCLE_PROJECT_REPONAME}"

      - store_artifacts:
          path: cyclonedx_image.sbom.json
          destination: sbom-image
      - store_artifacts:
          path: cyclonedx_build.sbom.json
          destination: sbom-build

workflows:
  build_and_upload:
    jobs:
      - build-image:
          context: kusari-credentials

Example with Blocked Packages Check

Enable the --check-blocked-packages flag to validate that uploaded SBOMs don't contain dependencies from your blocked package list:

      # Upload with blocked packages check
      - run:
          name: Upload SBOM with blocked packages check
          command: |
            kusari platform upload \
              --file-path="sbom.json" \
              --tenant-endpoint="${KUSARI_TENANT_ENDPOINT}" \
              --component-name="${CIRCLE_PROJECT_REPONAME}" \
              --document-type="image" \
              --check-blocked-packages

Example screenshot showing blocked packages found:

blocked_packages

note

Modification of the blocked packages can be done on the admin page

Full Documentation

For complete CLI documentation including all options and advanced configurations, see the Kusari CLI platform upload documentation.

Adding Secrets to CircleCI​

Option 1: Project Environment Variables​

First Variable: Client ID​

Second Variable: Client Secret​

Option 2: Using Contexts (Recommended for Multiple Projects)​

Basic Usage​

Required Parameters​

Optional Parameters​

Complete Example with Multiple SBOMs​

Example with Blocked Packages Check​

Full Documentation​