OWASP ZAP is one of the world's most popular free security tools, it can help you automatically find security vulnerabilities in your web applications. This plugin allows you to control ZAP in Jenkins pipeline builds, and also adds additional functionality like the ability to fail a build if a certain amount of alerts are found, a graph, and much more! It is recommended you proxy your tests through ZAP for maximum coverage, but you can also import a list of URLs to scan or load a session to attack.
- Gives you full control over ZAP through Pipeline, including starting ZAP, running the crawler, running an attack, importing a list of URLs, importing scan policies, loading a session & user, ect.
- Generates a graph showing amount of ZAP alerts over builds
- Generates an interactive report (viewable after ZAP has run through the sidebar button). This report incorporates the results of the previous build to show you new alerts, automatically filters out false-positives, and more!
- Ability to fail builds if a certain amount of high/medium/low alerts are found
- Allows you to provide a false positive file
- Support for distributed builds
- Supports Windows & Linux
- Simple & easy to use
- Go to the Jenkins Dashboard
- Click on "Manage Jenkins" in the sidebar
- Click on "Manage Plugins"
- Press the "Available" tab next to the "Updates" tab
- Search for "zap pipeline" and select the checkbox, then press "Download now and install after restart"
- Tick the "Restart Jenkins when installation is complete and no jobs are running" check box
How to use
The plugin provides additional functions for you to use in your Jenkinsfile. An example of a declarative pipeline is below, the functions work the same on a scripted pipeline. See the API below for more information.
Listed below are functions that you can use in your Jenkinsfile.
Proxying your tests
You may need to exclude some hosts from ZAP. If so you can use the -Dhttp.nonProxyHosts parameter, eg -Dhttp.nonProxyHosts=.com\|.co.uk
By default Java will not proxy localhost, 127.0.0.1, or any common loopback addresses. There is no way to disable this unless you set -Dhttp.nonProxyHosts= (empty). This means it is impossible to proxy just localhost without editing project code. You can mitigate this issue by changing your applications host to localhost.localdomain, which isn't checked by Java. An alternative to this is to edit your machines 'hosts' file and add your own local hostname.
Generating a false positives file
You can provide a JSON file of false positive definitions from your workspace to the plugin during the archive step. The default filename is zapFalsePositives.json. The file must consist of a JSON array of false positive objects. For example:
All alert instances that match to a false positive object are ignored when the plugin decided whether to fail your build or not, and are initially hidden in the UI report. A match is when ALL fields provided in the false positive object are equal to an alert instance. It is best practice to be as specific as possible to not hide true positives that may occur. The false positive URI is a regex string, alert instance URIs will be tested against this, it is useful to use if you have a dynamic path.
To aid in the generation of a false positives file, the UI report provides a 'Copy to Clipboard' button under each instance. This copies the alert instance as JSON, which can be used as a false positive object in the false positives file.
1.9.0 (14th January 2019)
Fixed start-up error on certain networks
1.8.0 (9th January 2019)
Added export as XML and export as JSON buttons to the report.
Stopped spamming the console with scan progress messages
1.5.1 (31st October 2018)
Lowered minimum required Jenkins version from 2.7.3 to 2.121.1
1.5.0 (23rd October 2018)
Added 32 unit and integration tests.
ImportZapUrls fails the build if you do not provide the path parameter or if the file failed to load.
RunZapCrawler no longer provides a default host to start the crawler on and will fail if you do not provide the host parameter.
If zapHome in startZap is not set the build will now fail, instead of carrying on silently.
Changed "Zap alert instances" to "Alert instances" on the chart, so the text is larger. Additionally, the chart now counts the alert instances rather than the number of alerts (bug)
Improved the UI report.
1.4.1 (15th October 2018)
Fixed archiving, general bug fixes and code improvements. If you were using a previous version before this the report view button will be lost on your old builds due to naming changes.
1.4 (9th October 2018)
Instead of comparing alerts to the previous build, you can now provide a false positives file in your projects, and alerts will be filtered using this file.
There is now a graph that displays on the Jenkins job page that shows you the amount of alert instances over your builds.
Previously, it was impossible to know that the build failed due to ZAP without checking the build console. There is now text on the build page which makes that clear.
The plugin was renamed since the previous version, remember to uninstall zap-comp.hpi so you don't have it installed twice.
1.2.0 (14th September 2018)
You can now have multiple nodes running at once
1.1.0 (12th September 2018)
Added support for Windows
1.0.0 (11th September 2018)