Skip to content

Commit 24b4823

Browse files
jrodewigjrodewig
authored
[DOCS] EQL: Add diagrams for sequence matching (#65898) (#65940)
1 parent d562caf commit 24b4823

File tree

3 files changed

+138
-51
lines changed

3 files changed

+138
-51
lines changed

‎docs/reference/eql/syntax.asciidoc

Lines changed: 136 additions & 51 deletions
Original file line numberDiff line numberDiff line change
@@ -766,27 +766,27 @@ order:
766766
767767
[source,js]
768768
----
769-
{ "index" : { "_id" : "1" } }
769+
{ "index" : { "_id": "1" } }
770770
{ "user": { "name": "root" }, "process": { "name": "attrib" }, ...}
771-
{ "index" : { "_id" : "2" } }
771+
{ "index" : { "_id": "2" } }
772772
{ "user": { "name": "root" }, "process": { "name": "attrib" }, ...}
773-
{ "index" : { "_id" : "3" } }
773+
{ "index" : { "_id": "3" } }
774774
{ "user": { "name": "elkbee" }, "process": { "name": "bash" }, ...}
775-
{ "index" : { "_id" : "4" } }
775+
{ "index" : { "_id": "4" } }
776776
{ "user": { "name": "root" }, "process": { "name": "bash" }, ...}
777-
{ "index" : { "_id" : "5" } }
777+
{ "index" : { "_id": "5" } }
778778
{ "user": { "name": "root" }, "process": { "name": "bash" }, ...}
779-
{ "index" : { "_id" : "6" } }
779+
{ "index" : { "_id": "6" } }
780780
{ "user": { "name": "elkbee" }, "process": { "name": "attrib" }, ...}
781-
{ "index" : { "_id" : "7" } }
781+
{ "index" : { "_id": "7" } }
782782
{ "user": { "name": "root" }, "process": { "name": "attrib" }, ...}
783-
{ "index" : { "_id" : "8" } }
783+
{ "index" : { "_id": "8" } }
784784
{ "user": { "name": "elkbee" }, "process": { "name": "bash" }, ...}
785-
{ "index" : { "_id" : "9" } }
785+
{ "index" : { "_id": "9" } }
786786
{ "user": { "name": "root" }, "process": { "name": "cat" }, ...}
787-
{ "index" : { "_id" : "10" } }
787+
{ "index" : { "_id": "10" } }
788788
{ "user": { "name": "elkbee" }, "process": { "name": "cat" }, ...}
789-
{ "index" : { "_id" : "11" } }
789+
{ "index" : { "_id": "11" } }
790790
{ "user": { "name": "root" }, "process": { "name": "cat" }, ...}
791791
----
792792
// NOTCONSOLE
@@ -807,81 +807,166 @@ The query's event items correspond to the following states:
807807
* State B: `[process where process.name == "bash"]`
808808
* Complete: `[process where process.name == "cat"]`
809809
810+
image::images/eql/sequence-state-machine.svg[align="center"]
811+
810812
To find matching sequences, the query uses separate state machines for each
811-
unique `user.name` value. Pending sequence matches move through each machine's
812-
states as follows:
813+
unique `user.name` value. Based on the data set, you can expect two state
814+
machines: one for the `root` user and one for `elkbee`.
815+
816+
image::images/eql/separate-state-machines.svg[align="center"]
817+
818+
Pending sequence matches move through each machine's states as follows:
813819
814820
[source,txt]
815821
----
816-
{ "index" : { "_id" : "1" } }
822+
{ "index" : { "_id": "1" } }
817823
{ "user": { "name": "root" }, "process": { "name": "attrib" }, ...}
818824
// Creates sequence [1] in state A for the "root" user.
819825
//
820-
// root: A=[1]
821-
822-
{ "index" : { "_id" : "2" } }
826+
// +------------------------"root"------------------------+
827+
// | +-----------+ +-----------+ +------------+ |
828+
// | | State A | | State B | | Complete | |
829+
// | +-----------+ +-----------+ +------------+ |
830+
// | | [1] | | | | | |
831+
// | +-----------+ +-----------+ +------------+ |
832+
// +------------------------------------------------------+
833+
834+
{ "index" : { "_id": "2" } }
823835
{ "user": { "name": "root" }, "process": { "name": "attrib" }, ...}
824836
// Creates sequence [2] in state A for "root", overwriting sequence [1].
825837
//
826-
// root: A=[2]
827-
828-
{ "index" : { "_id" : "3" } }
838+
// +------------------------"root"------------------------+
839+
// | +-----------+ +-----------+ +------------+ |
840+
// | | State A | | State B | | Complete | |
841+
// | +-----------+ +-----------+ +------------+ |
842+
// | | [2] | | | | | |
843+
// | +-----------+ +-----------+ +------------+ |
844+
// +------------------------------------------------------+
845+
846+
{ "index" : { "_id": "3" } }
829847
{ "user": { "name": "elkbee" }, "process": { "name": "bash" }, ...}
830-
// Nothing happens. The "elkbee" user has no pending sequence to move from state A to state B
831-
832-
{ "index" : { "_id" : "4" } }
848+
// Nothing happens. The "elkbee" user has no pending sequence to move
849+
// from state A to state B.
850+
//
851+
// +-----------------------"elkbee"-----------------------+
852+
// | +-----------+ +-----------+ +------------+ |
853+
// | | State A | | State B | | Complete | |
854+
// | +-----------+ +-----------+ +------------+ |
855+
// | | | | | | | |
856+
// | +-----------+ +-----------+ +------------+ |
857+
// +------------------------------------------------------+
858+
859+
{ "index" : { "_id": "4" } }
833860
{ "user": { "name": "root" }, "process": { "name": "bash" }, ...}
834-
// Sequence [2] moves out of state A for "root". State B for "root" now contains [2, 4]
835-
// State A for "root" is now empty.
861+
// Sequence [2] moves out of state A for "root".
862+
// State B for "root" now contains [2, 4].
863+
// State A for "root" is empty.
836864
//
837-
// root: A=[]
838-
// root: B=[2, 4]
839-
840-
{ "index" : { "_id" : "5" } }
865+
// +------------------------"root"------------------------+
866+
// | +-----------+ +-----------+ +------------+ |
867+
// | | State A | | State B | | Complete | |
868+
// | +-----------+ --> +-----------+ +------------+ |
869+
// | | | | [2, 4] | | | |
870+
// | +-----------+ +-----------+ +------------+ |
871+
// +------------------------------------------------------+
872+
873+
{ "index" : { "_id": "5" } }
841874
{ "user": { "name": "root" }, "process": { "name": "bash" }, ...}
842875
// Nothing happens. State A is empty for "root".
843-
844-
{ "index" : { "_id" : "6" } }
876+
//
877+
// +------------------------"root"------------------------+
878+
// | +-----------+ +-----------+ +------------+ |
879+
// | | State A | | State B | | Complete | |
880+
// | +-----------+ +-----------+ +------------+ |
881+
// | | | | [2, 4] | | | |
882+
// | +-----------+ +-----------+ +------------+ |
883+
// +------------------------------------------------------+
884+
885+
{ "index" : { "_id": "6" } }
845886
{ "user": { "name": "elkbee" }, "process": { "name": "attrib" }, ...}
846887
// Creates sequence [6] in state A for "elkbee".
847888
//
848-
// elkbee: A=[6]
849-
850-
{ "index" : { "_id" : "7" } }
889+
// +-----------------------"elkbee"-----------------------+
890+
// | +-----------+ +-----------+ +------------+ |
891+
// | | State A | | State B | | Complete | |
892+
// | +-----------+ +-----------+ +------------+ |
893+
// | | [6] | | | | | |
894+
// | +-----------+ +-----------+ +------------+ |
895+
// +------------------------------------------------------+
896+
897+
{ "index" : { "_id": "7" } }
851898
{ "user": { "name": "root" }, "process": { "name": "attrib" }, ...}
852899
// Creates sequence [7] in state A for "root".
853900
// Sequence [2, 4] remains in state B for "root".
854901
//
855-
// root: A=[7]
856-
// root: B=[2, 4]
857-
858-
{ "index" : { "_id" : "8" } }
902+
// +------------------------"root"------------------------+
903+
// | +-----------+ +-----------+ +------------+ |
904+
// | | State A | | State B | | Complete | |
905+
// | +-----------+ +-----------+ +------------+ |
906+
// | | [7] | | [2, 4] | | | |
907+
// | +-----------+ +-----------+ +------------+ |
908+
// +------------------------------------------------------+
909+
910+
{ "index" : { "_id": "8" } }
859911
{ "user": { "name": "elkbee" }, "process": { "name": "bash" }, ...}
860912
// Sequence [6, 8] moves to state B for "elkbee".
861913
// State A for "elkbee" is now empty.
862914
//
863-
// elkbee: A=[]
864-
// elkbee: B=[6, 8]
865-
866-
{ "index" : { "_id" : "9" } }
915+
// +-----------------------"elkbee"-----------------------+
916+
// | +-----------+ +-----------+ +------------+ |
917+
// | | State A | | State B | | Complete | |
918+
// | +-----------+ --> +-----------+ +------------+ |
919+
// | | | | [6, 8] | | | |
920+
// | +-----------+ +-----------+ +------------+ |
921+
// +------------------------------------------------------+
922+
923+
{ "index" : { "_id": "9" } }
867924
{ "user": { "name": "root" }, "process": { "name": "cat" }, ...}
868925
// Sequence [2, 4, 9] is complete for "root".
869926
// State B for "root" is now empty.
870927
// Sequence [7] remains in state A.
871928
//
872-
// root: A=[7]
873-
// root: B=[]
874-
875-
{ "index" : { "_id" : "10" } }
929+
// +------------------------"root"------------------------+
930+
// | +-----------+ +-----------+ +------------+ |
931+
// | | State A | | State B | | Complete | |
932+
// | +-----------+ +-----------+ --> +------------+ |
933+
// | | [7] | | | | [2, 4, 9] |
934+
// | +-----------+ +-----------+ +------------+ |
935+
// +------------------------------------------------------+
936+
937+
{ "index" : { "_id": "10" } }
876938
{ "user": { "name": "elkbee" }, "process": { "name": "cat" }, ...}
877939
// Sequence [6, 8, 10] is complete for "elkbee".
878940
// State A and B for "elkbee" are now empty.
879941
//
880-
// elkbee: A=[]
881-
// elkbee: B=[]
882-
883-
{ "index" : { "_id" : "11" } }
942+
// +-----------------------"elkbee"-----------------------+
943+
// | +-----------+ +-----------+ +------------+ |
944+
// | | State A | | State B | | Complete | |
945+
// | +-----------+ +-----------+ --> +------------+ |
946+
// | | | | | | [6, 8, 10] |
947+
// | +-----------+ +-----------+ +------------+ |
948+
// +------------------------------------------------------+
949+
950+
{ "index" : { "_id": "11" } }
884951
{ "user": { "name": "root" }, "process": { "name": "cat" }, ...}
885-
// Nothing happens. State B for "root" is empty.
952+
// Nothing happens.
953+
// The machines for "root" and "elkbee" remain the same.
954+
//
955+
// +------------------------"root"------------------------+
956+
// | +-----------+ +-----------+ +------------+ |
957+
// | | State A | | State B | | Complete | |
958+
// | +-----------+ +-----------+ +------------+ |
959+
// | | [7] | | | | [2, 4, 9] |
960+
// | +-----------+ +-----------+ +------------+ |
961+
// +------------------------------------------------------+
962+
//
963+
// +-----------------------"elkbee"-----------------------+
964+
// | +-----------+ +-----------+ +------------+ |
965+
// | | State A | | State B | | Complete | |
966+
// | +-----------+ +-----------+ +------------+ |
967+
// | | | | | | [6, 8, 10] |
968+
// | +-----------+ +-----------+ +------------+ |
969+
// +------------------------------------------------------+
886970
----
971+
887972
====

‎docs/reference/images/eql/separate-state-machines.svg

Lines changed: 1 addition & 0 deletions
Loading

0 commit comments

Comments
 (0)