Configuring Boost scanner modules with your Continuous Integration (CI)¶

BoostSecurity, through a modularized approach, supports a large number of specialized scanners enabling security automation for several security types such as

Static analysis (SAST)
Software composition (SCA)
Container scanning
Software bill of material inventory (SBOM)

Consequently, BoostSecurity enables security automation to be integrated into development workflows for many programming languages and ecosystems.

You can easily add the BoostSecurity scanner and begin scanning your source code and related artifacts by using one of our officially supported Continuous Integration (CI) plugins:

GitHub Action Workflows
Azure Devops
Bitbucket Pipeline
BuildKite Plugins
Circle CI Orbs
Jenkins

If you're using a different Continuous Integration (CI) system, you can use the BoostSecurity CLI (Command Line Interface) to setup the workflow.

Scanner Authentication to the BoostSecurity service¶

To allow the BoostSecurity scanner to upload results, an API token must be configured. To do so, you first must generate an API Key by visiting the BoostSecurity dashboard's Settings > Application Keys Page.

Once you have the API Key, we recommend you use your Continuous Integration (CI) environment's native secrets management system, and we recommend you give it the name BOOST_API_TOKEN. We will refer to this secret in the examples below.

GitHub Actions¶

Scanning steps can be added to your GitHub Actions workflow. A scanning step can be added for example with:

      - name: Run Native Scanner
        uses: boostsecurityio/boostsec-scanner-github@v4
        with:
          api_token: ${{ secrets.BOOST_API_TOKEN }}
          registry_module: boostsecurityio/native-scanner

boostsecurityio/boostsec-scanner-github is the BoostSecurity action enabling running scanners and uploading results to the BoostSecurity service. The keyword api_token configures the API key for authenticating the scanner, for an API key created from the dashboard Settings Page. The keyword registry_module specifies the scanner module to use; In the example above, the scanner configured is the BoostSecurity native scanner with the id boostsecurityio/native-scanner.

GitHub Action Workflow for source scanning¶

This configuration is appropriate for scanner modules for SAST scanning or SBOM inventory from source code.

Note: Even if the workflow is configured to run the SBOM scanner on pull requests, the SBOM scanner does not collect components inventory on pull requests.

Create a new workflow: .github/workflows/boost.yml:

name: boostsecurity.io
on:
  workflow_dispatch:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main
    types:
      - opened
      - synchronize
jobs:
  boost-sast:
    name: SAST
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v3
      - name: Run Native Scanner
        uses: boostsecurityio/boostsec-scanner-github@v4
        with:
          api_token: ${{ secrets.BOOST_API_TOKEN }}
          registry_module: boostsecurityio/native-scanner
  boost-sbom:
    name: SBOM
    if: github.event_name != 'pull_request'  # SBOM scanner only runs on default branch.
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v3
      - name: Upload SBOM from Trivy
        uses: boostsecurityio/boostsec-scanner-github@v4
        with:
          api_token: ${{ secrets.BOOST_API_TOKEN }}
          registry_module: boostsecurityio/trivy-sbom

GitHub Action Workflow for scanning generated artifacts¶

This configuration is appropriate for scanner modules that scan generated artifacts from the build process. For example, for scanner modules generating SBOM from container images or scanning for vulnerabilities; the container image needs to be generated first.

Add the BoostSecurity scanner module-related stanza to your build workflow.

An example of workflow configuration for container image scanning is provided below.

name: build acme docker image
on:
  workflow_dispatch:
  push:
    branches:
      - main
  ...
jobs:
  generate-acme-image:
    name: Container
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v3
      - name: Build Image   # Build your image here
        run: docker build . -t acme-analytics
      - name: Run Boost Trivy Image Scanner
        uses: boostsecurityio/boostsec-scanner-github@v4
        env:
          BOOST_IMAGE_NAME: acme-analytics  # set image name to scan
        with:
          api_token: ${{ secrets.BOOST_API_TOKEN }}
          registry_module: boostsecurityio/trivy-image

The step Build Image is where your image is built. It is likely your workflow is different than the example below. The part that needs to be inserted in your workflow is the step after, i.e., Run Boost Trivy Image Scanner. In the example above, the container image name set in the environment variable BOOST_IMAGE_NAME is static. If your image name needs to be created dynamically, a step can be inserted prior to the scan step, to set the environment variable. i.e., replace.

      - name: Build Image   # Build your image here
        run: docker build . -t acme-analytics
      - name: Run Boost Trivy Image Scanner
        uses: boostsecurityio/boostsec-scanner-github@v4
        env:
          BOOST_IMAGE_NAME: acme-analytics  # set image name to scan
        with:
          api_token: ${{ secrets.BOOST_API_TOKEN }}
          registry_module: boostsecurityio/trivy-image

