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.
- Prepare the application.
- Prepare the GitHub Action using the container image from HCL Software License Management Portal.
- Initiate the scan using GitHub Action.
Prerequisites
- 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
.paf
/.ppf
files- folder scanning
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 tocvol
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 thecvol
path. The commands listed are those used with the AppScan® Source CLI (Scanning without manual intervention).login … oa /cvol/SampleApp/SampleAll.ppf scan … logout
- 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 tocvol
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
- 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
- Make sure GitHub Action runner is online.
If the runner is self-hosted, manually execute a run script downloaded from GitHub.
- In GitHub, select
.yaml
script present in the branch.
to start a static analysis scan using the