Introduction to using ZAP with Docker

By Samuli Elomaa

 + 

For those who are not familiar with Docker. Docker is an application container, which works bit similar to "user mode Linux" or LXC containers, allowing users to deploy applications inside containers containing full virtualized OS install while having isolated container which can easily be deployed as needed.

The build process for the docker images is as simple as downloading the ascii-file containing the configuration along with specific OS-commands and running "docker build" -command, or just use the existing images with simple "docker pull" -command in order to download pre-made images from the docker hub.

In order to support zap usage on docker environments, the ZAP project has pre-made images available allowing easy use and deployment of Stable and Weekly versions of ZAP through docker.

What can you do with ZAP docker images?

For me the main advantages are:

• Integrating ZAP as part of docker based build/deploy CI-process in order to run non-interactive ZAP active scanning against other docker containers within the same cloud.
• Quickly deploying ZAP to a docker friendly datacenter in order to use ZAP for scanning applications behind firewalls.
• Having the latest ZAP stable/weekly release inside an isolated container in your personal workstation.

How to get started:

First you need to have the docker tool installed. You can do this by following instructions at the docker website. Or if you are using debian compatible OS, you can just type "apt-get install docker.io".

Once you have docker installed you can pull the latest zap docker image from owasp's docker image repository (hosted by docker hub).

docker pull owasp/zap2docker-stable

Or for weekly images:

docker pull owasp/zap2docker-weekly

This will download and install the zap docker images from docker project's image hub. Alternatively you can build your own with the docker files located at build/docker directory of the zap source code archive.

How to access the ZAP running inside the docker

• ZAP GUI (via VNC)
• ZAPR for script/CI-friendly automatic active scanning without user interaction.
• ZAP API

1. GUI via VNC

The easiest way to access the ZAP GUI is via the embedded vnc-server:

docker run -u zap -p 5900:5900 -p 8080:8080 -i owasp/zap2docker-stable x11vnc --forever --usepw --create

This will first ask you to set VNC server password, once done it will startup the VNC session. Which you can connect with your VNC client (eg. in the example its localhost and tcp port 5900). In order to reach the ZAP proxy from your web browser just set your http proxy point to your docker host's IP (or localhost) and TCP port 8080, when you are done you can just kill the docker image with ctrl+c.

For downloading the report files from the docker image, you can use the data volume mounting option: -v localdir:/home/zap/ , altough this does have problems when using systems like boot2docker. Please see the following site for more detailed information regarding managing data in docker containers: https://docs.docker.com/userguide/dockervolumes/

2. ZAPR

Zapr is ruby script for ZAP which allows non-interactive active scanning for desired targets, which is nice for things like cronjobs or shell-script jobs. Notice that the summary report from Zapr is printed to the console after running the docker command.

docker run -u zap -i owasp/zap2docker-stable zapr --debug --summary http://target

3. API or headless mode

The best way to integrate ZAP as part of your CI-scripts (if you use Java or Python) is through the API:

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

When this is run, you can access the ZAP API from localhost/host-ip at tcp port 8090. Eg. http://127.0.0.1:8090/ or http://dockerip:8090/

See more details regarding the ZAP api usage here: https://code.google.com/p/zaproxy/wiki/ApiDetails

For the Docker help, the docker project has nice Docker User guide at: https://docs.docker.com/userguide/

Happy Hacking!