[DOCS] EQL: Clarify until keyword docs (#61794) (#61808)

This commit is contained in:
James Rodewig 2020-09-01 13:56:51 -04:00 committed by GitHub
parent 77ecea6e3b
commit fd976e668c
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23

View File

@ -514,10 +514,11 @@ sequence by user.name with maxspan=15m
[[eql-until-keyword]]
==== `until` keyword
You can use the `until` keyword to specify an expiration event for sequences.
Matching sequences must end before this event, which is not included the
results. If this event occurs within a sequence, the sequence is not considered
a match.
You can use the `until` keyword to specify an expiration event for a sequence.
If this expiration event occurs _between_ matching events in a sequence, the
sequence expires and is not considered a match. If the expiration event occurs
_after_ matching events in a sequence, the sequence is still considered a
match. The expiration event is not included in the results.
[source,eql]
----
@ -525,30 +526,36 @@ sequence
[ event_category_1 where condition_1 ]
[ event_category_2 where condition_2 ]
...
until [ event_category_2 where condition_2 ]
until [ event_category_3 where condition_3 ]
----
.*Example*
[%collapsible]
====
The following EQL sequence query uses the `until` keyword to end sequences
before a process termination event. Process termination events have an event
category of `process` and `event.type` value of `termination`.
*Example* +
A dataset contains the following event sequences, grouped by shared IDs:
[source,txt]
----
A, B
A, B, C
A, C, B
----
The following EQL query searches the dataset for sequences containing
event `A` followed by event `B`. Event `C` is used as an expiration event.
[source,eql]
----
sequence
[ file where file.extension == "exe" ]
[ process where true ]
until [ process where event.type == "termination" ]
sequence by ID
A
B
until C
----
====
The query matches sequences `A, B` and `A, B, C` but not `A, C, B`.
[TIP]
====
The `until` keyword can be helpful when searching for process sequences in
Windows event logs, such as those ingested using
{winlogbeat-ref}/index.html[Winlogbeat].
The `until` keyword can be useful when searching for process sequences in
Windows event logs.
In Windows, a process ID (PID) is unique only while a process is running. After
a process terminates, its PID can be reused.
@ -559,14 +566,14 @@ and `sequence by` keywords.
.*Example*
[%collapsible]
=====
The following EQL query uses the `sequence by` keyword to match a sequence of
events that share the same `process.pid` value.
The following EQL query uses the `sequence by` keyword to match a
sequence of events that share the same `process.pid` value.
[source,eql]
----
sequence by process.pid
[ process where process.name == "cmd.exe" ]
[ process where process.name == "whoami.exe" ]
[ process where event.type == "start" and process.name == "cmd.exe" ]
[ process where file.extension == "exe" ]
----
=====
@ -579,15 +586,15 @@ event.
[%collapsible]
=====
The following EQL query uses the `until` keyword to end sequences before
`process` events with an `event.type` of `termination`. These events indicate a
process has been terminated.
`process` events with an `event.type` of `stop`. These events indicate a process
has been terminated.
[source,eql]
----
sequence by process.pid
[ process where process.name == "cmd.exe" ]
[ process where process.name == "whoami.exe" ]
until [ process where event.type == "termination" ]
[ process where event.type == "start" and process.name == "cmd.exe" ]
[ process where file.extension == "exe" ]
until [ process where event.type == "stop" ]
----
=====