Configuring scan automation with GitHub Action and containers

The HCL® AppScan® Source command line interface (CLI) container, available from HCL Harbor and HCL Software License Management Portal, can be used to automate static analysis scans with GitHub, and without installing a full instance of AppScan® Source.

The main steps for scanning using a container are:

Prepare the application.
Prepare the GitHub Action using the container image from HCL Software License Management Portal.
Initiate the scan using GitHub Action.

Prerequisites

Before you begin, ensure your environment meets these requirements:

GitHub Action environment: One or more Linux RHEL 7.9-based GitHub Action runner with Docker installed.
This is the system that is targeted to run a static analysis scan using the CLI container.
A valid license for AppScan® Source for Automation and relevant license server information.
AppScan® Source CLI container image

Download the AppScan® Source CLI container image from HCL Harbor or HCL Software License Management Portal. With a valid license, your HCL ID grants access to these locations.
AppScan® Source CLI script

A script is required for scanning with the container using GitHub Action.
AppScan® Source project (.ppf) and application (.paf) files: Use AppScan® Source for Analysis to generate the configuration files (requires an AppScan® Source installation on a Linux system that has access to the scan target).
Access to content on the GitHub Action from the container:
- The application to be scanned should be present in GitHub and accessible from the GitHub Action running the scan.
- The .paf/.ppf files
Note: Volume mapping (mapping path on the container host to a path in the container) is used for this purpose during instantiation of a scan.

Prepare the application to be scanned

Prepare the application for scanning using either:

.paf/.ppf files
folder scanning

Prepare the application to be scanned using paf/ppf files

Generate the .paf/.ppf file using the HCL® AppScan® Source for Analysis client on a Linux system that has AppScan® Source installed.
Ensure that the .paf and .ppf files are located at the root of the application to be scanned.
Ensure that the application files and the paf/ppf files are accessible from the GitHub Action runners.
For example, if the application is accessible at root path /usr/user1/SampleApp, the .paf/.ppf files are located at /usr/user1/SampleApp/SampleApp.paf and /usr/user1/SampleApp/SampleApp.ppf.
Volume mapping is required to allow the container to access the application files on the host/agent system. Determine the name of the volume as seen by the container.
For example, map /usr/user1 on the host to cvol in the container.
Note: The volume mapping is specified when running the CLI in the container.
Create the CLI script. For example, SampleApp.script in /usr/user1/SampleApp.
For this example, the script tells the container to access the application content using the cvol path. The commands listed are those used with the AppScan® Source CLI (Scanning without manual intervention).
```
login …
oa /cvol/SampleApp/SampleAll.ppf
scan
…
logout
```

Prepare the application for folder scan:

Ensure that the application files are accessible from the GitHub Action runners.
For example, the application is accessible at path /usr/user1/SampleApp on tthe GitHub Action runners.
Determine the name of the volume as seen by the container.
For example, map /usr/user1 on the host to cvol in the container.
Note: The volume mapping is specified when running the CLI in the container.
Create the CLI script. For example, SampleApp.script in /usr/user1/SampleApp.
```
login …
oa /cvol/SampleApp/SampleAll.ppf
scan
…
logout
```

Prepare the GitHub Action using the CLI container image

To prepare the runtime environment on the GitHub Action :

Download the AppScan® Source CLI container to the GitHub host from HCL Software License Management Portal or access directly from HCL Harbor.
Load the CLI container image using the docker load command if downloaded from HCL Software License Management Portal.

Create a yaml script file to run static analysis scan using AppScan® Source CLI container from HCL Harbor and place it in the appropriate branch. For example:

# This is a basic workflow to help you get started with Actions

name: CI

# Controls when the workflow will run
on:
  # Triggers the workflow on push or pull request events but only for the development branch
  push:
    <name of the branch used for running SAST scan>
  pull_request:
        <name of the branch used for running SAST scan>

  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:

# A workflow run is made up of one or more jobs that can run sequentially or in parallel
jobs:
  # This workflow contains a single job called "build"
  SAST_SCAN:
    # The type of runner that the job will run on , here we used a self-hosted runner
    runs-on: [ self-hosted ]

    # Steps represent a sequence of tasks that will be executed as part of the job
    steps:
      # Checks-out your repository under $GITHUB_WORKSPACE, so our job can access it
      - uses: actions/checkout@v2
      
       # Displays current working path
      - name: Display current workspace
        run: echo $GITHUB_WORKSPACE
        
.
      - name: Docker cleanup
        run : docker system prune -a -f
     
      - name: Docker run
        run : docker run --rm --env-file $GITHUB_WORKSPACE/env.list -v $GITHUB_WORKSPACE/:/wa  hclcr.io/appscan/appscan-src-cli:10.1.0 script /wa/CLI.script
      - name: Docker cleanup
        run : docker system prune -a -f
      - name: Success
        run: echo Scan completed successfully.

Initiate a static analysis scan using the GitHub Action runners

To run a static analysis scan:

Make sure GitHub Action runner is online.
If the runner is self-hosted, manually execute a run script downloaded from GitHub.
In GitHub, select Actions > Run workflow to start a static analysis scan using the .yaml script present in the branch.