Merge pull request #217 from OpenCTI-Platform/issue/216

[docs] Add protect sensitive configuration documentation (#216)
OpenCTI-Platform · Nov 15, 2024 · a476b83 · a476b83
2 parents 5d53771 + ac1ba0b
commit a476b83
Show file tree

Hide file tree

Showing 7 changed files with 107 additions and 1 deletion.
diff --git a/docs/administration/assets/check_allow_modification_sensitive_conf.png b/docs/administration/assets/check_allow_modification_sensitive_conf.png
diff --git a/docs/administration/assets/platform_organization_sensitive.png b/docs/administration/assets/platform_organization_sensitive.png
diff --git a/docs/administration/assets/role_administrator_sensitive_chip.png b/docs/administration/assets/role_administrator_sensitive_chip.png
diff --git a/docs/administration/assets/role_allow_modification_sensitive_conf.png b/docs/administration/assets/role_allow_modification_sensitive_conf.png
diff --git a/docs/administration/protect-sensitive-configuration.md b/docs/administration/protect-sensitive-configuration.md
@@ -0,0 +1,88 @@
+# Protect sensitive configuration
+
+Some administrative actions and configuration modifications via the user interface can lead to data loss during ingestion, loss of data visibility for users, disruption of predefined automations, slowness
+, etc.
+To protect platforms from uncontrolled actions and make administrators' tasks easier, it is possible to restrict the modification of certain configurations to specific users.
+
+## Concept
+
+Protected elements are clearly identifiable, bounded by a block with an red border and a “Danger zone” chip.
+
+![platform_organization_sensitive.png](assets%2Fplatform_organization_sensitive.png)
+
+![role_administrator_sensitive_chip.png](assets%2Frole_administrator_sensitive_chip.png)
+
+When a configuration is sensitive, it remains visible to user with access rights, but all
+possible actions are disabled.
+
+The sensitive configurations identified are:
+- Modification of specific roles and groups
+- Activation/deactivation of inference rules
+- Main platform Organization modification
+- Modification of specific marking definitions
+- Enterprise Edition deactivation
+- File indexing pause/reset
+
+## Configuration
+
+The configuration is done in the application configuration file. By default (in ``default.json``), ``platform_protected_sensitive_config`` is enabled.
+
+It is possible to activate it around specific areas in the platform, as listed previously. It is also possible to choose which `Roles`, `Groups`  or `Marking definitions` will be protected.
+
+By default, built-in `Groups` , `Roles` and `Markings` are protected:
+- Roles ``default``, ``administrator`` and ``connector``
+- Groups ``default``, ``administrators`` and ``connectors``
+- Marking definitions ``TLP`` and ``PAP``
+
+Once the platform is running, a platform administrator can restrict access to the sensitive configuration scoped in the platform settings through a capability in the RBAC, via ``Settings > Security > Roles > Capabilities list``.
+Only users with `Allow modification of sensitive configuration` capability enabled will be able to modify sensitive configurations.
+
+![check_allow_modification_sensitive_conf.png](assets%2Fcheck_allow_modification_sensitive_conf.png)
+
+![role_allow_modification_sensitive_conf.png](assets%2Frole_allow_modification_sensitive_conf.png)
+
+## Recommended approach to give yourself access to danger zone
+
+1. With a user having the capability “Manage credentials” or “Bypass all capabilities”, go into parameters/security
+2. Create a new role called “Danger Zone Administration”
+3. Give it the capability “Allow modification of sensitive configuration”
+4. Create a group “Danger Zone Administrator”
+5. Add a user of your choice (yourself for instance): at this stage, you should be able to manage any area under danger zone.
+
+## Recommended approach to give administrator group access to danger zone
+
+1. Follow the above steps
+2. Once your user can manage the danger zone, go to the administrator group & assign the Danger Zone Administration role to it.
+3. All your admins should now be able to edit anything flagged as danger zone.
+
+## Disable the danger zone
+
+1. Edit your config file to apply this configuration
+
+```jsx
+"protected_sensitive_config": {
+      "enabled": false,
+      "markings": {
+        "enabled": true,
+        "protected_definitions": ["TLP:CLEAR", "TLP:GREEN", "TLP:AMBER", "TLP:AMBER+STRICT", "TLP:RED", "PAP:CLEAR", "PAP:GREEN", "PAP:AMBER", "PAP:AMBER"]
+      },
+      "groups": {
+        "enabled": true,
+        "protected_names": ["Administrators", "Connectors", "Default"]
+      },
+      "roles": {
+        "enabled": true,
+        "protected_names": ["Administrator", "Connector", "Default"]
+      },
+      "rules": {
+        "enabled": true
+      },
+      "ce_ee_toggle": {
+        "enabled": true
+      },
+      "file_indexing": {
+        "enabled": true
+      }
+    }
+  },
+```
diff --git a/docs/deployment/configuration.md b/docs/deployment/configuration.md
@@ -239,6 +239,22 @@ Here are the configuration keys, for both containers (environment variables) and
 | ai:model        | AI__MODEL            |               | Model to be used for text generation (depending on type)  |
 | ai:model_images | AI__MODEL_IMAGES     |               | Model to be used for image generation (depending on type) |
 
+#### Protect Sensitive Configurations
+
+| Parameter                                                               | Environment variable                                      | Default value                                                                                                            | Description                                          |
+|:------------------------------------------------------------------------|:----------------------------------------------------------|:-------------------------------------------------------------------------------------------------------------------------|:-----------------------------------------------------|
+| protected_sensitive_config:enabled                                      | PROTECT_SENSITIVE_CONFIG__ENABLED                         | true                                                                                                                     | Enable Protect Sensitive Configurations              |
+| protected_sensitive_config:markings:enabled                             | PROTECT_SENSITIVE_CONFIG__MARKINGS__ENABLED               | true                                                                                                                     | Protect Markings                                     |
+| protected_sensitive_config:markings:protected_definitions               | PROTECT_SENSITIVE_CONFIG__MARKINGS__PROTECTED_DEFINITIONS | ["TLP:CLEAR", "TLP:GREEN", "TLP:AMBER", "TLP:AMBER+STRICT", "TLP:RED", "PAP:CLEAR", "PAP:GREEN", "PAP:AMBER", "PAP:RED"] | List of protected Markings definitions               |
+| protected_sensitive_config:groups:enabled                               | PROTECT_SENSITIVE_CONFIG__GROUPS__ENABLED                 | true                                                                                                                     | Enabled Groups protection                            |
+| protected_sensitive_config:groups:protected_names                       | PROTECT_SENSITIVE_CONFIG__GROUPS__PROTECTED_NAMES         | ["Administrators", "Connectors", "Default"]                                                                              | List of protected Groups                             |
+| protected_sensitive_config:roles:enabled                                | PROTECT_SENSITIVE_CONFIG__ROLES__ENABLED                  | true                                                                                                                     | Enabled Roles protection                             |
+| protected_sensitive_config:roles:protected_names                        | PROTECT_SENSITIVE_CONFIG__ROLES__PROTECTED_NAMES          | ["Administrators", "Connectors", "Default"]                                                                              | List of protected Roles                              |
+| protected_sensitive_config:rules:enabled                                | PROTECT_SENSITIVE_CONFIG__RULES__ENABLED                  | true                                                                                                                     | Enabled Rules protection                             |
+| protected_sensitive_config:ce_ee_toggle:enabled                         | PROTECT_SENSITIVE_CONFIG__CE_EE_TOGGLE__ENABLED           | true                                                                                                                     | Enabled Enterpise/Community Editon toggle protection |
+| protected_sensitive_config:file_indexing:enabled                        | PROTECT_SENSITIVE_CONFIG__FILE_INDEXING__ENABLED          | true                                                                                                                     | Enabled File Indexing protection                     |
+| protected_sensitive_config:platform_organization:enabled                | PROTECT_SENSITIVE_CONFIG__PLATFORM_ORGANIZATION__ENABLED  | true                                                                                                                     | Enabled main Platform Organization protection        |
+
 #### Using a credentials provider
 
 In some cases, it may not be possible to put directly dependencies credentials directly in environment variables or static configuration. The platform can then retrieve them from a credentials provider. Here is the list of supported providers:

diff --git a/mkdocs.yml b/mkdocs.yml
@@ -187,7 +187,9 @@ nav:
       - Parameters: administration/parameters.md
       - Security:
         - Policies: administration/policies.md
-        - Users and RBAC: administration/users.md
+        - Users and RBAC:
+          - Users and RBAC: administration/users.md
+          - Protect sensitive configuration: administration/protect-sensitive-configuration.md
         - Data segregation:
           - Marking restriction: administration/segregation.md
           - Organization segregation: administration/organization-segregation.md