Bitbucket Pipelines Pipe: sBOM Utilities

A Bitbucket Pipe containing a collection of open source tools to perform various types of additionl analysis on a CycloneDX or SPDX sBOM (Software Bill of Materials).

The official copy this project is hosted on Bitbucket. In order to reach a diverse audience a copy of the repo also exists in GitHub. Pull Requests should be submitted to the to the Bitbucket reposiotry and changes will be kept in sync.

Existing toolset and roadmap

The following tooling/functionally is currently available in this pipe

Current Tools

Tool/Feature	Description	From Version
devops-kung-fu/bomber	Scans Software Bill of Materials (SBOMs) for security vulnerabilities	1.0.0
interlynk-io/sbomqs	SBOM quality score - Quality metrics for your sboms	1.1.1
osv-scanner	Vulnerability scanner which uses the data provided by the osv.dev	1.2.0
grype	A vulnerability scanner for container images and filesystems	1.4.0

Future Tools & Featurs

The following are the next set of tools/features which will be incorported into this pipe. To requrst other tooling/features or to vote to have a specific tool/feature integreted next, open an issue

Tool/Feature	Description
sBOM Signing	Sign the sBOM using your priviate key to prove ownership
Distribution API	Send your sBOM to servers such as DependencyTrack for storage and further analysis

And more

YAML Definition

The following is an example of a Bitbucket Pipeline which performs the following:

1. Installes dependencies for a npm project
2. Produces a sBOM via cyclonedx-npm-pipe or cyclonedx-bitbucket-pipe
3. Uses sbom-utilities-pipe to furter process the sBOM

In the following example the sbom-utilities-pipe scans the sBOM for vulnerabilities using devops-kung-fu/bomber then scans the sbom to generate a quality score using interlynk-io/sbomqs. The following code snip would need to be added to the bitbucket-pipelines.yml file

pipelines:
  default:
    - step:
        name: Build and Test
        caches:
          - node
        script:
          - npm install
          - npm test
    - step:
        name: Gen CycloneDX sBom
        caches:
          - node
        script:
          # the build directory is owned by root but the pipe runs as the bitbucket-user
          # change the permission to allow the pipe to write to the build directory
          - chmod 777 build
          - pipe: docker://ccideas/cyclonedx-npm-pipe:1.3.0
            variables:
              IGNORE_NPM_ERRORS: 'true' # optional
              NPM_SHORT_PURLS: 'true' # optional
              NPM_OUTPUT_FORMAT: 'json' # optional
              NPM_PACKAGE_LOCK_ONLY: 'false' # optional
              OUTPUT_DIRECTORY: 'build' # optional # this dir should be archived by the pipeline
        artifacts:
          - build/*
  - step:
      name: Process sBOM
      script:
        # the build directory is owned by root but the pipe runs as the bitbucket-user
        # change the permission to allow the pipe to write to the build directory
        - chmod 777 build
        - pipe: docker://ccideas/sbom-utilities-pipe:1.4.0
          variables:
            PATH_TO_SBOM: "build/${BITBUCKET_REPO_SLUG}.json"
            SCAN_SBOM_WITH_BOMBER: 'true' # to enable a bomber scan
            BOMBER_OUTPUT_FORMAT: 'html'
            BOMBER_DEBUG: 'true'
            OUTPUT_DIRECTORY: 'build'
            SCAN_SBOM_WITH_SBOMQS: 'true' # to enable an sbomqs scan
            SBOMQS_OUTPUT_FORMAT: 'json'
            SCAN_SBOM_WITH_OSV: 'true' # to enable an osv scan
            OSV_OUTPUT_FORMAT: 'json'
            SCAN_SBOM_WITH_GRYPE: 'true' # to enable a grype scan
            GRYPE_ARGS: '--output table --add-cpes-if-none'
            GRYPE_OUTPUT_FILENAME: 'grype-scan-results.txt'
        artifacts:
          - build/*

Variables

Variable	Usage	Options	Default	Required
PATH_TO_SBOM	Used to specify the name of the sbom file to further process			true
SCAN_SBOM_WITH_BOMBER	Used to scan the sBOM for vulnerabilities using bomber	true, false	false	false
BOMBER_DEBUG	Used to enable debug mode during bomber scan	true, false	false	false
BOMBER_IGNORE_FILE	Used to tell bomber what CVEs to ignore		none	false
BOMBER_PROVIDER	Used to specify what vulnerability provider bomber will use	osv, ossindex	osv	false
BOMBER_PROVIDER_TOKEN	Used to specify an API token for the selected provider		none	false
BOMBER_PROVIDER_USERNAME	Used to specify an username for the selected provider		none	false
BOMBER_OUTPUT_FORMAT	Used to specify the output format of the bomber scan	json, html, stdout	stdout	false
SCAN_SBOM_WITH_SBOMQS	Used to scan the sBOM in order to generate a quality quality score	true, false	false	false
SBOMQS_OUTPUT_FORMAT	Used to specify the output format of the sbomqs scan	detailed, json	detailed	false
SCAN_SBOM_WITH_OSV	Used to scan the sBOM for vulberabilities using osv scanner	true, false	false	false
OSV_OUTPUT_FORMAT	Used to specify the output format of the osv scan	table, json, markdown, sarif	json	false
OSV_OUTPUT_FILENAME	Used to specify the filename to store the osv scan output		auto-generated	false
SCAN_SBOM_WITH_GRYPE	Used to scan the sBOM for vulberabilities using the grype scanner	true, false	false	false
GRYPE_ARGS	cmd args to use when running grype	see grype --help for full list		false
GRYPE_OUTPUT_FILENAME	the file to write grype ouput to		auto-generated	false
OUTPUT_DIRECTORY	Used to specify the directory to place all output in		build	false

Need an sBOM

This project contains some sample sBOMs which can be found in the examples/sboms directory. To produce a sBOM for a given project you can use any of the following Bitbucket Pipe

• cyclonedx-npm-pipe
• cyclonedx-bitbucket-pipe

Live Example

A working pipeline for the popular auditjs tool has been created as an example. The pipeline in this fork of the auditjs tool will install the required dependencies then generate a CycloneDX sBOM containing all the ingredients which make up the product then the sBOM will be further processed by the sbom-utilities-pipe

• Repository Link
• Link to bitbucket-pipelines.yml
• Link to pipeline

Support

If you'd like help with this pipe, or you have an issue, or a feature request, let us know.

If you are reporting an issue, please include:

the version of the pipe relevant logs and error messages steps to reproduce

Credits

This Bitbucket pipe is a collection and integration of the following open source tools

• bomber
• interlynk-io/sbomqs
• osv-scanner
• grype

A big thank-you to the teams and volunteers who make these amazing tools available