How to Automate OWASP ZAP
Tags: owasp, opensource, security, appsec
Published: 2022-09-14 14:52:47



## Introducing ZAP

[OWASP ZAP](https://www.zaproxy.org/) is the world’s most popular web app scanner that now sees over 4 Million “[Check for Updates](https://www.zaproxy.org/docs/statistics/bar-charts/)” calls per month (up from 1 million just earlier this year). 

It is free, open source, and used by people with a wide range of security experience, ranging from newcomers right up to experienced security professionals to get a better understanding of web application security posture. The way [OWASP ZAP](https://jit.io/zap) works is by attacking your web apps in a similar way to a malicious hacker, where it attacks your apps when they are running and shows you what attackers will be able to find when they attack your app.

## The ZAP Desktop

ZAP was built for flexibility and adoption, and therefore it is possible to run it in a diversity of ways aligned with how you like to work:

- From the command line
- As a desktop application
- As a background daemon

In this blog post I’ll show you how to automate ZAP from the command line, and to set it up by using the ZAP desktop application. The ZAP desktop app allows you to see exactly what ZAP does, and  to tune ZAP to handle your app as effectively as possible.

ZAP requires [Java 8+](https://www.zaproxy.org/download/) to run locally, but you can also run [ZAP in Docker](https://www.zaproxy.org/docs/docker/) and access it via a browser using [Webswing](https://www.zaproxy.org/docs/docker/webswing/).  We won’t dive into this setup here but you are welcome to reference the docs to get started.

Just note, if you use the docker option then you will need to make sure you start docker with the option to map a local drive so that you can access the file you are going to generate after you stop the docker image. On *nix systems the docker option is `-v $(pwd):/zap/wrk/:rw` - on Windows you will need to replace `$(pwd)` with the full path of a suitable directory.

## The Automation Framework

The [Automation Framework](https://www.zaproxy.org/docs/automate/automation-framework/) (AF) allows you to control ZAP with one yaml file. There are other ways to automate ZAP, but the AF is the recommended approach for most users.
You can create the yaml file in a text editor but it is also possible to create it using the ZAP desktop, as that allows you to test the plan as you go, that is the option we will use here.

## Exploring your App Using the Spiders

The first thing to do is to explore your app.
Apps designed for humans are typically best explored by humans, but that’s not a good option for automation and eventually scale. 
However we will start by doing a bit of manual exploration just to make sure we can connect to the app.

In the ZAP desktop click on the “Manual Explore” button.
In the next form fill in the URL of your target app, uncheck the “Enable HUD” box and click on “Launch Browser”.


![OWASP ZAP MANUAL EXPLORE](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/7k0epxkbbvlcpb7ua2u1.png)

A browser should be launched and display your target app - for the sake of this example we will be using Firefox, but Chrome should work as well, if that is the browser you have installed.

Now look at the Sites tree - you should see at least one URL from your target app, probably many more. In this case I’m using [OWASP Juice Shop](https://owasp.org/www-project-juice-shop/) as my target.

Now we can see how well each of the 2 spiders handles our app.

Right click on the top node of your app in the Sites tree and select “Attack -> Spider…” 


![OWASP ZAP - ATTACK](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/fmfjxdadtb0pt6kukxmm.png)

Then click “Start Scan"


![OWASP ZAP localhost](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/jjb45ey2szuwee752hty.png)

This spider should run very quickly, and it will tell you how many URLs are found and how many were added to the Sites tree:


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/y9gmmguy9wbna8m4f5qm.png)

If your target app is a more traditional app, then this should be sufficient. However, if it is a more modern web app which makes heavy use of JavaScript then you will need to use the AJAX spider.

Right click on the top node of your app in the Sites tree and select “Attack -> AJAX Spider…” 


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/hhj5t5baobkcvbzofs97.png)

Then click “Start Scan"


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/yqv3ghky85fdu9e2dddu.png)

This spider will take longer as it launches browsers in order to click on UI elements. It will also tell you how many URLs it found:

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/secx1yklnbuqrs0b74jl.png)

## Exploring your App by Importing API Definitions

If your app just defines an API then you will not be able to explore it either manually or using either of the ZAP spiders.

If you have an API definition then you can import that via the “Import” menu item. ZAP supports importing the following definitions:

- Open API
- GraphQL
- WSDL
- HAR

## Defining a Context

You do not need to define a context if you are just using ZAP manually, but you do need to define one when using the Automation Framework. Luckily this is easy to do - just right click the top node of your app in the Sites tree and select “Include in Context -> New Context“ 


![OWASP ZAP - Context Menu](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/rupqervnwiuincry7c7d.png)


and optionally give it a meaningful name:


![OWASP ZAP - Context Dialog](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/7wxkv5rgt4yd2ufy8yf5.png)

## Creating a Plan in the Desktop

We’re now ready to create the plan.

First, you need to find the “Automation” tab. ZAP has lots of tabs so all but the most essential ones are hidden by default. Click on the green plus tab in the bottom panel and select “Automation”:

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/rxgckkalf9qabug8a4zq.png)

