diff --git a/docs/reference/eql/syntax.asciidoc b/docs/reference/eql/syntax.asciidoc index 5c5056e447e0d..47379d52f73c0 100644 --- a/docs/reference/eql/syntax.asciidoc +++ b/docs/reference/eql/syntax.asciidoc @@ -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" ] ---- =====