Preview rule alerts generated on specified time range

Base URL: https://{kibana_url}

POST /api/detection_engine/rules/preview
POST /s/{space_id}/api/detection_engine/rules/preview

Refer to Spaces for more information.

Simulates a detection rule using the same rule type and query logic as a persisted rule, over a short time window, without persisting a rule or writing alerts. Use the response to validate queries, see sample matching documents, and inspect execution logs. Pair invocationCount and timeframeEnd to cap run time.

Authentication

Query parameters

Request body

Rule create payload (same shape as POST /api/detection_engine/rules for a given type) plus invocationCount and timeframeEnd to control how the preview is executed. Optional enable_logged_requests surfaces Elasticsearch request logging for debugging.

Any of:

type: eql

type enum required: Rule type; Values: eql
actions object[]: Array defining the automated actions (notifications) taken when alerts are generated.
alias_purpose enum: Values: savedObjectConversion savedObjectImport
alias_target_id string
author string[]: The rule’s author.
building_block_type string: Determines if the rule acts as a building block. If yes, the value must be default. 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. For more information, refer to About building block rules.
description string · min length: 1 required: The rule’s description.
enabled boolean: Determines whether the rule is enabled. Defaults to true.
exceptions_list object[]
false_positives string[]: String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.
from string · format: date-math: Time from which data is analyzed each time the rule runs, using a 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).
interval string: Frequency of rule execution, using a date math range. For example, "1h" means the rule runs every hour. Defaults to 5m (5 minutes).
investigation_fields object: Schema for fields relating to investigation fields. These are user defined fields we use to highlight in various features in the UI such as alert details flyout and exceptions auto-population from alert.
license string: The rule's license.
max_signals integer · min: 1: Maximum number of alerts the rule can create during a single run (the rule’s Max alerts per run advanced setting value). Defaults to 100.

Note

This setting can be superseded by the Kibana configuration setting xpack.alerting.rules.run.alerts.max, which determines the maximum alerts generated by any rule in the Kibana alerting framework. For example, if xpack.alerting.rules.run.alerts.max is set to 1000, the rule can generate no more than 1000 alerts even if max_signals is set higher.
meta object: Placeholder for metadata about the rule.

Note

This field is overwritten when you save changes to the rule’s settings.
name string · min length: 1 required: A human-readable name for the rule.
namespace string: Has no effect.
note string: Notes to help investigate alerts produced by the rule.
outcome enum: Values: exactMatch aliasMatch conflict
output_index string deprecated: (deprecated) Has no effect.
references string[]: Array containing notes about or references to relevant information about the rule. Defaults to an empty array.
related_integrations object[]
required_fields object[]: Elasticsearch fields and their types that need to be present for the rule to function.

Note

The value of required_fields does not affect the rule’s behavior, and specifying it incorrectly won’t cause the rule to fail. Use required_fields as an informational property to document the fields that the rule expects to be present in the data.
response_actions union oneOf[]: One of:
risk_score integer · min: 0 · max: 100 required: A numerical representation of the alert's severity from 0 to 100, where:

0 - 21 represents low severity

22 - 47 represents medium severity

48 - 73 represents high severity

74 - 100 represents critical severity
risk_score_mapping object[]: Overrides generated alerts' risk_score with a value from the source event
rule_id string: A stable unique identifier for the rule object. It can be assigned during rule creation. It can be any string, but often is a UUID. It should be unique not only within a given Kibana space, but also across spaces and Elastic environments. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have the same rule_ids.
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 on the Rules page in the Rule column). When unspecified, the rule’s name value is used. The source field must be a string data type.
setup string: Populates the rule’s setup guide with instructions on rule prerequisites such as required integrations, configuration steps, and anything else needed for the rule to work correctly.
severity enum required: Severity level of alerts produced by the rule, which must be one of the following:

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; Values: low medium high critical
severity_mapping object[]: Overrides generated alerts' severity with values from the source event
tags string[]: String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.
threat object[]
throttle union oneOf: Defines how often rule actions are taken.; Values: no_actions rule
timeline_id string: Timeline template ID
timeline_title string: Timeline template title
timestamp_override string: Sets the time field used to query indices. When unspecified, rules query the @timestamp field. The source field must be an Elasticsearch date data type.
timestamp_override_fallback_disabled boolean: Disables the fallback to the event's @timestamp field
to string
version integer · min: 1: The rule's version number.

For prebuilt rules it represents the version of the rule's content in the source detection-rules repository (and the corresponding security_detection_engine Fleet package that is used for distributing prebuilt rules).

For custom rules it is set to 1 when the rule is created.

Note

It is not incremented on each update. Compare this to the revision field.
language enum required: Values: eql
query string required: Query used by the rule to create alerts.

For indicator match rules, only the query’s results are used to determine whether an alert is generated.

ES|QL rules have additional query requirements. Refer to Create ES|QL rules for more information.
alert_suppression object: Defines alert suppression configuration.
data_view_id string
event_category_override string
filters object[]: The query and filter context array used to define the conditions for when alerts are created from events. Defaults to an empty array.

