Scan with GitHub Actions

Use these GitHub Actions to run security scans from GHA workflows and publish findings to CloudBees Unify. After a scan completes, findings are displayed in the component security center.

For scanner concepts and implicit scanning, refer to Configure SAST scanning and Configure implicit security analysis.

Supported scanners:

Black Duck SCA
Coverity SAST
Gitleaks
Gosec
Grype
Perforce Klocwork SAST
Trivy

Black Duck SCA scan

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.

Use the blackduck-scan-publish action to scan repositories for dependency vulnerabilities with the Black Duck SCA scanner, and then view comprehensive security results in CloudBees Unify. 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.

Add a Black Duck scan to your workflows in CloudBees Unify 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 Unify enables you to run a Black Duck scan either implicitly or explicitly. An implicit scan is automatically triggered; an explicit scan is one you configure to be invoked in a step of your workflow. To learn more, refer to Configure implicit security analysis.

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:

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 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 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. 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'▼

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 }}"▼

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

Coverity SAST scan

Use the coverity-scan-publish action to perform static application security testing (SAST) on a repository with the Coverity on Polaris scanner from Black Duck, and then view comprehensive security results in CloudBees Unify. This action is available on the GitHub Marketplace.

This action uses GitHub OIDC authentication to securely communicate with CloudBees Unify. Set permissions to id-token: write in your workflow.

Inputs

Table 3. Input details
Input name	Data type	Required?	Description
`api-token`	String	Yes	The Coverity on Polaris API token.
`server-url`	String	Yes	The Coverity on Polaris server URL.
`cloudbees-url`	String	No	The CloudBees Unify URL. The default value is `https://api.cloudbees.io`.

Usage example

The following is a basic example of using this action:

      permissions:
        id-token: write
        contents: read
      steps:
      - name: Scan with Coverity on Polaris
        uses: cloudbees-io-gha/coverity-scan-publish@v2
        with:
          api-token: ${{ secrets.COVERITY_POLARIS_TOKEN }}
          server-url: ${{ vars.COVERITY_POLARIS_SERVER_URL }}▼

Gitleaks scan

Use the gitleaks-scan-publish action to perform static application security testing (SAST) on a repository with the Gitleaks scanner, and then view comprehensive security results in CloudBees Unify.

Inputs

Table 4. Input details
Input name	Data type	Required?	Description
`cloudbees-pat`	String	Yes	The CloudBees Unify personal access token.
`cloudbees-url`	String	No	The CloudBees Unify URL. The default value is `https://api.cloudbees.io`.
`ref`	String	No	The commit reference to be checked out and archived.

Usage example

The following is a basic example of using this action:

      - name: Scan with Gitleaks
        uses: cloudbees-io-gha/gitleaks-scan-publish@v1
        with:
          cloudbees-pat: ${{ secrets.CloudBees-platform-PAT }}▼

Gosec scan

Use the gosec-scan-publish action to perform static application security testing (SAST) on a repository with the open-source Golang Security Checker (Gosec) scanner, and then view comprehensive security results in CloudBees Unify.

Inputs

Table 5. Input details
Input name	Data type	Required?	Description
`cloudbees-pat`	String	Yes	The CloudBees Unify personal access token.
`cloudbees-url`	String	No	The CloudBees Unify URL. The default value is `https://api.cloudbees.io`.

Usage example

The following is a basic example of using this action:

      - name: Scan with Gosec
        uses: cloudbees-io-gha/gosec-scan-publish@v1
        with:
          cloudbees-pat: ${{ secrets.CloudBees-platform-PAT }}▼

Grype scan

Use the grype-scan-publish action to perform static application security testing (SAST) on a binary TAR file with the Grype scanner, and then view comprehensive security results in CloudBees Unify.

Inputs

Input name Data type Required? Description

binary-tar-path

String

Yes

The path of the binary to be scanned.

The binary file must be in the TAR format.

cloudbees-pat

String

Yes

The CloudBees Unify personal access token.

cloudbees-url

String

The CloudBees Unify URL. The default value is https://api.cloudbees.io.

Usage example

The following is a basic example of using this action:

      - name: Scan with Grype
        uses: cloudbees-io-gha/grype-scan-publish@v1
        with:
          binary-tar-path: example-tar-path.tar
          cloudbees-pat: ${{ secrets.CloudBees-platform-PAT }}▼

Perforce Klocwork SAST scan

Use the perforce-klocwork-sast-publish action to analyze source code for security vulnerabilities and quality defects using the Perforce Klocwork SAST scanner. The action output can be used as a quality gate in subsequent GitHub Actions steps or jobs. This action is available on the GitHub Marketplace.

Add a Klocwork scan to your workflows in CloudBees Unify to:

