Skip to content

Commit 083627f

Browse files
authored
[DOCS] EQL: Clarify until keyword docs (#61794) (#61809)
1 parent b8de545 commit 083627f

File tree

1 file changed

+35
-28
lines changed

1 file changed

+35
-28
lines changed

docs/reference/eql/syntax.asciidoc

Lines changed: 35 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -514,41 +514,48 @@ sequence by user.name with maxspan=15m
514514
[[eql-until-keyword]]
515515
==== `until` keyword
516516

517-
You can use the `until` keyword to specify an expiration event for sequences.
518-
Matching sequences must end before this event, which is not included the
519-
results. If this event occurs within a sequence, the sequence is not considered
520-
a match.
517+
You can use the `until` keyword to specify an expiration event for a sequence.
518+
If this expiration event occurs _between_ matching events in a sequence, the
519+
sequence expires and is not considered a match. If the expiration event occurs
520+
_after_ matching events in a sequence, the sequence is still considered a
521+
match. The expiration event is not included in the results.
521522

522523
[source,eql]
523524
----
524525
sequence
525526
[ event_category_1 where condition_1 ]
526527
[ event_category_2 where condition_2 ]
527528
...
528-
until [ event_category_2 where condition_2 ]
529+
until [ event_category_3 where condition_3 ]
529530
----
530531

531-
.*Example*
532-
[%collapsible]
533-
====
534-
The following EQL sequence query uses the `until` keyword to end sequences
535-
before a process termination event. Process termination events have an event
536-
category of `process` and `event.type` value of `termination`.
532+
*Example* +
533+
A dataset contains the following event sequences, grouped by shared IDs:
534+
535+
[source,txt]
536+
----
537+
A, B
538+
A, B, C
539+
A, C, B
540+
----
541+
542+
The following EQL query searches the dataset for sequences containing
543+
event `A` followed by event `B`. Event `C` is used as an expiration event.
537544

538545
[source,eql]
539546
----
540-
sequence
541-
[ file where file.extension == "exe" ]
542-
[ process where true ]
543-
until [ process where event.type == "termination" ]
547+
sequence by ID
548+
A
549+
B
550+
until C
544551
----
545-
====
552+
553+
The query matches sequences `A, B` and `A, B, C` but not `A, C, B`.
546554

547555
[TIP]
548556
====
549-
The `until` keyword can be helpful when searching for process sequences in
550-
Windows event logs, such as those ingested using
551-
{winlogbeat-ref}/index.html[Winlogbeat].
557+
The `until` keyword can be useful when searching for process sequences in
558+
Windows event logs.
552559
553560
In Windows, a process ID (PID) is unique only while a process is running. After
554561
a process terminates, its PID can be reused.
@@ -559,14 +566,14 @@ and `sequence by` keywords.
559566
.*Example*
560567
[%collapsible]
561568
=====
562-
The following EQL query uses the `sequence by` keyword to match a sequence of
563-
events that share the same `process.pid` value.
569+
The following EQL query uses the `sequence by` keyword to match a
570+
sequence of events that share the same `process.pid` value.
564571

565572
[source,eql]
566573
----
567574
sequence by process.pid
568-
[ process where process.name == "cmd.exe" ]
569-
[ process where process.name == "whoami.exe" ]
575+
[ process where event.type == "start" and process.name == "cmd.exe" ]
576+
[ process where file.extension == "exe" ]
570577
----
571578
=====
572579
@@ -579,15 +586,15 @@ event.
579586
[%collapsible]
580587
=====
581588
The following EQL query uses the `until` keyword to end sequences before
582-
`process` events with an `event.type` of `termination`. These events indicate a
583-
process has been terminated.
589+
`process` events with an `event.type` of `stop`. These events indicate a process
590+
has been terminated.
584591

585592
[source,eql]
586593
----
587594
sequence by process.pid
588-
[ process where process.name == "cmd.exe" ]
589-
[ process where process.name == "whoami.exe" ]
590-
until [ process where event.type == "termination" ]
595+
[ process where event.type == "start" and process.name == "cmd.exe" ]
596+
[ process where file.extension == "exe" ]
597+
until [ process where event.type == "stop" ]
591598
----
592599
=====
593600

0 commit comments

Comments
 (0)