Note

This field is not supported for ES|QL rules.
index string[]: Indices on which the rule functions. Defaults to the Security Solution indices defined on the Kibana Advanced Settings page (Kibana → Stack Management → Advanced Settings → securitySolution:defaultIndex).

Note

This field is not supported for ES|QL rules.
tiebreaker_field string: Sets a secondary field for sorting events
timestamp_field string: Specifies the name of the event timestamp field used for sorting a sequence of events. Not to be confused with timestamp_override, which specifies the more general field used for querying events within a range. Defaults to the @timestamp ECS field.
invocationCount integer required
timeframeEnd string · format: date-time required

type: query

type enum required: Rule type; Values: query
actions object[]: Array defining the automated actions (notifications) taken when alerts are generated.; Same fields as actions in type: eql
alias_purpose enum: Values: savedObjectConversion savedObjectImport
alias_target_id string
author string[]: The rule’s author.
building_block_type string: Determines if the rule acts as a building block. If yes, the value must be default. 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. For more information, refer to About building block rules.
description string · min length: 1 required: The rule’s description.
enabled boolean: Determines whether the rule is enabled. Defaults to true.
exceptions_list object[]
false_positives string[]: String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.
from string · format: date-math: Time from which data is analyzed each time the rule runs, using a 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).
interval string: Frequency of rule execution, using a date math range. For example, "1h" means the rule runs every hour. Defaults to 5m (5 minutes).
investigation_fields object: Schema for fields relating to investigation fields. These are user defined fields we use to highlight in various features in the UI such as alert details flyout and exceptions auto-population from alert.
license string: The rule's license.
max_signals integer · min: 1: Maximum number of alerts the rule can create during a single run (the rule’s Max alerts per run advanced setting value). Defaults to 100.

Note

This setting can be superseded by the Kibana configuration setting xpack.alerting.rules.run.alerts.max, which determines the maximum alerts generated by any rule in the Kibana alerting framework. For example, if xpack.alerting.rules.run.alerts.max is set to 1000, the rule can generate no more than 1000 alerts even if max_signals is set higher.
meta object: Placeholder for metadata about the rule.

Note

This field is overwritten when you save changes to the rule’s settings.
name string · min length: 1 required: A human-readable name for the rule.
namespace string: Has no effect.
note string: Notes to help investigate alerts produced by the rule.
outcome enum: Values: exactMatch aliasMatch conflict
output_index string deprecated: (deprecated) Has no effect.
references string[]: Array containing notes about or references to relevant information about the rule. Defaults to an empty array.
related_integrations object[]
required_fields object[]: Elasticsearch fields and their types that need to be present for the rule to function.

Note

The value of required_fields does not affect the rule’s behavior, and specifying it incorrectly won’t cause the rule to fail. Use required_fields as an informational property to document the fields that the rule expects to be present in the data.
response_actions union oneOf[]: Same options as response_actions in type: eql
risk_score integer · min: 0 · max: 100 required: A numerical representation of the alert's severity from 0 to 100, where:

0 - 21 represents low severity

22 - 47 represents medium severity

48 - 73 represents high severity

74 - 100 represents critical severity
risk_score_mapping object[]: Overrides generated alerts' risk_score with a value from the source event
rule_id string: A stable unique identifier for the rule object. It can be assigned during rule creation. It can be any string, but often is a UUID. It should be unique not only within a given Kibana space, but also across spaces and Elastic environments. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have the same rule_ids.
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 on the Rules page in the Rule column). When unspecified, the rule’s name value is used. The source field must be a string data type.
setup string: Populates the rule’s setup guide with instructions on rule prerequisites such as required integrations, configuration steps, and anything else needed for the rule to work correctly.
severity enum required: Severity level of alerts produced by the rule, which must be one of the following:

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; Values: low medium high critical
severity_mapping object[]: Overrides generated alerts' severity with values from the source event
tags string[]: String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.
threat object[]: Same fields as threat in type: eql
throttle union oneOf: Defines how often rule actions are taken.; Values: no_actions rule
timeline_id string: Timeline template ID
timeline_title string: Timeline template title
timestamp_override string: Sets the time field used to query indices. When unspecified, rules query the @timestamp field. The source field must be an Elasticsearch date data type.
timestamp_override_fallback_disabled boolean: Disables the fallback to the event's @timestamp field
to string
version integer · min: 1: The rule's version number.

For prebuilt rules it represents the version of the rule's content in the source detection-rules repository (and the corresponding security_detection_engine Fleet package that is used for distributing prebuilt rules).

For custom rules it is set to 1 when the rule is created.

Note

It is not incremented on each update. Compare this to the revision field.
alert_suppression object: Defines alert suppression configuration.
data_view_id string
filters object[]: The query and filter context array used to define the conditions for when alerts are created from events. Defaults to an empty array.

Note