Detect security vulnerabilities and quality defects in source code.
Identify potential security flaws early in the development lifecycle.
Gain insight into code quality risks and how to fix issues.
Ensure compliance with industry standards such as OWASP, CWE, CERT, and MISRA.

CloudBees Unify enables you to run a Klocwork scan either implicitly or explicitly. An implicit scan is automatically triggered; an explicit scan is one you configure to be invoked in a step of your workflow. To learn more, refer to Configure implicit security analysis.

How the scanner works

The Klocwork SAST scanner architectural components are:

Client-side: The Klocwork analysis engine and command-line tools (kwbuildproject, kwciagent).
Server-side: The Klocwork Server for centralized analysis results management.
Analysis engine: Proprietary static analysis engine with deep dataflow and control flow analysis capabilities.

The scanning process is as follows:

The Klocwork build specification is created to capture the build configuration of your project.
Source code is analyzed on the client side using the Klocwork analysis engine.
The analysis results are uploaded to the Klocwork Server (if configured).
Security vulnerabilities and quality defects are identified based on enabled checkers and taxonomies.
Results are reported with severity levels, detailed descriptions, and remediation guidance.
The scan results are made available as actionable outputs for quality gates and downstream workflow steps.

For more information about the Perforce Klocwork SAST scanner, refer to the Perforce Klocwork documentation.

Inputs

Table 7. Input details
Input name	Data type	Required?	Description
`url`	String	Yes	The Klocwork server URL.
`username`	String	Yes	Klocwork username.
`password`	String	No	Klocwork password.
`token`	String	No	Klocwork application token.
`build-tool`	String	Yes	Klocwork build tool [make / cmake / python / maven / dotnet].
`build-directory`	String	No	Klocwork build directory [default is root folder /].
`ref`	String	Yes	Specify the ref to be checked out and scanned.
`build-name`	String	No	Klocwork build name.
`build-options`	String	No	Klocwork scan build options [e.g., make <target-name> -j4].
`build-spec-file`	String	No	Klocwork build specification file path [e.g., /tmp/kwinject.out].
`enable-agent-scan`	Boolean	No	Enable Klocwork Agent Scan [default is full scan].
`license-host`	String	No	Klocwork license server hostname [default is server hostname].
`license-port`	String	No	Klocwork license server port [default is 27000].
`project-name`	String	No	Klocwork project name.
`scan-timeout`	String	No	Klocwork scan waiting time in seconds [e.g., 3600].
`tables-directory`	String	No	Klocwork scan tables directory [e.g., /tmp/tables].
`enable-local-scan`	Boolean	No	Enable Klocwork Local Scan [performs analysis locally on the agent only and does not push results to the Klocwork Server].
`build-project-options`	String	No	Klocwork `kwbuildproject` command-line options.
`load-result-options`	String	No	Klocwork `kwadmin load` results command-line options.
`workspace-dir`	String	No	The file path of the code to be scanned.

For C/C++/.NET projects, since kwinject is used for building the specification file, the build-options parameter is mandatory. You must pass the appropriate build command with options. For example, if make is the build tool, the build-options should be specified like make targetName -j14 or similar build commands specific to your project configuration.

Outputs

Table 8. Output details
Output name	Data type	Description
`critical-count`	String	The number of Critical severity issues discovered during the scan.
`high-count`	String	The number of High severity issues discovered during the scan.
`medium-count`	String	The number of Medium severity issues discovered during the scan.
`low-count`	String	The number of Low severity issues discovered during the scan.
`total-issues`	String	The total number of issues discovered during the scan.

This action uses GitHub OIDC authentication to securely communicate with CloudBees Unify. Set permissions to id-token: write in your workflow.

Usage examples

