From 4a6caadfce24f525b00266d2570308fc6d94f801 Mon Sep 17 00:00:00 2001 From: Ben Skelker Date: Mon, 5 Oct 2020 12:30:11 +0300 Subject: [PATCH 1/8] adds eql rule to api docs --- .../api/rules/rules-api-create.asciidoc | 129 +++++++++++++++++- 1 file changed, 123 insertions(+), 6 deletions(-) diff --git a/docs/detections/api/rules/rules-api-create.asciidoc b/docs/detections/api/rules/rules-api-create.asciidoc index 55573fedc3..f8324b952c 100644 --- a/docs/detections/api/rules/rules-api-create.asciidoc +++ b/docs/detections/api/rules/rules-api-create.asciidoc @@ -6,7 +6,9 @@ Creates a new detection rule. You can create these types of rules: * *Query rules*: Searches the defined indices and creates an alert when -a document matches the rule's query. +a document matches the rule's KQL query. +* *EQL*: Searches the defined indices and creates an alert when results match an +{ref}/eql.html[Event Query Language (EQL)] query. * *Threshold rules*: Searches the defined indices and creates an alert when the number of times the specified field's value meets the threshold during a single execution. When there are multiple values that meet the threshold, an alert is @@ -73,8 +75,20 @@ calls, see: ==== Request body -A JSON object that defines the rule's values. +A JSON object that defines the rule's values: +* <> +* <> +* <> +* <> +* <> +* <> +* <> +* <> +* <> +* <> + +[[ref-fields-all]] ===== Required fields for all rule types [width="100%",options="header"] @@ -105,6 +119,7 @@ occurred |type |String a|Data type on which the rule is based: +* `eql`: EQL query (see {ref}/eql.html[Event Query Language) * `query`: query with or without additional filters. * `saved_query`: saved search, identified in the `saved_id` field. * `machine_learning`: rule based on a {ml} job's anomaly scores. @@ -113,6 +128,7 @@ specified field. |============================================== +[[req-fields-query-threshold]] ===== Required field for query and threshold rules [width="100%",options="header"] @@ -125,6 +141,7 @@ that's not very useful. |============================================== +[[req-fields-threshold]] ===== Required field for threshold rules [width="100%",options="header"] @@ -142,6 +159,7 @@ generated. |============================================== +[[req-fields-saved-query]] ===== Required field for saved-query rules [width="100%",options="header"] @@ -152,6 +170,18 @@ generated. |============================================== +[[req-fields-eql]] +===== Required field for EQL rules + +[width="100%",options="header"] +|============================================== +|Name |Type |Description + +|language |String |Must be `eql`. + +|============================================== + +[[req-fields-ml]] ===== Required fields for machine-learning rules [width="100%",options="header"] @@ -166,6 +196,7 @@ anomaly scores. |============================================== +[[opt-fields-all]] ===== Optional fields for all rule types [width="100%",options="header"] @@ -239,7 +270,8 @@ Required when `actions` are used to send notifications. |============================================== -===== Optional fields for query and threshold rules +[[opt-fields-query-eql]] +===== Optional fields for query and EQL rules [width="100%",options="header"] |============================================== @@ -257,6 +289,25 @@ valid in only the rule's {kib} space (`single`) or in all {kib} spaces (`agnostic`). * `type` (string, required): The exception type, which must be either a detection rule exception (`detection`) or an endpoint exception (`endpoint`). +|============================================== + +[[opt-fields-query-threshold]] +===== Optional fields for query and threshold rules + +[width="100%",options="header"] +|============================================== +|Name |Type |Description + +|language |String |Determines the query language, which must be +`kuery` or `lucene`. Defaults to `kuery`. +|============================================== + +[[opt-fields-eql-query-threshold]] +===== Optional fields for EQL, query and threshold rules + +[width="100%",options="header"] +|============================================== +|Name |Type |Description |filters |Object[] |The {ref}/query-filter-context.html[query and filter context] array used to define the conditions for when alerts are created from @@ -267,9 +318,6 @@ Security Solution indices defined on the {kib} Advanced Settings page (*Kibana* → *Stack Management* → *Advanced Settings* → `securitySolution:defaultIndex`). -|language |String |Determines the query language, which must be -`kuery` or `lucene`. Defaults to `kuery`. - |risk_score_mapping |Object[] a|Overrides generated alerts' `risk_score` with a value from the source event: @@ -574,6 +622,32 @@ POST api/detection_engine/rules -------------------------------------------------- // KIBANA +*Example 4* + +EQL rule that creates alerts when the Windows `rundll32.exe` process makes +unusual network connections: + +[source,console] +-------------------------------------------------- +POST api/detection_engine/rules +{ + "rule_id": "eql-outbound-rundll32-connections", + "risk_score": 21, + "description": "Unusual rundll32.exe network connection", + "name": "rundll32.exe network connection", + "severity": "low", + "tags": [ + "EQL", + "Windows", + "rundll32.exe" + ], + "type": "eql", + "language": "eql", + "query": "sequence by process.entity_id with maxspan=2h [process where event.type in (\"start\", \"process_started\") and (process.name == \"rundll32.exe\" or process.pe.original_file_name == \"rundll32.exe\") and ((process.args == \"rundll32.exe\" and process.args_count == 1) or (process.args != \"rundll32.exe\" and process.args_count == 0))] [network where event.type == \"connection\" and (process.name == \"rundll32.exe\" or process.pe.original_file_name == \"rundll32exe\")]" +} ' | jq +-------------------------------------------------- +// KIBANA + ==== Response code `200`:: @@ -763,3 +837,46 @@ Example response for a threshold rule: } } -------------------------------------------------- + +Example response for an EQL rule: + +[source,json] +-------------------------------------------------- +{ + "author": [], + "created_at": "2020-10-05T09:06:16.392Z", + "updated_at": "2020-10-05T09:06:16.403Z", + "created_by": "Liverpool", + "description": "Unusual rundll32.exe network connection", + "enabled": true, + "false_positives": [], + "from": "now-6m", + "id": "93808cae-b05b-4dc9-8479-73574b50f8b1", + "immutable": false, + "interval": "5m", + "rule_id": "eql-outbound-rundll32-connections", + "output_index": ".siem-signals-default", + "max_signals": 100, + "risk_score": 21, + "risk_score_mapping": [], + "name": "rundll32.exe network connection", + "references": [], + "severity": "low", + "severity_mapping": [], + "updated_by": "Liverpool", + "tags": [ + "EQL", + "Windows", + "rundll32.exe" + ], + "to": "now", + "type": "eql", + "threat": [], + "version": 1, + "exceptions_list": [], + "actions": [], + "throttle": "no_actions", + "query": "sequence by process.entity_id with maxspan=2h [process where event.type in (\"start\", \"process_started\") and (process.name == \"rundll32.exe\" or process.pe.original_file_name == \"rundll32.exe\") and ((process.args == \"rundll32.exe\" and process.args_count == 1) or (process.args != \"rundll32.exe\" and process.args_count == 0))] [network where event.type == \"connection\" and (process.name == \"rundll32.exe\" or process.pe.original_file_name == \"rundll32exe\")]", + "language": "eql" +} +-------------------------------------------------- From 872d7844d45d24293290730ab800eb96871eab62 Mon Sep 17 00:00:00 2001 From: Ben Skelker Date: Mon, 5 Oct 2020 13:20:12 +0300 Subject: [PATCH 2/8] starts adding threat match rule type --- docs/detections/api/rules/rules-api-create.asciidoc | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/docs/detections/api/rules/rules-api-create.asciidoc b/docs/detections/api/rules/rules-api-create.asciidoc index f8324b952c..e9158c4b84 100644 --- a/docs/detections/api/rules/rules-api-create.asciidoc +++ b/docs/detections/api/rules/rules-api-create.asciidoc @@ -8,7 +8,7 @@ You can create these types of rules: * *Query rules*: Searches the defined indices and creates an alert when a document matches the rule's KQL query. * *EQL*: Searches the defined indices and creates an alert when results match an -{ref}/eql.html[Event Query Language (EQL)] query. +{ref}/eql.html[Event Query Language (EQL)] query. EQL * *Threshold rules*: Searches the defined indices and creates an alert when the number of times the specified field's value meets the threshold during a single execution. When there are multiple values that meet the threshold, an alert is @@ -21,6 +21,11 @@ the rule's search results. If you're interested, see more information. * *{ml-cap} rules*: Creates an alert when a {ml} job discovers an anomaly above the defined threshold (see <>). +* *Threat match*: Creates an alert when fields match values defined in the +specified {ref}/indices-create-index.html[{es} indices]. The indices field +mapping must be {ecs-ref}[ECS-compliant]. For example, you can create an index +for IP addresses and use this index to create an alert whenever an +event's `destination.ip` equals a value in the index. IMPORTANT: To create {ml} rules, you must have the https://www.elastic.co/subscriptions[appropriate license] or use a @@ -123,6 +128,8 @@ occurred * `query`: query with or without additional filters. * `saved_query`: saved search, identified in the `saved_id` field. * `machine_learning`: rule based on a {ml} job's anomaly scores. +* `threat_match`: rule that matches event values with the specified {es} +indices. * `threshold`: rule based on the number of times a `query` matches the specified field. From df13b0b96d2d09c14a9c185ff84a5bfc539eac4e Mon Sep 17 00:00:00 2001 From: Ben Skelker Date: Tue, 6 Oct 2020 11:44:48 +0300 Subject: [PATCH 3/8] threat-match cont --- .../api/rules/rules-api-create.asciidoc | 138 ++++++++++++++++-- 1 file changed, 124 insertions(+), 14 deletions(-) diff --git a/docs/detections/api/rules/rules-api-create.asciidoc b/docs/detections/api/rules/rules-api-create.asciidoc index e9158c4b84..3f3d40b8c9 100644 --- a/docs/detections/api/rules/rules-api-create.asciidoc +++ b/docs/detections/api/rules/rules-api-create.asciidoc @@ -8,7 +8,7 @@ You can create these types of rules: * *Query rules*: Searches the defined indices and creates an alert when a document matches the rule's KQL query. * *EQL*: Searches the defined indices and creates an alert when results match an -{ref}/eql.html[Event Query Language (EQL)] query. EQL +{ref}/eql.html[Event Query Language (EQL)] query. * *Threshold rules*: Searches the defined indices and creates an alert when the number of times the specified field's value meets the threshold during a single execution. When there are multiple values that meet the threshold, an alert is @@ -22,10 +22,10 @@ more information. * *{ml-cap} rules*: Creates an alert when a {ml} job discovers an anomaly above the defined threshold (see <>). * *Threat match*: Creates an alert when fields match values defined in the -specified {ref}/indices-create-index.html[{es} indices]. The indices field -mapping must be {ecs-ref}[ECS-compliant]. For example, you can create an index -for IP addresses and use this index to create an alert whenever an -event's `destination.ip` equals a value in the index. +specified {ref}/indices-create-index.html[{es} index]. For example, you can +create an index for IP addresses and use this index to create an alert whenever +an event's `destination.ip` equals a value in the index. The index's field +mappings should be {ecs-ref}[ECS-compliant]. IMPORTANT: To create {ml} rules, you must have the https://www.elastic.co/subscriptions[appropriate license] or use a @@ -88,8 +88,10 @@ A JSON object that defines the rule's values: * <> * <> * <> +* <> * <> * <> +* <> * <> * <> @@ -124,27 +126,27 @@ occurred |type |String a|Data type on which the rule is based: -* `eql`: EQL query (see {ref}/eql.html[Event Query Language) +* `eql`: EQL query (see {ref}/eql.html[Event Query Language]). * `query`: query with or without additional filters. * `saved_query`: saved search, identified in the `saved_id` field. * `machine_learning`: rule based on a {ml} job's anomaly scores. -* `threat_match`: rule that matches event values with the specified {es} -indices. +* `threat_match`: rule that matches event values with values the specified {es} +index. * `threshold`: rule based on the number of times a `query` matches the specified field. |============================================== [[req-fields-query-threshold]] -===== Required field for query and threshold rules +===== Required field for query, threat-match and threshold rules [width="100%",options="header"] |============================================== |Name |Type |Description |query |String a|{kibana-ref}/search.html[Query] used by the rule to create -alerts. Technically, this is not required and defaults to an empty string but -that's not very useful. +alerts. For threat-match rules, only the query's results are used to determine +whether an alert is generated. |============================================== @@ -203,6 +205,35 @@ anomaly scores. |============================================== +[[req-fields-threat-match]] +===== Required fields for threat-match rules + +[width="100%",options="header"] +|============================================== +|Name |Type |Description + +|threat_index |String[] |{es} indices used to check which field values generate +alerts. + +|threat_query |String |Query used to determine which fields in the {es} index +are used for generating alerts. + +|threat_mapping |Object[] a|Array of `entries` objects that define mappings +between the source event fields and the values in the {es} threat index. Each +`entries` object must contain these fields: + +* `field`: field from the event indices on which the rule runs +* `type`: must be `mapping` +* `value`: field from the {es} threat index + +You can use Boolean `and` and `or` logic to define the conditions for when +matching fields and values generate alerts. Sibling `entries` objects +are evaluated using `or` logic, whereas multiple entries in a single `entries` +object use `and` logic. See <> for an example that +uses both `and` and `or` logic. + +|============================================== + [[opt-fields-all]] ===== Optional fields for all rule types @@ -278,7 +309,7 @@ Required when `actions` are used to send notifications. |============================================== [[opt-fields-query-eql]] -===== Optional fields for query and EQL rules +===== Optional fields for query, threat-match and EQL rules [width="100%",options="header"] |============================================== @@ -298,8 +329,20 @@ valid in only the rule's {kib} space (`single`) or in all {kib} spaces a detection rule exception (`detection`) or an endpoint exception (`endpoint`). |============================================== +[[opt-fields-threat-match]] +===== Optional fields for threat-match rules + +[width="100%",options="header"] +|============================================== +|Name |Type |Description + +|threat_filter |Object[] +|{ref}/query-filter-context.html[Query and filter context] array used to filter +documents from the {es} index containing the threat values. +|============================================== + [[opt-fields-query-threshold]] -===== Optional fields for query and threshold rules +===== Optional fields for query, threat-match and threshold rules [width="100%",options="header"] |============================================== @@ -651,10 +694,77 @@ POST api/detection_engine/rules "type": "eql", "language": "eql", "query": "sequence by process.entity_id with maxspan=2h [process where event.type in (\"start\", \"process_started\") and (process.name == \"rundll32.exe\" or process.pe.original_file_name == \"rundll32.exe\") and ((process.args == \"rundll32.exe\" and process.args_count == 1) or (process.args != \"rundll32.exe\" and process.args_count == 0))] [network where event.type == \"connection\" and (process.name == \"rundll32.exe\" or process.pe.original_file_name == \"rundll32exe\")]" -} ' | jq +} +-------------------------------------------------- +// KIBANA + +[[threat-match-example]] +*Example 5* + +Threat-match rule that creates an alert when one of the following is true: + +* The event's destination IP address *and* port number matches destination IP +*and* port values in the `threat_index` index. +* The event's source IP address matches a host IP address value in the +`threat_index` index. + +[source,console] +-------------------------------------------------- +POST api/detection_engine/rules +{ + "type": "threat_match", + "index": [ + "packetbeat-*" + ], + "query": "destination.ip:* or host.ip:*", + "threat_index": [ + "ip-threat-list" <1> + ], + "threat_query": "*:*", <2> + "threat_mapping": [ + { + "entries": [ <3> + { + "field": "destination.ip", + "type": "mapping", + "value": "destination.ip" + }, + { + "field": "destination.port", + "type": "mapping", + "value": "destination.port" + } + ] + }, + { + "entries": [ <4> + { + "field": "source.ip", + "type": "mapping", + "value": "host.ip" + } + ] + } + ], + "risk_score": 50, + "severity": "medium", + "name": "Bad IP threat match", + "description": "Checks the ip-threat-list index for bad IP addresses" +} -------------------------------------------------- // KIBANA +<1> The {es} index used for matching threat values. +<2> Query defining which threat index fields are used for matching values. In +this example, all values from the `ip-threat-list` index are used. +<3> Multiple objects in a single `entries` element are evaluated using `and` +logic. In this example, both the event's `destination.ip` and +`destination.port` values must match the corresponding field values in the +`ip-threat-list`. +<4> Sibling `entries` are evaluated using `or` logic. In this example, +an alert is generated when at least one `entries` object evaluates to +`true`. + ==== Response code `200`:: From 417a5eb3014a961fd94402bd66b34fbaf589eed9 Mon Sep 17 00:00:00 2001 From: Ben Skelker Date: Tue, 6 Oct 2020 11:56:02 +0300 Subject: [PATCH 4/8] adds threat-match rule response --- .../api/rules/rules-api-create.asciidoc | 73 ++++++++++++++++++- 1 file changed, 72 insertions(+), 1 deletion(-) diff --git a/docs/detections/api/rules/rules-api-create.asciidoc b/docs/detections/api/rules/rules-api-create.asciidoc index 3f3d40b8c9..88f761d4db 100644 --- a/docs/detections/api/rules/rules-api-create.asciidoc +++ b/docs/detections/api/rules/rules-api-create.asciidoc @@ -749,7 +749,7 @@ POST api/detection_engine/rules "risk_score": 50, "severity": "medium", "name": "Bad IP threat match", - "description": "Checks the ip-threat-list index for bad IP addresses" + "description": "Checks for bad IP addresses listed in the ip-threat-list index" } -------------------------------------------------- // KIBANA @@ -997,3 +997,74 @@ Example response for an EQL rule: "language": "eql" } -------------------------------------------------- + +Example response for a threat-match rule: + +[source,json] +-------------------------------------------------- +{ + "author": [], + "created_at": "2020-10-06T07:07:58.227Z", + "updated_at": "2020-10-06T07:07:58.237Z", + "created_by": "Liverpool", + "description": "Checks for bad IP addresses listed in the ip-threat-list index", + "enabled": true, + "false_positives": [], + "from": "now-6m", + "id": "d5daa13f-81fb-4b13-be2f-31011e1d9ae1", + "immutable": false, + "interval": "5m", + "rule_id": "608501e4-c768-4f64-9326-cec55b5d439b", + "output_index": ".siem-signals-default", + "max_signals": 100, + "risk_score": 50, + "risk_score_mapping": [], + "name": "Bad IP threat match", + "references": [], + "severity": "medium", + "severity_mapping": [], + "updated_by": "Liverpool", + "tags": [], + "to": "now", + "type": "threat_match", + "threat": [], + "version": 1, + "exceptions_list": [], + "actions": [], + "index": [ + "packetbeat-*" + ], + "throttle": "no_actions", + "query": "destination.ip:* or host.ip:*", + "language": "kuery", + "threat_query": "*:*", + "threat_index": [ + "ip-threat-list" + ], + "threat_mapping": [ + { + "entries": [ + { + "field": "destination.ip", + "type": "mapping", + "value": "destination.ip" + }, + { + "field": "destination.port", + "type": "mapping", + "value": "destination.port" + } + ] + }, + { + "entries": [ + { + "field": "source.ip", + "type": "mapping", + "value": "host.ip" + } + ] + } + ] +} +-------------------------------------------------- From 9b03de28031d11553789b887f507e40a0a46e95e Mon Sep 17 00:00:00 2001 From: Ben Skelker Date: Tue, 6 Oct 2020 12:11:22 +0300 Subject: [PATCH 5/8] update rule api chnages --- .../api/rules/rules-api-create.asciidoc | 4 +- .../api/rules/rules-api-update.asciidoc | 84 +++++++++++++++++-- 2 files changed, 77 insertions(+), 11 deletions(-) diff --git a/docs/detections/api/rules/rules-api-create.asciidoc b/docs/detections/api/rules/rules-api-create.asciidoc index 88f761d4db..0940d547d1 100644 --- a/docs/detections/api/rules/rules-api-create.asciidoc +++ b/docs/detections/api/rules/rules-api-create.asciidoc @@ -19,13 +19,13 @@ alert is generated for every source IP address that appears in at least 10 of the rule's search results. If you're interested, see {ref}/search-aggregations-bucket-terms-aggregation.html[Terms Aggregation] for more information. -* *{ml-cap} rules*: Creates an alert when a {ml} job discovers an anomaly above -the defined threshold (see <>). * *Threat match*: Creates an alert when fields match values defined in the specified {ref}/indices-create-index.html[{es} index]. For example, you can create an index for IP addresses and use this index to create an alert whenever an event's `destination.ip` equals a value in the index. The index's field mappings should be {ecs-ref}[ECS-compliant]. +* *{ml-cap} rules*: Creates an alert when a {ml} job discovers an anomaly above +the defined threshold (see <>). IMPORTANT: To create {ml} rules, you must have the https://www.elastic.co/subscriptions[appropriate license] or use a diff --git a/docs/detections/api/rules/rules-api-update.asciidoc b/docs/detections/api/rules/rules-api-update.asciidoc index 9709cba6eb..bb93b3315f 100644 --- a/docs/detections/api/rules/rules-api-update.asciidoc +++ b/docs/detections/api/rules/rules-api-update.asciidoc @@ -24,7 +24,7 @@ A JSON object with: IMPORTANT: If you call `PUT` to update a rule, all unspecified fields are deleted. You cannot modify the `id` or `rule_id` values. -For `PATCH` calls, any of the fields can be modified, whereas for `PUT` calls, +For `PATCH` calls any of the fields can be modified, whereas for `PUT` calls some fields are required. ===== Fields required for `PUT` calls @@ -57,23 +57,26 @@ occurred |type |String a|Data type on which the rule is based: +* `eql`: EQL query (see {ref}/eql.html[Event Query Language]). * `query`: query with or without additional filters. * `saved_query`: saved search, identified in the `saved_id` field. * `machine_learning`: rule based on a {ml} job's anomaly scores. +* `threat_match`: rule that matches event values with values the specified {es} +index. * `threshold`: rule based on the number of times a `query` matches the specified field. |============================================== -===== Field required for query and threshold rules `PUT` calls +===== Field required for query, threat-match and threshold rules `PUT` calls [width="100%",options="header"] |============================================== |Name |Type |Description |query |String a|{kibana-ref}/search.html[Query] used by the rule to create -alerts. Technically, this is not required and defaults to an empty string but -that's not very useful. +alerts. For threat-match rules, only the query's results are used to determine +whether an alert is generated. |============================================== @@ -104,6 +107,16 @@ generated. |============================================== +===== Field required for EQL rules `PUT` calls + +[width="100%",options="header"] +|============================================== +|Name |Type |Description + +|language |String |Must be `eql`. + +|============================================== + ===== Fields required for machine-learning rules `PUT` calls [width="100%",options="header"] @@ -118,6 +131,34 @@ anomaly scores. |============================================== +===== Fields required for threat-match rules `PUT` calls + +[width="100%",options="header"] +|============================================== +|Name |Type |Description + +|threat_index |String[] |{es} indices used to check which field values generate +alerts. + +|threat_query |String |Query used to determine which fields in the {es} index +are used for generating alerts. + +|threat_mapping |Object[] a|Array of `entries` objects that define mappings +between the source event fields and the values in the {es} threat index. Each +`entries` object must contain these fields: + +* `field`: field from the event indices on which the rule runs +* `type`: must be `mapping` +* `value`: field from the {es} threat index + +You can use Boolean `and` and `or` logic to define the conditions for when +matching fields and values generate alerts. Sibling `entries` objects +are evaluated using `or` logic, whereas multiple entries in a single `entries` +object use `and` logic. See <> for an example that +uses both `and` and `or` logic. + +|============================================== + ===== Optional fields for all rule types [width="100%",options="header"] @@ -191,7 +232,7 @@ number. |============================================== -===== Optional fields for query and threshold rules +===== Optional fields for query, threat-match and EQL rules [width="100%",options="header"] |============================================== @@ -206,9 +247,37 @@ criteria are met. The object has these fields: * `list_id` (string, required): List ID of the exception container. * `namespace_type` (string required): Determines whether the exceptions are valid in only the rule's {kib} space (`single`) or in all {kib} spaces -(`agnostic`). +(`agnostic`). * `type` (string, required): The exception type, which must be either a detection rule exception (`detection`) or an endpoint exception (`endpoint`). +|============================================== + +===== Optional fields for threat-match rules + +[width="100%",options="header"] +|============================================== +|Name |Type |Description + +|threat_filter |Object[] +|{ref}/query-filter-context.html[Query and filter context] array used to filter +documents from the {es} index containing the threat values. +|============================================== + +===== Optional fields for query, threat-match and threshold rules + +[width="100%",options="header"] +|============================================== +|Name |Type |Description + +|language |String |Determines the query language, which must be +`kuery` or `lucene`. Defaults to `kuery`. +|============================================== + +===== Optional fields for EQL, query and threshold rules + +[width="100%",options="header"] +|============================================== +|Name |Type |Description |filters |Object[] |The {ref}/query-filter-context.html[query and filter context] array used to define the conditions for when alerts are created from @@ -219,9 +288,6 @@ Security Solution indices defined on the {kib} Advanced Settings page (*Kibana* → *Stack Management* → *Advanced Settings* → `securitySolution:defaultIndex`). -|language |String |Determines the query language, which must be -`kuery` or `lucene`. Defaults to `kuery`. - |risk_score_mapping |Object[] a|Overrides generated alerts' `risk_score` with a value from the source event: From 838f44deeef185543419a9bf8b9758c33d46e88c Mon Sep 17 00:00:00 2001 From: Ben Skelker Date: Tue, 6 Oct 2020 12:25:24 +0300 Subject: [PATCH 6/8] proofing --- docs/detections/api/rules/rules-api-create.asciidoc | 9 ++++----- docs/detections/api/rules/rules-api-update.asciidoc | 4 ++-- 2 files changed, 6 insertions(+), 7 deletions(-) diff --git a/docs/detections/api/rules/rules-api-create.asciidoc b/docs/detections/api/rules/rules-api-create.asciidoc index 0940d547d1..e2aaeb65e8 100644 --- a/docs/detections/api/rules/rules-api-create.asciidoc +++ b/docs/detections/api/rules/rules-api-create.asciidoc @@ -130,8 +130,8 @@ occurred * `query`: query with or without additional filters. * `saved_query`: saved search, identified in the `saved_id` field. * `machine_learning`: rule based on a {ml} job's anomaly scores. -* `threat_match`: rule that matches event values with values the specified {es} -index. +* `threat_match`: rule that matches event values with values in the specified +{es} index. * `threshold`: rule based on the number of times a `query` matches the specified field. @@ -761,9 +761,8 @@ this example, all values from the `ip-threat-list` index are used. logic. In this example, both the event's `destination.ip` and `destination.port` values must match the corresponding field values in the `ip-threat-list`. -<4> Sibling `entries` are evaluated using `or` logic. In this example, -an alert is generated when at least one `entries` object evaluates to -`true`. +<4> Sibling `entries` are evaluated using `or` logic. An alert is generated when +at least one `entries` object evaluates to `true`. ==== Response code diff --git a/docs/detections/api/rules/rules-api-update.asciidoc b/docs/detections/api/rules/rules-api-update.asciidoc index bb93b3315f..f87d4cdd48 100644 --- a/docs/detections/api/rules/rules-api-update.asciidoc +++ b/docs/detections/api/rules/rules-api-update.asciidoc @@ -61,8 +61,8 @@ occurred * `query`: query with or without additional filters. * `saved_query`: saved search, identified in the `saved_id` field. * `machine_learning`: rule based on a {ml} job's anomaly scores. -* `threat_match`: rule that matches event values with values the specified {es} -index. +* `threat_match`: rule that matches event values with values in the specified +{es} index. * `threshold`: rule based on the number of times a `query` matches the specified field. From d6745e90a45e81a29b8f92fb5097098080fc1dd8 Mon Sep 17 00:00:00 2001 From: Ben Skelker <54019610+benskelker@users.noreply.github.com> Date: Wed, 7 Oct 2020 10:17:19 +0300 Subject: [PATCH 7/8] Update docs/detections/api/rules/rules-api-create.asciidoc missing dot --- docs/detections/api/rules/rules-api-create.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/detections/api/rules/rules-api-create.asciidoc b/docs/detections/api/rules/rules-api-create.asciidoc index e2aaeb65e8..65323f970f 100644 --- a/docs/detections/api/rules/rules-api-create.asciidoc +++ b/docs/detections/api/rules/rules-api-create.asciidoc @@ -693,7 +693,7 @@ POST api/detection_engine/rules ], "type": "eql", "language": "eql", - "query": "sequence by process.entity_id with maxspan=2h [process where event.type in (\"start\", \"process_started\") and (process.name == \"rundll32.exe\" or process.pe.original_file_name == \"rundll32.exe\") and ((process.args == \"rundll32.exe\" and process.args_count == 1) or (process.args != \"rundll32.exe\" and process.args_count == 0))] [network where event.type == \"connection\" and (process.name == \"rundll32.exe\" or process.pe.original_file_name == \"rundll32exe\")]" + "query": "sequence by process.entity_id with maxspan=2h [process where event.type in (\"start\", \"process_started\") and (process.name == \"rundll32.exe\" or process.pe.original_file_name == \"rundll32.exe\") and ((process.args == \"rundll32.exe\" and process.args_count == 1) or (process.args != \"rundll32.exe\" and process.args_count == 0))] [network where event.type == \"connection\" and (process.name == \"rundll32.exe\" or process.pe.original_file_name == \"rundll32.exe\")]" } -------------------------------------------------- // KIBANA From 2f1cd9b563d9415f88c1b29ddeca4d8b8adf9e3f Mon Sep 17 00:00:00 2001 From: Ben Skelker <54019610+benskelker@users.noreply.github.com> Date: Wed, 7 Oct 2020 10:18:14 +0300 Subject: [PATCH 8/8] Update docs/detections/api/rules/rules-api-create.asciidoc missing dot --- docs/detections/api/rules/rules-api-create.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/detections/api/rules/rules-api-create.asciidoc b/docs/detections/api/rules/rules-api-create.asciidoc index 65323f970f..e55adf129b 100644 --- a/docs/detections/api/rules/rules-api-create.asciidoc +++ b/docs/detections/api/rules/rules-api-create.asciidoc @@ -992,7 +992,7 @@ Example response for an EQL rule: "exceptions_list": [], "actions": [], "throttle": "no_actions", - "query": "sequence by process.entity_id with maxspan=2h [process where event.type in (\"start\", \"process_started\") and (process.name == \"rundll32.exe\" or process.pe.original_file_name == \"rundll32.exe\") and ((process.args == \"rundll32.exe\" and process.args_count == 1) or (process.args != \"rundll32.exe\" and process.args_count == 0))] [network where event.type == \"connection\" and (process.name == \"rundll32.exe\" or process.pe.original_file_name == \"rundll32exe\")]", + "query": "sequence by process.entity_id with maxspan=2h [process where event.type in (\"start\", \"process_started\") and (process.name == \"rundll32.exe\" or process.pe.original_file_name == \"rundll32.exe\") and ((process.args == \"rundll32.exe\" and process.args_count == 1) or (process.args != \"rundll32.exe\" and process.args_count == 0))] [network where event.type == \"connection\" and (process.name == \"rundll32.exe\" or process.pe.original_file_name == \"rundll32.exe\")]", "language": "eql" } --------------------------------------------------