Configuring scan automation with GitLab CI/CD and containers

The HCL® AppScan® Source command line interface (CLI) container, available from HCL Harbor and HCL FlexNet Operations portal (FNO), can be used to automate static analysis scans with GitLab, and without installing a full instance of AppScan® Source.

The main steps for scanning using a container are:
  1. Prepare the application.
  2. Prepare the GitLab CI/CD using the container image from HCL FNO.
  3. Initiate the scan using GitLab CI/CD runners.

Prerequisites

Before you begin, ensure your environment meets these requirements:
  • GitLab CI/CD environment: One or more Linux RHEL 7.9-based GitLab CI/CD runners 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 FNO. 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 GitLab CI/CD.

  • 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 GitLab CI/CD runners from the container:
    • The application to be scanned should be present in GitLab and accessible from the GitLab CI/CD runners 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
  1. 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.

  2. Ensure that the application files and the paf/ppf files are accessible from the GitLab CI/CD runners.

    For example, if the application is accessible at root path /usr/user1/SampleApp on the GitLab CI/CD runners, the paf/ppf files are located at /usr/user1/SampleApp/SampleApp.paf and /usr/user1/SampleApp/SampleApp.ppf.

  3. 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.
  4. 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:
  1. Ensure that the application files are accessible from the GitLab CI/CD runners.

    For example, the application is accessible at path /usr/user1/SampleApp on tthe GitLab CI/CD runners.

  2. 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.
  3. Create the CLI script. For example, SampleApp.script in /usr/user1/SampleApp.
    login …
oa /cvol/SampleApp/SampleAll.ppf
scan
…
logout

Prepare the runtime environment on the GitLab CI/CD runners

To prepare the runtime environment on the GitLab CI/CD runners:
  1. Download the AppScan® Source CLI container to the GitLab host from HCL FNO or access directly from HCL Harbor.

    Load the CLI container image using the docker load command if downloaded from HCL FNO.

  2. Create a yaml script file to run static analysis scan using AppScan® Source CLI container from HCL Harbor. For example:
    # This is a basic workflow to help you get started with GitLab CI/CD 

variables: 
    GIT_STRATEGY: clone 

build-job: 
    stage: build 
    script: 
        - echo "Hello, $GITLAB_USER_LOGIN!" 
        - chmod -R 777 $CI_PROJECT_DIR 
        - docker run --rm --env-file $CI_PROJECT_DIR/env.list -v $CI_PROJECT_DIR/:/wa hclcr.io/appscan/appscan-src-cli:10.3.0 script /wa/CLI_jspWIKI.script 
        - echo "Success, Scan complete" 
        - rm -vrf $CI_PROJECT_DIR 
        - echo "Clean up done"

Initiate a static analysis scan using the GitLab CI/CD runner

To initate the static analysis scan:
  1. Make sure GitLab CI/CD runner is online. In GitLab, select Admin > >Runners to verify status.
  2. Select Admin > Joba to start a static analysis scan using the .yaml script present in the branch.