This field is not supported for ES|QL rules.
index string[]: Indices on which the rule functions. Defaults to the Security Solution indices defined on the Kibana Advanced Settings page (Kibana → Stack Management → Advanced Settings → securitySolution:defaultIndex).

Note

This field is not supported for ES|QL rules.
saved_id string: Kibana saved search used by the rule to create alerts.
language enum: Values: kuery lucene
query string: Query used by the rule to create alerts.

For indicator match rules, only the query’s results are used to determine whether an alert is generated.

ES|QL rules have additional query requirements. Refer to Create ES|QL rules for more information.
invocationCount integer required
timeframeEnd string · format: date-time required

type: saved_query

type enum required: Rule type; Values: saved_query
actions object[]: Array defining the automated actions (notifications) taken when alerts are generated.; Same fields as actions in type: eql
alias_purpose enum: Values: savedObjectConversion savedObjectImport
alias_target_id string
author string[]: The rule’s author.
building_block_type string: Determines if the rule acts as a building block. If yes, the value must be default. 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. For more information, refer to About building block rules.
description string · min length: 1 required: The rule’s description.
enabled boolean: Determines whether the rule is enabled. Defaults to true.
exceptions_list object[]
false_positives string[]: String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.
from string · format: date-math: Time from which data is analyzed each time the rule runs, using a 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).
interval string: Frequency of rule execution, using a date math range. For example, "1h" means the rule runs every hour. Defaults to 5m (5 minutes).
investigation_fields object: Schema for fields relating to investigation fields. These are user defined fields we use to highlight in various features in the UI such as alert details flyout and exceptions auto-population from alert.
license string: The rule's license.
max_signals integer · min: 1: Maximum number of alerts the rule can create during a single run (the rule’s Max alerts per run advanced setting value). Defaults to 100.

Note

This setting can be superseded by the Kibana configuration setting xpack.alerting.rules.run.alerts.max, which determines the maximum alerts generated by any rule in the Kibana alerting framework. For example, if xpack.alerting.rules.run.alerts.max is set to 1000, the rule can generate no more than 1000 alerts even if max_signals is set higher.
meta object: Placeholder for metadata about the rule.

Note

This field is overwritten when you save changes to the rule’s settings.
name string · min length: 1 required: A human-readable name for the rule.
namespace string: Has no effect.
note string: Notes to help investigate alerts produced by the rule.
outcome enum: Values: exactMatch aliasMatch conflict
output_index string deprecated: (deprecated) Has no effect.
references string[]: Array containing notes about or references to relevant information about the rule. Defaults to an empty array.
related_integrations object[]
required_fields object[]: Elasticsearch fields and their types that need to be present for the rule to function.

Note

The value of required_fields does not affect the rule’s behavior, and specifying it incorrectly won’t cause the rule to fail. Use required_fields as an informational property to document the fields that the rule expects to be present in the data.
response_actions union oneOf[]: Same options as response_actions in type: eql
risk_score integer · min: 0 · max: 100 required: A numerical representation of the alert's severity from 0 to 100, where:

0 - 21 represents low severity

22 - 47 represents medium severity

48 - 73 represents high severity

74 - 100 represents critical severity
risk_score_mapping object[]: Overrides generated alerts' risk_score with a value from the source event
rule_id string: A stable unique identifier for the rule object. It can be assigned during rule creation. It can be any string, but often is a UUID. It should be unique not only within a given Kibana space, but also across spaces and Elastic environments. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have the same rule_ids.
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 on the Rules page in the Rule column). When unspecified, the rule’s name value is used. The source field must be a string data type.
setup string: Populates the rule’s setup guide with instructions on rule prerequisites such as required integrations, configuration steps, and anything else needed for the rule to work correctly.
severity enum required: Severity level of alerts produced by the rule, which must be one of the following:

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; Values: low medium high critical
severity_mapping object[]: Overrides generated alerts' severity with values from the source event
tags string[]: String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.
threat object[]: Same fields as threat in type: eql
throttle union oneOf: Defines how often rule actions are taken.; Values: no_actions rule
timeline_id string: Timeline template ID
timeline_title string: Timeline template title
timestamp_override string: Sets the time field used to query indices. When unspecified, rules query the @timestamp field. The source field must be an Elasticsearch date data type.
timestamp_override_fallback_disabled boolean: Disables the fallback to the event's @timestamp field
to string
version integer · min: 1: The rule's version number.

For prebuilt rules it represents the version of the rule's content in the source detection-rules repository (and the corresponding security_detection_engine Fleet package that is used for distributing prebuilt rules).

For custom rules it is set to 1 when the rule is created.

Note

It is not incremented on each update. Compare this to the revision field.
saved_id string required: Kibana saved search used by the rule to create alerts.
alert_suppression object: Defines alert suppression configuration.
data_view_id string
filters object[]: The query and filter context array used to define the conditions for when alerts are created from events. Defaults to an empty array.

Note

