Skip to content

Commit db64029

Browse files
authored
[7.x] [DOCS] Add parameter examples to EQL search tutorial (#52953)
Makes the following updates to the EQL search tutorial: * Adds an API response to the basic tutorial * Adds an example using the `event_type_field` parm * Adds an example using the `timestamp_field`parm * Adds an example using the `query` parm * Updates example dataset to support more EQL query variety
1 parent 89ed857 commit db64029

File tree

1 file changed

+121
-7
lines changed

1 file changed

+121
-7
lines changed

docs/reference/eql/search.asciidoc

+121-7
Original file line numberDiff line numberDiff line change
@@ -16,13 +16,14 @@ The following <<docs-bulk,bulk API>> request adds some example log data to the
1616
[source,console]
1717
----
1818
PUT sec_logs/_bulk?refresh
19-
{"index":{"_index" : "sec_logs"}}
19+
{"index":{"_index" : "sec_logs", "_id" : "1"}}
2020
{ "@timestamp": "2020-12-07T11:06:07.000Z", "agent": { "id": "8a4f500d" }, "event": { "category": "process" }, "process": { "name": "cmd.exe", "path": "C:\\Windows\\System32\\cmd.exe" } }
21-
{"index":{"_index" : "sec_logs"}}
22-
{ "@timestamp": "2020-12-07T11:07:08.000Z", "agent": { "id": "8a4f500d" }, "event": { "category": "image_load" }, "file": { "name": "cmd.exe", "path": "C:\\Windows\\System32\\cmd.exe" }, "process": { "name": "cmd.exe", "path": "C:\\Windows\\System32\\cmd.exe" } }
23-
{"index":{"_index" : "sec_logs"}}
21+
{"index":{"_index" : "sec_logs", "_id" : "2"}}
22+
{ "@timestamp": "2020-12-07T11:07:08.000Z", "agent": { "id": "8a4f500d" }, "event": { "category": "file" }, "file": { "accessed": "2020-12-07T11:07:08.000Z", "name": "cmd.exe", "path": "C:\\Windows\\System32\\cmd.exe", "type": "file", "size": 16384 }, "process": { "name": "cmd.exe", "path": "C:\\Windows\\System32\\cmd.exe" } }
23+
{"index":{"_index" : "sec_logs", "_id" : "3"}}
2424
{ "@timestamp": "2020-12-07T11:07:09.000Z", "agent": { "id": "8a4f500d" }, "event": { "category": "process" }, "process": { "name": "regsvr32.exe", "path": "C:\\Windows\\System32\\regsvr32.exe" } }
2525
----
26+
// TESTSETUP
2627

2728
You can now use the EQL search API to search this index using an EQL query.
2829

@@ -40,8 +41,121 @@ GET sec_logs/_eql/search
4041
"""
4142
}
4243
----
43-
// TEST[continued]
4444

4545
Because the `sec_log` index follows the ECS, you don't need to specify the
46-
event type or timestamp fields. The request uses the `event.category` and
47-
`@timestamp` fields by default.
46+
timestamp fields. The request uses the `@timestamp` field by default.
47+
48+
The API returns the following response containing the matching event:
49+
50+
[source,console-result]
51+
----
52+
{
53+
"took": 3,
54+
"timed_out": false,
55+
"hits": {
56+
"total": {
57+
"value": 1,
58+
"relation": "eq"
59+
},
60+
"events": [
61+
{
62+
"_index": "sec_logs",
63+
"_type": "_doc",
64+
"_id": "1",
65+
"_score": 0.9400072,
66+
"_source": {
67+
"@timestamp": "2020-12-07T11:06:07.000Z",
68+
"agent": {
69+
"id": "8a4f500d"
70+
},
71+
"event": {
72+
"category": "process"
73+
},
74+
"process": {
75+
"name": "cmd.exe",
76+
"path": "C:\\Windows\\System32\\cmd.exe"
77+
}
78+
}
79+
}
80+
]
81+
}
82+
}
83+
----
84+
// TESTRESPONSE[s/"took": 3/"took": $body.took/]
85+
86+
[discrete]
87+
[[eql-search-specify-event-type-field]]
88+
=== Specify an event type field
89+
90+
The EQL search API uses `event_type` as the required <<eql-required-fields,event
91+
type field>> by default. You can use the `event_type_field` parameter to specify
92+
another event type field.
93+
94+
For example, the following request specifies `file.type` as the event type
95+
field.
96+
97+
[source,console]
98+
----
99+
GET sec_logs/_eql/search
100+
{
101+
"event_type_field": "file.type",
102+
"query": """
103+
file where agent.id == "8a4f500d"
104+
"""
105+
}
106+
----
107+
108+
[discrete]
109+
[[eql-search-specify-timestamp-field]]
110+
=== Specify a timestamp field
111+
112+
The EQL search API uses `@timestamp` as the required <<eql-required-fields,event
113+
timestamp field>> by default. You can use the `timestamp_field` parameter to
114+
specify another timestamp field.
115+
116+
For example, the following request specifies `file.accessed` as the event
117+
timestamp field.
118+
119+
[source,console]
120+
----
121+
GET sec_logs/_eql/search
122+
{
123+
"timestamp_field": "file.accessed",
124+
"event_type_field": "event.category",
125+
"query": """
126+
file where (file.size > 1 and file.type == "file")
127+
"""
128+
}
129+
----
130+
131+
[discrete]
132+
[[eql-search-filter-query-dsl]]
133+
=== Filter using query DSL
134+
135+
You can use the `filter` parameter to specify an additional query using
136+
<<query-dsl,query DSL>>. This query filters the documents on which the EQL query
137+
runs.
138+
139+
For example, the following request uses a `range` query to filter the `sec_logs`
140+
index down to only documents with a `file.size` value greater than `1` but less
141+
than `1000000` bytes. The EQL query in `query` parameter then runs on these
142+
filtered documents.
143+
144+
[source,console]
145+
----
146+
GET sec_logs/_eql/search
147+
{
148+
"event_type_field": "event.category",
149+
"filter": {
150+
"range" : {
151+
"file.size" : {
152+
"gte" : 1,
153+
"lte" : 1000000
154+
}
155+
}
156+
},
157+
"query": """
158+
file where (file.type == "file" and file.name == "cmd.exe")
159+
"""
160+
}
161+
----

0 commit comments

Comments
 (0)