Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Expand on ES|QL rule docs #4235

Merged
merged 25 commits into from
Nov 28, 2023
Merged
Changes from all commits
Commits
Show all changes
25 commits
Select commit Hold shift + click to select a range
ff23d2f
First draft
nastasha-solomon Nov 10, 2023
9a2b043
title change
nastasha-solomon Nov 10, 2023
99fd35d
Slight revisions
nastasha-solomon Nov 10, 2023
a30a4d5
Merge branch 'main' into issue-4195-esql-rule-additions
nastasha-solomon Nov 10, 2023
dcf9841
Updating limitations
nastasha-solomon Nov 10, 2023
c9b8d9a
Re-orgs
nastasha-solomon Nov 13, 2023
94f65ea
Exp step 2
nastasha-solomon Nov 13, 2023
54b8f73
Fix char
nastasha-solomon Nov 13, 2023
6196d1b
Indent
nastasha-solomon Nov 13, 2023
a08dac4
Update docs/detections/rules-ui-create.asciidoc
nastasha-solomon Nov 13, 2023
0b935ab
Update docs/detections/rules-ui-create.asciidoc
nastasha-solomon Nov 14, 2023
6a90716
Update docs/detections/rules-ui-create.asciidoc
nastasha-solomon Nov 14, 2023
e9d1856
Update docs/detections/rules-ui-create.asciidoc
nastasha-solomon Nov 15, 2023
4011593
Merge branch 'main' into issue-4195-esql-rule-additions
nastasha-solomon Nov 15, 2023
ccb27cc
Update docs/detections/rules-ui-create.asciidoc
nastasha-solomon Nov 15, 2023
6ca4c35
small change
nastasha-solomon Nov 15, 2023
f1445ee
Merge branch 'main' into issue-4195-esql-rule-additions
nastasha-solomon Nov 15, 2023
1dbd424
Merge branch 'main' into issue-4195-esql-rule-additions
nastasha-solomon Nov 27, 2023
3258acb
Update docs/detections/rules-ui-create.asciidoc
nastasha-solomon Nov 27, 2023
5491f91
Update docs/detections/rules-ui-create.asciidoc
nastasha-solomon Nov 27, 2023
03d2a7a
Update docs/detections/rules-ui-create.asciidoc
nastasha-solomon Nov 27, 2023
69a710e
Update docs/detections/rules-ui-create.asciidoc
nastasha-solomon Nov 27, 2023
5c57d3d
Update docs/detections/rules-ui-create.asciidoc
nastasha-solomon Nov 27, 2023
3b75f70
Update docs/detections/rules-ui-create.asciidoc
nastasha-solomon Nov 27, 2023
e52e402
Update docs/detections/rules-ui-create.asciidoc
nastasha-solomon Nov 28, 2023
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 27 additions & 1 deletion docs/detections/rules-ui-create.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -270,7 +270,9 @@ Use {ref}/esql.html[{esql}] to query your source events and aggregate event data
To create an {esql} rule:

. Go to *Rules* -> *Detection rules (SIEM)* -> *Create new rule*. The *Create new rule* page appears.
. Select **{esql}**, then write a <<esql-rule-query-types,query>>.
. Select **{esql}**, then write a query.
+
NOTE: Refer to the sections below to learn more about <<esql-rule-query-types,{esql} query types>>, <<esql-query-design,query design considerations>>, and <<esql-rule-limitations,rule limitations>>.
+
TIP: Click the help icon (image:images/esql-ref-button.png[Click the ES|QL help icon,20,20]) to open the in-product reference documentation for all {esql} commands and functions.
+
Expand Down Expand Up @@ -358,6 +360,30 @@ FROM logs-* [metadata _id, _index, _version]
| LIMIT 10
-----

[float]
[[esql-query-design]]
==== Query design considerations

When writing your query, consider the following:

- The {ref}/esql-commands.html#esql-limit[`LIMIT`] command specifies the number of rows an {esql} query returns and the number of alerts created per rule execution. Similarly, a detection rule's <<opt-fields-all,`max_signals`>> setting specifies the maximum number of alerts it can create every time it runs.
+
If the `LIMIT` value is lower than the `max_signals` value, the rule uses the `LIMIT` value to determine the maximum number of alerts the rule generates. If the `LIMIT` value is higher than the `max_signals` value, the rule uses the `max_signals` value.
+
NOTE: The `max_signals` default value is 100. You can modify it using the <<rules-api-create,Create rule API>>.
+

- When writing an aggregating query, use the {ref}/esql-commands.html#esql-stats-by[`STATS...BY`] command with fields that you want to search and filter for after alerts are created. For example, using the `host.name`, `user.name`, `process.name` fields with the `BY` operator of the `STATS...BY` command returns these fields in alert documents, and allows you to search and filter for them from the Alerts table.

[float]
[[esql-rule-limitations]]
==== {esql} rule limitations

The {esql} rule has the following limitations:

- If your {esql} query creates new fields that aren’t part of the ECS schema, they won’t be mapped to the alerts index and you can't search or filter for them from the Alerts table. As a workaround, create <<runtime-fields,runtime fields>>.
- If your {esql} query creates new fields that aren’t in the query’s source index, they can’t be added to the rule’s <<rule-ui-advanced-params,custom highlighted fields>>.

[float]
[[rule-ui-basic-params]]
=== Configure basic rule settings
Expand Down