From 49ec7f339b2ba7525b567a7263f525c20beb8d47 Mon Sep 17 00:00:00 2001 From: jaywon Date: Sat, 23 Feb 2019 17:48:07 -1000 Subject: [PATCH 1/6] :wrench: Add .env.example for docker-compose env and add .env to .gitignore --- .env.example | 1 + .gitignore | 3 +++ 2 files changed, 4 insertions(+) create mode 100644 .env.example diff --git a/.env.example b/.env.example new file mode 100644 index 000000000..885546779 --- /dev/null +++ b/.env.example @@ -0,0 +1 @@ +ZAP_API_KEY= \ No newline at end of file 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 From 60f6980f923d2aa7019f4e960a2eae73b5340ecc Mon Sep 17 00:00:00 2001 From: jaywon Date: Sat, 23 Feb 2019 17:48:51 -1000 Subject: [PATCH 2/6] :whale: Add docker-compose file for running ZAP w/ HUD enabled --- docker-compose.yml | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) create mode 100644 docker-compose.yml diff --git a/docker-compose.yml b/docker-compose.yml new file mode 100644 index 000000000..f6c5f8725 --- /dev/null +++ b/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 From 5d6134fe21d516ad260907260e3b90078d540594 Mon Sep 17 00:00:00 2001 From: jaywon Date: Sat, 23 Feb 2019 17:49:16 -1000 Subject: [PATCH 3/6] :pencil2: Document docker-compose and Docker usage for running ZAP and HUD --- README.md | 32 +++++++++++++++++++++++++++++++- 1 file changed, 31 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 5c3674058..deb66e524 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,34 @@ 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-compose.yml` to start the environment in a Docker container. + +``` + git clone https://github.com/zaproxy/zap-hud.git + cd zap-hud + 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` + +``` + docker-compose up +``` + +#### Docker +If you'd like to run ZAP in a Docker container without cloning the repo, 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 +``` + ### Starting the HUD 1. Quick Start: Select either `Firefox` or `Chrome` on the `Quick Start` tab and click on the `Launch Browser` button. From 98bdec025554cbf4debc0c512d6b1acd760dc726 Mon Sep 17 00:00:00 2001 From: jaywon Date: Thu, 14 Mar 2019 09:46:48 -1000 Subject: [PATCH 4/6] Isolating Docker related configuration to dedicated directory As per feedback, for now isolating Docker related files into a dedicated directory. * Move .env, .env.example, docker-compose.yml to docker/ * Update documentation for running ZAP/HUD in Docker --- README.md | 10 +++++----- .env.example => docker/.env.example | 0 docker-compose.yml => docker/docker-compose.yml | 0 3 files changed, 5 insertions(+), 5 deletions(-) rename .env.example => docker/.env.example (100%) rename docker-compose.yml => docker/docker-compose.yml (100%) diff --git a/README.md b/README.md index deb66e524..9b0f2615b 100644 --- a/README.md +++ b/README.md @@ -39,11 +39,11 @@ 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-compose.yml` to start the environment in a Docker container. +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 + cd zap-hud/docker cp .env.example .env ``` @@ -51,14 +51,14 @@ Create a random API key of your choosing and add it to your `.env` file ``` ZAP_API_KEY=somevalue ``` -Start `docker-compose` +Start `docker-compose` environment ``` docker-compose up ``` -#### Docker -If you'd like to run ZAP in a Docker container without cloning the repo, you can run the following `docker` command, swapping out `CHANGE_ME` with your custom API Key value: +#### 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 \ diff --git a/.env.example b/docker/.env.example similarity index 100% rename from .env.example rename to docker/.env.example diff --git a/docker-compose.yml b/docker/docker-compose.yml similarity index 100% rename from docker-compose.yml rename to docker/docker-compose.yml From 5d6c08e29dba015b19a6a432e4b41fd42a3340a9 Mon Sep 17 00:00:00 2001 From: jaywon Date: Thu, 14 Mar 2019 09:50:34 -1000 Subject: [PATCH 5/6] :whale: Update instructions to start docker conatiner in daemon mode --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 9b0f2615b..96f0db5a9 100644 --- a/README.md +++ b/README.md @@ -54,7 +54,7 @@ ZAP_API_KEY=somevalue Start `docker-compose` environment ``` - docker-compose up + docker-compose up -d ``` #### Docker Stand-Alone From d3e4ac05d965ceb7abb702d45b40e27f8bffd55d Mon Sep 17 00:00:00 2001 From: jaywon Date: Thu, 14 Mar 2019 09:57:14 -1000 Subject: [PATCH 6/6] :pencil2: Add README entry for link to wiki for Docker environment specifics --- README.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/README.md b/README.md index 96f0db5a9..4c06ad9db 100644 --- a/README.md +++ b/README.md @@ -66,6 +66,11 @@ docker run -u zap -p 9090:9090 --rm -i owasp/zap2docker-weekly zap.sh -daemon -h -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.