Browse Source

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

James Rodewig 5 years ago
parent
commit
21deb3b7ea
1 changed files with 35 additions and 28 deletions
  1. 35 28
      docs/reference/eql/syntax.asciidoc

+ 35 - 28
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" ]
 ----
 =====