Configuring BoostSecurity 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

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
GitLab Pipelines
AWS CodeBuild and CodePipeline

If you're using a different Continuous Integration (CI) system, you can use the BoostSecurity CLI (Command Line Interface) to set up the workflow, as is shown in the instructions for Jenkins.

Minimum System Requirements¶

The minimum system requirements for manually running (i.e., not via ZTP (Zero Touch Provisioning)) the BoostSecurity scanner in a CI environment are as follows:

The following binaries must be installed: git, find, tar, and curl or wget.
The machine that executes the BoostSecurity scanner binary must either not have glibc or a glibc version of 2.28 or newer.

Scanner Authentication to the BoostSecurity service¶

An API token must be configured to allow the BoostSecurity scanner to upload results. 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. Our suggested name for it is BOOST_API_TOKEN. We will refer to this secret in the examples below.

Buildkite¶

Buildkite is a platform for running fast, secure, and scalable Continuous Integration pipelines on your 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 depend 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, it does not collect component 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/semgrep

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, scanner modules generating SBOM from container images or scanning for vulnerabilities need to generate the container image 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 BoostSecurity image scanning module scans the image. The environment variable BOOST_IMAGE_NAME is set to the image name to scan the image.

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/semgrep
        - 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 semgrep 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

In the example above, the scanner modules semgrep and trivy-sbom are configured for use. However, you can configure the required scanner module. 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 must first create the container image.

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 BoostSecurity Trivy scanner module to know which image to scan.

Jenkins¶

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

Before doing so, you must make the BoostSecurity 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 to support differential scanning.

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

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 BoostSecurity Semgrep scanner module
          sh label: "scan with boostsecurityio/semgrep",
            script: """
              export BOOST_SCANNER_REGISTRY_MODULE="boostsecurityio/semgrep"
              "${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/semgrep",
            script: """
              export BOOST_SCANNER_REGISTRY_MODULE="boostsecurityio/semgrep"
              "${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 artifacts generated from the build process. For example, scanner modules that generate SBOM from container images or scan for vulnerabilities need to generate the container image 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
            """
        }
      }
    }

AWS CodeBuild¶

Scanning steps can be added to your AWS pipeline by using our CLI installer. A scanning step is included by adding the boost scanning stanza in the buildspec.yml. For example:

  version: 0.2
  env:
    variables:
      BOOST_GIT_BRANCH: main
      BOOST_GIT_PROJECT: <'organization'/'repository'>
      BOOST_SCANNER_REGISTRY_MODULE: boostsecurityio/scanner
      BOOST_API_TOKEN: <'API token'>
      TMPDIR: /tmp
  phases:
    pre_build:
      commands:
        - env
        - curl -s https://assets.build.boostsecurity.io/boost-cli/get-boost-cli | bash
    build:
      commands:
        - ${TMPDIR}/boost-cli/latest scan repo

The environment variables that need to be set:

BOOST_GIT_BRANCH specifies the branch for which the scan is being done. Given the scan is set up for main branches, the environment variable should be set to main.

BOOST_GIT_PROJECT: the organization and the repository for the scan. It should be specified in the format: organization/repository, for example, my_test_org/my_test_repo.

BOOST_SCANNER_REGISTRY_MODULE: The scanner scans the code—for example, boostsecurityio/brakeman.

BOOST_API_TOKEN: The API token created in your Boost account.

TMPDIR: temporary directory used during the scanning. Use /tmp.

The pre_builds command downloads the BoostSecurity command line interface (CLI). The BoostSecurity CLI enables the running of the specified scanner module and publishes the scan results to the BoostSecurity service.

The build command boost-cli/latest scan repo instructs the BoostSecurity to run the scanner module specified in the environment variable BOOST_SCANNER_REGISTRY_MODULE.

What are the Pipelines that are supported for each Source Code Management Application¶

BoostSecurity's technology compatibility in terms of pipelines that are supported for each source code management (SCM) system differs for each SCM system.