Configuring scan automation with Jenkins 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 Jenkins, 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 runtime environment
  3. Initiate the scan from the container image

Prerequisites

Before you begin, ensure your environment meets these requirements:
  • Jenkins environment, including one more Linux agents/hosts 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 in a Jenkins pipeline.

  • Access to content on the Jenkins host / agent from the container:

    The application to be scanned must be accessible from the Jenkins host running the scan.

    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 Jenkins host/agent.

    For example, if the application is accessible at root path /usr/user1/SampleApp on the Jenkins host/agent, 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 Jenkins host/agent.

    For example, the application is accessible at path /usr/user1/SampleApp on the Jenkins host/agent.

  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 Jenkins host/agent

To prepare the runtime environment on the Jenkins host/agent:
  1. Download the AppScan® Source CLI container to the Jenkins 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 file (for example, env.list) containing a list of environment variables that must be made available to the CLI container during a scan. Some of the required information includes:
    AS_INSTALL_MODE=standalone
AS_LICENSE_TYPE=CLS
AS_LICENSE_SERVER_ID=<specify the license server ID>
    A complete list of parameters can be found here.

Initiate a static analysis scan using the container image

Initate the scan in one of two ways:

Initiate a scan using container image from HCL Harbor

Run the scan using a Linux shell command or the Docker Linux plugin:
  • Linux
    Incorporate the following shell command into a Jenkins pipeline to scan the SampleApp. Note that /usr/user1 on the Jenkins host/agent is mapped to cvol in the container. Adjust the version string based on the desired version of the CLI container. 
    sh "docker run --rm --volume /usr/user1:/cvol --env-file /cvol/SampleApp/ env.list hclcr.io/appscan/appscan-src-cli:10.1.0 script /cvol/SampleApp/SampleApp.script
  • Docker Jenkins plugin
    Incorporate the following Docker Jenkins plugin API into a Jenkins pipeline to scan the SampleApp. Note that /usr/user1 on the Jenkins host/agent is mapped to cvol in the container. Adjust the version string based on the desired version of the CLI container.
    docker.image('hclcr.io/appscan/appscan-src-cli:10.1.0').run('--name container-SampleApp --rm –-volume /usr/user1:/cvol --env-file /cvol/SampleApp/env.list script /cvol/SampleApp/SampleApp.script')

sh "docker logs --follow container-SampleApp"

Initiate a scan using the container image from HCL Software License Management Portal

The AppScan® Source CLI container image is available in HCL Software License Management Portal in archive format (tar.gz). The container image must be loaded prior to use to scan.
  1. Download the container image to the Jenkins host/agent. For example, /appscansrc/appscan-src-cli-10.1.0.tar.gz.

    The container image must be loaded prior to use.

  2. Run the scan using a Linux shell command or the Docker Linux plugin:
    • Linux
      Incorporate the following shell command into a Jenkins pipeline to scan the SampleApp. Note that /usr/user1 on the Jenkins host/agent is mapped to cvol in the container. Adjust the version string based on the desired version of the CLI container. 
      docker load -i /appscansrc/appscan-src-cli-10.1.0.tar.gz

sh "docker run --rm --env-file /cvol/SampleApp/env.list --volume /usr/user1:/cvol appscansrc/appscan-src-cli:10.1.0 script /cvol/SampleApp/cli.script"
    • Docker Jenkins plugin
      Incorporate the following Docker Jenkins plugin API into a Jenkins pipeline to scan the SampleApp. Note that /usr/user1 on the Jenkins host/agent is mapped to cvol in the container. Adjust the version string based on the desired version of the CLI container.
      docker.image(‘appscan-src-cli:10.1.0').run('--name container-SampleApp --rm –-volume /usr/user1:/cvol --env-file /cvol/SampleApp/env.list script /cvol/SampleApp/SampleApp.script')

sh "docker logs --follow container-SampleApp"