Skip to main content

Running OWASP Zed Attack Proxy with Docker

infosec
Learn how to set up and run OWASP ZAP using Docker for web application security testing, both in GUI mode and headless for CI/CD integration.

Introduction

Security testing is often seen as complex and time-consuming, requiring specialised skills and tools. For development teams looking to integrate security testing into their workflow, the overhead can seem daunting. How can you efficiently incorporate security scanning without disrupting your development process?

OWASP Zed Attack Proxy (ZAP) offers a solution, and Docker makes it even more accessible. This article will show you how to quickly set up and run ZAP using Docker, enabling you to perform automated security testing with minimal configuration.

What is OWASP ZAP?

ZAP is a free, open-source penetration testing tool maintained under the Open Web Application Security Project (OWASP). It's designed specifically for testing web applications and functions as a "man-in-the-middle proxy" - it stands between your browser and the web application, intercepting and inspecting messages, with the ability to modify contents if needed.

Setting up ZAP with Docker

Prerequisites

  • Docker installed on your system
  • Basic familiarity with command-line operations
  • A web application to test

Pulling the ZAP Docker image

First, let's pull the official ZAP Docker image:

docker pull owasp/zap2docker-stable

Note

The image will take up approximately 1GB of disk space. The Dockerfile is available at [zaproxy/zaproxy/blob/main/docker/Dockerfile-stable](https://github.com/zaproxy/zaproxy/blob/main/docker/Dockerfile-stable).

Running ZAP in different modes

ZAP can operate in multiple modes. Let's explore the two primary ways to run ZAP with Docker.

Running ZAP with GUI access

If you prefer a graphical interface, you can run ZAP with Webswing support:

docker run -u zap -p 8080:8080 -p 8090:8090 -i owasp/zap2docker-stable zap-webswing.sh

Once running, access the GUI through your browser at:

http://localhost:8080/zap

Caution

While the GUI is convenient for interactive testing, the Java-based interface may feel somewhat clunky compared to native applications. For automated testing, the headless mode is often preferable.

Running ZAP in headless mode

For automated testing or integration with CI/CD pipelines, headless mode is more suitable:

docker run -u zap -p 8080:8080 -i owasp/zap2docker-stable zap.sh -daemon -host 0.0.0.0 -port 8080

Configuration options for headless mode

When running ZAP headless, several configuration options can enhance security and accessibility:

API Key management:

-config api.disablekey=true

Important

Only disable the API key in completely isolated environments, as malicious sites could otherwise access the ZAP API.

Permitted IP addresses:

-config api.addrs.addr.name=.* -config api.addrs.addr.regex=true

Note

By default, ZAP only allows connections from the local machine. The configuration above permits all IP addresses to connect to ZAP's API, which should only be used in completely isolated environments.

Complete headless configuration example

Here's a complete command for running ZAP in headless mode with common configurations:

docker run -u zap -p 8080:8080 -i owasp/zap2docker-stable zap.sh \
    -daemon \
    -host 0.0.0.0 \
    -port 8080 \
    -config api.disablekey=true \
    -config api.addrs.addr.name=.* \
    -config api.addrs.addr.regex=true

Integrating ZAP into CI/CD pipelines

ZAP Docker images come with scripts designed for CI/CD integration. These scripts can be run directly from the container.

Basic scan example

To run a basic baseline scan against a website:

docker run -t owasp/zap2docker-stable zap-baseline.py -t https://www.example.com

Saving scan results to a file

If you need to save the results to a file:

docker run -v $(pwd):/zap/wrk/:rw -t owasp/zap2docker-stable zap-baseline.py \
    -t https://www.example.com -g gen.conf -r testreport.html

Sample scan output

A baseline scan produces output similar to this:

Total of 3 URLs
PASS: Cookie No HttpOnly Flag [10010]
PASS: Cookie Without Secure Flag [10011]
PASS: Password Autocomplete in Browser [10012]
...
WARN: Incomplete or No Cache-control and Pragma HTTP Header Set [10015] x 3
	https://www.example.com
	https://www.example.com/robots.txt
	https://www.example.com/sitemap.xml
...
FAIL: 0	WARN: 4	IGNORE: 0	PASS: 22

Tip

For all command line options, check the [manual for the baseline scan](https://www.zaproxy.org/docs/docker/baseline-scan/#usage).

Troubleshooting

Container health monitoring

To ensure your ZAP container remains responsive, you can use Docker's HEALTHCHECK instruction. Add the following to your Docker Compose file or Dockerfile:

healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost:8080/"]
  interval: 30s
  timeout: 10s
  retries: 3
  start_period: 30s

Conclusion

With Docker, integrating OWASP ZAP into your development workflow becomes straightforward. Whether you prefer using the GUI for interactive testing or headless mode for CI/CD integration, Docker provides a clean, consistent environment for your security testing needs.

By regularly running automated security scans with ZAP, you can catch vulnerabilities early in the development process, reducing the cost and effort of addressing security issues later.

Next steps

  • Explore ZAP's API for more advanced scanning options
  • Set up scheduled scans of your applications
  • Integrate ZAP scan results with your issue tracking system
  • Learn about authentication handling for testing secure areas of your application

Resources