Type to search.

Patch multiple detection rules

Base URL
https://{kibana_url}
  • PATCH /api/detection_engine/rules/_bulk_update
  • PATCH /s/{space_id}/api/detection_engine/rules/_bulk_update
Auth Deprecated

Update specific fields of existing detection rules using the rule_id or id field.

Warning

This API is deprecated and will be removed in Kibana v9.0.

Warning

When used with API key authentication, the user's key gets assigned to the affected rules. If the user's key gets deleted or the user becomes inactive, the rules will stop running.

If the API key that is used for authorization has different privileges than the key that created or most recently updated the rule, the rule behavior might change.

Path parameters

space_id string optional

An identifier for the space. If space_id is not provided in the URL, the default space is used. Refer to Spaces for more information.

Request body

A JSON array of rules, where each rule contains the required fields.

An array; each item is any of:
type enum

Rule type

Values: eql
alias_purpose enum
Values: savedObjectConversion savedObjectImport
alias_target_id string
author string[]

The rule’s author.

building_block_type string

Determines if the rule acts as a building block. If yes, the value must be default. By default, building-block alerts are not displayed in the UI. These rules are used as a foundation for other rules that do generate alerts. For more information, refer to About building block rules.

description string · min length: 1

The rule’s description.

enabled boolean

Determines whether the rule is enabled. Defaults to true.

false_positives string[]

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

from string · format: date-math

Time from which data is analyzed each time the rule runs, using a date math range. For example, now-4200s means the rule analyzes data from 70 minutes before its start time. Defaults to now-6m (analyzes data from 6 minutes before the start time).

id string · format: uuid

A universally unique identifier

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).

license string

The rule's license.

max_signals integer · min: 1 · default: 100

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

Note

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

meta object

Placeholder for metadata about the rule.

Note

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

name string · min length: 1

A human-readable name for the rule.

namespace string

Has no effect.

note string

Notes to help investigate alerts produced by the rule.

outcome enum
Values: exactMatch aliasMatch conflict
output_index string deprecated

(deprecated) Has no effect.

references string[]

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

response_actions union oneOf[]
One of:
action_type_id enum required
Values: .osquery
params object required
ecs_mapping map string to object

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

pack_id string

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

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.

risk_score integer · min: 0 · max: 100

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
rule_id string

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

rule_name_override string

Sets which field in the source event is used to populate the alert's signal.rule.name value (in the UI, this value is displayed on the Rules page in the Rule column). When unspecified, the rule’s name value is used. The source field must be a string data type.

setup string

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

severity enum

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

  • low: Alerts that are of interest but generally not considered to be security incidents
  • medium: Alerts that require investigation
  • high: Alerts that require immediate investigation
  • critical: Alerts that indicate it is highly likely a security incident has occurred
Values: low medium high critical
tags string[]

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

throttle union oneOf

Defines how often rule actions are taken.

Values: no_actions rule
timeline_id string

Timeline template ID

timeline_title string

Timeline template title

timestamp_override string

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

timestamp_override_fallback_disabled boolean

Disables the fallback to the event's @timestamp field

to string
version integer · min: 1

The rule's version number.

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

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

language enum
Values: eql
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.
data_view_id string
event_category_override string
filters object[]

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

Note

This field is not supported for ES|QL rules.

index string[]

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

Note

This field is not supported for ES|QL rules.

tiebreaker_field string

Sets a secondary field for sorting events

timestamp_field string

Specifies the name of the event timestamp field used for sorting a sequence of events. Not to be confused with timestamp_override, which specifies the more general field used for querying events within a range. Defaults to the @timestamp ECS field.

Response

Indicates a successful call.

application/json
An array; each item is one of:
Any of:
type: eql
type enum required

Rule type

Values: eql
actions object[] required

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

Same fields as actions in type: eql
alias_purpose enum
Values: savedObjectConversion savedObjectImport
alias_target_id string
author string[] required

The rule’s author.

building_block_type string

Determines if the rule acts as a building block. If yes, the value must be default. By default, building-block alerts are not displayed in the UI. These rules are used as a foundation for other rules that do generate alerts. For more information, refer to About building block rules.

description string · min length: 1 required

The rule’s description.

enabled boolean required

Determines whether the rule is enabled. Defaults to true.

exceptions_list object[] required
id string · format: nonempty · min length: 1 required

ID of the exception container

