Fortify on Demand GitHub Actions

Use the GitHub Action Runner Emulation plugin to integrate OpenText Fortify static code analysis into a GitHub Actions workflow. Set up actions to scan your code with Fortify on Demand, capture security issues into a SARIF file, and export the file to PulseUno to be converted into findings.

Note: The GitHub Action Runner Emulation plugin is provided as a technical preview.

Overview

With the GitHub Action Runner Emulation plugin, you can set up a workflow to analyze your source code with Fortify on Demand, produce and export a SARIF results file, and generate findings from it.

The workflow includes the following actions:

  1. Fortify ScanCentral Scan.

    GitHub Action: fortify/gha-setup-scancentral-client@v2.0

    Downloads and uses the Fortify ScanCentral SAST client to build a project from fetched sources and package the project into package.zip.

  2. Fortify on Demand Scan.

    GitHub Action: fortify/gha-setup-fod-uploader@v1

    Downloads and runs the FoDUploader utility to upload the package to Fortify on Demand, trigger a Fortify ScanCentral SAST scan, and wait for the scan to finish.

  3. Export Fortify vulnerability data.

    GitHub Action: fortify/gha-export-vulnerabilities@v1

    Produces a SARIF output file and exports the file from Fortify on Demand to the agent's workspace to be converted into findings.

For details about these actions, visit the GitHub Marketplace.

Tip: You can create your own workflows using other GitHub Actions for Fortify.

Back to top

Prerequisites

Before you can configure and run a chain with Fortify on Demand GitHub Actions, prepare your environment.

Prepare your PulseUno environment:

  1. In PulseUno, create a space named fortify. For details, see Create spaces.

  2. In the fortify space, create the following mirror repositories that sync with the corresponding GitHub repositories containing GitHub Actions:

    Mirror in PulseUno Corresponding repository on GitHub
    gha-setup-scancentral-client fortify/gha-setup-scancentral-client.git
    gha-setup-fod-uploader fortify/gha-setup-fod-uploader.git
    gha-export-vulnerabilities fortify/gha-export-vulnerabilities.git

    Set the mirrors to public access. For details, see Mirror a Git repository.

Prepare your PulseUno agent:

  • Download the Node 16 and Node 20 binaries and extract them in the following locations on the agent:

    • <agent-data-directory>/externals/node16

    • <agent-data-directory>/externals/node20

    If the externals directory doesn't exist, create it manually.

    Caution: To ensure seamless chain runs, avoid using symbolic links.

  • Windows agents: To avoid potential errors when running actions, use PowerShell 7.x or later.

Prepare the Fortify on Demand environment:

  • In your Fortify on Demand tenant, create an application. Within the application, create a release. This release is where your packaged project is uploaded and scanned. You need the release ID for the GitHub Actions workflow.

  • If the Fortify ScanCentral SAST Controller accepts authorized clients only, obtain the client authentication token for the Controller. The token is stored as the client_auth_token property in the config.properties file on the Controller. You need the token to download and use the Fortify ScanCentral SAST client.

  • Create a personal access token (PAT). You need the PAT to authenticate to the Fortify on Demand API and run the FoDUploader utility.

  • Verify that your Fortify on Demand account has the Start Static Scan permission for uploading code.

For details about these tasks, see the Fortify on Demand and Fortify ScanCentral SAST documentation.

Back to top

Configure Fortify on Demand actions

Use the GitHub Action Runner Emulation plugin to set up the Fortify on Demand GitHub Actions workflow.

