Skip to content

Commit 9306c8d

Browse files
authored
[DOCS] Update EQL default event category and timestamp values (#53102)
Updates the documented default `event_category_field` and `timestamp_field` values for the EQL search API. Also updates related guidance in the EQL requirement docs. Relates to #53073.
1 parent 9f641dc commit 9306c8d

File tree

2 files changed

+46
-22
lines changed

2 files changed

+46
-22
lines changed

docs/reference/eql/requirements.asciidoc

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@ In {es}, EQL assumes each document in an index corresponds to an event.
2727
To search an index using EQL, each document in the index must contain the
2828
following field archetypes:
2929

30-
Event type::
30+
Event category::
3131
A field containing the event classification, such as `process`, `file`, or
3232
`network`. This is typically mapped as a <<keyword,`keyword`>> field.
3333

docs/reference/eql/search.asciidoc

Lines changed: 45 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -17,10 +17,14 @@ The following <<docs-bulk,bulk API>> request adds some example log data to the
1717
----
1818
PUT sec_logs/_bulk?refresh
1919
{"index":{"_index" : "sec_logs", "_id" : "1"}}
20-
{ "@timestamp": "2020-12-07T11:06:07.000Z", "agent": { "id": "8a4f500d" }, "event": { "category": "process" }, "process": { "name": "cmd.exe", "path": "C:\\Windows\\System32\\cmd.exe" } }
20+
{ "@timestamp": "2020-12-06T11:04:05.000Z", "agent": { "id": "8a4f500d" }, "event": { "category": "process" }, "process": { "name": "cmd.exe", "path": "C:\\Windows\\System32\\cmd.exe" } }
2121
{"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" } }
22+
{ "@timestamp": "2020-12-06T11:04:07.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" } }
2323
{"index":{"_index" : "sec_logs", "_id" : "3"}}
24+
{ "@timestamp": "2020-12-07T11:06:07.000Z", "agent": { "id": "8a4f500d" }, "event": { "category": "process" }, "process": { "name": "cmd.exe", "path": "C:\\Windows\\System32\\cmd.exe" } }
25+
{"index":{"_index" : "sec_logs", "_id" : "4"}}
26+
{ "@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" } }
27+
{"index":{"_index" : "sec_logs", "_id" : "5"}}
2428
{ "@timestamp": "2020-12-07T11:07:09.000Z", "agent": { "id": "8a4f500d" }, "event": { "category": "process" }, "process": { "name": "regsvr32.exe", "path": "C:\\Windows\\System32\\regsvr32.exe" } }
2529
----
2630
// TESTSETUP
@@ -35,34 +39,56 @@ specified in the `query` parameter. The EQL query matches events with an
3539
----
3640
GET sec_logs/_eql/search
3741
{
38-
"event_category_field": "event.category",
39-
"timestamp_field": "@timestamp",
4042
"query": """
4143
process where process.name == "cmd.exe"
4244
"""
4345
}
4446
----
4547

4648
Because the `sec_log` index follows the ECS, you don't need to specify the
47-
timestamp field. The request uses the `@timestamp` field by default.
49+
required <<eql-required-fields,event category or timestamp>> fields. The request
50+
uses the `event.category` and `@timestamp` fields by default.
4851

49-
The API returns the following response containing the matching event:
52+
The API returns the following response containing the matching events. Events
53+
in the response are sorted by timestamp, converted to milliseconds since the
54+
https://en.wikipedia.org/wiki/Unix_time[Unix epoch], in ascending order.
5055

5156
[source,console-result]
5257
----
5358
{
54-
"took": 3,
59+
"took": 60,
5560
"timed_out": false,
5661
"hits": {
5762
"total": {
58-
"value": 1,
63+
"value": 2,
5964
"relation": "eq"
6065
},
6166
"events": [
6267
{
6368
"_index": "sec_logs",
6469
"_id": "1",
6570
"_score": null,
71+
"_source": {
72+
"@timestamp": "2020-12-06T11:04:05.000Z",
73+
"agent": {
74+
"id": "8a4f500d"
75+
},
76+
"event": {
77+
"category": "process"
78+
},
79+
"process": {
80+
"name": "cmd.exe",
81+
"path": "C:\\Windows\\System32\\cmd.exe"
82+
}
83+
},
84+
"sort": [
85+
1607252645000
86+
]
87+
},
88+
{
89+
"_index": "sec_logs",
90+
"_id": "3",
91+
"_score": null,
6692
"_source": {
6793
"@timestamp": "2020-12-07T11:06:07.000Z",
6894
"agent": {
@@ -76,31 +102,32 @@ The API returns the following response containing the matching event:
76102
"path": "C:\\Windows\\System32\\cmd.exe"
77103
}
78104
},
79-
"sort" : [1607339167000]
105+
"sort": [
106+
1607339167000
107+
]
80108
}
81109
]
82110
}
83111
}
84112
----
85-
// TESTRESPONSE[s/"took": 3/"took": $body.took/]
113+
// TESTRESPONSE[s/"took": 60/"took": $body.took/]
86114

87115
[discrete]
88-
[[eql-search-specify-event-type-field]]
89-
=== Specify an event type field
116+
[[eql-search-specify-event-category-field]]
117+
=== Specify an event category field
90118

91-
The EQL search API uses `event.category` as the required <<eql-required-fields,event
92-
category field>> by default. You can use the `event_category_field` parameter to specify
93-
another event category field.
119+
The EQL search API uses `event.category` as the required
120+
<<eql-required-fields,event category field>> by default. You can use the
121+
`event_category_field` parameter to specify another event category field.
94122

95-
For example, the following request specifies `file.type` as the event type
123+
For example, the following request specifies `file.type` as the event category
96124
field.
97125

98126
[source,console]
99127
----
100128
GET sec_logs/_eql/search
101129
{
102-
"event_category_field": "file.type",
103-
"timestamp_field": "@timestamp",
130+
"event_category_field": "file.type",
104131
"query": """
105132
file where agent.id == "8a4f500d"
106133
"""
@@ -123,7 +150,6 @@ timestamp field.
123150
GET sec_logs/_eql/search
124151
{
125152
"timestamp_field": "file.accessed",
126-
"event_category_field": "event.category",
127153
"query": """
128154
file where (file.size > 1 and file.type == "file")
129155
"""
@@ -147,8 +173,6 @@ filtered documents.
147173
----
148174
GET sec_logs/_eql/search
149175
{
150-
"event_category_field": "event.category",
151-
"timestamp_field": "@timestamp",
152176
"filter": {
153177
"range" : {
154178
"file.size" : {

0 commit comments

Comments
 (0)