diff --git a/.gitignore b/.gitignore index a21630f6c..42a95c548 100644 --- a/.gitignore +++ b/.gitignore @@ -33,3 +33,6 @@ # JS node_modules/ dist/ + +# Docker/Docker Compose +.env \ No newline at end of file diff --git a/README.md b/README.md index 5c3674058..4c06ad9db 100644 --- a/README.md +++ b/README.md @@ -18,7 +18,9 @@ Learn more: ## Using the HUD -### Downloading +### Usage + +#### From Source Code You can download ZAP enabled with the HUD from any of: 1. Download and run the latest [ZAP Weekly Release](https://github.com/zaproxy/zaproxy/wiki/Downloads#zap-weekly) @@ -36,6 +38,39 @@ You'll see the HUD Radar icon ![Radar Icon](https://raw.githubusercontent.com/za ![Toolbar with Radar](https://raw.githubusercontent.com/zaproxy/zap-hud/develop/assets/images/toolbar_radar.png) +#### Docker Compose +Alternatively if you just want to run ZAP with zero setup and the HUD automatically installed and enabled with Docker you can use the included `docker/docker-compose.yml` to start the environment in a Docker container. + +``` + git clone https://github.com/zaproxy/zap-hud.git + cd zap-hud/docker + cp .env.example .env +``` + +Create a random API key of your choosing and add it to your `.env` file +``` +ZAP_API_KEY=somevalue +``` +Start `docker-compose` environment + +``` + docker-compose up -d +``` + +#### Docker Stand-Alone +If you'd like to run ZAP in a Docker container without cloning the repo and a `docker-compose` environment, you can run the following `docker` command, swapping out `CHANGE_ME` with your custom API Key value: + +``` +docker run -u zap -p 9090:9090 --rm -i owasp/zap2docker-weekly zap.sh -daemon -host 0.0.0.0 -port 9090 \ +-config api.addrs.addr.name=.* -config api.addrs.addr.regex=true -config -config api.key=CHANGE_ME \ +-config hud.enabledForDaemon=true +``` + +### Docker Usage Considerations +For more detailed instructions on configuring your browser to use CA certificates generated in a ephemeral Docker environment please see the official wiki entry: + +[Using the HUD with ZAP in Docker](https://github.com/zaproxy/zap-hud/wiki/Using-the-HUD-with-ZAP-in-Docker) + ### Starting the HUD 1. Quick Start: Select either `Firefox` or `Chrome` on the `Quick Start` tab and click on the `Launch Browser` button. diff --git a/docker/.env.example b/docker/.env.example new file mode 100644 index 000000000..885546779 --- /dev/null +++ b/docker/.env.example @@ -0,0 +1 @@ +ZAP_API_KEY= \ No newline at end of file diff --git a/docker/docker-compose.yml b/docker/docker-compose.yml new file mode 100644 index 000000000..f6c5f8725 --- /dev/null +++ b/docker/docker-compose.yml @@ -0,0 +1,19 @@ +version: '3' +services: + zap-hud: + image: owasp/zap2docker-weekly + ports: + - 9090:9090 + user: zap + env_file: + - .env + command: > + sh -c " + zap.sh + -daemon + -host 0.0.0.0 + -port 9090 + -config api.addrs.addr.name=.* + -config api.addrs.addr.regex=true + -config api.key=${ZAP_API_KEY} + -config hud.enabledForDaemon=true" \ No newline at end of file