IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.

« Find rules Delete rule »

› › ›

Update rule

edit

Update rule

edit

This API supports Token-based authentication only.

Updates an existing detection rule.

Console supports only Elasticsearch APIs. Console doesn’t allow interactions with Kibana APIs. You must use curl or another HTTP tool instead. For more information, refer to Run Elasticsearch API requests.

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

edit

PUT <kibana host>:<port>/api/detection_engine/rules

PATCH <kibana host>:<port>/api/detection_engine/rules

Request body

edit

A JSON object with:

The id or rule_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

edit

Name	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: `0` - `21` represents low severity `22` - `47` represents medium severity `48` - `73` represents high severity `74` - `100` represents critical severity
severity	String	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
type	String	Data type on which the rule is based: `eql`: EQL query (see Event Query Language). `query`: query with or without additional filters. `saved_query`: saved search, identified in the `saved_id` field. `machine_learning`: rule based on a machine learning job’s anomaly scores. `threat_match`: rule that matches event values with values in the specified Elasticsearch index. `threshold`: rule based on the number of times a `query` matches the specified field.

Field required for query, threat-match and threshold rules `PUT` calls

edit

Name	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

edit

Name	Type	Description
threshold	Object	Defines the field and threshold value for when alerts are generated, where: `field` (string, required): The field on which the threshold is applied. If you specify an empty field (`""`), alerts are generated when the query returns at least the number of results specified in the `value` field. `value` (integer, required): The threshold value from which an alert is generated.

Field required for saved-query rules `PUT` calls

edit

Name	Type	Description
saved_id	String	Kibana saved search used by the rule to create alerts.

Field required for EQL rules `PUT` calls

edit

Name	Type	Description
language	String	Must be `eql`.

Fields required for machine-learning rules `PUT` calls

edit

Name	Type	Description
anomaly_threshold	Integer	Anomaly score threshold above which the rule creates an alert. Valid values are from `0` to `100`.
machine_learning_job_id	String	Machine learning job ID the rule monitors for anomaly scores.

Fields required for threat-match rules `PUT` calls

edit

Name Type Description

Name	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 `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 below for an example that uses both `and` and `or` logic.

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 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 below for an example that uses both and and or logic.

Optional fields for all rule types

edit

Name	Type	Description
actions	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 `default`. For more information, About building block rules.
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	Time from which data is analyzed each time the rule executes, 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).
license	String	The rule’s license.
max_signals	Integer	Maximum number of alerts the rule can create during a single execution. Defaults to `100`.
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 `.siem-signals-<space_name>` index, where `<space_name>` is the name of the Kibana space in which the rule exists.
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	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: `no_actions`: Never `rule`: Every time new alerts are detected `1h`: Every hour `1d`: Every day `7d`: Every week Required when `actions` are used to send notifications.
version	Integer	The rule’s version number. If this is not provided, the rule’s version number is incremented by 1. `PATCH` calls enabling and disabling the rule do not increment its version number.

Optional fields for query, threat-match and EQL rules

edit

Name	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: `id` (string, required): ID of the exception container. `list_id` (string, required): List ID of the exception container. `namespace_type` (string required): Determines whether the exceptions are valid in only the rule’s Kibana space (`single`) or in all Kibana spaces (`agnostic`). `type` (string, required): The exception type, which must be either a detection rule exception (`detection`) or an endpoint exception (`endpoint`).

Optional fields for threat-match rules

edit

Name	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

edit

Name	Type	Description
language	String	Determines the query language, which must be `kuery` or `lucene`. Defaults to `kuery`.

Optional fields for EQL, query and threshold rules

edit

Name	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 → `securitySolution:defaultIndex`).
risk_score_mapping	Object[]	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`. This field must be an integer. `operator` (string, required): Must be `equals`. `value`(string, required): Must be an empty string (`""`).
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 in the Rule column on the Detections page). When unspecified, the rule’s `name` value is used. The source field must be a string data type.
severity_mapping	Object[]	Overrides generated alerts' `severity` with values from the source event: `field` (string, required): Source event field used to override the default `severity`. `operator` (string, required): Must be `equals`. `severity` (string, required): Mapped severity value, must be `low`, `medium`, `high`, or `critical`. `value`(string, required): Field value used to determine the `severity`.
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.

`actions` schema

edit

These 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: `.slack` `.email` `.pagerduty` `.webhook`
group	String	Optionally groups actions by use cases. Use `default` for alert notifications.
id	String	The connector ID.
params	Object	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.

`threat` schema

edit

These 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: `id` - string, required `name` - string, required `reference` - string, required
technique	Object	Object containing information on the attack technique: `id` - string, required `name` - string, required `reference` - string, required

Only threats described using the MITRE ATT&CK^TM framework are displayed in the UI (Security → Detections → Manage detection rules → <rule name>).

Example request

edit

Updates 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

edit

The 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
}

« Find rules Delete rule »

Update rule

Update rule

Request URL

Request body

Fields required for PUT calls

Field required for query, threat-match and threshold rules PUT calls

Field required for threshold rules PUT calls

Field required for saved-query rules PUT calls

Field required for EQL rules PUT calls

Fields required for machine-learning rules PUT calls

Fields required for threat-match rules PUT calls

Optional fields for all rule types

Optional fields for query, threat-match and EQL rules

Optional fields for threat-match rules

Optional fields for query, threat-match and threshold rules

Optional fields for EQL, query and threshold rules

actions schema

threat schema

Example request

Response code

Response payload

Fields required for `PUT` calls

Field required for query, threat-match and threshold rules `PUT` calls

Field required for threshold rules `PUT` calls

Field required for saved-query rules `PUT` calls

Field required for EQL rules `PUT` calls

Fields required for machine-learning rules `PUT` calls

Fields required for threat-match rules `PUT` calls

`actions` schema

`threat` schema