From e3d3c3400cfd46429ce60640a748d4b2af4eba0a Mon Sep 17 00:00:00 2001 From: James Rodewig Date: Wed, 4 Mar 2020 09:16:27 -0500 Subject: [PATCH] [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. --- docs/reference/eql/requirements.asciidoc | 2 +- docs/reference/eql/search.asciidoc | 66 ++++++++++++++++-------- 2 files changed, 46 insertions(+), 22 deletions(-) diff --git a/docs/reference/eql/requirements.asciidoc b/docs/reference/eql/requirements.asciidoc index 62e217df9c3..9f7acec7ee4 100644 --- a/docs/reference/eql/requirements.asciidoc +++ b/docs/reference/eql/requirements.asciidoc @@ -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 <> field. diff --git a/docs/reference/eql/search.asciidoc b/docs/reference/eql/search.asciidoc index 151d2f30407..66c4d3065d7 100644 --- a/docs/reference/eql/search.asciidoc +++ b/docs/reference/eql/search.asciidoc @@ -17,10 +17,14 @@ The following <> 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 <> 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,31 +103,32 @@ 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 <> 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 +<> 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] ---- GET sec_logs/_eql/search { - "event_category_field": "file.type", - "timestamp_field": "@timestamp", + "event_category_field": "file.type", "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" : {