Preview rule alerts generated on specified time range

POST /api/detection_engine/rules/preview

Spaces method and path for this operation:

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.

Query parameters

enable_logged_requests boolean

Enables logging and returning in response ES queries, performed during rule execution

application/json

Body object Required

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.

actions array[object]

Array defining the automated actions (notifications) taken when alerts are generated.
Hide actions attributes Show actions attributes object
- action_type_id string Required
  The action type used for sending notifications, can be:
  
  .slack
  
  .slack_api
  
  .email
  
  .index
  
  .pagerduty
  
  .swimlane
  
  .webhook
  
  .servicenow
  
  .servicenow-itom
  
  .servicenow-sir
  
  .jira
  
  .resilient
  
  .opsgenie
  
  .teams
  
  .torq
  
  .tines
  
  .d3security
- alerts_filter object
  Object containing an action’s conditional filters.
  
  timeframe (object, optional): Object containing the time frame for when this action can be run.
  
  days (array of integers, required): List of days of the week on which this action will be run. Days of the week are expressed as numbers between 1-7, where 1 is Monday and 7 is Sunday. To select all days of the week, enter an empty array.
  
  hours (object, required): The hours of the day during which this action will run. Hours of the day are expressed as two strings in the format hh:mm in 24 hour time. A start of 00:00 and an end of 24:00 means the action can run all day.
  
  start (string, required): Start time in hh:mm format.
  
  end (string, required): End time in hh:mm format.
  
  timezone (string, required): An ISO timezone name, such as Europe/Madrid or America/New_York. Specific offsets such as UTC or UTC+1 will also work, but lack built-in DST.
  
  query (object, optional): Object containing a query filter which gets applied to an action and determines whether the action should run.
  
  kql (string, required): A KQL string.
  
  filters (array of objects, required): Array of filter objects, as defined in the kbn-es-query package.
  Additional properties are allowed.
- frequency object
  
  The action frequency defines when the action runs (for example, only on rule execution or at specific time intervals).
  Hide frequency attributes Show frequency attributes object
  
  notifyWhen string Required
  
  Defines how often rules run actions.
  
  Values are onActiveAlert, onThrottleInterval, or onActionGroupChange.
  
  summary boolean Required
  
  Action summary indicates whether we will send a summary notification about all the generate alerts or notification per individual alert
  
  throttle string Required
  
  Defines how often rule actions are taken.
  
  One of:
  string-1 string string-2 string
  
  Values are no_actions or rule.
  
  Time interval in seconds, minutes, hours, or days.
  
  Format should match the following pattern: ^[1-9]\d*[smhd]$.
- group string
  
  Optionally groups actions by use cases. Use default for alert notifications.
- id string Required
  
  The connector ID.
- params object Required
  Object containing the allowed connector fields, which varies according to the connector type.
  
  For Slack:
  
  message (string, required): The notification message.
  
  For email:
  
  to, cc, bcc (string): Email addresses to which the notifications are sent. At least one field must have a value.
  
  subject (string, optional): Email subject line.
  
  message (string, required): Email body text.
  
  For Webhook:
  
  body (string, required): JSON payload.
  
  For PagerDuty:
  
  severity (string, required): Severity of on the alert notification, can be: Critical, Error, Warning or Info.
  
  eventAction (string, required): Event action type, which can be trigger, resolve, or acknowledge.
  
  dedupKey (string, optional): Groups alert notifications with the same PagerDuty alert.
  
  timestamp (DateTime, optional): ISO-8601 format timestamp.
  
  component (string, optional): Source machine component responsible for the event, for example security-solution.
  
  group (string, optional): Enables logical grouping of service components.
  
  source (string, optional): The affected system. Defaults to the Kibana saved object ID of the action.
  
  summary (string, options): Summary of the event. Defaults to No summary provided. Maximum length is 1024 characters.
  
  class (string, optional): Value indicating the class/type of the event.
  Additional properties are allowed.
- uuid string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
alias_purpose string

