p15693087
/
monkey
forked from p15670423/monkey
1
0
Fork 0
Code Issues Pull Requests 1 Projects Releases Wiki Activity

Docs: moved server configuration and common configuration operation docs to corresponding deployment option setup pages

This commit is contained in:
VakarisZ 2021-11-30 15:44:46 +02:00
parent 06f31791fc
commit 0a32ac888e
5 changed files with 143 additions and 120 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

20
docs/content/FAQ/_index.md
View File

@ -201,25 +201,7 @@ The logs contain information about the internals of the Infection Monkey agent's
2019-07-22 19:16:45,013 [77598:140654230214464:DEBUG] connectionpool._make_request.396: https://updates.infectionmonkey.com:443 "GET / HTTP/1.1" 200 61
```
### How do I change the log level of the Monkey Island logger?
The log level of the Monkey Island logger is set in the `log_level` field
in the `server_config.json` file (located in the [data directory]({{< ref "/reference/data_directory" >}})).
Make sure to leave everything else in `server_config.json` unchanged:
```json
{
...
"log_level": "DEBUG",
...
}
```
Logging levels correspond to [the logging level constants in python](https://docs.python.org/3.7/library/logging.html#logging-levels).
To apply the changes, reset the Monkey Island process.
On Linux, use `sudo systemctl restart monkey-island.service`.
On Windows, restart the program.
Logging level/verbosity can also be changed, see [setup page](../../setup) for you operating system.
## Running the Infection Monkey in a production environment

65
docs/content/reference/server_configuration.md
View File

@ -37,64 +37,11 @@ Only relevant options can be specified, for example:
}
```
### Applying configuration to the island
### Configuration options
#### AppImage (Linux)
See setup instructions for your operating system to understand how to apply these.
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"
```
- `log_level` - can be set to `"DEBUG"`(verbose), `"INFO"`(less verbose) or `"ERROR"`(silent, except errors).
- `ssl_certificate` - contains paths for files, required to run the Island server with custom certificate.
- `data_dir` - path to a writeable directory where the Island will store the database and other files.
- `mongodb` - options for MongoDB. Should not be changed unless you want to run your own instance of MongoDB.

97
docs/content/setup/docker.md
View File

@ -49,12 +49,12 @@ any MongoDB containers or volumes associated with the previous version.
mongo:4.2
```
### 3a. Start Monkey Island with default certificate
### 3. 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
certificate](#start-monkey-island-with-user-provided-certificate) that has
been signed by a private certificate authority.
1. Run the Monkey Island server
@ -67,55 +67,90 @@ been signed by a private certificate authority.
guardicore/monkey-island:VERSION
```
### 3b. Start Monkey Island with user-provided certificate
{{% notice info %}}
If you are upgrading the Infection Monkey to a new version, be sure to remove
any volumes associated with the previous version.
{{% /notice %}}
### 4. Accessing Monkey Island
1. [Setup a volume with configuration file](../../reference/server_configuration/#docker).
After the Monkey Island docker container starts, you can access Monkey Island by pointing your browser at `https://localhost:5000`.
1. Move your `.crt` and `.key` files to the volume created in the previous step (`./monkey_island_data`).
## Configuring the server
1. Make sure that your `.crt` and `.key` files are readable and writeable only by you.
You can configure the server by mounting a volume and specifying a
[server configuration file](../../reference/server_configuration):
1. Create a directory for server configuration file, e.g. `monkey_island_data`:
```bash
chmod 600 ./monkey_island_data/<KEY_FILE>
chmod 600 ./monkey_island_data/<CRT_FILE>
mkdir ./monkey_island_data
chmod 700 ./monkey_island_data
```
1. Move your `server_config.json` file to `./monkey_island_data` directory.
1. 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"
```
1. Edit `./monkey_island_data/server_config.json` to configure Monkey Island
to use your certificate. Your config should look something like this:
### Start Monkey Island with user-provided certificate
```json {linenos=inline,hl_lines=["11-14"]}
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 that has been signed by a
private certificate authority.
1. Terminate the docker container it's already running.
1. Move your `.crt` and `.key` files to `./monkey_island_data` (directory created for the volume).
1. Make sure that your `.crt` and `.key` files are readable only by you.
```bash
chmod 600 <PATH_TO_KEY_FILE>
chmod 600 <PATH_TO_CRT_FILE>
```
1. Modify the [server configuration file](../../reference/server_configuration) and add the following lines:
```json
{
"data_dir": "/monkey_island_data",
"mongodb": {
"start_mongodb": false
},
"ssl_certificate": {
"ssl_certificate_file": "/monkey_island_data/<CRT_FILE>",
"ssl_certificate_key_file": "/monkey_island_data/<KEY_FILE>"
}
"ssl_certificate": {
"ssl_certificate_file": "/monkey_island_data/my_cert.crt",
"ssl_certificate_key_file": "/monkey_island_data/my_key.key"
}
}
```
1. Start/restart the Monkey Island server:
1. Run the container with a mounted volume, specify the path to the `server_config.json`:
```bash
sudo docker run \
--tty \
--interactive \
--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"
guardicore/monkey-island:VERSION --setup-only --server-config="/monkey_island_data/server_config.json"
```
1. Access the Monkey Island web UI by pointing your browser at
`https://localhost:5000`.
### 4. Accessing Monkey Island
### Change logging level
After the Monkey Island docker container starts, you can access Monkey Island by pointing your browser at `https://localhost:5000`.
1. Stop the docker container it's already running.
1. Modify the [server configuration file](../../reference/server_configuration) by adding the following lines:
```json
{
"log_level": "INFO"
}
```
1. 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"
```
1. Access the Monkey Island web UI by pointing your browser at
`https://localhost:5000`.
## Upgrading

47
docs/content/setup/linux.md
View File

@ -46,6 +46,14 @@ do, see the [FAQ]({{< ref
>}}) for more information.
{{% /notice %}}
## Configuring the server
You can configure the server by creating
a [server configuration file](../../reference/server_configuration) and
providing a path to it via command line parameters:
`./InfectionMonkey-v1.12.0.AppImage --server-config="/path/to/server_config.json"`
### Start Monkey Island with user-provided certificate
By default, Infection Monkey comes with a [self-signed SSL
@ -54,13 +62,7 @@ enterprise or other security-sensitive environments, it is recommended that the
user provide Infection Monkey with a certificate that has been signed by a
private certificate authority.
1. Run the Infection Monkey AppImage package with the `--setup-only` flag to
populate the `$HOME/.monkey_island` directory with a default
`server_config.json` file.
```bash
./InfectionMonkey-v1.12.0.AppImage --setup-only
```
1. Terminate the Island process if it's already running.
1. (Optional but recommended) Move your `.crt` and `.key` files to
`$HOME/.monkey_island`.
@ -73,6 +75,37 @@ private certificate authority.
```
1. Create a [server configuration file and provide the path to the certificate](../../reference/server_configuration).
Server configuration file should look something like:
```json
{
"ssl_certificate": {
"ssl_certificate_file": "$HOME/.monkey_island/my_cert.crt",
"ssl_certificate_key_file": "$HOME/.monkey_island/my_key.key"
}
}
```
1. Start Monkey Island by running the Infection Monkey AppImage package:
```bash
./InfectionMonkey-v1.12.0.AppImage --server-config="/path/to/server_config.json"
```
1. Access the Monkey Island web UI by pointing your browser at
`https://localhost:5000`.
### Change logging level
1. Terminate the Island process if it's already running.
1. Create a [server configuration file](../../reference/server_configuration).
Server configuration file should look something like:
```json
{
"log_level": "INFO"
}
```
1. Start Monkey Island by running the Infection Monkey AppImage package:
```bash

34
docs/content/setup/windows.md
View File

@ -26,6 +26,11 @@ do, see the [FAQ]({{< ref
"/faq/#i-updated-to-a-new-version-of-the-infection-monkey-and-im-being-asked-to-delete-my-existing-data-directory-why"
>}}) for more information.
{{% /notice %}}
>
## Configuring the server
You can configure the server by editing [the configuration file](../../reference/server_configuration) located
in installation directory. By default, the path should be `C:\Program Files\Guardicore\Monkey Island\monkey\monkey_island\cc\server_config.json`.
### Start Monkey Island with user-provided certificate
@ -34,14 +39,35 @@ enterprise or other security-sensitive environments, it is recommended that the
user provide Infection Monkey with a certificate that has been signed by a
private certificate authority.
1. If you haven't already, run the Monkey Island by clicking on the desktop
shortcut. This will populate MongoDB, as well as create and populate
`%AppData%\monkey_island`.
1. Stop the Monkey Island process.
1. (Optional but recommended) Move your `.crt` and `.key` files to `%AppData%\monkey_island`.
1. Create a [server configuration file and provide the path to the certificate](../../reference/server_configuration).
1. Modify the `server_config.json` (by default located in `C:\Program Files\Guardicore\Monkey Island\monkey\monkey_island\cc\server_config.json`) by adding the following lines:
```json
{
...
"ssl_certificate": {
"ssl_certificate_file": "%AppData%\\monkey_island\\my_cert.crt",
"ssl_certificate_key_file": "%AppData%\\monkey_island\\my_key.key"
},
...
}
```
1. Run the Monkey Island by clicking on the desktop shortcut.
1. Access the Monkey Island web UI by pointing your browser at
`https://localhost:5000`.
### Change logging level
1. Stop the Island server.
1. Modify the `server_config.json` (by default located in `C:\Program Files\Guardicore\Monkey Island\monkey\monkey_island\cc\server_config.json`) by adding the following lines:
```json
{
...
"log_level": "INFO",
...
}
```
1. Run the Monkey Island by clicking on the desktop shortcut.
1. Access the Monkey Island web UI by pointing your browser at
`https://localhost:5000`.