From b91076805e15050b3a863da39bf72e564a60f26b Mon Sep 17 00:00:00 2001 From: Shreya Malviya Date: Tue, 13 Aug 2024 17:53:31 +0530 Subject: [PATCH 1/8] Island: Update IslandConfigOptions' fields with descriptions --- .../cc/setup/island_config_options.py | 46 +++++++++++++++---- 1 file changed, 38 insertions(+), 8 deletions(-) diff --git a/monkey/monkey_island/cc/setup/island_config_options.py b/monkey/monkey_island/cc/setup/island_config_options.py index 18f503e21bd..2127a035a68 100644 --- a/monkey/monkey_island/cc/setup/island_config_options.py +++ b/monkey/monkey_island/cc/setup/island_config_options.py @@ -19,22 +19,52 @@ class MongoDBConfig(InfectionMonkeyBaseModel): - start_mongodb: bool = DEFAULT_START_MONGO_DB + start_mongodb: bool = Field( + default=DEFAULT_START_MONGO_DB, + description="If enabled, the MongoDB server will be started automatically with the Island.", + ) # TODO: rename redundant ssl_certificate_file and split the classes into idividual files class SSLCertificatesConfig(InfectionMonkeyBaseModel): ssl_certificate_file: Annotated[ - Path, Field(default=Path(DEFAULT_CRT_PATH)), BeforeValidator(expand_path) + Path, + Field( + default=Path(DEFAULT_CRT_PATH), + description="The path to the SSL certificate file that the Island server will use.", + ), + BeforeValidator(expand_path), ] ssl_certificate_key_file: Annotated[ - Path, Field(default=Path(DEFAULT_KEY_PATH)), BeforeValidator(expand_path) + Path, + Field( + default=Path(DEFAULT_KEY_PATH), + description="The path to the SSL certificate key file that the Island server will use.", + ), + BeforeValidator(expand_path), ] class IslandConfigOptions(InfectionMonkeyBaseModel): - data_dir: Annotated[Path, Field(default=DEFAULT_DATA_DIR), BeforeValidator(expand_path)] - log_level: str = DEFAULT_LOG_LEVEL - mongodb: MongoDBConfig = MongoDBConfig() - ssl_certificate: SSLCertificatesConfig = SSLCertificatesConfig() - island_port: int = DEFAULT_ISLAND_PORT + data_dir: Annotated[ + Path, + Field( + default=DEFAULT_DATA_DIR, + description="The directory where the Island will store runtime artifacts.", + ), + BeforeValidator(expand_path), + ] + log_level: str = Field( + default=DEFAULT_LOG_LEVEL, description="The threshold for the Island logger." + ) + mongodb: MongoDBConfig = Field( + default=MongoDBConfig(), description="The MongoDB configuration for the Island server." + ) + ssl_certificate: SSLCertificatesConfig = Field( + default=SSLCertificatesConfig(), + description="The SSL certificates configuration for the Island server.", + ) + island_port: int = Field( + default=DEFAULT_ISLAND_PORT, + description="The port on which the Island server should listen.", + ) From e3ae29ccca502ff77c99777b9d2a7fad75ea1e3b Mon Sep 17 00:00:00 2001 From: Shreya Malviya Date: Tue, 13 Aug 2024 19:05:10 +0530 Subject: [PATCH 2/8] Docs: Add server_config.json reference page --- .../content/reference/server-configuration.md | 153 ++++++++++++++---- 1 file changed, 121 insertions(+), 32 deletions(-) diff --git a/docs/content/reference/server-configuration.md b/docs/content/reference/server-configuration.md index f3c02dad899..29319e8c621 100644 --- a/docs/content/reference/server-configuration.md +++ b/docs/content/reference/server-configuration.md @@ -1,52 +1,141 @@ --- title: "Server configuration" -draft: true -pre: ' ' +draft: false +description: "Reference material for the server configuration" +pre: " " --- +{{< table_of_contents >}} -## Configuring the Monkey Island +## Configuration -The Monkey Island Server is configured through the `server_config.json` file. + -{{% notice info %}} -Refer to the [setup guides](../../setup/) to learn how to use -the `server_config.json` file for each deployment. -{{% /notice %}} + +| Property | Type | Required | Nullable | +| :----------------------------------- | :-------- | :------- | :------------- | +| [data\_dir](#data_dir) | `string` | Optional | cannot be null | +| [log\_level](#log_level) | `string` | Optional | cannot be null | +| [mongodb](#mongodb) | Merged | Optional | cannot be null | +| [ssl\_certificate](#ssl_certificate) | Merged | Optional | cannot be null | +| [island\_port](#island_port) | `integer` | Optional | cannot be null | -### Creating a configuration file +### data\_dir + +The directory where the Island will store runtime artifacts. + +`data_dir` + +* is optional + +* Type: `string` + +* cannot be null + +#### data\_dir Constraints + +The value of this string must be a valid path. + +#### data\_dir Default Value + +The default value for Windows is: + +```json +"%AppData%\\monkey_island" +``` + +The default value for Linux is: + +```json +"$HOME/.monkey_island" +``` + +### log\_level + +The threshold for the Island logger. + +`log_level` + +* is optional + +* Type: `string` + +* cannot be null + +#### log\_level Default Value + +The default value is: + +```json +"INFO" +``` + +### mongodb + +The MongoDB configuration for the Island server. + +`mongodb` + +* is optional + + +* Type: merged type ([Details](island_config_options-properties-mongodb.md)) + +* cannot be null + +#### mongodb Default Value + +The default value is: -Here's an example `server_config.json` with all options specified: ```json { - "island_port": 443, - "log_level": "DEBUG", - "ssl_certificate": { - "ssl_certificate_file": "", - "ssl_certificate_key_file": "" - }, - "mongodb": { - "start_mongodb": true - }, - "data_dir": "/monkey_island_data" + "start_mongodb": true } ``` -Only relevant options can be specified, for example: +### ssl\_certificate + +The SSL certificates configuration for the Island server. + +`ssl_certificate` + +* is optional + + +* Type: merged type ([Details](island_config_options-properties-ssl_certificate.md)) + +* cannot be null + +#### ssl\_certificate Default Value + +The default value is: + ```json { - "ssl_certificate": { - "ssl_certificate_file": "", - "ssl_certificate_key_file": "" - } + "ssl_certificate_file": "C:\\Users\\smalviya\\Desktop\\monkey-ecosystem\\infection_monkey\\monkey_island\\cc\\server.crt", + "ssl_certificate_key_file": "C:\\Users\\smalviya\\Desktop\\monkey-ecosystem\\infection_monkey\\monkey_island\\cc\\server.key" } ``` -### Configuration options +### island\_port + +The port on which the Island server should listen. + +`island_port` -See setup instructions for your operating system to understand how to apply these. +* is optional - - `island_port` - Port used by the Island C&C server. Default is `443`. - - `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. +* Type: `integer` + +* cannot be null + +#### island\_port Default Value + +The default value is: + +```json +443 +``` From c6baabc1b3e19d1e7d06cf51a754721adebddf23 Mon Sep 17 00:00:00 2001 From: Shreya Malviya Date: Tue, 13 Aug 2024 20:21:36 +0530 Subject: [PATCH 3/8] Docs: Update server_config.json reference page --- .../content/reference/server-configuration.md | 87 ++++++++++++++++--- 1 file changed, 77 insertions(+), 10 deletions(-) diff --git a/docs/content/reference/server-configuration.md b/docs/content/reference/server-configuration.md index 29319e8c621..f4e8e51efc5 100644 --- a/docs/content/reference/server-configuration.md +++ b/docs/content/reference/server-configuration.md @@ -1,7 +1,7 @@ --- title: "Server configuration" draft: false -description: "Reference material for the server configuration" +description: "Reference material for the server_config.json file" pre: " " --- {{< table_of_contents >}} @@ -14,13 +14,12 @@ through https://github.com/adobe/jsonschema2md. It was then modified by hand to remove extraneous information. --> - | Property | Type | Required | Nullable | | :----------------------------------- | :-------- | :------- | :------------- | | [data\_dir](#data_dir) | `string` | Optional | cannot be null | | [log\_level](#log_level) | `string` | Optional | cannot be null | -| [mongodb](#mongodb) | Merged | Optional | cannot be null | -| [ssl\_certificate](#ssl_certificate) | Merged | Optional | cannot be null | +| [mongodb](#mongodb) | `object` | Optional | cannot be null | +| [ssl\_certificate](#ssl_certificate) | `object` | Optional | cannot be null | | [island\_port](#island_port) | `integer` | Optional | cannot be null | ### data\_dir @@ -81,11 +80,31 @@ The MongoDB configuration for the Island server. * is optional - -* Type: merged type ([Details](island_config_options-properties-mongodb.md)) +* Type: `object` * cannot be null +#### mongodb Properties +**_start\_mongodb_** + +If enabled, the MongoDB server will be started automatically with the Island. + +`start_mongodb` + +* is optional + +* Type: `boolean` + +* cannot be null + +_start\_mongodb Default Value_ + +The default value is: + +```json +true +``` + #### mongodb Default Value The default value is: @@ -104,19 +123,67 @@ The SSL certificates configuration for the Island server. * is optional - -* Type: merged type ([Details](island_config_options-properties-ssl_certificate.md)) +* Type: `object` + +* cannot be null + +#### ssl\_certificate Properties +**_ssl\_certificate\_file_** + +The path to the SSL certificate file that the Island server will use. + +`ssl_certificate_file` + +* is optional + +* Type: `string` + +* cannot be null + +_ssl\_certificate\_file Constraints_ + +The value of this string must be a valid path. + +_ssl\_certificate\_file Default Value_ + +The default value is: + +```json +"\\monkey_island\\cc\\server.crt" +``` + +**_ssl\_certificate\_key\_file_** + +The path to the SSL certificate key file that the Island server will use. + +`ssl_certificate_key_file` + +* is optional + +* Type: `string` * cannot be null +_ssl\_certificate\_key\_file Constraints_ + +The value of this string must be a valid path. + +_ssl\_certificate\_key\_file Default Value_ + +The default value is: + +```json +"\\monkey_island\\cc\\server.key" +``` + #### ssl\_certificate Default Value The default value is: ```json { - "ssl_certificate_file": "C:\\Users\\smalviya\\Desktop\\monkey-ecosystem\\infection_monkey\\monkey_island\\cc\\server.crt", - "ssl_certificate_key_file": "C:\\Users\\smalviya\\Desktop\\monkey-ecosystem\\infection_monkey\\monkey_island\\cc\\server.key" + "ssl_certificate_file": "\\monkey_island\\cc\\server.crt", + "ssl_certificate_key_file": "\\monkey_island\\cc\\server.key" } ``` From 13059e73b3a53c46d1e819e2aa7ad360c3bdb135 Mon Sep 17 00:00:00 2001 From: Shreya Malviya Date: Wed, 14 Aug 2024 13:33:09 +0530 Subject: [PATCH 4/8] Docs: Fix formatting in server_config.json reference page --- docs/content/reference/server-configuration.md | 18 ++++++++---------- 1 file changed, 8 insertions(+), 10 deletions(-) diff --git a/docs/content/reference/server-configuration.md b/docs/content/reference/server-configuration.md index f4e8e51efc5..0feb54b8bad 100644 --- a/docs/content/reference/server-configuration.md +++ b/docs/content/reference/server-configuration.md @@ -84,8 +84,7 @@ The MongoDB configuration for the Island server. * cannot be null -#### mongodb Properties -**_start\_mongodb_** +#### start\_mongodb If enabled, the MongoDB server will be started automatically with the Island. @@ -97,7 +96,7 @@ If enabled, the MongoDB server will be started automatically with the Island. * cannot be null -_start\_mongodb Default Value_ +**start\_mongodb Default Value** The default value is: @@ -127,8 +126,7 @@ The SSL certificates configuration for the Island server. * cannot be null -#### ssl\_certificate Properties -**_ssl\_certificate\_file_** +#### ssl\_certificate\_file The path to the SSL certificate file that the Island server will use. @@ -140,11 +138,11 @@ The path to the SSL certificate file that the Island server will use. * cannot be null -_ssl\_certificate\_file Constraints_ +**ssl\_certificate\_file Constraints** The value of this string must be a valid path. -_ssl\_certificate\_file Default Value_ +**ssl\_certificate\_file Default Value** The default value is: @@ -152,7 +150,7 @@ The default value is: "\\monkey_island\\cc\\server.crt" ``` -**_ssl\_certificate\_key\_file_** +#### ssl\_certificate\_key\_file The path to the SSL certificate key file that the Island server will use. @@ -164,11 +162,11 @@ The path to the SSL certificate key file that the Island server will use. * cannot be null -_ssl\_certificate\_key\_file Constraints_ +**ssl\_certificate\_key\_file Constraints** The value of this string must be a valid path. -_ssl\_certificate\_key\_file Default Value_ +**ssl\_certificate\_key\_file Default Value** The default value is: From f57b218891372ff781cbb7f03bf820bd6add2723 Mon Sep 17 00:00:00 2001 From: Shreya Malviya Date: Wed, 14 Aug 2024 13:35:34 +0530 Subject: [PATCH 5/8] Island: Update IslandConfigOptions.log_level description --- monkey/monkey_island/cc/setup/island_config_options.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/monkey/monkey_island/cc/setup/island_config_options.py b/monkey/monkey_island/cc/setup/island_config_options.py index 2127a035a68..45117f7fbee 100644 --- a/monkey/monkey_island/cc/setup/island_config_options.py +++ b/monkey/monkey_island/cc/setup/island_config_options.py @@ -55,7 +55,7 @@ class IslandConfigOptions(InfectionMonkeyBaseModel): BeforeValidator(expand_path), ] log_level: str = Field( - default=DEFAULT_LOG_LEVEL, description="The threshold for the Island logger." + default=DEFAULT_LOG_LEVEL, description="The log level for the Island's logger." ) mongodb: MongoDBConfig = Field( default=MongoDBConfig(), description="The MongoDB configuration for the Island server." From 362638f7481222f043ae021944613152bd9241dd Mon Sep 17 00:00:00 2001 From: Shreya Malviya Date: Wed, 14 Aug 2024 13:36:19 +0530 Subject: [PATCH 6/8] Docs: Update 'log_level' description in server_config.json reference page --- docs/content/reference/server-configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/reference/server-configuration.md b/docs/content/reference/server-configuration.md index 0feb54b8bad..82060422b52 100644 --- a/docs/content/reference/server-configuration.md +++ b/docs/content/reference/server-configuration.md @@ -54,7 +54,7 @@ The default value for Linux is: ### log\_level -The threshold for the Island logger. +The log level for the Island's logger. `log_level` From bdbc1ffb07e59ed96a13d467205ef4f7bfb56ed9 Mon Sep 17 00:00:00 2001 From: Shreya Malviya Date: Fri, 16 Aug 2024 09:31:44 +0530 Subject: [PATCH 7/8] Docs: Remove repeated default value inserver_config.json reference page --- .../content/reference/server-configuration.md | 21 ------------------- 1 file changed, 21 deletions(-) diff --git a/docs/content/reference/server-configuration.md b/docs/content/reference/server-configuration.md index 82060422b52..fc67ad72632 100644 --- a/docs/content/reference/server-configuration.md +++ b/docs/content/reference/server-configuration.md @@ -104,16 +104,6 @@ The default value is: true ``` -#### mongodb Default Value - -The default value is: - -```json -{ - "start_mongodb": true -} -``` - ### ssl\_certificate The SSL certificates configuration for the Island server. @@ -174,17 +164,6 @@ The default value is: "\\monkey_island\\cc\\server.key" ``` -#### ssl\_certificate Default Value - -The default value is: - -```json -{ - "ssl_certificate_file": "\\monkey_island\\cc\\server.crt", - "ssl_certificate_key_file": "\\monkey_island\\cc\\server.key" -} -``` - ### island\_port The port on which the Island server should listen. From 6f7b7577f310977ba593e987046f2bc0ea9739a0 Mon Sep 17 00:00:00 2001 From: Shreya Malviya Date: Fri, 16 Aug 2024 09:32:24 +0530 Subject: [PATCH 8/8] Docs: Add example in server_config.json reference page --- docs/content/reference/server-configuration.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/docs/content/reference/server-configuration.md b/docs/content/reference/server-configuration.md index fc67ad72632..60f1373e29b 100644 --- a/docs/content/reference/server-configuration.md +++ b/docs/content/reference/server-configuration.md @@ -183,3 +183,20 @@ The default value is: ```json 443 ``` + +### `server_config.json` example + +``` +{ + "data_dir": "/home/user/.monkey_island", + "log_level": "INFO", + "mongodb": { + "start_mongodb": true + }, + "ssl_certificate": { + "ssl_certificate_file": "/home/user/infection_monkey_installation/monkey_island/cc/server.crt", + "ssl_certificate_key_file": "/home/user/infection_monkey_installation/monkey_island/cc/server.crt", + }, + "island_port": 443 +} +```