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

[DOCS] Make EQL example snippets more realistic (#60971) (#60974)

This commit is contained in:
James Rodewig 2020-08-11 12:01:31 -04:00 committed by GitHub
parent a1100bb770
commit c0fa582df4
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 117 additions and 131 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
docs/build.gradle
View File

@ -211,17 +211,17 @@ buildRestTests.setups['sec_logs'] = '''
refresh: true
body: |
{"index":{}}
{"@timestamp": "2020-12-06T11:04:05.000Z", "event": { "category": "process", "id": "edwCRnyD", "sequence": 1 }, "process": { "pid": 2012, "name": "cmd.exe", "executable": "C:\\\\Windows\\\\System32\\\\cmd.exe" }}
{"@timestamp": "2099-12-06T11:04:05.000Z", "event": { "category": "process", "id": "edwCRnyD", "sequence": 1 }, "process": { "pid": 2012, "name": "cmd.exe", "executable": "C:\\\\Windows\\\\System32\\\\cmd.exe" }}
{"index":{}}
{"@timestamp": "2020-12-06T11:04:07.000Z", "event": { "category": "file", "id": "dGCHwoeS", "sequence": 2 }, "file": { "accessed": "2020-12-07T11:07:08.000Z", "name": "cmd.exe", "path": "C:\\\\Windows\\\\System32\\\\cmd.exe", "type": "file", "size": 16384 }, "process": { "pid": 2012, "name": "cmd.exe", "executable": "C:\\\\Windows\\\\System32\\\\cmd.exe" }}
{"@timestamp": "2099-12-06T11:04:07.000Z", "event": { "category": "file", "id": "dGCHwoeS", "sequence": 2 }, "file": { "accessed": "2099-12-07T11:07:08.000Z", "name": "cmd.exe", "path": "C:\\\\Windows\\\\System32\\\\cmd.exe", "type": "file", "size": 16384 }, "process": { "pid": 2012, "name": "cmd.exe", "executable": "C:\\\\Windows\\\\System32\\\\cmd.exe" }}
{"index":{}}
{"@timestamp": "2020-12-07T11:06:07.000Z", "event": { "category": "process", "id": "cMyt5SZ2", "sequence": 3 }, "process": { "pid": 2012, "name": "cmd.exe", "executable": "C:\\\\Windows\\\\System32\\\\cmd.exe" } }
{"@timestamp": "2099-12-07T11:06:07.000Z", "event": { "category": "process", "id": "cMyt5SZ2", "sequence": 3 }, "process": { "pid": 2012, "name": "cmd.exe", "executable": "C:\\\\Windows\\\\System32\\\\cmd.exe" } }
{"index":{}}
{"@timestamp": "2020-12-07T11:07:08.000Z", "event": { "category": "file", "id": "bYA7gPay", "sequence": 4 }, "file": { "accessed": "2020-12-07T11:07:08.000Z", "name": "cmd.exe", "path": "C:\\\\Windows\\\\System32\\\\cmd.exe", "type": "file", "size": 16384 }, "process": { "pid": 2012, "name": "cmd.exe", "executable": "C:\\\\Windows\\\\System32\\\\cmd.exe" } }
{"@timestamp": "2099-12-07T11:07:09.000Z", "event": { "category": "process", "id": "aR3NWVOs", "sequence": 4 }, "process": { "pid": 2012, "name": "regsvr32.exe", "command_line": "regsvr32.exe /s /u /i:https://...RegSvr32.sct scrobj.dll", "executable": "C:\\\\Windows\\\\System32\\\\regsvr32.exe" }}
{"index":{}}
{"@timestamp": "2020-12-07T11:07:09.000Z", "event": { "category": "process", "id": "aR3NWVOs", "sequence": 5 }, "process": { "pid": 2012, "name": "regsvr32.exe", "executable": "C:\\\\Windows\\\\System32\\\\regsvr32.exe" }}
{"@timestamp": "2099-12-07T11:07:10.000Z", "event": { "category": "file", "id": "tZ1NWVOs", "sequence": 5 }, "process": { "pid": 2012, "name": "regsvr32.exe", "executable": "C:\\\\Windows\\\\System32\\\\regsvr32.exe" }, "file": { "path": "C:\\\\Windows\\\\System32\\\\scrobj.dll", "name": "scrobj.dll" }}
{"index":{}}
{"@timestamp": "2020-12-07T11:07:10.000Z", "event": { "category": "process", "id": "GTSmSqgz0U", "sequence": 6, "type": "termination" }, "process": { "pid": 2012, "name": "regsvr32.exe", "executable": "C:\\\\Windows\\\\System32\\\\regsvr32.exe" }}'''
{"@timestamp": "2099-12-07T11:07:10.000Z", "event": { "category": "process", "id": "GTSmSqgz0U", "sequence": 6, "type": "termination" }, "process": { "pid": 2012, "name": "regsvr32.exe", "executable": "C:\\\\Windows\\\\System32\\\\regsvr32.exe" }}'''
buildRestTests.setups['host'] = '''
# Fetch the http host. We use the host of the master because we know there will always be a master.

85
docs/reference/eql/eql-search-api.asciidoc
View File

@ -490,9 +490,9 @@ Original JSON body passed for the event at index time.
===== Basic query example
The following EQL search request searches for events with an `event.category` of
`file` that meet the following conditions:
`process` that meet the following conditions:
* A `file.name` of `cmd.exe`
* A `process.name` of `cmd.exe`
* An `process.pid` other than `2013`
[source,console]
@ -500,7 +500,7 @@ The following EQL search request searches for events with an `event.category` of
GET /my-index-000001/_eql/search
{
"query": """
file where (file.name == "cmd.exe" and process.pid != 2013)
process where (process.name == "cmd.exe" and process.pid != 2013)
"""
}
----
@ -532,52 +532,38 @@ the events in ascending, lexicographic order.
{
"_index": "my-index-000001",
"_type": "_doc",
"_id": "fwGeywNsBl8Y9Ys1x51b",
"_id": "babI3XMBI9IjHuIqU0S_",
"_score": null,
"_source": {
"@timestamp": "2020-12-06T11:04:07.000Z",
"@timestamp": "2099-12-06T11:04:05.000Z",
"event": {
"category": "file",
"id": "dGCHwoeS",
"sequence": 2,
},
"file": {
"accessed": "2020-12-07T11:07:08.000Z",
"name": "cmd.exe",
"path": "C:\\Windows\\System32\\cmd.exe",
"type": "file",
"size": 16384
"category": "process",
"id": "edwCRnyD",
"sequence": 1
},
"process": {
"pid": 2012,
"name": "cmd.exe",
"executable": "C:\\Windows\\System32\\cmd.exe",
"pid": 2012
"executable": "C:\\Windows\\System32\\cmd.exe"
}
}
},
{
"_index": "my-index-000001",
"_type": "_doc",
"_id": "AtOJ4UjUBAAx3XR5kcCM",
"_id": "b6bI3XMBI9IjHuIqU0S_",
"_score": null,
"_source": {
"@timestamp": "2020-12-07T11:07:08.000Z",
"@timestamp": "2099-12-07T11:06:07.000Z",
"event": {
"category": "file",
"id": "bYA7gPay",
"sequence": 4
},
"file": {
"accessed": "2020-12-07T11:07:08.000Z",
"name": "cmd.exe",
"path": "C:\\Windows\\System32\\cmd.exe",
"type": "file",
"size": 16384
"category": "process",
"id": "cMyt5SZ2",
"sequence": 3
},
"process": {
"pid": 2012,
"name": "cmd.exe",
"executable": "C:\\Windows\\System32\\cmd.exe",
"pid": 2012
"executable": "C:\\Windows\\System32\\cmd.exe"
}
}
}
@ -586,8 +572,8 @@ the events in ascending, lexicographic order.
}
----
// TESTRESPONSE[s/"took": 6/"took": $body.took/]
// TESTRESPONSE[s/"_id": "fwGeywNsBl8Y9Ys1x51b"/"_id": $body.hits.events.0._id/]
// TESTRESPONSE[s/"_id": "AtOJ4UjUBAAx3XR5kcCM"/"_id": $body.hits.events.1._id/]
// TESTRESPONSE[s/"_id": "babI3XMBI9IjHuIqU0S_"/"_id": $body.hits.events.0._id/]
// TESTRESPONSE[s/"_id": "b6bI3XMBI9IjHuIqU0S_"/"_id": $body.hits.events.1._id/]
[[eql-search-api-sequence-ex]]
===== Sequence query example
@ -651,49 +637,50 @@ shared `process.pid` value for each matching event.
"_type": "_doc",
"_id": "AtOJ4UjUBAAx3XR5kcCM",
"_version": 1,
"_seq_no": 3,
"_seq_no": 1,
"_primary_term": 1,
"_score": null,
"_source": {
"@timestamp": "2020-12-07T11:07:08.000Z",
"@timestamp": "2099-12-06T11:04:07.000Z",
"event": {
"category": "file",
"id": "bYA7gPay",
"sequence": 4
"id": "dGCHwoeS",
"sequence": 2
},
"file": {
"accessed": "2020-12-07T11:07:08.000Z",
"accessed": "2099-12-07T11:07:08.000Z",
"name": "cmd.exe",
"path": "C:\\Windows\\System32\\cmd.exe",
"type": "file",
"size": 16384
},
"process": {
"process": {
"pid": 2012,
"name": "cmd.exe",
"executable": "C:\\Windows\\System32\\cmd.exe",
"pid": 2012
"executable": "C:\\Windows\\System32\\cmd.exe"
}
}
},
{
"_index": "my-index-000001",
"_type": "_doc",
"_id": "yDwnGIJouOYGBzP0ZE9n",
"_id": "OQmfCaduce8zoHT93o4H",
"_version": 1,
"_seq_no": 4,
"_seq_no": 3,
"_primary_term": 1,
"_score": null,
"_source": {
"@timestamp": "2020-12-07T11:07:09.000Z",
"@timestamp": "2099-12-07T11:07:09.000Z",
"event": {
"category": "process",
"id": "aR3NWVOs",
"sequence": 5
"sequence": 4
},
"process": {
"process": {
"pid": 2012,
"name": "regsvr32.exe",
"executable": "C:\\Windows\\System32\\regsvr32.exe",
"pid": 2012
"command_line": "regsvr32.exe /s /u /i:https://...RegSvr32.sct scrobj.dll",
"executable": "C:\\Windows\\System32\\regsvr32.exe"
}
}
}
@ -705,4 +692,4 @@ shared `process.pid` value for each matching event.
----
// TESTRESPONSE[s/"took": 6/"took": $body.took/]
// TESTRESPONSE[s/"_id": "AtOJ4UjUBAAx3XR5kcCM"/"_id": $body.hits.sequences.0.events.0._id/]
// TESTRESPONSE[s/"_id": "yDwnGIJouOYGBzP0ZE9n"/"_id": $body.hits.sequences.0.events.1._id/]
// TESTRESPONSE[s/"_id": "OQmfCaduce8zoHT93o4H"/"_id": $body.hits.sequences.0.events.1._id/]

151
docs/reference/eql/eql.asciidoc
View File

@ -49,15 +49,16 @@ category field, you must specify it in the search request. See
You can use the <<eql-search-api,EQL search API>> to run an EQL search.
The following request searches `my-index-000001` for events with an
`event.category` of `process` and a `process.name` of `cmd.exe`. Each document
in `my-index-000001` includes a `@timestamp` and `event.category` field.
`event.category` of `process` and a `process.name` of `regsvr32.exe`. Each
document in `my-index-000001` includes a `@timestamp` and `event.category`
field.
[source,console]
----
GET /my-index-000001/_eql/search
{
"query": """
process where process.name == "cmd.exe"
process where process.name == "regsvr32.exe"
"""
}
----
@ -82,22 +83,23 @@ ascending order.
"relation": "eq"
},
"events": [
{
{
"_index": "my-index-000001",
"_type": "_doc",
"_id": "OQmfCaduce8zoHT93o4H",
"_score": null,
"_source": {
"@timestamp": "2020-12-06T11:04:05.000Z",
"@timestamp": "2099-12-07T11:07:09.000Z",
"event": {
"category": "process",
"id": "edwCRnyD",
"sequence": 1
"id": "aR3NWVOs",
"sequence": 4
},
"process": {
"name": "cmd.exe",
"executable": "C:\\Windows\\System32\\cmd.exe",
"pid": 2012
"pid": 2012,
"name": "regsvr32.exe",
"command_line": "regsvr32.exe /s /u /i:https://...RegSvr32.sct scrobj.dll",
"executable": "C:\\Windows\\System32\\regsvr32.exe"
}
}
},
@ -107,16 +109,17 @@ ascending order.
"_id": "xLkCaj4EujzdNSxfYLbO",
"_score": null,
"_source": {
"@timestamp": "2020-12-07T11:06:07.000Z",
"@timestamp": "2099-12-07T11:07:10.000Z",
"event": {
"category": "process",
"id": "cMyt5SZ2",
"sequence": 3
"id": "GTSmSqgz0U",
"sequence": 6,
"type": "termination"
},
"process": {
"name": "cmd.exe",
"executable": "C:\\Windows\\System32\\cmd.exe",
"pid": 2012
"pid": 2012,
"name": "regsvr32.exe",
"executable": "C:\\Windows\\System32\\regsvr32.exe"
}
}
}
@ -140,14 +143,14 @@ The following EQL search request matches a sequence that:
. Starts with an event with:
+
--
* An `event.category` of `file`
* A `file.name` of `cmd.exe`
* An `event.category` of `process`
* A `process.name` of `regsvr32.exe`
--
. Followed by an event with:
+
--
* An `event.category` of `process`
* A `process.name` that contains the substring `regsvr32`
* An `event.category` of `file`
* A `file.name` that contains the substring `scrobj.dll`
--
[source,console]
@ -156,8 +159,8 @@ GET /my-index-000001/_eql/search
{
"query": """
sequence
[ file where file.name == "cmd.exe" ]
[ process where stringContains(process.name, "regsvr32") ]
[ process where process.name == "regsvr32.exe" ]
[ file where stringContains(file.name, "scrobj.dll") ]
"""
}
----
@ -184,29 +187,23 @@ The API returns the following response. Matching sequences are included in the
{
"_index": "my-index-000001",
"_type": "_doc",
"_id": "AtOJ4UjUBAAx3XR5kcCM",
"_version" : 1,
"_seq_no" : 3,
"_primary_term" : 1,
"_id": "OQmfCaduce8zoHT93o4H",
"_version": 1,
"_seq_no": 3,
"_primary_term": 1,
"_score": null,
"_source": {
"@timestamp": "2020-12-07T11:07:08.000Z",
"@timestamp": "2099-12-07T11:07:09.000Z",
"event": {
"category": "file",
"id": "bYA7gPay",
"category": "process",
"id": "aR3NWVOs",
"sequence": 4
},
"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",
"executable": "C:\\Windows\\System32\\cmd.exe",
"pid": 2012
"pid": 2012,
"name": "regsvr32.exe",
"command_line": "regsvr32.exe /s /u /i:https://...RegSvr32.sct scrobj.dll",
"executable": "C:\\Windows\\System32\\regsvr32.exe"
}
}
},
@ -214,21 +211,25 @@ The API returns the following response. Matching sequences are included in the
"_index": "my-index-000001",
"_type": "_doc",
"_id": "yDwnGIJouOYGBzP0ZE9n",
"_version" : 1,
"_seq_no" : 4,
"_primary_term" : 1,
"_version": 1,
"_seq_no": 4,
"_primary_term": 1,
"_score": null,
"_source": {
"@timestamp": "2020-12-07T11:07:09.000Z",
"@timestamp": "2099-12-07T11:07:10.000Z",
"event": {
"category": "process",
"id": "aR3NWVOs",
"category": "file",
"id": "tZ1NWVOs",
"sequence": 5
},
"process": {
"pid": 2012,
"name": "regsvr32.exe",
"executable": "C:\\Windows\\System32\\regsvr32.exe",
"pid": 2012
"executable": "C:\\Windows\\System32\\regsvr32.exe"
},
"file": {
"path": "C:\\Windows\\System32\\scrobj.dll",
"name": "scrobj.dll"
}
}
}
@ -239,7 +240,7 @@ The API returns the following response. Matching sequences are included in the
}
----
// TESTRESPONSE[s/"took": 60/"took": $body.took/]
// TESTRESPONSE[s/"_id": "AtOJ4UjUBAAx3XR5kcCM"/"_id": $body.hits.sequences.0.events.0._id/]
// TESTRESPONSE[s/"_id": "OQmfCaduce8zoHT93o4H"/"_id": $body.hits.sequences.0.events.0._id/]
// TESTRESPONSE[s/"_id": "yDwnGIJouOYGBzP0ZE9n"/"_id": $body.hits.sequences.0.events.1._id/]
You can use the <<eql-with-maxspan-keywords,`with maxspan` keywords>> to
@ -255,8 +256,8 @@ GET /my-index-000001/_eql/search
{
"query": """
sequence with maxspan=1h
[ file where file.name == "cmd.exe" ]
[ process where stringContains(process.name, "regsvr32") ]
[ process where process.name == "regsvr32.exe" ]
[ file where stringContains(file.name, "scrobj.dll") ]
"""
}
----
@ -274,8 +275,8 @@ GET /my-index-000001/_eql/search
{
"query": """
sequence with maxspan=1h
[ file where file.name == "cmd.exe" ] by process.pid
[ process where stringContains(process.name, "regsvr32") ] by process.pid
[ process where process.name == "regsvr32.exe" ] by process.pid
[ file where stringContains(file.name, "scrobj.dll") ] by process.pid
"""
}
----
@ -291,8 +292,8 @@ GET /my-index-000001/_eql/search
{
"query": """
sequence by process.pid with maxspan=1h
[ file where file.name == "cmd.exe" ]
[ process where stringContains(process.name, "regsvr32") ]
[ process where process.name == "regsvr32.exe" ]
[ file where stringContains(file.name, "scrobj.dll") ]
"""
}
----
@ -322,29 +323,23 @@ contains the shared `process.pid` value for each matching event.
{
"_index": "my-index-000001",
"_type": "_doc",
"_id": "AtOJ4UjUBAAx3XR5kcCM",
"_id": "OQmfCaduce8zoHT93o4H",
"_version": 1,
"_seq_no": 3,
"_primary_term": 1,
"_score": null,
"_source": {
"@timestamp": "2020-12-07T11:07:08.000Z",
"@timestamp": "2099-12-07T11:07:09.000Z",
"event": {
"category": "file",
"id": "bYA7gPay",
"category": "process",
"id": "aR3NWVOs",
"sequence": 4
},
"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",
"executable": "C:\\Windows\\System32\\cmd.exe",
"pid": 2012
"pid": 2012,
"name": "regsvr32.exe",
"command_line": "regsvr32.exe /s /u /i:https://...RegSvr32.sct scrobj.dll",
"executable": "C:\\Windows\\System32\\regsvr32.exe"
}
}
},
@ -357,16 +352,20 @@ contains the shared `process.pid` value for each matching event.
"_primary_term": 1,
"_score": null,
"_source": {
"@timestamp": "2020-12-07T11:07:09.000Z",
"@timestamp": "2099-12-07T11:07:10.000Z",
"event": {
"category": "process",
"id": "aR3NWVOs",
"category": "file",
"id": "tZ1NWVOs",
"sequence": 5
},
"process": {
"pid": 2012,
"name": "regsvr32.exe",
"executable": "C:\\Windows\\System32\\regsvr32.exe",
"pid": 2012
"executable": "C:\\Windows\\System32\\regsvr32.exe"
},
"file": {
"path": "C:\\Windows\\System32\\scrobj.dll",
"name": "scrobj.dll"
}
}
}
@ -377,7 +376,7 @@ contains the shared `process.pid` value for each matching event.
}
----
// TESTRESPONSE[s/"took": 60/"took": $body.took/]
// TESTRESPONSE[s/"_id": "AtOJ4UjUBAAx3XR5kcCM"/"_id": $body.hits.sequences.0.events.0._id/]
// TESTRESPONSE[s/"_id": "OQmfCaduce8zoHT93o4H"/"_id": $body.hits.sequences.0.events.0._id/]
// TESTRESPONSE[s/"_id": "yDwnGIJouOYGBzP0ZE9n"/"_id": $body.hits.sequences.0.events.1._id/]
You can use the <<eql-until-keyword,`until` keyword>> to specify an expiration
@ -393,8 +392,8 @@ GET /my-index-000001/_eql/search
{
"query": """
sequence by process.pid with maxspan=1h
[ file where file.name == "cmd.exe" ]
[ process where stringContains(process.name, "regsvr32") ]
[ process where process.name == "regsvr32.exe" ]
[ file where stringContains(file.name, "scrobj.dll") ]
until [ process where event.type == "termination" ]
"""
}