Merge branch 'main' into issue-2044-big

Author: benironside

docs/detections/api/rules/rules-api-create.asciidoc

@@ -413,6 +413,24 @@ must be an {es} date data type.
 
 |==============================================
 
+[[opt-fields-eql-create]]
+===== Optional fields for event correlation rules
+
+[width="100%",options="header"]
+|==============================================
+|Name |Type |Description
+
+|event_category_field |String
+|Contains the event classification, such as `process`, `file`, or `network`. This field is typically mapped as a field type in the {ref}/keyword.html[keyword family]. Defaults to the `event.category` ECS field.
+
+|tiebreaker_field |String
+|Sets a secondary field for sorting events (in ascending, lexicographic order) if they have the same timestamp.
+
+|timestamp_field |String
+|Contains the event timestamp used for sorting a sequence of events. This is different from `timestamp_override`, which is used for querying events within a range. Defaults to the `@timestamp` ECS field.
+
+|==============================================
+
 [[actions-object-schema]]
 ===== `actions` schema
 

docs/detections/api/rules/rules-api-import.asciidoc

@@ -66,3 +66,18 @@ curl -X POST "api/detection_engine/rules/_import?overwrite=true"
 
 `200`::
     Indicates a successful call.
+
+===== Example response
+
+[source,json]
+--------------------------------------------------
+{
+    "success": true,
+    "success_count": 1,
+    "rules_count": 1,
+    "errors": [],
+    "exceptions_errors": [],
+    "exceptions_success": true,
+    "exceptions_success_count": 0
+}
+--------------------------------------------------

docs/detections/api/rules/rules-api-update.asciidoc

@@ -329,6 +329,24 @@ must be an {es} date data type.
 
 |==============================================
 
+[[opt-fields-eql-update]]
+===== Optional fields for EQL rules
+
+[width="100%",options="header"]
+|==============================================
+|Name |Type |Description
+
+|event_category_field |String
+|Contains the event classification, such as `process`, `file`, or `network`. This field is typically mapped as a field type in the {ref}/keyword.html[keyword family]. Defaults to the `event.category` ECS field.
+
+|tiebreaker_field |String
+|Sets a secondary field for sorting events (in ascending, lexicographic order) if they have the same timestamp.
+
+|timestamp_field |String
+|Contains the event timestamp used for sorting a sequence of events. This is different from `timestamp_override`, which is used for querying events within a range. Defaults to the `@timestamp` ECS field.
+
+|==============================================
+
 [[actions-object-schema-update]]
 ===== `actions` schema
 

docs/detections/detections-ui-exceptions.asciidoc

@@ -8,16 +8,6 @@ processes and network activity to function without producing unnecessary noise.
 
 You can add multiple exceptions to one rule.
 
-[IMPORTANT]
-=====
-When you add an exception to the
-<<endpoint-rule-exceptions, Elastic Endpoint Security>> rule, you can select to
-add the exception to the Endpoint. When selected, the exception is added to
-both the detection rule *and* the Elastic Endpoint agent on your hosts.
-
-{ref}/binary.html[Binary fields] are not supported in detection rule exceptions.
-=====
-
 In addition to defining exception queries for source event values, you can use rule
 exceptions with value lists. Value lists are lists of items with
 the same {es} {ref}/mapping-types.html[data type]. You can create value lists
@@ -87,6 +77,8 @@ You can add exceptions to a rule from the rule details page or the Alerts table.
 When you add an exception, you can also close all alerts that meet the
 exception's criteria.
 
+IMPORTANT:  To ensure an exception is successfully applied, make sure that the fields you've defined for the exception query are correctly and consistently mapped in their respective indices. Refer to {ecs-ref}[ECS] to learn more about supported mappings.
+
 [IMPORTANT]
 ==============
 Be careful when adding exceptions to event correlation rules. Exceptions are evaluated against every event in the sequence, and when the exception matches _all_ event(s) in the sequence, alerts _are not_ generated. If the exception only matches _some_ of the events in the sequence, alerts _are_ generated. 
