AppScan SAST Readme

Thank you for your interest in our AppScan SAST Agent Technology Preview. This preview showcases a new approach to static analysis in HCL AppScan.

Before you get started with this Technology Preview, please note the following:
  • The code and other artefacts are a technical preview of work in progress.
  • This piece of technology should not be used in production systems. It is meant for testing and demonstration purposes only.
  • This solution is Non-Warranted and will be not supported through the normal HCL AppScan Support channels. For assistance, questions or feedback, please reach out directly to florin.coada@hcl.com.
  • This package can be removed at any time, without prior notice.
  • This readme file includes a series of instructions on installing this technical preview and generating scan results compatible with AppScan Source 10.0.4

Introduction

AppScan SAST allows users to perform source code scans using Docker containers. Users can create new scan engines in the form of containers, thus allowing users to perform scans in parallel. The Docker host machine mush have sufficient resources for running parallel scans.

System Requirements

  • A supported LINUX version (RHEL 7.x) to install AppScan Source 10.0.4 version
  • Docker, to host Docker images and containers

Limitations

AppScan SAST containers can be created and scans run only on Linux. Windows is not supported for this Technical Preview release.

Prepare Docker Host machine

Prepare the machine to run AppScan SAST in containers:
  1. Install AppScan Source 10.0.4.
  2. Create a group and a user account with name appscan. This user will perform scans in the container. The same user account is used to create the Docker image and containers.
    Note: Add the user to the docker group to execute Docker commands. For example: 
    groupadd appscan && useradd appscan -m -s "/bin/bash" -G appscan,docker -d /home/appscan
  3. Download and extract the AppScan SAST bundle (AppScanSAST.tar.gz) under the AppScan Source installation path (for example, /opt/ibm/appscansource/AppScanSAST/) as user appscan.

Build SAST agent as Docker image

  1. 1. Open a terminal as appscan user.
  2. Navigate to <source_install_path>/AppScanSAST/bin.
  3. Execute create_image.sh
    A Docker image with tag name hcl/appscan/sast_agent:10.0.4 is created. 
    # docker images
REPOSITORY				TAG	   IMAGE ID		
hcl/appscan/sast_agent		  10.0.4	e2bef18f718c	…
registry.access.redhat.com/ubi7/ubi   7.9	   063b2549dde7	…
…
    Note: In addition to creating the Docker image, this script also creates a file with name SAClientUtil.10.0.4.tar.gzin the current folder. This utility can be used to generate an IRX file for the given source code to be scanned.

Create Docker container(s)

Once the SAST agent Docker image is created, use the image to create one or more containers to perform SAST scans as needed. For example:
# docker run -d -P hcl/appscan/sast_agent:10.0.4
6d72d8ca8cb23b022b20e2fdc0f6619a7d70196bece14b1ffa77ea926473c4c5

# docker ps -a
CONTAINER ID        IMAGE                           … PORTS
6d72d8ca8cb2        hcl/appscan/sast_agent:10.0.4   … 0.0.0.0:32701->8080/tcp
…
Note: The option -P maps the container’s services port to a dynamic port on the Docker host machine. which can be accessed from anywhere in the current network. In the example, the services default port 8080 is mapped to a dynamic port 32701 on the host machine. The service which runs on the container can be accessed using http://<hostmachine>:32701. Any number of containers can be created and accessed individually through the mapped ports.

Perform SAST scans using REST API services

The following REST APIs are exposed through the AppScan SAST containers and can be used to perform SAST scans. Swagger-UI can be accessed using http://<hostname>:<port>/swagger-ui/index.html.

API Description

FileUpload

/api/v2/FileUpload

Upload an IRX file to be scanned. To generate an IRX file, use the utility that is generated during Docker image creation (SAClientUtil.10.0.4.tar.gz).

Returns a file-id on successful upload which can then be used to execute the scan.

Scans

/api/v2/Scans/StaticAnalyzer

Execute the SAST scan using the uploaded IRX file-id.

Returns scan-id once the scan is triggered, which can then be used to fetch the scan status or download assessment.

Scans

/api/v2/Scans/{Id}		 Fetch the scan status for a given scan-id.

Scans

/api/v2/Scans/Assessment/Download/{Id}

Download the scan assessment for a given scan-id. Use this API once the scan is completed.

Note: Assessment will not include IFA excluded findings.

Refer to the Swagger-UI for more details on the APIs.

IRX file creation

To generate an IRX file, use the utility that is generated during Docker image creation (SAClientUtil.10.0.4.tar.gz). Refer https://help.hcltechsw.com/appscan/ASoC/src_irx_gen_config.html to create IRX file through command line.

Before creating the IRX file, the following environment variable should be set: 

export APPSCAN_OPTS=”-DNO_ENCRYPT -DUSE_STAGER=false”