This field is not supported for ES|QL rules.
index string[]: Indices on which the rule functions. Defaults to the Security Solution indices defined on the Kibana Advanced Settings page (Kibana → Stack Management → Advanced Settings → securitySolution:defaultIndex).

Note

This field is not supported for ES|QL rules.
query string: Query used by the rule to create alerts.

For indicator match rules, only the query’s results are used to determine whether an alert is generated.

ES|QL rules have additional query requirements. Refer to Create ES|QL rules for more information.
language enum: Values: kuery lucene
invocationCount integer required
timeframeEnd string · format: date-time required

type: threshold

type enum required: Rule type; Values: threshold
actions object[]: Array defining the automated actions (notifications) taken when alerts are generated.; Same fields as actions in type: eql
alias_purpose enum: Values: savedObjectConversion savedObjectImport
alias_target_id string
author string[]: The rule’s author.
building_block_type string: Determines if the rule acts as a building block. If yes, the value must be default. 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. For more information, refer to About building block rules.
description string · min length: 1 required: The rule’s description.
enabled boolean: Determines whether the rule is enabled. Defaults to true.
exceptions_list object[]
false_positives string[]: String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.
from string · format: date-math: Time from which data is analyzed each time the rule runs, using a 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).
interval string: Frequency of rule execution, using a date math range. For example, "1h" means the rule runs every hour. Defaults to 5m (5 minutes).
investigation_fields object: Schema for fields relating to investigation fields. These are user defined fields we use to highlight in various features in the UI such as alert details flyout and exceptions auto-population from alert.
license string: The rule's license.
max_signals integer · min: 1: Maximum number of alerts the rule can create during a single run (the rule’s Max alerts per run advanced setting value). Defaults to 100.

Note

This setting can be superseded by the Kibana configuration setting xpack.alerting.rules.run.alerts.max, which determines the maximum alerts generated by any rule in the Kibana alerting framework. For example, if xpack.alerting.rules.run.alerts.max is set to 1000, the rule can generate no more than 1000 alerts even if max_signals is set higher.
meta object: Placeholder for metadata about the rule.

Note

This field is overwritten when you save changes to the rule’s settings.
name string · min length: 1 required: A human-readable name for the rule.
namespace string: Has no effect.
note string: Notes to help investigate alerts produced by the rule.
outcome enum: Values: exactMatch aliasMatch conflict
output_index string deprecated: (deprecated) Has no effect.
references string[]: Array containing notes about or references to relevant information about the rule. Defaults to an empty array.
related_integrations object[]
required_fields object[]: Elasticsearch fields and their types that need to be present for the rule to function.

Note

The value of required_fields does not affect the rule’s behavior, and specifying it incorrectly won’t cause the rule to fail. Use required_fields as an informational property to document the fields that the rule expects to be present in the data.
response_actions union oneOf[]: Same options as response_actions in type: eql
risk_score integer · min: 0 · max: 100 required: A numerical representation of the alert's severity from 0 to 100, where:

0 - 21 represents low severity

22 - 47 represents medium severity

48 - 73 represents high severity

74 - 100 represents critical severity
risk_score_mapping object[]: Overrides generated alerts' risk_score with a value from the source event
rule_id string: A stable unique identifier for the rule object. It can be assigned during rule creation. It can be any string, but often is a UUID. It should be unique not only within a given Kibana space, but also across spaces and Elastic environments. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have the same rule_ids.
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 on the Rules page in the Rule column). When unspecified, the rule’s name value is used. The source field must be a string data type.
setup string: Populates the rule’s setup guide with instructions on rule prerequisites such as required integrations, configuration steps, and anything else needed for the rule to work correctly.
severity enum required: Severity level of alerts produced by the rule, which must be one of the following:

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; Values: low medium high critical
severity_mapping object[]: Overrides generated alerts' severity with values from the source event
tags string[]: String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.
threat object[]: Same fields as threat in type: eql
throttle union oneOf: Defines how often rule actions are taken.; Values: no_actions rule
timeline_id string: Timeline template ID
timeline_title string: Timeline template title
timestamp_override string: Sets the time field used to query indices. When unspecified, rules query the @timestamp field. The source field must be an Elasticsearch date data type.
timestamp_override_fallback_disabled boolean: Disables the fallback to the event's @timestamp field
to string
version integer · min: 1: The rule's version number.

For prebuilt rules it represents the version of the rule's content in the source detection-rules repository (and the corresponding security_detection_engine Fleet package that is used for distributing prebuilt rules).

For custom rules it is set to 1 when the rule is created.

Note

It is not incremented on each update. Compare this to the revision field.
query string required: Query used by the rule to create alerts.

For indicator match rules, only the query’s results are used to determine whether an alert is generated.

ES|QL rules have additional query requirements. Refer to Create ES|QL rules for more information.
threshold object required
alert_suppression object: Defines alert suppression configuration.
data_view_id string
filters object[]: The query and filter context array used to define the conditions for when alerts are created from events. Defaults to an empty array.

Note

