@@ -514,41 +514,48 @@ sequence by user.name with maxspan=15m
514
514
[[eql-until-keyword]]
515
515
==== `until` keyword
516
516
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.
521
522
522
523
[source,eql]
523
524
----
524
525
sequence
525
526
[ event_category_1 where condition_1 ]
526
527
[ event_category_2 where condition_2 ]
527
528
...
528
- until [ event_category_2 where condition_2 ]
529
+ until [ event_category_3 where condition_3 ]
529
530
----
530
531
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.
537
544
538
545
[source,eql]
539
546
----
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
544
551
----
545
- ====
552
+
553
+ The query matches sequences `A, B` and `A, B, C` but not `A, C, B`.
546
554
547
555
[TIP]
548
556
====
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.
552
559
553
560
In Windows, a process ID (PID) is unique only while a process is running. After
554
561
a process terminates, its PID can be reused.
@@ -559,14 +566,14 @@ and `sequence by` keywords.
559
566
.*Example*
560
567
[%collapsible]
561
568
=====
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.
564
571
565
572
[source,eql]
566
573
----
567
574
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" ]
570
577
----
571
578
=====
572
579
@@ -579,15 +586,15 @@ event.
579
586
[%collapsible]
580
587
=====
581
588
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.
584
591
585
592
[source,eql]
586
593
----
587
594
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 " ]
591
598
----
592
599
=====
593
600
0 commit comments