Update rule
editUpdate rule
editWhen 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.
Updates an existing detection rule.
You can use PUT
or PATCH
methods to update rules, where:
-
PUT
replaces the original rule and deletes fields that are not specified. -
PATCH
updates the specified fields.
Request URL
editPUT <kibana host>:<port>/api/detection_engine/rules
PATCH <kibana host>:<port>/api/detection_engine/rules
Request body
editA JSON object with:
-
The
id
orrule_id
field of the rule you want to update. - The fields you want to modify.
If you call PUT
to update a rule, all unspecified fields are
deleted. You cannot modify the id
or rule_id
values.
For PATCH
calls any of the fields can be modified, whereas for PUT
calls
some fields are required.
Fields required for PUT
calls
editName | Type | Description |
---|---|---|
description |
String |
The rule’s description. |
name |
String |
The rule’s name. |
risk_score |
Integer |
A numerical representation of the alert’s severity from 0 to 100, where:
|
severity |
String |
Severity level of alerts produced by the rule, which must be one of the following:
|
type |
String |
Data type on which the rule is based:
|
Field required for query, threat-match, threshold, and new terms rules PUT
calls
editName | Type | Description |
---|---|---|
query |
String |
Query used by the rule to create alerts. For threat-match rules, only the query’s results are used to determine whether an alert is generated. |
Field required for threshold rules PUT
calls
editName | Type | Description |
---|---|---|
threshold |
Object |
Defines the field and threshold value for when alerts are generated, where:
|
Field required for saved-query rules PUT
calls
editName | Type | Description |
---|---|---|
saved_id |
String |
Kibana saved search used by the rule to create alerts. |
Field required for EQL rules PUT
calls
editName | Type | Description |
---|---|---|
language |
String |
Must be |
Fields required for machine-learning rules PUT
calls
editName | Type | Description |
---|---|---|
anomaly_threshold |
Integer |
Anomaly score threshold above which the rule
creates an alert. Valid values are from |
machine_learning_job_id |
String |
Machine learning job ID the rule monitors for anomaly scores. |
Fields required for threat-match rules PUT
calls
editName | Type | Description |
---|---|---|
threat_index |
String[] |
Elasticsearch indices used to check which field values generate alerts. |
threat_query |
String |
Query used to determine which fields in the Elasticsearch index are used for generating alerts. |
threat_mapping |
Object[] |
Array of
You can use Boolean |
Fields required for new terms rules PUT
calls
editName | Type | Description |
---|---|---|
new_terms_fields |
String[] |
Fields to monitor for new values. Must contain 1–3 field names. |
history_window_start |
String |
Start date to use when checking if a term has been seen before.
Supports relative dates – for example, |
Optional fields for all rule types
editName | Type | Description |
---|---|---|
actions |
Array defining the automated actions (notifications) taken when alerts are generated. |
|
author |
String[] |
The rule’s author. |
building_block_type |
String |
Determines if the rule acts as a building block.
By default, building-block alerts are not displayed in the UI. These rules are
used as a foundation for other rules that do generate alerts. Its value must be
|
enabled |
Boolean |
Determines whether the rule is enabled. Defaults to |
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 |
Time from which data is analyzed each time the rule executes,
using a date math range. For example,
|
interval |
String |
Frequency of rule execution, using a
date math range. For example, |
license |
String |
The rule’s license. |
max_signals |
Integer |
Maximum number of alerts the rule can create during a
single execution. Defaults to |
meta |
Object |
Placeholder for metadata about the rule. NOTE: This field is overwritten when you save changes to the rule’s settings. |
note |
String |
Notes to help investigate alerts produced by the rule. |
references |
String[] |
Array containing notes about or references to relevant information about the rule. Defaults to an empty array. |
tags |
String[] |
String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array. |
threat |
Object containing attack information about the type of threat the rule monitors, see ECS threat fields. Defaults to an empty array. |
|
throttle |
String |
Determines how often actions are taken:
Required when |
version |
Integer |
The rule’s version number. If this is not provided, the rule’s version number is incremented by 1.
|
Optional fields for query, threat-match, EQL, and new terms rules
editName | Type | Description |
---|---|---|
exceptions_list |
Object[] |
Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met. The object has these fields:
|
Optional fields for threat-match rules
editName | Type | Description |
---|---|---|
threat_filters |
Object[] |
Query and filter context array used to filter documents from the Elasticsearch index containing the threat values. |
threat_indicator_path |
String |
Much like an ingest processor, users can use this field to define where their threat indicator can be found on their indicator documents. Defaults to |
Optional fields for query, threat-match, threshold, and new terms rules
editName | Type | Description |
---|---|---|
language |
String |
Determines the query language, which must be
|
Optional fields for EQL, query, threshold, and new terms rules
editName | Type | Description |
---|---|---|
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. |
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 →
|
risk_score_mapping |
Object[] |
Overrides generated alerts'
|
rule_name_override |
String |
Sets which field in the source event is used to
populate the alert’s |
severity_mapping |
Object[] |
Overrides generated alerts'
|
timestamp_override |
String |
Sets the time field used to query indices.
When unspecified, rules query the |
Optional fields for EQL rules
editName | Type | Description |
---|---|---|
event_category_field |
String |
Contains the event classification, such as |
tiebreaker_field |
String |
Sets a secondary field for sorting events (in ascending, lexicographic order) if they have the same timestamp. |
timestamp_field |
String |
Contains the event timestamp used for sorting a sequence of events. This is different from |
actions
schema
editThese fields are required when calling PUT
to modify the actions
object:
Name | Type | Description |
---|---|---|
action_type_id |
String |
The action type used for sending notifications, can be:
|
group |
String |
Optionally groups actions by use cases. Use |
id |
String |
The connector ID. |
params |
Object |
Object containing the allowed connector fields, which varies according to the connector type:
|
threat
schema
editThese fields are required when calling PUT
to modify the threat
object:
Name | Type | Description |
---|---|---|
framework |
String |
Relevant attack framework. |
tactic |
Object |
Object containing information on the attack type:
|
technique |
Object |
Object containing information on the attack technique:
|
Only threats described using the MITRE ATT&CKTM framework are displayed in the UI (Manage → Rules → Rule name).
Optional alert suppression fields for query rules
editThis functionality is in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features.
Name | Type | Description |
---|---|---|
alert_suppression |
Object |
Defines alert suppression configuration. Available fields:
|
Example request
editUpdates the threat
object:
PATCH api/detection_engine/rules { "rule_id": "process_started_by_ms_office_program_possible_payload", "threat": [ { "framework": "MITRE ATT&CK", "tactic": { "id": "TA0001", "reference": "https://attack.mitre.org/tactics/TA0001", "name": "Initial Access" }, "technique": [ { "id": "T1193", "name": "Spearphishing Attachment", "reference": "https://attack.mitre.org/techniques/T1193" } ] } ] }
Response code
edit-
200
- Indicates a successful call.
Response payload
editThe rule’s updated JSON object, including the time the rule was updated and an incremented version number.
Example response:
{ "created_at": "2020-01-05T09:56:11.805Z", "updated_at": "2020-01-05T09:59:59.129Z", "created_by": "elastic", "description": "Process started by MS Office program - possible payload", "enabled": false, "false_positives": [], "filters": [ { "query": { "match": { "event.action": { "query": "Process Create (rule: ProcessCreate)", "type": "phrase" } } } } ], "from": "now-6m", "id": "4f228868-9928-47e4-9785-9a1a9b520c7f", "interval": "5m", "rule_id": "process_started_by_ms_office_program_possible_payload", "language": "kuery", "max_signals": 100, "risk_score": 50, "name": "MS Office child process", "query": "process.parent.name:EXCEL.EXE or process.parent.name:MSPUB.EXE or process.parent.name:OUTLOOK.EXE or process.parent.name:POWERPNT.EXE or process.parent.name:VISIO.EXE or process.parent.name:WINWORD.EXE", "references": [], "severity": "low", "updated_by": "elastic", "tags": [ "child process", "ms office" ], "related_integrations": [], "required_fields": [], "setup": "", "type": "query", "threat": [ { "framework": "MITRE ATT&CK", "tactic": { "id": "TA0001", "reference": "https://attack.mitre.org/tactics/TA0001", "name": "Initial Access" }, "technique": [ { "id": "T1193", "name": "Spearphishing Attachment", "reference": "https://attack.mitre.org/techniques/T1193" } ] } ], "execution_summary": { "last_execution": { "date": "2022-03-23T16:06:12.787Z", "status": "partial failure", "status_order": 20, "message": "This rule attempted to query data from Elasticsearch indices listed in the \"Index pattern\" section of the rule definition, but no matching index was found.", "metrics": { "total_search_duration_ms": 135, "total_indexing_duration_ms": 15, "execution_gap_duration_s": 0, } } }, "version": 2 }
[dev]
This functionality is in development and may be changed or removed completely in a future release. These features are unsupported and not subject to the support SLA of official GA features.
These fields are under development and their usage or schema may change: |