This field is not supported for ES|QL rules.
index string[]: Indices on which the rule functions. Defaults to the Security Solution indices defined on the Kibana Advanced Settings page (Kibana → Stack Management → Advanced Settings → securitySolution:defaultIndex).

Note

This field is not supported for ES|QL rules.
saved_id string: Kibana saved search used by the rule to create alerts.
language enum: Values: kuery lucene
invocationCount integer required
timeframeEnd string · format: date-time required

type: threat_match

type enum required

Rule type

Values: threat_match

actions object[]

Array defining the automated actions (notifications) taken when alerts are generated.

Same fields as actions in type: eql

alias_purpose enum

Values: savedObjectConversion savedObjectImport

alias_target_id string

author string[]

The rule’s author.

building_block_type string

Determines if the rule acts as a building block. If yes, the value must be default. 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. For more information, refer to About building block rules.

description string · min length: 1 required

The rule’s description.

enabled boolean

Determines whether the rule is enabled. Defaults to true.

exceptions_list object[]

false_positives string[]

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.

from string · format: date-math

Time from which data is analyzed each time the rule runs, using a 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).

interval string

Frequency of rule execution, using a date math range. For example, "1h" means the rule runs every hour. Defaults to 5m (5 minutes).

investigation_fields object

Schema for fields relating to investigation fields. These are user defined fields we use to highlight in various features in the UI such as alert details flyout and exceptions auto-population from alert.

license string

The rule's license.

max_signals integer · min: 1

Maximum number of alerts the rule can create during a single run (the rule’s Max alerts per run advanced setting value). Defaults to 100.

Note

This setting can be superseded by the Kibana configuration setting xpack.alerting.rules.run.alerts.max, which determines the maximum alerts generated by any rule in the Kibana alerting framework. For example, if xpack.alerting.rules.run.alerts.max is set to 1000, the rule can generate no more than 1000 alerts even if max_signals is set higher.

meta object

Placeholder for metadata about the rule.

Note

This field is overwritten when you save changes to the rule’s settings.

name string · min length: 1 required

A human-readable name for the rule.

namespace string

Has no effect.

note string

Notes to help investigate alerts produced by the rule.

outcome enum

Values: exactMatch aliasMatch conflict

output_index string deprecated

(deprecated) Has no effect.

references string[]

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.

related_integrations object[]

required_fields object[]

Elasticsearch fields and their types that need to be present for the rule to function.

Note

The value of required_fields does not affect the rule’s behavior, and specifying it incorrectly won’t cause the rule to fail. Use required_fields as an informational property to document the fields that the rule expects to be present in the data.

response_actions union oneOf[]

Same options as response_actions in type: eql

risk_score integer · min: 0 · max: 100 required

A numerical representation of the alert's severity from 0 to 100, where:

0 - 21 represents low severity
22 - 47 represents medium severity
48 - 73 represents high severity
74 - 100 represents critical severity

risk_score_mapping object[]

Overrides generated alerts' risk_score with a value from the source event

rule_id string

A stable unique identifier for the rule object. It can be assigned during rule creation. It can be any string, but often is a UUID. It should be unique not only within a given Kibana space, but also across spaces and Elastic environments. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have the same rule_ids.

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 on the Rules page in the Rule column). When unspecified, the rule’s name value is used. The source field must be a string data type.

setup string

Populates the rule’s setup guide with instructions on rule prerequisites such as required integrations, configuration steps, and anything else needed for the rule to work correctly.

severity enum required

Severity level of alerts produced by the rule, which must be one of the following:

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

Values: low medium high critical

severity_mapping object[]

Overrides generated alerts' severity with values from the source event

tags string[]

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.

threat object[]

Same fields as threat in type: eql

throttle union oneOf

Defines how often rule actions are taken.

Values: no_actions rule

timeline_id string

Timeline template ID

timeline_title string

Timeline template title

timestamp_override string

Sets the time field used to query indices. When unspecified, rules query the @timestamp field. The source field must be an Elasticsearch date data type.

timestamp_override_fallback_disabled boolean

Disables the fallback to the event's @timestamp field

to string

version integer · min: 1

The rule's version number.

For prebuilt rules it represents the version of the rule's content in the source detection-rules repository (and the corresponding security_detection_engine Fleet package that is used for distributing prebuilt rules).
For custom rules it is set to 1 when the rule is created.

Note

It is not incremented on each update. Compare this to the revision field.

query string required

Query used by the rule to create alerts.

For indicator match rules, only the query’s results are used to determine whether an alert is generated.
ES|QL rules have additional query requirements. Refer to Create ES|QL rules for more information.

threat_index string[] required

Elasticsearch indices used to check which field values generate alerts.

threat_mapping object[] · min items: 1 required

Array of entries objects that define mappings between the source event fields and the values in the Elasticsearch 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 Elasticsearch 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 Example of Threat Match rule which uses both and and or logic.

threat_query string required

Query used to determine which fields in the Elasticsearch index are used for generating alerts.

alert_suppression object

