Add Security information to Security Analytics documentation

_security-analytics/security.md

@@ -0,0 +1,95 @@
+---
+layout: default
+title: OpenSearch Security for Security Analytics
+nav_order: 2
+has_children: false
+---
+
+# OpenSearch Security for Security Analytics
+
+You can use OpenSearch Security with Security Analytics to assign user permissions and manage the actions that users can and cannot perform. For example, you might want one group of users to be able to create, update, or delete detectors and another group of users to only view detectors.
+
+All Security Analytics indexes are protected as system indexes. Only a super admin user or an admin user with a TLS certificate can access system indexes. For more information, see [System indexes]({{site.url}}{{site.baseurl}}/security/configuration/system-indices/).
+
+
+Security for Security Analytics works much the same as [Alerting security]({{site.url}}{{site.baseurl}}/monitoring-plugins/alerting/security/).
+
+## Basic permissions
+
+As an admin user, you can use Security to assign specific permissions to users based on the specific APIs they need to access. For a list of supported APIs, see [API tools]({{site.url}}{{site.baseurl}}/security-analytics/api-tools/index/).
+
+OpenSearch Security has two built-in roles that cover most Security Analytics use cases: `security_analytics_full_access` and `security_analytics_read_access`. A third built-in role allows users to view and acknowledge alerts: `security_analytics_ack_alerts`. For descriptions of each, see [Predefined roles]({{site.url}}{{site.baseurl}}/security/access-control/users-roles#predefined-roles).
+
+If these roles don't meet your needs, mix and match individual Security Analytics [permissions]({{site.url}}{{site.baseurl}}/security/access-control/permissions/#security-analytics-permissions) to suit your use case. Each action corresponds to an operation in the REST API. For example, the `cluster:admin/opensearch/securityanalytics/detector/delete` permission lets you delete detectors.
+
+## (Advanced) Limit access by backend role
+
+Use backend roles to configure fine-grained access to individual detectors based on roles. For example, users of different departments in an organization can view detectors owned by their own department.
+
+First, make sure your users have the appropriate [backend roles]({{site.url}}{{site.baseurl}}/security/access-control/index/). Backend roles usually come from an [LDAP server]({{site.url}}{{site.baseurl}}/security/configuration/ldap/) or [SAML provider]({{site.url}}{{site.baseurl}}/security/configuration/saml/), but if you use the internal user database, you can use the REST API to [add them manually]({{site.url}}{{site.baseurl}}/security/access-control/api#create-user).
+
+Next, enable the following setting:
+
+```json
+PUT _cluster/settings
+{
+  "transient": {
+    "plugins.security_analytics.filter_by_backend_roles": "true"
+  }
+}
+```
+{% include copy-curl.html %}
+
+Now when users view Security Analytics resources in OpenSearch Dashboards (or make REST API calls), they only see detectors created by users who share at least one backend role.
+For example, consider two users: `alice` and `bob`.
+
+`alice` has an analyst backend role:
+
+```json
+PUT _plugins/_security/api/internalusers/alice
+{
+  "password": "alice",
+  "backend_roles": [
+    "analyst"
+  ],
+  "attributes": {}
+}
+```
+{% include copy-curl.html %}
+
+`bob` has a human-resources backend role:
+
+```json
+PUT _plugins/_security/api/internalusers/bob
+{
+  "password": "bob",
+  "backend_roles": [
+    "human-resources"
+  ],
+  "attributes": {}
+}
+```
+{% include copy-curl.html %}
+
+Both `alice` and `bob` have full access to Security Analytics:
+
+```json
+PUT _plugins/_security/api/rolesmapping/security_analytics_full_access
+{
+  "backend_roles": [],
+  "hosts": [],
+  "users": [
+    "alice",
+    "bob"
+  ]
+}
+```
+{% include copy-curl.html %}
+
+Because they have different backend roles, `alice` and `bob` cannot view each other's detectors or their results.
+
+## A note on using fine-grained access control with the plugin
+
+When a trigger generates an alert, the detector configurations, the alert itself, and any notification that is sent to a channel may include metadata describing the index being queried. By design, the plugin must extract the data and store it as metadata outside of the index. [Document-level security]({{site.url}}{{site.baseurl}}/security/access-control/document-level-security) (DLS) and [field-level security]({{site.url}}{{site.baseurl}}/security/access-control/field-level-security) (FLS) access controls are designed to protect the data in the index. But once the data is stored outside the index as metadata, users with access to the detector and monitor configurations, alerts, and their notifications will be able to view this metadata and possibly infer the contents and quality of data in the index, which would otherwise be concealed by DLS and FLS access control.
+
+To reduce the chances of unintended users viewing metadata that could describe an index, we recommend that administrators enable role-based access control and keep these kinds of design elements in mind when assigning permissions to the intended group of users. See [Limit access by backend role](#advanced-limit-access-by-backend-role) for details.

_security/access-control/permissions.md

@@ -69,11 +69,20 @@ Rather than individual permissions, you can often achieve your desired security
 
 These permissions are for the cluster and can't be applied granularly. For example, you either have permissions to take snapshots (`cluster:admin/snapshot/create`) or you don't. You can't have permissions to take snapshots only for certain indices.
 
+### Ingest API permissions
+
+See [Ingest APIs]({{site.url}}{{site.baseurl}}/api-reference/ingest-apis/index/).
+
 - cluster:admin/ingest/pipeline/delete
 - cluster:admin/ingest/pipeline/get
 - cluster:admin/ingest/pipeline/put
 - cluster:admin/ingest/pipeline/simulate
 - cluster:admin/ingest/processor/grok/get
+
+### Anamoly Detection permissions
+
+See [Anomaly detection API]({{site.url}}{{site.baseurl}}/observing-your-data/ad/api/).
+
 - cluster:admin/opendistro/ad/detector/delete
 - cluster:admin/opendistro/ad/detector/info
 - cluster:admin/opendistro/ad/detector/jobmanagement
@@ -87,6 +96,11 @@ These permissions are for the cluster and can't be applied granularly. For examp
 - cluster:admin/opendistro/ad/result/search
 - cluster:admin/opendistro/ad/result/topAnomalies
 - cluster:admin/opendistro/ad/tasks/search
+
+### Alerting permissions
+
+See [Alerting API]({{site.url}}{{site.baseurl}}/observing-your-data/alerting/api/).
+
 - cluster:admin/opendistro/alerting/alerts/ack (acknowledge)
 - cluster:admin/opendistro/alerting/alerts/get
 - cluster:admin/opendistro/alerting/destination/delete
@@ -105,10 +119,20 @@ These permissions are for the cluster and can't be applied granularly. For examp
 - cluster:admin/opendistro/alerting/monitor/get
 - cluster:admin/opendistro/alerting/monitor/search
 - cluster:admin/opendistro/alerting/monitor/write
+
+### Asynchronous Search permissions
+
+See [Asynchronous search]({{site.url}}{{site.baseurl}}/search-plugins/async/index/).
+
 - cluster:admin/opendistro/asynchronous_search/stats
 - cluster:admin/opendistro/asynchronous_search/delete
 - cluster:admin/opendistro/asynchronous_search/get
 - cluster:admin/opendistro/asynchronous_search/submit
+
+### Index State Management permissions
+
+See [ISM API]({{site.url}}{{site.baseurl}}/im-plugin/ism/api/).
+
 - cluster:admin/opendistro/ism/managedindex/add
 - cluster:admin/opendistro/ism/managedindex/change
 - cluster:admin/opendistro/ism/managedindex/remove
@@ -118,13 +142,23 @@ These permissions are for the cluster and can't be applied granularly. For examp
 - cluster:admin/opendistro/ism/policy/get
 - cluster:admin/opendistro/ism/policy/search
 - cluster:admin/opendistro/ism/policy/delete
+
+### Index Rollup permissions
+
+See [Index rollups API]({{site.url}}{{site.baseurl}}/im-plugin/index-rollups/rollup-api/).
+
 - cluster:admin/opendistro/rollup/index
 - cluster:admin/opendistro/rollup/get
 - cluster:admin/opendistro/rollup/search
 - cluster:admin/opendistro/rollup/delete
 - cluster:admin/opendistro/rollup/start
 - cluster:admin/opendistro/rollup/stop
 - cluster:admin/opendistro/rollup/explain
+
+### Reporting permissions
+
+See [Creating reports with the Dashboards interface]({{site.url}}{{site.baseurl}}/dashboards/reporting/).
+
 - cluster:admin/opendistro/reports/definition/create
 - cluster:admin/opendistro/reports/definition/update
 - cluster:admin/opendistro/reports/definition/on_demand
@@ -134,37 +168,115 @@ These permissions are for the cluster and can't be applied granularly. For examp
 - cluster:admin/opendistro/reports/instance/list
 - cluster:admin/opendistro/reports/instance/get
 - cluster:admin/opendistro/reports/menu/download
+
+### Transform job permissions
+
+See [Transforms APIs]({{site.url}}{{site.baseurl}}/im-plugin/index-transforms/transforms-apis/)
+
 - cluster:admin/opendistro/transform/index
 - cluster:admin/opendistro/transform/get
 - cluster:admin/opendistro/transform/preview
 - cluster:admin/opendistro/transform/delete
 - cluster:admin/opendistro/transform/start
 - cluster:admin/opendistro/transform/stop
 - cluster:admin/opendistro/transform/explain
+
+### Observability permissions
+
+See [Observability security]({{site.url}}{{site.baseurl}}/observing-your-data/observability-security/).
+
 - cluster:admin/opensearch/observability/create
 - cluster:admin/opensearch/observability/update
 - cluster:admin/opensearch/observability/delete
 - cluster:admin/opensearch/observability/get
+
+### Cross-cluster replication
+
+See [Cross-cluster replication security]({{site.url}}{{site.baseurl}}/tuning-your-cluster/replication-plugin/permissions/).
+
 - cluster:admin/plugins/replication/autofollow/update
+
+### Reindex
+
+See [Reindex document]({{site.url}}{{site.baseurl}}/api-reference/document-apis/reindex/).
+
 - cluster:admin/reindex/rethrottle
+
+### Snapshot repository permissions
+
+See [Snapshot APIs]({{site.url}}{{site.baseurl}}/api-reference/snapshots/index/).
+
 - cluster:admin/repository/delete
 - cluster:admin/repository/get
 - cluster:admin/repository/put
 - cluster:admin/repository/verify
+
+### Reroute
+
+See [Cluster manager task throttling]({{site.url}}{{site.baseurl}}/tuning-your-cluster/cluster-manager-task-throttling/).
+
 - cluster:admin/reroute
+
+### Script permissions
+
+See [Script APIs]({{site.url}}{{site.baseurl}}/api-reference/script-apis/index/).
+
 - cluster:admin/script/delete
 - cluster:admin/script/get
 - cluster:admin/script/put
+
+### Update settings permission
+
+See [Update settings]({{site.url}}{{site.baseurl}}api-reference/index-apis/update-settings/) in Index APIs.
+
 - cluster:admin/settings/update
+
+### Snapshot permissions
+
+See [Snapshot APIs]({{site.url}}{{site.baseurl}}/api-reference/snapshots/index/).
+
 - cluster:admin/snapshot/create
 - cluster:admin/snapshot/delete
 - cluster:admin/snapshot/get
 - cluster:admin/snapshot/restore
 - cluster:admin/snapshot/status
 - cluster:admin/snapshot/status*
+
+### Task permissions
+
+See [Tasks]({{site.url}}{{site.baseurl}}/api-reference/tasks/) APIs.
+
 - cluster:admin/tasks/cancel
 - cluster:admin/tasks/test
 - cluster:admin/tasks/testunblock
+
+### Security Analytics permissions
+
+See [API tools]({{site.url}}{{site.baseurl}}/security-analytics/api-tools/index/).
+
+**Permission** | **Description**
+:--- | :---
+cluster:admin/opensearch/securityanalytics/alerts/get | permission to get alerts
+cluster:admin/opensearch/securityanalytics/alerts/ack | permission to acknowledge alerts
+cluster:admin/opensearch/securityanalytics/detector/get | permission to get detectors
+cluster:admin/opensearch/securityanalytics/detector/search | permission to search detectors
+cluster:admin/opensearch/securityanalytics/detector/write | permission to create and update detectors
+cluster:admin/opensearch/securityanalytics/detector/delete | permission to delete detectors
+cluster:admin/opensearch/securityanalytics/findings/get | permission to get findings
+cluster:admin/opensearch/securityanalytics/mapping/get | permission to get field mappings by index
+cluster:admin/opensearch/securityanalytics/mapping/view/get | permission to get field mappings by index and view mapped and unmapped fields
+cluster:admin/opensearch/securityanalytics/mapping/create | permission to create field mappings
+cluster:admin/opensearch/securityanalytics/mapping/update | permission to update field mappings
+cluster:admin/opensearch/securityanalytics/rules/categories | permission to get all rule categories
+cluster:admin/opensearch/securityanalytics/rule/write | permission to create and update rules
+cluster:admin/opensearch/securityanalytics/rule/search | permission to search for rules
+cluster:admin/opensearch/securityanalytics/rules/validate | permission to validate rules
+cluster:admin/opensearch/securityanalytics/rule/delete | permission to delete rules
+
+### Cluster monitoring
+
+See [Cluster APIs]({{site.url}}{{site.baseurl}}/api-reference/cluster-api/index/).
+
 - cluster:monitor/allocation/explain
 - cluster:monitor/health
 - cluster:monitor/main
@@ -180,6 +292,10 @@ These permissions are for the cluster and can't be applied granularly. For examp
 - cluster:monitor/task/get
 - cluster:monitor/tasks/list
 
+### Index templates
+
+See [Index templates]({{site.url}}{{site.baseurl}}/im-plugin/index-templates/).
+
 The following permissions are for indexes but apply globally to the cluster:
 
 - indices:admin/index_template/delete

_security/access-control/users-roles.md

@@ -129,6 +129,10 @@ Role | Description
 `snapshot_management_full_access` | Grants full permissions to all snapshot management actions.
 `snapshot_management_read_access` | Grants permissions to view policies but not create, modify, start, stop, or delete them.
 `point_in_time_full_access` | Grants full permissions to all Point in Time operations.
+`security_analytics_full_access` | Grants full permissions to all Security Analytics functionality.
+`security_analytics_read_access` | Grants permissions to view the various components in Security Analytics, such as detectors, alerts, and findings. It also includes permissions that allow users to search for detectors and rules. This role does not allow a user to perform actions such as modfying or deleting a detector.
+`security_analytics_ack_alerts` | Grants permissions to view and acknowledge alerts.
+
 
 For more detailed summaries of the permissions for each role, reference their action groups against the descriptions in [Default action groups]({{site.url}}{{site.baseurl}}/security/access-control/default-action-groups/).
 
@@ -137,7 +141,6 @@ For more detailed summaries of the permissions for each role, reference their ac
 
 The following examples show how you might set up a read-only and a bulk access role.
 
-
 ### Set up a read-only user in OpenSearch Dashboards
 
 Create a new `read_only_index` role: