« Find rules Delete rule »
Elastic Docs ›Elastic Security Solution [8.16] ›Elastic Security APIs ›Detections API

Update rule

edit

Update rule

edit

New API Reference

For the most up-to-date API details, refer to detections APIs.

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.

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

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).
  • esql: ES|QL query (refer to Elasticsearch 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.
  • new_terms: rule that alerts on values that have not been seen before

Field required for query, threat-match, threshold, and new terms 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:

  • cardinality (Array of length 1): The field on which the cardinality is applied.
  • cardinality.field (string, required): The field on which to calculate and compare the cardinality.
  • cardinality.value (integer, required): The threshold value from which an alert is generated based on unique number of values of cardinality.field.
  • field (string or 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.
  • 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.

Field required for ES|QL rules PUT calls

edit
Name Type Description

language

String

Must be esql.

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

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.

Fields required for new terms rules PUT calls

edit
Name 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, 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.

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, refer to 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 run (the rule’s Max alerts per run advanced setting value). Defaults to 100.

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.

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.

required_fields

Object[]

Elasticsearch fields and their types that need to be present for the rule to function. The object has these fields:

  • name (string, required): The field’s name.
  • type (string, required): The field’s data type.
  • ecs (Boolean, optional): Indicates whether the field is ECS-compliant. This property is only present in responses. Its value is computed based on field’s name and type.

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.

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.

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:

The rule level throttle field is deprecated in Elastic Security 8.8 and will remain active for at least the next 12 months.

In Elastic Security 8.8 and later, you can use the (frequency) field to define frequencies for individual actions. Actions without frequencies will acquire a converted version of the rule’s throttle field. In the response, the converted throttle setting appears in the individual actions' frequency field.

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

related_integrations

Object[]

Elastic integrations the rule depends on. The object has these fields:

  • package (String, required): The integration package’s name, as used by the Elastic Package Registry.
  • integration (String, optional): The integration’s name. This field is optional for packages with only one integration whose name matches the package name, but it’s required for packages with multiple integrations.
  • version: (String, required): Integration (package containing the integration) version constraint in semantic versioning format. For version ranges, you must use tilde or caret syntax. For example, ~1.2.3 is from 1.2.3 to any patch version less than 1.3.0, and ^1.2.3 is from 1.2.3` to any minor and patch version less than 2.0.0.

Optional fields for threat-match rules

edit
Name 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 threatintel.indicator.

Optional fields for query, threat-match, threshold, and new terms 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, threshold, indicator match, new terms rules, and ES|QL 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.

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

This field is not supported for ES|QL rules.

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

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.

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 EQL rules

edit
Name Type Description

event_category_field

String

Contains the event classification, such as process, file, or network. This field is typically mapped as a field type in the keyword family. Defaults to the event.category ECS field.

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 timestamp_override, which is used for querying events within a range. Defaults to the @timestamp ECS field.

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
  • .slack_api
  • .email
  • .index
  • .pagerduty
  • .swimlane
  • .webhook
  • .servicenow
  • .servicenow-itom
  • .servicenow-sir
  • .jira
  • .resilient
  • .opsgenie
  • .teams
  • .torq
  • .tines
  • .d3security

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.
Optional action fields
edit
Name Type Description

frequency

String

Object containing an action’s frequency:

  • summary (Boolean, required): Defines whether to send notifications as a summary of alerts or for each generated alert.

  • notifyWhen (String, required`): Defines how often alerts generate actions. Valid values are:

    • onActiveAlert: Actions run when the alert is generated.
    • onThrottleInterval: Actions run on the specified throttle interval and summarize new alerts generated during that interval.
  • throttle (String, optional): Defines how often an alert generates repeated actions. This custom action interval must be specified in seconds, minutes, hours, or days. For example, 10m or 1h. This property is used only if notifyWhen is onThrottleInterval.

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 can 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 can 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)
      • end (String, required)
    • 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): A filter object, as defined in the kbn-es-query package.

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&CKTM framework are displayed in the UI (Rules → Detection rules (SIEM) → Rule name).

Optional alert suppression fields for query, indicator match, threshold, event correlation (non-sequence queries only), new terms, ES|QL, and machine learning rules

edit

Alert suppression is in technical preview for event correlation rules. The functionality 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.

Query, indicator match, event correlation (non-sequence queries only), new terms, ES|QL, and machine learning rules
edit
Name Type Description

alert_suppression

Object

Defines alert suppression configuration. Available fields:

  • group_by (string[], required): An array of 1-3 field names to use for suppressing alerts.
  • duration (duration object, optional): The time period in which alerts will be suppressed, beginning when the rule first meets its criteria and creates the alert. If not specified, alerts will be suppressed on rule execution only.

  • missing_fields_strategy (string, optional): Defines how to handle events with missing suppression fields. Possible values:

    • doNotSuppress: Create a separate alert for each matching event.
    • suppress: Create one alert for each group of events with missing fields.
Threshold rule
edit
Name Type Description

alert_suppression

Object

Defines alert suppression configuration. Available fields:

* duration (duration object, required): The time period in which alerts will be suppressed, beginning when the rule first meets its criteria and creates the alert.

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",
  "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": [
    { "package": "o365", "version": "^2.3.2"}
  ],
  "required_fields": [
    { "name": "process.parent.name", "type": "keyword", "ecs": true }
  ],
  "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: execution_summary.
« Find rules Delete rule »