Defines alert suppression configuration.

concurrent_searches integer · min: 1

data_view_id string

filters object[]

The query and filter context array used to define the conditions for when alerts are created from events. Defaults to an empty array.

Note

This field is not supported for ES|QL rules.

index string[]

Indices on which the rule functions. Defaults to the Security Solution indices defined on the Kibana Advanced Settings page (Kibana → Stack Management → Advanced Settings → securitySolution:defaultIndex).

Note

This field is not supported for ES|QL rules.

items_per_search integer · min: 1

saved_id string

Kibana saved search used by the rule to create alerts.

threat_filters object[]

threat_indicator_path string

Defines the path to the threat indicator in the indicator documents (optional)

threat_language enum

Values: kuery lucene

language enum

Values: kuery lucene

invocationCount integer required

timeframeEnd string · format: date-time required

type: machine_learning

type enum required: Rule type; Values: machine_learning
actions object[]: Array defining the automated actions (notifications) taken when alerts are generated.; Same fields as actions in type: eql
alias_purpose enum: Values: savedObjectConversion savedObjectImport
alias_target_id string
author string[]: The rule’s author.
building_block_type string: Determines if the rule acts as a building block. If yes, the value must be default. 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. For more information, refer to About building block rules.
description string · min length: 1 required: The rule’s description.
enabled boolean: Determines whether the rule is enabled. Defaults to true.
exceptions_list object[]
false_positives string[]: String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.
from string · format: date-math: Time from which data is analyzed each time the rule runs, using a 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).
interval string: Frequency of rule execution, using a date math range. For example, "1h" means the rule runs every hour. Defaults to 5m (5 minutes).
investigation_fields object: Schema for fields relating to investigation fields. These are user defined fields we use to highlight in various features in the UI such as alert details flyout and exceptions auto-population from alert.
license string: The rule's license.
max_signals integer · min: 1: Maximum number of alerts the rule can create during a single run (the rule’s Max alerts per run advanced setting value). Defaults to 100.

Note

This setting can be superseded by the Kibana configuration setting xpack.alerting.rules.run.alerts.max, which determines the maximum alerts generated by any rule in the Kibana alerting framework. For example, if xpack.alerting.rules.run.alerts.max is set to 1000, the rule can generate no more than 1000 alerts even if max_signals is set higher.
meta object: Placeholder for metadata about the rule.

Note

This field is overwritten when you save changes to the rule’s settings.
name string · min length: 1 required: A human-readable name for the rule.
namespace string: Has no effect.
note string: Notes to help investigate alerts produced by the rule.
outcome enum: Values: exactMatch aliasMatch conflict
output_index string deprecated: (deprecated) Has no effect.
references string[]: Array containing notes about or references to relevant information about the rule. Defaults to an empty array.
related_integrations object[]
required_fields object[]: Elasticsearch fields and their types that need to be present for the rule to function.

Note

The value of required_fields does not affect the rule’s behavior, and specifying it incorrectly won’t cause the rule to fail. Use required_fields as an informational property to document the fields that the rule expects to be present in the data.
response_actions union oneOf[]: Same options as response_actions in type: eql
risk_score integer · min: 0 · max: 100 required: A numerical representation of the alert's severity from 0 to 100, where:

0 - 21 represents low severity

22 - 47 represents medium severity

48 - 73 represents high severity

74 - 100 represents critical severity
risk_score_mapping object[]: Overrides generated alerts' risk_score with a value from the source event
rule_id string: A stable unique identifier for the rule object. It can be assigned during rule creation. It can be any string, but often is a UUID. It should be unique not only within a given Kibana space, but also across spaces and Elastic environments. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have the same rule_ids.
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 on the Rules page in the Rule column). When unspecified, the rule’s name value is used. The source field must be a string data type.
setup string: Populates the rule’s setup guide with instructions on rule prerequisites such as required integrations, configuration steps, and anything else needed for the rule to work correctly.
severity enum required: Severity level of alerts produced by the rule, which must be one of the following:

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; Values: low medium high critical
severity_mapping object[]: Overrides generated alerts' severity with values from the source event
tags string[]: String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.
threat object[]: Same fields as threat in type: eql
throttle union oneOf: Defines how often rule actions are taken.; Values: no_actions rule
timeline_id string: Timeline template ID
timeline_title string: Timeline template title
timestamp_override string: Sets the time field used to query indices. When unspecified, rules query the @timestamp field. The source field must be an Elasticsearch date data type.
timestamp_override_fallback_disabled boolean: Disables the fallback to the event's @timestamp field
to string
version integer · min: 1: The rule's version number.

For prebuilt rules it represents the version of the rule's content in the source detection-rules repository (and the corresponding security_detection_engine Fleet package that is used for distributing prebuilt rules).

For custom rules it is set to 1 when the rule is created.

Note

