Perforce Klocwork scan and publish to CloudBees Unify

Use this action to analyze the source code for security vulnerabilities and quality defects using the Perforce Klocwork Static Application Security Testing (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.

For background on how the scanner works and the difference between explicit and implicit scans, refer to Understanding Perforce Klocwork 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
`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 2. 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. Be sure to set permissions to id-token: write in your workflow.

Usage examples

The following is a basic example of using this action:

In the following example, the Klocwork command reference provides detailed guidance on specifying build-options according to the build-tool used. For example, if the build-tool is make, the build-options must 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▼

Using the action output

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

Full workflow and run example

The following GHA workflow example scans a repository with Perforce Klocwork SAST scanner.

Example GHA workflow YAML file

name: Perforce Klocwork scan

on:
  push:
    branches:
     - klocwork-test

permissions:
  id-token: write
  contents: read

jobs:
  klocwork-codescan:
    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:

      # Checkout code
      - name: Checkout repository code
        uses: actions/checkout@v4

      # Print run info
      - name: Print run info
        shell: bash
        run: |
          echo "Ref name is $GITHUB_RUN_ID"
          echo "Source is ${{ github.server_url }}/${{ github.repository }}"
          echo "Subject is $GITHUB_WORKFLOW_REF|${{ github.run_id }}|${{ github.run_attempt }}|${{ github.run_number }}"
          echo "Job is $GITHUB_JOB"

      # Run Klocwork scan
      - name: Klocwork scan
        id: klocwork-step
        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 }}"▼

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

When the respective artifact is deployed to an application environment, Klocwork findings are also displayed in the Security center and the Security overview for the application.

Understanding Perforce Klocwork scanning in GitHub Actions