In the following example, the Klocwork command reference provides detailed guidance on specifying build-options according to the build-tool used. For instance, if the build-tool is make, the build-options should include the build command and relevant flags, such as make targetName -j14, to ensure that kwinject can correctly generate the build specification file.

    permissions:
      id-token: write
      contents: read
    steps:
      - name: Scan with Perforce Klocwork SAST scanner
        uses: cloudbees-io-gha/perforce-klocwork-sast-publish@v1
        with:
          url: ${{ vars.KLOCWORK_URL }}
          token: ${{ secrets.KLOCWORK_APP_TOKEN }}
          license-host: ${{ vars.KLOCWORK_LICENSE }}
          username: ${{ vars.KLOCWORK_USERNAME }}
          project-name: test-c-project
          build-directory: /
          build-tool: make
          build-options:  make clean <target-name> --ignore-errors
          enable-agent-scan: false
          enable-local-scan: false▼

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:
  klocwork-scan-job:
    runs-on: ubuntu-latest
    steps:
      - name: Check out source code
        uses: actions/checkout@v2

      - id: klocwork-step
        name: Perforce Klocwork Scan
        uses: cloudbees-io-gha/perforce-klocwork-sast-publish@v1
        with:
          url: ${{ vars.KLOCWORK_URL }}
          token: ${{ secrets.KLOCWORK_APP_TOKEN }}
          license-host: ${{ vars.KLOCWORK_LICENSE }}
          username: ${{ vars.KLOCWORK_USERNAME }}
          project-name: test-c-project
          build-directory: /
          build-tool: make
          build-options:   make  clean <targetName> --ignore-errors
          enable-agent-scan: false
          enable-local-scan: true

      - 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-klocwork-step
        name: Print outputs from the upstream Perforce Klocwork Scan step
        run: |
          # Printing all outputs
          echo "Outputs from upstream Perforce Klocwork Scan step:"
          echo "Critical count: ${{ steps.klocwork-step.outputs.critical-count }}"
          echo "Very high count: ${{ steps.klocwork-step.outputs.very-high-count }}"
          echo "High count: ${{ steps.klocwork-step.outputs.high-count }}"
          echo "Medium count: ${{ steps.klocwork-step.outputs.medium-count }}"
          echo "Low count: ${{ steps.klocwork-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:
      klocwork-job-output-critical: ${{ steps.klocwork-step.outputs.critical-count }}
      klocwork-job-output-very-high: ${{ steps.klocwork-step.outputs.very-high-count }}
      klocwork-job-output-high: ${{ steps.klocwork-step.outputs.high-count }}
      klocwork-job-output-medium: ${{ steps.klocwork-step.outputs.medium-count }}
      klocwork-job-output-low: ${{ steps.klocwork-step.outputs.low-count }}
    steps:
      - name: Check out source code
        uses: actions/checkout@v2

      - id: klocwork-step
        name: Perforce Klocwork scan
        uses: cloudbees-io-gha/perforce-klocwork-sast-publish@v1
        with:
          url: ${{ vars.KLOCWORK_URL }}
          token: ${{ secrets.KLOCWORK_APP_TOKEN }}
          username: ${{ vars.KLOCWORK_USERNAME }}
          build-directory: path/to/work/directory
          build-tool: ${{ vars.KLOCWORK_BUILD_TOOL }}
          build-options: ${{ vars.KLOCWORK_BUILD_OPS }}

      - 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 Perforce Klocwork Scan job:"
          echo "Critical count: ${{ needs.job1.outputs.klocwork-job-output-critical }}"
          echo "Very high count: ${{ needs.job1.outputs.klocwork-job-output-very-high }}"
          echo "High count: ${{ needs.job1.outputs.klocwork-job-output-high }}"
          echo "Medium count: ${{ needs.job1.outputs.klocwork-job-output-medium }}"
          echo "Low count: ${{ needs.job1.outputs.klocwork-job-output-low }}"▼

Trivy scan

Use the trivy-scan-publish action to perform static application security testing (SAST) on a binary TAR file with the Trivy scanner, and then view comprehensive security results in CloudBees Unify. This action is available on the GitHub Marketplace.

This action uses GitHub OIDC authentication to securely communicate with CloudBees Unify. Set permissions to id-token: write in your workflow.

Inputs

Input name Data type Required? Description

binary-tar-path

String

Yes

The path of the binary to be scanned.

The binary file must be in the TAR format.

cloudbees-url

String

The CloudBees Unify URL. The default value is https://api.cloudbees.io.

license

Boolean

The option to perform license scanning. Specify license: true to perform license scanning.

Usage examples

The following is a basic example of using this action:

    permissions:
      id-token: write
      contents: read

    steps:
      - name: Trivy SAST scan
        uses: cloudbees-io-gha/trivy-scan-publish@v2
        with:
          binary-tar-path: example-tar-path.tar▼

In the following example, the license option is enabled to scan the binary for license files, and then output the risk to CloudBees Unify analytics dashboards. To learn more, refer to the Trivy license scanning documentation.

    permissions:
      id-token: write
      contents: read

    steps:
      - name: Trivy SAST scan
        uses: cloudbees-io-gha/trivy-scan-publish@v2
        with:
          binary-tar-path: example-tar-path.tar
          license: true▼

Scan with GitHub Actions

Black Duck SCA scan

How the scanner works

Inputs

Outputs

Usage examples

Coverity SAST scan

Inputs

Usage example

Gitleaks scan

Inputs

Usage example

Gosec scan

Inputs

Usage example

Grype scan

Inputs

Usage example

Perforce Klocwork SAST scan

How the scanner works

Inputs

Outputs

Usage examples

Trivy scan

Inputs

Usage examples

Related pages