Skip to content

Commit

Permalink
[DOCS] Add new EQL search configuration options (#2061)
Browse files Browse the repository at this point in the history
* Update eql-rule-query-example.png

* Update procedure for creating EQL rule

* Update API docs: create rule, update rule

* Align minor phrasing

* Explain timestamp_field & timestamp_override

* Updates based on review feedback

(cherry picked from commit 3f2f653)
  • Loading branch information
joepeeples authored and mergify[bot] committed Jun 23, 2022
1 parent 63a7301 commit 0406a6d
Show file tree
Hide file tree
Showing 5 changed files with 42 additions and 1 deletion.
18 changes: 18 additions & 0 deletions docs/detections/api/rules/rules-api-create.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
18 changes: 18 additions & 0 deletions docs/detections/api/rules/rules-api-update.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
Binary file modified docs/detections/images/eql-rule-query-example.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/detections/images/eql-settings-icon.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
7 changes: 6 additions & 1 deletion docs/detections/rules-ui-create.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -180,7 +180,7 @@ network connection:
+
** *Index patterns*: `winlogbeat-*`
+
> Winlogbeat ships Windows events to {elastic-sec}.
Winlogbeat ships Windows events to {elastic-sec}.

** *EQL query*:
+
Expand All @@ -205,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]
Expand Down

0 comments on commit 0406a6d

Please sign in to comment.