To configure the Fortify on Demand GitHub Actions workflow:

  1. Add the GitHub Action Runner Emulation step to a chain, as described in Create chains.

  2. (Optional) Rename the plugin step.

  3. From the Mode list, select YAML.

  4. In the YAML box, enter the YAML definition of the steps to run:

    Copy code 
    steps:

    # The following command performs these tasks:
    # - Downloads, extracts, and caches the specified version of the Fortify ScanCentral SAST client zip file.
    # - Adds the Fortify ScanCentral SAST client's bin directory to the path.

          - name: Download Fortify ScanCentral Client
            uses: fortify/gha-setup-scancentral-client@v2.0
            with:
              version: 22.1.0
              client-auth-token: "ScanCentral_client-auth-token"                
              # You need to provide the client authentication token for the ScanCentral Controller only if the Controller requires client authentication. 
          - run: scancentral package -bt none -o package.zip

    # The following command performs these tasks:
    # - Downloads and caches the specified version of the FoDUploader tool (FoDUpload.jar).
    # - Adds the FOD_UPLOAD_JAR environment variable containing the full path to the FoDUpload.jar file.

          - name: Download Fortify on Demand Universal CI Tool
            uses: fortify/gha-setup-fod-uploader@v1
          - name: Perform SAST Scan
            run: java -jar $FOD_UPLOAD_JAR -z package.zip -aurl $FOD_API_URL -purl $FOD_URL -rid "$FOD_RELEASE_ID" -tc "$FOD_TENANT" -uc "$FOD_USER" "$FOD_PAT" $FOD_UPLOADER_OPTS -n "$FOD_UPLOADER_NOTES"
            env:
              FOD_TENANT: "FoD_tenant_name"
              FOD_USER: "FoD_username"
              FOD_PAT: "FoD_personal_access_token"
              FOD_RELEASE_ID: "123456"
              FOD_URL: "https://ams.fortify.com"
              FOD_API_URL: "https://api.ams.fortify.com"
              FOD_UPLOADER_OPTS: "-ep 2 -pp 0 -I 1 -apf"
              FOD_UPLOADER_NOTES: "Triggered by PulsUno GitHub Actions"

    # The following command performs these tasks:
    # - Exports Fortify vulnerability data from Fortify on Demand and generates SARIF output.
    # - Downloads the SARIF file (gh-fortify-sast.sarif) to the PulseUno agent and generates findings from the file.

          - name: Export Results
            uses: fortify/gha-export-vulnerabilities@v1
            with:
              FOD_BASE_URL: "https://ams.fortify.com"
              FOD_TENANT: "FoD_tenant_name"
              FOD_USER: "FoD_username"
              FOD_PASSWORD: "FoD_password"
              FOD_RELEASE_ID: "123456"

    # The following command generates findings from the SARIF file (gh-fortify-sast.sarif).
    # The GITHUB_SARIF environment variable specifies the file path to the SARIF file on the agent.

          - run: 
              echo $GITHUB_SARIF
              cp ./gh-fortify-sast.sarif $GITHUB_SARIF

    Caution: If the scan generates multiple SARIF files, you must use the SARIF file parser plugin to convert them into findings.

    For details about the variables used in this workflow, and the syntax for referencing them, see Environment variables.

  5. (Optional) Set the rest of the plugin options. For details, see GitHub Action Runner Emulation.

  6. Save the chain.

Back to top

Environment variables

The Fortify on Demand actions workflow uses the following environment variables:

Variable Description
FOD_TENANT Specifies your tenant ID in Fortify on Demand. For example, PulseUno.
FOD_USER Specifies the username to authenticate to the Fortify on Demand tenant.
FOD_PAT Specifies the personal access token to authenticate to the Fortify on Demand API.
FOD_PASSWORD Specifies the password to authenticate to the Fortify on Demand tenant.
FOD_RELEASE_ID Specifies the Fortify on Demand release ID.

FOD_URL

FOD_BASE_URL

Specifies the URL of the Fortify on Demand portal, for example:

https://ams.fortify.com

FOD_API_URL

Specifies the Fortify on Demand API root URL, for example:

https://api.ams.fortify.com

The API root URL is determined by your tenant's data center. For a list of data center API root URLs, see the Fortify on Demand User Guide.
FOD_UPLOAD_JAR

Specifies the location of the FoDUploader file, FoDUpload.jar.

FoDUploader is a Java utility for uploading code to Fortify on Demand.
FOD_UPLOADER_OPTS

Specifies the FoDUploader arguments.

For example, use the following arguments for the FoDUploader polling option to wait for scan completion:

-ep 2 -pp 0 -I 1 -apf

where:

-ep 2 Uses the Automated audit preference for the Fortify on Demand release.
-pp 0 Does not allow to start a new scan if another scan is in progress.
-I 1 Polls for scan status every minute.
-apf If the scan fails the security policy of the release, allows the scan to exit with a code of 0 (success).

For details about the FoDUploader arguments, see the Fortify on Demand User Guide.
FOD_UPLOADER_NOTES Specifies additional information about the action.
GITHUB_SARIF

Specifies the SARIF file path on the agent after the file has been exported from Fortify on Demand. The file path is predefined and cannot be changed.

PulseUno uses the file on this path to generate findings.

Use the following syntax for referencing environment variables in shell scripts:

Windows agents (PowerShell syntax)

If a variable's value doesn't contain spaces, use this syntax:

$env:VAR_NAME

If a variable's value contains spaces, use this syntax:

$env.VAR_NAME.split()

For example, to reference the following variable:

FOD_UPLOADER_OPTS: "-ep 2 -pp 0 -I 1 -apf"

use this syntax:

$env.FOD_UPLOADER_OPTS.split()

Linux agents (Bash syntax) $VAR_NAME

Back to top

See also: