From b4426ee08bcccff31f5c677458b8861591f5a67f Mon Sep 17 00:00:00 2001 From: Nastasha Solomon Date: Fri, 13 Jun 2025 17:17:38 -0400 Subject: [PATCH 1/6] First draft --- docs/detections/about-rules.asciidoc | 2 ++ docs/detections/query-alert-indices.asciidoc | 2 ++ docs/reference/alert-schema.asciidoc | 7 ++++++- 3 files changed, 10 insertions(+), 1 deletion(-) diff --git a/docs/detections/about-rules.asciidoc b/docs/detections/about-rules.asciidoc index b241b82013..2148070bae 100644 --- a/docs/detections/about-rules.asciidoc +++ b/docs/detections/about-rules.asciidoc @@ -59,6 +59,8 @@ When you create a rule, you must either specify the {es} index pattens for which NOTE: To access data views, ensure you have the {kibana-ref}/data-views.html#data-views-read-only-access[required permissions]. +IMPORTANT: System indices, such as the alerts indices, contain important configuration and internal data; do not change their mappings. Changes can lead to rule execution and alert indexing failures. + [float] [[about-notifications]] === Notifications diff --git a/docs/detections/query-alert-indices.asciidoc b/docs/detections/query-alert-indices.asciidoc index 07d8018ff8..eacb5221b6 100644 --- a/docs/detections/query-alert-indices.asciidoc +++ b/docs/detections/query-alert-indices.asciidoc @@ -2,6 +2,8 @@ == Query alert indices This page explains how you should query alert indices, for example, when building rule queries, custom dashboards, or visualizations. For more information about alert event field definitions, review the <>. +IMPORTANT: System indices, such as the alerts indices, contain important configuration and internal data; do not change their mappings. Changes can lead to rule execution and alert indexing failures. + [discrete] === Alert index aliases We recommend querying the following index aliases: diff --git a/docs/reference/alert-schema.asciidoc b/docs/reference/alert-schema.asciidoc index a4d27d1faf..e76f1e12c1 100644 --- a/docs/reference/alert-schema.asciidoc +++ b/docs/reference/alert-schema.asciidoc @@ -9,7 +9,12 @@ {elastic-sec} stores alerts that have been generated by detection rules in hidden {es} indices. In 8.x versions, the index pattern is `.alerts-security.alerts-`. In 7.x versions, the index pattern was `.siem-signals-`, and some field names were different. The following table includes the current names and cross-references the legacy field names. -NOTE: Users are advised NOT to use the `_source` field in alert documents, but rather to use the `fields` option in the search API to programmatically obtain the list of fields used in these documents. Learn more about {ref}/search-fields.html[retrieving selected fields from a search]. +[IMPORTANT] +==== + +* System indices, such as the alerts indices, contain important configuration and internal data; do not change their mappings. Changes can lead to rule execution and alert indexing failures. +* Users are advised NOT to use the `_source` field in alert documents, but rather to use the `fields` option in the search API to programmatically obtain the list of fields used in these documents. Learn more about {ref}/search-fields.html[retrieving selected fields from a search]. +==== NOTE: The non-ECS fields listed below are beta and subject to change. From 2c5ff04965d0cbd3c47398f5b801958e104c1482 Mon Sep 17 00:00:00 2001 From: Nastasha Solomon Date: Fri, 27 Jun 2025 14:59:25 -0400 Subject: [PATCH 2/6] Add link to runtime fields --- docs/detections/about-rules.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/detections/about-rules.asciidoc b/docs/detections/about-rules.asciidoc index 2148070bae..c5a4563d99 100644 --- a/docs/detections/about-rules.asciidoc +++ b/docs/detections/about-rules.asciidoc @@ -59,7 +59,7 @@ When you create a rule, you must either specify the {es} index pattens for which NOTE: To access data views, ensure you have the {kibana-ref}/data-views.html#data-views-read-only-access[required permissions]. -IMPORTANT: System indices, such as the alerts indices, contain important configuration and internal data; do not change their mappings. Changes can lead to rule execution and alert indexing failures. +IMPORTANT: System indices, such as the alerts indices, contain important configuration and internal data; do not change their mappings. Changes can lead to rule execution and alert indexing failures. Use runtime fields instead, which allow you to add fields to existing alert and event documents. Refer to <> to learn more. [float] [[about-notifications]] From 496c4722406afff4e728ca8fbcdb5c460cb6c7e6 Mon Sep 17 00:00:00 2001 From: Nastasha Solomon Date: Fri, 27 Jun 2025 15:01:01 -0400 Subject: [PATCH 3/6] apply to other areas --- docs/detections/query-alert-indices.asciidoc | 2 +- docs/reference/alert-schema.asciidoc | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/detections/query-alert-indices.asciidoc b/docs/detections/query-alert-indices.asciidoc index eacb5221b6..cdf2fe124e 100644 --- a/docs/detections/query-alert-indices.asciidoc +++ b/docs/detections/query-alert-indices.asciidoc @@ -2,7 +2,7 @@ == Query alert indices This page explains how you should query alert indices, for example, when building rule queries, custom dashboards, or visualizations. For more information about alert event field definitions, review the <>. -IMPORTANT: System indices, such as the alerts indices, contain important configuration and internal data; do not change their mappings. Changes can lead to rule execution and alert indexing failures. +IMPORTANT: System indices, such as the alerts indices, contain important configuration and internal data; do not change their mappings. Changes can lead to rule execution and alert indexing failures. Use runtime fields instead, which allow you to add fields to existing alert and event documents. Refer to <> to learn more. [discrete] === Alert index aliases diff --git a/docs/reference/alert-schema.asciidoc b/docs/reference/alert-schema.asciidoc index e76f1e12c1..4eb974c051 100644 --- a/docs/reference/alert-schema.asciidoc +++ b/docs/reference/alert-schema.asciidoc @@ -12,7 +12,7 @@ [IMPORTANT] ==== -* System indices, such as the alerts indices, contain important configuration and internal data; do not change their mappings. Changes can lead to rule execution and alert indexing failures. +* System indices, such as the alerts indices, contain important configuration and internal data; do not change their mappings. Changes can lead to rule execution and alert indexing failures. Use runtime fields instead, which allow you to add fields to existing alert and event documents. Refer to <> to learn more. * Users are advised NOT to use the `_source` field in alert documents, but rather to use the `fields` option in the search API to programmatically obtain the list of fields used in these documents. Learn more about {ref}/search-fields.html[retrieving selected fields from a search]. ==== From 9b576912e4a4ca13a6d4205707770c8ec47bc0e4 Mon Sep 17 00:00:00 2001 From: Nastasha Solomon Date: Fri, 27 Jun 2025 15:08:22 -0400 Subject: [PATCH 4/6] remove s --- docs/detections/about-rules.asciidoc | 2 +- docs/detections/query-alert-indices.asciidoc | 2 +- docs/reference/alert-schema.asciidoc | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/detections/about-rules.asciidoc b/docs/detections/about-rules.asciidoc index c5a4563d99..de32aa03ef 100644 --- a/docs/detections/about-rules.asciidoc +++ b/docs/detections/about-rules.asciidoc @@ -59,7 +59,7 @@ When you create a rule, you must either specify the {es} index pattens for which NOTE: To access data views, ensure you have the {kibana-ref}/data-views.html#data-views-read-only-access[required permissions]. -IMPORTANT: System indices, such as the alerts indices, contain important configuration and internal data; do not change their mappings. Changes can lead to rule execution and alert indexing failures. Use runtime fields instead, which allow you to add fields to existing alert and event documents. Refer to <> to learn more. +IMPORTANT: System indices, such as the alert indices, contain important configuration and internal data; do not change their mappings. Changes can lead to rule execution and alert indexing failures. Use runtime fields instead, which allow you to add fields to existing alert and event documents. Refer to <> to learn more. [float] [[about-notifications]] diff --git a/docs/detections/query-alert-indices.asciidoc b/docs/detections/query-alert-indices.asciidoc index cdf2fe124e..a084037234 100644 --- a/docs/detections/query-alert-indices.asciidoc +++ b/docs/detections/query-alert-indices.asciidoc @@ -2,7 +2,7 @@ == Query alert indices This page explains how you should query alert indices, for example, when building rule queries, custom dashboards, or visualizations. For more information about alert event field definitions, review the <>. -IMPORTANT: System indices, such as the alerts indices, contain important configuration and internal data; do not change their mappings. Changes can lead to rule execution and alert indexing failures. Use runtime fields instead, which allow you to add fields to existing alert and event documents. Refer to <> to learn more. +IMPORTANT: System indices, such as the alert indices, contain important configuration and internal data; do not change their mappings. Changes can lead to rule execution and alert indexing failures. Use runtime fields instead, which allow you to add fields to existing alert and event documents. Refer to <> to learn more. [discrete] === Alert index aliases diff --git a/docs/reference/alert-schema.asciidoc b/docs/reference/alert-schema.asciidoc index 4eb974c051..0a2ba6a617 100644 --- a/docs/reference/alert-schema.asciidoc +++ b/docs/reference/alert-schema.asciidoc @@ -12,7 +12,7 @@ [IMPORTANT] ==== -* System indices, such as the alerts indices, contain important configuration and internal data; do not change their mappings. Changes can lead to rule execution and alert indexing failures. Use runtime fields instead, which allow you to add fields to existing alert and event documents. Refer to <> to learn more. +* System indices, such as the alert indices, contain important configuration and internal data; do not change their mappings. Changes can lead to rule execution and alert indexing failures. Use runtime fields instead, which allow you to add fields to existing alert and event documents. Refer to <> to learn more. * Users are advised NOT to use the `_source` field in alert documents, but rather to use the `fields` option in the search API to programmatically obtain the list of fields used in these documents. Learn more about {ref}/search-fields.html[retrieving selected fields from a search]. ==== From 33cd7064e65a556287cbb6ed7f61cf568e6f60db Mon Sep 17 00:00:00 2001 From: Nastasha Solomon Date: Fri, 27 Jun 2025 15:12:47 -0400 Subject: [PATCH 5/6] cleanup --- docs/detections/about-rules.asciidoc | 2 +- docs/detections/query-alert-indices.asciidoc | 2 +- docs/reference/alert-schema.asciidoc | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/detections/about-rules.asciidoc b/docs/detections/about-rules.asciidoc index de32aa03ef..81710bf359 100644 --- a/docs/detections/about-rules.asciidoc +++ b/docs/detections/about-rules.asciidoc @@ -59,7 +59,7 @@ When you create a rule, you must either specify the {es} index pattens for which NOTE: To access data views, ensure you have the {kibana-ref}/data-views.html#data-views-read-only-access[required permissions]. -IMPORTANT: System indices, such as the alert indices, contain important configuration and internal data; do not change their mappings. Changes can lead to rule execution and alert indexing failures. Use runtime fields instead, which allow you to add fields to existing alert and event documents. Refer to <> to learn more. +IMPORTANT: System indices, such as the alert indices, contain important configuration and internal data; do not change their mappings. Changes can lead to rule execution and alert indexing failures. Use <> instead, which allow you to add fields to existing alert and event documents. [float] [[about-notifications]] diff --git a/docs/detections/query-alert-indices.asciidoc b/docs/detections/query-alert-indices.asciidoc index a084037234..5a61f38836 100644 --- a/docs/detections/query-alert-indices.asciidoc +++ b/docs/detections/query-alert-indices.asciidoc @@ -2,7 +2,7 @@ == Query alert indices This page explains how you should query alert indices, for example, when building rule queries, custom dashboards, or visualizations. For more information about alert event field definitions, review the <>. -IMPORTANT: System indices, such as the alert indices, contain important configuration and internal data; do not change their mappings. Changes can lead to rule execution and alert indexing failures. Use runtime fields instead, which allow you to add fields to existing alert and event documents. Refer to <> to learn more. +IMPORTANT: System indices, such as the alert indices, contain important configuration and internal data; do not change their mappings. Changes can lead to rule execution and alert indexing failures. Use <> instead, which allow you to add fields to existing alert and event documents. [discrete] === Alert index aliases diff --git a/docs/reference/alert-schema.asciidoc b/docs/reference/alert-schema.asciidoc index 0a2ba6a617..57a9be3a97 100644 --- a/docs/reference/alert-schema.asciidoc +++ b/docs/reference/alert-schema.asciidoc @@ -12,7 +12,7 @@ [IMPORTANT] ==== -* System indices, such as the alert indices, contain important configuration and internal data; do not change their mappings. Changes can lead to rule execution and alert indexing failures. Use runtime fields instead, which allow you to add fields to existing alert and event documents. Refer to <> to learn more. +* System indices, such as the alert indices, contain important configuration and internal data; do not change their mappings. Changes can lead to rule execution and alert indexing failures. Use <> instead, which allow you to add fields to existing alert and event documents. * Users are advised NOT to use the `_source` field in alert documents, but rather to use the `fields` option in the search API to programmatically obtain the list of fields used in these documents. Learn more about {ref}/search-fields.html[retrieving selected fields from a search]. ==== From 3a25fa63a3ebfb2002ff877c4955c7dae975b82b Mon Sep 17 00:00:00 2001 From: Nastasha Solomon <79124755+nastasha-solomon@users.noreply.github.com> Date: Fri, 27 Jun 2025 15:43:19 -0400 Subject: [PATCH 6/6] Update docs/reference/alert-schema.asciidoc Co-authored-by: Janeen Mikell Roberts <57149392+jmikell821@users.noreply.github.com> --- docs/reference/alert-schema.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/alert-schema.asciidoc b/docs/reference/alert-schema.asciidoc index 57a9be3a97..337a13e72b 100644 --- a/docs/reference/alert-schema.asciidoc +++ b/docs/reference/alert-schema.asciidoc @@ -13,7 +13,7 @@ ==== * System indices, such as the alert indices, contain important configuration and internal data; do not change their mappings. Changes can lead to rule execution and alert indexing failures. Use <> instead, which allow you to add fields to existing alert and event documents. -* Users are advised NOT to use the `_source` field in alert documents, but rather to use the `fields` option in the search API to programmatically obtain the list of fields used in these documents. Learn more about {ref}/search-fields.html[retrieving selected fields from a search]. +* We recommend to NOT use the `_source` field in alert documents, but rather the `fields` option in the search API to programmatically obtain the list of fields used in these documents. Learn more about {ref}/search-fields.html[retrieving selected fields from a search]. ==== NOTE: The non-ECS fields listed below are beta and subject to change.