Configuring ZAP scans

Available parameters for ZAP scans

Create a file trigger_zap_scans inside your application repository, at a location of your choice, for example, inside a scripts directory.

Set the values for the corresponding parameters by adding these lines to the trigger_zap_scans as follows - set_env <parameter name> <value>. For more information about a reference implementation, see hello-compliance-app.

You can set and customize the following parameters to configure ZAP scans to run penetration testing on your running app.

Configuring ZAP API scans

Inside your application repository, you must have at least one API definition file present, in json format. This API definition file needs to be a valid swagger or openapi definition. These files can be present at any location inside the application repository, for example, inside a definitions directory. For clarity, these files are referred to as follows: definitions1.json, definitions2.json, and so on.

More parameters are required for configuring ZAP API scans. These parameters can be set by adding the following lines to the trigger_zap_scans as follows - set_env <parameter name> <value>.

Create a file custom-api-script inside your application repository, at a location of your choice, for example, inside scripts/zap-custom-scripts directory. This file can be named differently too, and set the path to this file against the zap-api-custom-script parameter.

Use the file custom-api-script to modify the request that goes into the ZAP scanner. The parameters that can be used in the request payload are as follows:

For sensitive information like credentials, you must read these values from a vault or a secret store.

Configuring ZAP UI scans

Similar to configuring ZAP API scans, create or update the file trigger_zap_scans inside your application repository, at a location of your choice, for example, inside a scripts directory.

Set the values for the corresponding parameters by adding these lines to the trigger_zap_scans as follows - set_env <parameter name> <value>. For more information about a reference implementation, see hello-compliance-app.

Set the zap-ui-scan parameter to true for ZAP UI scan to run.

Parameters that are required for configuring ZAP UI scans are as follows.

Create a folder uiscripts inside the scripts/zap directory inside your application repository. Also set this folder path against zap-ui-script-directory in the trigger_zap_scans file. This folder can be created anywhere else, too. The path should be adjusted for zap-ui-script-directory.

Create a file run.sh inside the uiscripts directory. run.sh drives the UI tests. We can configure Protractor-based tests or any other suitable framework.

Create a file export.sh inside the uiscripts directory. This file holds all the different environment variables that are required for the test framework to use. Set those environment values by adding export <VARIABLE_NAME>=<VALUE>.

To hold any configuration information for the test framework, create a folder conf inside the uiscripts directory to house configuration information for the test framework.

For a reference implementation that uses Protractor as the test framework, see hello-compliance-app.

Managing ZAP Scan results

Based on the value of the parameters opt-in-dynamic-api-scan and opt-in-dynamic-ui-scan, we can choose to selectively run either the API scan or the UI scan or both.

Inside the trigger_zap_scans file, we can trigger individual scans based on the opt-in parameters as follows.

if [ -n "$(get_env opt-in-dynamic-api-scan "")" ]; then
    # start the api scan
    set_env "zap-ui-scan" "false"
    source "${COMMONS_PATH}"/owasp-zap/run_scan.sh
fi

if [ -n "$(get_env opt-in-dynamic-ui-scan "")" ]; then
    # set for zap-ui-scans and start zap-ui-scan
    set_env "zap-ui-scan" "true"
    source "${COMMONS_PATH}"/owasp-zap/run_scan.sh
fi

The COMMONS_PATH refers to a location that holds the build scripts and run scripts for various tools that are a part of the DevSecOps pipeline. For more information, see Common scripts.

You can compute the success of the ZAP scan by setting an exit code based on whether the API scan or the UI scan was run. Any vulnerabilities found are also reported. This can be checked by tapping into the variables api-scan-result and ui-scan-result.

The possible values that these parameters can take are success or failure, and defaults to notRun.

ZAP_API_RESULT=$(get_env api-scan-result "notRun")
ZAP_UI_RESULT=$(get_env ui-scan-result "notRun")

if [[ "${ZAP_API_RESULT}" =~ ^(success|notRun)$ && "${ZAP_UI_RESULT}" =~ ^(success|notRun)$ ]]; then
   exit 0
else
   exit 1
fi

A sample implementation can be found in the trigger_zap_scans file inside the scripts/zap directory inside this repository.

Configuring ZAP scan for CC pipeline

The following table lists the additional parameters that are required to run ZAP scans inside the CC pipeline.

Configuring Zap UI scans to use custom UI test images without zipping UI tests

The following table lists the additional parameters that are required to configure ZAP UI scans to use custom UI test images.

This custom UI scan step is to use user's custom UI docker images for tesing zap UI scans, instead of putting the docker image information in zip file which is the default case zap-custom-ui-image is required environment variable to be set for configuring ZAP UI scans to use custom UI test images.