The ZAP code must conform to standard formatting rules - if any changes do not conform then they will fail the build.
This document gives an overview of the automatic and manual components provided by OWASP Zed Attack Proxy (ZAP) that are recommended for testing each of the OWASP Top Ten Project 2021 risks.
For the previous Top Ten see ZAPping the OWASP Top 10 (2017)
Note that the OWASP Top Ten Project risks cover a wide range of underlying vulnerabilities, some of which are not really possible to test for in a completely automated way. If a completely automated tool claims to protect you against the full OWASP Top Ten then you can be sure they are being ‘economical with the truth’!
ZAP stores its session data in an HSQLDB file database. There is also experimental support for other database engines.
Since ZAP locks its session file, it is only possible to view or modify the database when ZAP doesn’t have the session open.
Session files are usually stored under session/ in the default directory.
This guide explains how to make changes to ZAP using IntelliJ IDEA.
You will need to have followed the Quick Start Guide to Building ZAP and installed a version of IntelliJ IDEA.
ZAP has a plugin architecture and new functionality is implemented via add-ons.
Add-ons can be defined in any repository but most of the ones that the ZAP core team maintains live in zap-extensions. You should use this repository if you are planning on contributing your add-on to the ZAP project, but please talk to the ZAP Core team about this first via the ZAP Developer Group. If you are planning on maintaining your add-on yourself then you should create it in another repository.
If you want to make changes to ZAP using the Eclipse IDE then you are in the right place.
You will need to have followed the Quick Start Guide to Building ZAP and installed a version of Eclipse suitable for Java development. We would suggest the “Eclipse IDE for Java Developers” package.
The new Automation Framework will in time replace the Command Line and Packaged Scan options. It allows you to control ZAP via one YAML file and provides more flexibility while not being tied to any specific container technology.
The Automation Framework is included with the latest version of ZAP as well as the stable docker image. The framework is plugable and many of the existing add-ons have been enhanced to support it.
This may look like a long list of rules but hopefully many of them are just good development practice.
If you are just getting started with ZAP development then do not worry to much about them, but if you plan to make bigger contributions then you should check them before making too many changes that you might need to rework.
Ever wanted to experiment with the ZAP codebase but felt intimidated by it? This guide will walk you through the process of building ZAP from the command line regardless of your operating system or IDE.
You can also follow along with Simon Bennetts as he sets the ZAP development environment in this Deep Dive video:
This document gives an overview of the automatic and manual components provided by OWASP Zed Attack Proxy (ZAP) that are recommended for testing each of the OWASP Top Ten Project 2017 risks.
For the latest Top Ten see ZAPping the OWASP Top 10 (2021)
Note that the OWASP Top Ten Project risks cover a wide range of underlying vulnerabilities, some of which are not really possible to test for in a completely automated way. If a completely automated tool claims to protect you against the full OWASP Top Ten then you can be sure they are being ‘economical with the truth’!
These are the concepts that you will need to understand in order to configure authentication in ZAP.
ZAP contexts are a way of relating a set of URLs together. You can define any contexts you like, but it is expected that a context will correspond to a web application.
The following SSO providers have documented solutions for automation.
We will aim to test ZAP with as many of these providers as possible in order to provide specific ZAP integration details. If you would like to help with this effort then please get in touch 😁.
Suggested way to get a session token using a direct grant:
Authentication is a key way of restricting access to an app. Some authentication mechanisms also make it significantly harder to use tools like ZAP, even for those people who have permission to use them.
Testing with valid credentials in a production environment is a really bad idea. You will pollute data stores with invalid data and you always run the risk of taking the service down or impacting valid users in some other way.
If you are just performing manual testing then authentication is generally easier.
With manual testing you should be exploring the target app manually with a browser that is proxying through ZAP. In this case you can just use the valid credentials in the browser and in most cases you will be logged in.
If ZAP is handling authentication then it needs to handle sessions as well - logging in is of no use if ZAP does not maintain the session as the target app will just treat ZAP as being unauthenticated.
Session management configuration is part of a ZAP context.
Authentication Methods are the means by which ZAP actually authenticates to a web app.
The following methods are supported:
This is the default method, and means that you are handling authentication yourself.
ZAP has options for auto-detecting all of the different parts of authentication that it requires. If they work for your apps then it will make your life considerably easier, so this is the best place for you to start.
The Authentication Tester Dialog is a quick and easy way to check if ZAP can automatically detect all of the information it needs - you only need to provide the URL of your login page and valid credentials.
ZAP cannot attack parts of the target app if it does not know about them. Exploring the app is key - the more effectively that is done the more effectively ZAP will be able to attack it. This is why ZAP has so many options for exploring apps.
If you want to use ZAP for automated security scanning then you have a wide range of options, also listed on the main Automate page.
Also see the ZAP Chat 06 Automation Introduction video which talks about and demonstrates all of these options in more detail.
Each of these options provides a different balance between ease of use and flexibility + functionality:
It is not unusual for target systems to struggle or even fail when being scanned by ZAP.
This page explains what can go wrong, how to detect these problems and what can be done about them.
If ZAP cannot connect to the target app then it will typically fail very quickly. Solving connection problems will depend on the underlying cause, which ZAP will not be able to detect.
If you ask a question related to authentication on one of the ZAP forums then you will be directed here.
We know that the ZAP authentication documentation needs improving. One of the reasons why it has not been improved is that we are too busy trying to answer authentication questions 😉.
Docker is a great way to run ZAP in a CI/CD pipeline, but diagnosing problems can be tricky.
If ZAP cannot connect to your target app then the first thing to do is to see if this is a ‘Docker’ networking issue.
If you need to set up ZAP to handle authentication then you really need to find a suitable verification URL in your app.
You should always try Auto Detection first as if this works it will find a suitable verification URL for you.
The verification URL will be one that you can request from the Manual Request Editor dialog and which will send a response that allows you to work out whether you are logged in or not. What that looks like will entirely depend on your app, but could be something like:
If you can generate an authentication token (e.g. to use in a header or cookie) and you know that your app will not invalidate it while you are using ZAP then one option is to handle authentication yourself.
In this case you take on the responsibility for handling the authentication and session handling. This means that you do not have to configure ZAP as much but it also means that ZAP will not be able to help you as much.
The ZAP API scan is a script that is available in the ZAP Docker images.
It is tuned for performing scans against APIs defined by OpenAPI, SOAP, or GraphQL via either a local file or a URL.
It imports the definition that you specify and then runs an Active Scan against the URLs found. The Active Scan is tuned to APIs, so it doesn’t bother looking for things like XSSs.
The ZAP Baseline scan is a script that is available in the ZAP Docker images.
It runs the ZAP spider against the specified target for (by default) 1 minute and then waits for the passive scanning to complete before reporting the results.
This means that the script doesn’t perform any actual ‘attacks’ and will run for a relatively short period of time (a few minutes at most).
The ZAP full scan is a script that is available in the ZAP Docker images.
It runs the ZAP spider against the specified target (by default with no time limit) followed by an optional ajax spider scan and then a full active scan before reporting the results.
This means that the script does perform actual ‘attacks’ and can potentially run for a long period of time.
To make it easy to make little tweaks here and there a hook system is in place to help you. It enables you to override or modify behaviour of the script components instead of having to write a new script.
Modifying Args
For the AJAX crawler you may want to target a suburl with a specific
hash (http://example.com vs http://example.com/#/dashboard). You can use the
zap_ajax_spider hook to intercept the arguments and modify them.
Starting with version 2.5.0 you can run the ZAP Desktop UI in your browser without having to install Java, thanks to the magic of Docker and Webswing
To do this you will just need Docker installed. Start the container with webswing support:
docker run -u zap -p 8080:8080 -p 8090:8090 -i ghcr.io/zaproxy/zaproxy:stable zap-webswing.shdocker run -u zap -p 8080:8080 -p 8090:8090 -i ghcr.io/zaproxy/zaproxy:weekly zap-webswing.shThen point your browser at:
Docker image with Zed Attack Proxy preinstalled.
Please note that ZAP Docker images are available on Docker Hub as well as GitHub Container Registry (GHCR).
While the docker run commands on this page use the Docker Hub images, either can be used interchangeably.
The stable image is updated whenever there is a ZAP full release. It is also regenerated monthly, typically on the first Monday of the month. The monthly updates pull in the latest base Docker image and also any updated ZAP add-ons - no ZAP ‘core’ changes are included.