It is not incremented on each update. Compare this to the revision field.
anomaly_threshold integer · min: 0 required: Anomaly score threshold above which the rule creates an alert. Valid values are from 0 to 100.
machine_learning_job_id union oneOf required: Machine learning job ID(s) the rule monitors for anomaly scores.; One of: string[] or string
alert_suppression object: Defines alert suppression configuration.
invocationCount integer required
timeframeEnd string · format: date-time required

type: new_terms

type enum required: Rule type; Values: new_terms
actions object[]: Array defining the automated actions (notifications) taken when alerts are generated.; Same fields as actions in type: eql
alias_purpose enum: Values: savedObjectConversion savedObjectImport
alias_target_id string
author string[]: The rule’s author.
building_block_type string: Determines if the rule acts as a building block. If yes, the value must be default. 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. For more information, refer to About building block rules.
description string · min length: 1 required: The rule’s description.
enabled boolean: Determines whether the rule is enabled. Defaults to true.
exceptions_list object[]
false_positives string[]: String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.
from string · format: date-math: Time from which data is analyzed each time the rule runs, using a 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).
interval string: Frequency of rule execution, using a date math range. For example, "1h" means the rule runs every hour. Defaults to 5m (5 minutes).
investigation_fields object: Schema for fields relating to investigation fields. These are user defined fields we use to highlight in various features in the UI such as alert details flyout and exceptions auto-population from alert.
license string: The rule's license.
max_signals integer · min: 1: Maximum number of alerts the rule can create during a single run (the rule’s Max alerts per run advanced setting value). Defaults to 100.

Note

This setting can be superseded by the Kibana configuration setting xpack.alerting.rules.run.alerts.max, which determines the maximum alerts generated by any rule in the Kibana alerting framework. For example, if xpack.alerting.rules.run.alerts.max is set to 1000, the rule can generate no more than 1000 alerts even if max_signals is set higher.
meta object: Placeholder for metadata about the rule.

Note

This field is overwritten when you save changes to the rule’s settings.
name string · min length: 1 required: A human-readable name for the rule.
namespace string: Has no effect.
note string: Notes to help investigate alerts produced by the rule.
outcome enum: Values: exactMatch aliasMatch conflict
output_index string deprecated: (deprecated) Has no effect.
references string[]: Array containing notes about or references to relevant information about the rule. Defaults to an empty array.
related_integrations object[]
required_fields object[]: Elasticsearch fields and their types that need to be present for the rule to function.

Note

The value of required_fields does not affect the rule’s behavior, and specifying it incorrectly won’t cause the rule to fail. Use required_fields as an informational property to document the fields that the rule expects to be present in the data.
response_actions union oneOf[]: Same options as response_actions in type: eql
risk_score integer · min: 0 · max: 100 required: A numerical representation of the alert's severity from 0 to 100, where:

0 - 21 represents low severity

22 - 47 represents medium severity

48 - 73 represents high severity

74 - 100 represents critical severity
risk_score_mapping object[]: Overrides generated alerts' risk_score with a value from the source event
rule_id string: A stable unique identifier for the rule object. It can be assigned during rule creation. It can be any string, but often is a UUID. It should be unique not only within a given Kibana space, but also across spaces and Elastic environments. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have the same rule_ids.
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 on the Rules page in the Rule column). When unspecified, the rule’s name value is used. The source field must be a string data type.
setup string: Populates the rule’s setup guide with instructions on rule prerequisites such as required integrations, configuration steps, and anything else needed for the rule to work correctly.
severity enum required: Severity level of alerts produced by the rule, which must be one of the following:

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; Values: low medium high critical
severity_mapping object[]: Overrides generated alerts' severity with values from the source event
tags string[]: String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.
threat object[]: Same fields as threat in type: eql
throttle union oneOf: Defines how often rule actions are taken.; Values: no_actions rule
timeline_id string: Timeline template ID
timeline_title string: Timeline template title
timestamp_override string: Sets the time field used to query indices. When unspecified, rules query the @timestamp field. The source field must be an Elasticsearch date data type.
timestamp_override_fallback_disabled boolean: Disables the fallback to the event's @timestamp field
to string
version integer · min: 1: The rule's version number.

For prebuilt rules it represents the version of the rule's content in the source detection-rules repository (and the corresponding security_detection_engine Fleet package that is used for distributing prebuilt rules).

For custom rules it is set to 1 when the rule is created.

Note

It is not incremented on each update. Compare this to the revision field.
history_window_start string · format: nonempty · min length: 1 required: Start date to use when checking if a term has been seen before. Supports relative dates – for example, now-30d will search the last 30 days of data when checking if a term is new. We do not recommend using absolute dates, which can cause issues with rule performance due to querying increasing amounts of data over time.
new_terms_fields string[] · min items: 1 · max items: 3 required: Fields to monitor for new values.
query string required: Query used by the rule to create alerts.

For indicator match rules, only the query’s results are used to determine whether an alert is generated.

ES|QL rules have additional query requirements. Refer to Create ES|QL rules for more information.
alert_suppression object: Defines alert suppression configuration.
data_view_id string
filters object[]: The query and filter context array used to define the conditions for when alerts are created from events. Defaults to an empty array.

