One of the easiest ways to enhance ZAP is to write new passive scan rules.
Passive scan rules are used to warn the user of potential vulnerabilities that can be detected passively - they are not allowed to make any new requests or manipulate the requests or responses in any way.
They typically run against all of the requests and responses that flow through ZAP.
Passive rules run in separate background thread so that they have as little effect on performance as possible.
You can write passive scan rules dynamically using scripts, as we will see later in this series, but even then it's very useful to understand some of the concepts and the underlying classes available to you.
Where to start
The easiest way to get started is to rip off an existing rule. The passive scan rules can be found in 3 add-ons in the zap-extensions project, depending on their status:
- Release quality: addOns/pscanrules
- Beta quality: addOns/pscanrulesBeta
- Alpha quality: addOns/pscanrulesAlpha
There are also some simple examples that we will examine in more detail. These are all in the
The main classes
The following classes are key to implementing passive scan rules.
PluginPassiveScanner - this is
the class that all passive rules must extend. There are 2 key methods that you will need to implement:
scanHttpRequestSend(HttpMessage msg, int id)- This is called for every request. All details of the request are available via the
msgparameter, as detailed below.
scanHttpResponseReceive(HttpMessage msg, int id, Source source)- This is called for every response. All details of the request and response are available via the
msgparameter, as detailed below. The response is also available as a DOM structure via the
You can implement one or both of these methods depending on your requirements. You can examine any part of the request and response in order to find potential vulnerabilities, but you must not change anything.
If you find a potential vulnerability then you can raise it via the method:
PassiveScanThread.raiseAlert(int id, Alert alert)
HttpMessage is passed in to both of the
scan methods. This class has methods that allow you to access all aspects of the request and response, although the latter is obviously only
scanHttpResponseReceive. Some examples include:
Source parameter is passed into
this is a DOM representation of the response generated by the Jericho HTML parser. See the Jericho
documentation or the other scan rules for examples of how to access DOM elements.
Alert class is used to represent
potential vulnerabilities. It supports the following fields:
pluginIdUsed to identify the scanner, especially useful via the ZAP API
nameThe summary displayed to the user
riskAn indication of how serious the issue is:
Alert.RISK_INFOInformational (it's not really a vulnerability)
Alert.RISK_LOWA low risk vulnerability
Alert.RISK_MEDIUMA medium risk vulnerability
Alert.RISK_HIGHA high risk vulnerability
confidenceAn indication of how likely this is a real problem:
Alert.CONFIDENCE_FALSE_POSITIVEShould not be used - this is for the user to set
Alert.CONFIDENCE_LOWA lower level of confidence
Alert.CONFIDENCE_MEDIUMA medium level of confidence
Alert.CONFIDENCE_HIGHA higher level of confidence
Alert.CONFIDENCE_USER_CONFIRMEDShould not be used - this is for the user to set
descriptionA more detailed description
uriThe URI affected
paramThe name of the vulnerable parameter, if relevant
attackThe attack string used (not relevant for passive vulnerabilities)
otherInfoInformation that doesn't readily fit into any of the other fields
solutionInformation about how to prevent the vulnerability
referenceA list of URLs giving more information about this type of vulnerability (separated by newline characters)
evidenceA string present in the request or response which can be used as evidence of the vulnerability - this will be highlighted when the related request or response is displayed
cweIdThe CWE id
wascIdThe WASC Threat Classification id
ExampleSimplePassiveScanRule class implements a very simple passive
scan rule. As you will see, it just raises an alert randomly, so it isn't of any practical use. However it does demonstrate a couple of useful
It uses the
Vulnerabilities class to get the
name, description, solution and references. This class loads vulnerability details from the
vulnerabilities.xml files included with ZAP. There are actually
a set of
vulnerabilities.xml files as it is internationalized, so ZAP will read the localized version for the language the user has selected,
defaulting back to English for any phrases that have not been translated. This is therefore a quick and easy way to fill in these details, as
long as the relevant vulnerability is included in that file.
It also uses the Log4j 2
Logger class to output debug messages. This is the recommended way of outputting such
Note that the
pluginId needs to be unique across all active and passive scan rules. The master list of ids is in the
File based example
ExampleFilePassiveScanRule class implements a
slightly more complex passive scan rule. In this case it reads in a set of strings from a configuration file and checks for their presence in
the response. It could also use hardcoded strings, but the advantage of the approach taken is that a knowledgeable user could manually edit the
file to meet their requirement.
(ZAP automatically extracts the files located in the
zapHomeFiles directory into a directory underneath the ZAP user directory.)
This class also demonstrates a couple of other features:
Instead of using the
Vulnerabilities class the code uses
Constant.messages.getString(str). All of the strings used in this way are defined in the
Messages.properties file. If you are just implementing the rule
for your own benefit then you can hardcode the strings if you want, but internationalizing them is very simple and saves having to go back and
change your code if you want to have your rule included in the ZAP Marketplace.
The code also makes use of the
getAlertThreshold() method. This returns an
AlertThreshold which indicates how strictly you should check for
vulnerabilities. The threshold returned can be one of:
LOW: This indicates you should report more potential vulnerabilities, which might mean more false positives
MEDIUM: This is the default level
HIGH: This indicates you should report fewer potential vulnerabilities, which might mean more false negatives
You do not have to use the threshold - especially as it might not be relevant for the vulnerability you are testing for, but it is also a useful way for the user to tune how the rules work and so it's worth using if you can.
Building and deploying
The alpha passive active scan rules add-on build file is addOns/pscanrulesAlpha/pscanrulesAlpha.gradle.kts. All you need to do is run the Gradle task
:addOns:pscanrulesAlpha:copyZapAddOn in the
zap-extensions project and the relevant add-on will be built and copied to the correct location, assuming you have a ZAP core project called
zaproxy. If you want to deploy to a different location then you can use the command line argument
Updating the help
To finish off a new rule you should add a short description of the rule to the help file: pscanalpha.html
This is not really necessary unless you want to publish your rules.
A future post will cover how to contribute your code back to the ZAP community and progress it from alpha to beta and then release status.