Retrieve a detection rule

Base URL
https://{kibana_url}
  • GET /api/detection_engine/rules
  • GET /s/{space_id}/api/detection_engine/rules
Auth

Retrieve a detection rule using the rule_id or id field.

The URL query must include one of the following:

  • id - GET /api/detection_engine/rules?id=<id>
  • rule_id - GET /api/detection_engine/rules?rule_id=<rule_id>

The difference between the id and rule_id is that the id is a unique rule identifier that is randomly generated when a rule is created and cannot be set, whereas rule_id is a stable rule identifier that can be assigned during rule creation.

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.

Query parameters

id string · format: uuid

The rule's id value.

rule_id string

The rule's rule_id value.

Response

Indicates a successful call.

Note

These fields are under development and their usage or schema may change: execution_summary.

application/json
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.

action_type_id string required

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
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 will 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 will 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): Start time in hh:mm format.
      • end (string, required): End time in hh:mm format.
    • 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): Array of filter objects, as defined in the kbn-es-query package.
frequency object

The action frequency defines when the action runs (for example, only on rule execution or at specific time intervals).

notifyWhen enum required

Defines how often rules run actions.

Values: onActiveAlert onThrottleInterval onActionGroupChange
summary boolean required

Action summary indicates whether we will send a summary notification about all the generate alerts or notification per individual alert

throttle union oneOf required

Defines how often rule actions are taken.

Values: no_actions rule
group string

Optionally groups actions by use cases. Use default for alert notifications.

id string required

The connector ID.

params object required

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.
uuid string · format: nonempty · min length: 1

A string that does not contain only whitespace characters

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

investigation_fields object

Schema for fields relating to investigation fields. These are user defined fields we use to highlight in various features in the UI such as alert details flyout and exceptions auto-population from alert.

field_names string[] · format: nonempty · min items: 1 required
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[]
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"}}

<string> object
field string
value union string | string[]
pack_id string

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

queries object[]
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"}}

<string> object
field string
value union string | string[]
id string required

Query ID

platform string
query string required

Query to run

removed boolean
snapshot boolean
version string

Query version

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

Relevant attack framework

tactic object required

Object containing information on the attack type

id string required

Tactic ID

name string required

Tactic name

reference string required

Tactic reference

technique object[]

Array containing information on the attack techniques (optional)

id string required

Technique ID

name string required

Technique name

reference string required

Technique reference

subtechnique object[]

Array containing more specific information on the attack technique.

id string required

Subtechnique ID

name string required

Subtechnique name

reference string required

Subtechnique reference

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
execution_summary object

Summary of the last execution of a rule.

Note

This field is under development and its usage or schema may change

last_execution object required
date string · format: date-time required

Date of the last execution

message string required
metrics object required
execution_gap_duration_s integer · min: 0

Duration in seconds of execution gap

frozen_indices_queried_count integer · min: 0

Count of frozen indices queried during the rule execution. These indices could not be entirely excluded after applying the time range filter.

gap_range object

Range of the execution gap

gte string required

Start date of the execution gap

lte string required

End date of the execution gap

total_enrichment_duration_ms integer · min: 0

Total time spent enriching documents during current rule execution cycle

total_indexing_duration_ms integer · min: 0

Total time spent indexing documents during current rule execution cycle

total_search_duration_ms integer · min: 0

Total time spent performing ES searches as measured by Kibana; includes network latency and time spent serializing/deserializing request/response

status enum required

Custom execution status of Security rules that is different from the status used in the Alerting Framework. We merge our custom status with the Framework's status to determine the resulting status of a rule.

  • going to run - @deprecated Replaced by the 'running' status but left for backwards compatibility with rule execution events already written to Event Log in the prior versions of Kibana. Don't use when writing rule status changes.
  • running - Rule execution started but not reached any intermediate or final status.
  • partial failure - Rule can partially fail for various reasons either in the middle of an execution (in this case we update its status right away) or in the end of it. So currently this status can be both intermediate and final at the same time. A typical reason for a partial failure: not all the indices that the rule searches over actually exist.
  • failed - Rule failed to execute due to unhandled exception or a reason defined in the business logic of its executor function.
  • succeeded - Rule executed successfully without any issues. Note: this status is just an indication of a rule's "health". The rule might or might not generate any alerts despite of it.
Values: going to run running partial failure failed succeeded
status_order integer 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.
alert_suppression object

Defines alert suppression configuration.

duration object
unit enum required

Time unit

Values: s m h
value integer · min: 1 required
group_by string[] · min items: 1 · max items: 3 required
missing_fields_strategy enum

Describes how alerts will be generated for documents with missing suppress by fields: doNotSuppress - per each document a separate alert will be created suppress - only alert will be created per suppress by bucket

Values: doNotSuppress suppress
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.

Base URL
https://{kibana_url}