list_id string · format: nonempty · min length: 1 required

List ID of the exception container

namespace_type enum required

Determines the exceptions validity in rule's Kibana space

Values: agnostic single
type enum required

The exception type

Values: detection rule_default endpoint endpoint_trusted_apps endpoint_events endpoint_host_isolation_exceptions endpoint_blocklists
false_positives string[] required

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

from string · format: date-math required

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 required

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

license string

The rule's license.

max_signals integer · min: 1 · default: 100 required

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

Note

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

meta object

Placeholder for metadata about the rule.

Note

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

name string · min length: 1 required

A human-readable name for the rule.

namespace string

Has no effect.

note string

Notes to help investigate alerts produced by the rule.

outcome enum
Values: exactMatch aliasMatch conflict
output_index string deprecated

(deprecated) Has no effect.

references string[] required

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

A string that does not contain only whitespace characters

A string that does not contain only whitespace characters

A string that does not contain only whitespace characters

required_fields object[] required

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

Note

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

name string · format: nonempty · min length: 1 required

Name of an Elasticsearch field

type string · format: nonempty · min length: 1 required

Type of the Elasticsearch field

response_actions union oneOf[]
Same options as response_actions in type: eql
risk_score integer · min: 0 · max: 100 required

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

  • 0 - 21 represents low severity
  • 22 - 47 represents medium severity
  • 48 - 73 represents high severity
  • 74 - 100 represents critical severity
risk_score_mapping object[] required

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

field string required

Source event field used to override the default risk_score.

operator enum required
Values: equals
risk_score integer · min: 0 · max: 100

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
value string required
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 required

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

severity enum required

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

  • low: Alerts that are of interest but generally not considered to be security incidents
  • medium: Alerts that require investigation
  • high: Alerts that require immediate investigation
  • critical: Alerts that indicate it is highly likely a security incident has occurred
Values: low medium high critical
severity_mapping object[] required

Overrides generated alerts' severity with values from the source event

field string required

Source event field used to override the default severity.

operator enum required
Values: equals
severity enum required

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

  • low: Alerts that are of interest but generally not considered to be security incidents
  • medium: Alerts that require investigation
  • high: Alerts that require immediate investigation
  • critical: Alerts that indicate it is highly likely a security incident has occurred
Values: low medium high critical
value string required
tags string[] required

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

threat object[] required
Same fields as threat in type: eql
throttle union oneOf

Defines how often rule actions are taken.

Values: no_actions rule
timeline_id string

Timeline template ID

timeline_title string

Timeline template title

timestamp_override string

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

timestamp_override_fallback_disabled boolean

Disables the fallback to the event's @timestamp field

to string required
version integer · min: 1 required

The rule's version number.

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

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

created_at string · format: date-time required
created_by string required
id string · format: uuid required

A universally unique identifier

immutable boolean required deprecated

This field determines whether the rule is a prebuilt Elastic rule. It will be replaced with the rule_source field.

revision integer · min: 0 required

The rule's revision number.

It represents the version of rule's object in Kibana. It is set to 0 when the rule is installed or created and then gets incremented on each update.

Note

Not all updates to any rule fields will increment the revision. Only those fields that are considered static rule parameters can trigger revision increments. For example, an update to a rule's query or index fields will increment the rule's revision by 1. However, changes to dynamic or technical fields like enabled or execution_summary will not cause revision increments.

rule_id string required

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_source union oneOf required

Discriminated union that determines whether the rule is internally sourced (created within the Kibana app) or has an external source, such as the Elastic Prebuilt rules repo.

One of: (determined by type)
type: external

Type of rule source for externally sourced rules, i.e. rules that have an external source, such as the Elastic Prebuilt rules repo.

type enum required
Values: external
is_customized boolean required

Determines whether an external/prebuilt rule has been customized by the user (i.e. any of its fields have been modified and diverged from the base value).

updated_at string · format: date-time required
updated_by string required
language enum required
Values: eql
query string required

Query used by the rule to create alerts.

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

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

Note

This field is not supported for ES|QL rules.

index string[]

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

Note

This field is not supported for ES|QL rules.

tiebreaker_field string

Sets a secondary field for sorting events

timestamp_field string

Specifies the name of the event timestamp field used for sorting a sequence of events. Not to be confused with timestamp_override, which specifies the more general field used for querying events within a range. Defaults to the @timestamp ECS field.