October 6, 2020

How to Integrate ZAP with Jenkins: A Step by Step Guide

Let's start by understanding why we want to integrate ZAP with Jenkins in the first place. You're probably here because you want to improve your application security while it's still in the pipeline. In a Rapid Application Development Cycle, whenever a new version or feature of the product is being released, security teams (for the most part) had to manually initiate DAST tools to find security vulnerabilities in the release. This was obviously non-scalable and extremely time consuming especially with strict short release sprints. More so, when the product in question mandates high security impetus.

Thankfully, a number of tools exist that can make a good portion of this process automatic. While this may not replace an actual person physically attempting to crack your application, it will reduce the time that person spends handling the tedious day-to-day vulnerability attacks.

OWASP’s Zed Attack Proxy (ZAP) is one of the most widely used application security scanners. The following manual describes the short steps involved in integrating the OWASP ZAP plugin with Jenkins - the world's favourite CI / CD platform.

In this blog, we walk you through integrating ZAP with a Jenkins pipeline, enabling you to trigger ZAP for every build. We’ve kept it very simple, so if some of the steps seem like a no-brainer to you, please ignore it and move along to the subsequent steps.

Note: Words in orange refer to the actual options/menu items displayed on Jenkins or ZAP.

Integrate ZAP with Jenkins in 15 Easy Steps

STEP 1: ZAP Jenkins Plugin

To integrate ZAP with Jenkins, you’ll first need the ZAP Jenkins plugin. You can get that under Manage Jenkins -> Manage Plugins. Install OWASP ZAP Official plugin under Available Tab.

Downloading ZAP plugin

Image: Download ZAP plugin

STEP 2: Installing ZAP Locally

In addition to the plugin, you’ll also need to install ZAP in your local machine. If you already have ZAP, you can skip this step.

Under Manage Jenkins -> Global Tool Configuration, click on Custom Tool installation. Under Custom tool Section; provide OWASP ZAP tar downloadable link and the directory name. (The actual download will happen in step 7, so don’t worry about it right now)

Note: If you do not have the Custom Tool Installation option, you need to download a plugin called “Custom Tool Installation”. To get that, follow the same process as in Step 1

installing ZAP

Image: Install ZAP

STEP 3: Running ZAP on Jenkins

By now, you should have ZAP and its plugin. Moving forward, you’ll need to configure two essential things; namely ZAP host and port. Go to Manage Jenkins -> Configure System and fill the ZAP HOST and Port field under ZAP section.

configuring ZAP

Image: Configure ZAP host and port

Ok, now let’s go ahead and create a “job” on Jenkins to run ZAP.

STEP 4: Create New Project

Click New Item and create a new Job as Freestyle Project. Click OK

creating a new jenkins job

Image: Create a new Jenkins job

Next step is to create a workspace folder in master machine. Follow the steps 5 & 6

STEP 5: Save Project

Click Save without making any configuration changes for the Job.

Creating a new job without making configuration changes

Image: Creating a new job without making configuration changes

STEP 6: Create Workspace

Now, click Build Now to create a workspace on the master machine.

Creating a workspace on the master machine.

Image: Creating a workspace on the master machine.

Voila! We are now ready to configure ZAP as a part of the job. If you had ZAP before reading this blog, you can skip step 7. As mentioned earlier, this part does the actual downloading of ZAP to your system.

STEP 7: Configure ZAP

Go to ZAP Project Configure Page. In my case, it would be under ZAP_CI_Demo project. Click Configure | Select Build Environment. Check the Install Custom Tools option, and select the ZAP tool.

Downloading ZAP through Jenkins

Image : Downloading ZAP through Jenkins

Next step in the integration process is to trigger-start ZAP during the build process.

STEP 8: Execute ZAP

Select Build Tab under project configurations | Click Add build step | Select Execute ZAP

Setting a trigger for ZAP

Image : Setting a trigger for ZAP

To let Jenkins know how to start ZAP and where to locate ZAP installed directory, follow step 9.1 or 9.2 based on if you had ZAP before this blog or not.

STEP 9.1: Installing ZAP

If you had ZAP before this blog, move to step 9.2

Use the Installation Method option to specify how ZAP will be installed on the master machine and specify the absolute location of the ZAP Home Directory where would you like to create, or you can specify .ZAP as relative path for ZAP Home Directory. It will automatically create the .ZAP folder on the Jenkins Custom Tools Directory (/var/lib/jenkins/tools/../.ZAP/)

Note: If you specified custom path for ZAP Home Directory, make sure Jenkins has the needed permission to create a directory on the specified path. For Example: If the Jenkins user does not have permission to create directory on /home/ , you'll have to create the directory manually and change the owner of the folder to the Jenkins user.

Specifying home directory path

Image: Specifying home directory path

STEP 9.2: Find ZAP Installation Directory

If you already had ZAP, select the “System Installed: ZAP Installation Directory” option, and let the environment variable input remain default.

Now, to specify the ZAP installed path for the environment variable (ZAPROXY_HOME).

