Update rule
editUpdate rule
editUpdates 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 and threshold 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 |
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 |
String |
Notes to help investigate alerts produced by the rule. |
output_index |
String |
Index to which alerts created by the rule are saved.
If unspecified alerts are saved to |
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 and EQL 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_filter |
Object[] |
Query and filter context array used to filter documents from the Elasticsearch index containing the threat values. |
Optional fields for query, threat-match and threshold rules
editName | Type | Description |
---|---|---|
language |
String |
Determines the query language, which must be
|
Optional fields for EQL, query and threshold 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 |
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 (Security → Detections → Manage detection rules → <rule name>).
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", "output_index": ".siem-signals-default", "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" ], "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" } ] } ], "version": 2 }