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.
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.
Image: Download ZAP plugin
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
Image: Install ZAP
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.
Image: Configure ZAP host and port
Ok, now let’s go ahead and create a “job” on Jenkins to run ZAP.
Click New Item and create a new Job as Freestyle Project. Click OK
Image: Create a new Jenkins job
Next step is to create a workspace folder in master machine. Follow the steps 5 & 6
Click Save without making any configuration changes for the Job.
Image: Creating a new job without making configuration changes
Now, click Build Now to create 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.
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.
Image : Downloading ZAP through Jenkins
Next step in the integration process is to trigger-start ZAP during the build process.
Select Build Tab under project configurations | Click Add build step | Select Execute 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.
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.
Image: Specifying home directory path
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.
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
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.
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.
Image: Configuring the scan policies per your testing requirements
Next step is to generate reports from the scans.
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_${BUILD_ID}
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.
Image: Generating reports
Next, you need to archive the reports and logs generated by ZAP for every iteration of scans.
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)
logs/*,reports/*
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
JENKINS_ZAP_VULNERABILITY_REPORT_${BUILD_ID}.html
Image: Archiving reports
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
Image : Demo CI/CD Pipeline flow example
In the above image, blue arrows indicate the flow of pipeline, and numbers indicate the build process.
With that in perspective, follow the next steps to finish up the integration.
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.
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.
