From 8c1e76ffbed8b1a1389ee099452b93866bed69d2 Mon Sep 17 00:00:00 2001 From: Mike Salvatore Date: Mon, 7 Jun 2021 09:54:09 -0400 Subject: [PATCH 1/5] docs: Reword docker supported operating systems --- docs/content/setup/docker.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/content/setup/docker.md b/docs/content/setup/docker.md index 7cee1e6fe..341969ed6 100644 --- a/docs/content/setup/docker.md +++ b/docs/content/setup/docker.md @@ -7,6 +7,10 @@ weight: 4 tags: ["setup", "docker", "linux", "windows"] --- +## Supported operating systems + +The Infection Monkey Docker container works on Linux only. It is not compatible with Docker for Windows or Docker for Mac. + ## Deployment ### Linux @@ -25,10 +29,6 @@ sudo docker run --name monkey-island --network=host -d guardicore/monkey-island: Wait until the Island is done setting up and it will be available on https://localhost:5000 -### Windows and Mac OS X - -Not supported yet, since docker doesn't support `--network=host` parameter on these OS's. - ## Upgrading Currently, there's no "upgrade-in-place" option when a new version is released. From 16ed2e59e8078c6245de620fbe8a3002561265f7 Mon Sep 17 00:00:00 2001 From: Mike Salvatore Date: Mon, 7 Jun 2021 09:56:02 -0400 Subject: [PATCH 2/5] docs: Add steps for user-provided certificate for docker container --- docs/content/setup/docker.md | 119 +++++++++++++++++++++++++++++++---- 1 file changed, 108 insertions(+), 11 deletions(-) diff --git a/docs/content/setup/docker.md b/docs/content/setup/docker.md index 341969ed6..50b195932 100644 --- a/docs/content/setup/docker.md +++ b/docs/content/setup/docker.md @@ -13,21 +13,118 @@ The Infection Monkey Docker container works on Linux only. It is not compatible ## Deployment -### Linux +### 1. Load the docker images +1. Pull the MongoDB v4.2 Docker image: -To extract the `tar.gz` file, run `tar -xvzf monkey-island-docker.tar.gz`. + ```bash + sudo docker pull mongo:4.2 + ``` -Once you've extracted the container from the tar.gz file, run the following commands: +1. Extract the Monkey Island Docker tarball: -```sh -sudo docker load -i dk.monkeyisland.1.10.0.tar -sudo docker pull mongo:4.2 -sudo mkdir -p /var/monkey-mongo/data/db -sudo docker run --name monkey-mongo --network=host -v /var/monkey-mongo/data/db:/data/db -d mongo:4.2 -sudo docker run --name monkey-island --network=host -d guardicore/monkey-island:1.10.0 -``` + ```bash + tar -xvzf monkey-island-docker.tar.gz + ``` -Wait until the Island is done setting up and it will be available on https://localhost:5000 +1. Load the Monkey Island Docker image: + + ```bash + sudo docker load -i dk.monkeyisland.1.10.0.tar + ``` + +### 2. Start MongoDB + +1. Start a MongoDB Docker container: + + ```bash + sudo docker run \ + --name monkey-mongo \ + --network=host \ + --volume db:/data/db \ + --detach mongo:4.2 + ``` + +### 3a. Start Monkey Island with default certificate + +By default, Infection Monkey comes with a [self-signed SSL certificate](https://aboutssl.org/what-is-self-sign-certificate/). In +enterprise or other security-sensitive environments, it is recommended that the +user [provide Infection Monkey with a +certificate](#3b-start-monkey-island-with-user-provided-certificate) that has +been signed by a private certificate authority. + +1. Run the Monkey Island server + ```bash + sudo docker run \ + --name monkey-island \ + --network=host \ + guardicore/monkey-island:1.10.0 + ``` + +### 3b. Start Monkey Island with User-Provided Certificate + +1. Create a directory named `monkey_island_data`. This will serve as the + location where Infection Monkey stores its configuration and runtime + artifacts. + + ```bash + mkdir ./monkey_island_data + ``` + +1. Run Monkey Island with the `--setup-only` flag to populate the `./monkey_island_data` directory with a default `server_config.json` file. + + ```bash + sudo docker run \ + --rm \ + --name monkey-island \ + --network=host \ + --user $(id -u ${USER}):$(id -g ${USER}) \ + --volume "$(realpath ./monkey_island_data)":/monkey_island_data \ + guardicore/monkey-island:1.10.0 --setup-only + ``` + +1. (Optional but recommended) Copy your `.crt` and `.key` files to `./monkey_island_data`. + +1. Make sure that your `.crt` and `.key` files are read-only and readable only by you. + + ```bash + chmod 400 ./monkey_island_data/{*.key,*.crt} + ``` + +1. Edit `./monkey_island_data/server_config.json` to configure Monkey Island + to use your certificate. Your config should look something like this: + + ```json {linenos=inline,hl_lines=["11-14"]} + { + "data_dir": "/monkey_island_data", + "log_level": "DEBUG", + "environment": { + "server_config": "password", + "deployment": "docker" + }, + "mongodb": { + "start_mongodb": false + }, + "ssl_certificate": { + "ssl_certificate_file": "", + "ssl_certificate_key_file": "", + } + } + ``` + +1. Start the Monkey Island server: + + ```bash + sudo docker run \ + --name monkey-island \ + --network=host \ + --user $(id -u ${USER}):$(id -g ${USER}) \ + --volume "$(realpath ./monkey_island_data)":/monkey_island_data \ + guardicore/monkey-island:1.10.0 + ``` + +### 4. Accessing Monkey Island + +After the Monkey Island docker container starts, you can access Monkey Island by pointing your browser at `https://localhost:5000`. ## Upgrading From 6c04124303b402a87109fdd7f1c09f1fdf8854c9 Mon Sep 17 00:00:00 2001 From: Mike Salvatore Date: Mon, 7 Jun 2021 09:56:52 -0400 Subject: [PATCH 3/5] docs: Add `--volume` workaround to docker troubleshooting Resolves #1032 --- docs/content/setup/docker.md | 25 ++++++++++++++++++++----- 1 file changed, 20 insertions(+), 5 deletions(-) diff --git a/docs/content/setup/docker.md b/docs/content/setup/docker.md index 50b195932..e325de002 100644 --- a/docs/content/setup/docker.md +++ b/docs/content/setup/docker.md @@ -140,12 +140,27 @@ using the *Export config* button and then import it to the new Monkey Island. ## Troubleshooting ### The Monkey Island container crashes due to a 'UnicodeDecodeError' -`UnicodeDecodeError: 'utf-8' codec can't decode byte 0xee in position 0: invalid continuation byte` -You may encounter this error because of the existence of different MongoDB keys in the `monkey-island` and `monkey-mongo` containers. +You will encounter a `UnicodeDecodeError` if the `monkey-island` container is +using a different secret key to encrypt sensitive data than was initially used +to store data in the `monkey-mongo` container. -Starting a new container from the `guardicore/monkey-island:1.10.0` image generates a new secret key for storing sensitive information in MongoDB. If you have an old database instance running (from a previous run of Monkey), the key in the `monkey-mongo` container is different than the newly generated key in the `monkey-island` container. Since encrypted data (obtained from the previous run) is stored in MongoDB with the old key, decryption fails and you get this error. +``` +UnicodeDecodeError: 'utf-8' codec can't decode byte 0xee in position 0: invalid continuation byte +``` -You can fix this in two ways: +Starting a new container from the `guardicore/monkey-island:1.10.0` image +generates a new secret key for storing sensitive information in MongoDB. If you +have an old database instance running (from a previous instance of Infection +Monkey), the data stored in the `monkey-mongo` container has been encrypted +with a key that is different from the one that Monkey Island is currently +using. When MongoDB attempts to decrypt its data with the new key, decryption +fails and you get this error. + +You can fix this in one of three ways: 1. Instead of starting a new container for the Monkey Island, you can run `docker container start -a monkey-island` to restart the existing container, which will contain the correct key material. -2. Kill and remove the existing MongoDB container, and start a new one. This will remove the old database entirely. Then, start the new Monkey Island container. +1. Kill and remove the existing MongoDB container, and start a new one. This will remove the old database entirely. Then, start the new Monkey Island container. +1. When you start the Monkey Island container, use `--volume + monkey_island_data:/monkey_island_data`. This will store all of Monkey + Island's runtime artifacts (including the encryption key file) in a docker + volume that can be reused by subsequent Monkey Island containers. From 82c3273e698e3f3dc48fc41bc5d1bae9d1477ec8 Mon Sep 17 00:00:00 2001 From: Mike Salvatore Date: Mon, 7 Jun 2021 10:37:06 -0400 Subject: [PATCH 4/5] docs: Fix minor capitalization issue in docker setup --- docs/content/setup/docker.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/setup/docker.md b/docs/content/setup/docker.md index e325de002..4d05b9b1a 100644 --- a/docs/content/setup/docker.md +++ b/docs/content/setup/docker.md @@ -60,7 +60,7 @@ been signed by a private certificate authority. guardicore/monkey-island:1.10.0 ``` -### 3b. Start Monkey Island with User-Provided Certificate +### 3b. Start Monkey Island with user-provided certificate 1. Create a directory named `monkey_island_data`. This will serve as the location where Infection Monkey stores its configuration and runtime From 9086d9313761ecd483f818d60c47af1e51415153 Mon Sep 17 00:00:00 2001 From: Mike Salvatore Date: Tue, 8 Jun 2021 06:40:59 -0400 Subject: [PATCH 5/5] docs: Make chmod command less specific in docker setup --- docs/content/setup/docker.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/content/setup/docker.md b/docs/content/setup/docker.md index 4d05b9b1a..c839f4aef 100644 --- a/docs/content/setup/docker.md +++ b/docs/content/setup/docker.md @@ -87,7 +87,8 @@ been signed by a private certificate authority. 1. Make sure that your `.crt` and `.key` files are read-only and readable only by you. ```bash - chmod 400 ./monkey_island_data/{*.key,*.crt} + chmod 400 + chmod 400 ``` 1. Edit `./monkey_island_data/server_config.json` to configure Monkey Island