This is a Jenkins pipeline plugin that lets you control OWASP ZAP through Jenkins Pipeline. Unlike other plugins for ZAP, this generates a report which shows new alerts compared to the last build, has the ability to fail a build with configurable failure parameters, filters out false positives and displays a graph which shows the amount of ZAP alerts over your builds.
pipeline {
agent any
stages {
stage('Setup') {
steps {
script {
startZap(host: 127.0.0.1, port: 9091, timeout:500, zapHome: "/opt/zaproxy", sessionPath:"/somewhere/session.session", allowedHosts:['github.com']) // Start ZAP at /opt/zaproxy/zap.sh, allowing scans on github.com
}
}
}
stage('Build & Test') {
steps {
script {
sh "mvn verify -Dhttp.proxyHost=127.0.0.1 -Dhttp.proxyPort=9091 -Dhttps.proxyHost=127.0.0.1 -Dhttps.proxyPort=9091" // Proxy tests through ZAP
}
}
}
}
post {
always {
script {
archiveZap(failAllAlerts: 1, failHighAlerts: 0, failMediumAlerts: 0, failLowAlerts: 0, falsePositivesFilePath: "zapFalsePositives.json")
}
}
}
}This example is a declarative pipeline, but using the functions on a scripted pipeline works the same.
startZap - Starts the ZAP process and configures the plugin.
startZap(host: 127.0.0.1, port: 9095, timeout: 900, failHighAlert:1, failLowAlert:10, zapHome: "/opt/zaproxy", allowedHosts:['10.0.0.1'], sessionPath:"/path/to/session.session")
host: The host to run the ZAP proxy server on. Passed to ZAP in the -host parameter.
port: The port to run the proxy on
timeout (optional): If a scan takes too long it will stop
failAllBuild (optional): Maximum amount of alerts that can happen in total before a build will fail
failHighBuild (optional): Maximum amount of high risk alerts that can happen before a build will fail
failMediumBuild (optional): Maximum amount of medium risk alerts that can happen before a build will fail
failLowBuild (optional): Maximum amount of low risk alerts that can happen before a build will fail
allowedHosts (optional): Once the active ZAP scan starts, it won't scan any hosts unless they are here. If you don't set this it will only scan if the host is localhost
sessionPath (optional): If you want to load a previous ZAP session that you have expored, you can do that here. Useful when you want to run a scan but don't want to run all your tests through ZAP.runZapCrawler - Runs the ZAP crawler on a specific URL
runZapCrawler(host: "https://localhost")importZapScanPolicy - Loads a specific ZAP attack policy from the path you specify (Scan Policy Manager -> Export), to be used with runZapAttack
importZapScanPolicy(policyPath: "/home/you/yourattackpolicy.policy")importZapUrls - Imports a list of URLs to ZAP. You need the "Import files containing URLs" plugin for this to work.
importZapUrls(path: "/path/to/your/urls")runZapAttack - Once you have proxied your tests through ZAP or ran the crawler, this function runs an active scan on all the hosts that have been provided in the allowedHosts parameter in startZap.
runZapAttack(userId: 5, scanPolicyName: "yourScanPolicy")
userId (optional): Run the scan with a specific user, loaded from the session
scanPolicyName (optional): The attack policy to use when running the scan. Loaded with importScanPolicyarchiveZap - Reads the alerts found by ZAP, filters out any false positives if a false positives file is provided in the project, checks if there are any alerts that are higher than the fail build parameters (and fails the build if so), generates a report, and finally shuts down ZAP. This should be the last thing you run.
archiveZap(failAllAlerts: 1, failHighAlerts: 0, failMediumAlerts: 0, failLowAlerts: 0, falsePositivesFilePath: "zapFalsePositives.json")sh "mvn verify -Dhttp.proxyHost=127.0.0.1 -Dhttp.proxyPort=9095 -Dhttps.proxyHost=127.0.0.1 -Dhttps.proxyPort=9095"You may need to exclude some hosts from the proxy. If so 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's impossible to proxy just localhost without editing project code. You can mitigate this by changing your applications host to localhost.localdomain, which isn't checked by Java (NOTE: not all OS's have this hostname as a loopback address by default, you may need to add it to your machine's 'hosts' file).
You can provide a JSON file of false positive definitions from your workspace to the zap plugin during the archive step (the default is zapFalsePositives.json). The file must consist of a single valid JSON array of false positive objects. Example:
[
{
"name": "Cross Site Scripting (Reflected)",
"cweid": "79",
"wascid": "8",
"uri": "https:\/\/yourdomain.com\/a\/certain\/url",
"method": "POST",
"param": "param1",
"attack": "<script>alert(1);</script>",
"evidence": "<script>alert(1);</script>"
},
{
"uri": "https:\/\/yourdomain.com\/another/url",
"method": "GET"
}
]All alert instances that match to a false positive object are ignored when judging whether to fail a build, and are initially hidden in the UI report. A match is when ALL fields provided in the False Positive object are equal to that in a given alert instance. It is best practice to be as specific as possible (to not hide future true positives that may occur).
To aid the generation of a false positives file, the UI report provides a 'Copy To Clipboard' button under each instance, that copies the alert instance as JSON, which can be used as a false positive object in the false positive file.
The false positive URI is a regex string, alert instance URIs will be tested against this.
Download the latest release from the releases section. In Jenkins, go to 'Manage Jenkins' -> 'Manage Plugins', and select the 'Advanced' tab. Then under 'Upload Plugin', choose the downloaded hpi file and click upload.
The MIT License (MIT)
Copyright (c) 2018 Manolis Vrondakis
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.