@@ -167,6 +159,16 @@ Like detection rule exceptions, you can add Endpoint agent exceptions either by
 
 You can also add Endpoint exceptions to rules that are associated with {elastic-endpoint} rule exceptions. To associate rules, when creating or editing a rule, select the <<rule-ui-advanced-params, *{elastic-endpoint} exceptions*>> option.
 
+[IMPORTANT]
+=====
+When you add an exception to the
+<<endpoint-rule-exceptions, Elastic Endpoint Security>> rule, you can select to
+add the exception to the endpoint. When selected, the exception is added to
+both the detection rule *and* the {elastic-endpoint} agent on your hosts.
+
+{ref}/binary.html[Binary fields] are not supported in detection rule exceptions.
+=====
+
 [IMPORTANT]
 =============
 Exceptions added to the Elastic {endpoint-sec} rule affect all alerts sent

docs/detections/images/eql-rule-query-example.png

@@ -164,18 +164,8 @@ For example, if `Group by` is `source.ip`, `destination.ip` and its `Threshold`
 +
 You can also leave the `Group by` field undefined. The rule then creates an alert when the number of search results is equal to or greater than the threshold value. If you set `Count` to limit the results by `process.name` >= 2, an alert will only be generated for source/destination IP pairs that appear with at least 2 unique process names across all events.
 +
-[IMPORTANT]
-==============
-Signals created by *threshold* rules are synthetic signals that do not resemble the source documents. The signal itself only contains data about the fields that were aggregated over (the `Group by` fields). Additionally, the signal contains "lookup" data for retrieving a *Timeline* of all of the source events that caused the threshold to be exceeded.
-If you wish to create an <<rule-notifications, *Action*>> based on a threshold rule, you can obtain values of the fields that were aggregated over by entering the following:
-```
-{{#context.alerts}}
-  {{#signal.threshold_result.terms}}
-    {{value}}
-  {{/signal.threshold_result.terms}}
-{{/context.alerts}}
-```
-==============
+IMPORTANT: Alerts created by threshold rules are synthetic alerts that do not resemble the source documents. The alert itself only contains data about the fields that were aggregated over (the `Group by` fields). Other fields are omitted, because they can vary across all source documents that were counted toward the threshold. Additionally, you can reference the actual count of documents that exceeded the threshold from the `kibana.alert.threshold_result.count` field.
+
 . Continue with <<preview-rules, previewing the rule>> (optional) or click *Continue* to <<rule-ui-basic-params, configure basic rule settings>>.
 
 [discrete]
@@ -190,7 +180,7 @@ network connection:
 +
 ** *Index patterns*: `winlogbeat-*`
 +
-> Winlogbeat ships Windows events to {elastic-sec}.
+Winlogbeat ships Windows events to {elastic-sec}.
 
 ** *EQL query*:
 +
@@ -215,6 +205,11 @@ image::images/eql-rule-query-example.png[]
 +
 NOTE: For sequence events, the {security-app} generates a single alert when all events listed in the sequence are detected. To see the matched sequence events in more detail, you can view the alert in the Timeline, and, if all events came from the same process, open the alert in Analyze Event view.
 +
+. (Optional) Click the EQL settings icon (image:images/eql-settings-icon.png[EQL settings icon,16,16]) to configure additional fields used by {ref}/eql.html#specify-a-timestamp-or-event-category-field[EQL search]:
+  * *Event category field*: Contains the event classification, such as `process`, `file`, or `network`. This field is typically mapped as a field type in the {ref}/keyword.html[keyword family]. Defaults to the `event.category` ECS field.
+  * *Tiebreaker field*: Sets a secondary field for sorting events (in ascending, lexicographic order) if they have the same timestamp.
+  * *Timestamp field*: Contains the event timestamp used for sorting a sequence of events. This is different from the *Timestamp override* advanced setting, which is used for querying events within a range. Defaults to the `@timestamp` ECS field.
++
 . Continue with <<preview-rules, previewing the rule>> (optional) or click *Continue* to <<rule-ui-basic-params, configure basic rule settings>>.
 
 [discrete]