with

      - name: Build Image   # Build your image here
        run: docker build . -t <some image name>
      - name: Set Image Name
        run: echo "BOOST_IMAGE_NAME=<some image name>" >> $GITHUB_ENV
      - name: Run Boost Trivy Image Scanner
        uses: boostsecurityio/boostsec-scanner-github@v4
        with:
          api_token: ${{ secrets.BOOST_API_TOKEN }}
          registry_module: boostsecurityio/trivy-image

Note the Set Image Name step setting the environment variable and the key env removed from step Run Boost Trivy Image Scanner.

Azure Devops¶

Scanning steps can be added to your Azure Devops pipelines by installing our Extension.

Prior to doing so, you must install the extension:

Navigate to the Marketplace App.
Click Get it free.
Select your organization and click Install.

Additionally, you must make the Boost Api Token available in your Variables. If you do not already have an api token created, you may create one on the dashboard Settings Page.

Once everything is ready, a scanning step can be added for example with:

  - stage: Run Security Scanners
    variables:
      - group: boostsecurity
      - name: boostApiToken
        value: $[variables.BOOST_API_TOKEN]
    jobs:
      - job:
        steps:
          - task: BoostSecurityScan@1
            inputs:
              apiToken: $(boostApiToken)
              registryModule: boostsecurityio/native-scanner

BoostSecurityScan is the BoostSecurity pipeline task enabling running scanners and uploading results to the BoostSecurity service.

The input apiToken configures the API key for authenticating the scanner.

The keyword registry_module specifies the scanner module to use; In the example above, the scanner configured is the BoostSecurity native scanner with the id boostsecurityio/native-scanner.

Azure Devops for source scanning¶

This configuration is appropriate for scanner modules for SAST scanning or SBOM inventory from source code.

Note: Even if the pipeline is configured to run the SBOM scanner on pull requests, the SBOM scanner does not collect components inventory on pull requests.

  - stage: Run Security Scanners
    variables:
      - group: boostsecurity
      - name: boostApiToken
        value: $[variables.BOOST_API_TOKEN]
      - name: isMainBranch
        value: $[eq(variables['Build.SourceBranch'], 'refs/heads/main')]
    jobs:
      - job:
        steps:
          - task: BoostSecurityScan@1
            inputs:
              apiToken: $(boostApiToken)
              registryModule: boostsecurityio/native-scanner
          - task: BoostSecurityScan@1
            condition: eq(variables.isMainBranch, 'true')
            inputs:
              apiToken: $(boostApiToken)
              registryModule: boostsecurityio/trivy-sbom

Azure Devops for scanning generated artifacts¶

This configuration is appropriate for scanner modules that scan generated artifacts from the build process. For example, for scanner modules generating SBOM from container images or scanning for vulnerabilities; the container image needs to be generated first.

Add the BoostSecurity scanner module-related stanza to your build pipeline, for example:

  - stage: Build Step
    variables:
      - group: boostsecurity
      - name: boostApiToken
        value: $[variables.BOOST_API_TOKEN]
    jobs:
      - job:
        steps:
          - task: Bash@3
            displayName: Build Image
            inputs:
              targetType: "inline"
              script: |
                docker build . -t acme-analytics
          - task: BoostSecurityScan@1
            env:
              BOOST_IMAGE_NAME: acme-analytics  # set image name to scan
            inputs:
              apiToken: $(boostApiToken)
              registryModule: boostsecurityio/trivy-image

In the example above, the container image name set in the environment variable BOOST_IMAGE_NAME is static. If your image name needs to be created dynamically, a step can be inserted prior to the scan step, to set the environment variable. i.e., replace.

  steps:
    - task: Bash@3
      displayName: Build Image
      inputs:
        targetType: "inline"
        script: |
          docker build . -t acme-analytics
    - task: BoostSecurityScan@1
      env:
        BOOST_IMAGE_NAME: acme-analytics  # set image name to scan
      inputs:
        apiToken: $(boostApiToken)
        registryModule: boostsecurityio/trivy-image

