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

Prerequisites

Before you begin, ensure your environment meets these requirements:
  • Azure 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 Azure host / agent from the container:

    The application to be scanned must be accessible from the Azure 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 theAzure DevOps pipeline environment

There are three ways to prepare the environment:
  • Using the container image from HCL Software License Management Portal using the classic editor.
  • Using the container image from HCL Harbor using the classic editor.
  • Using the container image from HCL Harbor using a YAML configuration file.
To prepare the Azure DevOps Pipeline using the container image from HCL Software License Management Portaland the classic editor:
  1. Download the AppScan® Source CLI container to the Azure VM from HCL Software License Management Portal.
  2. Load the CLI container image using the docker load command.
  3. Inside Azure DevOps organization, create a new pipeline using classic editor. Click Use the classic editor.
  4. Select repository and branch where project to be scanned and CLI script is stored, and click Continue.
    1. Select Azure Repos Git as the source.
    2. Select Team project.
    3. Select the Repository.
  5. Select the Azure Agent pool where Azure VM configured with AppScan® Source CLI container is present.
  6. Add a new Docker task to load an image. Include these specifications:
    • Task Version: 0
    • Display Name: Specify a name or use the default.
    • Container Registry Type: Specify the registry type or use the default.
    • Docker Registry Service Connection: Specify a connection or use the default.
    • Action: Run a Docker command
    • Command: load -i /usr/user1/appscan-src-cli-10.2.0.tar.gz
  7. Add a new Docker task to run an image with these specifications:
    • Task Version: 1
    • Display Name: Specify a name or use the default.
    • Container Registry Type: Specify the registry type or use the default.
    • Docker Registry Service Connection: Specify a connection or use the default.
    • Command: run
    • Arguments: --rm
    • Image name: appscan/appscan-src-cli:10.2.0
    • Volumes: /usr/user1:/wa
    • Environment variables:
      • AS_INSTALL_MODE=standalone
      • AS_LICENSE_TYPE=CLS
      • AS_LICENSE_SERVER_ID=<the license server ID>
      • AS_LICENSE_SERVER=hclsoftware
    • Container command: script /wa/cli.script
  8. Add a new Docker task for clean-up with these specifications:
    • Task Version: 0
    • Display Name: Specify a name or use the default.
    • Container Registry Type: Specify the registry type or use the default.
    • Docker Registry Service Connection: Specify a connection or use the default.
    • Action: Run a Docker command
    • Command: rmi appscan/appscan-src-cli:10.2.0
To prepare the Azure DevOps Pipeline using the container image from HCL Harbor using the classic editor:
  1. Create a file (for example, env.list) containing the environment variables that must be made available to the CLI container during a scan. Include the following required information:

    • AS_INSTALL_MODE=standalone

    • AS_LICENSE_TYPE=CLS

    • AS_LICENSE_SERVER_ID=<the license server ID>

    A complete list of parameters can be found here.

  2. Inside Azure DevOps organization, create a new pipeline using classic editor. Click Use the classic editor.
  3. Select repository and branch where project to be scanned and CLI script is stored, and click Continue.
    1. Select Azure Repos Git as the source.
    2. Select Team project.
    3. Select the Repository.
  4. Select the Azure Agent pool where Azure VM configured with AppScan® Source CLI container is present.
  5. Add a new Docker task to run an image with these specifications:
    • Task Version: 2
    • Display Name: Specify a name or use the default.
    • Container Registry: Specify the registry type or use the default.
    • Action: Run a Docker command
    • Command: run
    • Arguments: --rm --env-file /usr/user1/env.list -v $(Agent.BuildDirectory)/s:/wa hclcr.io/appscan/appscan-src-cli:10.2.0 script /wa/cli.script
  6. Add a new Docker task for clean-up with these specifications:
    • Task Version: 0
    • Display Name: Specify a name or use the default.
    • Container Registry Type: Specify the registry type or use the default.
    • Docker Registry Service Connection: Specify the registry type or use the default.
    • Action: Run a Docker command
    • Command: rmi appscan/appscan-src-cli:10.2.0

To prepare the Azure DevOps Pipeline using the container image from HCL Harbor using YAML

Use the following sample script as a guide to run a static analysis scan using a AppScan Source CLI container from HCL Harbor.

# Starter pipeline
# Start with a minimal pipeline that you can customize to build and deploy your code.
# Add steps that build, run tests, deploy, and more:
# https://aka.ms/yaml

trigger:
- main

pool:
  name: Ubuntu-VM-pool
  #vmImage: ubuntu-latest

#steps:
#- script: echo Hello, world!
#  displayName: 'Run a one-line script'

steps:
- task: CmdLine@2
  inputs:
    script: |
- task: Docker@1
  displayName: 'Run an image'
  inputs:
    containerregistrytype: 'Container Registry'
    dockerRegistryEndpoint: 'MyConnection’
    command: 'Run an image'
    arguments: '--rm'
    imageName: 'hclcr.io/appscan/appscan-src-cli:10.2.0 '
    volumes: '$(Agent.WorkFolder)<path to downloaded source files>:/wa'
    envVars: |
     AS_INSTALL_MODE=standalone
     AS_LICENSE_TYPE=CLS
     AS_LICENSE_SERVER_ID=<specify the license server ID>
     AS_LICENSE_SERVER=<specify the license server name>
    containerCommand: 'script /wa/cli.script'
    runInBackground: false
- task: Docker@0
  displayName: Clean
  inputs:
    containerregistrytype: 'Container Registry'
    dockerRegistryConnection: 'MyConnection'
    action: 'Run a Docker command'
    customCommand: ' rmi hclcr.io/appscan/appscan-src-cli:10.2.0'

Initiate a static analysis scan using the container image

To initiate the scan using the pipline:

  1. In Azure, make sure Azure VM in Azure Agent pool is online.
  2. From Pipelines page, select the pipeline to run.
  3. Select Run pipeline to start the static analysis scan.