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

4 minute read

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 CloudBees platform. You can also use the action output as a quality gate for the next step or job in your workflow.

This action is available on the GitHub marketplace.

Black Duck is a software composition analysis (SCA) scanning solution that helps organizations manage risks associated with open-source software in terms of security, license compliance, and code quality.

Add a Black Duck scan to your workflows in CloudBees platform to:

  • Detect open-source and third-party dependencies in software, source code, and artifacts with multiple analysis techniques.

  • Identify code vulnerabilities and receive timely security advisories.

  • Gain insight into security risks and how to fix vulnerabilities.

CloudBees platform enables you to run a Black Duck scan either implicitly or explicitly.

Explicit and implicit scan types

An implicit scan is automatically triggered, and an explicit scan is one you configure to be invoked in a step of your workflow. To learn more about the differences between explicit and implicit scans, refer to CloudBees actions.

To set up implicit scanning, refer to Code and binary security analysis.

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.

How the scanner works

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:

  1. The Black Duck Detect tool is used to authenticate and initiate the code scan.

  2. Codebases are scanned on the client side.

  3. 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.

  4. 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.

  5. The REST API is used to fetch the bearer token and retrieve the scanning results.

  6. 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 Black Duck documentation.

Inputs

Table 1. Input details
Input name Data type Required? Description

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

project-name

String

No

The Black Duck project name.

project-version

String

No

The Black Duck project version.

Outputs

Table 2. Output details
Output name Data type Description

critical-count

String

The number of Critical security findings discovered during the scan.

very-high-count

String

The number of Very high security findings discovered during the scan.

high-count

String

The number of High security findings discovered during the scan.

medium-count

String

The number of Medium security findings discovered during the scan.

low-count

String

The number of Low security findings discovered during the scan.

This action uses GitHub OIDC authentication to securely communicate with the CloudBees platform. Be sure to set permissions to id-token: write in your workflow.

Usage examples

The following is a basic example of using this action:

permissions: id-token: write contents: read steps: - name: Scan with Black Duck SCA uses: cloudbees-io-gha/blackduck-scan-publish@v2 with: api-token: ${{ secrets.BLACK_DUCK_TOKEN }} server-url: ${{ vars.BLACK_DUCK_URL }}

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

permissions: id-token: write contents: read steps: - name: Scan with Black Duck SCA with params uses: cloudbees-io-gha/blackduck-scan-publish@v2 with: api-token: ${{ secrets.BLACK_DUCK_TOKEN }} server-url: ${{ vars.BLACK_DUCK_URL }} detect-cli-params: '--logging.level.detect=DEBUG --blackduck.offline.mode=false'

Using the action output

You can use the output values from this action in downstream steps and jobs. The following example uses the action output in a downstream step of the same job:

name: my-workflow on: push: branches: - main permissions: contents: read id-token: write jobs: black-duck-scan-job: runs-on: ubuntu-latest steps: - name: Check out source code uses: actions/checkout@v2 - id: black-duck-step name: Black Duck scan uses: cloudbees-io-gha/blackduck-scan-publish@v2 with: api-token: ${{ secrets.BLACK_DUCK_TOKEN }} server-url: ${{ vars.BLACK_DUCK_URL }} - name: Source dir examine run: | docker run --rm -v "${{ github.workspace }}:/work" -w /work golang:1.20.3-alpine3.17 ls -latR /work - id: print-outputs-from-black-duck-step name: Print outputs from the upstream Black Duck step run: | # Printing all outputs echo "Outputs from upstream Black Duck step:" echo "Critical count: ${{ steps.black-duck-step.outputs.critical-count }}" echo "Very high count: ${{ steps.black-duck-step.outputs.very-high-count }}" echo "High count: ${{ steps.black-duck-step.outputs.high-count }}" echo "Medium count: ${{ steps.black-duck-step.outputs.medium-count }}" echo "Low count: ${{ steps.black-duck-step.outputs.low-count }}"

The following example uses the action output in a downstream job:

name: my-workflow on: push: branches: - main permissions: contents: read id-token: write jobs: job1: runs-on: ubuntu-latest outputs: black-duck-job-output-critical: ${{ steps.black-duck-step.outputs.critical-count }} black-duck-job-output-very-high: ${{ steps.black-duck-step.outputs.very-high-count }} black-duck-job-output-high: ${{ steps.black-duck-step.outputs.high-count }} black-duck-job-output-medium: ${{ steps.black-duck-step.outputs.medium-count }} black-duck-job-output-low: ${{ steps.black-duck-step.outputs.low-count }} steps: - name: Check out source code uses: actions/checkout@v2 - id: black-duck-step name: Black Duck scan uses: cloudbees-io-gha/blackduck-scan-publish@v2 with: api-token: ${{ secrets.BLACK_DUCK_TOKEN }} server-url: ${{ vars.BLACK_DUCK_URL }} - name: Source dir examine run: | ls -latR ${GITHUB_WORKSPACE} job2: runs-on: ubuntu-latest needs: job1 steps: - id: print-outputs-from-job1 name: Print outputs from upstream job1 run: | # Printing all outputs echo "Outputs from upstream Black Duck job:" echo "Critical count: ${{ needs.job1.outputs.black-duck-job-output-critical }}" echo "Very high count: ${{ needs.job1.outputs.black-duck-job-output-very-high }}" echo "High count: ${{ needs.job1.outputs.black-duck-job-output-high }}" echo "Medium count: ${{ needs.job1.outputs.black-duck-job-output-medium }}" echo "Low count: ${{ needs.job1.outputs.black-duck-job-output-low }}"

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 permissions: id-token: write contents: read steps: - name: Check out repository code uses: actions/checkout@v3 - name: Black Duck scan uses: cloudbees-io-gha/blackduck-scan-publish@v2 with: 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.

Black Duck results in security center
Figure 1. Example Black Duck scanning results highlighted.

Scan a CloudBees platform workflow explicitly with Black Duck

If you are using a CloudBees platform workflow rather than a GHA workflow, explicitly scan with the CloudBees Black Duck action.