with

  steps:
    - task: Bash@3
      displayName: Build Image
      inputs:
        targetType: "inline"
        script: |
          docker build . -t acme-analytics
          echo "##vso[task.setvariable variable=BOOST_IMAGE_NAME]my_image_name_and_tag"
    - task: BoostSecurityScan@1
      inputs:
        apiToken: $(boostApiToken)
        registryModule: boostsecurityio/trivy-image

Note the task.setvariable step setting the environment variable and the key env removed from step BoostSecurityScan.

Buildkite¶

Buildkite is a platform for running fast, secure, and scalable Continuous Integration pipelines on your own infrastructure.

The BoostSecurity integration for Buildkite is packaged as a plugin that runs as a command hook. The plugin executes the BoostSecurity Scanner to scan repositories for vulnerabilities and uploads results to the BoostSecurity platform. Adding BoostSecurity scanning into your workflow is just a matter of adding a stanza to your Buildkite pipeline configuration file. The configuration options and location to add the stanza depends on whether the scanning needs to be done on the project's source code or a generated artifact, such as container images.

The first step in setting BoostSecurity for Buildkite is to define the environment variable BOOST_API_TOKEN for your Buildkite Agent. Refer to the Buildkite documentation for how to do it.

Buildkite Pipeline Steps for scanning source code¶

This configuration is appropriate for scanner modules for SAST scanning or (SBOM) inventory from source code, for example.

Note: Even if the workflow is configured to run the SBOM scanner on pull requests, the SBOM scanner does not collect components inventory on PRs.

When configuring your Buildkite to run the BoostSecurity scanning from the project's source code, add the following stanza to your pipeline.yml:

steps:
  - label: "boostsecurity scanner"
    plugins:
      - boostsecurityio/boostsec-scanner#v4:
          registry_module: boostsecurityio/trivy-sbom
        if: build.branch == "main"
      - boostsecurityio/boostsec-scanner#v4:
          registry_module: boostsecurityio/native-scanner

Buildkite Pipeline Steps for scanning generated artifact¶

This configuration is appropriate for scanner modules that require scan-generated artifacts from the build process. For example, for scanner modules generating SBOM from container images or scanning for vulnerabilities, the container image needs to be generated first.

When configuring your Buildkite to run the BoostSecurity scanning from the generated artifacts, add the following stanza to your pipeline.yml:

steps:
  - command: echo 'BOOST_IMAGE_NAME=myimage:tag' >> $BUILDKITE_ENV_FILE
  - wait
  - label: "Building the Image"
    command: docker build -t ${BOOST_IMAGE_NAME} .
    branches: "main"
  - wait
  - label: "boostsecurity scanner"
    plugins:
      - boostsecurityio/boostsec-scanner#v4:
          registry_module: boostsecurityio/trivy-image
    branches: "main"

In the first step, the docker image is built. In the second step, the image is scanned with the BoostSecurity image scanning module. In order to scan the image, the environment variable BOOST_IMAGE_NAME is set to the image name.

CircleCI¶

The BoostSecurity CI integration for CircleCI provides an orb with both a job running on a machine executor and a command to use within your pipeline configurations. Both invocation methods will execute the BoostSecurity Scanner to scan repositories for vulnerabilities and upload the results to the BoostSecurity service.

The CircleCI Orb is published on the registry and may be found here. The configuration that needs to be added to your .circleci/config.yml depends on whether the scanner runs on the project's source code or on a produced artifact such as a built container image.

The first step in setting BoostSecurity for CircleCI is to create a CircleCI context called boost-security containing a secret named BOOST_API_TOKEN with your organization's API KEY.

CircleCi Job for source scanning¶

This configuration is appropriate for scanner modules for SAST scanning or SBOM inventory from source code, for example.

Note: Even if the workflow is configured to run the SBOM scanner on pull requests, the SBOM scanner does not collect components inventory on pull requests. When configuring your CircleCI to run the BoostSecurity scanning from the project's source code, add the following stanza to your .circleci/config.yml:

version: '2.1'
orbs:
  boost-security-scanner: boostsecurityio/scanner@4

workflows:
  build:
    jobs:
      steps:
        - boost-security-scanner/scan:
            context: boost-security
            registry_module: boostsecurityio/native-scanner
        - when:
            condition:
              or:
                - equal: [ main, << pipeline.git.branch >> ]
            steps:
              - boost-security-scanner/scan:
                  context: boost-security
                  registry_module: boostsecurityio/trivy-sbom             

  version: 2

