From 802aa4eb4d082a94cff018381c46120110b6fbae Mon Sep 17 00:00:00 2001 From: Ben Skelker Date: Tue, 21 Jul 2020 12:48:33 +0300 Subject: [PATCH 01/14] adds new rule fields --- .../detections/api/rules-api-create.asciidoc | 110 +++++++++++++----- 1 file changed, 82 insertions(+), 28 deletions(-) diff --git a/docs/siem/detections/api/rules-api-create.asciidoc b/docs/siem/detections/api/rules-api-create.asciidoc index 0273ee051f..c44b424a8d 100644 --- a/docs/siem/detections/api/rules-api-create.asciidoc +++ b/docs/siem/detections/api/rules-api-create.asciidoc @@ -1,12 +1,15 @@ [[rules-api-create]] === Create rule -Creates a new signal detection rule. +Creates a new detection rule. -You can create two types of rules: +You can create these types of rules: -* Query-based rules, which search the defined indices and creates a signal when +* Query rules: Searches the defined indices and creates an alert when a document matches the rule's query. +* Threshold rules: Searches the defined indices and creates an alert when the +number of times the specified event field is matched during a single execution +meets the specified threshold. * {ml-cap} rules, which create a signal when a {ml} job discovers an anomaly above the defined threshold (see <>). IMPORTANT: To create {ml} rules, you must have the @@ -73,11 +76,27 @@ actions (notifications) taken when signals are produced. |No creates signals. Valid values are from `0` to `100`. |Yes, for {ml} rules. Not allowed in `query` rule types. +|building_block_type |String |Determines if the rule acts as a building block. +|No + +|`author` |String[] |The rule's author. |No + |description |String |The rule's description. |Yes |enabled |Boolean |Determines whether the rule is enabled. |No, defaults to `true`. +|exceptions_list |Object[] a|Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met. The object has these fields: + +* `id` (string, required): 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`). +* `type` (string, required): The exception type, which must be either +a detection rule exception (`detection`) or an endpoint (`endpoint`). + +|No + |false_positives |String[] |String array used to describe common reasons why the rule may issue false-positive signals. |No, defaults to an empty array. @@ -95,10 +114,6 @@ using a {ref}/common-options.html#date-math[date math range]. For example, time. |No, defaults to `now-6m` (analyzes data from 6 minutes before the start time). -|rule_id |String |Unique ID used to identify rules. For example, when a rule -is converted from a third-party security solution. |No, automatically created -when it is not provided. - |index |String[] |Indices on which the rule functions. |No. For query rules, defaults to the {siem-soln} indices defined on the {kib} Advanced Settings page (*Kibana* → *Management* → *Advanced Settings* → `siem:defaultIndex`). @@ -107,25 +122,34 @@ defaults to the {siem-soln} indices defined on the {kib} Advanced Settings page {ref}/common-options.html#date-math[date math range]. For example, `"1h"` means the rule runs every hour. |No, defaults to `5m` (5 minutes). +|language |String |Determines the query language, which must be +`kuery` or `lucene`. |No. For `query` rule types, defaults to `kuery`. Not +allowed in `machine-learning` rule types. + +|`license` |String |The rule's license. |No + |machine_learning_job_id |String |{ml-cap} job ID the rule monitors for anomaly scores. |Yes, for {ml} rules. Not allowed in `query` rules types. -|query |String |{kibana-ref}/search.html[Query] used by the rule to create a -signal. |No. For `query` rules types, defaults to an empty string. Not allowed -in `machine-learning` rule types. +|max_signals |Integer |Maximum number of signals the rule can create during a +single execution. |No, defaults to `100`. -|language |String |Determines the query language, which must be -`kuery` or `lucene`. |No. For `query` rule types, defaults to `kuery`. Not -allowed in `machine-learning` rule types. +|meta |Object |Placeholder for metadata about the rule. |No + +|name |String |The rule's name. |Yes + +|note |String |Notes to help investigate alerts produced by the rule. |No |output_index |String |Index to which signals detected by the rule are saved. |No, if unspecified signals are saved to `.siem-signals-` index, where `` is the name of the {kib} space in which the rule exists. -|saved_id |String |Kibana saved search used by the rule to create signals. -|Yes, for `saved_query` rules only. +|query |String |{kibana-ref}/search.html[Query] used by the rule to create a +signal. |No. For `query` rules types, defaults to an empty string. Not allowed +in `machine-learning` rule types. -|meta |Object |Placeholder for metadata about the rule. |No +|references |String[] |String array containing notes about or references to +relevant information about the rule. |No, defaults to an empty array. |risk_score |Integer a|A numerical representation of the signal's severity from 0 to 100, where: @@ -137,12 +161,22 @@ where `` is the name of the {kib} space in which the rule exists. |Yes -|max_signals |Integer |Maximum number of signals the rule can create during a -single execution. |No, defaults to `100`. +|risk_score_mapping |Object[] a|Overrides generated alerts' `risk_score` with +a value from the source event: -|name |String |The rule's name. |Yes +* `field` (string, required): Source event field used to override the default +`risk_score`. This field must be an integer. +* `operator` (string, required): Must be `equals`. +* `value`(string, required): Must be an empty string (`""`). + +|No + +|rule_id |String |Unique ID used to identify rules. For example, when a rule +is converted from a third-party security solution. |No, automatically created +when it is not provided. -|note |String |Notes to help investigate signals produced by the rule. |No +|saved_id |String |Kibana saved search used by the rule to create signals. +|Yes, for `saved_query` rules only. |severity |String a|Severity level of signals produced by the rule, which must be one of the following: @@ -156,9 +190,33 @@ occurred |Yes +|severity_mapping |Object[] a|Overrides generated alerts' `severity` with +values from the source event: + +* `field` (string, required): Source event field used to override the default +`severity`. +* `operator` (string, required): Must be `equals`. +* `severity` (string, required): Mapped severity value, must be `low`, +`medium`, `high`, or `critical`. +* `value`(string, required): Field value used to determine the `severity`. + +|No + |tags |String[] |String array containing words and phrases to help categorize, filter, and search rules. |No, defaults to an empty array. +|threat |<> |Object containing attack +information about the type of threat the rule monitors, see +{ecs-ref}/ecs-threat.html[ECS threat fields]. |No, defaults to an empty array. + +|threshold |Object a|Defines the field and threshold value for when alerts +are generated, where: + +* `field` (string, required): The field on which the threshold is applied. +* `value` (integer, required): The value from alerts are generated. + +|Yes, for threshold rules only. + |throttle |String a|Determines how often actions are taken: * `no_actions`: Never @@ -169,6 +227,9 @@ filter, and search rules. |No, defaults to an empty array. |Yes, when actions are used to send notifications. +|timestamp_override |String |Specifies a source event field to use as the +timestamp in generated alerts. The source field must an {es} date data type. + // |to |String |Time to which data is analyzed each time the rule executes, using a // {ref}/common-options.html#date-math[date math range]. For example, `"now-300s"` // means the rule analyzes data until 5 minutes before its starts time. |Yes @@ -178,17 +239,10 @@ filter, and search rules. |No, defaults to an empty array. * `query`: query-based conditions 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. +* `threshold`: rule based on the number of times the `query` is matched. |Yes - -|threat |<> |Object containing attack -information about the type of threat the rule monitors, see -{ecs-ref}/ecs-threat.html[ECS threat fields]. |No, defaults to an empty array. - -|references |String[] |String array containing notes about or references to -relevant information about the rule. |No, defaults to an empty array. - |version |Integer |The rule's version number. a|No, defaults to `1`. |============================================== From f56ad126caca5f60e4066f05382f5c9a29bc6260 Mon Sep 17 00:00:00 2001 From: Ben Skelker Date: Tue, 21 Jul 2020 13:51:39 +0300 Subject: [PATCH 02/14] makes things more readable?? --- .../detections/api/rules-api-create.asciidoc | 264 ++++++++++-------- 1 file changed, 145 insertions(+), 119 deletions(-) diff --git a/docs/siem/detections/api/rules-api-create.asciidoc b/docs/siem/detections/api/rules-api-create.asciidoc index c44b424a8d..f35ad40ae7 100644 --- a/docs/siem/detections/api/rules-api-create.asciidoc +++ b/docs/siem/detections/api/rules-api-create.asciidoc @@ -63,159 +63,150 @@ calls, see: ==== Request body -A JSON object with these fields: +A JSON object that defines the rule's field values. + +===== Required fields for all rule types [width="100%",options="header"] |============================================== -|Name |Type |Description |Required +|Name |Type |Description -|actions |<> |Array defining the automated -actions (notifications) taken when signals are produced. |No +|description |String |The rule's description. -|anomaly_threshold |Integer |Anomaly score threshold above which the rule -creates signals. Valid values are from `0` to `100`. |Yes, for {ml} rules. Not -allowed in `query` rule types. +|name |String |The rule's name. -|building_block_type |String |Determines if the rule acts as a building block. -|No +|risk_score |Integer a|A numerical representation of the signal's severity from +0 to 100, where: -|`author` |String[] |The rule's author. |No +* `0` - `21` represents low severity +* `22` - `47` represents medium severity +* `48` - `73` represents high severity +* `74` - `100` represents critical severity -|description |String |The rule's description. |Yes +|severity |String a|Severity level of signals produced by the rule, which must +be one of the following: -|enabled |Boolean |Determines whether the rule is enabled. |No, defaults to -`true`. +* `low`: Signals that are of interest but generally not considered to be +security incidents +* `medium`: Signals that require investigation +* `high`: Signals that require immediate investigation +* `critical`: Signals that indicate it is highly likely a security incident has +occurred -|exceptions_list |Object[] a|Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met. The object has these fields: +|type |String a|Data type on which the rule is based: -* `id` (string, required): 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`). -* `type` (string, required): The exception type, which must be either -a detection rule exception (`detection`) or an endpoint (`endpoint`). +* `query`: query-based conditions 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. +* `threshold`: rule based on the number of times the `query` is matched. -|No +|============================================== -|false_positives |String[] |String array used to describe common reasons why -the rule may issue false-positive signals. |No, defaults to an empty array. +===== Required field for query and threshold rules -// |filter |Object |{kibana-ref}/field-filter.html[Filter] used by the rule to -// create a signal |Yes, for filter-based rules only +[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 signals are created from -events. |No, defaults to an empty array. +|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 +with an empty query no alerts will be generated. -[[detection-rules-from]] -|from |String |Time from which data is analyzed each time the rule executes, -using a {ref}/common-options.html#date-math[date math range]. For example, -`now-4200s` means the rule analyzes data from 70 minutes before its start -time. |No, defaults to `now-6m` (analyzes data from 6 minutes before the start -time). +|============================================== -|index |String[] |Indices on which the rule functions. |No. For query rules, -defaults to the {siem-soln} indices defined on the {kib} Advanced Settings page -(*Kibana* → *Management* → *Advanced Settings* → `siem:defaultIndex`). +===== Required field for threshold rules -|interval |String |Frequency of rule execution, using a -{ref}/common-options.html#date-math[date math range]. For example, `"1h"` -means the rule runs every hour. |No, defaults to `5m` (5 minutes). +[width="100%",options="header"] +|============================================== +|Name |Type |Description -|language |String |Determines the query language, which must be -`kuery` or `lucene`. |No. For `query` rule types, defaults to `kuery`. Not -allowed in `machine-learning` rule types. +|threshold |Object a|Defines the field and threshold value for when alerts +are generated, where: -|`license` |String |The rule's license. |No +* `field` (string, required): The field on which the threshold is applied. +* `value` (integer, required): The value from alerts are generated. -|machine_learning_job_id |String |{ml-cap} job ID the rule monitors for -anomaly scores. |Yes, for {ml} rules. Not allowed in `query` rules types. +|============================================== -|max_signals |Integer |Maximum number of signals the rule can create during a -single execution. |No, defaults to `100`. +===== Required field for saved query rules -|meta |Object |Placeholder for metadata about the rule. |No +[width="100%",options="header"] +|============================================== +|Name |Type |Description -|name |String |The rule's name. |Yes +|saved_id |String |Kibana saved search used by the rule to create signals. -|note |String |Notes to help investigate alerts produced by the rule. |No +|============================================== -|output_index |String |Index to which signals detected by the rule are saved. -|No, if unspecified signals are saved to `.siem-signals-` index, -where `` is the name of the {kib} space in which the rule exists. +===== Required fields for machine learning rules -|query |String |{kibana-ref}/search.html[Query] used by the rule to create a -signal. |No. For `query` rules types, defaults to an empty string. Not allowed -in `machine-learning` rule types. +[width="100%",options="header"] +|============================================== +|Name |Type |Description -|references |String[] |String array containing notes about or references to -relevant information about the rule. |No, defaults to an empty array. +|anomaly_threshold |Integer |Anomaly score threshold above which the rule +creates signals. Valid values are from `0` to `100`. -|risk_score |Integer a|A numerical representation of the signal's severity from -0 to 100, where: +|machine_learning_job_id |String |{ml-cap} job ID the rule monitors for +anomaly scores. -* `0` - `21` represents low severity -* `22` - `47` represents medium severity -* `48` - `73` represents high severity -* `74` - `100` represents critical severity +|============================================== -|Yes +===== Optional fields for all rule types -|risk_score_mapping |Object[] a|Overrides generated alerts' `risk_score` with -a value from the source event: +[width="100%",options="header"] +|============================================== +|Name |Type |Description -* `field` (string, required): Source event field used to override the default -`risk_score`. This field must be an integer. -* `operator` (string, required): Must be `equals`. -* `value`(string, required): Must be an empty string (`""`). +|actions |<> |Array defining the automated +actions (notifications) taken when signals are produced. -|No +|author |String[] |The rule's author. -|rule_id |String |Unique ID used to identify rules. For example, when a rule -is converted from a third-party security solution. |No, automatically created -when it is not provided. +|building_block_type |String |Determines if the rule acts as a building block. -|saved_id |String |Kibana saved search used by the rule to create signals. -|Yes, for `saved_query` rules only. +|enabled |Boolean |Determines whether the rule is enabled. Defaults to `true`. -|severity |String a|Severity level of signals produced by the rule, which must -be one of the following: +|false_positives |String[] |String array used to describe common reasons why +the rule may issue false-positive signals. Defaults to an empty array. -* `low`: Signals that are of interest but generally not considered to be -security incidents -* `medium`: Signals that require investigation -* `high`: Signals that require immediate investigation -* `critical`: Signals that indicate it is highly likely a security incident has -occurred +[[detection-rules-from]] +|from |String |Time from which data is analyzed each time the rule executes, +using a {ref}/common-options.html#date-math[date math range]. For example, +`now-4200s` means the rule analyzes data from 70 minutes before its start +time. Defaults to `now-6m` (analyzes data from 6 minutes before the start +time). -|Yes +|interval |String |Frequency of rule execution, using a +{ref}/common-options.html#date-math[date math range]. For example, `"1h"` +means the rule runs every hour. Defaults to `5m` (5 minutes). -|severity_mapping |Object[] a|Overrides generated alerts' `severity` with -values from the source event: +|license |String |The rule's license. -* `field` (string, required): Source event field used to override the default -`severity`. -* `operator` (string, required): Must be `equals`. -* `severity` (string, required): Mapped severity value, must be `low`, -`medium`, `high`, or `critical`. -* `value`(string, required): Field value used to determine the `severity`. +|max_signals |Integer |Maximum number of signals the rule can create during a +single execution. Defaults to `100`. -|No +|meta |Object |Placeholder for metadata about the rule. -|tags |String[] |String array containing words and phrases to help categorize, -filter, and search rules. |No, defaults to an empty array. +|note |String |Notes to help investigate alerts produced by the rule. -|threat |<> |Object containing attack -information about the type of threat the rule monitors, see -{ecs-ref}/ecs-threat.html[ECS threat fields]. |No, defaults to an empty array. +|output_index |String |Index to which alerts created by the rule are saved. +If unspecified signals are saved to `.siem-signals-` index, +where `` is the name of the {kib} space in which the rule exists. -|threshold |Object a|Defines the field and threshold value for when alerts -are generated, where: +|references |String[] |Array containing notes about or references to +relevant information about the rule. Defaults to an empty array. -* `field` (string, required): The field on which the threshold is applied. -* `value` (integer, required): The value from alerts are generated. +|rule_id |String |Unique ID used to identify rules. For example, when a rule +is converted from a third-party security solution. Automatically created when +it is not provided. + +|tags |String[] |String array containing words and phrases to help categorize, +filter, and search rules. Defaults to an empty array. -|Yes, for threshold rules only. +|threat |<> |Object containing attack +information about the type of threat the rule monitors, see +{ecs-ref}/ecs-threat.html[ECS threat fields]. Defaults to an empty array. |throttle |String a|Determines how often actions are taken: @@ -225,25 +216,60 @@ are generated, where: * `1d`: Every day * `7d`: Every week -|Yes, when actions are used to send notifications. +Required when `actions` are used to send notifications. -|timestamp_override |String |Specifies a source event field to use as the -timestamp in generated alerts. The source field must an {es} date data type. +|version |Integer |The rule's version number. Defaults to `1`. -// |to |String |Time to which data is analyzed each time the rule executes, using a -// {ref}/common-options.html#date-math[date math range]. For example, `"now-300s"` -// means the rule analyzes data until 5 minutes before its starts time. |Yes +|============================================== -|type |String a|Data type on which the rule is based: +===== Optional fields for query and threshold rules -* `query`: query-based conditions 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. -* `threshold`: rule based on the number of times the `query` is matched. +[width="100%",options="header"] +|============================================== +|Name |Type |Description -|Yes +|exceptions_list |Object[] a|Array of exception containers, which define +exceptions that prevent the rule from generating alerts even when its other +criteria are met. The object has these fields: -|version |Integer |The rule's version number. a|No, defaults to `1`. +* `id` (string, required): 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`). +* `type` (string, required): The exception type, which must be either +a detection rule exception (`detection`) or an endpoint (`endpoint`). + +|filters |Object[] |The {ref}/query-filter-context.html[query and filter +context] array used to define the conditions for when signals are created from +events. |Defaults to an empty array. + +|index |String[] |Indices on which the rule functions. Defaults to the +{siem-soln} indices defined on the {kib} Advanced Settings page +(*Kibana* → *Management* → *Advanced Settings* → `siem: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: + +* `field` (string, required): Source event field used to override the default +`risk_score`. This field must be an integer. +* `operator` (string, required): Must be `equals`. +* `value`(string, required): Must be an empty string (`""`). + +|severity_mapping |Object[] a|Overrides generated alerts' `severity` with +values from the source event: + +* `field` (string, required): Source event field used to override the default +`severity`. +* `operator` (string, required): Must be `equals`. +* `severity` (string, required): Mapped severity value, must be `low`, +`medium`, `high`, or `critical`. +* `value`(string, required): Field value used to determine the `severity`. + +|timestamp_override |String |Specifies a source event field to use as the +timestamp in generated alerts. The source field must an {es} date data type. |============================================== From cf915f5cddee92cd20c4907f00f6c8ddff94e487 Mon Sep 17 00:00:00 2001 From: Ben Skelker Date: Tue, 21 Jul 2020 14:44:32 +0300 Subject: [PATCH 03/14] updates terminology where possible --- .../detections/api/rules-api-create.asciidoc | 99 +++++++++---------- 1 file changed, 49 insertions(+), 50 deletions(-) diff --git a/docs/siem/detections/api/rules-api-create.asciidoc b/docs/siem/detections/api/rules-api-create.asciidoc index f35ad40ae7..145d184401 100644 --- a/docs/siem/detections/api/rules-api-create.asciidoc +++ b/docs/siem/detections/api/rules-api-create.asciidoc @@ -9,8 +9,8 @@ You can create these types of rules: a document matches the rule's query. * Threshold rules: Searches the defined indices and creates an alert when the number of times the specified event field is matched during a single execution -meets the specified threshold. -* {ml-cap} rules, which create a signal when a {ml} job discovers an anomaly above the defined threshold (see <>). +meets the threshold. +* {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 @@ -35,7 +35,7 @@ the `groups` field can be used to create rules: ... -------------------------------------------------- -Additionally, you can set up notifications for when rules create signals. The +Additionally, you can set up notifications for when rules create alerts. The notifications use the {kib} {kibana-ref}/alerting-getting-started.html[Alerting and Actions framework]. Each action type requires a connector. Connectors store the information required to send notifications via external systems. These action types are @@ -46,15 +46,17 @@ supported for rule notifications: * PagerDuty * Webhook -NOTE: For more information on PagerDuty fields, see https://v2.developer.pagerduty.com/v2/docs/send-an-event-events-api-v2[PagerDuty Send a v2 Event API]. +NOTE: For more information on PagerDuty fields, see +https://developer.pagerduty.com/docs/events-api-v2/trigger-events/[Send a v2 Event]. To retrieve connector IDs, which are required to configure rule notifications, -call `GET :/api/action/_find`. +call the {kib} {kibana-re}/saved-objects-api-find.html[Find objects API] with +`"type": "action"` in the request payload.. For detailed information on {kib} actions and alerting, and additional API calls, see: -* https://github.com/elastic/kibana/tree/master/x-pack/plugins/alerting +* https://github.com/elastic/kibana/tree/master/x-pack/plugins/alerts * https://github.com/elastic/kibana/tree/master/x-pack/plugins/actions ==== Request URL @@ -63,7 +65,7 @@ calls, see: ==== Request body -A JSON object that defines the rule's field values. +A JSON object that defines the rule's values. ===== Required fields for all rule types @@ -75,7 +77,7 @@ A JSON object that defines the rule's field values. |name |String |The rule's name. -|risk_score |Integer a|A numerical representation of the signal's severity from +|risk_score |Integer a|A numerical representation of the alert's severity from 0 to 100, where: * `0` - `21` represents low severity @@ -83,7 +85,7 @@ A JSON object that defines the rule's field values. * `48` - `73` represents high severity * `74` - `100` represents critical severity -|severity |String a|Severity level of signals produced by the rule, which must +|severity |String a|Severity level of alerts produced by the rule, which must be one of the following: * `low`: Signals that are of interest but generally not considered to be @@ -110,7 +112,7 @@ occurred |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 -with an empty query no alerts will be generated. +then no alerts will ever be generated. |============================================== @@ -134,7 +136,7 @@ are generated, where: |============================================== |Name |Type |Description -|saved_id |String |Kibana saved search used by the rule to create signals. +|saved_id |String |Kibana saved search used by the rule to create alerts. |============================================== @@ -145,7 +147,7 @@ are generated, where: |Name |Type |Description |anomaly_threshold |Integer |Anomaly score threshold above which the rule -creates signals. Valid values are from `0` to `100`. +creates alerts. Valid values are from `0` to `100`. |machine_learning_job_id |String |{ml-cap} job ID the rule monitors for anomaly scores. @@ -159,7 +161,7 @@ anomaly scores. |Name |Type |Description |actions |<> |Array defining the automated -actions (notifications) taken when signals are produced. +actions (notifications) taken when alerts are produced. |author |String[] |The rule's author. @@ -168,7 +170,7 @@ actions (notifications) taken when signals are produced. |enabled |Boolean |Determines whether the rule is enabled. Defaults to `true`. |false_positives |String[] |String array used to describe common reasons why -the rule may issue false-positive signals. Defaults to an empty array. +the rule may issue false-positive alerts. Defaults to an empty array. [[detection-rules-from]] |from |String |Time from which data is analyzed each time the rule executes, @@ -183,7 +185,7 @@ means the rule runs every hour. Defaults to `5m` (5 minutes). |license |String |The rule's license. -|max_signals |Integer |Maximum number of signals the rule can create during a +|max_signals |Integer |Maximum number of alerts the rule can create during a single execution. Defaults to `100`. |meta |Object |Placeholder for metadata about the rule. @@ -191,7 +193,7 @@ single execution. Defaults to `100`. |note |String |Notes to help investigate alerts produced by the rule. |output_index |String |Index to which alerts created by the rule are saved. -If unspecified signals are saved to `.siem-signals-` index, +If unspecified alerts are saved to `.siem-signals-` index, where `` is the name of the {kib} space in which the rule exists. |references |String[] |Array containing notes about or references to @@ -211,7 +213,7 @@ information about the type of threat the rule monitors, see |throttle |String a|Determines how often actions are taken: * `no_actions`: Never -* `rule`: Every time new signals are detected +* `rule`: Every time new alerts are detected * `1h`: Every hour * `1d`: Every day * `7d`: Every week @@ -237,15 +239,16 @@ criteria are met. The object has these fields: 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 (`endpoint`). +a detection rule exception (`detection`) or an endpoint exception (`endpoint`). |filters |Object[] |The {ref}/query-filter-context.html[query and filter -context] array used to define the conditions for when signals are created from -events. |Defaults to an empty array. +context] array used to define the conditions for when alerts are created from +events. Defaults to an empty array. |index |String[] |Indices on which the rule functions. Defaults to the -{siem-soln} indices defined on the {kib} Advanced Settings page -(*Kibana* → *Management* → *Advanced Settings* → `siem:defaultIndex`). +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`. @@ -276,9 +279,11 @@ timestamp in generated alerts. The source field must an {es} date data type. [[actions-object-schema]] ===== `actions` schema +All fields are required: + [width="100%",options="header"] |============================================== -|Name |Type |Description |Required +|Name |Type |Description |action_type_id |String a|The action type used for sending notifications, can be: @@ -288,12 +293,10 @@ be: * `.pagerduty` * `.webhook` -|Yes +|group |String |Optionally groups actions by use cases. Use `default` for alert +notifications. -|group |String |Optionally groups actions by use cases. Use `default` for signal -notifications.|Yes - -|id |String |The connector ID. |Yes +|id |String |The connector ID. |params |Object a|Object containing the allowed connector fields, which varies according to the connector type: @@ -307,15 +310,15 @@ sent. At least one field must have a value. * For Webhook: ** `body` (string, required): JSON payload. * For PagerDuty: -** `severity` (string, required): Severity of on the signal notification, can +** `severity` (string, required): Severity of on the alert notification, can be: `Critical`, `Error`, `Warning` or `Info`. ** `eventAction` (string, required): Event https://v2.developer.pagerduty.com/docs/events-api-v2#event-action[action type], which can be `trigger`, `resolve`, or `acknowledge`. -** `dedupKey` (string, optional): Groups signal notifications with the same +** `dedupKey` (string, optional): Groups alert notifications with the same PagerDuty alert. ** `timestamp` (DateTime, optional): https://v2.developer.pagerduty.com/v2/docs/types#datetime[ISO-8601 format timestamp]. ** `component` (string, optional): Source machine component responsible for the -event, for example `siem`. +event, for example `security-solution`. ** `group` (string, optional): Enables logical grouping of service components. ** `source` (string, optional): The affected system. Defaults to the {kib} saved object ID of the action. @@ -323,17 +326,15 @@ saved object ID of the action. `No summary provided`. Maximum length is 1024 characters. ** `class` (string, optional): Value indicating the class/type of the event. -|Yes - |============================================== All text fields (such as `message` fields) can contain placeholders for rule -and signal details: +and alert details: -* `{{state.signals_count}}`: Number of signals detected -* `{{{context.results_link}}}`: URL to the signals in {kib} +* `{{state.signals_count}}`: Number of alerts detected +* `{{{context.results_link}}}`: URL to the alerts in {kib} * `{{context.rule.anomaly_threshold}}`: Anomaly threshold score above which -signals are generated ({ml} rules only) +alerts are generated ({ml} rules only) * `{{context.rule.description}}`: Rule description * `{{context.rule.false_positives}}`: Rule false positives * `{{context.rule.filters}}`: Rule filters (query-based rules only) @@ -342,10 +343,10 @@ signals are generated ({ml} rules only) * `{{context.rule.language}}`: Rule query language (query-based rules only) * `{{context.rule.machine_learning_job_id}}`: ID of associated {ml} job ({ml} rules only) -* `{{context.rule.max_signals}}`: Maximum allowed number of signals per rule +* `{{context.rule.max_signals}}`: Maximum allowed number of alerts per rule execution * `{{context.rule.name}}`: Rule name -* `{{context.rule.output_index}}`: Index to which signals are written +* `{{context.rule.output_index}}`: Index to which alerts are written * `{{context.rule.query}}`: Rule query (query-based rules only) * `{{context.rule.references}}`: Rule references * `{{context.rule.risk_score}}`: Rule risk score @@ -363,14 +364,16 @@ used as an identifier across systems ===== `threat` schema NOTE: Only threats described using the MITRE ATT&CK^TM^ framework are displayed -in the UI (*SIEM* -> *Detections* -> *Manage signal detection rules* -> -). +in the UI (*Security* -> *Detections* -> *Manage detection rules* -> ). + +All fields are required: [width="100%",options="header"] |============================================== -|Name |Type |Description |Required +|Name |Type |Description -|framework |String |Relevant attack framework. |Yes +|framework |String |Relevant attack framework. |tactic |Object a|Object containing information on the attack type: @@ -378,8 +381,6 @@ in the UI (*SIEM* -> *Detections* -> *Manage signal detection rules* -> * `name` - string, required * `reference` - string, required -|Yes - |technique |Object a|Object containing information on the attack technique: @@ -387,8 +388,6 @@ technique: * `name` - string, required * `reference` - string, required -|Yes - |============================================== ===== Example requests @@ -440,7 +439,7 @@ When it runs next, at 16:00, it will analyze data from 14:50 until 16:00. *Example 2* -{ml-cap} rule that creates signals, and sends Slack notifications, when the +{ml-cap} rule that creates alerts, and sends Slack notifications, when the `linux_anomalous_network_activity_ecs` {ml} job discovers anomalies with a threshold of 70 or above: @@ -452,7 +451,7 @@ POST api/detection_engine/rules "rule_id": "ml_linux_network_high_threshold", "risk_score": 70, "machine_learning_job_id": "linux_anomalous_network_activity_ecs", - "description": "Generates signals when the job discovers anomalies over 70", + "description": "Generates alerts when the job discovers anomalies over 70", "interval": "5m", "name": "Anomalous Linux network activity", "note": "Shut down the internet.", @@ -548,7 +547,7 @@ Example response for a {ml} job rule: "created_at": "2020-04-07T14:45:15.679Z", "updated_at": "2020-04-07T14:45:15.892Z", "created_by": "LiverpoolFC", - "description": "Generates signals when the job discovers anomalies over 70", + "description": "Generates alerts when the job discovers anomalies over 70", "enabled": true, "false_positives": [], "from": "now-6m", From c8801fbdbd535b2377893208e0d15385249a2184 Mon Sep 17 00:00:00 2001 From: Ben Skelker Date: Tue, 21 Jul 2020 14:48:06 +0300 Subject: [PATCH 04/14] typos and stuff --- docs/siem/detections/api/rules-api-create.asciidoc | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/siem/detections/api/rules-api-create.asciidoc b/docs/siem/detections/api/rules-api-create.asciidoc index 145d184401..8bcfa4a820 100644 --- a/docs/siem/detections/api/rules-api-create.asciidoc +++ b/docs/siem/detections/api/rules-api-create.asciidoc @@ -50,8 +50,8 @@ NOTE: For more information on PagerDuty fields, see https://developer.pagerduty.com/docs/events-api-v2/trigger-events/[Send a v2 Event]. To retrieve connector IDs, which are required to configure rule notifications, -call the {kib} {kibana-re}/saved-objects-api-find.html[Find objects API] with -`"type": "action"` in the request payload.. +call the {kib} {kibana-ref}/saved-objects-api-find.html[Find objects API] with +`"type": "action"` in the request payload. For detailed information on {kib} actions and alerting, and additional API calls, see: @@ -363,10 +363,6 @@ used as an identifier across systems [[threats-object-create]] ===== `threat` schema -NOTE: Only threats described using the MITRE ATT&CK^TM^ framework are displayed -in the UI (*Security* -> *Detections* -> *Manage detection rules* -> ). - All fields are required: [width="100%",options="header"] @@ -390,6 +386,10 @@ technique: |============================================== +NOTE: Only threats described using the MITRE ATT&CK^TM^ framework are displayed +in the UI (*Security* -> *Detections* -> *Manage detection rules* -> ). + ===== Example requests *Example 1* From e8312ecce9dc8f1a5ce0ebd8d424d35aa9f13df3 Mon Sep 17 00:00:00 2001 From: Ben Skelker Date: Tue, 21 Jul 2020 14:58:11 +0300 Subject: [PATCH 05/14] more terminology changes --- docs/siem/detections/api/rules-api-create.asciidoc | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/siem/detections/api/rules-api-create.asciidoc b/docs/siem/detections/api/rules-api-create.asciidoc index 8bcfa4a820..5222d8235b 100644 --- a/docs/siem/detections/api/rules-api-create.asciidoc +++ b/docs/siem/detections/api/rules-api-create.asciidoc @@ -88,11 +88,11 @@ A JSON object that defines the rule's values. |severity |String a|Severity level of alerts produced by the rule, which must be one of the following: -* `low`: Signals that are of interest but generally not considered to be +* `low`: Alerts that are of interest but generally not considered to be security incidents -* `medium`: Signals that require investigation -* `high`: Signals that require immediate investigation -* `critical`: Signals that indicate it is highly likely a security incident has +* `medium`: Alerts that require investigation +* `high`: Alerts that require immediate investigation +* `critical`: Alerts that indicate it is highly likely a security incident has occurred |type |String a|Data type on which the rule is based: From d79dc21adc9069aa8ee9ba88ed1a7b14636a4588 Mon Sep 17 00:00:00 2001 From: Ben Skelker Date: Wed, 22 Jul 2020 14:05:45 +0300 Subject: [PATCH 06/14] corrections and new eample --- .../detections/api/rules-api-create.asciidoc | 198 ++++++++++++++++-- 1 file changed, 180 insertions(+), 18 deletions(-) diff --git a/docs/siem/detections/api/rules-api-create.asciidoc b/docs/siem/detections/api/rules-api-create.asciidoc index 5222d8235b..c637332378 100644 --- a/docs/siem/detections/api/rules-api-create.asciidoc +++ b/docs/siem/detections/api/rules-api-create.asciidoc @@ -97,10 +97,11 @@ occurred |type |String a|Data type on which the rule is based: -* `query`: query-based conditions with or without additional filters. +* `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. -* `threshold`: rule based on the number of times the `query` is matched. +* `threshold`: rule based on the number of times a `query` matches the +specified field. |============================================== @@ -112,7 +113,7 @@ occurred |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 -then no alerts will ever be generated. +that's not very useful. |============================================== @@ -125,12 +126,15 @@ then no alerts will ever be generated. |threshold |Object a|Defines the field and threshold value for when alerts are generated, where: -* `field` (string, required): The field on which the threshold is applied. -* `value` (integer, required): The value from alerts are generated. +* `field` (string, required): The field on which the threshold is applied. If +you specify an empty field (`""`), alerts are generated when the query returns +at least the number of results specified in the `value` field. +* `value` (integer, required): The threshold value from which an alert is +generated. |============================================== -===== Required field for saved query rules +===== Required field for saved-query rules [width="100%",options="header"] |============================================== @@ -140,14 +144,14 @@ are generated, where: |============================================== -===== Required fields for machine learning rules +===== Required fields for machine-learning rules [width="100%",options="header"] |============================================== |Name |Type |Description |anomaly_threshold |Integer |Anomaly score threshold above which the rule -creates alerts. Valid values are from `0` to `100`. +creates an alert. Valid values are from `0` to `100`. |machine_learning_job_id |String |{ml-cap} job ID the rule monitors for anomaly scores. @@ -161,11 +165,14 @@ anomaly scores. |Name |Type |Description |actions |<> |Array defining the automated -actions (notifications) taken when alerts are produced. +actions (notifications) taken when alerts are generated. |author |String[] |The rule's author. |building_block_type |String |Determines if the rule acts as a building block. +By default, building-block alerts are not displayed in the UI. These rules are +used as a foundation for other rules that do generate alerts. Its value must be +`default`. For more information, see BEN - add link later. |enabled |Boolean |Determines whether the rule is enabled. Defaults to `true`. @@ -234,13 +241,15 @@ Required when `actions` are used to send notifications. exceptions that prevent the rule from generating alerts even when its other criteria are met. The object has these fields: -* `id` (string, required): ID of the exception container. +* `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`). * `type` (string, required): The exception type, which must be either a detection rule exception (`detection`) or an endpoint exception (`endpoint`). +BEN - add link later + |filters |Object[] |The {ref}/query-filter-context.html[query and filter context] array used to define the conditions for when alerts are created from events. Defaults to an empty array. @@ -271,8 +280,9 @@ values from the source event: `medium`, `high`, or `critical`. * `value`(string, required): Field value used to determine the `severity`. -|timestamp_override |String |Specifies a source event field to use as the -timestamp in generated alerts. The source field must an {es} date data type. +|timestamp_override |String |Determines the time field used to query indices. +When unspecified, rules query the `@timestamp` field. The source field +must an {es} date data type. |============================================== @@ -337,17 +347,17 @@ and alert details: alerts are generated ({ml} rules only) * `{{context.rule.description}}`: Rule description * `{{context.rule.false_positives}}`: Rule false positives -* `{{context.rule.filters}}`: Rule filters (query-based rules only) +* `{{context.rule.filters}}`: Rule filters (query rules only) * `{{context.rule.id}}`: Unique rule ID returned after creating the rule -* `{{context.rule.index}}`: Indices rule runs on (query-based rules only) -* `{{context.rule.language}}`: Rule query language (query-based rules only) +* `{{context.rule.index}}`: Indices rule runs on (query rules only) +* `{{context.rule.language}}`: Rule query language (query rules only) * `{{context.rule.machine_learning_job_id}}`: ID of associated {ml} job ({ml} rules only) * `{{context.rule.max_signals}}`: Maximum allowed number of alerts per rule execution * `{{context.rule.name}}`: Rule name * `{{context.rule.output_index}}`: Index to which alerts are written -* `{{context.rule.query}}`: Rule query (query-based rules only) +* `{{context.rule.query}}`: Rule query (query rules only) * `{{context.rule.references}}`: Rule references * `{{context.rule.risk_score}}`: Rule risk score * `{{context.rule.rule_id}}`: Generated or user-defined rule ID that can be @@ -355,6 +365,7 @@ used as an identifier across systems * `{{context.rule.saved_id}}`: Saved search ID * `{{context.rule.severity}}`: Rule severity * `{{context.rule.threat}}`: Rule threat framework +* `{{context.rule.threshold}}`: Rule threshold (threshold rules only) * `{{context.rule.timeline_id}}`: Associated timeline ID * `{{context.rule.timeline_title}}`: Associated timeline name * `{{context.rule.type}}`: Rule type @@ -394,7 +405,7 @@ name>). *Example 1* -Query-based rule that searches for processes started by MS Office: +Query rule that searches for processes started by MS Office: [source,console] -------------------------------------------------- @@ -439,6 +450,78 @@ When it runs next, at 16:00, it will analyze data from 14:50 until 16:00. *Example 2* +Threshold rule that detects multiple failed login attempts to a Windows host +from the same external source IP address, and maps the `severity` value to +custom source event fields: + +[source,console] +-------------------------------------------------- +POST api/detection_engine/rules +{ + "description": "Detects when there are 20 or more failed login attempts from the same IP address with a 2 minute time frame.", + "enabled": true, + "exceptions_list": [ <1> + { + "id": "int-ips", + "namespace_type": "single", + "type": "detection" + } + ], + "from": "now-180s", + "index": [ + "winlogbeat-*" + ], + "interval": "2m", + "name": "Liverpool Windows server prml-19", + "query": "host.name:prml-19 and event.category:authentication and event.outcome:failure", + "risk_score": 30, + "rule_id": "liv-win-ser-logins", + "severity": "low", + "severity_mapping": [ <2> + { + "field": "source.geo.city_name", + "operator": "equals", + "severity": "low", + "value": "Liverpool" + }, + { + "field": "source.geo.city_name", + "operator": "equals", + "severity": "medium", + "value": "West Ham" + }, + { + "field": "source.geo.city_name", + "operator": "equals", + "severity": "high", + "value": "Everton" + }, + { + "field": "source.geo.city_name", + "operator": "equals", + "severity": "critical", + "value": "Manchester" + } + ], + "tags": [ + "Brute force" + ], + "threshold": { <3> + "field": "source.ip", + "value": 20 + }, + "type": "threshold" +} +-------------------------------------------------- +// KIBANA + +<1> Exception list container used to exclude internal IP addresses. +<2> Alert severity levels are mapped according to the defined field values. +<3> Alerts are generated when the same source IP address is discovered in at +least 20 results. + +*Example 3* + {ml-cap} rule that creates alerts, and sends Slack notifications, when the `linux_anomalous_network_activity_ecs` {ml} job discovers anomalies with a threshold of 70 or above: @@ -489,7 +572,7 @@ A JSON object that includes a unique ID, the time the rule was created, and its version number. If the request payload did not include a `rule_id` field, a unique rule ID is also generated. -Example response for a query-based rule: +Example response for a query rule: [source,json] -------------------------------------------------- @@ -588,3 +671,82 @@ Example response for a {ml} job rule: "machine_learning_job_id": "linux_anomalous_network_activity_ecs" } -------------------------------------------------- + +Example response for a threshold rule: + +[source,json] +-------------------------------------------------- +{ + "author": [], + "created_at": "2020-07-22T10:27:23.486Z", + "updated_at": "2020-07-22T10:27:23.673Z", + "created_by": "LiverpoolFC", + "description": "Detects when there are 20 or more failed login attempts from the same IP address with a 2 minute time frame.", + "enabled": true, + "false_positives": [], + "from": "now-180s", + "id": "15dbde26-b627-4d74-bb1f-a5e0ed9e4993", + "immutable": false, + "interval": "2m", + "rule_id": "liv-win-ser-logins", + "output_index": ".siem-signals-default", + "max_signals": 100, + "risk_score": 30, + "risk_score_mapping": [], + "name": "Liverpool Windows server prml-19", + "references": [], + "severity": "low", + "severity_mapping": [ + { + "field": "source.geo.city_name", + "operator": "equals", + "severity": "low", + "value": "Liverpool" + }, + { + "field": "source.geo.city_name", + "operator": "equals", + "severity": "medium", + "value": "West Ham" + }, + { + "field": "source.geo.city_name", + "operator": "equals", + "severity": "high", + "value": "Everton" + }, + { + "field": "source.geo.city_name", + "operator": "equals", + "severity": "critical", + "value": "Manchester" + } + ], + "updated_by": "LiverpoolFC", + "tags": [ + "Brute force" + ], + "to": "now", + "type": "threshold", + "threat": [], + "version": 1, + "exceptions_list": [ + { + "id": "int-ips", + "namespace_type": "single", + "type": "detection" + } + ], + "actions": [], + "index": [ + "winlogbeat-*" + ], + "throttle": "no_actions", + "query": "host.name:prml-19 and event.category:authentication and event.outcome:failure", + "language": "kuery", + "threshold": { + "field": "source.ip", + "value": 20 + } +} +-------------------------------------------------- From 9b79634285e8d2364044e2db9a6a7cb13ecbb288 Mon Sep 17 00:00:00 2001 From: Ben Skelker Date: Wed, 22 Jul 2020 15:08:30 +0300 Subject: [PATCH 07/14] updates-signals-endpoint --- .../api/signals-api-overview.asciidoc | 66 ++++++++++++++----- 1 file changed, 48 insertions(+), 18 deletions(-) diff --git a/docs/siem/detections/api/signals-api-overview.asciidoc b/docs/siem/detections/api/signals-api-overview.asciidoc index ee7414cda5..8f2f71b653 100644 --- a/docs/siem/detections/api/signals-api-overview.asciidoc +++ b/docs/siem/detections/api/signals-api-overview.asciidoc @@ -2,17 +2,17 @@ [role="xpack"] === Signals endpoint -The signals endpoint is for retrieving, aggregating, and updating signals. -For detailed information on how to retrieve and aggregate results from the -indices, see: +The signals endpoint is for retrieving, aggregating, and updating detection +alerts. For detailed information on how to retrieve and aggregate results from +the indices, see: * {ref}/getting-started-search.html[Start searching] * {ref}/search-aggregations.html[Aggregations] * {ref}/query-dsl.html[Query DSL] -==== Get signals +==== Get alerts -Aggregates and returns signals. +Aggregates and returns alerts. ===== Request URL @@ -24,9 +24,9 @@ A query DSL that determines which results are returned. ====== Example request -Gets aggregated results of all open signals with a risk score equal to or +Gets aggregated results of all open alerts with a risk score equal to or greater than 70. It also returns the timestamps of the oldest and -newest signals that meet the query's criteria. +newest alerts that meet the query's criteria. [source,console] -------------------------------------------------- @@ -61,8 +61,35 @@ POST api/detection_engine/signals/search } ] } - }, - "size": 0 + } +} +-------------------------------------------------- + +Gets all in-progress alerts with a risk score equal to or +greater than 70. + +[source,console] +-------------------------------------------------- +POST api/detection_engine/signals/search +{ + "query": { + "bool": { + "filter": [ + { + "match": { + "signal.status": "in-progress" + } + }, + { + "range": { + "signal.rule.risk_score": { + "gte": 70 + } + } + } + ] + } + } } -------------------------------------------------- // KIBANA @@ -74,7 +101,7 @@ POST api/detection_engine/signals/search ====== Response payload -A JSON object with the aggregated values and requested signals. +A JSON object with the aggregated values and requested alerts. Example response: @@ -110,9 +137,9 @@ Example response: } -------------------------------------------------- -==== Set signal status +==== Set alert status -Sets the status of one or more signals. +Sets the status of one or more alert. ===== Request URL @@ -126,17 +153,20 @@ A JSON object with either a `query` or `signals_id` field: |============================================== |Name |Type |Description |Required -|`signal_ids` |String[] |Array of rule IDs. |Yes, when the `query` field is not used. +|`signal_ids` |String[] |Array of alert IDs. |Yes, when the `query` field is +not used. -|`query` |Query DSL |Query that determines which signals are updated. |Yes, when the `signal_ids` field is not used. +|`query` |Query DSL |Query that determines which alerts are updated. |Yes, when +the `signal_ids` field is not used. -|`status` |String |The new status, which can be `open` or `closed`. |Yes. +|`status` |String |The new status, which can be `open`, `in-progress` or +`closed`. |Yes. |============================================== ====== Example requests -Closes signal with signal IDs: +Closes alerts with `signal_ids`: [source,console] -------------------------------------------------- @@ -151,7 +181,7 @@ POST api/detection_engine/signals/status -------------------------------------------------- // KIBANA -Closes signals that are over a month old and have a risk score less than or +Closes alerts that are over a month old and have a risk score less than or equal to 20: [source,json] @@ -190,7 +220,7 @@ POST api/detection_engine/signals/status ====== Response payload -A JSON object containing the number of updated signals. +A JSON object containing the number of updated alerts. Example response: From 095bc3d8af273c98403408df15ee3df704475911 Mon Sep 17 00:00:00 2001 From: Ben Skelker Date: Wed, 22 Jul 2020 15:39:54 +0300 Subject: [PATCH 08/14] missing comma --- docs/siem/detections/api/rules-api-create.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/siem/detections/api/rules-api-create.asciidoc b/docs/siem/detections/api/rules-api-create.asciidoc index c637332378..d09ad01a0a 100644 --- a/docs/siem/detections/api/rules-api-create.asciidoc +++ b/docs/siem/detections/api/rules-api-create.asciidoc @@ -112,7 +112,7 @@ specified field. |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 +alerts. Technically, this is not required and defaults to an empty string, but that's not very useful. |============================================== From 702e9455224cd4cd5e3ea28eb9af513725482e01 Mon Sep 17 00:00:00 2001 From: Ben Skelker Date: Thu, 23 Jul 2020 09:35:34 +0300 Subject: [PATCH 09/14] corrections after reiew --- .../detections/api/rules-api-create.asciidoc | 38 ++++++++++++------- 1 file changed, 25 insertions(+), 13 deletions(-) diff --git a/docs/siem/detections/api/rules-api-create.asciidoc b/docs/siem/detections/api/rules-api-create.asciidoc index d09ad01a0a..a5c2c2aa26 100644 --- a/docs/siem/detections/api/rules-api-create.asciidoc +++ b/docs/siem/detections/api/rules-api-create.asciidoc @@ -7,9 +7,16 @@ 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. -* Threshold rules: Searches the defined indices and creates an alert when the -number of times the specified event field is matched during a single execution -meets the threshold. +* Threshold rules: Searches the defined indices and create 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 +generated for each value. ++ +For example, if the threshold `field` is `source.ip` and its `value` is `10`, an +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 <>). IMPORTANT: To create {ml} rules, you must have the @@ -112,7 +119,7 @@ specified field. |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 +alerts. Technically, this is not required and defaults to an empty string but that's not very useful. |============================================== @@ -270,6 +277,11 @@ a value from the source event: * `operator` (string, required): Must be `equals`. * `value`(string, required): Must be an empty string (`""`). +|rule_name_override |String |Sets the value used to populate an alert's +`signal.rule.name` field (in the UI, this value is displayed in the *Rule* +column on the Detections page). When unspecified, the rule's `name` value is +used. + |severity_mapping |Object[] a|Overrides generated alerts' `severity` with values from the source event: @@ -280,7 +292,7 @@ values from the source event: `medium`, `high`, or `critical`. * `value`(string, required): Field value used to determine the `severity`. -|timestamp_override |String |Determines the time field used to query indices. +|timestamp_override |String |Sets the time field used to query indices. When unspecified, rules query the `@timestamp` field. The source field must an {es} date data type. @@ -482,25 +494,25 @@ POST api/detection_engine/rules "field": "source.geo.city_name", "operator": "equals", "severity": "low", - "value": "Liverpool" + "value": "Manchester" }, { "field": "source.geo.city_name", "operator": "equals", "severity": "medium", - "value": "West Ham" + "value": "London" }, { "field": "source.geo.city_name", "operator": "equals", "severity": "high", - "value": "Everton" + "value": "Birmingham" }, { "field": "source.geo.city_name", "operator": "equals", "severity": "critical", - "value": "Manchester" + "value": "Wallingford" } ], "tags": [ @@ -701,25 +713,25 @@ Example response for a threshold rule: "field": "source.geo.city_name", "operator": "equals", "severity": "low", - "value": "Liverpool" + "value": "Manchester" }, { "field": "source.geo.city_name", "operator": "equals", "severity": "medium", - "value": "West Ham" + "value": "London" }, { "field": "source.geo.city_name", "operator": "equals", "severity": "high", - "value": "Everton" + "value": "Birmingham" }, { "field": "source.geo.city_name", "operator": "equals", "severity": "critical", - "value": "Manchester" + "value": "Wallingford" } ], "updated_by": "LiverpoolFC", From af741b7d28cd333ea4774aee3c43436e5c3c9369 Mon Sep 17 00:00:00 2001 From: Ben Skelker Date: Thu, 23 Jul 2020 09:50:27 +0300 Subject: [PATCH 10/14] typo --- docs/siem/detections/api/rules-api-create.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/siem/detections/api/rules-api-create.asciidoc b/docs/siem/detections/api/rules-api-create.asciidoc index a5c2c2aa26..2ace1957ec 100644 --- a/docs/siem/detections/api/rules-api-create.asciidoc +++ b/docs/siem/detections/api/rules-api-create.asciidoc @@ -7,7 +7,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 query. -* Threshold rules: Searches the defined indices and create an alert when the +* 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 generated for each value. From e30802ec9ffacf916f8c1b120fe8427fea3ca8fb Mon Sep 17 00:00:00 2001 From: Ben Skelker Date: Thu, 23 Jul 2020 09:56:51 +0300 Subject: [PATCH 11/14] wording and typos --- docs/siem/detections/api/rules-api-create.asciidoc | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/siem/detections/api/rules-api-create.asciidoc b/docs/siem/detections/api/rules-api-create.asciidoc index 2ace1957ec..ac250fc69f 100644 --- a/docs/siem/detections/api/rules-api-create.asciidoc +++ b/docs/siem/detections/api/rules-api-create.asciidoc @@ -277,10 +277,10 @@ a value from the source event: * `operator` (string, required): Must be `equals`. * `value`(string, required): Must be an empty string (`""`). -|rule_name_override |String |Sets the value used to populate an alert's -`signal.rule.name` field (in the UI, this value is displayed in the *Rule* -column on the Detections page). When unspecified, the rule's `name` value is -used. +|rule_name_override |String |Sets which field in the source event is used to +populate the alert's `signal.rule.name` value (in the UI, this value is +displayed in the *Rule* column on the Detections page). When unspecified, the +rule's `name` value is used. The source field must be a string data type. |severity_mapping |Object[] a|Overrides generated alerts' `severity` with values from the source event: @@ -294,7 +294,7 @@ values from the source event: |timestamp_override |String |Sets the time field used to query indices. When unspecified, rules query the `@timestamp` field. The source field -must an {es} date data type. +must be an {es} date data type. |============================================== From 3c5c360a2d09977724ab0b0454e7a2f703ad6dfb Mon Sep 17 00:00:00 2001 From: Ben Skelker Date: Thu, 23 Jul 2020 10:51:30 +0300 Subject: [PATCH 12/14] updates update rule endpoint --- .../detections/api/rules-api-update.asciidoc | 285 ++++++++++++------ 1 file changed, 187 insertions(+), 98 deletions(-) diff --git a/docs/siem/detections/api/rules-api-update.asciidoc b/docs/siem/detections/api/rules-api-update.asciidoc index 5c753a8148..a2a6294cd7 100644 --- a/docs/siem/detections/api/rules-api-update.asciidoc +++ b/docs/siem/detections/api/rules-api-update.asciidoc @@ -25,145 +25,240 @@ 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, -some fields are required. +some fields are required. + +===== Fields required for `PUT` calls [width="100%",options="header"] |============================================== -|Name |Type |Description |Required (`PUT` calls) +|Name |Type |Description -|actions |<> |Array defining the -automated actions (notifications) taken when signals are produced. |No +|description |String |The rule's description. -|anomaly_threshold |Integer |Anomaly score threshold above which the rule -creates signals. Valid values are from `0` to `100`. |Yes, for {ml} rules. Not -allowed in `query` rule types. +|name |String |The rule's name. -|description |String |The rule's description. |Yes +|risk_score |Integer a|A numerical representation of the alert's severity from +0 to 100, where: -|enabled |Boolean |Determines whether the rule is enabled. |No, defaults to -`true`. +* `0` - `21` represents low severity +* `22` - `47` represents medium severity +* `48` - `73` represents high severity +* `74` - `100` represents critical severity -|false_positives |String[] |String array used to describe common reasons why -the rule may issue false-positive signals. |No, defaults to an empty array. +|severity |String a|Severity level of alerts produced by the rule, which must +be one of the following: -// |filter |Object |{kibana-ref}/field-filter.html[Filter] used by the rule to -// create a signal |Yes, for filter-based rules only +* `low`: Alerts that are of interest but generally not considered to be +security incidents +* `medium`: Alerts that require investigation +* `high`: Alerts that require immediate investigation +* `critical`: Alerts that indicate it is highly likely a security incident has +occurred -|filters |Object[] |The {ref}/query-filter-context.html[query and filter -context] array used to define the conditions for when signals are created from -events. |No, defaults to an empty array. +|type |String a|Data type on which the rule is based: -|from |String |Time from which data is analyzed each time the rule executes, -using a {ref}/common-options.html#date-math[date math range]. For example, -`now-4200s` means the rule analyzes data from 70 minutes before its start -time. |No, defaults to `now-6m` (analyzes data from 6 minutes before the start -time). +* `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. +* `threshold`: rule based on the number of times a `query` matches the +specified field. -|index |String[] |Indices on which the rule functions. |No, defaults to the -{siem-soln} indices defined on the {kib} Advanced Settings page (*Kibana* → -*Management* → *Advanced Settings* → `siem:defaultIndex`). +|============================================== -|interval |String |Frequency of rule execution, using a -{ref}/common-options.html#date-math[date math range]. For example, `"1h"` -means the rule runs every hour. |No, defaults to `5m` (5 minutes). +===== Field required for query 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. + +|============================================== + +===== Field required for threshold rules `PUT` calls + +[width="100%",options="header"] +|============================================== +|Name |Type |Description + +|threshold |Object a|Defines the field and threshold value for when alerts +are generated, where: + +* `field` (string, required): The field on which the threshold is applied. If +you specify an empty field (`""`), alerts are generated when the query returns +at least the number of results specified in the `value` field. +* `value` (integer, required): The threshold value from which an alert is +generated. + +|============================================== + +===== Field required for saved-query rules `PUT` calls + +[width="100%",options="header"] +|============================================== +|Name |Type |Description + +|saved_id |String |Kibana saved search used by the rule to create alerts. + +|============================================== + +===== Fields required for machine-learning rules `PUT` calls + +[width="100%",options="header"] +|============================================== +|Name |Type |Description + +|anomaly_threshold |Integer |Anomaly score threshold above which the rule +creates an alert. Valid values are from `0` to `100`. |machine_learning_job_id |String |{ml-cap} job ID the rule monitors for -anomaly scores. |Yes, for {ml} rules. Not allowed in `query` rules types. +anomaly scores. -|query |String |{kibana-ref}/search.html[Query] used by the rule to create a -signal. |No. For `query` rules types, defaults to an empty string. Not allowed -in `machine-learning` rule types. +|============================================== -|language |String |Determines the query language, which must be -`kuery` or `lucene`. |No. For `query` rule types, defaults to `kuery`. Not -allowed in `machine-learning` rule types. +===== Optional fields for all rule types -|output_index |String |Index to which signals detected by the rule are saved. -|No, if unspecified signals are saved to `.siem-signals-` index, -where `` is the name of the {kib} space in which the rule exists. +[width="100%",options="header"] +|============================================== +|Name |Type |Description -|saved_id |String |Kibana saved search used by the rule to create signals. -|Yes, for `saved_query` rules only. +|actions |<> |Array defining the automated +actions (notifications) taken when alerts are generated. -|meta |Object |Placeholder for metadata about the rule. |No +|author |String[] |The rule's author. -|risk_score |Integer a|A numerical representation of the signal's severity from -0 to 100, where: +|building_block_type |String |Determines if the rule acts as a building block. +By default, building-block alerts are not displayed in the UI. These rules are +used as a foundation for other rules that do generate alerts. Its value must be +`default`. For more information, see BEN - add link later. -* `0` - `21` represents low severity -* `22` - `47` represents medium severity -* `48` - `73` represents high severity -* `74` - `100` represents critical severity +|enabled |Boolean |Determines whether the rule is enabled. Defaults to `true`. -|Yes +|false_positives |String[] |String array used to describe common reasons why +the rule may issue false-positive alerts. Defaults to an empty array. -|max_signals |Integer |Maximum number of signals the rule can create during a -single execution. |No, defaults to `100`. +[[detection-rules-from]] +|from |String |Time from which data is analyzed each time the rule executes, +using a {ref}/common-options.html#date-math[date math range]. For example, +`now-4200s` means the rule analyzes data from 70 minutes before its start +time. Defaults to `now-6m` (analyzes data from 6 minutes before the start +time). -|name |String |The rule's name. |Yes +|interval |String |Frequency of rule execution, using a +{ref}/common-options.html#date-math[date math range]. For example, `"1h"` +means the rule runs every hour. Defaults to `5m` (5 minutes). -|note |String |Notes to help investigate signals produced by the rule. |No +|license |String |The rule's license. -|severity |String a|Severity level of signals produced by the rule, which must -be one of the following: +|max_signals |Integer |Maximum number of alerts the rule can create during a +single execution. Defaults to `100`. -* `low`: Signals that are of interest but generally not considered to be -security incidents -* `medium`: Signals that require investigation -* `high`: Signals that require immediate investigation -* `critical`: Signals that indicate it is highly likely a security incident has -occurred +|meta |Object |Placeholder for metadata about the rule. -|Yes +|note |String |Notes to help investigate alerts produced by the rule. + +|output_index |String |Index to which alerts created by the rule are saved. +If unspecified alerts are saved to `.siem-signals-` index, +where `` is the name of the {kib} space in which the rule exists. + +|references |String[] |Array containing notes about or references to +relevant information about the rule. Defaults to an empty array. |tags |String[] |String array containing words and phrases to help categorize, -filter, and search rules. |No, defaults to an empty array. +filter, and search rules. Defaults to an empty array. -// |to |String |Time to which data is analyzed each time the rule executes, using a -// {ref}/common-options.html#date-math[date math range]. For example, `"now-300s"` -// means the rule analyzes data until 5 minutes before its starts time. +|threat |<> |Object containing attack +information about the type of threat the rule monitors, see +{ecs-ref}/ecs-threat.html[ECS threat fields]. Defaults to an empty array. |throttle |String a|Determines how often actions are taken: * `no_actions`: Never -* `rule`: Every time new signals are detected +* `rule`: Every time new alerts are detected * `1h`: Every hour * `1d`: Every day * `7d`: Every week -|Yes, when actions are used to send notifications. +Required when `actions` are used to send notifications. -|type |String a|Data type on which the rule is based: +|version |Integer a|The rule's version number. If this is not provided, the +rule's version number is incremented by 1. -* `query`: query-based conditions 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. +`PATCH` calls enabling and disabling the rule do not increment its version +number. + +|============================================== -|Yes +===== Optional fields for query and threshold rules -|threat |<> |Object containing attack -information about the type of threat the rule monitors, see -{ecs-ref}/ecs-threat.html[ECS threat fields]. |No, defaults to an empty array. +[width="100%",options="header"] +|============================================== +|Name |Type |Description -|references |String[] |String array containing notes about or references to -relevant information about the rule. |No, defaults to an empty array. +|exceptions_list |Object[] a|Array of exception containers, which define +exceptions that prevent the rule from generating alerts even when its other +criteria are met. The object has these fields: -|version |Integer a|The rule's version number. If this is not provided, the -rule's version number is incremented by 1. +* `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`). +* `type` (string, required): The exception type, which must be either +a detection rule exception (`detection`) or an endpoint exception (`endpoint`). -`PATCH` calls enabling and disabling the rule do not increment its version -number. +BEN - add link later + +|filters |Object[] |The {ref}/query-filter-context.html[query and filter +context] array used to define the conditions for when alerts are created from +events. Defaults to an empty array. + +|index |String[] |Indices on which the rule functions. Defaults to the +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: + +* `field` (string, required): Source event field used to override the default +`risk_score`. This field must be an integer. +* `operator` (string, required): Must be `equals`. +* `value`(string, required): Must be an empty string (`""`). + +|rule_name_override |String |Sets which field in the source event is used to +populate the alert's `signal.rule.name` value (in the UI, this value is +displayed in the *Rule* column on the Detections page). When unspecified, the +rule's `name` value is used. The source field must be a string data type. + +|severity_mapping |Object[] a|Overrides generated alerts' `severity` with +values from the source event: -|No +* `field` (string, required): Source event field used to override the default +`severity`. +* `operator` (string, required): Must be `equals`. +* `severity` (string, required): Mapped severity value, must be `low`, +`medium`, `high`, or `critical`. +* `value`(string, required): Field value used to determine the `severity`. + +|timestamp_override |String |Sets the time field used to query indices. +When unspecified, rules query the `@timestamp` field. The source field +must be an {es} date data type. |============================================== [[actions-object-schema-update]] ===== `actions` schema +These fields are required when calling `PUT` to modify the `actions` object: + [width="100%",options="header"] |============================================== -|Name |Type |Description |Required (`PUT` calls) +|Name |Type |Description |action_type_id |String a|The action type used for sending notifications, can be: @@ -173,12 +268,10 @@ be: * `.pagerduty` * `.webhook` -|Yes - |group |String |Optionally groups actions by use cases. Use `default` for signal -notifications.|Yes +notifications. -|id |String |The connector ID. |Yes +|id |String |The connector ID. |params |Object a|Object containing the allowed connector fields, which varies according to the connector type: @@ -208,23 +301,19 @@ saved object ID of the action. `No summary provided`. Maximum length is 1024 characters. ** `class` (string, optional): Value indicating the class/type of the event. -|Yes - |============================================== [[threats-object-update]] ===== `threat` schema -NOTE: Only threats described using the MITRE ATT&CK^TM^ framework are displayed -in the UI (*SIEM* -> *Detections* -> *Manage signal detection rules* -> -). +These fields are required when calling `PUT` to modify the `threat` object: [width="100%",options="header"] |============================================== -|Name |Type |Description |Required (`PUT` calls) +|Name |Type |Description -|framework |String |Relevant attack framework. |Yes +|framework |String |Relevant attack framework. |tactic |Object a|Object containing information on the attack type: @@ -232,8 +321,6 @@ in the UI (*SIEM* -> *Detections* -> *Manage signal detection rules* -> * `name` - string, required * `reference` - string, required -|Yes - |technique |Object a|Object containing information on the attack technique: @@ -241,10 +328,12 @@ technique: * `name` - string, required * `reference` - string, required -|Yes - |============================================== +NOTE: Only threats described using the MITRE ATT&CK^TM^ framework are displayed +in the UI (*SIEM* -> *Detections* -> *Manage signal detection rules* -> +). + ===== Example request Updates the `threat` object: From 5fbfe5510d46ffeb523d91b545c590cf804c2e71 Mon Sep 17 00:00:00 2001 From: Ben Skelker Date: Thu, 23 Jul 2020 11:05:05 +0300 Subject: [PATCH 13/14] terminology --- docs/siem/detections/api/rules-api-update.asciidoc | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/siem/detections/api/rules-api-update.asciidoc b/docs/siem/detections/api/rules-api-update.asciidoc index a2a6294cd7..c1fc8fe3d3 100644 --- a/docs/siem/detections/api/rules-api-update.asciidoc +++ b/docs/siem/detections/api/rules-api-update.asciidoc @@ -1,7 +1,7 @@ [[rules-api-update]] === Update rule -Updates an existing signal detection rule. +Updates an existing detection rule. You can use `PUT` or `PATCH` methods to update rules, where: @@ -268,7 +268,7 @@ be: * `.pagerduty` * `.webhook` -|group |String |Optionally groups actions by use cases. Use `default` for signal +|group |String |Optionally groups actions by use cases. Use `default` for alert notifications. |id |String |The connector ID. @@ -285,15 +285,15 @@ sent. At least one field must have a value. * For Webhook: ** `body` (string, required): JSON payload. * For PagerDuty: -** `severity` (string, required): Severity of on the signal notification, can +** `severity` (string, required): Severity of on the alert notification, can be: `Critical`, `Error`, `Warning` or `Info`. ** `eventAction` (string, required): Event https://v2.developer.pagerduty.com/docs/events-api-v2#event-action[action type], which can be `trigger`, `resolve`, or `acknowledge`. -** `dedupKey` (string, optional): Groups signal notifications with the same +** `dedupKey` (string, optional): Groups alert notifications with the same PagerDuty alert. ** `timestamp` (DateTime, optional): https://v2.developer.pagerduty.com/v2/docs/types#datetime[ISO-8601 format timestamp]. ** `component` (string, optional): Source machine component responsible for the -event, for example `siem`. +event, for example `security-solution`. ** `group` (string, optional): Enables logical grouping of service components. ** `source` (string, optional): The affected system. Defaults to the {kib} saved object ID of the action. @@ -331,8 +331,8 @@ technique: |============================================== NOTE: Only threats described using the MITRE ATT&CK^TM^ framework are displayed -in the UI (*SIEM* -> *Detections* -> *Manage signal detection rules* -> -). +in the UI (*Security* -> *Detections* -> *Manage detection rules* -> ). ===== Example request From 5b8008ed1b525186d8cc4260e1e389fac21326de Mon Sep 17 00:00:00 2001 From: Ben Skelker Date: Sun, 26 Jul 2020 15:56:51 +0300 Subject: [PATCH 14/14] corrections after review --- docs/siem/detections/api/rules-api-create.asciidoc | 6 +++--- docs/siem/detections/api/signals-api-overview.asciidoc | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/siem/detections/api/rules-api-create.asciidoc b/docs/siem/detections/api/rules-api-create.asciidoc index ac250fc69f..3ca370e77a 100644 --- a/docs/siem/detections/api/rules-api-create.asciidoc +++ b/docs/siem/detections/api/rules-api-create.asciidoc @@ -5,9 +5,9 @@ Creates a new detection rule. You can create these types of rules: -* Query rules: Searches the defined indices and creates an alert when +* *Query rules*: Searches the defined indices and creates an alert when a document matches the rule's query. -* Threshold rules: Searches the defined indices and creates an alert when the +* *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 generated for each value. @@ -17,7 +17,7 @@ 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 <>). +* *{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/siem/detections/api/signals-api-overview.asciidoc b/docs/siem/detections/api/signals-api-overview.asciidoc index 8f2f71b653..d7cc1d279e 100644 --- a/docs/siem/detections/api/signals-api-overview.asciidoc +++ b/docs/siem/detections/api/signals-api-overview.asciidoc @@ -6,7 +6,7 @@ The signals endpoint is for retrieving, aggregating, and updating detection alerts. For detailed information on how to retrieve and aggregate results from the indices, see: -* {ref}/getting-started-search.html[Start searching] +* {ref}/getting-started-search.html[Start searching indices] * {ref}/search-aggregations.html[Aggregations] * {ref}/query-dsl.html[Query DSL]