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
- 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
- GitLab Pipelines
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.
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.
GitHub Actions¶
Scanning steps can be added to your GitHub Actions workflow. A scanning step can be added, for example:
- 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
Build Image
is where your image is built. Your workflow is likely different from 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 before 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
- 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 keyenv
removed from stepRun Boost Trivy Image Scanner
.
Azure DevOps¶
Scanning steps can be added to your Azure DevOps pipelines by installing our extension.
Before 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:
- 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
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 keyenv
removed from stepBoostSecurityScan
.
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 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
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
- 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.
Bitbucket Pipelines¶
Scanning steps can be added to your Bitbucket pipeline. A scanning step can be added, for example:
- 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"
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 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 locationhttps://bitbucket.org/<workspace-slug>/workspace/settings/addon/admin/pipelines/account-variables
and for repository variables they would be added at locationhttps://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"
Gitlab Pipelines¶
Scanning steps can be added to your GitLab pipeline. A scanning step can be added for example with:
include:
- remote: 'https://raw.githubusercontent.com/boostsecurityio/boostsec-scanner-gitlab/main/scanner.yml'
boost-native-scanner:
stage: build
extends:
- .boost_scan
variables:
BOOST_SCANNER_REGISTRY_MODULE: "boostsecurityio/native-scanner"
Within this example, the include
step loads the BoostSecurity template into the pipeline making certain extension points available via the extends
statement. For instance, in the example above, the .boost_scan
extension is loaded, which will install the BoostSecurity CLI, start docker-in-docker, apply specific rules, and then execute the scan.
The environment variable BOOST_API_TOKEN
is required, should be defined within your secrets and should contain 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 can be configured in the pipeline as required.
GitLab Pipeline 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.
- Update your pipeline:
.gitlab-ci.yml
:
include:
- remote: 'https://raw.githubusercontent.com/boostsecurityio/boostsec-scanner-gitlab/main/scanner.yml'
boost-sast-scan:
stage: build
extends:
- .boost_scan
variables:
BOOST_SCANNER_REGISTRY_MODULE: "boostsecurityio/native-scanner"
boost-sbom-scan:
stage: build
extends:
- .boost_scan
rules:
# execute on pushes to the default branch
- if: ($CI_PIPELINE_SOURCE == "push") && ($CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH)
variables:
BOOST_SCANNER_REGISTRY_MODULE: "boostsecurityio/trivy-sbom"
GitLab Pipeline 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.
include:
- remote: 'https://raw.githubusercontent.com/boostsecurityio/boostsec-scanner-gitlab/main/scanner.yml'
boost-sast-scan:
stage: build
extends:
- .boost_scan
script:
- docker build . -t ${BOOST_IMAGE_NAME}
- !reference [.boost_scan, script]
variables:
BOOST_SCANNER_REGISTRY_MODULE: "boostsecurityio/trivy-image"
BOOST_IMAGE_NAME: acme-analytics
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 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
"""
}
}
}
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 differ for each SCM system.