Apply suggestions from code review

29 suggestions from Shaina

Co-authored-by: shainaraskas <[email protected]>

Author: eedugon

deploy-manage/monitor/logging-configuration/auditing-search-queries.md

@@ -23,12 +23,21 @@ xpack.security.audit.logfile.events.emit_request_body: true
 You can apply this setting through [cluster update settings API](https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster-update-settings.html), as described in [](./configuring-audit-logs.md). Alternatively, you can modify `elasticsearch.yml` in all nodes and restart for the changes to take effect.
 
 ::::{important} 
-No filtering is performed when auditing, so **sensitive data might be audited in plain text when audit events include the request body**. Also, the request body can contain malicious content that can break a parser consuming the audit logs.
+No filtering is performed when auditing, so sensitive data might be audited in plain text when audit events include the request body. Also, the request body can contain malicious content that can break a parser consuming the audit logs.
 ::::
 
 The request body is printed as an escaped JSON string value (RFC 4627) to the `request.body` event attribute.
 
-Not all events contain the `request.body` attribute, even when the above setting is toggled. The ones that do are: `authentication_success`, `authentication_failed`, `realm_authentication_failed`, `tampered_request`, `run_as_denied`, and `anonymous_access_denied`. The `request.body` attribute is printed on the coordinating node only (the node that handles the REST request). Most of these event types are [not included by default](https://www.elastic.co/guide/en/elasticsearch/reference/current/auditing-settings.html#xpack-sa-lf-events-include).
+Not all events contain the `request.body` attribute, even when the above setting is toggled. The ones that do are:
+ 
+* `authentication_success`
+* `authentication_failed`
+* `realm_authentication_failed`
+* `tampered_request`
+* `run_as_denied` 
+* `anonymous_access_denied`
+
+The `request.body` attribute is printed on the coordinating node only (the node that handles the REST request). Most of these event types are [not included by default](https://www.elastic.co/guide/en/elasticsearch/reference/current/auditing-settings.html#xpack-sa-lf-events-include).
 
 A good practical piece of advice is to add `authentication_success` to the event types that are audited (add it to the list in the `xpack.security.audit.logfile.events.include`), as this event type is not audited by default.
 

deploy-manage/monitor/logging-configuration/configuring-audit-logs.md

@@ -20,28 +20,22 @@ When auditing security events, a single client request might generate multiple a
   * [{{es}} ignore policies settings](https://www.elastic.co/guide/en/elasticsearch/reference/current/auditing-settings.html#audit-event-ignore-policies): Use ignore policies for fine-grained control over which audit events are printed to the log file.
 
     ::::{tip}
-    In {{es}}, all auditing settings except `xpack.security.audit.enabled` are **dynamic**. This means you can configure them using the [cluster update settings API](https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster-update-settings.html), allowing changes to take effect immediately without requiring a restart. This approach is faster and more convenient than modifying `elasticsearch.yml`. 
+    In {{es}}, all auditing settings except `xpack.security.audit.enabled` are dynamic. This means you can configure them using the [cluster update settings API](https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster-update-settings.html), allowing changes to take effect immediately without requiring a restart. This approach is faster and more convenient than modifying `elasticsearch.yml`. 
     ::::
 
-Note that {{ech}} deployments provide its own subset of supported settings for auditing configuration:
-  * [Elasticsearch audit settings for Elastic Cloud Hosted deployments](https://www.elastic.co/guide/en/cloud/current/ec-add-user-settings.html#ec_audit_settings)
 
-For a complete description of event details and format, refer to:
-  * [{{es}} audit events details and schema](/deploy-manage/monitor/logging-configuration/elasticsearch-audit-events.md).
-  * [{{es}} logentry output format](/deploy-manage/monitor/logging-configuration/logfile-audit-output.md#audit-log-entry-format)
+For a complete description of event details and format, refer to the following resources:
+  * [{{es}} audit events details and schema](/deploy-manage/monitor/logging-configuration/elasticsearch-audit-events.md)
+  * [{{es}} log entry output format](/deploy-manage/monitor/logging-configuration/logfile-audit-output.md#audit-log-entry-format)
 
 ### Kibana auditing configuration
 
-{{kib}} configuration options include:
-
-  * [{{kib}} ignore filters](https://www.elastic.co/guide/en/kibana/current/security-settings-kb.html#audit-logging-ignore-filters): List of filters that determine which events should be excluded from the audit log.
+To control the logs that are outputted by Kibana, you can use [{{kib}} ignore filters](https://www.elastic.co/guide/en/kibana/current/security-settings-kb.html#audit-logging-ignore-filters). These are a list of filters that determine which events should be excluded from the audit log.
 
     ::::{tip}
     To configure {{kib}} settings, follow the same [procedure](./enabling-audit-logs.md#enable-audit-logging-procedure) as when enabling {{kib}} audit logs, but apply the relevant settings instead.
     ::::
 
-Note that {{ech}} deployments provide its own subset of supported settings for auditing configuration:
-  * [Kibana audit settings on Elastic Cloud](https://www.elastic.co/guide/en/cloud/current/ec-manage-kibana-settings.html#ec_logging_and_audit_settings)
 
 For a complete description of auditing event details, such as `category`, `type`, or `action`, refer to:
   * [{{kib}} audit events](https://www.elastic.co/guide/en/kibana/current/xpack-security-audit-logging.html#xpack-security-ecs-audit-logging)
@@ -55,7 +49,7 @@ For a complete description of auditing event details, such as `category`, `type`
 * Refer to [auditing search queries](./auditing-search-queries.md) for details on logging request bodies in the {{es}} audit logs.
 
   ::::{important}
-  Be advised that **sensitive data may be audited in plain text** when including the request body in audit events, even though all the security APIs, such as those that change the user’s password, have the credentials filtered out when audited.
+  Sensitive data may be audited in plain text when including the request body in audit events, even though all the security APIs, such as those that change the user’s password, have the credentials filtered out when audited.
   ::::
 
 * Use {{kib}} [ignore filters](https://www.elastic.co/guide/en/kibana/current/security-settings-kb.html#audit-logging-ignore-filters) if you want to filter out certain events from the {{kib}} audit log.

deploy-manage/monitor/logging-configuration/enabling-audit-logs.md

@@ -24,14 +24,18 @@ You can log security-related events such as authentication failures and refused
 Use the {{kib}} audit logs in conjunction with {{es}} audit logging to get a holistic view of all security related events. {{kib}} defers to the {{es}} security model for authentication, data index authorization, and features that are driven by cluster-wide privileges.
 
 ::::{note}
-Audit logs are **disabled** by default and must be explicitly enabled.
+Audit logs are disabled by default and must be explicitly enabled.
 ::::
 
 This section describes how to enable and configure audit logging in both {{es}} and {{kib}} for all supported deployment types, including self-managed clusters, Elastic Cloud Hosted, Elastic Cloud Enterprise (ECE), and Elastic Cloud on Kubernetes (ECK).
 
-## Enabling procedure [enable-audit-logging-procedure]
+::::{important}
+In orchestrated deployments, audit logs must be shipped to a monitoring deployment; otherwise, they remain at container level and won't be accessible to users. For details on configuring log forwarding in orchestrated environments, refer to [logging configuration](../logging-configuration.md).
+::::
+
+## Enable audit logging [enable-audit-logging-procedure]
 
-To enable {{es}} or {{kib}} audit logs, configure `xpack.security.audit.enabled` to `true` in **all {{es}} or {{kib}} nodes**, then restart the nodes to apply the changes. The following provide detailed steps for all supported deployment types:
+To enable {{es}} or {{kib}} audit logs, configure `xpack.security.audit.enabled` to `true` in **all {{es}} or {{kib}} nodes**, then restart the nodes to apply the changes. For detailed instructions, select your deployment type:
 
 % content discarded (for review)
 % The process of enabling and configuring audit logging is consistent across all supported deployment types, whether self-managed, Elastic Cloud, Elastic Cloud Enterprise (ECE), or Elastic Cloud on Kubernetes (ECK). The same settings apply regardless of the deployment type, ensuring a unified approach to audit logging configuration.
@@ -56,48 +60,43 @@ You can configure additional options to control what events are logged and what
 
 **To enable audit logging in {{kib}}**:
 
-1. Set `xpack.security.audit.enabled` to `true` in `kibana.yml`
-2. Restart {{kib}}
+1. Set `xpack.security.audit.enabled` to `true` in `kibana.yml`.
+2. Restart {{kib}}.
 
 You can optionally configure audit logs location, file/rolling file appenders and ignore filters using [{{kib}} audit logging settings](https://www.elastic.co/guide/en/kibana/current/security-settings-kb.html#audit-logging-settings).
 
 :::::
 
 :::::{tab-item} Elastic Cloud Hosted
 
-::::{important}
-In orchestrated deployments, audit logs must be shipped to a monitoring deployment; otherwise, they remain at container level and won't be accessible to users. For details on configuring log forwarding in orchestrated environments, refer to [logging configuration](../logging-configuration.md).
-::::
 
 To enable audit logging in an {{ech}} deployment:
 
-1. Log in to the [Elasticsearch Service Console](https://cloud.elastic.co?page=docs&placement=docs-body).
+1. Log in to the [{{ecloud}} Console](https://cloud.elastic.co?page=docs&placement=docs-body).
 
-2. Find your deployment on the home page in the Elasticsearch Service card and select **Manage** to access it directly. Or, select **Hosted deployments** to go to the deployments page to view all of your deployments.
+2. Find your deployment on the home page in the **Hosted deployments** card and select **Manage** to access it directly. Or, select **Hosted deployments** to go to the deployments page to view all of your deployments.
 
 3. From your deployment menu, go to the **Edit** page.
 
 4. To enable auditing for Elasticsearch:
-    * In the **Elasticsearch** section select **Manage user settings and extensions**. For deployments with existing user settings, you may have to expand the **Edit elasticsearch.yml** caret for each node instead.
+    * In the **Elasticsearch** section, select **Manage user settings and extensions**. For deployments with existing user settings, you may have to expand the **Edit elasticsearch.yml** caret for each node instead.
     * Add the setting `xpack.security.audit.enabled: true`.
 
 5. To enable auditing for Kibana:
     * In the **Kibana** section, select **Edit user settings**. For deployments with existing user settings, you may have to expand the **Edit kibana.yml** caret instead.
     * Add the setting `xpack.security.audit.enabled: true`.
 
 6. Select **Save changes**.
-    * A plan change will run on your deployment. When it finishes, **audit logs will be delivered to your monitoring deployment**.
+
+A plan change will run on your deployment. When it finishes, audit logs will be delivered to your monitoring deployment.
 :::::
 
 :::::{tab-item} ECE
 
-::::{important}
-In orchestrated deployments, audit logs must be shipped to a monitoring deployment; otherwise, they remain at container level and won't be accessible to users. For details on configuring log forwarding in orchestrated environments, refer to [logging configuration](../logging-configuration.md).
-::::
 
 To enable audit logging in an ECE deployment:
 
-1. [Log into the Cloud UI](../../deploy/cloud-enterprise/log-into-cloud-ui.md).
+1. [Log in to the Cloud UI](../../deploy/cloud-enterprise/log-into-cloud-ui.md).
 
 2. On the **Deployments** page, select your deployment.
 
@@ -113,16 +112,16 @@ To enable audit logging in an ECE deployment:
     * If your Elastic Stack version is below 7.6.0, add the setting `logging.quiet: false`.
 
 6. Select **Save**.
-    * A plan change will run on your deployment. When it finishes, **audit logs will be delivered to your monitoring deployment**.
+
+A plan change will run on your deployment. When it finishes, audit logs will be delivered to your monitoring deployment.
 :::::
 
 :::::{tab-item} ECK
 
-::::{important}
-In orchestrated deployments, audit logs must be shipped to a monitoring deployment; otherwise, they remain at container level and won't be accessible to users. For details on configuring log forwarding in orchestrated environments, refer to [logging configuration](../logging-configuration.md).
-::::
 
-To enable audit logging in an ECK-managed cluster, add `xpack.security.audit.enabled: true` to the `config` section of each {{es}} `nodeSet` and to the `config` section of the {{kib}} object's specification. The following example shows this configuration together with logs and metrics delivery towards a remote cluster:
+To enable audit logging in an ECK-managed cluster, add `xpack.security.audit.enabled: true` to the `config` section of each {{es}} `nodeSet` and to the `config` section of the {{kib}} object's specification. 
+
+The following example shows this configuration, along with  together with logs and metrics delivery towards a remote cluster:
 
 ```yaml
 apiVersion: elasticsearch.k8s.elastic.co/v1
@@ -160,7 +159,7 @@ spec:
     xpack.security.audit.enabled: true
 ```
 
-When enabled, audit logs are collected and shipped to the monitoring cluster referenced in the `monitoring.logs` section. If monitoring is not enabled audit logs will only be visible at container level.
+When enabled, audit logs are collected and shipped to the monitoring cluster referenced in the `monitoring.logs` section. If monitoring is not enabled, audit logs will only be visible at container level.
 :::::
 
 ::::::

deploy-manage/monitor/logging-configuration/logfile-audit-output.md

@@ -15,7 +15,7 @@ The `logfile` audit output is the only output for auditing. By default, it write
 
 In self-managed clusters, you can configure how the `logfile` is written in the `log4j2.properties` file located in `ES_PATH_CONF` (or check out the relevant portion of the [log4j2.properties in the sources](https://github.com/elastic/elasticsearch/blob/master/x-pack/plugin/core/src/main/config/log4j2.properties)). However, **Elastic strongly recommends using the default Log4j2 configuration**.
 
-Orchestrated deployments (Elastic Cloud, Elastic Cloud Enterprise (ECE), and Elastic Cloud on Kubernetes (ECK)) do not support changes in `log4j2.properties` files of the {{es}} instances.
+Orchestrated deployments (ECH, ECE, and ECK) do not support changes in `log4j2.properties` files of the {{es}} instances.
 
 ::::{note} 
 If you overwrite the `log4j2.properties` and do not specify appenders for any of the audit trails, audit events are forwarded to the root appender, which by default points to the `elasticsearch.log` file.

deploy-manage/monitor/logging-configuration/security-event-audit-logging.md

@@ -18,12 +18,12 @@ Audit logging also provides forensic evidence in the event of an attack, and can
 
 In this section, you'll learn how to:
 
-1. [](./enabling-audit-logs.md): Activate {{es}} or {{kib}} audit logs for all supported deployment types, including self-managed clusters, {{ech}}, {{ece}} (ECE), and {{eck}} (ECK).
+* [](./enabling-audit-logs.md): Activate {{es}} or {{kib}} audit logs for all supported deployment types.
 
-2. [](./configuring-audit-logs.md): Filter and control what security events get logged in the audit log output.
+* [](./configuring-audit-logs.md): Filter and control what security events get logged in the audit log output.
 
-3. Optionally, [audit {{es}} search queries](./auditing-search-queries.md): Audit and log search request bodies. 
+* [Audit {{es}} search queries](./auditing-search-queries.md): Audit and log search request bodies. 
 
-4. [Correlate audit events](./correlating-kibana-elasticsearch-audit-logs.md): Explore audit logs and understand how events from the same request are correlated.
+* [Correlate audit events](./correlating-kibana-elasticsearch-audit-logs.md): Explore audit logs and understand how events from the same request are correlated.
 
 By following these guidelines, you can effectively audit system activity, enhance security monitoring, and meet compliance requirements.

manage-data/ingest/ingesting-data-from-applications/ingest-data-with-nodejs-on-elasticsearch-service.md

@@ -290,7 +290,7 @@ const client = new Client({
 })
 ```
 
-Check [Create API key API](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-create-api-key.html) to learn more about API Keys and [Security privileges](../../../deploy-manage/users-roles/cluster-or-deployment-auth/elasticsearch-privileges.md) to understand which privileges are needed. If you are not sure what the right combination of privileges for your custom application is, you can enable [audit logging](../../../deploy-manage/monitor/logging-configuration/enabling-audit-logs.md) on {{es}} to find out what privileges are being used. To learn more about how logging works on {{ech}} or {{ece}}, check [Monitoring Elastic Cloud deployment logs and metrics](https://www.elastic.co/blog/monitoring-elastic-cloud-deployment-logs-and-metrics).
+Check [Create API key API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-create-api-key) to learn more about API Keys and [Security privileges](../../../deploy-manage/users-roles/cluster-or-deployment-auth/elasticsearch-privileges.md) to understand which privileges are needed. If you are not sure what the right combination of privileges for your custom application is, you can enable [audit logging](../../../deploy-manage/monitor/logging-configuration/enabling-audit-logs.md) on {{es}} to find out what privileges are being used. To learn more about how logging works on {{ech}} or {{ece}}, check [Monitoring Elastic Cloud deployment logs and metrics](https://www.elastic.co/blog/monitoring-elastic-cloud-deployment-logs-and-metrics).
 
 
 ### Best practices [ec_best_practices]

manage-data/ingest/ingesting-data-from-applications/ingest-data-with-python-on-elasticsearch-service.md

@@ -351,7 +351,7 @@ es = Elasticsearch(
 )
 ```
 
-Check [Create API key API](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-create-api-key.html) to learn more about API Keys and [Security privileges](../../../deploy-manage/users-roles/cluster-or-deployment-auth/elasticsearch-privileges.md) to understand which privileges are needed. If you are not sure what the right combination of privileges for your custom application is, you can enable [audit logging](../../../deploy-manage/monitor/logging-configuration/enabling-audit-logs.md) on {{es}} to find out what privileges are being used. To learn more about how logging works on {{ech}} or {{ece}}, check [Monitoring Elastic Cloud deployment logs and metrics](https://www.elastic.co/blog/monitoring-elastic-cloud-deployment-logs-and-metrics).
+Check [Create API key API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-create-api-key) to learn more about API Keys and [Security privileges](../../../deploy-manage/users-roles/cluster-or-deployment-auth/elasticsearch-privileges.md) to understand which privileges are needed. If you are not sure what the right combination of privileges for your custom application is, you can enable [audit logging](../../../deploy-manage/monitor/logging-configuration/enabling-audit-logs.md) on {{es}} to find out what privileges are being used. To learn more about how logging works on {{ech}} or {{ece}}, check [Monitoring Elastic Cloud deployment logs and metrics](https://www.elastic.co/blog/monitoring-elastic-cloud-deployment-logs-and-metrics).
 
 For more information on refreshing an index, searching, updating, and deleting, check the [elasticsearch-py examples](https://www.elastic.co/guide/en/elasticsearch/client/python-api/current/examples.html).