Guide on ZAP

Community - Tips and Tricks

Fri, 25 Aug 2023 00:00:00 +0000

News about a community area to contribute ZAP usage tips and tricks.

Verifying Your Changes

Mon, 07 Feb 2022 00:00:00 +0000

Code Formatting

The ZAP code must conform to standard formatting rules - if any changes do not conform then they will fail the build.

ZAPping the OWASP Top 10 (2021)

Wed, 01 Dec 2021 00:00:00 +0000

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 Session Database

Wed, 15 Sep 2021 00:00:00 +0000

ZAP stores its session data in an HSQLDB file database. There is also experimental support for other database engines.

Connecting to a Session Database

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.

Building ZAP with IntelliJ IDEA

Mon, 22 Mar 2021 00:00:00 +0000

This guide explains how to make changes to ZAP using IntelliJ IDEA.

Preparation

You will need to have followed the Quick Start Guide to Building ZAP and installed a version of IntelliJ IDEA.

Creating a New Add-on in zap-extensions

Mon, 22 Mar 2021 00:00:00 +0000

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.

Building ZAP with Eclipse

Thu, 18 Mar 2021 00:00:00 +0000

If you want to make changes to ZAP using the Eclipse IDE then you are in the right place.

Preparation

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.

Automation Framework

Tue, 09 Mar 2021 00:00:00 +0000

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.

Development Rules and Guidelines

Wed, 20 Jan 2021 00:00:00 +0000

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.

A Quick Start Guide to Building ZAP

Fri, 04 Dec 2020 00:00:00 +0000

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:

ZAPping the OWASP Top 10 (2017)

Thu, 30 Jan 2020 00:00:00 +0000

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)

Authentication - Concepts

Mon, 01 Jan 0001 00:00:00 +0000

These are the concepts that you will need to understand in order to configure authentication in ZAP.

Contexts

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.

Authentication - Documented SSO Solutions

Mon, 01 Jan 0001 00:00:00 +0000

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 😁.

Keycloak

Documentation: https://www.keycloak.org/docs/latest/securing_apps/#_resource_owner_password_credentials_flow
Test service: none

Suggested way to get a session token using a direct grant:

Authentication - Make your Life Easier

Mon, 01 Jan 0001 00:00:00 +0000

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.

Test in a Safe Environment

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.

Authentication - Manual

Mon, 01 Jan 0001 00:00:00 +0000

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.

Authentication - Session Handling

Mon, 01 Jan 0001 00:00:00 +0000

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.

In the ZAP desktop it is configured via the Context Session Management screen.
In the Automation Framework it is part of a context defined in the environment.
In the API it is configured via endpoints underneath the sessionManagement component.

ZAP supports Cookie and HTTP Authentication Session Management out of the box.

Authentication Methods

Mon, 01 Jan 0001 00:00:00 +0000

Authentication Methods are the means by which ZAP actually authenticates to a web app.

The following methods are supported:

Manual Authentication

This is the default method, and means that you are handling authentication yourself.

Auto-Detection

Mon, 01 Jan 0001 00:00:00 +0000

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.

Authentication Tester Dialog

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.

Automation Guide - Exploring Your App

Mon, 01 Jan 0001 00:00:00 +0000

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.

Automation Guide - Options

Mon, 01 Jan 0001 00:00:00 +0000

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:

Automation Guide - Target Scanning Issues

Mon, 01 Jan 0001 00:00:00 +0000

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.

Cannot Connect

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.

Diagnosing Authentication Problems

Mon, 01 Jan 0001 00:00:00 +0000

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 😉.

Diagnosing Docker Problems

Mon, 01 Jan 0001 00:00:00 +0000

Docker is a great way to run ZAP in a CI/CD pipeline, but diagnosing problems can be tricky.

ZAP Cannot Connect to the Target

If ZAP cannot connect to your target app then the first thing to do is to see if this is a ‘Docker’ networking issue.

Finding a Verification URL

Mon, 01 Jan 0001 00:00:00 +0000

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:

Handling Authentication Yourself (in Automation)

Mon, 01 Jan 0001 00:00:00 +0000

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.

ZAP - API Scan

Mon, 01 Jan 0001 00:00:00 +0000

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.

ZAP - Baseline Scan

Mon, 01 Jan 0001 00:00:00 +0000

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).

ZAP - Full Scan

Mon, 01 Jan 0001 00:00:00 +0000

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.

ZAP - Scan Hooks

Mon, 01 Jan 0001 00:00:00 +0000

Scan Hooks

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.

Use Cases

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.

ZAP - Webswing Usage

Mon, 01 Jan 0001 00:00:00 +0000

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:

Stable:
- docker run -u zap -p 8080:8080 -p 8090:8090 -i ghcr.io/zaproxy/zaproxy:stable zap-webswing.sh
Weekly:
- docker run -u zap -p 8080:8080 -p 8090:8090 -i ghcr.io/zaproxy/zaproxy:weekly zap-webswing.sh

Then point your browser at:

ZAP Browser Extension Integration

Mon, 01 Jan 0001 00:00:00 +0000

Using Browser Extensions in ZAP

If you just want to get ZAP to inject one or more browser extensions in any of the browsers that ZAP launches then you can do that via the Selenium Options Screen.

ZAP Docker User Guide

Mon, 01 Jan 0001 00:00:00 +0000

Introduction

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.

Details

Install Instructions

Stable

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.