In the new Automation panel click the “New Plan…” button:

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/sjvlb6eqkyct87fr3dyg.png)


Select the context you defined above and then one of the following Profiles:

- Baseline - if you just want to passively scan your app and not attack it
- GraphQL - if you have a GraphQL API definition
- OpenAPI - if you have an OpenAPI / Swagger API definition
- SOAP - if you have a SOAP definition
- Full Scan - if you want to attack your app (and do not have an API definition)

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/bqvepr2i8jqb07kqu8i7.png)

A summary of your plan will now be displayed:

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/xw6v50iqho0rq144qwjl.png)


A plan can be much more flexible than these profiles, but they are the best option to use when you are getting started.

The Baseline and Full scans will include both the [spider](https://www.zaproxy.org/docs/desktop/addons/automation-framework/job-spider/) and the [spiderAjax](https://www.zaproxy.org/docs/desktop/addons/ajax-spider/automation/) - you can remove one of them if you find it is not necessary. Do not remove both as then the plan will not explore your app at all!

If you want to import an API definition in addition to spidering then add the relevant job.

You can edit a plan in the ZAP desktop:

Double clicking on any job will bring up a dialog which will allow you to configure it
The “Add job…” button will allow you to add a job to the existing plan
The “Remove Job…” button will remove the selected job
The “Move Job Up” button will move the selected job up one place
The “Move Job Down” button will move the selected job down one place

## Passive Scanning

ZAP will passively scan every request initiated by ZAP or proxied through it.
The profiles will all add two related jobs:

- [passiveScan-config](https://www.zaproxy.org/docs/desktop/addons/automation-framework/job-pscanconf/) - this allows you to fine tune the passive scanner
- [passiveScan-wait](https://www.zaproxy.org/docs/desktop/addons/automation-framework/job-pscanwait/) - the waits until all of the requests have been passively scanned, it should always be run after any jobs which explore your app

## Active Scanning

The [activeScan](https://www.zaproxy.org/docs/desktop/addons/automation-framework/job-ascan/) job runs the active scanner - this performs the actual attacks.

You should always include this job unless you only want to passively scan your app.

Double clicking on the job will allow you to fine tune the active scan rules.

## Generating a Report

The report job not surprisingly has the task of generating a report - there are a variety of templates with different options for you to choose from. See [https://www.zaproxy.org/docs/desktop/addons/report-generation/templates/](https://www.zaproxy.org/docs/desktop/addons/report-generation/templates/) for the latest list with examples of each.

## Authentication

Authentication is hard, and definitely out of scope for this blog post (but we will do our best to write a deep dive on this in the future). However, ZAP can handle pretty much any authentication mechanisms - more details on the [ZAP website](https://www.zaproxy.org/docs/authentication/). And the good news is that you can test authentication handling in the ZAP desktop where you can see exactly what is going on, and when you create a plan using that context all of the authentication configuration will be imported into the plan.

## Testing Your Plan Locally

You can run the authentication plan you have created in ZAP using the “Run Plan…” button.
You will then see the status of the jobs as the plan runs:

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/hcqi9wr8162rbmey1rff.png)

If any of the jobs fail then you can investigate them in the ZAP desktop.

However jobs may appear to succeed while still not doing what you expect.
Thats is why the AF supports [job outcome tests](https://www.zaproxy.org/docs/desktop/addons/automation-framework/tests/) - these tests can be added to any job and can do things like:

- Check any of the [ZAP statistics](https://www.zaproxy.org/docs/internal-statistics/)
- Check is specific alerts are present of absent
- Check if specific URLs have been found and optionally check their content

Statistics tests are added by default to the spider jobs, but you can add more tests to any of the jobs using the “Add Test…” button (there’s also a “Remove Test…” button) and don’t forget that you can double click on any of the tests in the plan in order to edit them.

## Running in CI/CD

You can run AF tests from the command line using a command like:

`zap.sh -cmd -autorun plan.yaml`

You can also run them in docker. If you are using the stable image then we recommend updating ZAP using a separate command:

`docker run -v $(pwd):/zap/wrk/:rw -t owasp/zap2docker-stable bash -c "zap.sh -cmd -addonupdate; zap.sh -cmd -autorun /zap/wrk/plan.yaml"`

The `$(pwd):/zap/wrk/:rw` part of the command maps your local CWD to the directory `/zap/wrk` in the docker container.

If you use any scripts in your plan then you will need to make sure they are in or below your local CWD and change your plan so that they are referenced via the location they appear in the docker container (i.e. under `/zap/wrk`).

## OWASP ZAP + Jit Integration

While ZAP is an extremely powerful tool, it is very much a “point solution” and does not provide any scan scheduling, history or an online interface. Jit is a [DevSecOps orchestration platform](https://jit.io) which integrates [ZAP](https://jit.io/zap) and other security tools.  By using Jit you can have your ZAP findings available in an aggregated dashboard with the rest  of your security tooling, and receive greater context for the overall security posture of your application.