From 3e32dbbc52eaa189b9c07442f4b9d796deecd044 Mon Sep 17 00:00:00 2001 From: VakarisZ Date: Fri, 26 Nov 2021 16:55:43 +0200 Subject: [PATCH] Docs: extract the server configuration workflow to a separate server_configuration.md page, which explains how to setup and use server_configuration.json This change extracts server_config.json usage into a single page, which can then be referred to from any page that requires island configuration --- docs/content/FAQ/_index.md | 4 + docs/content/reference/data_directory.md | 2 +- .../content/reference/server_configuration.md | 100 ++++++++++++++++++ docs/content/setup/docker.md | 32 +----- docs/content/setup/linux.md | 23 +--- docs/content/setup/windows.md | 20 +--- 6 files changed, 112 insertions(+), 69 deletions(-) create mode 100644 docs/content/reference/server_configuration.md diff --git a/docs/content/FAQ/_index.md b/docs/content/FAQ/_index.md index 49cc4e0b8..24f26b0be 100644 --- a/docs/content/FAQ/_index.md +++ b/docs/content/FAQ/_index.md @@ -174,6 +174,10 @@ The log enables you to see which requests were requested from the server and ext 2019-07-23 10:52:24,027 - report.py:580 - get_domain_issues() - INFO - Domain issues generated for reporting ``` +It's also possible to change the default log level by editing `log_level` value in a [server configuration file](../../reference/server_configuration). +You can use any of the default Python log levels. + + ### Infection Monkey agent logs The Infection Monkey agent log file can be found in the following paths on machines where it was executed: diff --git a/docs/content/reference/data_directory.md b/docs/content/reference/data_directory.md index 2ab7ca78e..2fc6605cd 100644 --- a/docs/content/reference/data_directory.md +++ b/docs/content/reference/data_directory.md @@ -22,7 +22,7 @@ On Windows, the default path is `%AppData%\monkey_island`. The location of the data directory is set in the `data_dir` field in the `server_config.json` file. -1. Create a custom `server_config.json` file and set the `data_dir` field. Its +1. [Create a custom server_config.json file](../server_configuration) and set the `data_dir` field. Its contents will look like: ```json diff --git a/docs/content/reference/server_configuration.md b/docs/content/reference/server_configuration.md new file mode 100644 index 000000000..60f0dd12c --- /dev/null +++ b/docs/content/reference/server_configuration.md @@ -0,0 +1,100 @@ +--- +title: "Server configuration" +date: 2021-11-26T12:00:19+02:00 +draft: true +pre: ' ' +weight: 1 +--- + +## Configuring the Island + +The Island Server(C&C) is configured by creating a `server_config.json` file. + +### Creating a configuration file + +Here's an example `server_config.json` with all options specified: +```json +{ + "log_level": "DEBUG", + "ssl_certificate": { + "ssl_certificate_file": "", + "ssl_certificate_key_file": "" + }, + "mongodb": { + "start_mongodb": true + }, + "data_dir": "/monkey_island_data" +} +``` + +Only relevant options can be specified, for example: +```json +{ + "ssl_certificate": { + "ssl_certificate_file": "", + "ssl_certificate_key_file": "" + } +} +``` + +### Applying configuration to the island + +#### AppImage (Linux) + +Specify the path to the `server_config.json` through a command line argument. + +Example: `./InfectionMonkey-v1.12.0.AppImage --server-config="/tmp/server_config.json"` + +#### Windows + +Move the created `server_config.json` to the install directory, monkey island directory. +If you haven't changed the default install directory, the path should look like: + +`C:\Program Files\Guardicore\Monkey Island\monkey\monkey_island\server_config.json` + +#### Docker + +Best way to configure the docker is to is to map server's [data directory](../data_directory) to a volume: + +1. Create a directory for server configuration and other files, e.g. `monkey_island_data`. If you already have it, + **make sure it's empty**. + + ```bash + mkdir ./monkey_island_data + chmod 700 ./monkey_island_data + ``` +1. Establish and populate the created directory with server files (modify the `VERSION` to the one you downloaded): +```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 +``` + +Once the volume is mapped, we can put `server_config.json` there. +`server_config.json` for docker **must** contain a valid data directory field and `start_mongodb` set to false. + +So, at minimum your `server_config.json` should look like this: + +```json +{ + "data_dir": "/monkey_island_data", + "mongodb": { + "start_mongodb": false + } +} +``` + +Then, the container can be launched by providing `server_config.json` path in the arguments: +```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 --server-config="/monkey_island_data/server_config.json" +``` diff --git a/docs/content/setup/docker.md b/docs/content/setup/docker.md index db5979fc6..1feeec07d 100644 --- a/docs/content/setup/docker.md +++ b/docs/content/setup/docker.md @@ -73,28 +73,9 @@ If you are upgrading the Infection Monkey to a new version, be sure to remove any volumes associated with the previous version. {{% /notice %}} -1. Create a directory named `monkey_island_data`. If you already have it, - **make sure it's empty**. This will serve as the location where Infection - Monkey stores its configuration and runtime artifacts. +1. [Setup a volume with configuration file](../../reference/server_configuration/#docker). - ```bash - mkdir ./monkey_island_data - chmod 700 ./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:VERSION --setup-only - ``` - -1. Move your `.crt` and `.key` files to `./monkey_island_data`. +1. Move your `.crt` and `.key` files to the volume created in the previous step (`./monkey_island_data`). 1. Make sure that your `.crt` and `.key` files are readable and writeable only by you. @@ -109,11 +90,6 @@ any volumes associated with the previous version. ```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 }, @@ -124,7 +100,7 @@ any volumes associated with the previous version. } ``` -1. Start the Monkey Island server: +1. Start/restart the Monkey Island server: ```bash sudo docker run \ @@ -134,7 +110,7 @@ any volumes associated with the previous version. --network=host \ --user "$(id -u ${USER}):$(id -g ${USER})" \ --volume "$(realpath ./monkey_island_data)":/monkey_island_data \ - guardicore/monkey-island:VERSION + guardicore/monkey-island:VERSION --server-config="/monkey_island_data/server_config.json" ``` ### 4. Accessing Monkey Island diff --git a/docs/content/setup/linux.md b/docs/content/setup/linux.md index 275330c2c..b1791c617 100644 --- a/docs/content/setup/linux.md +++ b/docs/content/setup/linux.md @@ -72,30 +72,11 @@ private certificate authority. chmod 600 ``` -1. Edit `$HOME/.monkey_island/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", - "log_level": "DEBUG", - "environment": { - "server_config": "password", - "deployment": "linux" - }, - "mongodb": { - "start_mongodb": true - }, - "ssl_certificate": { - "ssl_certificate_file": "", - "ssl_certificate_key_file": "" - } - } - ``` +1. Create a [server configuration file and provide the path to the certificate](../../reference/server_configuration). 1. Start Monkey Island by running the Infection Monkey AppImage package: ```bash - ./InfectionMonkey-v1.12.0.AppImage + ./InfectionMonkey-v1.12.0.AppImage --server-config="/path/to/server_config.json" ``` 1. Access the Monkey Island web UI by pointing your browser at diff --git a/docs/content/setup/windows.md b/docs/content/setup/windows.md index f9fd5acaf..f76e80de1 100644 --- a/docs/content/setup/windows.md +++ b/docs/content/setup/windows.md @@ -39,25 +39,7 @@ private certificate authority. `%AppData%\monkey_island`. 1. Stop the Monkey Island process. 1. (Optional but recommended) Move your `.crt` and `.key` files to `%AppData%\monkey_island`. -1. Edit `%AppData%\monkey_island\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"]} - { - "log_level": "DEBUG", - "environment": { - "server_config": "password", - "deployment": "windows" - }, - "mongodb": { - "start_mongodb": true - }, - "ssl_certificate": { - "ssl_certificate_file": "", - "ssl_certificate_key_file": "" - } - } - ``` +1. Create a [server configuration file and provide the path to the certificate](../../reference/server_configuration). 1. Run the Monkey Island by clicking on the desktop shortcut. 1. Access the Monkey Island web UI by pointing your browser at