From bd32697be0b475cf441d5e34c9256075065b7d1f Mon Sep 17 00:00:00 2001 From: aetter Date: Fri, 6 Nov 2020 15:11:57 -0800 Subject: [PATCH 1/4] First cut at security for alerting --- docs/alerting/api.md | 110 ++++++++++++++++++-- docs/alerting/cron.md | 2 +- docs/alerting/monitors.md | 59 ++++++----- docs/alerting/security-roles.md | 48 --------- docs/alerting/security.md | 79 ++++++++++++++ docs/alerting/settings.md | 10 +- docs/security/access-control/permissions.md | 26 +++++ docs/security/access-control/users-roles.md | 3 + 8 files changed, 249 insertions(+), 88 deletions(-) delete mode 100644 docs/alerting/security-roles.md create mode 100644 docs/alerting/security.md diff --git a/docs/alerting/api.md b/docs/alerting/api.md index ff057a93..fa18eb16 100644 --- a/docs/alerting/api.md +++ b/docs/alerting/api.md @@ -2,7 +2,7 @@ layout: default title: API parent: Alerting -nav_order: 3 +nav_order: 15 --- # Alerting API @@ -829,6 +829,96 @@ PUT _opendistro/_alerting/destinations/ ``` +--- + +## Get destination + +Retrieve one destination. + +#### Requests + +```json +GET _opendistro/_alerting/destinations/ +``` + +#### Sample response + +```json +{ + "totalDestinations": 1, + "destinations": [{ + "id": "1a2a3a4a5a6a7a", + "type": "slack", + "name": "sample-destination", + "user": { + "name": "psantos", + "backend_roles": [ + "human-resources" + ], + "roles": [ + "alerting_full_access", + "hr-role" + ], + "custom_attribute_names": [] + }, + "schema_version": 3, + "seq_no": 0, + "primary_term": 6, + "last_update_time": 1603943261722, + "slack": { + "url": "https://example.com" + } + } + ] +} +``` + + +--- + +## Get destinations + +Retrieve all destinations. + +#### Requests + +```json +GET _opendistro/_alerting/destinations +``` + +#### Sample response + +```json +{ + "totalDestinations": 1, + "destinations": [{ + "id": "1a2a3a4a5a6a7a", + "type": "slack", + "name": "sample-destination", + "user": { + "name": "psantos", + "backend_roles": [ + "human-resources" + ], + "roles": [ + "alerting_full_access", + "hr-role" + ], + "custom_attribute_names": [] + }, + "schema_version": 3, + "seq_no": 0, + "primary_term": 6, + "last_update_time": 1603943261722, + "slack": { + "url": "https://example.com" + } + } + ] +} +``` + + --- ## Delete destination @@ -904,7 +994,7 @@ PUT _opendistro/_alerting/destinations/email_accounts/ "port": 465, "method": "ssl" } -``` +``` #### Sample response ```json { @@ -1045,7 +1135,7 @@ POST _opendistro/_alerting/destinations/email_accounts/_search ``` --- - + ## Create email group #### Request @@ -1056,7 +1146,7 @@ POST _opendistro/_alerting/destinations/email_groups "name": "example_email_group", "emails": [{ "email": "example@email.com" - }] + }] } ``` @@ -1090,7 +1180,7 @@ PUT _opendistro/_alerting/destinations/email_groups/ "name": "example_email_group", "emails": [{ "email": "example@email.com" - }] + }] } ``` #### Sample response @@ -1112,7 +1202,7 @@ PUT _opendistro/_alerting/destinations/email_groups/ } } ``` - + ## Get email group #### Request @@ -1122,7 +1212,7 @@ GET _opendistro/_alerting/destinations/email_groups/ "name": "example_email_group", "emails": [{ "email": "example@email.com" - }] + }] } ``` #### Sample response @@ -1144,7 +1234,7 @@ GET _opendistro/_alerting/destinations/email_groups/ } } ``` - + ## Delete email group #### Request @@ -1170,7 +1260,7 @@ DELETE _opendistro/_alerting/destinations/email_groups/ "_primary_term" : 2 } ``` - + ## Search email group #### Request @@ -1235,4 +1325,4 @@ POST _opendistro/_alerting/destinations/email_groups/_search } } ``` ---- \ No newline at end of file +--- diff --git a/docs/alerting/cron.md b/docs/alerting/cron.md index 8c2d74d9..dff7e58b 100644 --- a/docs/alerting/cron.md +++ b/docs/alerting/cron.md @@ -1,7 +1,7 @@ --- layout: default title: Cron -nav_order: 5 +nav_order: 20 parent: Alerting has_children: false --- diff --git a/docs/alerting/monitors.md b/docs/alerting/monitors.md index 477c208c..78c6ed26 100644 --- a/docs/alerting/monitors.md +++ b/docs/alerting/monitors.md @@ -32,7 +32,7 @@ Destination | A reusable location for an action, such as Amazon Chime, Slack, or 1. Choose **Alerting**, **Destinations**, **Add destination**. 1. Specify a name for the destination so that you can identify it later. -1. For **Type**, choose Slack, Amazon Chime, custom webhook, or [email](#email-as-a-destination). +1. For **Type**, choose Slack, Amazon Chime, custom webhook, or [email](#email-as-a-destination). For Email type, refer to [Email as a destination](#email-as-a-destination) section below. For all other types, specify the webhook URL. For more information about webhooks, see the documentation for [Slack](https://api.slack.com/incoming-webhooks) and [Chime](https://docs.aws.amazon.com/chime/latest/ug/webhooks.html). @@ -40,56 +40,61 @@ For custom webhooks, you must specify more information: parameters and headers. This information is stored in plain text in the Elasticsearch cluster. We will improve this design in the future, but for now, the encoded credentials (which are neither encrypted nor hashed) might be visible to other Elasticsearch users. + ### Email as a destination -To send or receive an alert notification as an email, first select **Email** as the destination **Type** for the alert. Next, you must add at least one sender and a recipient. We also recommend adding email groups if you want to notify more than a few people of an alert. You can configure senders and recipients using **Manage senders** and **Manage email groups**. + +To send or receive an alert notification as an email, choose **Email** as the destination type. Next, add at least one sender and recipient. We recommend adding email groups if you want to notify more than a few people of an alert. You can configure senders and recipients using **Manage senders** and **Manage email groups**. + #### Manage senders -Manage senders allows you to configure and manage **Sender** email addresses. Senders are email accounts from where the alert notification is sent to different recipients or email groups. + +Senders are email accounts from which the alerting plugin sends notifications. To configure a sender email, do the following: -1. Once you choose **Email** as the destination **Type**, choose **Manage senders**, under **Settings**. You can also do this using the **Actions** button on the top right of the **Destinations** page. -1. In the **Manage email senders** modal window, choose **Add sender**, **New sender**. Multiple senders can be added one at a time. -1. Enter a unique **Sender name**. -1. Enter the **Email address**, SMTP **Host** (e.g. `smtp.gmail.com` for a Gmail account), and the **Port** number. -1. You can choose to use an **Encryption method** or leave it as **None**. However, most email providers require SSL or TLS and this requires you to add a username and password to the Elasticsearch keystore. Refer to [Authenticate sender account](#authenticate-sender-account) to learn more. -1. Choose **Save** to save the configuration and create the sender. You can create a sender even before you enter your credentials for SSL or TLS. However, you must [authenticate each sender account](#authenticate-sender-account) with credentials before you use the destination to send your alert. +1. After you choose **Email** as the destination type, choose **Manage senders**. +1. Choose **Add sender**, **New sender** and enter a unique name. +1. Enter the email address, SMTP host (e.g. `smtp.gmail.com` for a Gmail account), and the port. +1. Choose an encryption method, or use the default value of **None**. However, most email providers require SSL or TLS, which requires a username and password in Elasticsearch keystore. Refer to [Authenticate sender account](#authenticate-sender-account) to learn more. +1. Choose **Save** to save the configuration and create the sender. You can create a sender even before you add your credentials to the Elasticsearch keystore. However, you must [authenticate each sender account](#authenticate-sender-account) before you use the destination to send your alert. + +You can reuse senders across many different destinations, but each destination only supports one sender. + -Once the sender is created, the sender account is available to be selected when creating an email destination. You can reuse senders across many different destinations, but each destination only supports one sender. +#### Manage email groups or recipients -#### Manage email groups or recipients -Use email groups to create and manage reusable lists of email addresses. For example, one alert might email the DevOps team, whereas another might email the DevOps team and the engineering team. +Use email groups to create and manage reusable lists of email addresses. For example, one alert might email the DevOps team, whereas another might email the executive team and the engineering team. -You can enter individual email addresses, or an email group in the **Recipients** field. For email groups, you can pre-create a group using **Manage email groups**. +You can enter individual email addresses or an email group in the **Recipients** field. -To create and manage email groups, do the following: -1. Once you select **Email** as the destination **Type**, choose **Manage email groups**, under **Settings**. Then choose **Add email group**, **New email group**. You can also do this using the **Actions** button on the top right of the **Destinations** page. -1. Enter a unique **Email group name**. -1. For recipient emails, enter any number of email addresses. +1. After you choose **Email** as the destination type, choose **Manage email groups**. Then choose **Add email group**, **New email group**. +1. Enter a unique name. +1. For recipient emails, enter any number of email addresses. 1. Choose **Save**. -You can view the list of all email destinations you created on the **Destinations** landing page. The **Actions** button on the top right of the **Destinations** page allows you to mange email senders and email groups from this page. #### Authenticate sender account -You must authenticate each sender account with credentials before you send an alert notification from that account to recipients or email groups. You can enter these credentials in the Elasticsearch keystore using the CLI. Run the following commands (in your Elasticsearch directory) to enter your username and password. The `` is the name you entered for **Sender**. +If your email provider requires SSL or TLS, you must authenticate each sender account before you can send an email. Enter these credentials in the Elasticsearch keystore using the CLI. Run the following commands (in your Elasticsearch directory) to enter your username and password. The `` is the name you entered for **Sender** earlier. ```bash -./bin/elasticsearch-keystore add opendistro.alerting.destination.email..username +./bin/elasticsearch-keystore add opendistro.alerting.destination.email..username ./bin/elasticsearch-keystore add opendistro.alerting.destination.email..password ``` -**Note**: The keystore settings are node-specific. You must run these commands on each node. +**Note**: Keystore settings are node-specific. You must run these commands on each node. {: .note} -To change or update your credentials (once you've added them in the keystore settings for every node), you can call the reload API to ensure that your new changes are automatically updated on every node. Run this command to call the reload API: +To change or update your credentials (after you've added them to the keystore on every node), call the reload API to automatically update those credentials without restarting Elasticsearch: + ```json -POST _nodes/reload_secure_settings +POST _nodes/reload_secure_settings { - "secure_settings_password": "1234" + "secure_settings_password": "1234" } ``` + --- ## Create monitors @@ -98,7 +103,7 @@ POST _nodes/reload_secure_settings 1. Specify a name and schedule for the monitor. The anomaly detection option is for pairing with the anomaly detection plugin. See [Anomaly Detection](../../ad/). -For anomaly detector, choose an appropriate schedule for the monitor based on the detector interval. Otherwise, the alerting monitor may miss reading the results. +For anomaly detector, choose an appropriate schedule for the monitor based on the detector interval. Otherwise, the alerting monitor might miss reading the results. For example, assume you set the monitor interval and the detector interval as 5 minutes, and you start the detector at 12:00. If an anomaly is detected at 12:05, it might be available at 12:06 because of the delay between writing the anomaly and it being available for queries. The monitor reads the anomaly results between 12:00 and 12:05, so it does not get the anomaly results available at 12:06. @@ -108,6 +113,9 @@ When you create a monitor using Kibana, the anomaly detector plugin generates a Whenever you update a detector’s interval, make sure to update the associated monitor interval as well, as the anomaly detection plugin does not do this automatically. 1. Choose one or more indices. You can also use `*` as a wildcard to specify an index pattern. + + If you use the security plugin, you can only choose indices that you have permission to access. For details, see [Alerting security](../security/). + 1. Define the monitor in one of three ways: visually, using a query, or using an anomaly detector. - Visual definition works well for monitors that you can define as "some value is above or below some threshold for some amount of time." @@ -200,6 +208,7 @@ A return value of true means the trigger condition has been met, and the trigger The **Info** link next to **Trigger condition** contains a useful summary of the variables and results available to your query. {: .tip } + ### Anomaly detector For **Trigger type**, choose **Anomaly detector grade and confidence**. diff --git a/docs/alerting/security-roles.md b/docs/alerting/security-roles.md deleted file mode 100644 index cf3c2b0f..00000000 --- a/docs/alerting/security-roles.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -layout: default -title: Security Roles -nav_order: 4 -parent: Alerting -has_children: false ---- - -# Security roles - -If you use the security plugin alongside alerting, you might want to limit certain users to certain permissions. For example, you might want some users to only be able to view and acknowledge alerts, while others can create monitors and destinations. This page contains some sample roles for common use cases. - -Mix and match these roles to give users the permissions they need to use the alerting feature. - - -## View and acknowledge alerts - -1. In Kibana, choose **Security**, **Roles**. -1. Create a new security role named `alerting_alerts`. -1. In the **Index Permissions** tab, choose **Add index permissions**. -1. Specify the `.opendistro-alerting-alerts` index pattern. -1. Add the `crud` action group and **Save role definition**. -1. Choose **Role Mappings**. -1. Map the `alerting_alerts` role to the desired users or backend roles. - - -## Create, update, and delete monitors and destinations - -1. In Kibana, choose **Security**, **Roles**. -1. Create a new security role named `alerting_monitors`. -1. In the **Index Permissions** tab, choose **Add index permissions**. -1. Specify the `.opendistro-alerting-config` index pattern. -1. Add the `crud` action group and **Save role definition**. -1. Choose **Role Mappings**. -1. Map the `alerting_monitors` role to the desired users or backend roles. - - -## Read-only - -1. In Kibana, choose **Security**, **Roles**. -1. Create a new security role named `alerting_read_only`. -1. In the **Index Permissions** tab, choose **Add index permissions**. -1. Specify the `.opendistro-alerting-alerts` index pattern. -1. Choose **Add index pattern** to add a second index pattern. -1. Specify the `.opendistro-alerting-config` index pattern. -1. Choose the `read` action group and **Save role definition**. -1. Choose **Role Mappings**. -1. Map the `alerting_read_only` role to the desired users or backend roles. diff --git a/docs/alerting/security.md b/docs/alerting/security.md new file mode 100644 index 00000000..be74d929 --- /dev/null +++ b/docs/alerting/security.md @@ -0,0 +1,79 @@ +--- +layout: default +title: Alerting Security +nav_order: 10 +parent: Alerting +has_children: false +--- + +# Alerting security + +If you use the security plugin alongside alerting, you might want to limit certain users to certain actions. For example, you might want some users to only be able to view and acknowledge alerts, while others can modify monitors and destinations. + + +## Basic permissions + +The security plugin has three built-in roles that cover most alerting use cases: `alerting_read_access`, `alerting_ack_alerts`, and `alerting_full_access`. For descriptions of each, see [Predefined roles](../../security/access-control/users-roles/#predefined-roles). + +If these roles don't meet your needs, mix and match individual alerting [permissions](../../security/access-control/permissions/) to suit your use case. Each action corresponds to an operation in the REST API. For example, the `cluster:admin/opendistro/alerting/destination/delete` permission lets you delete destinations. + + +## How monitors access data + +Monitors run with the permissions of the user who created or last modified them. For example, consider the user `jdoe`, who works at a chain of retail stores. `jdoe` has two roles. Together, these two roles allow read access to three indices: `store1-returns`, `store2-returns`, `store3-returns`. + +`jdoe` creates a monitor that sends an email to management whenever the number of returns across across all three indices exceeds 40 per hour. + +Later, the user `psantos` wants to edit the monitor to run every two hours, but `psantos` only has access to `store1-returns`. To make the change, `psantos` has two options: + +- Update the monitor so that it only checks `store1-returns`. +- Ask an administrator for read access to the other two indices. + +After making the change, the monitor now runs with the same permissions as `psantos`, including any [document-level security](../../security/access-control/document-level-security/) queries, [excluded fields](../../security/access-control/field-level-security/), and [masked fields](../../security/access-control/field-masking/). If you use an extraction query to define your monitor, use the **Run** button to ensure that the response includes the fields you need. + + +## (Advanced) Limit access by backend role + +Out of the box, the alerting plugin has no concept of ownership. For example, if you have the `cluster:admin/opendistro/alerting/monitor/write` permission, you can edit *all* monitors, regardless of whether or not you created them. If a small number of trusted users manage your monitors and destinations, this lack of ownership generally isn't a problem. A larger organization might need to segment access by backend role. + +First, make sure that your users have the appropriate [backend roles](../../security/access-control/). Backend roles usually come from an [LDAP server](../../security/configuration/ldap/) or [SAML provider](../../security/configuration/saml/), but if you use the internal user database, you can use the REST API to [add them manually](../../security/access-control/api/#create-user). + +Next, enable the following setting: + +```json +PUT _cluster/settings +{ + "transient": { + "opendistro.alerting.filter_by_backend_roles": "true" + } +} +``` + +Now when users view alerting resources in Kibana (or make REST API calls), they only see monitors and destinations created by users who share *at least one* backend role. For example, consider three users: `jdoe`, `jroe`, and `psantos`, all of whom have full access to alerting. + +`jdoe` and `jroe` are on the same team at work and both have the `analyst` backend role. `psantos` has the `human-resources` backend role. + +If `jdoe` creates a monitor, `jroe` can see and modify it. `psantos` can't. If that monitor generates an alert, the situation is the same: `jroe` can see and acknowledge it, but `psantos` can't. If `psantos` creates a destination---you guessed it---neither `jdoe` nor `jroe` can see or modify it. + + +## (Advanced) Limit access by individual + +If you only want users to be able to see and modify their own monitors and destinations, duplicate the `alerting_full_access` role and add the following [DLS query](../../security/access-control/document-level-security/) to it: + +```json +{ + "bool": { + "should": [{ + "match": { + "monitor.created_by": "${user.name}" + } + }, { + "match": { + "destination.created_by": "${user.name}" + } + }] + } +} +``` + +Then use this new role for all alerting users. diff --git a/docs/alerting/settings.md b/docs/alerting/settings.md index 12cc52f0..61bea217 100644 --- a/docs/alerting/settings.md +++ b/docs/alerting/settings.md @@ -2,7 +2,7 @@ layout: default title: Management parent: Alerting -nav_order: 2 +nav_order: 5 --- # Management @@ -40,16 +40,18 @@ Setting | Default | Description `opendistro.alerting.action_throttle_max_value` | 24h | The maximum amount of time you can set for action throttling. By default, this value displays as 1440 minutes in Kibana. `opendistro.alerting.input_timeout` | 30s | How long the monitor can take to issue the search request. `opendistro.alerting.bulk_timeout` | 120s | How long the monitor can write alerts to the alert index. -`opendistro.alerting.alert_backoff_count` | 2 | The number of retries for writing alerts before the operation fails. +`opendistro.alerting.alert_backoff_count` | 3 | The number of retries for writing alerts before the operation fails. `opendistro.alerting.alert_backoff_millis` | 50ms | The amount of time to wait between retries---increases exponentially after each failed retry. `opendistro.alerting.alert_history_rollover_period` | 12h | How frequently to check whether the `.opendistro-alerting-alert-history-write` alias should roll over to a new history index and whether the Alerting plugin should delete any history indices. `opendistro.alerting.move_alerts_backoff_millis` | 250 | The amount of time to wait between retries---increases exponentially after each failed retry. `opendistro.alerting.move_alerts_backoff_count` | 3 | The number of retries for moving alerts to a deleted state after their monitor or trigger has been deleted. `opendistro.alerting.monitor.max_monitors` | 1000 | The maximum number of monitors users can create. -`opendistro.alerting.alert_history_max_age` | 24h | The oldest document the `.opendistro-alert-history-` index should keep. +`opendistro.alerting.alert_history_max_age` | 30d | The oldest document the `.opendistro-alert-history-` index should keep. `opendistro.alerting.alert_history_max_docs` | 1000 | The maximum number of documents the `.opendistro-alert-history-` index should keep. `opendistro.alerting.alert_history_enabled` | true | Whether to create `.opendistro-alerting-alert-history-` indices. -`opendistro.alerting.alert_history_retention_period` | 30d | The amount of time to keep history indices before automatically deleting them. +`opendistro.alerting.alert_history_retention_period` | 60d | The amount of time to keep history indices before automatically deleting them. +`opendistro.alerting.destination.allow_list` | ["chime", "slack", "custom_webhook", "email", "test_action"] | The list of allowed destinations. If you don't want to allow users to a certain type of destination, you can remove it from this list, but we recommend leaving this setting as-is. +`opendistro.alerting.filter_by_backend_roles` | "false" | Restricts access to monitors by backend role. See [Alerting security](../security/). `opendistro.scheduled_jobs.sweeper.period` | 5m | The alerting feature uses its "job sweeper" component to periodically check for new or updated jobs. This setting is the rate at which the sweeper checks to see if any jobs (monitors) have changed and need to be rescheduled. `opendistro.scheduled_jobs.sweeper.page_size` | 100 | The page size for the sweeper. You shouldn't need to change this value. `opendistro.scheduled_jobs.sweeper.backoff_millis` | 50ms | The amount of time the sweeper waits between retries---increases exponentially after each failed retry. diff --git a/docs/security/access-control/permissions.md b/docs/security/access-control/permissions.md index 08d75464..29bd8ef5 100644 --- a/docs/security/access-control/permissions.md +++ b/docs/security/access-control/permissions.md @@ -21,6 +21,32 @@ Rather than creating new action groups from individual permissions, you can ofte - cluster:admin/ingest/pipeline/put - cluster:admin/ingest/pipeline/simulate - cluster:admin/ingest/processor/grok/get +- cluster:admin/opendistro/ad/detector/delete +- cluster:admin/opendistro/ad/detector/jobmanagement +- cluster:admin/opendistro/ad/detector/run +- cluster:admin/opendistro/ad/detector/search +- cluster:admin/opendistro/ad/detector/stats +- cluster:admin/opendistro/ad/detector/write +- cluster:admin/opendistro/ad/detectors/get +- cluster:admin/opendistro/ad/result/search +- cluster:admin/opendistro/alerting/alerts/ack +- cluster:admin/opendistro/alerting/alerts/get +- cluster:admin/opendistro/alerting/destination/delete +- cluster:admin/opendistro/alerting/destination/email_account/delete +- cluster:admin/opendistro/alerting/destination/email_account/get +- cluster:admin/opendistro/alerting/destination/email_account/search +- cluster:admin/opendistro/alerting/destination/email_account/write +- cluster:admin/opendistro/alerting/destination/email_group/delete +- cluster:admin/opendistro/alerting/destination/email_group/get +- cluster:admin/opendistro/alerting/destination/email_group/search +- cluster:admin/opendistro/alerting/destination/email_group/write +- cluster:admin/opendistro/alerting/destination/get +- cluster:admin/opendistro/alerting/destination/write +- cluster:admin/opendistro/alerting/monitor/delete +- cluster:admin/opendistro/alerting/monitor/execute +- cluster:admin/opendistro/alerting/monitor/get +- cluster:admin/opendistro/alerting/monitor/search +- cluster:admin/opendistro/alerting/monitor/write - cluster:admin/reindex/rethrottle - cluster:admin/repository/delete - cluster:admin/repository/get diff --git a/docs/security/access-control/users-roles.md b/docs/security/access-control/users-roles.md index 80569a0a..87fa5cc5 100644 --- a/docs/security/access-control/users-roles.md +++ b/docs/security/access-control/users-roles.md @@ -106,6 +106,9 @@ The security plugin includes several predefined roles that serve as useful defau Role | Description :--- | :--- +`alerting_ack_alerts` | Grants permissions to view and acknowledge alerts, but not modify destinations or monitors. +`alerting_full_access` | Grants full permissions to all alerting actions. +`alerting_read_access` | Grants permissions to view alerts, destinations, and monitors, but not acknowledge alerts or modify destinations or monitors. `all_access` | Grants full access to the cluster: all cluster-wide operations, write to all indices, write to all tenants. `kibana_read_only` | A special role that prevents users from making changes to visualizations, dashboards, and other Kibana objects. See `opendistro_security.readonly_mode.roles` in `kibana.yml`. Pair with the `kibana_user` role. `kibana_user` | Grants permissions to use Kibana: cluster-wide searches, index monitoring, and write to various Kibana indices. From c3a4c62a453c3bacdd84fe0317719f468c02d39a Mon Sep 17 00:00:00 2001 From: aetter Date: Wed, 11 Nov 2020 09:31:19 -0800 Subject: [PATCH 2/4] Comment out individual user section --- docs/alerting/security.md | 4 ++-- docs/alerting/settings.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/alerting/security.md b/docs/alerting/security.md index be74d929..d9f5ab88 100644 --- a/docs/alerting/security.md +++ b/docs/alerting/security.md @@ -56,7 +56,7 @@ Now when users view alerting resources in Kibana (or make REST API calls), they If `jdoe` creates a monitor, `jroe` can see and modify it. `psantos` can't. If that monitor generates an alert, the situation is the same: `jroe` can see and acknowledge it, but `psantos` can't. If `psantos` creates a destination---you guessed it---neither `jdoe` nor `jroe` can see or modify it. -## (Advanced) Limit access by individual + diff --git a/docs/alerting/settings.md b/docs/alerting/settings.md index 61bea217..10c65665 100644 --- a/docs/alerting/settings.md +++ b/docs/alerting/settings.md @@ -46,8 +46,8 @@ Setting | Default | Description `opendistro.alerting.move_alerts_backoff_millis` | 250 | The amount of time to wait between retries---increases exponentially after each failed retry. `opendistro.alerting.move_alerts_backoff_count` | 3 | The number of retries for moving alerts to a deleted state after their monitor or trigger has been deleted. `opendistro.alerting.monitor.max_monitors` | 1000 | The maximum number of monitors users can create. -`opendistro.alerting.alert_history_max_age` | 30d | The oldest document the `.opendistro-alert-history-` index should keep. -`opendistro.alerting.alert_history_max_docs` | 1000 | The maximum number of documents the `.opendistro-alert-history-` index should keep. +`opendistro.alerting.alert_history_max_age` | 30d | The oldest document to store in the `.opendistro-alert-history-` index before creating a new index. If the number of alerts in this time period does not exceed `alert_history_max_docs`, alerting creates one history index per period (e.g. one index every 30 days). +`opendistro.alerting.alert_history_max_docs` | 1000 | The maximum number of alerts to store in the `.opendistro-alert-history-` index before creating a new index. `opendistro.alerting.alert_history_enabled` | true | Whether to create `.opendistro-alerting-alert-history-` indices. `opendistro.alerting.alert_history_retention_period` | 60d | The amount of time to keep history indices before automatically deleting them. `opendistro.alerting.destination.allow_list` | ["chime", "slack", "custom_webhook", "email", "test_action"] | The list of allowed destinations. If you don't want to allow users to a certain type of destination, you can remove it from this list, but we recommend leaving this setting as-is. From af99d3db5cd8918a950a8abc7267d2f42591b97a Mon Sep 17 00:00:00 2001 From: aetter Date: Wed, 11 Nov 2020 13:37:15 -0800 Subject: [PATCH 3/4] System indices --- docs/elasticsearch/snapshot-restore.md | 2 +- docs/security/configuration/system-indices.md | 28 +++++++++++++++++++ 2 files changed, 29 insertions(+), 1 deletion(-) create mode 100644 docs/security/configuration/system-indices.md diff --git a/docs/elasticsearch/snapshot-restore.md b/docs/elasticsearch/snapshot-restore.md index 5e28acd9..b3e6d040 100644 --- a/docs/elasticsearch/snapshot-restore.md +++ b/docs/elasticsearch/snapshot-restore.md @@ -381,5 +381,5 @@ POST _snapshot/my-repository/3/_restore The `.opendistro_security` index contains sensitive data, so we recommend excluding it when you take a snapshot. If you do need to restore the index from a snapshot, you must include an admin certificate in the request: ```bash -curl -k --cert chain.pem --key kirk.key.pem -XPOST 'https://localhost:9200/_snapshot/my-repository/3/_restore?pretty' +curl -k --cert ./kirk.pem --key ./kirk-key.pem -XPOST 'https://localhost:9200/_snapshot/my-repository/3/_restore?pretty' ``` diff --git a/docs/security/configuration/system-indices.md b/docs/security/configuration/system-indices.md new file mode 100644 index 00000000..0d50faa9 --- /dev/null +++ b/docs/security/configuration/system-indices.md @@ -0,0 +1,28 @@ +--- +layout: default +title: System Indices +parent: Configuration +grand_parent: Security +nav_order: 15 +--- + +# System indices + +By default, Open Distro for Elasticsearch has several protected system indices. Even if your user account has read permissions for all indices, you can't directly access the data in these system indices. + +The first and most critical index is `.opendistro_security`, which stores the security configuration for your cluster. The demo configuration creates this index automatically, but when you configure the plugin manually, you create it when you first run [securityadmin.sh](../security-admin/). + +You can see other system indices in `elasticsearch.yml`: + +```yml +opendistro_security.system_indices.enabled: true +opendistro_security.system_indices.indices: [".opendistro-alerting-config", ".opendistro-alerting-alert*"] +``` + +To access these indices, you must authenticate with an [admin certificate](../tls/#configure-admin-certificates): + +```bash +curl -k --cert ./kirk.pem --key ./kirk-key.pem -XGET 'https://localhost:9200/.opendistro_security/_search' +``` + +The alternative is to remove indices from the `opendistro_security.system_indices.indices` list on each node and restart Elasticsearch. From e96b6d3b8f53c461095d0b3214242a6d584b33e3 Mon Sep 17 00:00:00 2001 From: aetter Date: Wed, 11 Nov 2020 14:30:00 -0800 Subject: [PATCH 4/4] Add some AD system indices --- docs/security/configuration/system-indices.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/security/configuration/system-indices.md b/docs/security/configuration/system-indices.md index 0d50faa9..88fcc700 100644 --- a/docs/security/configuration/system-indices.md +++ b/docs/security/configuration/system-indices.md @@ -16,7 +16,7 @@ You can see other system indices in `elasticsearch.yml`: ```yml opendistro_security.system_indices.enabled: true -opendistro_security.system_indices.indices: [".opendistro-alerting-config", ".opendistro-alerting-alert*"] +opendistro_security.system_indices.indices: [".opendistro-alerting-config", ".opendistro-alerting-alert*", ".opendistro-anomaly-results*", ".opendistro-anomaly-detector*", ".opendistro-anomaly-checkpoints", ".opendistro-anomaly-detection-state"] ``` To access these indices, you must authenticate with an [admin certificate](../tls/#configure-admin-certificates):