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

Step 1: load the Docker images

1. Pull the MongoDB v6.0 Docker image:

   Bash

   sudo docker pull mongo:6.0
   

2. Pull the Monkey Island Docker image:

   Bash

   sudo docker pull infectionmonkey/monkey-island:latest
   

Step 2: start MongoDB

If you are upgrading the Infection Monkey to a new version, be sure to remove any MongoDB containers or volumes associated with the previous version.

1. Start a MongoDB Docker container:

   Bash

   sudo docker run \
       --name monkey-mongo \
       --network=host \
       --volume db:/data/db \
       --detach \
       mongo:6.0
   

Step 3: start Monkey Island with a default certificate

By default, Infection Monkey has a self-signed SSL certificate. In enterprise or other security-sensitive environments, we recommend that the user provide Infection Monkey with a certificate signed by a private certificate authority.

1. Run the Monkey Island Server
   Bash

   sudo docker run \
       --tty \
       --interactive \
       --name monkey-island \
       --network=host \
       infectionmonkey/monkey-island:latest
   

Step 4: accessing Monkey Island

After the Monkey Island docker container starts, you can access Monkey Island by pointing your browser at https://localhost:5000.

Once you have access to the Monkey Island server, check out the getting started page

Configuring the server

You can configure the server by mounting a volume and specifying a server configuration file:

1. Create a directory for the server configuration file, e.g. monkey_island_data:
   Bash

   mkdir -m=0700 ./monkey_island_data
   

2. Run the container with a mounted volume, and the --setup-only flag:

sudo docker run \
        --rm \
        --name monkey-island \
        --network=host \
        --user "$(id -u ${USER}):$(id -g ${USER})" \
        --volume "$(realpath ./monkey_island_data)":/monkey_island_data \
        infectionmonkey/monkey-island:latest --setup-only

3. Move your server_config.json file to ./monkey_island_data directory.

Your server_config.json file must contain at least the following:
json { "data_dir": "/monkey_island_data", "mongodb": { "start_mongodb": false } }

3. Run the container with a mounted volume, specify the path to the server_config.json:

sudo docker run \
    --rm \
    --name monkey-island \
    --network=host \
    --user "$(id -u ${USER}):$(id -g ${USER})" \
    --volume "$(realpath ./monkey_island_data)":/monkey_island_data \
    infectionmonkey/monkey-island:latest --server-config="/monkey_island_data/server_config.json"

Start Monkey Island with a user-provided certificate

By default, Infection Monkey comes with a self-signed SSL certificate. In an enterprise or other security-sensitive environments, it is recommended that the user provides Infection Monkey with a certificate that a private certificate authority has signed.

1. If you haven't already, follow the steps above in the Configuring the server section.
2. Terminate the Docker container if it's already running.
3. Move your .crt and .key files to ./monkey_island_data.
4. Make sure that your .crt and .key files are readable only by you.

chmod 600 <PATH_TO_KEY_FILE>
chmod 600 <PATH_TO_CRT_FILE>

5. Modify the server configuration file to look like:

{
  "data_dir": "/monkey_island_data",
        "mongodb": {
            "start_mongodb": false
        }, 
  "ssl_certificate": {
        "ssl_certificate_file": "/monkey_island_data/my_cert.crt",
        "ssl_certificate_key_file": "/monkey_island_data/my_key.key"
    }
}

6. Run the container with a mounted volume, specify the path to the server_config.json:

sudo docker run \
    --rm \
    --name monkey-island \
    --network=host \
    --user "$(id -u ${USER}):$(id -g ${USER})" \
    --volume "$(realpath ./monkey_island_data)":/monkey_island_data \
            infectionmonkey/monkey-island:latest --server-config="/monkey_island_data/server_config.json"

7. Access the Monkey Island web UI by pointing your browser at https://localhost:5000.

Change logging level

1. Stop the Docker container if it's already running.
2. Modify the server configuration file by adding the following lines:
   JSON

   {
       "log_level": "INFO"
   }
   

3. Run the container with a mounted volume, specify the path to the server_config.json:
   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:VERSION --setup-only --server-config="/monkey_island_data/server_config.json"
   

4. Access the Monkey Island web UI by pointing your browser at https://localhost:5000.

Upgrading

Currently, there's no "upgrade-in-place" option when a new version is released. To get an updated version, download it, stop and remove the current Monkey Island and MongoDB containers and volumes, and rerun the installation commands with the new file.

If you'd like to keep your existing configuration, you can export it to a file using the Export config button and then import it to the new Monkey Island.

Troubleshooting

The Monkey Island container crashes due to a 'UnicodeDecodeError'

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.

UnicodeDecodeError: 'utf-8' codec can't decode byte 0xee in position 0: invalid continuation byte

Starting a new container from the infectionmonkey/monkey-island:VERSION 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.
3. 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.