The example above shows that native-scanner module runs on both commits on the main branch and on pull requests. However, the scanner module trivy-sbom for the SBOM service, runs only on commits on the main branch.

Note That in the example above, the scanner modules native-scanner and trivy-sbom are configured to be used. However, you can configure the scanner module required. Refer to Registry Modules for the available scanner modules.

CircleCi Job for scanning generated artifacts¶

This configuration is appropriate for scanner modules requiring scan-generated artifacts from the build process. For example, scanner modules generating SBOM from container images or scanning for vulnerabilities, the container image needs to be generated first.

In order to enable the scanning of generated artifacts, add the BoostSecurity scanner module-related stanza to your build workflow in .circleci/config.yml, in the appropriate location after the step where the artifact was generated. Note that the example below is related to scanning a container image for vulnerabilities.

version: '2.1'
orbs:
  boost-security-scanner: boostsecurityio/scanner@4

workflows:
  ... some environment specific declarations and steps

jobs:
  ... some test and other jobs

  build-push:
    executor: default
    steps:
      ... some steps specific to your environment
      - checkout
      - run:
          command: make docker.build
      - run:
          command: make docker.push
      - when:
          condition:
            or:
              - equal: [ main, << pipeline.git.branch >> ]
          steps:
            - run:
                name: make docker.echo.tag
                command: |
                  BOOST_IMAGE_NAME=$(make docker.echo.tag)
                  echo "export BOOST_IMAGE_NAME=${BOOST_IMAGE_NAME}" | tee -a $BASH_ENV
            - boost-security-scanner/scan:
                registry_module: boostsecurityio/trivy-image
  version: 2

The condition - equal: [ main, << pipeline.git.branch >> ] makes the image scanning module run on commit to main only after the image was built. The command BOOST_IMAGE_NAME=$(make docker.echo.tag) and echo "export BOOST_IMAGE_NAME=${BOOST_IMAGE_NAME}" | tee -a $BASH_ENV sets the environment variable required by the boost trivy scanner module to know which image to scan.

Bitbucket Pipelines¶

Scanning steps can be added to your Bitbucket pipeline. A scanning step can be added for example with:

        - step:
            name: Boost Native Scanner
            script:
              - pipe: docker://public.ecr.aws/boostsecurityio/boost-scanner-bitbucket:v4
                variables:
                  BOOST_API_TOKEN: $BOOST_API_TOKEN
                  BOOST_SCANNER_REGISTRY_MODULE: "boostsecurityio/native-scanner"

The environment variable BOOST_API_TOKEN is the API token created from the dashboard Settings Page. The variable BOOST_SCANNER_REGISTRY_MODULE specifies the scanner to execute, from the module registry. Multiple scanners steps can be configured in the pipeline, as required.

Note The required environment variables such as $BOOST_API_TOKEN need to be added to workspace or repository variables. For example for workspace variables they would be added at location https://bitbucket.org/<workspace-slug>/workspace/settings/addon/admin/pipelines/account-variables and for repository variables they would be added at location https://bitbucket.org/<workspace-slug>/<repository-slug>/admin/addon/admin/pipelines/repository-variables.

Scanner steps can be configured for both the main branch and for the PR flow. The example below shows steps for running scanners in both the main branch as well as in pull requests:

pipelines:
  branches:
    main:
      - parallel:
        - step:
            name: Semgrep Scanner
            script:
              - pipe: docker://public.ecr.aws/boostsecurityio/boost-scanner-bitbucket:v4
                variables:
                  BOOST_API_TOKEN: $BOOST_API_TOKEN
                  BOOST_SCANNER_REGISTRY_MODULE: "boostsecurityio/semgrep"

        - step:
            name: SBOM
            script:
              - pipe: docker://public.ecr.aws/boostsecurityio/boost-scanner-bitbucket:v4
                variables:
                  BOOST_API_TOKEN: $BOOST_API_TOKEN
                  BOOST_SCANNER_REGISTRY_MODULE: "boostsecurityio/trivy-sbom"

  pull-requests:
    '**':
      - parallel:
        - step:
            name: Semgrep Scanner
            script:
              - pipe: docker://public.ecr.aws/boostsecurityio/boost-scanner-bitbucket:v4
                variables:
                  BOOST_API_TOKEN: $BOOST_API_TOKEN
                  BOOST_SCANNER_REGISTRY_MODULE: "boostsecurityio/semgrep"

Jenkins¶

Scanning steps can be added to your Jenkinsfile by making use of our CLI installer.