Values are savedObjectConversion or savedObjectImport.
alias_target_id string
author array[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 Required

The rule’s description.

Minimum length is 1.
enabled boolean

Determines whether the rule is enabled. Defaults to true.
exceptions_list array[object]
Hide exceptions_list attributes Show exceptions_list attributes object
Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.
- id string(nonempty) Required
  
  ID of the exception container
  
  Minimum length is 1.
- list_id string(nonempty) Required
  
  List ID of the exception container
  
  Minimum length is 1.
- namespace_type string Required
  
  Determines the exceptions validity in rule's Kibana space
  
  Values are agnostic or single.
- type string Required
  
  The exception type
  
  Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_trusted_devices, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.
false_positives array[string]

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.
from string(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.
Hide investigation_fields attribute Show investigation_fields attribute object
- field_names array[string(nonempty)] Required
  
  A string that does not contain only whitespace characters
  
  At least 1 element. Minimum length of each is 1.
license string

The rule's license.
max_signals integer

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

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.

Minimum value is 1. Default value is 100.
meta object

Placeholder for metadata about the rule.

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

Additional properties are allowed.
name string Required

A human-readable name for the rule.

Minimum length is 1.
namespace string

Has no effect.
note string

Notes to help investigate alerts produced by the rule.
outcome string

Values are exactMatch, aliasMatch, or conflict.
output_index string Deprecated

(deprecated) Has no effect.
references array[string]

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.
related_integrations array[object]
Hide related_integrations attributes Show related_integrations attributes object
Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:
- package: name of the package (required, unique id)
- version: version of the package (required, semver-compatible)
- integration: name of the integration of this package (optional, id within the package)
There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.
- integration string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- package string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- version string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
required_fields array[object]

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

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.
Hide required_fields attributes Show required_fields attributes object
Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.
- name string(nonempty) Required
  
  Name of an Elasticsearch field
  
  Minimum length is 1.
- type string(nonempty) Required
  
  Type of the Elasticsearch field
  
  Minimum length is 1.
response_actions array[object]
One of:
.osquery object .endpoint object
Hide attributes Show attributes

action_type_id string Required Discriminator

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

To specify a query pack, use the packId field. Example: "packId": "processes_elastic"

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

id string Required

Query ID

platform string

query string Required

Query to run

removed boolean

snapshot boolean

version string

Query version

query string

To run a single query, use the query field and enter a SQL query. Example: "query": "SELECT * FROM processes;"

saved_query_id string

To run a saved query, use the saved_query_id field and specify the saved query ID. Example: "saved_query_id": "processes_elastic"

timeout number

A timeout period, in seconds, after which the query will stop running. Overwriting the default timeout allows you to support queries that require more time to complete. The default and minimum supported value is 60. The maximum supported value is 900. Example: "timeout": 120.
Hide attributes Show attributes

action_type_id string Required Discriminator

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object Security_Detections_API_RunscriptParams object

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.

This functionality is currently not available

Hide attributes Show attributes

command string Required

Value is runscript.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log

config object

Hide config attributes Show config attributes object

linux object

Hide linux attributes Show linux attributes object

scriptId string

scriptInput string

timeout integer

Specify the timeout in seconds for the script execution

macos object

Hide macos attributes Show macos attributes object

scriptId string

scriptInput string

timeout integer

Specify the timeout in seconds for the script execution

windows object

Hide windows attributes Show windows attributes object

scriptId string

scriptInput string

timeout integer

Specify the timeout in seconds for the script execution
risk_score integer 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
Minimum value is 0, maximum value is 100.
risk_score_mapping array[object]

Overrides generated alerts' risk_score with a value from the source event
Hide risk_score_mapping attributes Show risk_score_mapping attributes object
- field string Required
  
  Source event field used to override the default risk_score.
- operator string Required
  
  Value is equals.
- risk_score integer
  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
  Minimum value is 0, maximum value is 100.
- value string Required
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 string 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 are low, medium, high, or critical.
severity_mapping array[object]

Overrides generated alerts' severity with values from the source event
Hide severity_mapping attributes Show severity_mapping attributes object
- field string Required
  
  Source event field used to override the default severity.
- operator string Required
  
  Value is equals.
- severity string 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 are low, medium, high, or critical.
- value string Required
tags array[string]

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.
threat array[object]
Hide threat attributes Show threat attributes object
Currently, only threats described using the MITRE ATT&CK™ framework are supported.
- framework string Required
  
  Relevant attack framework
- tactic object Required
  
  Object containing information on the attack type
  Hide tactic attributes Show tactic attributes object
  
  id string Required
  
  Tactic ID
  
  name string Required
  
  Tactic name
  
  reference string Required
  
  Tactic reference
- technique array[object]
  
  Array containing information on the attack techniques (optional)
  Hide technique attributes Show technique attributes object
  
  id string Required
  
  Technique ID
  
  name string Required
  
  Technique name
  
  reference string Required
  
  Technique reference
  
  subtechnique array[object]
  
  Array containing more specific information on the attack technique.
  
  Hide subtechnique attributes Show subtechnique attributes object
  
  id string Required
  
  Subtechnique ID
  
  name string Required
  
  Subtechnique name
  
  reference string Required
  
  Subtechnique reference
throttle string

Defines how often rule actions are taken.

One of:
string-1 string string-2 string

Values are no_actions or rule.

Time interval in seconds, minutes, hours, or days.

Format should match the following pattern: ^[1-9]\d*[smhd]$.
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
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.
It is not incremented on each update. Compare this to the revision field.
Minimum value is 1.
language string Required

Value is 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.
type string Required

Rule type

Value is eql.
alert_suppression object

Defines alert suppression configuration.
Hide alert_suppression attributes Show alert_suppression attributes object
- duration object
  Hide duration attributes Show duration attributes object
  
  unit string Required
  
  Time unit
  
  Values are s, m, or h.
  
  value integer Required
  
  Minimum value is 1.
- group_by array[string] Required
  
  At least 1 but not more than 3 elements.
- missing_fields_strategy string
  
  Describes how alerts will be generated for documents with missing suppress by fields: doNotSuppress - per each document a separate alert will be created suppress - only alert will be created per suppress by bucket
  
  Values are doNotSuppress or suppress.
data_view_id string
event_category_override string
filters array

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

This field is not supported for ES|QL rules.
index array[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).

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(date-time) Required

actions array[object]

Array defining the automated actions (notifications) taken when alerts are generated.
Hide actions attributes Show actions attributes object
- action_type_id string Required
  The action type used for sending notifications, can be:
  
  .slack
  
  .slack_api
  
  .email
  
  .index
  
  .pagerduty
  
  .swimlane
  
  .webhook
  
  .servicenow
  
  .servicenow-itom
  
  .servicenow-sir
  
  .jira
  
  .resilient
  
  .opsgenie
  
  .teams
  
  .torq
  
  .tines
  
  .d3security
- alerts_filter object
  Object containing an action’s conditional filters.
  
  timeframe (object, optional): Object containing the time frame for when this action can be run.
  
  days (array of integers, required): List of days of the week on which this action will be run. Days of the week are expressed as numbers between 1-7, where 1 is Monday and 7 is Sunday. To select all days of the week, enter an empty array.
  
  hours (object, required): The hours of the day during which this action will run. Hours of the day are expressed as two strings in the format hh:mm in 24 hour time. A start of 00:00 and an end of 24:00 means the action can run all day.
  
  start (string, required): Start time in hh:mm format.
  
  end (string, required): End time in hh:mm format.
  
  timezone (string, required): An ISO timezone name, such as Europe/Madrid or America/New_York. Specific offsets such as UTC or UTC+1 will also work, but lack built-in DST.
  
  query (object, optional): Object containing a query filter which gets applied to an action and determines whether the action should run.
  
  kql (string, required): A KQL string.
  
  filters (array of objects, required): Array of filter objects, as defined in the kbn-es-query package.
  Additional properties are allowed.
- frequency object
  
  The action frequency defines when the action runs (for example, only on rule execution or at specific time intervals).
  Hide frequency attributes Show frequency attributes object
  
  notifyWhen string Required
  
  Defines how often rules run actions.
  
  Values are onActiveAlert, onThrottleInterval, or onActionGroupChange.
  
  summary boolean Required
  
  Action summary indicates whether we will send a summary notification about all the generate alerts or notification per individual alert
  
  throttle string Required
  
  Defines how often rule actions are taken.
  
  One of:
  string-1 string string-2 string
  
  Values are no_actions or rule.
  
  Time interval in seconds, minutes, hours, or days.
  
  Format should match the following pattern: ^[1-9]\d*[smhd]$.
- group string
  
  Optionally groups actions by use cases. Use default for alert notifications.
- id string Required
  
  The connector ID.
- params object Required
  Object containing the allowed connector fields, which varies according to the connector type.
  
  For Slack:
  
  message (string, required): The notification message.
  
  For email:
  
  to, cc, bcc (string): Email addresses to which the notifications are sent. At least one field must have a value.
  
  subject (string, optional): Email subject line.
  
  message (string, required): Email body text.
  
  For Webhook:
  
  body (string, required): JSON payload.
  
  For PagerDuty:
  
  severity (string, required): Severity of on the alert notification, can be: Critical, Error, Warning or Info.
  
  eventAction (string, required): Event action type, which can be trigger, resolve, or acknowledge.
  
  dedupKey (string, optional): Groups alert notifications with the same PagerDuty alert.
  
  timestamp (DateTime, optional): ISO-8601 format timestamp.
  
  component (string, optional): Source machine component responsible for the event, for example security-solution.
  
  group (string, optional): Enables logical grouping of service components.
  
  source (string, optional): The affected system. Defaults to the Kibana saved object ID of the action.
  
  summary (string, options): Summary of the event. Defaults to No summary provided. Maximum length is 1024 characters.
  
  class (string, optional): Value indicating the class/type of the event.
  Additional properties are allowed.
- uuid string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
alias_purpose string

Values are savedObjectConversion or savedObjectImport.
alias_target_id string
author array[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 Required

The rule’s description.

Minimum length is 1.
enabled boolean

Determines whether the rule is enabled. Defaults to true.
exceptions_list array[object]
Hide exceptions_list attributes Show exceptions_list attributes object
Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.
- id string(nonempty) Required
  
  ID of the exception container
  
  Minimum length is 1.
- list_id string(nonempty) Required
  
  List ID of the exception container
  
  Minimum length is 1.
- namespace_type string Required
  
  Determines the exceptions validity in rule's Kibana space
  
  Values are agnostic or single.
- type string Required
  
  The exception type
  
  Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_trusted_devices, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.
false_positives array[string]

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.
from string(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.
Hide investigation_fields attribute Show investigation_fields attribute object
- field_names array[string(nonempty)] Required
  
  A string that does not contain only whitespace characters
  
  At least 1 element. Minimum length of each is 1.
license string

The rule's license.
max_signals integer

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

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.

Minimum value is 1. Default value is 100.
meta object

Placeholder for metadata about the rule.

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

Additional properties are allowed.
name string Required

A human-readable name for the rule.

Minimum length is 1.
namespace string

Has no effect.
note string

Notes to help investigate alerts produced by the rule.
outcome string

Values are exactMatch, aliasMatch, or conflict.
output_index string Deprecated

(deprecated) Has no effect.
references array[string]

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.
related_integrations array[object]
Hide related_integrations attributes Show related_integrations attributes object
Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:
- package: name of the package (required, unique id)
- version: version of the package (required, semver-compatible)
- integration: name of the integration of this package (optional, id within the package)
There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.
- integration string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- package string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- version string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
required_fields array[object]

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

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.
Hide required_fields attributes Show required_fields attributes object
Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.
- name string(nonempty) Required
  
  Name of an Elasticsearch field
  
  Minimum length is 1.
- type string(nonempty) Required
  
  Type of the Elasticsearch field
  
  Minimum length is 1.
response_actions array[object]
One of:
.osquery object .endpoint object
Hide attributes Show attributes

action_type_id string Required Discriminator

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

To specify a query pack, use the packId field. Example: "packId": "processes_elastic"

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

id string Required

Query ID

platform string

query string Required

Query to run

removed boolean

snapshot boolean

version string

Query version

query string

To run a single query, use the query field and enter a SQL query. Example: "query": "SELECT * FROM processes;"

saved_query_id string

To run a saved query, use the saved_query_id field and specify the saved query ID. Example: "saved_query_id": "processes_elastic"

timeout number

A timeout period, in seconds, after which the query will stop running. Overwriting the default timeout allows you to support queries that require more time to complete. The default and minimum supported value is 60. The maximum supported value is 900. Example: "timeout": 120.
Hide attributes Show attributes

action_type_id string Required Discriminator

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object Security_Detections_API_RunscriptParams object

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.

This functionality is currently not available

Hide attributes Show attributes

command string Required

Value is runscript.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log

config object

Hide config attributes Show config attributes object

linux object

Hide linux attributes Show linux attributes object

scriptId string

scriptInput string

timeout integer

Specify the timeout in seconds for the script execution

macos object

Hide macos attributes Show macos attributes object

scriptId string

scriptInput string

timeout integer

Specify the timeout in seconds for the script execution

windows object

Hide windows attributes Show windows attributes object

scriptId string

scriptInput string

timeout integer

Specify the timeout in seconds for the script execution
risk_score integer 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
Minimum value is 0, maximum value is 100.
risk_score_mapping array[object]

Overrides generated alerts' risk_score with a value from the source event
Hide risk_score_mapping attributes Show risk_score_mapping attributes object
- field string Required
  
  Source event field used to override the default risk_score.
- operator string Required
  
  Value is equals.
- risk_score integer
  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
  Minimum value is 0, maximum value is 100.
- value string Required
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 string 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 are low, medium, high, or critical.
severity_mapping array[object]

Overrides generated alerts' severity with values from the source event
Hide severity_mapping attributes Show severity_mapping attributes object
- field string Required
  
  Source event field used to override the default severity.
- operator string Required
  
  Value is equals.
- severity string 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 are low, medium, high, or critical.
- value string Required
tags array[string]

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.
threat array[object]
Hide threat attributes Show threat attributes object
Currently, only threats described using the MITRE ATT&CK™ framework are supported.
- framework string Required
  
  Relevant attack framework
- tactic object Required
  
  Object containing information on the attack type
  Hide tactic attributes Show tactic attributes object
  
  id string Required
  
  Tactic ID
  
  name string Required
  
  Tactic name
  
  reference string Required
  
  Tactic reference
- technique array[object]
  
  Array containing information on the attack techniques (optional)
  Hide technique attributes Show technique attributes object
  
  id string Required
  
  Technique ID
  
  name string Required
  
  Technique name
  
  reference string Required
  
  Technique reference
  
  subtechnique array[object]
  
  Array containing more specific information on the attack technique.
  
  Hide subtechnique attributes Show subtechnique attributes object
  
  id string Required
  
  Subtechnique ID
  
  name string Required
  
  Subtechnique name
  
  reference string Required
  
  Subtechnique reference
throttle string

Defines how often rule actions are taken.

One of:
string-1 string string-2 string

Values are no_actions or rule.

Time interval in seconds, minutes, hours, or days.

Format should match the following pattern: ^[1-9]\d*[smhd]$.
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
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.
It is not incremented on each update. Compare this to the revision field.
Minimum value is 1.
type string Required

Rule type

Value is query.
alert_suppression object

Defines alert suppression configuration.
Hide alert_suppression attributes Show alert_suppression attributes object
- duration object
  Hide duration attributes Show duration attributes object
  
  unit string Required
  
  Time unit
  
  Values are s, m, or h.
  
  value integer Required
  
  Minimum value is 1.
- group_by array[string] Required
  
  At least 1 but not more than 3 elements.
- missing_fields_strategy string
  
  Describes how alerts will be generated for documents with missing suppress by fields: doNotSuppress - per each document a separate alert will be created suppress - only alert will be created per suppress by bucket
  
  Values are doNotSuppress or suppress.
data_view_id string
filters array

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

This field is not supported for ES|QL rules.
index array[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).

This field is not supported for ES|QL rules.
saved_id string

Kibana saved search used by the rule to create alerts.
language string

Values are kuery or 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(date-time) Required

actions array[object]

Array defining the automated actions (notifications) taken when alerts are generated.
Hide actions attributes Show actions attributes object
- action_type_id string Required
  The action type used for sending notifications, can be:
  
  .slack
  
  .slack_api
  
  .email
  
  .index
  
  .pagerduty
  
  .swimlane
  
  .webhook
  
  .servicenow
  
  .servicenow-itom
  
  .servicenow-sir
  
  .jira
  
  .resilient
  
  .opsgenie
  
  .teams
  
  .torq
  
  .tines
  
  .d3security
- alerts_filter object
  Object containing an action’s conditional filters.
  
  timeframe (object, optional): Object containing the time frame for when this action can be run.
  
  days (array of integers, required): List of days of the week on which this action will be run. Days of the week are expressed as numbers between 1-7, where 1 is Monday and 7 is Sunday. To select all days of the week, enter an empty array.
  
  hours (object, required): The hours of the day during which this action will run. Hours of the day are expressed as two strings in the format hh:mm in 24 hour time. A start of 00:00 and an end of 24:00 means the action can run all day.
  
  start (string, required): Start time in hh:mm format.
  
  end (string, required): End time in hh:mm format.
  
  timezone (string, required): An ISO timezone name, such as Europe/Madrid or America/New_York. Specific offsets such as UTC or UTC+1 will also work, but lack built-in DST.
  
  query (object, optional): Object containing a query filter which gets applied to an action and determines whether the action should run.
  
  kql (string, required): A KQL string.
  
  filters (array of objects, required): Array of filter objects, as defined in the kbn-es-query package.
  Additional properties are allowed.
- frequency object
  
  The action frequency defines when the action runs (for example, only on rule execution or at specific time intervals).
  Hide frequency attributes Show frequency attributes object
  
  notifyWhen string Required
  
  Defines how often rules run actions.
  
  Values are onActiveAlert, onThrottleInterval, or onActionGroupChange.
  
  summary boolean Required
  
  Action summary indicates whether we will send a summary notification about all the generate alerts or notification per individual alert
  
  throttle string Required
  
  Defines how often rule actions are taken.
  
  One of:
  string-1 string string-2 string
  
  Values are no_actions or rule.
  
  Time interval in seconds, minutes, hours, or days.
  
  Format should match the following pattern: ^[1-9]\d*[smhd]$.
- group string
  
  Optionally groups actions by use cases. Use default for alert notifications.
- id string Required
  
  The connector ID.
- params object Required
  Object containing the allowed connector fields, which varies according to the connector type.
  
  For Slack:
  
  message (string, required): The notification message.
  
  For email:
  
  to, cc, bcc (string): Email addresses to which the notifications are sent. At least one field must have a value.
  
  subject (string, optional): Email subject line.
  
  message (string, required): Email body text.
  
  For Webhook:
  
  body (string, required): JSON payload.
  
  For PagerDuty:
  
  severity (string, required): Severity of on the alert notification, can be: Critical, Error, Warning or Info.
  
  eventAction (string, required): Event action type, which can be trigger, resolve, or acknowledge.
  
  dedupKey (string, optional): Groups alert notifications with the same PagerDuty alert.
  
  timestamp (DateTime, optional): ISO-8601 format timestamp.
  
  component (string, optional): Source machine component responsible for the event, for example security-solution.
  
  group (string, optional): Enables logical grouping of service components.
  
  source (string, optional): The affected system. Defaults to the Kibana saved object ID of the action.
  
  summary (string, options): Summary of the event. Defaults to No summary provided. Maximum length is 1024 characters.
  
  class (string, optional): Value indicating the class/type of the event.
  Additional properties are allowed.
- uuid string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
alias_purpose string

Values are savedObjectConversion or savedObjectImport.
alias_target_id string
author array[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 Required

The rule’s description.

Minimum length is 1.
enabled boolean

Determines whether the rule is enabled. Defaults to true.
exceptions_list array[object]
Hide exceptions_list attributes Show exceptions_list attributes object
Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.
- id string(nonempty) Required
  
  ID of the exception container
  
  Minimum length is 1.
- list_id string(nonempty) Required
  
  List ID of the exception container
  
  Minimum length is 1.
- namespace_type string Required
  
  Determines the exceptions validity in rule's Kibana space
  
  Values are agnostic or single.
- type string Required
  
  The exception type
  
  Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_trusted_devices, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.
false_positives array[string]

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.
from string(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.
Hide investigation_fields attribute Show investigation_fields attribute object
- field_names array[string(nonempty)] Required
  
  A string that does not contain only whitespace characters
  
  At least 1 element. Minimum length of each is 1.
license string

The rule's license.
max_signals integer

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

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.

Minimum value is 1. Default value is 100.
meta object

Placeholder for metadata about the rule.

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

Additional properties are allowed.
name string Required

A human-readable name for the rule.

Minimum length is 1.
namespace string

Has no effect.
note string

Notes to help investigate alerts produced by the rule.
outcome string

Values are exactMatch, aliasMatch, or conflict.
output_index string Deprecated

(deprecated) Has no effect.
references array[string]

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.
related_integrations array[object]
Hide related_integrations attributes Show related_integrations attributes object
Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:
- package: name of the package (required, unique id)
- version: version of the package (required, semver-compatible)
- integration: name of the integration of this package (optional, id within the package)
There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.
- integration string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- package string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- version string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
required_fields array[object]

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

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.
Hide required_fields attributes Show required_fields attributes object
Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.
- name string(nonempty) Required
  
  Name of an Elasticsearch field
  
  Minimum length is 1.
- type string(nonempty) Required
  
  Type of the Elasticsearch field
  
  Minimum length is 1.
response_actions array[object]
One of:
.osquery object .endpoint object
Hide attributes Show attributes

action_type_id string Required Discriminator

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

To specify a query pack, use the packId field. Example: "packId": "processes_elastic"

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

id string Required

Query ID

platform string

query string Required

Query to run

removed boolean

snapshot boolean

version string

Query version

query string

To run a single query, use the query field and enter a SQL query. Example: "query": "SELECT * FROM processes;"

saved_query_id string

To run a saved query, use the saved_query_id field and specify the saved query ID. Example: "saved_query_id": "processes_elastic"

timeout number

A timeout period, in seconds, after which the query will stop running. Overwriting the default timeout allows you to support queries that require more time to complete. The default and minimum supported value is 60. The maximum supported value is 900. Example: "timeout": 120.
Hide attributes Show attributes

action_type_id string Required Discriminator

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object Security_Detections_API_RunscriptParams object

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.

This functionality is currently not available

Hide attributes Show attributes

command string Required

Value is runscript.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log

config object

Hide config attributes Show config attributes object

linux object

Hide linux attributes Show linux attributes object

scriptId string

scriptInput string

timeout integer

Specify the timeout in seconds for the script execution

macos object

Hide macos attributes Show macos attributes object

scriptId string

scriptInput string

timeout integer

Specify the timeout in seconds for the script execution

windows object

Hide windows attributes Show windows attributes object

scriptId string

scriptInput string

timeout integer

Specify the timeout in seconds for the script execution
risk_score integer 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
Minimum value is 0, maximum value is 100.
risk_score_mapping array[object]

Overrides generated alerts' risk_score with a value from the source event
Hide risk_score_mapping attributes Show risk_score_mapping attributes object
- field string Required
  
  Source event field used to override the default risk_score.
- operator string Required
  
  Value is equals.
- risk_score integer
  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
  Minimum value is 0, maximum value is 100.
- value string Required
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 string 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 are low, medium, high, or critical.
severity_mapping array[object]

Overrides generated alerts' severity with values from the source event
Hide severity_mapping attributes Show severity_mapping attributes object
- field string Required
  
  Source event field used to override the default severity.
- operator string Required
  
  Value is equals.
- severity string 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 are low, medium, high, or critical.
- value string Required
tags array[string]

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.
threat array[object]
Hide threat attributes Show threat attributes object
Currently, only threats described using the MITRE ATT&CK™ framework are supported.
- framework string Required
  
  Relevant attack framework
- tactic object Required
  
  Object containing information on the attack type
  Hide tactic attributes Show tactic attributes object
  
  id string Required
  
  Tactic ID
  
  name string Required
  
  Tactic name
  
  reference string Required
  
  Tactic reference
- technique array[object]
  
  Array containing information on the attack techniques (optional)
  Hide technique attributes Show technique attributes object
  
  id string Required
  
  Technique ID
  
  name string Required
  
  Technique name
  
  reference string Required
  
  Technique reference
  
  subtechnique array[object]
  
  Array containing more specific information on the attack technique.
  
  Hide subtechnique attributes Show subtechnique attributes object
  
  id string Required
  
  Subtechnique ID
  
  name string Required
  
  Subtechnique name
  
  reference string Required
  
  Subtechnique reference
throttle string

Defines how often rule actions are taken.

One of:
string-1 string string-2 string

Values are no_actions or rule.

Time interval in seconds, minutes, hours, or days.

Format should match the following pattern: ^[1-9]\d*[smhd]$.
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
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.
It is not incremented on each update. Compare this to the revision field.
Minimum value is 1.
saved_id string Required

Kibana saved search used by the rule to create alerts.
type string Required

Rule type

Value is saved_query.
alert_suppression object

Defines alert suppression configuration.
Hide alert_suppression attributes Show alert_suppression attributes object
- duration object
  Hide duration attributes Show duration attributes object
  
  unit string Required
  
  Time unit
  
  Values are s, m, or h.
  
  value integer Required
  
  Minimum value is 1.
- group_by array[string] Required
  
  At least 1 but not more than 3 elements.
- missing_fields_strategy string
  
  Describes how alerts will be generated for documents with missing suppress by fields: doNotSuppress - per each document a separate alert will be created suppress - only alert will be created per suppress by bucket
  
  Values are doNotSuppress or suppress.
data_view_id string
filters array

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

This field is not supported for ES|QL rules.
index array[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).

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 string

Values are kuery or lucene.
invocationCount integer Required
timeframeEnd string(date-time) Required

actions array[object]

Array defining the automated actions (notifications) taken when alerts are generated.
Hide actions attributes Show actions attributes object
- action_type_id string Required
  The action type used for sending notifications, can be:
  
  .slack
  
  .slack_api
  
  .email
  
  .index
  
  .pagerduty
  
  .swimlane
  
  .webhook
  
  .servicenow
  
  .servicenow-itom
  
  .servicenow-sir
  
  .jira
  
  .resilient
  
  .opsgenie
  
  .teams
  
  .torq
  
  .tines
  
  .d3security
- alerts_filter object
  Object containing an action’s conditional filters.
  
  timeframe (object, optional): Object containing the time frame for when this action can be run.
  
  days (array of integers, required): List of days of the week on which this action will be run. Days of the week are expressed as numbers between 1-7, where 1 is Monday and 7 is Sunday. To select all days of the week, enter an empty array.
  
  hours (object, required): The hours of the day during which this action will run. Hours of the day are expressed as two strings in the format hh:mm in 24 hour time. A start of 00:00 and an end of 24:00 means the action can run all day.
  
  start (string, required): Start time in hh:mm format.
  
  end (string, required): End time in hh:mm format.
  
  timezone (string, required): An ISO timezone name, such as Europe/Madrid or America/New_York. Specific offsets such as UTC or UTC+1 will also work, but lack built-in DST.
  
  query (object, optional): Object containing a query filter which gets applied to an action and determines whether the action should run.
  
  kql (string, required): A KQL string.
  
  filters (array of objects, required): Array of filter objects, as defined in the kbn-es-query package.
  Additional properties are allowed.
- frequency object
  
  The action frequency defines when the action runs (for example, only on rule execution or at specific time intervals).
  Hide frequency attributes Show frequency attributes object
  
  notifyWhen string Required
  
  Defines how often rules run actions.
  
  Values are onActiveAlert, onThrottleInterval, or onActionGroupChange.
  
  summary boolean Required
  
  Action summary indicates whether we will send a summary notification about all the generate alerts or notification per individual alert
  
  throttle string Required
  
  Defines how often rule actions are taken.
  
  One of:
  string-1 string string-2 string
  
  Values are no_actions or rule.
  
  Time interval in seconds, minutes, hours, or days.
  
  Format should match the following pattern: ^[1-9]\d*[smhd]$.
- group string
  
  Optionally groups actions by use cases. Use default for alert notifications.
- id string Required
  
  The connector ID.
- params object Required
  Object containing the allowed connector fields, which varies according to the connector type.
  
  For Slack:
  
  message (string, required): The notification message.
  
  For email:
  
  to, cc, bcc (string): Email addresses to which the notifications are sent. At least one field must have a value.
  
  subject (string, optional): Email subject line.
  
  message (string, required): Email body text.
  
  For Webhook:
  
  body (string, required): JSON payload.
  
  For PagerDuty:
  
  severity (string, required): Severity of on the alert notification, can be: Critical, Error, Warning or Info.
  
  eventAction (string, required): Event action type, which can be trigger, resolve, or acknowledge.
  
  dedupKey (string, optional): Groups alert notifications with the same PagerDuty alert.
  
  timestamp (DateTime, optional): ISO-8601 format timestamp.
  
  component (string, optional): Source machine component responsible for the event, for example security-solution.
  
  group (string, optional): Enables logical grouping of service components.
  
  source (string, optional): The affected system. Defaults to the Kibana saved object ID of the action.
  
  summary (string, options): Summary of the event. Defaults to No summary provided. Maximum length is 1024 characters.
  
  class (string, optional): Value indicating the class/type of the event.
  Additional properties are allowed.
- uuid string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
alias_purpose string

Values are savedObjectConversion or savedObjectImport.
alias_target_id string
author array[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 Required

The rule’s description.

Minimum length is 1.
enabled boolean

Determines whether the rule is enabled. Defaults to true.
exceptions_list array[object]
Hide exceptions_list attributes Show exceptions_list attributes object
Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.
- id string(nonempty) Required
  
  ID of the exception container
  
  Minimum length is 1.
- list_id string(nonempty) Required
  
  List ID of the exception container
  
  Minimum length is 1.
- namespace_type string Required
  
  Determines the exceptions validity in rule's Kibana space
  
  Values are agnostic or single.
- type string Required
  
  The exception type
  
  Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_trusted_devices, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.
false_positives array[string]

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.
from string(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.
Hide investigation_fields attribute Show investigation_fields attribute object
- field_names array[string(nonempty)] Required
  
  A string that does not contain only whitespace characters
  
  At least 1 element. Minimum length of each is 1.
license string

The rule's license.
max_signals integer

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

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.

Minimum value is 1. Default value is 100.
meta object

Placeholder for metadata about the rule.

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

Additional properties are allowed.
name string Required

A human-readable name for the rule.

Minimum length is 1.
namespace string

Has no effect.
note string

Notes to help investigate alerts produced by the rule.
outcome string

Values are exactMatch, aliasMatch, or conflict.
output_index string Deprecated

(deprecated) Has no effect.
references array[string]

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.
related_integrations array[object]
Hide related_integrations attributes Show related_integrations attributes object
Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:
- package: name of the package (required, unique id)
- version: version of the package (required, semver-compatible)
- integration: name of the integration of this package (optional, id within the package)
There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.
- integration string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- package string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- version string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
required_fields array[object]

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

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.
Hide required_fields attributes Show required_fields attributes object
Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.
- name string(nonempty) Required
  
  Name of an Elasticsearch field
  
  Minimum length is 1.
- type string(nonempty) Required
  
  Type of the Elasticsearch field
  
  Minimum length is 1.
response_actions array[object]
One of:
.osquery object .endpoint object
Hide attributes Show attributes

action_type_id string Required Discriminator

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

To specify a query pack, use the packId field. Example: "packId": "processes_elastic"

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

id string Required

Query ID

platform string

query string Required

Query to run

removed boolean

snapshot boolean

version string

Query version

query string

To run a single query, use the query field and enter a SQL query. Example: "query": "SELECT * FROM processes;"

saved_query_id string

To run a saved query, use the saved_query_id field and specify the saved query ID. Example: "saved_query_id": "processes_elastic"

timeout number

A timeout period, in seconds, after which the query will stop running. Overwriting the default timeout allows you to support queries that require more time to complete. The default and minimum supported value is 60. The maximum supported value is 900. Example: "timeout": 120.
Hide attributes Show attributes

action_type_id string Required Discriminator

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object Security_Detections_API_RunscriptParams object

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.

This functionality is currently not available

Hide attributes Show attributes

command string Required

Value is runscript.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log

config object

Hide config attributes Show config attributes object

linux object

Hide linux attributes Show linux attributes object

scriptId string

scriptInput string

timeout integer

Specify the timeout in seconds for the script execution

macos object

Hide macos attributes Show macos attributes object

scriptId string

scriptInput string

timeout integer

Specify the timeout in seconds for the script execution

windows object

Hide windows attributes Show windows attributes object

scriptId string

scriptInput string

timeout integer

Specify the timeout in seconds for the script execution
risk_score integer 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
Minimum value is 0, maximum value is 100.
risk_score_mapping array[object]

Overrides generated alerts' risk_score with a value from the source event
Hide risk_score_mapping attributes Show risk_score_mapping attributes object
- field string Required
  
  Source event field used to override the default risk_score.
- operator string Required
  
  Value is equals.
- risk_score integer
  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
  Minimum value is 0, maximum value is 100.
- value string Required
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 string 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 are low, medium, high, or critical.
severity_mapping array[object]

Overrides generated alerts' severity with values from the source event
Hide severity_mapping attributes Show severity_mapping attributes object
- field string Required
  
  Source event field used to override the default severity.
- operator string Required
  
  Value is equals.
- severity string 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 are low, medium, high, or critical.
- value string Required
tags array[string]

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.
threat array[object]
Hide threat attributes Show threat attributes object
Currently, only threats described using the MITRE ATT&CK™ framework are supported.
- framework string Required
  
  Relevant attack framework
- tactic object Required
  
  Object containing information on the attack type
  Hide tactic attributes Show tactic attributes object
  
  id string Required
  
  Tactic ID
  
  name string Required
  
  Tactic name
  
  reference string Required
  
  Tactic reference
- technique array[object]
  
  Array containing information on the attack techniques (optional)
  Hide technique attributes Show technique attributes object
  
  id string Required
  
  Technique ID
  
  name string Required
  
  Technique name
  
  reference string Required
  
  Technique reference
  
  subtechnique array[object]
  
  Array containing more specific information on the attack technique.
  
  Hide subtechnique attributes Show subtechnique attributes object
  
  id string Required
  
  Subtechnique ID
  
  name string Required
  
  Subtechnique name
  
  reference string Required
  
  Subtechnique reference
throttle string

Defines how often rule actions are taken.

One of:
string-1 string string-2 string

Values are no_actions or rule.

Time interval in seconds, minutes, hours, or days.

Format should match the following pattern: ^[1-9]\d*[smhd]$.
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
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.
It is not incremented on each update. Compare this to the revision field.
Minimum value is 1.
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
Hide threshold attributes Show threshold attributes object
- cardinality array[object]
  
  The field on which the cardinality is applied.
  Hide cardinality attributes Show cardinality attributes object
  
  field string Required
  
  The field on which to calculate and compare the cardinality.
  
  value integer Required
  
  The threshold value from which an alert is generated based on unique number of values of cardinality.field.
  
  Minimum value is 0.
- field string | array[string] Required
  
  The field on which the threshold is applied. If you specify an empty array ([]), alerts are generated when the query returns at least the number of results specified in the value field.
  
  One of:
  string-1 string array-2 array[string]
  
  At least 0 but not more than 5 elements.
- value integer Required
  
  The threshold value from which an alert is generated.
  
  Minimum value is 1.
type string Required

Rule type

Value is threshold.
alert_suppression object

Defines alert suppression configuration.
Hide alert_suppression attribute Show alert_suppression attribute object
- duration object Required
  Hide duration attributes Show duration attributes object
  
  unit string Required
  
  Time unit
  
  Values are s, m, or h.
  
  value integer Required
  
  Minimum value is 1.
data_view_id string
filters array

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

This field is not supported for ES|QL rules.
index array[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).

This field is not supported for ES|QL rules.
saved_id string

Kibana saved search used by the rule to create alerts.
language string

Values are kuery or lucene.
invocationCount integer Required
timeframeEnd string(date-time) Required

actions array[object]

Array defining the automated actions (notifications) taken when alerts are generated.
Hide actions attributes Show actions attributes object
- action_type_id string Required
  The action type used for sending notifications, can be:
  
  .slack
  
  .slack_api
  
  .email
  
  .index
  
  .pagerduty
  
  .swimlane
  
  .webhook
  
  .servicenow
  
  .servicenow-itom
  
  .servicenow-sir
  
  .jira
  
  .resilient
  
  .opsgenie
  
  .teams
  
  .torq
  
  .tines
  
  .d3security
- alerts_filter object
  Object containing an action’s conditional filters.
  
  timeframe (object, optional): Object containing the time frame for when this action can be run.
  
  days (array of integers, required): List of days of the week on which this action will be run. Days of the week are expressed as numbers between 1-7, where 1 is Monday and 7 is Sunday. To select all days of the week, enter an empty array.
  
  hours (object, required): The hours of the day during which this action will run. Hours of the day are expressed as two strings in the format hh:mm in 24 hour time. A start of 00:00 and an end of 24:00 means the action can run all day.
  
  start (string, required): Start time in hh:mm format.
  
  end (string, required): End time in hh:mm format.
  
  timezone (string, required): An ISO timezone name, such as Europe/Madrid or America/New_York. Specific offsets such as UTC or UTC+1 will also work, but lack built-in DST.
  
  query (object, optional): Object containing a query filter which gets applied to an action and determines whether the action should run.
  
  kql (string, required): A KQL string.
  
  filters (array of objects, required): Array of filter objects, as defined in the kbn-es-query package.
  Additional properties are allowed.
- frequency object
  
  The action frequency defines when the action runs (for example, only on rule execution or at specific time intervals).
  Hide frequency attributes Show frequency attributes object
  
  notifyWhen string Required
  
  Defines how often rules run actions.
  
  Values are onActiveAlert, onThrottleInterval, or onActionGroupChange.
  
  summary boolean Required
  
  Action summary indicates whether we will send a summary notification about all the generate alerts or notification per individual alert
  
  throttle string Required
  
  Defines how often rule actions are taken.
  
  One of:
  string-1 string string-2 string
  
  Values are no_actions or rule.
  
  Time interval in seconds, minutes, hours, or days.
  
  Format should match the following pattern: ^[1-9]\d*[smhd]$.
- group string
  
  Optionally groups actions by use cases. Use default for alert notifications.
- id string Required
  
  The connector ID.
- params object Required
  Object containing the allowed connector fields, which varies according to the connector type.
  
  For Slack:
  
  message (string, required): The notification message.
  
  For email:
  
  to, cc, bcc (string): Email addresses to which the notifications are sent. At least one field must have a value.
  
  subject (string, optional): Email subject line.
  
  message (string, required): Email body text.
  
  For Webhook:
  
  body (string, required): JSON payload.
  
  For PagerDuty:
  
  severity (string, required): Severity of on the alert notification, can be: Critical, Error, Warning or Info.
  
  eventAction (string, required): Event action type, which can be trigger, resolve, or acknowledge.
  
  dedupKey (string, optional): Groups alert notifications with the same PagerDuty alert.
  
  timestamp (DateTime, optional): ISO-8601 format timestamp.
  
  component (string, optional): Source machine component responsible for the event, for example security-solution.
  
  group (string, optional): Enables logical grouping of service components.
  
  source (string, optional): The affected system. Defaults to the Kibana saved object ID of the action.
  
  summary (string, options): Summary of the event. Defaults to No summary provided. Maximum length is 1024 characters.
  
  class (string, optional): Value indicating the class/type of the event.
  Additional properties are allowed.
- uuid string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
alias_purpose string

Values are savedObjectConversion or savedObjectImport.
alias_target_id string
author array[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 Required

The rule’s description.

Minimum length is 1.
enabled boolean

Determines whether the rule is enabled. Defaults to true.
exceptions_list array[object]
Hide exceptions_list attributes Show exceptions_list attributes object
Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.
- id string(nonempty) Required
  
  ID of the exception container
  
  Minimum length is 1.
- list_id string(nonempty) Required
  
  List ID of the exception container
  
  Minimum length is 1.
- namespace_type string Required
  
  Determines the exceptions validity in rule's Kibana space
  
  Values are agnostic or single.
- type string Required
  
  The exception type
  
  Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_trusted_devices, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.
false_positives array[string]

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.
from string(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.
Hide investigation_fields attribute Show investigation_fields attribute object
- field_names array[string(nonempty)] Required
  
  A string that does not contain only whitespace characters
  
  At least 1 element. Minimum length of each is 1.
license string

The rule's license.
max_signals integer

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

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.

Minimum value is 1. Default value is 100.
meta object

Placeholder for metadata about the rule.

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

Additional properties are allowed.
name string Required

A human-readable name for the rule.

Minimum length is 1.
namespace string

Has no effect.
note string

Notes to help investigate alerts produced by the rule.
outcome string

Values are exactMatch, aliasMatch, or conflict.
output_index string Deprecated

(deprecated) Has no effect.
references array[string]

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.
related_integrations array[object]
Hide related_integrations attributes Show related_integrations attributes object
Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:
- package: name of the package (required, unique id)
- version: version of the package (required, semver-compatible)
- integration: name of the integration of this package (optional, id within the package)
There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.
- integration string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- package string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- version string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
required_fields array[object]

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

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.
Hide required_fields attributes Show required_fields attributes object
Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.
- name string(nonempty) Required
  
  Name of an Elasticsearch field
  
  Minimum length is 1.
- type string(nonempty) Required
  
  Type of the Elasticsearch field
  
  Minimum length is 1.
response_actions array[object]
One of:
.osquery object .endpoint object
Hide attributes Show attributes

action_type_id string Required Discriminator

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

To specify a query pack, use the packId field. Example: "packId": "processes_elastic"

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

id string Required

Query ID

platform string

query string Required

Query to run

removed boolean

snapshot boolean

version string

Query version

query string

To run a single query, use the query field and enter a SQL query. Example: "query": "SELECT * FROM processes;"

saved_query_id string

To run a saved query, use the saved_query_id field and specify the saved query ID. Example: "saved_query_id": "processes_elastic"

timeout number

A timeout period, in seconds, after which the query will stop running. Overwriting the default timeout allows you to support queries that require more time to complete. The default and minimum supported value is 60. The maximum supported value is 900. Example: "timeout": 120.
Hide attributes Show attributes

action_type_id string Required Discriminator

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object Security_Detections_API_RunscriptParams object

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.

This functionality is currently not available

Hide attributes Show attributes

command string Required

Value is runscript.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log

config object

Hide config attributes Show config attributes object

linux object

Hide linux attributes Show linux attributes object

scriptId string

scriptInput string

timeout integer

Specify the timeout in seconds for the script execution

macos object

Hide macos attributes Show macos attributes object

scriptId string

scriptInput string

timeout integer

Specify the timeout in seconds for the script execution

windows object

Hide windows attributes Show windows attributes object

scriptId string

scriptInput string

timeout integer

Specify the timeout in seconds for the script execution
risk_score integer 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
Minimum value is 0, maximum value is 100.
risk_score_mapping array[object]

Overrides generated alerts' risk_score with a value from the source event
Hide risk_score_mapping attributes Show risk_score_mapping attributes object
- field string Required
  
  Source event field used to override the default risk_score.
- operator string Required
  
  Value is equals.
- risk_score integer
  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
  Minimum value is 0, maximum value is 100.
- value string Required
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 string 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 are low, medium, high, or critical.
severity_mapping array[object]

Overrides generated alerts' severity with values from the source event
Hide severity_mapping attributes Show severity_mapping attributes object
- field string Required
  
  Source event field used to override the default severity.
- operator string Required
  
  Value is equals.
- severity string 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 are low, medium, high, or critical.
- value string Required
tags array[string]

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.
threat array[object]
Hide threat attributes Show threat attributes object
Currently, only threats described using the MITRE ATT&CK™ framework are supported.
- framework string Required
  
  Relevant attack framework
- tactic object Required
  
  Object containing information on the attack type
  Hide tactic attributes Show tactic attributes object
  
  id string Required
  
  Tactic ID
  
  name string Required
  
  Tactic name
  
  reference string Required
  
  Tactic reference
- technique array[object]
  
  Array containing information on the attack techniques (optional)
  Hide technique attributes Show technique attributes object
  
  id string Required
  
  Technique ID
  
  name string Required
  
  Technique name
  
  reference string Required
  
  Technique reference
  
  subtechnique array[object]
  
  Array containing more specific information on the attack technique.
  
  Hide subtechnique attributes Show subtechnique attributes object
  
  id string Required
  
  Subtechnique ID
  
  name string Required
  
  Subtechnique name
  
  reference string Required
  
  Subtechnique reference
throttle string

Defines how often rule actions are taken.

One of:
string-1 string string-2 string

Values are no_actions or rule.

Time interval in seconds, minutes, hours, or days.

Format should match the following pattern: ^[1-9]\d*[smhd]$.
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
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.
It is not incremented on each update. Compare this to the revision field.
Minimum value is 1.
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 array[string] Required

Elasticsearch indices used to check which field values generate alerts.
threat_mapping array[object] 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.
At least 1 element.
Hide threat_mapping attribute Show threat_mapping attribute object
- entries array[object] Required
  Hide entries attributes Show entries attributes object
  
  field string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  negate boolean
  
  type string Required
  
  Value is mapping.
  
  value string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
threat_query string Required

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

Rule type

Value is threat_match.
alert_suppression object

Defines alert suppression configuration.
Hide alert_suppression attributes Show alert_suppression attributes object
- duration object
  Hide duration attributes Show duration attributes object
  
  unit string Required
  
  Time unit
  
  Values are s, m, or h.
  
  value integer Required
  
  Minimum value is 1.
- group_by array[string] Required
  
  At least 1 but not more than 3 elements.
- missing_fields_strategy string
  
  Describes how alerts will be generated for documents with missing suppress by fields: doNotSuppress - per each document a separate alert will be created suppress - only alert will be created per suppress by bucket
  
  Values are doNotSuppress or suppress.
concurrent_searches integer

Minimum value is 1.
data_view_id string
filters array

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

This field is not supported for ES|QL rules.
index array[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).

This field is not supported for ES|QL rules.
items_per_search integer

Minimum value is 1.
saved_id string

Kibana saved search used by the rule to create alerts.
threat_filters array

Query and filter context array used to filter documents from the Elasticsearch index containing the threat values
threat_indicator_path string

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

Values are kuery or lucene.
language string

Values are kuery or lucene.
invocationCount integer Required
timeframeEnd string(date-time) Required

actions array[object]

Array defining the automated actions (notifications) taken when alerts are generated.
Hide actions attributes Show actions attributes object
- action_type_id string Required
  The action type used for sending notifications, can be:
  
  .slack
  
  .slack_api
  
  .email
  
  .index
  
  .pagerduty
  
  .swimlane
  
  .webhook
  
  .servicenow
  
  .servicenow-itom
  
  .servicenow-sir
  
  .jira
  
  .resilient
  
  .opsgenie
  
  .teams
  
  .torq
  
  .tines
  
  .d3security
- alerts_filter object
  Object containing an action’s conditional filters.
  
  timeframe (object, optional): Object containing the time frame for when this action can be run.
  
  days (array of integers, required): List of days of the week on which this action will be run. Days of the week are expressed as numbers between 1-7, where 1 is Monday and 7 is Sunday. To select all days of the week, enter an empty array.
  
  hours (object, required): The hours of the day during which this action will run. Hours of the day are expressed as two strings in the format hh:mm in 24 hour time. A start of 00:00 and an end of 24:00 means the action can run all day.
  
  start (string, required): Start time in hh:mm format.
  
  end (string, required): End time in hh:mm format.
  
  timezone (string, required): An ISO timezone name, such as Europe/Madrid or America/New_York. Specific offsets such as UTC or UTC+1 will also work, but lack built-in DST.
  
  query (object, optional): Object containing a query filter which gets applied to an action and determines whether the action should run.
  
  kql (string, required): A KQL string.
  
  filters (array of objects, required): Array of filter objects, as defined in the kbn-es-query package.
  Additional properties are allowed.
- frequency object
  
  The action frequency defines when the action runs (for example, only on rule execution or at specific time intervals).
  Hide frequency attributes Show frequency attributes object
  
  notifyWhen string Required
  
  Defines how often rules run actions.
  
  Values are onActiveAlert, onThrottleInterval, or onActionGroupChange.
  
  summary boolean Required
  
  Action summary indicates whether we will send a summary notification about all the generate alerts or notification per individual alert
  
  throttle string Required
  
  Defines how often rule actions are taken.
  
  One of:
  string-1 string string-2 string
  
  Values are no_actions or rule.
  
  Time interval in seconds, minutes, hours, or days.
  
  Format should match the following pattern: ^[1-9]\d*[smhd]$.
- group string
  
  Optionally groups actions by use cases. Use default for alert notifications.
- id string Required
  
  The connector ID.
- params object Required
  Object containing the allowed connector fields, which varies according to the connector type.
  
  For Slack:
  
  message (string, required): The notification message.
  
  For email:
  
  to, cc, bcc (string): Email addresses to which the notifications are sent. At least one field must have a value.
  
  subject (string, optional): Email subject line.
  
  message (string, required): Email body text.
  
  For Webhook:
  
  body (string, required): JSON payload.
  
  For PagerDuty:
  
  severity (string, required): Severity of on the alert notification, can be: Critical, Error, Warning or Info.
  
  eventAction (string, required): Event action type, which can be trigger, resolve, or acknowledge.
  
  dedupKey (string, optional): Groups alert notifications with the same PagerDuty alert.
  
  timestamp (DateTime, optional): ISO-8601 format timestamp.
  
  component (string, optional): Source machine component responsible for the event, for example security-solution.
  
  group (string, optional): Enables logical grouping of service components.
  
  source (string, optional): The affected system. Defaults to the Kibana saved object ID of the action.
  
  summary (string, options): Summary of the event. Defaults to No summary provided. Maximum length is 1024 characters.
  
  class (string, optional): Value indicating the class/type of the event.
  Additional properties are allowed.
- uuid string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
alias_purpose string

Values are savedObjectConversion or savedObjectImport.
alias_target_id string
author array[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 Required

The rule’s description.

Minimum length is 1.
enabled boolean

Determines whether the rule is enabled. Defaults to true.
exceptions_list array[object]
Hide exceptions_list attributes Show exceptions_list attributes object
Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.
- id string(nonempty) Required
  
  ID of the exception container
  
  Minimum length is 1.
- list_id string(nonempty) Required
  
  List ID of the exception container
  
  Minimum length is 1.
- namespace_type string Required
  
  Determines the exceptions validity in rule's Kibana space
  
  Values are agnostic or single.
- type string Required
  
  The exception type
  
  Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_trusted_devices, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.
false_positives array[string]

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.
from string(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.
Hide investigation_fields attribute Show investigation_fields attribute object
- field_names array[string(nonempty)] Required
  
  A string that does not contain only whitespace characters
  
  At least 1 element. Minimum length of each is 1.
license string

The rule's license.
max_signals integer

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

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.

Minimum value is 1. Default value is 100.
meta object

Placeholder for metadata about the rule.

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

Additional properties are allowed.
name string Required

A human-readable name for the rule.

Minimum length is 1.
namespace string

Has no effect.
note string

Notes to help investigate alerts produced by the rule.
outcome string

Values are exactMatch, aliasMatch, or conflict.
output_index string Deprecated

(deprecated) Has no effect.
references array[string]

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.
related_integrations array[object]
Hide related_integrations attributes Show related_integrations attributes object
Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:
- package: name of the package (required, unique id)
- version: version of the package (required, semver-compatible)
- integration: name of the integration of this package (optional, id within the package)
There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.
- integration string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- package string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- version string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
required_fields array[object]

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

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.
Hide required_fields attributes Show required_fields attributes object
Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.
- name string(nonempty) Required
  
  Name of an Elasticsearch field
  
  Minimum length is 1.
- type string(nonempty) Required
  
  Type of the Elasticsearch field
  
  Minimum length is 1.
response_actions array[object]
One of:
.osquery object .endpoint object
Hide attributes Show attributes

action_type_id string Required Discriminator

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

To specify a query pack, use the packId field. Example: "packId": "processes_elastic"

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

id string Required

Query ID

platform string

query string Required

Query to run

removed boolean

snapshot boolean

version string

Query version

query string

To run a single query, use the query field and enter a SQL query. Example: "query": "SELECT * FROM processes;"

saved_query_id string

To run a saved query, use the saved_query_id field and specify the saved query ID. Example: "saved_query_id": "processes_elastic"

timeout number

A timeout period, in seconds, after which the query will stop running. Overwriting the default timeout allows you to support queries that require more time to complete. The default and minimum supported value is 60. The maximum supported value is 900. Example: "timeout": 120.
Hide attributes Show attributes

action_type_id string Required Discriminator

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object Security_Detections_API_RunscriptParams object

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.

This functionality is currently not available

Hide attributes Show attributes

command string Required

Value is runscript.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log

config object

Hide config attributes Show config attributes object

linux object

Hide linux attributes Show linux attributes object

scriptId string

scriptInput string

timeout integer

Specify the timeout in seconds for the script execution

macos object

Hide macos attributes Show macos attributes object

scriptId string

scriptInput string

timeout integer

Specify the timeout in seconds for the script execution

windows object

Hide windows attributes Show windows attributes object

scriptId string

scriptInput string

timeout integer

Specify the timeout in seconds for the script execution
risk_score integer 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
Minimum value is 0, maximum value is 100.
risk_score_mapping array[object]

Overrides generated alerts' risk_score with a value from the source event
Hide risk_score_mapping attributes Show risk_score_mapping attributes object
- field string Required
  
  Source event field used to override the default risk_score.
- operator string Required
  
  Value is equals.
- risk_score integer
  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
  Minimum value is 0, maximum value is 100.
- value string Required
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 string 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 are low, medium, high, or critical.
severity_mapping array[object]

Overrides generated alerts' severity with values from the source event
Hide severity_mapping attributes Show severity_mapping attributes object
- field string Required
  
  Source event field used to override the default severity.
- operator string Required
  
  Value is equals.
- severity string 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 are low, medium, high, or critical.
- value string Required
tags array[string]

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.
threat array[object]
Hide threat attributes Show threat attributes object
Currently, only threats described using the MITRE ATT&CK™ framework are supported.
- framework string Required
  
  Relevant attack framework
- tactic object Required
  
  Object containing information on the attack type
  Hide tactic attributes Show tactic attributes object
  
  id string Required
  
  Tactic ID
  
  name string Required
  
  Tactic name
  
  reference string Required
  
  Tactic reference
- technique array[object]
  
  Array containing information on the attack techniques (optional)
  Hide technique attributes Show technique attributes object
  
  id string Required
  
  Technique ID
  
  name string Required
  
  Technique name
  
  reference string Required
  
  Technique reference
  
  subtechnique array[object]
  
  Array containing more specific information on the attack technique.
  
  Hide subtechnique attributes Show subtechnique attributes object
  
  id string Required
  
  Subtechnique ID
  
  name string Required
  
  Subtechnique name
  
  reference string Required
  
  Subtechnique reference
throttle string

Defines how often rule actions are taken.

One of:
string-1 string string-2 string

Values are no_actions or rule.

Time interval in seconds, minutes, hours, or days.

Format should match the following pattern: ^[1-9]\d*[smhd]$.
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
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.
It is not incremented on each update. Compare this to the revision field.
Minimum value is 1.
anomaly_threshold integer Required

Anomaly score threshold above which the rule creates an alert. Valid values are from 0 to 100.

Minimum value is 0.
machine_learning_job_id string | array[string] Required

Machine learning job ID(s) the rule monitors for anomaly scores.

One of:
string-1 string array-2 array[string]

At least 1 element.
type string Required

Rule type

Value is machine_learning.
alert_suppression object

Defines alert suppression configuration.
Hide alert_suppression attributes Show alert_suppression attributes object
- duration object
  Hide duration attributes Show duration attributes object
  
  unit string Required
  
  Time unit
  
  Values are s, m, or h.
  
  value integer Required
  
  Minimum value is 1.
- group_by array[string] Required
  
  At least 1 but not more than 3 elements.
- missing_fields_strategy string
  
  Describes how alerts will be generated for documents with missing suppress by fields: doNotSuppress - per each document a separate alert will be created suppress - only alert will be created per suppress by bucket
  
  Values are doNotSuppress or suppress.
invocationCount integer Required
timeframeEnd string(date-time) Required

actions array[object]

Array defining the automated actions (notifications) taken when alerts are generated.
Hide actions attributes Show actions attributes object
- action_type_id string Required
  The action type used for sending notifications, can be:
  
  .slack
  
  .slack_api
  
  .email
  
  .index
  
  .pagerduty
  
  .swimlane
  
  .webhook
  
  .servicenow
  
  .servicenow-itom
  
  .servicenow-sir
  
  .jira
  
  .resilient
  
  .opsgenie
  
  .teams
  
  .torq
  
  .tines
  
  .d3security
- alerts_filter object
  Object containing an action’s conditional filters.
  
  timeframe (object, optional): Object containing the time frame for when this action can be run.
  
  days (array of integers, required): List of days of the week on which this action will be run. Days of the week are expressed as numbers between 1-7, where 1 is Monday and 7 is Sunday. To select all days of the week, enter an empty array.
  
  hours (object, required): The hours of the day during which this action will run. Hours of the day are expressed as two strings in the format hh:mm in 24 hour time. A start of 00:00 and an end of 24:00 means the action can run all day.
  
  start (string, required): Start time in hh:mm format.
  
  end (string, required): End time in hh:mm format.
  
  timezone (string, required): An ISO timezone name, such as Europe/Madrid or America/New_York. Specific offsets such as UTC or UTC+1 will also work, but lack built-in DST.
  
  query (object, optional): Object containing a query filter which gets applied to an action and determines whether the action should run.
  
  kql (string, required): A KQL string.
  
  filters (array of objects, required): Array of filter objects, as defined in the kbn-es-query package.
  Additional properties are allowed.
- frequency object
  
  The action frequency defines when the action runs (for example, only on rule execution or at specific time intervals).
  Hide frequency attributes Show frequency attributes object
  
  notifyWhen string Required
  
  Defines how often rules run actions.
  
  Values are onActiveAlert, onThrottleInterval, or onActionGroupChange.
  
  summary boolean Required
  
  Action summary indicates whether we will send a summary notification about all the generate alerts or notification per individual alert
  
  throttle string Required
  
  Defines how often rule actions are taken.
  
  One of:
  string-1 string string-2 string
  
  Values are no_actions or rule.
  
  Time interval in seconds, minutes, hours, or days.
  
  Format should match the following pattern: ^[1-9]\d*[smhd]$.
- group string
  
  Optionally groups actions by use cases. Use default for alert notifications.
- id string Required
  
  The connector ID.
- params object Required
  Object containing the allowed connector fields, which varies according to the connector type.
  
  For Slack:
  
  message (string, required): The notification message.
  
  For email:
  
  to, cc, bcc (string): Email addresses to which the notifications are sent. At least one field must have a value.
  
  subject (string, optional): Email subject line.
  
  message (string, required): Email body text.
  
  For Webhook:
  
  body (string, required): JSON payload.
  
  For PagerDuty:
  
  severity (string, required): Severity of on the alert notification, can be: Critical, Error, Warning or Info.
  
  eventAction (string, required): Event action type, which can be trigger, resolve, or acknowledge.
  
  dedupKey (string, optional): Groups alert notifications with the same PagerDuty alert.
  
  timestamp (DateTime, optional): ISO-8601 format timestamp.
  
  component (string, optional): Source machine component responsible for the event, for example security-solution.
  
  group (string, optional): Enables logical grouping of service components.
  
  source (string, optional): The affected system. Defaults to the Kibana saved object ID of the action.
  
  summary (string, options): Summary of the event. Defaults to No summary provided. Maximum length is 1024 characters.
  
  class (string, optional): Value indicating the class/type of the event.
  Additional properties are allowed.
- uuid string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
alias_purpose string

Values are savedObjectConversion or savedObjectImport.
alias_target_id string
author array[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 Required

The rule’s description.

Minimum length is 1.
enabled boolean

Determines whether the rule is enabled. Defaults to true.
exceptions_list array[object]
Hide exceptions_list attributes Show exceptions_list attributes object
Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.
- id string(nonempty) Required
  
  ID of the exception container
  
  Minimum length is 1.
- list_id string(nonempty) Required
  
  List ID of the exception container
  
  Minimum length is 1.
- namespace_type string Required
  
  Determines the exceptions validity in rule's Kibana space
  
  Values are agnostic or single.
- type string Required
  
  The exception type
  
  Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_trusted_devices, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.
false_positives array[string]

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.
from string(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.
Hide investigation_fields attribute Show investigation_fields attribute object
- field_names array[string(nonempty)] Required
  
  A string that does not contain only whitespace characters
  
  At least 1 element. Minimum length of each is 1.
license string

The rule's license.
max_signals integer

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

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.

Minimum value is 1. Default value is 100.
meta object

Placeholder for metadata about the rule.

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

Additional properties are allowed.
name string Required

A human-readable name for the rule.

Minimum length is 1.
namespace string

Has no effect.
note string

Notes to help investigate alerts produced by the rule.
outcome string

Values are exactMatch, aliasMatch, or conflict.
output_index string Deprecated

(deprecated) Has no effect.
references array[string]

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.
related_integrations array[object]
Hide related_integrations attributes Show related_integrations attributes object
Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:
- package: name of the package (required, unique id)
- version: version of the package (required, semver-compatible)
- integration: name of the integration of this package (optional, id within the package)
There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.
- integration string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- package string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- version string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
required_fields array[object]

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

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.
Hide required_fields attributes Show required_fields attributes object
Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.
- name string(nonempty) Required
  
  Name of an Elasticsearch field
  
  Minimum length is 1.
- type string(nonempty) Required
  
  Type of the Elasticsearch field
  
  Minimum length is 1.
response_actions array[object]
One of:
.osquery object .endpoint object
Hide attributes Show attributes

action_type_id string Required Discriminator

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

To specify a query pack, use the packId field. Example: "packId": "processes_elastic"

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

id string Required

Query ID

platform string

query string Required

Query to run

removed boolean

snapshot boolean

version string

Query version

query string

To run a single query, use the query field and enter a SQL query. Example: "query": "SELECT * FROM processes;"

saved_query_id string

To run a saved query, use the saved_query_id field and specify the saved query ID. Example: "saved_query_id": "processes_elastic"

timeout number

A timeout period, in seconds, after which the query will stop running. Overwriting the default timeout allows you to support queries that require more time to complete. The default and minimum supported value is 60. The maximum supported value is 900. Example: "timeout": 120.
Hide attributes Show attributes

action_type_id string Required Discriminator

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object Security_Detections_API_RunscriptParams object

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.

This functionality is currently not available

Hide attributes Show attributes

command string Required

Value is runscript.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log

config object

Hide config attributes Show config attributes object

linux object

Hide linux attributes Show linux attributes object

scriptId string

scriptInput string

timeout integer

Specify the timeout in seconds for the script execution

macos object

Hide macos attributes Show macos attributes object

scriptId string

scriptInput string

timeout integer

Specify the timeout in seconds for the script execution

windows object

Hide windows attributes Show windows attributes object

scriptId string

scriptInput string

timeout integer

Specify the timeout in seconds for the script execution
risk_score integer 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
Minimum value is 0, maximum value is 100.
risk_score_mapping array[object]

Overrides generated alerts' risk_score with a value from the source event
Hide risk_score_mapping attributes Show risk_score_mapping attributes object
- field string Required
  
  Source event field used to override the default risk_score.
- operator string Required
  
  Value is equals.
- risk_score integer
  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
  Minimum value is 0, maximum value is 100.
- value string Required
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 string 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 are low, medium, high, or critical.
severity_mapping array[object]

Overrides generated alerts' severity with values from the source event
Hide severity_mapping attributes Show severity_mapping attributes object
- field string Required
  
  Source event field used to override the default severity.
- operator string Required
  
  Value is equals.
- severity string 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 are low, medium, high, or critical.
- value string Required
tags array[string]

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.
threat array[object]
Hide threat attributes Show threat attributes object
Currently, only threats described using the MITRE ATT&CK™ framework are supported.
- framework string Required
  
  Relevant attack framework
- tactic object Required
  
  Object containing information on the attack type
  Hide tactic attributes Show tactic attributes object
  
  id string Required
  
  Tactic ID
  
  name string Required
  
  Tactic name
  
  reference string Required
  
  Tactic reference
- technique array[object]
  
  Array containing information on the attack techniques (optional)
  Hide technique attributes Show technique attributes object
  
  id string Required
  
  Technique ID
  
  name string Required
  
  Technique name
  
  reference string Required
  
  Technique reference
  
  subtechnique array[object]
  
  Array containing more specific information on the attack technique.
  
  Hide subtechnique attributes Show subtechnique attributes object
  
  id string Required
  
  Subtechnique ID
  
  name string Required
  
  Subtechnique name
  
  reference string Required
  
  Subtechnique reference
throttle string

Defines how often rule actions are taken.

One of:
string-1 string string-2 string

Values are no_actions or rule.

Time interval in seconds, minutes, hours, or days.

Format should match the following pattern: ^[1-9]\d*[smhd]$.
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
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.
It is not incremented on each update. Compare this to the revision field.
Minimum value is 1.
history_window_start string(nonempty) 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.

Minimum length is 1.
new_terms_fields array[string] Required

Fields to monitor for new values.

At least 1 but not more than 3 elements.
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.
type string Required

Rule type

Value is new_terms.
alert_suppression object

Defines alert suppression configuration.
Hide alert_suppression attributes Show alert_suppression attributes object
- duration object
  Hide duration attributes Show duration attributes object
  
  unit string Required
  
  Time unit
  
  Values are s, m, or h.
  
  value integer Required
  
  Minimum value is 1.
- group_by array[string] Required
  
  At least 1 but not more than 3 elements.
- missing_fields_strategy string
  
  Describes how alerts will be generated for documents with missing suppress by fields: doNotSuppress - per each document a separate alert will be created suppress - only alert will be created per suppress by bucket
  
  Values are doNotSuppress or suppress.
data_view_id string
filters array

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

This field is not supported for ES|QL rules.
index array[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).

This field is not supported for ES|QL rules.
language string

Values are kuery or lucene.
invocationCount integer Required
timeframeEnd string(date-time) Required

actions array[object]

Array defining the automated actions (notifications) taken when alerts are generated.
Hide actions attributes Show actions attributes object
- action_type_id string Required
  The action type used for sending notifications, can be:
  
  .slack
  
  .slack_api
  
  .email
  
  .index
  
  .pagerduty
  
  .swimlane
  
  .webhook
  
  .servicenow
  
  .servicenow-itom
  
  .servicenow-sir
  
  .jira
  
  .resilient
  
  .opsgenie
  
  .teams
  
  .torq
  
  .tines
  
  .d3security
- alerts_filter object
  Object containing an action’s conditional filters.
  
  timeframe (object, optional): Object containing the time frame for when this action can be run.
  
  days (array of integers, required): List of days of the week on which this action will be run. Days of the week are expressed as numbers between 1-7, where 1 is Monday and 7 is Sunday. To select all days of the week, enter an empty array.
  
  hours (object, required): The hours of the day during which this action will run. Hours of the day are expressed as two strings in the format hh:mm in 24 hour time. A start of 00:00 and an end of 24:00 means the action can run all day.
  
  start (string, required): Start time in hh:mm format.
  
  end (string, required): End time in hh:mm format.
  
  timezone (string, required): An ISO timezone name, such as Europe/Madrid or America/New_York. Specific offsets such as UTC or UTC+1 will also work, but lack built-in DST.
  
  query (object, optional): Object containing a query filter which gets applied to an action and determines whether the action should run.
  
  kql (string, required): A KQL string.
  
  filters (array of objects, required): Array of filter objects, as defined in the kbn-es-query package.
  Additional properties are allowed.
- frequency object
  
  The action frequency defines when the action runs (for example, only on rule execution or at specific time intervals).
  Hide frequency attributes Show frequency attributes object
  
  notifyWhen string Required
  
  Defines how often rules run actions.
  
  Values are onActiveAlert, onThrottleInterval, or onActionGroupChange.
  
  summary boolean Required
  
  Action summary indicates whether we will send a summary notification about all the generate alerts or notification per individual alert
  
  throttle string Required
  
  Defines how often rule actions are taken.
  
  One of:
  string-1 string string-2 string
  
  Values are no_actions or rule.
  
  Time interval in seconds, minutes, hours, or days.
  
  Format should match the following pattern: ^[1-9]\d*[smhd]$.
- group string
  
  Optionally groups actions by use cases. Use default for alert notifications.
- id string Required
  
  The connector ID.
- params object Required
  Object containing the allowed connector fields, which varies according to the connector type.
  
  For Slack:
  
  message (string, required): The notification message.
  
  For email:
  
  to, cc, bcc (string): Email addresses to which the notifications are sent. At least one field must have a value.
  
  subject (string, optional): Email subject line.
  
  message (string, required): Email body text.
  
  For Webhook:
  
  body (string, required): JSON payload.
  
  For PagerDuty:
  
  severity (string, required): Severity of on the alert notification, can be: Critical, Error, Warning or Info.
  
  eventAction (string, required): Event action type, which can be trigger, resolve, or acknowledge.
  
  dedupKey (string, optional): Groups alert notifications with the same PagerDuty alert.
  
  timestamp (DateTime, optional): ISO-8601 format timestamp.
  
  component (string, optional): Source machine component responsible for the event, for example security-solution.
  
  group (string, optional): Enables logical grouping of service components.
  
  source (string, optional): The affected system. Defaults to the Kibana saved object ID of the action.
  
  summary (string, options): Summary of the event. Defaults to No summary provided. Maximum length is 1024 characters.
  
  class (string, optional): Value indicating the class/type of the event.
  Additional properties are allowed.
- uuid string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
alias_purpose string

Values are savedObjectConversion or savedObjectImport.
alias_target_id string
author array[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 Required

The rule’s description.

Minimum length is 1.
enabled boolean

Determines whether the rule is enabled. Defaults to true.
exceptions_list array[object]
Hide exceptions_list attributes Show exceptions_list attributes object
Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.
- id string(nonempty) Required
  
  ID of the exception container
  
  Minimum length is 1.
- list_id string(nonempty) Required
  
  List ID of the exception container
  
  Minimum length is 1.
- namespace_type string Required
  
  Determines the exceptions validity in rule's Kibana space
  
  Values are agnostic or single.
- type string Required
  
  The exception type
  
  Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_trusted_devices, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.
false_positives array[string]

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.
from string(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.
Hide investigation_fields attribute Show investigation_fields attribute object
- field_names array[string(nonempty)] Required
  
  A string that does not contain only whitespace characters
  
  At least 1 element. Minimum length of each is 1.
license string

The rule's license.
max_signals integer

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

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.

Minimum value is 1. Default value is 100.
meta object

Placeholder for metadata about the rule.

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

Additional properties are allowed.
name string Required

A human-readable name for the rule.

Minimum length is 1.
namespace string

Has no effect.
note string

Notes to help investigate alerts produced by the rule.
outcome string

Values are exactMatch, aliasMatch, or conflict.
output_index string Deprecated

(deprecated) Has no effect.
references array[string]

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.
related_integrations array[object]
Hide related_integrations attributes Show related_integrations attributes object
Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:
- package: name of the package (required, unique id)
- version: version of the package (required, semver-compatible)
- integration: name of the integration of this package (optional, id within the package)
There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.
- integration string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- package string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- version string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
required_fields array[object]

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

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.
Hide required_fields attributes Show required_fields attributes object
Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.
- name string(nonempty) Required
  
  Name of an Elasticsearch field
  
  Minimum length is 1.
- type string(nonempty) Required
  
  Type of the Elasticsearch field
  
  Minimum length is 1.
response_actions array[object]
One of:
.osquery object .endpoint object
Hide attributes Show attributes

action_type_id string Required Discriminator

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

To specify a query pack, use the packId field. Example: "packId": "processes_elastic"

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

id string Required

Query ID

platform string

query string Required

Query to run

removed boolean

snapshot boolean

version string

Query version

query string

To run a single query, use the query field and enter a SQL query. Example: "query": "SELECT * FROM processes;"

saved_query_id string

To run a saved query, use the saved_query_id field and specify the saved query ID. Example: "saved_query_id": "processes_elastic"

timeout number

A timeout period, in seconds, after which the query will stop running. Overwriting the default timeout allows you to support queries that require more time to complete. The default and minimum supported value is 60. The maximum supported value is 900. Example: "timeout": 120.
Hide attributes Show attributes

action_type_id string Required Discriminator

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object Security_Detections_API_RunscriptParams object

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.

This functionality is currently not available

Hide attributes Show attributes

command string Required

Value is runscript.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log

config object

Hide config attributes Show config attributes object

linux object

Hide linux attributes Show linux attributes object

scriptId string

scriptInput string

timeout integer

Specify the timeout in seconds for the script execution

macos object

Hide macos attributes Show macos attributes object

scriptId string

scriptInput string

timeout integer

Specify the timeout in seconds for the script execution

windows object

Hide windows attributes Show windows attributes object

scriptId string

scriptInput string

timeout integer

Specify the timeout in seconds for the script execution
risk_score integer 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
Minimum value is 0, maximum value is 100.
risk_score_mapping array[object]

Overrides generated alerts' risk_score with a value from the source event
Hide risk_score_mapping attributes Show risk_score_mapping attributes object
- field string Required
  
  Source event field used to override the default risk_score.
- operator string Required
  
  Value is equals.
- risk_score integer
  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
  Minimum value is 0, maximum value is 100.
- value string Required
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 string 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 are low, medium, high, or critical.
severity_mapping array[object]

Overrides generated alerts' severity with values from the source event
Hide severity_mapping attributes Show severity_mapping attributes object
- field string Required
  
  Source event field used to override the default severity.
- operator string Required
  
  Value is equals.
- severity string 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 are low, medium, high, or critical.
- value string Required
tags array[string]

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.
threat array[object]
Hide threat attributes Show threat attributes object
Currently, only threats described using the MITRE ATT&CK™ framework are supported.
- framework string Required
  
  Relevant attack framework
- tactic object Required
  
  Object containing information on the attack type
  Hide tactic attributes Show tactic attributes object
  
  id string Required
  
  Tactic ID
  
  name string Required
  
  Tactic name
  
  reference string Required
  
  Tactic reference
- technique array[object]
  
  Array containing information on the attack techniques (optional)
  Hide technique attributes Show technique attributes object
  
  id string Required
  
  Technique ID
  
  name string Required
  
  Technique name
  
  reference string Required
  
  Technique reference
  
  subtechnique array[object]
  
  Array containing more specific information on the attack technique.
  
  Hide subtechnique attributes Show subtechnique attributes object
  
  id string Required
  
  Subtechnique ID
  
  name string Required
  
  Subtechnique name
  
  reference string Required
  
  Subtechnique reference
throttle string

Defines how often rule actions are taken.

One of:
string-1 string string-2 string

Values are no_actions or rule.

Time interval in seconds, minutes, hours, or days.

Format should match the following pattern: ^[1-9]\d*[smhd]$.
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
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.
It is not incremented on each update. Compare this to the revision field.
Minimum value is 1.
alert_suppression object

Defines alert suppression configuration.
Hide alert_suppression attributes Show alert_suppression attributes object
- duration object
  Hide duration attributes Show duration attributes object
  
  unit string Required
  
  Time unit
  
  Values are s, m, or h.
  
  value integer Required
  
  Minimum value is 1.
- group_by array[string] Required
  
  At least 1 but not more than 3 elements.
- missing_fields_strategy string
  
  Describes how alerts will be generated for documents with missing suppress by fields: doNotSuppress - per each document a separate alert will be created suppress - only alert will be created per suppress by bucket
  
  Values are doNotSuppress or suppress.
language string Required

Value is 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.
type string Required

Rule type

Value is esql.
invocationCount integer Required
timeframeEnd string(date-time) Required

Responses

200 application/json

Successful response
Hide response attributes Show response attributes object
- isAborted boolean
- logs array[object] Required
  
  Hide logs attributes Show logs attributes object
  
  duration integer Required
  
  Execution duration in milliseconds
  
  errors array[string(nonempty)] Required
  
  A string that does not contain only whitespace characters
  
  Minimum length of each is 1.
  
  requests array[object]
  
  Hide requests attributes Show requests attributes object
  
  description string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  duration integer
  
  request string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  request_type string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  startedAt string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  warnings array[string(nonempty)] Required
  
  A string that does not contain only whitespace characters
  
  Minimum length of each is 1.
- previewId string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
400 application/json

Invalid input data response
One of:
Security_Detections_API_PlatformErrorResponse object Security_Detections_API_SiemErrorResponse object
Hide attributes Show attributes

error string Required

message string Required

statusCode integer Required
Hide attributes Show attributes

message string Required

status_code integer Required
401 application/json

Unsuccessful authentication response
Hide response attributes Show response attributes object
- error string Required
- message string Required
- statusCode integer Required
500 application/json

Internal server error response
Hide response attributes Show response attributes object
- message string Required
- status_code integer Required

POST /api/detection_engine/rules/preview

curl \
 --request POST 'https://<KIBANA_URL>/api/detection_engine/rules/preview' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"description":"Find matching events","from":"now-24h","index":["logs-*"],"invocationCount":1,"language":"kuery","max_signals":20,"name":"Rule preview","query":"process.name : *","risk_score":25,"severity":"low","timeframeEnd":"2025-01-20T12:00:00.000Z","to":"now","type":"query"}'

Request example

{
  "description": "Find matching events",
  "from": "now-24h",
  "index": [
    "logs-*"
  ],
  "invocationCount": 1,
  "language": "kuery",
  "max_signals": 20,
  "name": "Rule preview",
  "query": "process.name : *",
  "risk_score": 25,
  "severity": "low",
  "timeframeEnd": "2025-01-20T12:00:00.000Z",
  "to": "now",
  "type": "query"
}

Response examples (200)

{
  "isAborted": false,
  "logs": [
    {
      "duration": 45,
      "errors": [],
      "requests": [],
      "startedAt": "2025-01-20T10:00:00.000Z",
      "warnings": []
    }
  ],
  "previewId": "7f1c9d1e-4c8a-4a3e-9a5d-0d4f6e1b2a90"
}

Response examples (400)

{
  "error": "Bad Request",
  "message": "[request body].timeframeEnd: expected string, received null",
  "statusCode": 400
}

Response examples (401)

{
  "error": "Unauthorized",
  "message": "[security_exception\n\tRoot causes:\n\t\tsecurity_exception: unable to authenticate user [elastic] for REST request [/_security/_authenticate]]: unable to authenticate user [elastic] for REST request [/_security/_authenticate]",
  "statusCode": 401
}

Response examples (500)

{
  "message": "Internal Server Error",
  "status_code": 500
}