README.md

Deprecation Notice

This GitHub Action has been deprecated and will no longer be maintained as of December 31st, 2023. Similar functionality is now available through the consolidated fortify/github-action and its sub-actions; please update your GitHub workflows to use these actions instead.

Setup Fortify ScanCentral Client

Build secure software fast with Fortify. Fortify offers end-to-end application security solutions with the flexibility of testing on-premises and on-demand to scale and cover the entire software development lifecycle. With Fortify, find security issues early and fix at the speed of DevOps. This GitHub Action sets up the Fortify ScanCentral Client to integrate Static Application Security Testing (SAST) into your GitHub workflows. This action:

• Downloads, extracts and caches the specified version of the Fortify ScanCentral Client zip file
• Adds the Fortify ScanCentral Client bin-directory to the path

Usage

The following example illustrates how to invoke ScanCentral Client from within a GitHub workflow:

name: Fortify ScanCentral SAST Scan
on:
  workflow_dispatch:
  push:
    # Master or main branch that you want to trigger this workflow for
    branches: [master]
  pull_request:
    # The branches below must be a subset of the branches above
    branches: [master]

jobs:                                                  
  Fortify-SAST:
    # Use the appropriate runner for building your source code
    runs-on: ubuntu-latest 

    steps:
      # Check out source code
      - name: Check Out Source Code
        uses: actions/checkout@v2
        with:
          # Fetch at least the immediate parents so that if this is a pull request then we can checkout the head.
          fetch-depth: 2
      # If this run was triggered by a pull request event, then checkout the head of the pull request instead of the merge commit.
      - run: git checkout HEAD^2
        if: ${{ github.event_name == 'pull_request' }} 

      # Java is required to run ScanCentral Client, and may be required for your build
      # Java version to use depends on the Java version required to run your build (if any),
      # and the Java version supported by the ScanCentral Client version that you are running
      - name: Setup Java
        uses: actions/setup-java@v1
        with:
          java-version: 11

      ### Set up Fortify ScanCentral Client ###
      - name: Download Fortify ScanCentral Client
        uses: fortify/gha-setup-scancentral-client@v1   
        with:
          version: 23.1.0                                      # On-prem customers should specify a client version that matches their ScanCentral environment
                                                               # FoD customers usually should not specify a version but rather rely on the default version
          client-auth-token: ${{ secrets.CLIENT_AUTH_TOKEN }}  # Optional, but required if ScanCentral Controller requires client authentication

      ### Run Fortify ScanCentral Client ###
      # Update BUILD_OPTS based on the ScanCentral Client documentation and your project's included tech stack(s).
      #   ScanCentral Client will download dependencies for maven, gradle and msbuild projects.
      #   For other build tools, add your build commands to the workflow to download necessary dependencies and prepare according to Fortify SCA documentation.
      - name: Perform SAST Scan
        run: scancentral -url ${SC_CONTROLLER_URL} start $BUILD_OPTS -upload -application $APPLICATION -version $VERSION -uptoken $SSC_UPLOAD_TOKEN
        env:                                            
          SC_CONTROLLER_URL: ${{ secrets.SC_CONTROLLER_URL }}
          SSC_UPLOAD_TOKEN: ${{ secrets.SSC_UPLOAD_TOKEN }}
          APPLICATION: "My Application"
          VERSION: "1.0"
          BUILD_OPTS: "-bt mvn"

      ### Archive ScanCentral Client logs on failure ###
      - name: Save ScanCentral Logs
        uses: actions/upload-artifact@v2                
        if: failure()
        with:
           name: scancentral-logs
           path: ~/.fortify/scancentral/log

This example workflow demonstrates the use of the fortify/gha-setup-scancentral-client action to set up ScanCentral Client, and then invoking ScanCentral Client similar to how you would manually run this command from a command line. You can run any available client action like start or package, and even invoke the other commands shipped with ScanCentral Client like pwtool. Please see the ScanCentral documentation for details. All potentially sensitive data should be stored in the GitHub secrets storage.

Following are the most common use cases for this GitHub Action:

• Start a SAST scan on a ScanCentral environment; note that the ScanCentral Controller must be accessible from the GitHub Runner where the workflow is running.
• Start a scan on Fortify on Demand (FoD), utilizing ScanCentral Client for packaging only; see https://github.com/fortify/gha-setup-fod-uploader for details

Additional Considerations

• In order to utilize the ScanCentral Client for packaging .NET code, you will need to modify the sample workflow to utilize a Windows runner. Windows-based runners use different syntax and different file locations. In particular:
  • Environment variables are referenced as $Env:var instead of $var, for example "$Env:URL" instead of $URL
  • ScanCentral logs are stored in a different location, so the upload-artifact step would need to be adjusted accordingly if you wish to archive ScanCentral logs
• Be sure to consider the appropriate event triggers for your project and branching strategy
• If you are not already a Fortify customer, check out our Free Trial

Inputs

version

Optional The version of the Fortify ScanCentral Client to be set up. At the time of writing, the following versions are available:

• 23.1.0 (default if not specified)
• 22.2.1
• 22.1.2
• 21.2.3

If you plan on using ScanCentral Client just for packaging your source code to be submitted to Fortify on Demand, it is recommended to not specify this input in your workflow, in order to rely on the default/latest version.

If you plan on using ScanCentral Client to submit scan requests to a ScanCentral environment, the ScanCentral Client version should match the versions of your ScanCentral Controller and Sensors as closely as possible. As such it is recommended to explicitly specify the ScanCentral Client version to be used rather than relying on the default version installed by this GitHub Action, as the default version may change in future versions of this Github Action. Please see the ScanCentral documentation for exact version requirements.

client-auth-token

Optional Client authentication token to pass to ScanCentral Controller. Required if ScanCentral Controller accepts authorized clients only.

Information for Developers

All commits to the main or master branch should follow the Conventional Commits convention. In particular, commits using the feat: Some feature and fix: Some fix convention are used to automatically manage version numbers and for updating the CHANGELOG.md file.

Whenever changes are pushed to the main or master branch, the .github/workflows/publish-release.yml workflow will be triggered. If there have been any commits with the feat: or fix: prefixes, the release-please-action will generate a pull request with the appropriate changes to the CHANGELOG.md file and version number in package.json. If there is already an existing pull request, based on earlier feature or fix commits, the pull request will be updated.

Once the pull request is accepted, the release-please-action will publish the new release to the GitHub Releases page and tag it with the appropriate v{major}.{minor}.{patch} tag. The two richardsimko/update-tag action instances referenced in the publish-release.yml workflow will create or update the appropriate v{major}.{minor} and v{major} tags, allowing users to reference the action by major, minor or patch version.