Black Duck scan and publish to CloudBees Unify

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

For background on how the scanner works and the difference between explicit and implicit scans, refer to Understanding Black Duck scanning.

Prerequisites

Set up CloudBees Unify and GHA to work together, providing key features of CloudBees Unify to GHA workflows. For more information, refer to Set up GitHub Actions integration.

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

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 CloudBees Unify. 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 Component security center of the component containing the workflow.

Figure 1. Example Black Duck scanning results highlighted.

Scan a CloudBees Unify workflow explicitly with Black Duck

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

Understanding Black Duck scanning in GitHub Actions