honeymoose
/
OpenSearch
mirror of https://github.com/honeymoose/OpenSearch.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

[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.
This commit is contained in:
James Rodewig 2020-03-04 09:16:27 -05:00
parent 0c4bf64095
commit e3d3c3400c
2 changed files with 46 additions and 22 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/reference/eql/requirements.asciidoc
View File

@ -27,7 +27,7 @@ In {es}, EQL assumes each document in an index corresponds to an event.
To search an index using EQL, each document in the index must contain the
following field archetypes:
Event type::
Event category::
A field containing the event classification, such as `process`, `file`, or
`network`. This is typically mapped as a <<keyword,`keyword`>> field.

64
docs/reference/eql/search.asciidoc
View File

@ -17,10 +17,14 @@ The following <<docs-bulk,bulk API>> request adds some example log data to the
----
PUT sec_logs/_bulk?refresh
{"index":{"_index" : "sec_logs", "_id" : "1"}}
{ "@timestamp": "2020-12-07T11:06:07.000Z", "agent": { "id": "8a4f500d" }, "event": { "category": "process" }, "process": { "name": "cmd.exe", "path": "C:\\Windows\\System32\\cmd.exe" } }
{ "@timestamp": "2020-12-06T11:04:05.000Z", "agent": { "id": "8a4f500d" }, "event": { "category": "process" }, "process": { "name": "cmd.exe", "path": "C:\\Windows\\System32\\cmd.exe" } }
{"index":{"_index" : "sec_logs", "_id" : "2"}}
{ "@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" } }
{ "@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" } }
{"index":{"_index" : "sec_logs", "_id" : "3"}}
{ "@timestamp": "2020-12-07T11:06:07.000Z", "agent": { "id": "8a4f500d" }, "event": { "category": "process" }, "process": { "name": "cmd.exe", "path": "C:\\Windows\\System32\\cmd.exe" } }
{"index":{"_index" : "sec_logs", "_id" : "4"}}
{ "@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" } }
{"index":{"_index" : "sec_logs", "_id" : "5"}}
{ "@timestamp": "2020-12-07T11:07:09.000Z", "agent": { "id": "8a4f500d" }, "event": { "category": "process" }, "process": { "name": "regsvr32.exe", "path": "C:\\Windows\\System32\\regsvr32.exe" } }
----
// TESTSETUP
@ -35,8 +39,6 @@ specified in the `query` parameter. The EQL query matches events with an
----
GET sec_logs/_eql/search
{
"event_category_field": "event.category",
"timestamp_field": "@timestamp",
"query": """
process where process.name == "cmd.exe"
"""
@ -44,18 +46,21 @@ GET sec_logs/_eql/search
----
Because the `sec_log` index follows the ECS, you don't need to specify the
timestamp field. The request uses the `@timestamp` field by default.
required <<eql-required-fields,event category or timestamp>> fields. The request
uses the `event.category` and `@timestamp` fields by default.
The API returns the following response containing the matching event:
The API returns the following response containing the matching events. Events
in the response are sorted by timestamp, converted to milliseconds since the
https://en.wikipedia.org/wiki/Unix_time[Unix epoch], in ascending order.
[source,console-result]
----
{
"took": 3,
"took": 60,
"timed_out": false,
"hits": {
"total": {
"value": 1,
"value": 2,
"relation": "eq"
},
"events": [
@ -64,6 +69,27 @@ The API returns the following response containing the matching event:
"_type": "_doc",
"_id": "1",
"_score": null,
"_source": {
"@timestamp": "2020-12-06T11:04:05.000Z",
"agent": {
"id": "8a4f500d"
},
"event": {
"category": "process"
},
"process": {
"name": "cmd.exe",
"path": "C:\\Windows\\System32\\cmd.exe"
}
},
"sort": [
1607252645000
]
},
{
"_index": "sec_logs",
"_id": "3",
"_score": null,
"_source": {
"@timestamp": "2020-12-07T11:06:07.000Z",
"agent": {
@ -77,23 +103,25 @@ The API returns the following response containing the matching event:
"path": "C:\\Windows\\System32\\cmd.exe"
}
},
"sort" : [1607339167000]
"sort": [
1607339167000
]
}
]
}
}
----
// TESTRESPONSE[s/"took": 3/"took": $body.took/]
// TESTRESPONSE[s/"took": 60/"took": $body.took/]
[discrete]
[[eql-search-specify-event-type-field]]
=== Specify an event type field
[[eql-search-specify-event-category-field]]
=== Specify an event category field
The EQL search API uses `event.category` as the required <<eql-required-fields,event
category field>> by default. You can use the `event_category_field` parameter to specify
another event category field.
The EQL search API uses `event.category` as the required
<<eql-required-fields,event category field>> by default. You can use the
`event_category_field` parameter to specify another event category field.
For example, the following request specifies `file.type` as the event type
For example, the following request specifies `file.type` as the event category
field.
[source,console]
@ -101,7 +129,6 @@ field.
GET sec_logs/_eql/search
{
"event_category_field": "file.type",
"timestamp_field": "@timestamp",
"query": """
file where agent.id == "8a4f500d"
"""
@ -124,7 +151,6 @@ timestamp field.
GET sec_logs/_eql/search
{
"timestamp_field": "file.accessed",
"event_category_field": "event.category",
"query": """
file where (file.size > 1 and file.type == "file")
"""
@ -148,8 +174,6 @@ filtered documents.
----
GET sec_logs/_eql/search
{
"event_category_field": "event.category",
"timestamp_field": "@timestamp",
"filter": {
"range" : {
"file.size" : {