Prior to doing so, you must make the Boost Api Token available in your credentials. If you do not already have an api token created, you may create one on the dashboard Settings Page.

Additionally, the CLI will need to run within a context where it may pull from the remote Git repository in order to support differential scanning.

Once everything is ready, a scanning step can be added for example with:

pipeline {
  agent any

  environment {
    // Expose the api token as an environment variable
    BOOST_API_TOKEN = credentials('boost-api-token')
  }

  options {
    // Skip default checkout so that we may expose env vars later
    skipDefaultCheckout(true)
  }

  stages {
    stage('BoostSecurity Scanner') {
      steps {
        script {
          // Ensure SCM parameters are exposed as env vars
          def scmVars = checkout scm
          scmVars.each { k, v ->
            env."${k}" = v
          }
        }

        sh label: "download the boost cli",
          script: """
            curl -s https://assets.build.boostsecurity.io/boost-cli/get-boost-cli | bash
          """

        // Expose GIT credentials to support pulling.
        withCredentials([gitUsernamePassword(credentialsId: "github-token")]) {
          // Execute the boost native scanner module
          sh label: "scan with boostsecurityio/native-scanner",
            script: """
              export BOOST_SCANNER_REGISTRY_MODULE="boostsecurityio/native-scanner"
              "${env.WORKSPACE_TMP}/boost-cli/latest" scan repo
            """
        }
      }
    }
  }
}

Jenkins for source scanning¶

This configuration is appropriate for scanner modules for SAST scanning or SBOM inventory from source code.

Note: Even if the pipeline is configured to run the SBOM scanner on pull requests, the SBOM scanner does not collect components inventory on pull requests.

  stages {
    stage('BoostSecurity Scanner') {
      steps {
        script {
          def scmVars = checkout scm
          scmVars.each { k, v ->
            env."${k}" = v
          }
        }

        sh label: "download the boost cli",
          script: """
            curl -s https://assets.build.boostsecurity.io/boost-cli/get-boost-cli | bash
          """

        withCredentials([gitUsernamePassword(credentialsId: "github-token")]) {
          sh label: "scan with boostsecurityio/native-scanner",
            script: """
              export BOOST_SCANNER_REGISTRY_MODULE="boostsecurityio/native-scanner"
              "${env.WORKSPACE_TMP}/boost-cli/latest" scan repo
            """
        }
      }
    }

    stage('BoostSecurity SBOM') {
      when {
        // SBOM generation should only occur on the main branch
        branch 'main'
      }

      steps {
        script {
          def scmVars = checkout scm
          scmVars.each { k, v ->
            env."${k}" = v
          }
        }

        sh label: "download the boost cli",
          script: """
            curl -s https://assets.build.boostsecurity.io/boost-cli/get-boost-cli | bash
          """

        withCredentials([gitUsernamePassword(credentialsId: "github-token")]) {
          sh label: "scan with boostsecurityio/trivy-sbom",
            script: """
              export BOOST_SCANNER_REGISTRY_MODULE="boostsecurityio/trivy-sbom"
              "${env.WORKSPACE_TMP}/boost-cli/latest" scan repo
            """
        }
      }
    }
  }

Jenkins for scanning generated artifacts¶

This configuration is appropriate for scanner modules that scan generated artifacts from the build process. For example, for scanner modules generating SBOM from container images or scanning for vulnerabilities; the container image needs to be generated first.

Add the BoostSecurity scanner module-related stanza to your build pipeline, for example:

  stages {
    stage('BoostSecurity Scanner') {
      steps {
        script {
          def scmVars = checkout scm
          scmVars.each { k, v ->
            env."${k}" = v
          }
        }

        sh label: "download the boost cli",
          script: """
            curl -s https://assets.build.boostsecurity.io/boost-cli/get-boost-cli | bash
          """

        def dockerfile = 'Dockerfile.test'
        def customImage = docker.build("my-image:${env.BUILD_ID}",
                                       "-f ${dockerfile} ./dockerfiles")

        withCredentials([gitUsernamePassword(credentialsId: "github-token")]) {
          sh label: "scan with boostsecurityio/trivy-image",
            script: """
              export BOOST_IMAGE_NAME="my-image:${env.BUILD_ID}"
              export BOOST_SCANNER_REGISTRY_MODULE="boostsecurityio/trivy-image"
              "${env.WORKSPACE_TMP}/boost-cli/latest" scan repo
            """
        }
      }
    }