---
name: devsecops-devsecops-configuring-zap-scans-v1
title: Configuring ZAP scans
description: Zed Attack Proxy (ZAP) is a free and open source penetration testing (PEN) tool that is maintained under the umbrella of OWASP. ZAP is a "man-in-the-middle" proxy that sits between the tester's web browser and a web server. ZAP intercepts packets, modifies the content if needed, and forwards those packets to the web server.
last-updated: 2026-02-17
---

> ## Documentation Index
> The table of contents for this documentation set is at https://cloud.ibm.com/docs/devsecops?format=markdown
> The index for all IBM Cloud docs is at: https://cloud.ibm.com/docs/llms.txt
> Use these files to discover more information as needed.

# Configuring ZAP scans
{: #cd-devsecops-zap-scans}

Zed Attack Proxy (ZAP) is a free and open source penetration testing (PEN) tool that is maintained under the umbrella of OWASP. ZAP is a "man-in-the-middle" proxy that sits between the tester's web browser and a web server. ZAP intercepts packets, modifies the content if needed, and forwards those packets to the web server.
{: shortdesc}

## ZAP scans execution
{: #zap-scans-execution}

You can create a specific script to start ZAP scans, like `trigger_zap_scans` inside your application repository, at a location of your choice, for example, inside a `scripts` directory and invoke this script in the `dynamic-scan` stage of the pipeline-config file.

You can customize the `trigger_zap_scans` script file to invoke the proper zap scan (api or ui) as described [here](https://cloud.ibm.com/docs/devsecops?topic=devsecops-cd-devsecops-zap-scans&format=markdown#zap-scan-results) and rely on [Common zap scan execution script](https://cloud.ibm.com/docs/devsecops?topic=devsecops-devsecops-common-scripts-revise&format=markdown) to run a ZAP scan (`ui` or `api`) to run penetration testing on your running app.

An alternate way is to execute zap scan(s) in a sub-pipeline as defined in the reference implementation, see [hello-compliance-app](https://us-south.git.cloud.ibm.com/open-toolchain/hello-compliance-app){: external}.

With this configuration in the pipeline config file, the `dynamic-scan` stage will invoke `trigger-async-zap.sh` script to trigger `owasp-zap` stage to initiate Zed Attack Proxy (ZAP) tool scanning in a dedicated sub-pipeline. It also rely on [Common zap scan execution script](https://cloud.ibm.com/docs/devsecops?topic=devsecops-devsecops-common-scripts-revise&format=markdown) to run a ZAP scan (`ui` or `api`) to run penetration testing on your running app.




## Available parameters for ZAP scans
{: #zap-parameters}

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

|Name |Type	|Description |Required or Optional |
|:----------|:------------------------------|:------------------|:----------|
|`cluster-name`|String|The name of the cluster where you want the zap scanner to be deployed and run from, if not running in DinD.| Required if not running in DinD, that is, `zap-dind` is set to `false`.|
|`ibmcloud-api`|String|Specifies the cloud environment for the ZAP cluster. Defaults to `https://cloud.ibm.com`|Required if not running in DinD, that is, `zap-dind` is set to `false`.|
|`ibmcloud-api-key`|String|API Key to deploy ZAP on a cluster.|Required if not running in DinD, that is, `zap-dind` is set to `false`.|
|`iam-token-endpoint`|String|The endpoint to retrieve the token for IAM authentication. Defaults to `https://iam.cloud.ibm.com/identity/token`|Optional, but if provided, `target-api-key` must also be provided.|
|`target-api-key`|String|API Key for IAM authentication.|Optional, but if provided, `iam-token-endpoint` must also be provided.|
|`target-application-server-url`|String|The base URL of the application server for zap to scan. It can be the same as the URL of the deployed application.|Required|
|`filter-options`|String|Set it to filter out alerts based on severity. Possible values: `Critical`, `High`, `Medium`, `Low`, `Informational`. Defaults to `Informational`, can be a comma-separated list.|Optional|
|`zap-custom-api-policy-file-path`|String|Relative path in the repository to the custom policy file(XML format) for ZAP API scans. If this is not set, the default policy `API-Minimal.policy` will be used.|Optional|
|`zap-custom-ui-policy-file-path`|String|Relative path in the repository for the custom policy file (XML format) used in ZAP UI scans. If this path is not set, the default policy `default.policy` will be used.|Optional|
|`zap-ui-scan`|String|Flag to determine whether the scan is the UI scan or the API scan. Possible values: `true`, `false`. Setting this flag to `true` runs the UI scan, setting it to false runs the API scan. This parameter works with `opt-in-dynamic-api-scan` and `opt-in-dynamic-ui-scan` parameters.|Required|
|`zap_dind`|String|Flag to switch between deploying ZAP to a cluster or running DinD. Default: `true`. Possible values: `true`, `false`. Setting it to `true` runs ZAP as DinD, setting it to `false` deploys ZAP to a cluster for which `cluster-name`, `ibmcloud-api`, and `ibmcloud-api-key` must be set.|Optional|
|`zap-dind-localhost`|String|Hostname for ZAP Scanners when running in DinD, default: `localhost`.|Optional|
|`zap-namespace`|String|Namespace to deploy ZAP API and UI scanners in the cluster, default: `zap`.|Optional for running ZAP in cluster, `Not required` for ZAP running in DinD.|
|`zap-polling-interval`|String|Interval for the scanners to poll ZAP for completion of the scanning, default: `120s`.|Optional|
|`zap-artifact`|String|The asset key for the artifact that is to be zap scanned and for which collect-evidence is to be invoked, The default value is `app-image`.|Optional|
|`zap_evidence_type`|String|The evidence type for evidence gathering for scans performed by ZAP, default: `com.ibm.dynamic_scan`.|Optional|
|`show-container-log`|String|Flag to enable or disable the container logging capability for the ZAP scanners when running in DinD, default: `false`.|Optional|
|`show-zap-log`|String|Flag to enable or disable ZAP server logging capability, default: `false`.|Optional|
{: caption="ZAP scan configuration parameters" caption-side="bottom"}

## Configuring ZAP API scans
{: #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.

|Name |Type	|Description |Required or Optional |
|:----------|:------------------------------|:------------------|:----------|
|`zap-api-custom-script`|String|Path to the file that contains the request transformation logic before initiating the ZAP API scan.|Required|
|`swagger-definition-files`|String|Path to the files that contain the Swagger definitions. Can be comma-separated list.|Required|
|`zap-api-port`|String|Port to run the ZAP API scanner when deployed to a cluster, default: `9086`.|Optional|
|`zap_api_deployment_name`|String|Name of the ZAP API scanner deployment, default: `zap-api-deployment`.|Optional|
|`zap-api-image`|String|Set this parameter to use a custom ZAP API Scanner image. Otherwise, the IBM default is used.|Optional|
|`flatten-zap-api-scan-report`|String|Set this parameter to `true` to flatten the ZAP API scan results into one single html and json file. Default `false`.|Optional|
{: caption="ZAP API configuration parameters" caption-side="bottom"}

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:

|Name |Type	|Description |Required or Optional |
|:----------|:------------------------------|:------------------|:----------|
|`excludeScanTypes`|Array|List of scans that the user wants to exclude. Complete list of scans to choose from: `CRLF_Injection`,`Buffer_Overflow`, `Directory_Browsing`, `External_Redirect`, `Format_String_Error`, `Parameter_Tampering`, `Remote_File_Inclusion`, `Script_Active_Scan`, `Server_Side_Code_Injection`, `Server_Side_Include`, `SQL_Injection`, `Xpath_Injection`, `XXE_External_Entity`, `SOAP_Action_Spoofing`, `SOAP_XML_Injection`, `Relative_Path_Confusion`, `Remote_OS_Command_Injection`, `ElmahScanRule` and, `HtAccessScanRule`.|Optional|
|`apisToScan`|Array|List of APIs to scan along with required params. If `"apisToScan": ["all"]` is mentioned, then all APIs mentioned in the swagger definition are scanned with mock data for mandatory parameters/body. To customize this array to have selective APIs to be scanned, use this substructure `apisToScan: [ { "path": "/path/to/endpoint", method: "get" } ]`.|Required|
|`globalExcludeUrls`|Array|Array of URL regexes to instruct ZAP not to scan for those routes. For example, `"globalExcludeUrls": [ "^http:\/\/foo.bar$", "^http:\/\/john.doe$" ]`.|Optional|
|`authenticationType`|String|Authentication mechanism for request headers. Supported auth mechanisms are `Bearer`, `Basic`, or `ApiKey`.|Optional|
|`apiKey`|String|If `authenticationType` is not sent, this API key is used for IAM authentication that is sent in Authorization header for all requests. If `authenticationType` is set to `Bearer`, the header that is formed is `Authorization: Bearer <apiKey>`. If `authenticationType` is set to `ApiKey`, the header that is formed is `Authorization: <apiKey>`. Field is ignored for `authenticationType` as `Basic`.|Optional|
|`username`|String|Username to be used for `authenticationType` `Basic`.|Required if `authenticationType` as `Basic`|
|`password`|String|Password to be used for `authenticationType` `Basic`.|Required if `authenticationType` as `Basic`|
{: caption="Parameters in the request payload" caption-side="bottom"}

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

## Configuring ZAP UI scans
{: #zap-ui-scans}

Set the `zap-ui-scan` parameter to `true` for ZAP UI scan to run.
{: note}

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

|Name |Type	|Description |Required or Optional |
|:----------|:------------------------------|:------------------|:----------|
|`zap-ui-custom-script`|String|Path to the file that contains the modification logic for the UI scan payload, if required, before the ZAP UI scan is initiated.|Optional|
|`zap-ui-script-directory`|String|Path to the directory that contains the UI tests and required files to run the UI scan.|Required|
|`context-file`|String|Path to a custom context file for UI scans provided to ZAP.|Optional|
|`zap-ui-auth-user`|String|User name to be used to authorize and run zap ui scan as. This requires `context-file` to be provided which should also contain the information of the way to authenticate this user.|Optional|
|`zap-ui-port`|String|Port to run the ZAP UI scanner when deployed to a cluster, default: `9085`.|Optional|
|`zap_ui_deployment_name`|String|Name of the ZAP UI scanner deployment, default: `zap-ui-deployment`.|Optional|
|`zap-proxy-service`|String|Name for the ZAP Proxy service required by the UI scanner, default: `zap-proxy-service`.|Optional|
|`zap-ui-image`|String|Set this parameter to use a custom ZAP UI Scanner image. Otherwise, the IBM default is used.|Optional|
|`zap-proxy-image`|String|Set this to use a custom ZAP Proxy image. Otherwise, the IBM default is used.|Optional|
{: caption="ZAP UI configuration parameters" caption-side="bottom"}

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](https://us-south.git.cloud.ibm.com/open-toolchain/hello-compliance-app){: external}.

## Managing ZAP Scan results
{: #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.

For instance, inside the `trigger_zap_scans` file, one can trigger individual scans based on the opt-in parameters as follows.

```bash
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](https://cloud.ibm.com/docs/devsecops?topic=devsecops-devsecops-common-scripts-revise&format=markdown).

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`.

```bash
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
```

## Configuring ZAP scan for CC pipeline
{: #zap-scan-for-cc}

The following table lists the additional parameters that are required to run ZAP scans inside the [CC pipeline](https://cloud.ibm.com/docs/devsecops?topic=devsecops-devsecops-cc-pipeline&format=markdown#devsecops-cc-pipeline-dynamic-scan).

|Name |Type	|Description |Required or Optional |
|:----------|:------------------------------|:------------------|:----------|
|`app-url`|String|URL of the deployed application on which the ZAP scan runs. Use the `staging` url of the application.|Required|
|`repo-url`|String|URL of the repository of the deployed application.|Optional, if `inventory repo` has all the artifacts from only one application repo.|
{: caption="ZAP parameters in the CC pipeline" caption-side="bottom"}

## Configuring Zap UI scans to use custom UI test images without zipping UI tests
{: #zap-ui-scan-custom}

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

|Name |Type	|Description |Required or Optional |
|:----------|:------------------------------|:------------------|:----------|
|`zap-custom-ui-deployment-name`|String|Custom UI docker container name.|Optional|
|`zap-custom-ui-docker-run-param`|String|Docker run parameters to run the custom UI image.|Optional|
|`zap-custom-ui-exit-code-ignored`|String|Zap UI exits with the custom UI exit code but its exit code will be ignored if this variable is set to `true`.|Optional|
|`zap-custom-ui-image`|String|Custom UI docker image that runs tests.|Required|
|`zap-custom-ui-post-script`|String|Script to be executed after running the custom UI image.|Optional|
|`zap-custom-ui-pre-script`|String|Script to be executed before running the custom UI image.|Optional|
|`zap-custom-ui-progress-script`|String| Script to be executed while running the custom UI image.|Optional|
|`zap-custom-ui-timeout-in-sec`|String|Zap UI scan exits after this time.|Optional|
{: caption="ZAP parameters in the CC pipeline" caption-side="bottom"}

This custom UI scan step is to use user's custom UI docker images for testing 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.