Note

This field is not supported for ES|QL rules.
index string[]: Indices on which the rule functions. Defaults to the Security Solution indices defined on the Kibana Advanced Settings page (Kibana → Stack Management → Advanced Settings → securitySolution:defaultIndex).

Note

This field is not supported for ES|QL rules.
language enum: Values: kuery lucene
invocationCount integer required
timeframeEnd string · format: date-time required

type: esql

type enum required: Rule type; Values: esql
actions object[]: Array defining the automated actions (notifications) taken when alerts are generated.; Same fields as actions in type: eql
alias_purpose enum: Values: savedObjectConversion savedObjectImport
alias_target_id string
author string[]: The rule’s author.
building_block_type string: Determines if the rule acts as a building block. If yes, the value must be default. 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. For more information, refer to About building block rules.
description string · min length: 1 required: The rule’s description.
enabled boolean: Determines whether the rule is enabled. Defaults to true.
exceptions_list object[]
false_positives string[]: String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.
from string · format: date-math: Time from which data is analyzed each time the rule runs, using a 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).
interval string: Frequency of rule execution, using a date math range. For example, "1h" means the rule runs every hour. Defaults to 5m (5 minutes).
investigation_fields object: Schema for fields relating to investigation fields. These are user defined fields we use to highlight in various features in the UI such as alert details flyout and exceptions auto-population from alert.
license string: The rule's license.
max_signals integer · min: 1: Maximum number of alerts the rule can create during a single run (the rule’s Max alerts per run advanced setting value). Defaults to 100.

Note

This setting can be superseded by the Kibana configuration setting xpack.alerting.rules.run.alerts.max, which determines the maximum alerts generated by any rule in the Kibana alerting framework. For example, if xpack.alerting.rules.run.alerts.max is set to 1000, the rule can generate no more than 1000 alerts even if max_signals is set higher.
meta object: Placeholder for metadata about the rule.

Note

This field is overwritten when you save changes to the rule’s settings.
name string · min length: 1 required: A human-readable name for the rule.
namespace string: Has no effect.
note string: Notes to help investigate alerts produced by the rule.
outcome enum: Values: exactMatch aliasMatch conflict
output_index string deprecated: (deprecated) Has no effect.
references string[]: Array containing notes about or references to relevant information about the rule. Defaults to an empty array.
related_integrations object[]
required_fields object[]: Elasticsearch fields and their types that need to be present for the rule to function.

Note

The value of required_fields does not affect the rule’s behavior, and specifying it incorrectly won’t cause the rule to fail. Use required_fields as an informational property to document the fields that the rule expects to be present in the data.
response_actions union oneOf[]: Same options as response_actions in type: eql
risk_score integer · min: 0 · max: 100 required: A numerical representation of the alert's severity from 0 to 100, where:

0 - 21 represents low severity

22 - 47 represents medium severity

48 - 73 represents high severity

74 - 100 represents critical severity
risk_score_mapping object[]: Overrides generated alerts' risk_score with a value from the source event
rule_id string: A stable unique identifier for the rule object. It can be assigned during rule creation. It can be any string, but often is a UUID. It should be unique not only within a given Kibana space, but also across spaces and Elastic environments. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have the same rule_ids.
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 on the Rules page in the Rule column). When unspecified, the rule’s name value is used. The source field must be a string data type.
setup string: Populates the rule’s setup guide with instructions on rule prerequisites such as required integrations, configuration steps, and anything else needed for the rule to work correctly.
severity enum required: Severity level of alerts produced by the rule, which must be one of the following:

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; Values: low medium high critical
severity_mapping object[]: Overrides generated alerts' severity with values from the source event
tags string[]: String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.
threat object[]: Same fields as threat in type: eql
throttle union oneOf: Defines how often rule actions are taken.; Values: no_actions rule
timeline_id string: Timeline template ID
timeline_title string: Timeline template title
timestamp_override string: Sets the time field used to query indices. When unspecified, rules query the @timestamp field. The source field must be an Elasticsearch date data type.
timestamp_override_fallback_disabled boolean: Disables the fallback to the event's @timestamp field
to string
version integer · min: 1: The rule's version number.

For prebuilt rules it represents the version of the rule's content in the source detection-rules repository (and the corresponding security_detection_engine Fleet package that is used for distributing prebuilt rules).

For custom rules it is set to 1 when the rule is created.

Note

It is not incremented on each update. Compare this to the revision field.
alert_suppression object: Defines alert suppression configuration.
language enum required: Values: esql
query string required: Query used by the rule to create alerts.

For indicator match rules, only the query’s results are used to determine whether an alert is generated.

ES|QL rules have additional query requirements. Refer to Create ES|QL rules for more information.
invocationCount integer required
timeframeEnd string · format: date-time required

Responses

Successful response

application/json

Invalid input data response

application/json

Unsuccessful authentication response

application/json

Internal server error response

application/json