9.2.1: Go to Manage Jenkins -> Configure System and Select Environment variable checkbox under Global Properties. Click Add

9.2.2: Enter the name as ZAPROXY_HOME and give the value as ZAP installed path. In this example, it would be the path /opt/zaproxy. Save the changes.

Specifying build environment

Image : Specifying build environment

Then continue with your ZAP Configuration. Under ZAP Home Directory, provide the path along with “.ZAP”. (ZAP Home Directory is already created while running the ZAP for the first time in your local machine. In this example it would be /home/umar/.ZAP)


Image : Providing the testing application/URL information for scans

STEP 10: Testing

So far, you’ve connected ZAP with Jenkins and configured it such that ZAP is triggered during the build process. Now, you need to provide information on application or URL that needs testing. This part is still done under BUILD tab.

10.1: For that, you would need to create Persist session in ZAP under Session Management section.

10.2: Next, you’ll need to provide application name and URL under Session Properties Options in regex format. Under the Include in Context, supply the URL. Under the Exclude in Context, you should provide the parameter that does not need an active scan or spidering.

For Example:

Include in Context: http://testphp.vulnweb.com

where Testphp.vulnweb.com is the Target Application and * indicates all paths across the application

Exclude from Context (optional): ^(?:(?!http://testphp.vulnweb.com).*).$



Image: Session Management

In the above example, we’ve provided a URL for testing in the Include in Context input field. In the Exclude in Context field, we’ve provided a regex that will exclude everything that is not within the scope.

Alright! Let’s take a breath and see what we’ve achieved. So far, you’ve downloaded the required plugins, connected ZAP to Jenkins, set ZAP to trigger during build, and provided the testing session details. Now, you need to configure the scan policies and spidering of the application, because the goal of this integration is to scan the application with specific to certain scanning policies.

STEP 11: Attack Mode

Under the Attack Mode section of the build tab, enter the URL in Starting Point field for spidering the application, and select Spider scan option. Let the rest under this section remain default. Enable Active Scan checkbox and select the Policy from the dropdown list. If you don’t have any options in the dropdown list, which will be the case if it’s your first time running ZAP, it will consider the Default Policy for the active scan.

Configuring the scan policies per your testing requirements

Image: Configuring the scan policies per your testing requirements

Next step is to generate reports from the scans.

STEP 12: Generate Report

Tick Generate Report check box and provide all information to generate report in HTML and XML Format. You need to give a unique filename for every iteration of scans. Example: Consider filename as


JENKINS_ZAP_VULNERABILITY_REPORT_ : This is a constant prefix

${BUILD_ID}  : This is the Jenkins Environment variable, which is always unique for on the current build.

Generating reports

Image: Generating reports

Next, you need to archive the reports and logs generated by ZAP for every iteration of scans.

STEP 13: Post-build Actions

Under Post-build Actions:

13.1: Click Add Post-Build Action, and select Archive the artifacts. In the input field under the Archive the Artifacts, add the following directories, which should be separated by commas. (You can copy paste it from below as is)


13.2: click Add Post-Build Action, and select Publish HTML Reports. Then, click Add, and input the directory where the HTML reports are stored. Under the Index page input field, specify the file’s name as used in step 12, along with extension .html. In this example, use


Archiving reports

Image: Archiving reports

STEP 14: Complete Build

Click on Save and Click Build Now. Once build is completed, you can view the HTML Report on Job Dashboard and other archived files from workspace.


Image : Options to viewing archived reports.

Finally, let’s look at an example pipeline workflow with ZAP integrated as part of the mainstream pipeline          

Demo CI/CD Pipeline flow example

    Image : Demo CI/CD Pipeline flow example

In the above image, blue arrows indicate the flow of pipeline, and numbers indicate the build process.

  1. Developer makes a new commit to the code repository.
  2. Assuming that the Github repository is already integrated with Jenkins CI service using a Jenkins Webhook, this will trigger the Github Checkout Build process.
  3. Once the Github Checkout Build is completed, it will initiate the ZAP build process to automate the DAST scan against deployed Environment.
  4. ZAP scan results will then be archived in Jenkins and pushed to Orchestron (in this case) for result correlation.
  5. Application Security Engineer & Developer can automatically raise ticket in Jira using results from Orchestron.

With that in perspective, follow the next steps to finish up the integration.

STEP 15: Build Triggers

Go to ZAP Project, click Configure and select Build trigger tab. Under the Build Trigger section, select one of the option which preferable for the CI/CD Pipeline.

In our case, use the ‘Build after other projects are built’ checkbox option and enter the Project to watch field. It will trigger the ZAP Job after that project build process is completed.

You need to select your conditional statement that is suitable for the project which you are watching.

  • Trigger only if build is stable
  • Trigger even if the build is unstable
  • Trigger even if the build fails
Integrate ZAP with Jenkins

    Image: Build Trigger

Make sure to save the changes.

Now, you have successfully integrated ZAP with your Jenkins pipeline. The ZAP Build process will run continuously along with your existing CI Pipeline whenever a new commit made on the Github repository.

You're all set!

Learn more about our entire AppSec testing process here.