GitHub action: Black Duck scan and publish to the CloudBees platform

Use this action to scan repositories for dependency vulnerabilities with the Black Duck Software Composition Analysis (SCA) scanner, and then view comprehensive security results in the CloudBees platform.

This action is available on the GitHub marketplace.

Prerequisites

Set up the CloudBees platform and GHA to work together, providing key features of the platform to GHA workflows. Refer to Getting started for more information.

Scanner information

The Black Duck SCA scanner architectural components are:

Client-side: The Black Duck Detect scanning tool, the Signature Scanner command line tool, and the REST API.
Server-side: The Black Duck server.
Data center: The Black Duck KnowledgeBase open-source software database.

The scanning process is as follows:

The Black Duck Detect tool is used to authenticate and initiate the code scan.
Codebases are scanned on the client side.
The scan data is uploaded to the Black Duck server with the Detect tool. The completed scan data does not contain any source code, to maintain your code security. The completed scan contains only file and directory signatures, and information derived from package management files.
The scan data is sent to the Black Duck KnowledgeBase, and open source components in your code are matched and identified. The matching/identification process is based on your package manager data and SHA1 hashes created by the Signature Scanner when it scans your files and directories.
The REST API is used to fetch the bearer token and retrieve the scanning results.
The matched open source components are reported as a viewable Bill of Materials that contains the associated security, licensing, and operational risks of the discovered components.

For more information about the Black Duck SCA scanner, refer to the product documentation.

Inputs

Table 1. Input details
Input name	Data type	Required?	Description
`cloudbees-pat`	String	Yes	The CloudBees platform personal access token.
`api-token`	String	Yes	The Black Duck client secret.
`server-url`	String	Yes	The Black Duck server URL.
`cloudbees-url`	String	No	The CloudBees platform URL. The default value is `"https://api.cloudbees.io"`.
`detect-cli-params`	String	No	Specify any Black Duck Detect properties.
`project-name`	String	No	The Black Duck project name.
`project-version`	String	No	The Black Duck project version.

Usage examples

The following is a basic example of using this action:

      - name: Scan with Black Duck SCA
        uses: cloudbees-io-gha/blackduck-scan-publish@v1
        with:
          api-token: ${{ secrets.BLACK_DUCK_TOKEN }}
          server-url: ${{ vars.BLACK_DUCK_URL }}
          cloudbees-pat: ${{ secrets.CloudBees-platform-PAT }}▼

In the following example, the Black Duck Detect properties logging.level.detect and blackduck.offline.mode are specified:

      - name: Scan with Black Duck SCA with params
        uses: cloudbees-io-gha/blackduck-scan-publish@v1
        with:
          cloudbees-pat: ${{ secrets.CloudBees-platform-PAT }}
          api-token: ${{ secrets.BLACK_DUCK_TOKEN }}
          server-url: ${{ vars.BLACK_DUCK_URL }}
          detect-cli-params: '--logging.level.detect=DEBUG --blackduck.offline.mode=false'▼

Full workflow and run example

The following GHA workflow example scans a repository with Black Duck.

Example GHA workflow YAML file

name: Black Duck scan workflow

on:
  push:
    branches:
    - main

jobs:
  blackduck-codescan:
    runs-on: ubuntu-latest
    steps:
      - name: Check out repository code
        uses: actions/checkout@v3

      - name: Black Duck scan
        uses: cloudbees-io-gha/blackduck-scan-publish@v1
        with:
          cloudbees-pat: ${{ secrets.CLOUDBEES_PAT }}
          api-token: ${{ secrets.BLACKDUCK_API_TOKEN }}
          server-url: ${{ vars.BLACKDUCK_SERVER_URL }}▼

After the GHA run has completed, the security findings are collected and displayed in the Security center of the component containing the workflow.

Figure 1. Example Black Duck scanning results highlighted.