Kibana Serverless APIs
1.0.2

Base URL

https://<KIBANA_URL>

The Kibana REST APIs for Elastic serverless enable you to manage resources such as connectors, data views, and saved objects. The API calls are stateless. Each request that you make happens in isolation from other calls and must include all of the necessary information for Kibana to fulfill the request. API requests return JSON output, which is a format that is machine-readable and works well for automation.

To interact with Kibana APIs, use the following operations:

GET: Fetches the information.
POST: Adds new information.
PUT: Updates the existing information.
DELETE: Removes the information.

You can prepend any Kibana API endpoint with kbn: and run the request in Dev Tools → Console. For example:

GET kbn:/api/data_views

Documentation source and versions

This documentation is derived from the main branch of the kibana repository. It is provided under license Attribution-NonCommercial-NoDerivatives 4.0 International.

This is version 1.0.2 of this API documentation. Last update on May 6, 2025.

Authentication

Api key auth (http_api_key)

You must create an API key and use the encoded value in the request header. To learn about creating keys, go to API keys.

Get rule details

GET /api/alerting/rule/{id}

Path parameters

id string Required

The identifier for the rule.

Responses

200 application/json

Indicates a successful call.
Hide response attributes Show response attributes object
- actions array[object] Required
  
  Hide actions attributes Show actions attributes object
  
  alerts_filter object
  
  Defines a period that limits whether the action runs.
  
  Additional properties are NOT allowed.
  
  Hide alerts_filter attributes Show alerts_filter attributes object
  
  query object
  
  Additional properties are NOT allowed.
  
  Hide query attributes Show query attributes object
  
  dsl string
  
  A filter written in Elasticsearch Query Domain Specific Language (DSL).
  
  filters array[object] Required
  
  A filter written in Elasticsearch Query Domain Specific Language (DSL) as defined in the kbn-es-query package.
  
  Hide filters attributes Show filters attributes object
  
  $state object
  
  Additional properties are NOT allowed.
  
  Hide $state attribute Show $state attribute object
  
  store string Required
  
  A filter can be either specific to an application context or applied globally.
  
  Values are appState or globalState.
  
  meta object Required
  
  Additional properties are allowed.
  
  query object
  
  Additional properties are allowed.
  
  kql string Required
  
  A filter written in Kibana Query Language (KQL).
  
  timeframe object
  
  Additional properties are NOT allowed.
  
  Hide timeframe attributes Show timeframe attributes object
  
  days array[integer] Required
  
  Defines the days of the week that the action can run, represented as an array of numbers. For example, 1 represents Monday. An empty array is equivalent to specifying all the days of the week.
  
  Values are 1, 2, 3, 4, 5, 6, or 7.
  
  hours object Required
  
  Additional properties are NOT allowed.
  
  Hide hours attributes Show hours attributes object
  
  end string Required
  
  The end of the time frame in 24-hour notation (hh:mm).
  
  start string Required
  
  The start of the time frame in 24-hour notation (hh:mm).
  
  timezone string Required
  
  The ISO time zone for the hours values. Values such as UTC and UTC+1 also work but lack built-in daylight savings time support and are not recommended.
  
  connector_type_id string Required
  
  The type of connector. This property appears in responses but cannot be set in requests.
  
  frequency object
  
  Additional properties are NOT allowed.
  
  Hide frequency attributes Show frequency attributes object
  
  notify_when string Required
  
  Indicates how often alerts generate actions. Valid values include: onActionGroupChange: Actions run when the alert status changes; onActiveAlert: Actions run when the alert becomes active and at each check interval while the rule conditions are met; onThrottleInterval: Actions run when the alert becomes active and at the interval specified in the throttle property while the rule conditions are met. NOTE: You cannot specify notify_when at both the rule and action level. The recommended method is to set it for each action. If you set it at the rule level then update the rule in Kibana, it is automatically changed to use action-specific values.
  
  Values are onActionGroupChange, onActiveAlert, or onThrottleInterval.
  
  summary boolean Required
  
  Indicates whether the action is a summary.
  
  throttle string | null Required
  
  The throttle interval, which defines how often an alert generates repeated actions. It is specified in seconds, minutes, hours, or days and is applicable only if 'notify_when' is set to 'onThrottleInterval'. NOTE: You cannot specify the throttle interval at both the rule and action level. The recommended method is to set it for each action. If you set it at the rule level then update the rule in Kibana, it is automatically changed to use action-specific values.
  
  group string
  
  The group name, which affects when the action runs (for example, when the threshold is met or when the alert is recovered). Each rule type has a list of valid action group names. If you don't need to group actions, set to default.
  
  id string Required
  
  The identifier for the connector saved object.
  
  params object Required
  
  The parameters for the action, which are sent to the connector. The params are handled as Mustache templates and passed a default set of context.
  
  Additional properties are allowed.
  
  use_alert_data_for_template boolean
  
  Indicates whether to use alert data as a template.
  
  uuid string
  
  A universally unique identifier (UUID) for the action.
- active_snoozes array[string]
  
  List of active snoozes for the rule.
- alert_delay object
  
  Indicates that an alert occurs only when the specified number of consecutive runs met the rule conditions.
  
  Additional properties are NOT allowed.
  
  Hide alert_delay attribute Show alert_delay attribute object
  
  active number Required
  
  The number of consecutive runs that must meet the rule conditions.
- api_key_created_by_user boolean | null
  
  Indicates whether the API key that is associated with the rule was created by the user.
- api_key_owner string | null Required
  
  The owner of the API key that is associated with the rule and used to run background tasks.
- artifacts object
  
  Additional properties are NOT allowed.
  
  Hide artifacts attributes Show artifacts attributes object
  
  dashboards array[object]
  
  Hide dashboards attribute Show dashboards attribute object
  
  id string Required
  
  investigation_guide object
  
  Additional properties are NOT allowed.
  
  Hide investigation_guide attribute Show investigation_guide attribute object
  
  blob string Required
  
  User-created content that describes alert causes and remdiation.
- consumer string Required
  
  The name of the application or feature that owns the rule. For example: alerts, apm, discover, infrastructure, logs, metrics, ml, monitoring, securitySolution, siem, stackAlerts, or uptime.
- created_at string Required
  
  The date and time that the rule was created.
- created_by string | null Required
  
  The identifier for the user that created the rule.
- enabled boolean Required
  
  Indicates whether you want to run the rule on an interval basis after it is created.
- execution_status object Required
  
  Additional properties are NOT allowed.
  
  Hide execution_status attributes Show execution_status attributes object
  
  error object
  
  Additional properties are NOT allowed.
  
  Hide error attributes Show error attributes object
  
  message string Required
  
  Error message.
  
  reason string Required
  
  Reason for error.
  
  Values are read, decrypt, execute, unknown, license, timeout, disabled, or validate.
  
  last_duration number
  
  Duration of last execution of the rule.
  
  last_execution_date string Required
  
  The date and time when rule was executed last.
  
  status string Required
  
  Status of rule execution.
  
  Values are ok, active, error, warning, pending, or unknown.
  
  warning object
  
  Additional properties are NOT allowed.
  
  Hide warning attributes Show warning attributes object
  
  message string Required
  
  Warning message.
  
  reason string Required
  
  Reason for warning.
  
  Values are maxExecutableActions, maxAlerts, maxQueuedActions, or ruleExecution.
- flapping object | null
  
  When flapping detection is turned on, alerts that switch quickly between active and recovered states are identified as “flapping” and notifications are reduced.
  
  Additional properties are NOT allowed.
  
  Hide flapping attributes Show flapping attributes object | null
  
  look_back_window number Required
  
  The minimum number of runs in which the threshold must be met.
  
  Minimum value is 2, maximum value is 20.
  
  status_change_threshold number Required
  
  The minimum number of times an alert must switch states in the look back window.
  
  Minimum value is 2, maximum value is 20.
- id string Required
  
  The identifier for the rule.
- is_snoozed_until string | null
  
  The date when the rule will no longer be snoozed.
- last_run object | null
  
  Additional properties are NOT allowed.
  
  Hide last_run attributes Show last_run attributes object | null
  
  alerts_count object Required
  
  Additional properties are NOT allowed.
  
  Hide alerts_count attributes Show alerts_count attributes object
  
  active number | null
  
  Number of active alerts during last run.
  
  ignored number | null
  
  Number of ignored alerts during last run.
  
  new number | null
  
  Number of new alerts during last run.
  
  recovered number | null
  
  Number of recovered alerts during last run.
  
  outcome string Required
  
  Outcome of last run of the rule. Value could be succeeded, warning or failed.
  
  Values are succeeded, warning, or failed.
  
  outcome_msg array[string] | null
  
  Outcome message generated during last rule run.
  
  outcome_order number
  
  Order of the outcome.
  
  warning string | null
  
  Warning of last rule execution.
  
  Values are read, decrypt, execute, unknown, license, timeout, disabled, validate, maxExecutableActions, maxAlerts, maxQueuedActions, or ruleExecution.
- mapped_params object
  
  Additional properties are allowed.
- monitoring object
  
  Monitoring details of the rule.
  
  Additional properties are NOT allowed.
  
  Hide monitoring attribute Show monitoring attribute object
  
  run object Required
  
  Rule run details.
  
  Additional properties are NOT allowed.
  
  Hide run attributes Show run attributes object
  
  calculated_metrics object Required
  
  Calculation of different percentiles and success ratio.
  
  Additional properties are NOT allowed.
  
  Hide calculated_metrics attributes Show calculated_metrics attributes object
  
  p50 number
  
  p95 number
  
  p99 number
  
  success_ratio number Required
  
  history array[object] Required
  
  History of the rule run.
  
  Hide history attributes Show history attributes object
  
  duration number
  
  Duration of the rule run.
  
  outcome string
  
  Outcome of last run of the rule. Value could be succeeded, warning or failed.
  
  Values are succeeded, warning, or failed.
  
  success boolean Required
  
  Indicates whether the rule run was successful.
  
  timestamp number Required
  
  Time of rule run.
  
  last_run object Required
  
  Additional properties are NOT allowed.
  
  Hide last_run attributes Show last_run attributes object
  
  metrics object Required
  
  Additional properties are NOT allowed.
  
  Hide metrics attributes Show metrics attributes object
  
  duration number
  
  Duration of most recent rule run.
  
  gap_duration_s number | null
  
  Duration in seconds of rule run gap.
  
  gap_range object | null
  
  Additional properties are NOT allowed.
  
  Hide gap_range attributes Show gap_range attributes object | null
  
  gte string Required
  
  End of the gap range.
  
  lte string Required
  
  Start of the gap range.
  
  total_alerts_created number | null
  
  Total number of alerts created during last rule run.
  
  total_alerts_detected number | null
  
  Total number of alerts detected during last rule run.
  
  total_indexing_duration_ms number | null
  
  Total time spent indexing documents during last rule run in milliseconds.
  
  total_search_duration_ms number | null
  
  Total time spent performing Elasticsearch searches as measured by Kibana; includes network latency and time spent serializing or deserializing the request and response.
  
  timestamp string Required
  
  Time of the most recent rule run.
- mute_all boolean Required
  
  Indicates whether all alerts are muted.
- muted_alert_ids array[string] Required
  
  List of identifiers of muted alerts.
- name string Required
  
  The name of the rule.
- next_run string | null
  
  Date and time of the next run of the rule.
- notify_when string | null
  
  Indicates how often alerts generate actions. Valid values include: onActionGroupChange: Actions run when the alert status changes; onActiveAlert: Actions run when the alert becomes active and at each check interval while the rule conditions are met; onThrottleInterval: Actions run when the alert becomes active and at the interval specified in the throttle property while the rule conditions are met. NOTE: You cannot specify notify_when at both the rule and action level. The recommended method is to set it for each action. If you set it at the rule level then update the rule in Kibana, it is automatically changed to use action-specific values.
  
  Values are onActionGroupChange, onActiveAlert, or onThrottleInterval.
- params object Required
  
  The parameters for the rule.
  
  Additional properties are allowed.
- revision number Required
  
  The rule revision number.
- rule_type_id string Required
  
  The rule type identifier.
- running boolean | null
  
  Indicates whether the rule is running.
- schedule object Required
  
  Additional properties are NOT allowed.
  
  Hide schedule attribute Show schedule attribute object
  
  interval string Required
  
  The interval is specified in seconds, minutes, hours, or days.
- scheduled_task_id string
  
  Identifier of the scheduled task.
- snooze_schedule array[object]
  
  Hide snooze_schedule attributes Show snooze_schedule attributes object
  
  duration number Required
  
  Duration of the rule snooze schedule.
  
  id string
  
  Identifier of the rule snooze schedule.
  
  rRule object Required
  
  Additional properties are NOT allowed.
  
  Hide rRule attributes Show rRule attributes object
  
  byhour array[number] | null
  
  Indicates hours of the day to recur.
  
  byminute array[number] | null
  
  Indicates minutes of the hour to recur.
  
  bymonth array[number] | null
  
  Indicates months of the year that this rule should recur.
  
  bymonthday array[number] | null
  
  Indicates the days of the month to recur.
  
  bysecond array[number] | null
  
  Indicates seconds of the day to recur.
  
  bysetpos array[number] | null
  
  A positive or negative integer affecting the nth day of the month. For example, -2 combined with byweekday of FR is 2nd to last Friday of the month. It is recommended to not set this manually and just use byweekday.
  
  byweekday array[string | number] | null
  
  Indicates the days of the week to recur or else nth-day-of-month strings. For example, "+2TU" second Tuesday of month, "-1FR" last Friday of the month, which are internally converted to a byweekday/bysetpos combination.
  
  byweekno array[number] | null
  
  Indicates number of the week hours to recur.
  
  byyearday array[number] | null
  
  Indicates the days of the year that this rule should recur.
  
  count number
  
  Number of times the rule should recur until it stops.
  
  dtstart string Required
  
  Rule start date in Coordinated Universal Time (UTC).
  
  freq integer
  
  Indicates frequency of the rule. Options are YEARLY, MONTHLY, WEEKLY, DAILY.
  
  Values are 0, 1, 2, 3, 4, 5, or 6.
  
  interval number
  
  Indicates the interval of frequency. For example, 1 and YEARLY is every 1 year, 2 and WEEKLY is every 2 weeks.
  
  tzid string Required
  
  Indicates timezone abbreviation.
  
  until string
  
  Recur the rule until this date.
  
  wkst string
  
  Indicates the start of week, defaults to Monday.
  
  Values are MO, TU, WE, TH, FR, SA, or SU.
  
  skipRecurrences array[string]
  
  Skips recurrence of rule on this date.
- tags array[string] Required
  
  The tags for the rule.
- throttle string | null Deprecated
  
  Deprecated in 8.13.0. Use the throttle property in the action frequency object instead. The throttle interval, which defines how often an alert generates repeated actions. NOTE: You cannot specify the throttle interval at both the rule and action level. If you set it at the rule level then update the rule in Kibana, it is automatically changed to use action-specific values.
- updated_at string Required
  
  The date and time that the rule was updated most recently.
- updated_by string | null Required
  
  The identifier for the user that updated this rule most recently.
- view_in_app_relative_url string | null
  
  Relative URL to view rule in the app.
400

Indicates an invalid schema or parameters.
403

Indicates that this call is forbidden.
404

Indicates a rule with the given ID does not exist.

GET /api/alerting/rule/{id}

curl \
 --request GET 'https://<KIBANA_URL>/api/alerting/rule/{id}' \
 --header "Authorization: $API_KEY"

Update a rule

PUT /api/alerting/rule/{id}

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

Path parameters

id string Required

The identifier for the rule.

application/json

Body

actions array[object]

An action that runs under defined conditions.

Default value is [] (empty).
Hide actions attributes Show actions attributes object
- alerts_filter object
  
  Additional properties are NOT allowed.
  Hide alerts_filter attributes Show alerts_filter attributes object
  
  query object
  
  Additional properties are NOT allowed.
  
  Hide query attributes Show query attributes object
  
  dsl string
  
  A filter written in Elasticsearch Query Domain Specific Language (DSL).
  
  filters array[object] Required
  
  A filter written in Elasticsearch Query Domain Specific Language (DSL) as defined in the kbn-es-query package.
  
  Hide filters attributes Show filters attributes object
  
  $state object
  
  Additional properties are NOT allowed.
  
  Hide $state attribute Show $state attribute object
  
  store string Required
  
  A filter can be either specific to an application context or applied globally.
  
  Values are appState or globalState.
  
  meta object Required
  
  Additional properties are allowed.
  
  query object
  
  Additional properties are allowed.
  
  kql string Required
  
  A filter written in Kibana Query Language (KQL).
  
  timeframe object
  
  Defines a period that limits whether the action runs.
  
  Additional properties are NOT allowed.
  
  Hide timeframe attributes Show timeframe attributes object
  
  days array[integer] Required
  
  Defines the days of the week that the action can run, represented as an array of numbers. For example, 1 represents Monday. An empty array is equivalent to specifying all the days of the week.
  
  Values are 1, 2, 3, 4, 5, 6, or 7.
  
  hours object Required
  
  Defines the range of time in a day that the action can run. If the start value is 00:00 and the end value is 24:00, actions be generated all day.
  
  Additional properties are NOT allowed.
  
  Hide hours attributes Show hours attributes object
  
  end string Required
  
  The end of the time frame in 24-hour notation (hh:mm).
  
  start string Required
  
  The start of the time frame in 24-hour notation (hh:mm).
  
  timezone string Required
  
  The ISO time zone for the hours values. Values such as UTC and UTC+1 also work but lack built-in daylight savings time support and are not recommended.
- frequency object
  
  Additional properties are NOT allowed.
  Hide frequency attributes Show frequency attributes object
  
  notify_when string Required
  
  Indicates how often alerts generate actions. Valid values include: onActionGroupChange: Actions run when the alert status changes; onActiveAlert: Actions run when the alert becomes active and at each check interval while the rule conditions are met; onThrottleInterval: Actions run when the alert becomes active and at the interval specified in the throttle property while the rule conditions are met. NOTE: You cannot specify notify_when at both the rule and action level. The recommended method is to set it for each action. If you set it at the rule level then update the rule in Kibana, it is automatically changed to use action-specific values.
  
  Values are onActionGroupChange, onActiveAlert, or onThrottleInterval.
  
  summary boolean Required
  
  Indicates whether the action is a summary.
  
  throttle string | null Required
  
  The throttle interval, which defines how often an alert generates repeated actions. It is specified in seconds, minutes, hours, or days and is applicable only if notify_when is set to onThrottleInterval. NOTE: You cannot specify the throttle interval at both the rule and action level. The recommended method is to set it for each action. If you set it at the rule level then update the rule in Kibana, it is automatically changed to use action-specific values.
- group string
  
  The group name, which affects when the action runs (for example, when the threshold is met or when the alert is recovered). Each rule type has a list of valid action group names. If you don't need to group actions, set to default.
- id string Required
  
  The identifier for the connector saved object.
- params object
  
  The parameters for the action, which are sent to the connector. The params are handled as Mustache templates and passed a default set of context.
  
  Default value is {} (empty). Additional properties are allowed.
- use_alert_data_for_template boolean
  
  Indicates whether to use alert data as a template.
- uuid string
  
  A universally unique identifier (UUID) for the action.
alert_delay object

Indicates that an alert occurs only when the specified number of consecutive runs met the rule conditions.

Additional properties are NOT allowed.
Hide alert_delay attribute Show alert_delay attribute object
- active number Required
  
  The number of consecutive runs that must meet the rule conditions.
artifacts object

Additional properties are NOT allowed.
Hide artifacts attributes Show artifacts attributes object
- dashboards array[object]
  
  Not more than 10 elements.
  Hide dashboards attribute Show dashboards attribute object
  
  id string Required
- investigation_guide object
  
  Additional properties are NOT allowed.
  Hide investigation_guide attribute Show investigation_guide attribute object
  
  blob string Required
  
  Maximum length is 1000.
flapping object | null

When flapping detection is turned on, alerts that switch quickly between active and recovered states are identified as “flapping” and notifications are reduced.

Additional properties are NOT allowed.
Hide flapping attributes Show flapping attributes object | null
- look_back_window number Required
  
  The minimum number of runs in which the threshold must be met.
  
  Minimum value is 2, maximum value is 20.
- status_change_threshold number Required
  
  The minimum number of times an alert must switch states in the look back window.
  
  Minimum value is 2, maximum value is 20.
name string Required

The name of the rule. While this name does not have to be unique, a distinctive name can help you identify a rule.
notify_when string | null

Indicates how often alerts generate actions. Valid values include: onActionGroupChange: Actions run when the alert status changes; onActiveAlert: Actions run when the alert becomes active and at each check interval while the rule conditions are met; onThrottleInterval: Actions run when the alert becomes active and at the interval specified in the throttle property while the rule conditions are met. NOTE: You cannot specify notify_when at both the rule and action level. The recommended method is to set it for each action. If you set it at the rule level then update the rule in Kibana, it is automatically changed to use action-specific values.

Values are onActionGroupChange, onActiveAlert, or onThrottleInterval.
params object

The parameters for the rule.

Default value is {} (empty). Additional properties are allowed.
schedule object Required

Additional properties are NOT allowed.
Hide schedule attribute Show schedule attribute object
- interval string Required
  
  The interval is specified in seconds, minutes, hours, or days.
tags array[string]

The tags for the rule.

Default value is [] (empty).
throttle string | null

Use the throttle property in the action frequency object instead. The throttle interval, which defines how often an alert generates repeated actions. NOTE: You cannot specify the throttle interval at both the rule and action level. If you set it at the rule level then update the rule in Kibana, it is automatically changed to use action-specific values.

Responses

200 application/json

Indicates a successful call.
Hide response attributes Show response attributes object
- actions array[object] Required
  
  Hide actions attributes Show actions attributes object
  
  alerts_filter object
  
  Defines a period that limits whether the action runs.
  
  Additional properties are NOT allowed.
  
  Hide alerts_filter attributes Show alerts_filter attributes object
  
  query object
  
  Additional properties are NOT allowed.
  
  Hide query attributes Show query attributes object
  
  dsl string
  
  A filter written in Elasticsearch Query Domain Specific Language (DSL).
  
  filters array[object] Required
  
  A filter written in Elasticsearch Query Domain Specific Language (DSL) as defined in the kbn-es-query package.
  
  Hide filters attributes Show filters attributes object
  
  $state object
  
  Additional properties are NOT allowed.
  
  Hide $state attribute Show $state attribute object
  
  store string Required
  
  A filter can be either specific to an application context or applied globally.
  
  Values are appState or globalState.
  
  meta object Required
  
  Additional properties are allowed.
  
  query object
  
  Additional properties are allowed.
  
  kql string Required
  
  A filter written in Kibana Query Language (KQL).
  
  timeframe object
  
  Additional properties are NOT allowed.
  
  Hide timeframe attributes Show timeframe attributes object
  
  days array[integer] Required
  
  Defines the days of the week that the action can run, represented as an array of numbers. For example, 1 represents Monday. An empty array is equivalent to specifying all the days of the week.
  
  Values are 1, 2, 3, 4, 5, 6, or 7.
  
  hours object Required
  
  Additional properties are NOT allowed.
  
  Hide hours attributes Show hours attributes object
  
  end string Required
  
  The end of the time frame in 24-hour notation (hh:mm).
  
  start string Required
  
  The start of the time frame in 24-hour notation (hh:mm).
  
  timezone string Required
  
  The ISO time zone for the hours values. Values such as UTC and UTC+1 also work but lack built-in daylight savings time support and are not recommended.
  
  connector_type_id string Required
  
  The type of connector. This property appears in responses but cannot be set in requests.
  
  frequency object
  
  Additional properties are NOT allowed.
  
  Hide frequency attributes Show frequency attributes object
  
  notify_when string Required
  
  Indicates how often alerts generate actions. Valid values include: onActionGroupChange: Actions run when the alert status changes; onActiveAlert: Actions run when the alert becomes active and at each check interval while the rule conditions are met; onThrottleInterval: Actions run when the alert becomes active and at the interval specified in the throttle property while the rule conditions are met. NOTE: You cannot specify notify_when at both the rule and action level. The recommended method is to set it for each action. If you set it at the rule level then update the rule in Kibana, it is automatically changed to use action-specific values.
  
  Values are onActionGroupChange, onActiveAlert, or onThrottleInterval.
  
  summary boolean Required
  
  Indicates whether the action is a summary.
  
  throttle string | null Required
  
  The throttle interval, which defines how often an alert generates repeated actions. It is specified in seconds, minutes, hours, or days and is applicable only if 'notify_when' is set to 'onThrottleInterval'. NOTE: You cannot specify the throttle interval at both the rule and action level. The recommended method is to set it for each action. If you set it at the rule level then update the rule in Kibana, it is automatically changed to use action-specific values.
  
  group string
  
  The group name, which affects when the action runs (for example, when the threshold is met or when the alert is recovered). Each rule type has a list of valid action group names. If you don't need to group actions, set to default.
  
  id string Required
  
  The identifier for the connector saved object.
  
  params object Required
  
  The parameters for the action, which are sent to the connector. The params are handled as Mustache templates and passed a default set of context.
  
  Additional properties are allowed.
  
  use_alert_data_for_template boolean
  
  Indicates whether to use alert data as a template.
  
  uuid string
  
  A universally unique identifier (UUID) for the action.
- active_snoozes array[string]
  
  List of active snoozes for the rule.
- alert_delay object
  
  Indicates that an alert occurs only when the specified number of consecutive runs met the rule conditions.
  
  Additional properties are NOT allowed.
  
  Hide alert_delay attribute Show alert_delay attribute object
  
  active number Required
  
  The number of consecutive runs that must meet the rule conditions.
- api_key_created_by_user boolean | null
  
  Indicates whether the API key that is associated with the rule was created by the user.
- api_key_owner string | null Required
  
  The owner of the API key that is associated with the rule and used to run background tasks.
- artifacts object
  
  Additional properties are NOT allowed.
  
  Hide artifacts attributes Show artifacts attributes object
  
  dashboards array[object]
  
  Hide dashboards attribute Show dashboards attribute object
  
  id string Required
  
  investigation_guide object
  
  Additional properties are NOT allowed.
  
  Hide investigation_guide attribute Show investigation_guide attribute object
  
  blob string Required
  
  User-created content that describes alert causes and remdiation.
- consumer string Required
  
  The name of the application or feature that owns the rule. For example: alerts, apm, discover, infrastructure, logs, metrics, ml, monitoring, securitySolution, siem, stackAlerts, or uptime.
- created_at string Required
  
  The date and time that the rule was created.
- created_by string | null Required
  
  The identifier for the user that created the rule.
- enabled boolean Required
  
  Indicates whether you want to run the rule on an interval basis after it is created.
- execution_status object Required
  
  Additional properties are NOT allowed.
  
  Hide execution_status attributes Show execution_status attributes object
  
  error object
  
  Additional properties are NOT allowed.
  
  Hide error attributes Show error attributes object
  
  message string Required
  
  Error message.
  
  reason string Required
  
  Reason for error.
  
  Values are read, decrypt, execute, unknown, license, timeout, disabled, or validate.
  
  last_duration number
  
  Duration of last execution of the rule.
  
  last_execution_date string Required
  
  The date and time when rule was executed last.
  
  status string Required
  
  Status of rule execution.
  
  Values are ok, active, error, warning, pending, or unknown.
  
  warning object
  
  Additional properties are NOT allowed.
  
  Hide warning attributes Show warning attributes object
  
  message string Required
  
  Warning message.
  
  reason string Required
  
  Reason for warning.
  
  Values are maxExecutableActions, maxAlerts, maxQueuedActions, or ruleExecution.
- flapping object | null
  
  When flapping detection is turned on, alerts that switch quickly between active and recovered states are identified as “flapping” and notifications are reduced.
  
  Additional properties are NOT allowed.
  
  Hide flapping attributes Show flapping attributes object | null
  
  look_back_window number Required
  
  The minimum number of runs in which the threshold must be met.
  
  Minimum value is 2, maximum value is 20.
  
  status_change_threshold number Required
  
  The minimum number of times an alert must switch states in the look back window.
  
  Minimum value is 2, maximum value is 20.
- id string Required
  
  The identifier for the rule.
- is_snoozed_until string | null
  
  The date when the rule will no longer be snoozed.
- last_run object | null
  
  Additional properties are NOT allowed.
  
  Hide last_run attributes Show last_run attributes object | null
  
  alerts_count object Required
  
  Additional properties are NOT allowed.
  
  Hide alerts_count attributes Show alerts_count attributes object
  
  active number | null
  
  Number of active alerts during last run.
  
  ignored number | null
  
  Number of ignored alerts during last run.
  
  new number | null
  
  Number of new alerts during last run.
  
  recovered number | null
  
  Number of recovered alerts during last run.
  
  outcome string Required
  
  Outcome of last run of the rule. Value could be succeeded, warning or failed.
  
  Values are succeeded, warning, or failed.
  
  outcome_msg array[string] | null
  
  Outcome message generated during last rule run.
  
  outcome_order number
  
  Order of the outcome.
  
  warning string | null
  
  Warning of last rule execution.
  
  Values are read, decrypt, execute, unknown, license, timeout, disabled, validate, maxExecutableActions, maxAlerts, maxQueuedActions, or ruleExecution.
- mapped_params object
  
  Additional properties are allowed.
- monitoring object
  
  Monitoring details of the rule.
  
  Additional properties are NOT allowed.
  
  Hide monitoring attribute Show monitoring attribute object
  
  run object Required
  
  Rule run details.
  
  Additional properties are NOT allowed.
  
  Hide run attributes Show run attributes object
  
  calculated_metrics object Required
  
  Calculation of different percentiles and success ratio.
  
  Additional properties are NOT allowed.
  
  Hide calculated_metrics attributes Show calculated_metrics attributes object
  
  p50 number
  
  p95 number
  
  p99 number
  
  success_ratio number Required
  
  history array[object] Required
  
  History of the rule run.
  
  Hide history attributes Show history attributes object
  
  duration number
  
  Duration of the rule run.
  
  outcome string
  
  Outcome of last run of the rule. Value could be succeeded, warning or failed.
  
  Values are succeeded, warning, or failed.
  
  success boolean Required
  
  Indicates whether the rule run was successful.
  
  timestamp number Required
  
  Time of rule run.
  
  last_run object Required
  
  Additional properties are NOT allowed.
  
  Hide last_run attributes Show last_run attributes object
  
  metrics object Required
  
  Additional properties are NOT allowed.
  
  Hide metrics attributes Show metrics attributes object
  
  duration number
  
  Duration of most recent rule run.
  
  gap_duration_s number | null
  
  Duration in seconds of rule run gap.
  
  gap_range object | null
  
  Additional properties are NOT allowed.
  
  Hide gap_range attributes Show gap_range attributes object | null
  
  gte string Required
  
  End of the gap range.
  
  lte string Required
  
  Start of the gap range.
  
  total_alerts_created number | null
  
  Total number of alerts created during last rule run.
  
  total_alerts_detected number | null
  
  Total number of alerts detected during last rule run.
  
  total_indexing_duration_ms number | null
  
  Total time spent indexing documents during last rule run in milliseconds.
  
  total_search_duration_ms number | null
  
  Total time spent performing Elasticsearch searches as measured by Kibana; includes network latency and time spent serializing or deserializing the request and response.
  
  timestamp string Required
  
  Time of the most recent rule run.
- mute_all boolean Required
  
  Indicates whether all alerts are muted.
- muted_alert_ids array[string] Required
  
  List of identifiers of muted alerts.
- name string Required
  
  The name of the rule.
- next_run string | null
  
  Date and time of the next run of the rule.
- notify_when string | null
  
  Indicates how often alerts generate actions. Valid values include: onActionGroupChange: Actions run when the alert status changes; onActiveAlert: Actions run when the alert becomes active and at each check interval while the rule conditions are met; onThrottleInterval: Actions run when the alert becomes active and at the interval specified in the throttle property while the rule conditions are met. NOTE: You cannot specify notify_when at both the rule and action level. The recommended method is to set it for each action. If you set it at the rule level then update the rule in Kibana, it is automatically changed to use action-specific values.
  
  Values are onActionGroupChange, onActiveAlert, or onThrottleInterval.
- params object Required
  
  The parameters for the rule.
  
  Additional properties are allowed.
- revision number Required
  
  The rule revision number.
- rule_type_id string Required
  
  The rule type identifier.
- running boolean | null
  
  Indicates whether the rule is running.
- schedule object Required
  
  Additional properties are NOT allowed.
  
  Hide schedule attribute Show schedule attribute object
  
  interval string Required
  
  The interval is specified in seconds, minutes, hours, or days.
- scheduled_task_id string
  
  Identifier of the scheduled task.
- snooze_schedule array[object]
  
  Hide snooze_schedule attributes Show snooze_schedule attributes object
  
  duration number Required
  
  Duration of the rule snooze schedule.
  
  id string
  
  Identifier of the rule snooze schedule.
  
  rRule object Required
  
  Additional properties are NOT allowed.
  
  Hide rRule attributes Show rRule attributes object
  
  byhour array[number] | null
  
  Indicates hours of the day to recur.
  
  byminute array[number] | null
  
  Indicates minutes of the hour to recur.
  
  bymonth array[number] | null
  
  Indicates months of the year that this rule should recur.
  
  bymonthday array[number] | null
  
  Indicates the days of the month to recur.
  
  bysecond array[number] | null
  
  Indicates seconds of the day to recur.
  
  bysetpos array[number] | null
  
  A positive or negative integer affecting the nth day of the month. For example, -2 combined with byweekday of FR is 2nd to last Friday of the month. It is recommended to not set this manually and just use byweekday.
  
  byweekday array[string | number] | null
  
  Indicates the days of the week to recur or else nth-day-of-month strings. For example, "+2TU" second Tuesday of month, "-1FR" last Friday of the month, which are internally converted to a byweekday/bysetpos combination.
  
  byweekno array[number] | null
  
  Indicates number of the week hours to recur.
  
  byyearday array[number] | null
  
  Indicates the days of the year that this rule should recur.
  
  count number
  
  Number of times the rule should recur until it stops.
  
  dtstart string Required
  
  Rule start date in Coordinated Universal Time (UTC).
  
  freq integer
  
  Indicates frequency of the rule. Options are YEARLY, MONTHLY, WEEKLY, DAILY.
  
  Values are 0, 1, 2, 3, 4, 5, or 6.
  
  interval number
  
  Indicates the interval of frequency. For example, 1 and YEARLY is every 1 year, 2 and WEEKLY is every 2 weeks.
  
  tzid string Required
  
  Indicates timezone abbreviation.
  
  until string
  
  Recur the rule until this date.
  
  wkst string
  
  Indicates the start of week, defaults to Monday.
  
  Values are MO, TU, WE, TH, FR, SA, or SU.
  
  skipRecurrences array[string]
  
  Skips recurrence of rule on this date.
- tags array[string] Required
  
  The tags for the rule.
- throttle string | null Deprecated
  
  Deprecated in 8.13.0. Use the throttle property in the action frequency object instead. The throttle interval, which defines how often an alert generates repeated actions. NOTE: You cannot specify the throttle interval at both the rule and action level. If you set it at the rule level then update the rule in Kibana, it is automatically changed to use action-specific values.
- updated_at string Required
  
  The date and time that the rule was updated most recently.
- updated_by string | null Required
  
  The identifier for the user that updated this rule most recently.
- view_in_app_relative_url string | null
  
  Relative URL to view rule in the app.
400

Indicates an invalid schema or parameters.
403

Indicates that this call is forbidden.
404

Indicates a rule with the given ID does not exist.
409

Indicates that the rule has already been updated by another user.

PUT /api/alerting/rule/{id}

curl \
 --request PUT 'https://<KIBANA_URL>/api/alerting/rule/{id}' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"name":"new name","tags":[],"params":{"index":[".updated-index"],"aggType":"avg","groupBy":"top","aggField":"sheet.version","termSize":6,"termField":"name.keyword","threshold":[1000],"timeField":"@timestamp","timeWindowSize":5,"timeWindowUnit":"m","thresholdComparator":"\u003e"},"actions":[{"id":"96b668d0-a1b6-11ed-afdf-d39a49596974","group":"threshold met","params":{"level":"info","message":"Rule {{rule.name}} is active for group {{context.group}}:\n\n- Value: {{context.value}}\n- Conditions Met: {{context.conditions}} over {{rule.params.timeWindowSize}}{{rule.params.timeWindowUnit}}\n- Timestamp: {{context.date}}"},"frequency":{"summary":false,"notify_when":"onActionGroupChange"}}],"schedule":{"interval":"1m"}}'

Request example

Update an index threshold rule that uses a server log connector to send notifications when the threshold is met.

{
  "name": "new name",
  "tags": [],
  "params": {
    "index": [
      ".updated-index"
    ],
    "aggType": "avg",
    "groupBy": "top",
    "aggField": "sheet.version",
    "termSize": 6,
    "termField": "name.keyword",
    "threshold": [
      1000
    ],
    "timeField": "@timestamp",
    "timeWindowSize": 5,
    "timeWindowUnit": "m",
    "thresholdComparator": ">"
  },
  "actions": [
    {
      "id": "96b668d0-a1b6-11ed-afdf-d39a49596974",
      "group": "threshold met",
      "params": {
        "level": "info",
        "message": "Rule {{rule.name}} is active for group {{context.group}}:\n\n- Value: {{context.value}}\n- Conditions Met: {{context.conditions}} over {{rule.params.timeWindowSize}}{{rule.params.timeWindowUnit}}\n- Timestamp: {{context.date}}"
      },
      "frequency": {
        "summary": false,
        "notify_when": "onActionGroupChange"
      }
    }
  ],
  "schedule": {
    "interval": "1m"
  }
}

Response examples (200)

The response for successfully updating an index threshold rule.

{
  "id": "ac4e6b90-6be7-11eb-ba0d-9b1c1f912d74",
  "name": "new name",
  "tags": [],
  "params": {
    "index": [
      ".updated-index"
    ],
    "aggType": "avg",
    "groupBy": "top",
    "aggField": "sheet.version",
    "termSize": 6,
    "termField": "name.keyword",
    "threshold": [
      1000
    ],
    "timeField": "@timestamp",
    "timeWindowSize": 5,
    "timeWindowUnit": "m",
    "thresholdComparator": ">"
  },
  "actions": [
    {
      "id": "96b668d0-a1b6-11ed-afdf-d39a49596974",
      "uuid": "07aef2a0-9eed-4ef9-94ec-39ba58eb609d",
      "group": "threshold met",
      "params": {
        "level": "info",
        "message": "Rule {{rule.name}} is active for group {{context.group}}:\n\n- Value: {{context.value}}\n- Conditions Met: {{context.conditions}} over {{rule.params.timeWindowSize}}{{rule.params.timeWindowUnit}}\n- Timestamp: {{context.date}"
      },
      "frequency": {
        "summary": false,
        "throttle": null,
        "notify_when": "onActionGroupChange"
      },
      "connector_type_id": ".server-log"
    }
  ],
  "enabled": true,
  "running": false,
  "consumer": "alerts",
  "last_run": {
    "outcome": "succeeded",
    "warning": null,
    "outcome_msg": null,
    "alerts_count": {
      "new": 0,
      "active": 0,
      "ignored": 0,
      "recovered": 0
    }
  },
  "mute_all": false,
  "next_run": "2024-03-26T23:23:51.316Z",
  "revision": 1,
  "schedule": {
    "interval": "1m"
  },
  "throttle": null,
  "created_at": "2024-03-26T23:13:20.985Z",
  "created_by": "elastic",
  "updated_at": "2024-03-26T23:22:59.949Z",
  "updated_by": "elastic",
  "rule_type_id": ".index-threshold",
  "api_key_owner": "elastic",
  "muted_alert_ids": [],
  "execution_status": {
    "status": "ok",
    "last_duration": 52,
    "last_execution_date": "2024-03-26T23:22:51.390Z"
  },
  "scheduled_task_id": "4c5eda00-e74f-11ec-b72f-5b18752ff9ea",
  "api_key_created_by_user": false
}

Create a rule

POST /api/alerting/rule/{id}

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

Path parameters

id string Required

The identifier for the rule. If it is omitted, an ID is randomly generated.

application/json

Body

actions array[object]

An action that runs under defined conditions.

Default value is [] (empty).
Hide actions attributes Show actions attributes object
- alerts_filter object
  
  Conditions that affect whether the action runs. If you specify multiple conditions, all conditions must be met for the action to run. For example, if an alert occurs within the specified time frame and matches the query, the action runs.
  
  Additional properties are NOT allowed.
  Hide alerts_filter attributes Show alerts_filter attributes object
  
  query object
  
  Additional properties are NOT allowed.
  
  Hide query attributes Show query attributes object
  
  dsl string
  
  A filter written in Elasticsearch Query Domain Specific Language (DSL).
  
  filters array[object] Required
  
  A filter written in Elasticsearch Query Domain Specific Language (DSL) as defined in the kbn-es-query package.
  
  Hide filters attributes Show filters attributes object
  
  $state object
  
  Additional properties are NOT allowed.
  
  Hide $state attribute Show $state attribute object
  
  store string Required
  
  A filter can be either specific to an application context or applied globally.
  
  Values are appState or globalState.
  
  meta object Required
  
  Additional properties are allowed.
  
  query object
  
  Additional properties are allowed.
  
  kql string Required
  
  A filter written in Kibana Query Language (KQL).
  
  timeframe object
  
  Defines a period that limits whether the action runs.
  
  Additional properties are NOT allowed.
  
  Hide timeframe attributes Show timeframe attributes object
  
  days array[integer] Required
  
  Defines the days of the week that the action can run, represented as an array of numbers. For example, 1 represents Monday. An empty array is equivalent to specifying all the days of the week.
  
  Values are 1, 2, 3, 4, 5, 6, or 7.
  
  hours object Required
  
  Defines the range of time in a day that the action can run. If the start value is 00:00 and the end value is 24:00, actions be generated all day.
  
  Additional properties are NOT allowed.
  
  Hide hours attributes Show hours attributes object
  
  end string Required
  
  The end of the time frame in 24-hour notation (hh:mm).
  
  start string Required
  
  The start of the time frame in 24-hour notation (hh:mm).
  
  timezone string Required
  
  The ISO time zone for the hours values. Values such as UTC and UTC+1 also work but lack built-in daylight savings time support and are not recommended.
- frequency object
  
  Additional properties are NOT allowed.
  Hide frequency attributes Show frequency attributes object
  
  notify_when string Required
  
  Indicates how often alerts generate actions. Valid values include: onActionGroupChange: Actions run when the alert status changes; onActiveAlert: Actions run when the alert becomes active and at each check interval while the rule conditions are met; onThrottleInterval: Actions run when the alert becomes active and at the interval specified in the throttle property while the rule conditions are met. NOTE: You cannot specify notify_when at both the rule and action level. The recommended method is to set it for each action. If you set it at the rule level then update the rule in Kibana, it is automatically changed to use action-specific values.
  
  Values are onActionGroupChange, onActiveAlert, or onThrottleInterval.
  
  summary boolean Required
  
  Indicates whether the action is a summary.
  
  throttle string | null Required
  
  The throttle interval, which defines how often an alert generates repeated actions. It is specified in seconds, minutes, hours, or days and is applicable only if notify_when is set to onThrottleInterval. NOTE: You cannot specify the throttle interval at both the rule and action level. The recommended method is to set it for each action. If you set it at the rule level then update the rule in Kibana, it is automatically changed to use action-specific values.
- group string
  
  The group name, which affects when the action runs (for example, when the threshold is met or when the alert is recovered). Each rule type has a list of valid action group names. If you don't need to group actions, set to default.
- id string Required
  
  The identifier for the connector saved object.
- params object
  
  The parameters for the action, which are sent to the connector. The params are handled as Mustache templates and passed a default set of context.
  
  Default value is {} (empty). Additional properties are allowed.
- use_alert_data_for_template boolean
  
  Indicates whether to use alert data as a template.
- uuid string
  
  A universally unique identifier (UUID) for the action.
alert_delay object

Indicates that an alert occurs only when the specified number of consecutive runs met the rule conditions.

Additional properties are NOT allowed.
Hide alert_delay attribute Show alert_delay attribute object
- active number Required
  
  The number of consecutive runs that must meet the rule conditions.
artifacts object

Additional properties are NOT allowed.
Hide artifacts attributes Show artifacts attributes object
- dashboards array[object]
  
  Not more than 10 elements.
  Hide dashboards attribute Show dashboards attribute object
  
  id string Required
- investigation_guide object
  
  Additional properties are NOT allowed.
  Hide investigation_guide attribute Show investigation_guide attribute object
  
  blob string Required
  
  Maximum length is 1000.
consumer string Required

The name of the application or feature that owns the rule. For example: alerts, apm, discover, infrastructure, logs, metrics, ml, monitoring, securitySolution, siem, stackAlerts, or uptime.
enabled boolean

Indicates whether you want to run the rule on an interval basis after it is created.

Default value is true.
flapping object | null

When flapping detection is turned on, alerts that switch quickly between active and recovered states are identified as “flapping” and notifications are reduced.

Additional properties are NOT allowed.
Hide flapping attributes Show flapping attributes object | null
- look_back_window number Required
  
  The minimum number of runs in which the threshold must be met.
  
  Minimum value is 2, maximum value is 20.
- status_change_threshold number Required
  
  The minimum number of times an alert must switch states in the look back window.
  
  Minimum value is 2, maximum value is 20.
name string Required

The name of the rule. While this name does not have to be unique, a distinctive name can help you identify a rule.
notify_when string | null

Indicates how often alerts generate actions. Valid values include: onActionGroupChange: Actions run when the alert status changes; onActiveAlert: Actions run when the alert becomes active and at each check interval while the rule conditions are met; onThrottleInterval: Actions run when the alert becomes active and at the interval specified in the throttle property while the rule conditions are met. NOTE: You cannot specify notify_when at both the rule and action level. The recommended method is to set it for each action. If you set it at the rule level then update the rule in Kibana, it is automatically changed to use action-specific values.

Values are onActionGroupChange, onActiveAlert, or onThrottleInterval.
rule_type_id string Required

The rule type identifier.
schedule object Required

The check interval, which specifies how frequently the rule conditions are checked.

Additional properties are NOT allowed.
Hide schedule attribute Show schedule attribute object
- interval string Required
  
  The interval is specified in seconds, minutes, hours, or days.
tags array[string]

The tags for the rule.

Default value is [] (empty).
throttle string | null

Use the throttle property in the action frequency object instead. The throttle interval, which defines how often an alert generates repeated actions. NOTE: You cannot specify the throttle interval at both the rule and action level. If you set it at the rule level then update the rule in Kibana, it is automatically changed to use action-specific values.
params object

The parameters for the rule.
Any of:
params_property_apm_anomaly object params_property_apm_error_count object params_property_apm_transaction_duration object params_property_apm_transaction_error_rate object params_es_query_dsl_rule object params_es_query_esql_rule object params_es_query_kql_rule object params_index_threshold_rule object params_property_infra_inventory object Count object Ratio object params_property_infra_metric_threshold object params_property_slo_burn_rate object params_property_synthetics_uptime_tls object params_property_synthetics_monitor_status object
Hide attributes Show attributes

serviceName string

Filter the rule to apply to a specific service name.

transactionType string

Filter the rule to apply to a specific transaction type.

windowSize number Required

The size of the time window (in windowUnit units), which determines how far back to search for documents. Generally it should be a value higher than the rule check interval to avoid gaps in detection.

windowUnit string Required

The type of units for the time window. For example: minutes, hours, or days.

Values are m, h, or d.

environment string Required

Filter the rule to apply to a specific environment.

anomalySeverityType string Required

The severity of anomalies that will generate alerts: critical, major, minor, or warning.

Values are critical, major, minor, or warning.
Hide attributes Show attributes

serviceName string

Filter the errors coming from your application to apply the rule to a specific service.

windowSize number Required

The time frame in which the errors must occur (in windowUnit units). Generally it should be a value higher than the rule check interval to avoid gaps in detection.

windowUnit string Required

The type of units for the time window: minutes, hours, or days.

Values are m, h, or d.

environment string Required

Filter the errors coming from your application to apply the rule to a specific environment.

threshold number Required

The error count threshold.

groupBy array[string]

Perform a composite aggregation against the selected fields. When any of these groups match the selected rule conditions, an alert is triggered per group.

Values are service.name, service.environment, transaction.name, or error.grouping_key. Default value is ["service.name", "service.environment"].

errorGroupingKey string

Filter the errors coming from your application to apply the rule to a specific error grouping key, which is a hash of the stack trace and other properties.
Hide attributes Show attributes

serviceName string

Filter the rule to apply to a specific service.

transactionType string

Filter the rule to apply to a specific transaction type.

transactionName string

Filter the rule to apply to a specific transaction name.

windowSize number Required

The size of the time window (in windowUnit units), which determines how far back to search for documents. Generally it should be a value higher than the rule check interval to avoid gaps in detection.

windowUnit string Required

The type of units for the time window. For example: minutes, hours, or days.

Values are m, h, or d.

environment string Required

Filter the rule to apply to a specific environment.

threshold number Required

The latency threshold value.

groupBy array[string]

Perform a composite aggregation against the selected fields. When any of these groups match the selected rule conditions, an alert is triggered per group.

Values are service.name, service.environment, transaction.type, or transaction.name. Default value is ["service.name", "service.environment", "transaction.type"].

aggregationType string Required

The type of aggregation to perform.

Values are avg, 95th, or 99th.
Hide attributes Show attributes

serviceName string

The service name from APM

transactionType string

The transaction type from APM

transactionName string

The transaction name from APM

windowSize number Required

The window size

windowUnit string Required

The window size unit

Values are m, h, or d.

environment string Required

The environment from APM

threshold number Required

The error rate threshold value

groupBy array[string]

Values are service.name, service.environment, transaction.type, or transaction.name. Default value is ["service.name", "service.environment", "transaction.type"].
An Elasticsearch query rule can run a query defined in Elasticsearch Query DSL and compare the number of matches to a configured threshold. These parameters are appropriate when rule_type_id is .es-query.
Hide attributes Show attributes

aggField string

The name of the numeric field that is used in the aggregation. This property is required when aggType is avg, max, min or sum.

aggType string

The type of aggregation to perform.

Values are avg, count, max, min, or sum. Default value is count.

esQuery string Required

The query definition, which uses Elasticsearch Query DSL.

excludeHitsFromPreviousRun boolean

Indicates whether to exclude matches from previous runs. If true, you can avoid alert duplication by excluding documents that have already been detected by the previous rule run. This option is not available when a grouping field is specified.

groupBy string

Indicates whether the aggregation is applied over all documents (all) or split into groups (top) using a grouping field (termField). If grouping is used, an alert will be created for each group when it exceeds the threshold; only the top groups (up to termSize number of groups) are checked.

Values are all or top. Default value is all.

index array[string] | string Required

The indices to query.

One of:
array-1 array[string] string-2 string

searchType string

The type of query, in this case a query that uses Elasticsearch Query DSL.

Value is esQuery. Default value is esQuery.

size integer

The number of documents to pass to the configured actions when the threshold condition is met.

termField string | array[string]

The names of up to four fields that are used for grouping the aggregation. This property is required when groupBy is top.

One of:
string-1 string array-2 array[string]

termSize integer

This property is required when groupBy is top. It specifies the number of groups to check against the threshold and therefore limits the number of alerts on high cardinality fields.

threshold array[integer] Required

The threshold value that is used with the thresholdComparator. If the thresholdComparator is between or notBetween, you must specify the boundary values.

thresholdComparator string Required

The comparison function for the threshold. For example, "is above", "is above or equals", "is below", "is below or equals", "is between", and "is not between".

Values are >, >=, <, <=, between, or notBetween.

timeField string Required

The field that is used to calculate the time window.

timeWindowSize integer Required

The size of the time window (in timeWindowUnit units), which determines how far back to search for documents. Generally it should be a value higher than the rule check interval to avoid gaps in detection.

timeWindowUnit string Required

The type of units for the time window: seconds, minutes, hours, or days.

Values are s, m, h, or d.
An Elasticsearch query rule can run an ES|QL query and compare the number of matches to a configured threshold. These parameters are appropriate when rule_type_id is .es-query.
Hide attributes Show attributes

aggField string

The name of the numeric field that is used in the aggregation. This property is required when aggType is avg, max, min or sum.

aggType string

The type of aggregation to perform.

Values are avg, count, max, min, or sum. Default value is count.

esqlQuery object Required

Hide esqlQuery attribute Show esqlQuery attribute object

esql string Required

The query definition, which uses Elasticsearch Query Language.

excludeHitsFromPreviousRun boolean

Indicates whether to exclude matches from previous runs. If true, you can avoid alert duplication by excluding documents that have already been detected by the previous rule run. This option is not available when a grouping field is specified.

groupBy string

Indicates whether the aggregation is applied over all documents (all) or split into groups (top) using a grouping field (termField). If grouping is used, an alert will be created for each group when it exceeds the threshold; only the top groups (up to termSize number of groups) are checked.

Values are all or top. Default value is all.

searchType string Required

The type of query, in this case a query that uses Elasticsearch Query Language (ES|QL).

Value is esqlQuery.

size integer Required

When searchType is esqlQuery, this property is required but it does not affect the rule behavior.

termSize integer

This property is required when groupBy is top. It specifies the number of groups to check against the threshold and therefore limits the number of alerts on high cardinality fields.

threshold array[integer] Required

The threshold value that is used with the thresholdComparator. When searchType is esqlQuery, this property is required and must be set to zero.

Minimum value of each is 0, maximum value of each is 0.

thresholdComparator string Required

The comparison function for the threshold. When searchType is esqlQuery, this property is required and must be set to ">". Since the threshold value must be 0, the result is that an alert occurs whenever the query returns results.

Value is >.

timeField string

The field that is used to calculate the time window.

timeWindowSize integer Required

The size of the time window (in timeWindowUnit units), which determines how far back to search for documents. Generally it should be a value higher than the rule check interval to avoid gaps in detection.

timeWindowUnit string Required

The type of units for the time window: seconds, minutes, hours, or days.

Values are s, m, h, or d.
An Elasticsearch query rule can run a query defined in KQL or Lucene and compare the number of matches to a configured threshold. These parameters are appropriate when rule_type_id is .es-query.
Hide attributes Show attributes

aggField string

The name of the numeric field that is used in the aggregation. This property is required when aggType is avg, max, min or sum.

aggType string

The type of aggregation to perform.

Values are avg, count, max, min, or sum. Default value is count.

excludeHitsFromPreviousRun boolean

Indicates whether to exclude matches from previous runs. If true, you can avoid alert duplication by excluding documents that have already been detected by the previous rule run. This option is not available when a grouping field is specified.

groupBy string

Indicates whether the aggregation is applied over all documents (all) or split into groups (top) using a grouping field (termField). If grouping is used, an alert will be created for each group when it exceeds the threshold; only the top groups (up to termSize number of groups) are checked.

Values are all or top. Default value is all.

searchConfiguration object

The query definition, which uses KQL or Lucene to fetch the documents from Elasticsearch.

Hide searchConfiguration attributes Show searchConfiguration attributes object

filter array[object]

A filter written in Elasticsearch Query Domain Specific Language (DSL) as defined in the kbn-es-query package.

Hide filter attributes Show filter attributes object

meta object

Hide meta attributes Show meta attributes object

alias string | null

controlledBy string

disabled boolean

field string

group string

index string

isMultiIndex boolean

key string

negate boolean

params object

type string

value string

query object

$state object

index string | array[string]

The indices to query.

One of:
string-1 string array-2 array[string]

query object

Hide query attributes Show query attributes object

language string

query string

searchType string Required

The type of query, in this case a text-based query that uses KQL or Lucene.

Value is searchSource.

size integer Required

The number of documents to pass to the configured actions when the threshold condition is met.

termField string | array[string]

The names of up to four fields that are used for grouping the aggregation. This property is required when groupBy is top.

One of:
string-1 string array-2 array[string]

termSize integer

This property is required when groupBy is top. It specifies the number of groups to check against the threshold and therefore limits the number of alerts on high cardinality fields.

threshold array[integer] Required

The threshold value that is used with the thresholdComparator. If the thresholdComparator is between or notBetween, you must specify the boundary values.

thresholdComparator string Required

The comparison function for the threshold. For example, "is above", "is above or equals", "is below", "is below or equals", "is between", and "is not between".

Values are >, >=, <, <=, between, or notBetween.

timeField string

The field that is used to calculate the time window.

timeWindowSize integer Required

The size of the time window (in timeWindowUnit units), which determines how far back to search for documents. Generally it should be a value higher than the rule check interval to avoid gaps in detection.

timeWindowUnit string Required

The type of units for the time window: seconds, minutes, hours, or days.

Values are s, m, h, or d.
An index threshold rule runs an Elasticsearch query, aggregates field values from documents, compares them to threshold values, and schedules actions to run when the thresholds are met. These parameters are appropriate when rule_type_id is .index-threshold.
Hide attributes Show attributes

aggField string

The name of the numeric field that is used in the aggregation. This property is required when aggType is avg, max, min or sum.

aggType string

The type of aggregation to perform.

Values are avg, count, max, min, or sum. Default value is count.

filterKuery string

A KQL expression thats limits the scope of alerts.

groupBy string

Indicates whether the aggregation is applied over all documents (all) or split into groups (top) using a grouping field (termField). If grouping is used, an alert will be created for each group when it exceeds the threshold; only the top groups (up to termSize number of groups) are checked.

Values are all or top. Default value is all.

index array[string] Required

The indices to query.

termField string | array[string]

The names of up to four fields that are used for grouping the aggregation. This property is required when groupBy is top.

One of:
string-1 string array-2 array[string]

termSize integer

This property is required when groupBy is top. It specifies the number of groups to check against the threshold and therefore limits the number of alerts on high cardinality fields.

threshold array[integer] Required

The threshold value that is used with the thresholdComparator. If the thresholdComparator is between or notBetween, you must specify the boundary values.

thresholdComparator string Required

The comparison function for the threshold. For example, "is above", "is above or equals", "is below", "is below or equals", "is between", and "is not between".

Values are >, >=, <, <=, between, or notBetween.

timeField string Required

The field that is used to calculate the time window.

timeWindowSize integer Required

The size of the time window (in timeWindowUnit units), which determines how far back to search for documents. Generally it should be a value higher than the rule check interval to avoid gaps in detection.

timeWindowUnit string Required

The type of units for the time window: seconds, minutes, hours, or days.

Values are s, m, h, or d.
Hide attributes Show attributes

criteria array[object]

Hide criteria attributes Show criteria attributes object

metric string

Values are count, cpu, diskLatency, load, memory, memoryTotal, tx, rx, logRate, diskIOReadBytes, diskIOWriteBytes, s3TotalRequests, s3NumberOfObjects, s3BucketSize, s3DownloadBytes, s3UploadBytes, rdsConnections, rdsQueriesExecuted, rdsActiveTransactions, rdsLatency, sqsMessagesVisible, sqsMessagesDelayed, sqsMessagesSent, sqsMessagesEmpty, sqsOldestMessage, or custom.

timeSize number

timeUnit string

Values are s, m, h, or d.

sourceId string

threshold array[number]

comparator string

Values are <, <=, >, >=, between, or outside.

customMetric object

Hide customMetric attributes Show customMetric attributes object

type string

Value is custom.

field string

aggregation string

Values are avg, max, min, or rate.

id string

label string

warningThreshold array[number]

warningComparator string

Values are <, <=, >, >=, between, or outside.

filterQuery string

filterQueryText string

nodeType string

Values are host, pod, container, awsEC2, awsS3, awsSQS, or awsRDS.

sourceId string

alertOnNoData boolean
Hide attributes Show attributes

criteria array[object]

Hide criteria attributes Show criteria attributes object

field string

comparator string

Values are more than, more than or equals, less than, less than or equals, equals, does not equal, matches, does not match, matches phrase, or does not match phrase.

value number | string

One of:
number-1 number string-2 string

count object Required

Hide count attributes Show count attributes object

comparator string

Values are more than, more than or equals, less than, less than or equals, equals, does not equal, matches, does not match, matches phrase, or does not match phrase.

value number

timeSize number Required

timeUnit string Required

Values are s, m, h, or d.

logView object Required

Hide logView attributes Show logView attributes object

logViewId string

type string

Value is log-view-reference.

groupBy array[string]
Hide attributes Show attributes

criteria array[array]

Hide criteria attributes Show criteria attributes object

field string

comparator string

Values are more than, more than or equals, less than, less than or equals, equals, does not equal, matches, does not match, matches phrase, or does not match phrase.

value number | string

One of:
number-1 number string-2 string

count object Required

Hide count attributes Show count attributes object

comparator string

Values are more than, more than or equals, less than, less than or equals, equals, does not equal, matches, does not match, matches phrase, or does not match phrase.

value number

timeSize number Required

timeUnit string Required

Values are s, m, h, or d.

logView object Required

Hide logView attributes Show logView attributes object

logViewId string

type string

Value is log-view-reference.

groupBy array[string]
Hide attributes Show attributes

criteria array[object]

One of:
non count criterion object count criterion object custom criterion object

Hide attributes Show attributes

threshold array[number]

comparator string

Values are <, <=, >, >=, between, or outside.

timeUnit string

timeSize number

warningThreshold array[number]

warningComparator string

Values are <, <=, >, >=, between, or outside.

metric string

aggType string

Values are avg, max, min, cardinality, rate, count, sum, p95, p99, or custom.

Hide attributes Show attributes

threshold array[number]

comparator string

Values are <, <=, >, >=, between, or outside.

timeUnit string

timeSize number

warningThreshold array[number]

warningComparator string

Values are <, <=, >, >=, between, or outside.

aggType string

Value is count.

Hide attributes Show attributes

threshold array[number]

comparator string

Values are <, <=, >, >=, between, or outside.

timeUnit string

timeSize number

warningThreshold array[number]

warningComparator string

Values are <, <=, >, >=, between, or outside.

aggType string

Value is custom.

customMetric array[object]

One of:
object-1 object object-2 object

Hide attributes Show attributes

name string

aggType string

Values are avg, sum, max, min, or cardinality.

field string

equation string

label string

groupBy string | array[string]

One of:
string-1 string array-2 array[string]

filterQuery string

sourceId string

alertOnNoData boolean

alertOnGroupDisappear boolean
Hide attributes Show attributes

sloId string

The SLO identifier used by the rule

burnRateThreshold number

The burn rate threshold used to trigger the alert

maxBurnRateThreshold number

The maximum burn rate threshold value defined by the SLO error budget

longWindow object

The duration of the long window used to compute the burn rate

Hide longWindow attributes Show longWindow attributes object

value number

The duration value

unit string

The duration unit

shortWindow object

The duration of the short window used to compute the burn rate

Hide shortWindow attributes Show shortWindow attributes object

value number

The duration value

unit string

The duration unit
Hide attributes Show attributes

search string

certExpirationThreshold number

certAgeThreshold number
Hide attributes Show attributes

availability object

Hide availability attributes Show availability attributes object

range number

rangeUnit string

threshold string

filters string | object

One of:
string-1 string object-2 object Deprecated

locations array[string] Deprecated

numTimes number Required

search string

shouldCheckStatus boolean Required

shouldCheckAvailability boolean Required

timerangeCount number

timerangeUnit string

timerange object Deprecated

Hide timerange attributes Show timerange attributes object Deprecated

from string

to string

version number

isAutoGenerated boolean

Responses

200 application/json

Indicates a successful call.
Hide response attributes Show response attributes object
- actions array[object] Required
  
  Hide actions attributes Show actions attributes object
  
  alerts_filter object
  
  Defines a period that limits whether the action runs.
  
  Additional properties are NOT allowed.
  
  Hide alerts_filter attributes Show alerts_filter attributes object
  
  query object
  
  Additional properties are NOT allowed.
  
  Hide query attributes Show query attributes object
  
  dsl string
  
  A filter written in Elasticsearch Query Domain Specific Language (DSL).
  
  filters array[object] Required
  
  A filter written in Elasticsearch Query Domain Specific Language (DSL) as defined in the kbn-es-query package.
  
  Hide filters attributes Show filters attributes object
  
  $state object
  
  Additional properties are NOT allowed.
  
  Hide $state attribute Show $state attribute object
  
  store string Required
  
  A filter can be either specific to an application context or applied globally.
  
  Values are appState or globalState.
  
  meta object Required
  
  Additional properties are allowed.
  
  query object
  
  Additional properties are allowed.
  
  kql string Required
  
  A filter written in Kibana Query Language (KQL).
  
  timeframe object
  
  Additional properties are NOT allowed.
  
  Hide timeframe attributes Show timeframe attributes object
  
  days array[integer] Required
  
  Defines the days of the week that the action can run, represented as an array of numbers. For example, 1 represents Monday. An empty array is equivalent to specifying all the days of the week.
  
  Values are 1, 2, 3, 4, 5, 6, or 7.
  
  hours object Required
  
  Additional properties are NOT allowed.
  
  Hide hours attributes Show hours attributes object
  
  end string Required
  
  The end of the time frame in 24-hour notation (hh:mm).
  
  start string Required
  
  The start of the time frame in 24-hour notation (hh:mm).
  
  timezone string Required
  
  The ISO time zone for the hours values. Values such as UTC and UTC+1 also work but lack built-in daylight savings time support and are not recommended.
  
  connector_type_id string Required
  
  The type of connector. This property appears in responses but cannot be set in requests.
  
  frequency object
  
  Additional properties are NOT allowed.
  
  Hide frequency attributes Show frequency attributes object
  
  notify_when string Required
  
  Indicates how often alerts generate actions. Valid values include: onActionGroupChange: Actions run when the alert status changes; onActiveAlert: Actions run when the alert becomes active and at each check interval while the rule conditions are met; onThrottleInterval: Actions run when the alert becomes active and at the interval specified in the throttle property while the rule conditions are met. NOTE: You cannot specify notify_when at both the rule and action level. The recommended method is to set it for each action. If you set it at the rule level then update the rule in Kibana, it is automatically changed to use action-specific values.
  
  Values are onActionGroupChange, onActiveAlert, or onThrottleInterval.
  
  summary boolean Required
  
  Indicates whether the action is a summary.
  
  throttle string | null Required
  
  The throttle interval, which defines how often an alert generates repeated actions. It is specified in seconds, minutes, hours, or days and is applicable only if 'notify_when' is set to 'onThrottleInterval'. NOTE: You cannot specify the throttle interval at both the rule and action level. The recommended method is to set it for each action. If you set it at the rule level then update the rule in Kibana, it is automatically changed to use action-specific values.
  
  group string
  
  The group name, which affects when the action runs (for example, when the threshold is met or when the alert is recovered). Each rule type has a list of valid action group names. If you don't need to group actions, set to default.
  
  id string Required
  
  The identifier for the connector saved object.
  
  params object Required
  
  The parameters for the action, which are sent to the connector. The params are handled as Mustache templates and passed a default set of context.
  
  Additional properties are allowed.
  
  use_alert_data_for_template boolean
  
  Indicates whether to use alert data as a template.
  
  uuid string
  
  A universally unique identifier (UUID) for the action.
- active_snoozes array[string]
  
  List of active snoozes for the rule.
- alert_delay object
  
  Indicates that an alert occurs only when the specified number of consecutive runs met the rule conditions.
  
  Additional properties are NOT allowed.
  
  Hide alert_delay attribute Show alert_delay attribute object
  
  active number Required
  
  The number of consecutive runs that must meet the rule conditions.
- api_key_created_by_user boolean | null
  
  Indicates whether the API key that is associated with the rule was created by the user.
- api_key_owner string | null Required
  
  The owner of the API key that is associated with the rule and used to run background tasks.
- artifacts object
  
  Additional properties are NOT allowed.
  
  Hide artifacts attributes Show artifacts attributes object
  
  dashboards array[object]
  
  Hide dashboards attribute Show dashboards attribute object
  
  id string Required
  
  investigation_guide object
  
  Additional properties are NOT allowed.
  
  Hide investigation_guide attribute Show investigation_guide attribute object
  
  blob string Required
  
  User-created content that describes alert causes and remdiation.
- consumer string Required
  
  The name of the application or feature that owns the rule. For example: alerts, apm, discover, infrastructure, logs, metrics, ml, monitoring, securitySolution, siem, stackAlerts, or uptime.
- created_at string Required
  
  The date and time that the rule was created.
- created_by string | null Required
  
  The identifier for the user that created the rule.
- enabled boolean Required
  
  Indicates whether you want to run the rule on an interval basis after it is created.
- execution_status object Required
  
  Additional properties are NOT allowed.
  
  Hide execution_status attributes Show execution_status attributes object
  
  error object
  
  Additional properties are NOT allowed.
  
  Hide error attributes Show error attributes object
  
  message string Required
  
  Error message.
  
  reason string Required
  
  Reason for error.
  
  Values are read, decrypt, execute, unknown, license, timeout, disabled, or validate.
  
  last_duration number
  
  Duration of last execution of the rule.
  
  last_execution_date string Required
  
  The date and time when rule was executed last.
  
  status string Required
  
  Status of rule execution.
  
  Values are ok, active, error, warning, pending, or unknown.
  
  warning object
  
  Additional properties are NOT allowed.
  
  Hide warning attributes Show warning attributes object
  
  message string Required
  
  Warning message.
  
  reason string Required
  
  Reason for warning.
  
  Values are maxExecutableActions, maxAlerts, maxQueuedActions, or ruleExecution.
- flapping object | null
  
  When flapping detection is turned on, alerts that switch quickly between active and recovered states are identified as “flapping” and notifications are reduced.
  
  Additional properties are NOT allowed.
  
  Hide flapping attributes Show flapping attributes object | null
  
  look_back_window number Required
  
  The minimum number of runs in which the threshold must be met.
  
  Minimum value is 2, maximum value is 20.
  
  status_change_threshold number Required
  
  The minimum number of times an alert must switch states in the look back window.
  
  Minimum value is 2, maximum value is 20.
- id string Required
  
  The identifier for the rule.
- is_snoozed_until string | null
  
  The date when the rule will no longer be snoozed.
- last_run object | null
  
  Additional properties are NOT allowed.
  
  Hide last_run attributes Show last_run attributes object | null
  
  alerts_count object Required
  
  Additional properties are NOT allowed.
  
  Hide alerts_count attributes Show alerts_count attributes object
  
  active number | null
  
  Number of active alerts during last run.
  
  ignored number | null
  
  Number of ignored alerts during last run.
  
  new number | null
  
  Number of new alerts during last run.
  
  recovered number | null
  
  Number of recovered alerts during last run.
  
  outcome string Required
  
  Outcome of last run of the rule. Value could be succeeded, warning or failed.
  
  Values are succeeded, warning, or failed.
  
  outcome_msg array[string] | null
  
  Outcome message generated during last rule run.
  
  outcome_order number
  
  Order of the outcome.
  
  warning string | null
  
  Warning of last rule execution.
  
  Values are read, decrypt, execute, unknown, license, timeout, disabled, validate, maxExecutableActions, maxAlerts, maxQueuedActions, or ruleExecution.
- mapped_params object
  
  Additional properties are allowed.
- monitoring object
  
  Monitoring details of the rule.
  
  Additional properties are NOT allowed.
  
  Hide monitoring attribute Show monitoring attribute object
  
  run object Required
  
  Rule run details.
  
  Additional properties are NOT allowed.
  
  Hide run attributes Show run attributes object
  
  calculated_metrics object Required
  
  Calculation of different percentiles and success ratio.
  
  Additional properties are NOT allowed.
  
  Hide calculated_metrics attributes Show calculated_metrics attributes object
  
  p50 number
  
  p95 number
  
  p99 number
  
  success_ratio number Required
  
  history array[object] Required
  
  History of the rule run.
  
  Hide history attributes Show history attributes object
  
  duration number
  
  Duration of the rule run.
  
  outcome string
  
  Outcome of last run of the rule. Value could be succeeded, warning or failed.
  
  Values are succeeded, warning, or failed.
  
  success boolean Required
  
  Indicates whether the rule run was successful.
  
  timestamp number Required
  
  Time of rule run.
  
  last_run object Required
  
  Additional properties are NOT allowed.
  
  Hide last_run attributes Show last_run attributes object
  
  metrics object Required
  
  Additional properties are NOT allowed.
  
  Hide metrics attributes Show metrics attributes object
  
  duration number
  
  Duration of most recent rule run.
  
  gap_duration_s number | null
  
  Duration in seconds of rule run gap.
  
  gap_range object | null
  
  Additional properties are NOT allowed.
  
  Hide gap_range attributes Show gap_range attributes object | null
  
  gte string Required
  
  End of the gap range.
  
  lte string Required
  
  Start of the gap range.
  
  total_alerts_created number | null
  
  Total number of alerts created during last rule run.
  
  total_alerts_detected number | null
  
  Total number of alerts detected during last rule run.
  
  total_indexing_duration_ms number | null
  
  Total time spent indexing documents during last rule run in milliseconds.
  
  total_search_duration_ms number | null
  
  Total time spent performing Elasticsearch searches as measured by Kibana; includes network latency and time spent serializing or deserializing the request and response.
  
  timestamp string Required
  
  Time of the most recent rule run.
- mute_all boolean Required
  
  Indicates whether all alerts are muted.
- muted_alert_ids array[string] Required
  
  List of identifiers of muted alerts.
- name string Required
  
  The name of the rule.
- next_run string | null
  
  Date and time of the next run of the rule.
- notify_when string | null
  
  Indicates how often alerts generate actions. Valid values include: onActionGroupChange: Actions run when the alert status changes; onActiveAlert: Actions run when the alert becomes active and at each check interval while the rule conditions are met; onThrottleInterval: Actions run when the alert becomes active and at the interval specified in the throttle property while the rule conditions are met. NOTE: You cannot specify notify_when at both the rule and action level. The recommended method is to set it for each action. If you set it at the rule level then update the rule in Kibana, it is automatically changed to use action-specific values.
  
  Values are onActionGroupChange, onActiveAlert, or onThrottleInterval.
- params object Required
  
  The parameters for the rule.
  
  Additional properties are allowed.
- revision number Required
  
  The rule revision number.
- rule_type_id string Required
  
  The rule type identifier.
- running boolean | null
  
  Indicates whether the rule is running.
- schedule object Required
  
  Additional properties are NOT allowed.
  
  Hide schedule attribute Show schedule attribute object
  
  interval string Required
  
  The interval is specified in seconds, minutes, hours, or days.
- scheduled_task_id string
  
  Identifier of the scheduled task.
- snooze_schedule array[object]
  
  Hide snooze_schedule attributes Show snooze_schedule attributes object
  
  duration number Required
  
  Duration of the rule snooze schedule.
  
  id string
  
  Identifier of the rule snooze schedule.
  
  rRule object Required
  
  Additional properties are NOT allowed.
  
  Hide rRule attributes Show rRule attributes object
  
  byhour array[number] | null
  
  Indicates hours of the day to recur.
  
  byminute array[number] | null
  
  Indicates minutes of the hour to recur.
  
  bymonth array[number] | null
  
  Indicates months of the year that this rule should recur.
  
  bymonthday array[number] | null
  
  Indicates the days of the month to recur.
  
  bysecond array[number] | null
  
  Indicates seconds of the day to recur.
  
  bysetpos array[number] | null
  
  A positive or negative integer affecting the nth day of the month. For example, -2 combined with byweekday of FR is 2nd to last Friday of the month. It is recommended to not set this manually and just use byweekday.
  
  byweekday array[string | number] | null
  
  Indicates the days of the week to recur or else nth-day-of-month strings. For example, "+2TU" second Tuesday of month, "-1FR" last Friday of the month, which are internally converted to a byweekday/bysetpos combination.
  
  byweekno array[number] | null
  
  Indicates number of the week hours to recur.
  
  byyearday array[number] | null
  
  Indicates the days of the year that this rule should recur.
  
  count number
  
  Number of times the rule should recur until it stops.
  
  dtstart string Required
  
  Rule start date in Coordinated Universal Time (UTC).
  
  freq integer
  
  Indicates frequency of the rule. Options are YEARLY, MONTHLY, WEEKLY, DAILY.
  
  Values are 0, 1, 2, 3, 4, 5, or 6.
  
  interval number
  
  Indicates the interval of frequency. For example, 1 and YEARLY is every 1 year, 2 and WEEKLY is every 2 weeks.
  
  tzid string Required
  
  Indicates timezone abbreviation.
  
  until string
  
  Recur the rule until this date.
  
  wkst string
  
  Indicates the start of week, defaults to Monday.
  
  Values are MO, TU, WE, TH, FR, SA, or SU.
  
  skipRecurrences array[string]
  
  Skips recurrence of rule on this date.
- tags array[string] Required
  
  The tags for the rule.
- throttle string | null Deprecated
  
  Deprecated in 8.13.0. Use the throttle property in the action frequency object instead. The throttle interval, which defines how often an alert generates repeated actions. NOTE: You cannot specify the throttle interval at both the rule and action level. If you set it at the rule level then update the rule in Kibana, it is automatically changed to use action-specific values.
- updated_at string Required
  
  The date and time that the rule was updated most recently.
- updated_by string | null Required
  
  The identifier for the user that updated this rule most recently.
- view_in_app_relative_url string | null
  
  Relative URL to view rule in the app.
400

Indicates an invalid schema or parameters.
403

Indicates that this call is forbidden.
409

Indicates that the rule id is already in use.

POST /api/alerting/rule/{id}

curl \
 --request POST 'https://<KIBANA_URL>/api/alerting/rule/{id}' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"name":"my Elasticsearch query ESQL rule","params":{"size":0,"esqlQuery":{"esql":"FROM kibana_sample_data_logs | KEEP bytes, clientip, host, geo.dest | where geo.dest != \"GB\" | STATS sumbytes = sum(bytes) by clientip, host | WHERE sumbytes \u003e 5000 | SORT sumbytes desc | LIMIT 10"},"threshold":[0],"timeField":"@timestamp","searchType":"esqlQuery","timeWindowSize":1,"timeWindowUnit":"d","thresholdComparator":"\u003e"},"actions":[{"id":"d0db1fe0-78d6-11ee-9177-f7d404c8c945","group":"query matched","params":{"level":"info","message":"Elasticsearch query rule '{{rule.name}}' is active:\n- Value: {{context.value}} - Conditions Met: {{context.conditions}} over {{rule.params.timeWindowSize}}{{rule.params.timeWindowUnit}} - Timestamp: {{context.date}} - Link: {{context.link}}"},"frequency":{"summary":false,"notify_when":"onActiveAlert"}}],"consumer":"stackAlerts","schedule":{"interval":"1d"},"rule_type_id":".es-query"}'

Request examples

Create an Elasticsearch query rule that uses Elasticsearch Query Language (ES|QL) to define its query and a server log connector to send notifications.

{
  "name": "my Elasticsearch query ESQL rule",
  "params": {
    "size": 0,
    "esqlQuery": {
      "esql": "FROM kibana_sample_data_logs | KEEP bytes, clientip, host, geo.dest | where geo.dest != \"GB\" | STATS sumbytes = sum(bytes) by clientip, host | WHERE sumbytes > 5000 | SORT sumbytes desc | LIMIT 10"
    },
    "threshold": [
      0
    ],
    "timeField": "@timestamp",
    "searchType": "esqlQuery",
    "timeWindowSize": 1,
    "timeWindowUnit": "d",
    "thresholdComparator": ">"
  },
  "actions": [
    {
      "id": "d0db1fe0-78d6-11ee-9177-f7d404c8c945",
      "group": "query matched",
      "params": {
        "level": "info",
        "message": "Elasticsearch query rule '{{rule.name}}' is active:\n- Value: {{context.value}} - Conditions Met: {{context.conditions}} over {{rule.params.timeWindowSize}}{{rule.params.timeWindowUnit}} - Timestamp: {{context.date}} - Link: {{context.link}}"
      },
      "frequency": {
        "summary": false,
        "notify_when": "onActiveAlert"
      }
    }
  ],
  "consumer": "stackAlerts",
  "schedule": {
    "interval": "1d"
  },
  "rule_type_id": ".es-query"
}

Create an Elasticsearch query rule that uses Kibana query language (KQL).

{
  "name": "my Elasticsearch query KQL rule",
  "params": {
    "size": 100,
    "aggType": "count",
    "groupBy": "all",
    "threshold": [
      1000
    ],
    "searchType": "searchSource",
    "timeWindowSize": 5,
    "timeWindowUnit": "m",
    "searchConfiguration": {
      "index": "90943e30-9a47-11e8-b64d-95841ca0b247",
      "query": {
        "query": "\"\"geo.src : \"US\" \"\"",
        "language": "kuery"
      }
    },
    "thresholdComparator": ">",
    "excludeHitsFromPreviousRun": true
  },
  "consumer": "alerts",
  "schedule": {
    "interval": "1m"
  },
  "rule_type_id": ".es-query"
}

Create an Elasticsearch query rule that uses Elasticsearch query domain specific language (DSL) to define its query and a server log connector to send notifications.

{
  "name": "my Elasticsearch query rule",
  "params": {
    "size": 100,
    "index": [
      "kibana_sample_data_logs"
    ],
    "esQuery": "\"\"\"{\"query\":{\"match_all\" : {}}}\"\"\"",
    "threshold": [
      100
    ],
    "timeField": "@timestamp",
    "timeWindowSize": 1,
    "timeWindowUnit": "d",
    "thresholdComparator": ">"
  },
  "actions": [
    {
      "id": "fdbece50-406c-11ee-850e-c71febc4ca7f",
      "group": "query matched",
      "params": {
        "level": "info",
        "message": "The system has detected {{alerts.new.count}} new, {{alerts.ongoing.count}} ongoing, and {{alerts.recovered.count}} recovered alerts."
      },
      "frequency": {
        "summary": true,
        "throttle": "1d",
        "notify_when": "onThrottleInterval"
      }
    },
    {
      "id": "fdbece50-406c-11ee-850e-c71febc4ca7f",
      "group": "recovered",
      "params": {
        "level": "info",
        "message": "Recovered"
      },
      "frequency": {
        "summary": false,
        "notify_when": "onActionGroupChange"
      }
    }
  ],
  "consumer": "alerts",
  "schedule": {
    "interval": "1d"
  },
  "rule_type_id": ".es-query"
}

Create an index threshold rule that uses a server log connector to send notifications when the threshold is met.

{
  "name": "my rule",
  "tags": [
    "cpu"
  ],
  "params": {
    "index": [
      ".test-index"
    ],
    "aggType": "avg",
    "groupBy": "top",
    "aggField": "sheet.version",
    "termSize": 6,
    "termField": "name.keyword",
    "threshold": [
      1000
    ],
    "timeField": "@timestamp",
    "timeWindowSize": 5,
    "timeWindowUnit": "m",
    "thresholdComparator": ">"
  },
  "actions": [
    {
      "id": "48de3460-f401-11ed-9f8e-399c75a2deeb",
      "group": "threshold met",
      "params": {
        "level": "info",
        "message": "Rule '{{rule.name}}' is active for group '{{context.group}}':\n\n- Value: {{context.value}}\n- Conditions Met: {{context.conditions}} over {{rule.params.timeWindowSize}}{{rule.params.timeWindowUnit}}\n- Timestamp: {{context.date}}"
      },
      "frequency": {
        "summary": false,
        "notify_when": "onActionGroupChange"
      }
    }
  ],
  "consumer": "alerts",
  "schedule": {
    "interval": "1m"
  },
  "alert_delay": {
    "active": 3
  },
  "rule_type_id": ".index-threshold"
}

Create a tracking containment rule that checks when an entity is contained or no longer contained within a boundary.

{
  "name": "my tracking rule",
  "params": {
    "index": "kibana_sample_data_logs",
    "entity": "agent.keyword",
    "indexId": "90943e30-9a47-11e8-b64d-95841ca0b247",
    "geoField": "geo.coordinates",
    "dateField\"": "@timestamp",
    "boundaryType": "entireIndex",
    "boundaryIndexId": "0cd90abf-abe7-44c7-909a-f621bbbcfefc",
    "boundaryGeoField": "location",
    "boundaryNameField": "name",
    "boundaryIndexTitle": "boundary*"
  },
  "consumer": "alerts",
  "schedule": {
    "interval": "1h"
  },
  "rule_type_id": ".geo-containment"
}

Response examples (200)

The response for successfully creating an Elasticsearch query rule that uses Elasticsearch Query Language (ES|QL).

{
  "id": "e0d62360-78e8-11ee-9177-f7d404c8c945",
  "name": "my Elasticsearch query ESQL rule",
  "tags": [],
  "params": {
    "size": 0,
    "aggType": "count",
    "groupBy": "all",
    "esqlQuery": {
      "esql": "FROM kibana_sample_data_logs | keep bytes, clientip, host, geo.dest | WHERE geo.dest != \"GB\" | stats sumbytes = sum(bytes) by clientip, host | WHERE sumbytes > 5000 | sort sumbytes desc | limit 10"
    },
    "threshold": [
      0
    ],
    "timeField": "@timestamp",
    "searchType": "esqlQuery",
    "timeWindowSize": 1,
    "timeWindowUnit": "d",
    "thresholdComparator": ">",
    "excludeHitsFromPreviousRun\"": "true,"
  },
  "actions": [
    {
      "id": "d0db1fe0-78d6-11ee-9177-f7d404c8c945",
      "uuid": "bfe370a3-531b-4855-bbe6-ad739f578844",
      "group": "query matched",
      "params": {
        "level": "info",
        "message": "Elasticsearch query rule '{{rule.name}}' is active:\n- Value: {{context.value}} - Conditions Met: {{context.conditions}} over {{rule.params.timeWindowSize}}{{rule.params.timeWindowUnit}} - Timestamp: {{context.date}} - Link: {{context.link}}"
      },
      "frequency": {
        "summary": false,
        "throttle": null,
        "notify_when": "onActiveAlert"
      },
      "connector_type_id": ".server-log"
    }
  ],
  "enabled": true,
  "running": false,
  "consumer": "stackAlerts",
  "mute_all": false,
  "revision": 0,
  "schedule": {
    "interval": "1d"
  },
  "throttle": null,
  "created_at": "2023-11-01T19:00:10.453Z",
  "created_by": "elastic",
  "updated_at": "2023-11-01T19:00:10.453Z",
  "updated_by": "elastic\",",
  "notify_when": null,
  "rule_type_id": ".es-query",
  "api_key_owner": "elastic",
  "muted_alert_ids": [],
  "execution_status": {
    "status": "pending",
    "last_execution_date": "2023-11-01T19:00:10.453Z"
  },
  "scheduled_task_id": "e0d62360-78e8-11ee-9177-f7d404c8c945",
  "api_key_created_by_user": false
}

The response for successfully creating an Elasticsearch query rule that uses Kibana query language (KQL).

{
  "id": "7bd506d0-2284-11ee-8fad-6101956ced88",
  "name": "my Elasticsearch query KQL rule\"",
  "tags": [],
  "params": {
    "size": 100,
    "aggType": "count",
    "groupBy": "all",
    "threshold": [
      1000
    ],
    "searchType": "searchSource",
    "timeWindowSize": 5,
    "timeWindowUnit": "m",
    "searchConfiguration": {
      "index": "90943e30-9a47-11e8-b64d-95841ca0b247",
      "query": {
        "query": "\"\"geo.src : \"US\" \"\"",
        "language": "kuery"
      }
    },
    "thresholdComparator": ">",
    "excludeHitsFromPreviousRun": true
  },
  "actions": [],
  "enabled": true,
  "running": false,
  "consumer": "alerts",
  "mute_all": false,
  "revision": 0,
  "schedule": {
    "interval": "1m"
  },
  "throttle": null,
  "created_at": "2023-07-14T20:24:50.729Z",
  "created_by": "elastic",
  "updated_at": "2023-07-14T20:24:50.729Z",
  "updated_by": "elastic",
  "notify_when": null,
  "rule_type_id": ".es-query",
  "api_key_owner": "elastic",
  "muted_alert_ids": [],
  "execution_status": {
    "status": "pending",
    "last_execution_date": "2023-07-14T20:24:50.729Z"
  },
  "scheduled_task_id": "7bd506d0-2284-11ee-8fad-6101956ced88",
  "api_key_created_by_user": false
}

The response for successfully creating an Elasticsearch query rule that uses Elasticsearch query domain specific language (DSL).

{
  "id": "58148c70-407f-11ee-850e-c71febc4ca7f",
  "name": "my Elasticsearch query rule",
  "tags": [],
  "params": {
    "size": 100,
    "index": [
      "kibana_sample_data_logs"
    ],
    "aggType": "count",
    "esQuery": "\"\"\"{\"query\":{\"match_all\" : {}}}\"\"\"",
    "groupBy": "all",
    "threshold": [
      100
    ],
    "timeField": "@timestamp",
    "searchType": "esQuery",
    "timeWindowSize": 1,
    "timeWindowUnit": "d",
    "thresholdComparator": ">",
    "excludeHitsFromPreviousRun": true
  },
  "actions": [
    {
      "id": "fdbece50-406c-11ee-850e-c71febc4ca7f",
      "uuid": "53f3c2a3-e5d0-4cfa-af3b-6f0881385e78",
      "group": "query matched",
      "params": {
        "level": "info",
        "message": "The system has detected {{alerts.new.count}} new, {{alerts.ongoing.count}} ongoing, and {{alerts.recovered.count}} recovered alerts."
      },
      "frequency": {
        "summary": true,
        "throttle": "1d",
        "notify_when": "onThrottleInterval"
      },
      "connector_type_id": ".server-log"
    },
    {
      "id": "fdbece50-406c-11ee-850e-c71febc4ca7f",
      "uuid": "2324e45b-c0df-45c7-9d70-4993e30be758",
      "group": "recovered",
      "params": {
        "level": "info",
        "message": "Recovered"
      },
      "frequency": {
        "summary": false,
        "throttle": null,
        "notify_when": "onActionGroupChange"
      },
      "connector_type_id": ".server-log"
    }
  ],
  "enabled": true,
  "running": false,
  "consumer": "alerts",
  "mute_all": false,
  "revision": 0,
  "schedule": {
    "interval": "1d"
  },
  "throttle": null,
  "created_at": "2023-08-22T00:03:38.263Z",
  "created_by": "elastic",
  "updated_at": "2023-08-22T00:03:38.263Z",
  "updated_by": "elastic",
  "notify_when": null,
  "rule_type_id": ".es-query",
  "api_key_owner": "elastic",
  "muted_alert_ids": [],
  "execution_status": {
    "status": "pending",
    "last_execution_date": "2023-08-22T00:03:38.263Z"
  },
  "scheduled_task_id": "58148c70-407f-11ee-850e-c71febc4ca7f",
  "api_key_created_by_user": false
}

The response for successfully creating an index threshold rule.

{
  "id": "41893910-6bca-11eb-9e0d-85d233e3ee35",
  "name": "my rule",
  "tags": [
    "cpu"
  ],
  "params": {
    "index": [
      ".test-index"
    ],
    "aggType": "avg",
    "groupBy": "top",
    "aggField": "sheet.version",
    "termSize": 6,
    "termField": "name.keyword",
    "threshold": [
      1000
    ],
    "timeField": "@timestamp",
    "timeWindowSize": 5,
    "timeWindowUnit": "m",
    "thresholdComparator": ">"
  },
  "actions": [
    {
      "id": "dceeb5d0-6b41-11eb-802b-85b0c1bc8ba2",
      "uuid": "07aef2a0-9eed-4ef9-94ec-39ba58eb609d",
      "group": "threshold met",
      "params": {
        "level": "info",
        "message": "Rule {{rule.name}} is active for group {{context.group} :\n\n- Value: {{context.value}}\n- Conditions Met: {{context.conditions}} over {{rule.params.timeWindowSize}}{{rule.params.timeWindowUnit}}\n- Timestamp: {{context.date}}"
      },
      "frequency": {
        "summary": false,
        "throttle": null,
        "notify_when": "onActionGroupChange"
      },
      "connector_type_id": ".server-log"
    }
  ],
  "enabled": true,
  "running": false,
  "consumer": "alerts",
  "mute_all": false,
  "revision": 0,
  "schedule": {
    "interval": "1m"
  },
  "throttle": null,
  "created_at": "2022-06-08T17:20:31.632Z",
  "created_by": "elastic",
  "updated_at": "2022-06-08T17:20:31.632Z",
  "updated_by": "elastic",
  "alert_delay": {
    "active": 3
  },
  "notify_when": null,
  "rule_type_id": ".index-threshold",
  "api_key_owner": "elastic",
  "muted_alert_ids": [],
  "execution_status": {
    "status": "pending",
    "last_execution_date": "2022-06-08T17:20:31.632Z"
  },
  "scheduled_task_id": "425b0800-6bca-11eb-9e0d-85d233e3ee35",
  "api_key_created_by_user": false
}

The response for successfully creating a tracking containment rule.

{
  "id": "b6883f9d-5f70-4758-a66e-369d7c26012f",
  "name": "my tracking rule",
  "tags": [],
  "params": {
    "index": "kibana_sample_data_logs",
    "entity": "agent.keyword",
    "indexId": "90943e30-9a47-11e8-b64d-95841ca0b247",
    "geoField": "geo.coordinates",
    "dateField": "@timestamp",
    "boundaryType": "entireIndex",
    "boundaryIndexId": "0cd90abf-abe7-44c7-909a-f621bbbcfefc",
    "boundaryGeoField": "location",
    "boundaryNameField": "name",
    "boundaryIndexTitle": "boundary*"
  },
  "actions": [],
  "enabled": true,
  "running": false,
  "consumer": "alerts",
  "last_run": {
    "outcome": "succeeded",
    "warning": null,
    "outcome_msg": null,
    "alerts_count": {
      "new": 0,
      "active": 0,
      "ignored": 0,
      "recovered": 0
    },
    "outcome_order": 0
  },
  "mute_all": false,
  "next_run": "2024-02-15T03:26:38.033Z",
  "revision": 1,
  "schedule": {
    "interval": "1h"
  },
  "throttle": null,
  "created_at": "2024-02-14T19:52:55.920Z",
  "created_by": "elastic",
  "updated_at": "2024-02-15T03:24:32.574Z",
  "updated_by": "elastic",
  "notify_when": null,
  "rule_type_id": ".geo-containment",
  "api_key_owner": "elastic",
  "muted_alert_ids": [],
  "execution_status": {
    "status": "ok",
    "last_duration": 74,
    "last_execution_date": "2024-02-15T03:25:38.125Z"
  },
  "scheduled_task_id": "b6883f9d-5f70-4758-a66e-369d7c26012f",
  "api_key_created_by_user": false
}

Delete a rule

DELETE /api/alerting/rule/{id}

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

Path parameters

id string Required

The identifier for the rule.

Responses

204

Indicates a successful call.
400

Indicates an invalid schema or parameters.
403

Indicates that this call is forbidden.
404

Indicates a rule with the given ID does not exist.

DELETE /api/alerting/rule/{id}

curl \
 --request DELETE 'https://<KIBANA_URL>/api/alerting/rule/{id}' \
 --header "Authorization: $API_KEY" \
 --header "kbn-xsrf: true"

Disable a rule

POST /api/alerting/rule/{id}/_disable

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

Path parameters

id string Required

The identifier for the rule.

application/json

Body

untrack boolean

Defines whether this rule's alerts should be untracked.

Responses

204

Indicates a successful call.
400

Indicates an invalid schema.
403

Indicates that this call is forbidden.
404

Indicates a rule with the given ID does not exist.

POST /api/alerting/rule/{id}/_disable

curl \
 --request POST 'https://<KIBANA_URL>/api/alerting/rule/{id}/_disable' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"untrack":true}'

Enable a rule

POST /api/alerting/rule/{id}/_enable

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

Path parameters

id string Required

The identifier for the rule.

Responses

204

Indicates a successful call.
400

Indicates an invalid schema or parameters.
403

Indicates that this call is forbidden.
404

Indicates a rule with the given ID does not exist.

POST /api/alerting/rule/{id}/_enable

curl \
 --request POST 'https://<KIBANA_URL>/api/alerting/rule/{id}/_enable' \
 --header "Authorization: $API_KEY" \
 --header "kbn-xsrf: true"

Mute all alerts

POST /api/alerting/rule/{id}/_mute_all

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

Path parameters

id string Required

The identifier for the rule.

Responses

204

Indicates a successful call.
400

Indicates an invalid schema or parameters.
403

Indicates that this call is forbidden.
404

Indicates a rule with the given ID does not exist.

POST /api/alerting/rule/{id}/_mute_all

curl \
 --request POST 'https://<KIBANA_URL>/api/alerting/rule/{id}/_mute_all' \
 --header "Authorization: $API_KEY" \
 --header "kbn-xsrf: true"

Unmute all alerts

POST /api/alerting/rule/{id}/_unmute_all

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

Path parameters

id string Required

The identifier for the rule.

Responses

204

Indicates a successful call.
400

Indicates an invalid schema or parameters.
403

Indicates that this call is forbidden.
404

Indicates a rule with the given ID does not exist.

POST /api/alerting/rule/{id}/_unmute_all

curl \
 --request POST 'https://<KIBANA_URL>/api/alerting/rule/{id}/_unmute_all' \
 --header "Authorization: $API_KEY" \
 --header "kbn-xsrf: true"

Update the API key for a rule

POST /api/alerting/rule/{id}/_update_api_key

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

Path parameters

id string Required

The identifier for the rule.

Responses

204

Indicates a successful call.
400

Indicates an invalid schema or parameters.
403

Indicates that this call is forbidden.
404

Indicates a rule with the given ID does not exist.
409

Indicates that the rule has already been updated by another user.

POST /api/alerting/rule/{id}/_update_api_key

curl \
 --request POST 'https://<KIBANA_URL>/api/alerting/rule/{id}/_update_api_key' \
 --header "Authorization: $API_KEY" \
 --header "kbn-xsrf: true"

Schedule a snooze for the rule

POST /api/alerting/rule/{id}/snooze_schedule

When you snooze a rule, the rule checks continue to run but alerts will not generate actions. You can snooze for a specified period of time and schedule single or recurring downtimes.

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

Path parameters

id string Required

Identifier of the rule.

application/json

Body

schedule object Required

Additional properties are NOT allowed.
Hide schedule attribute Show schedule attribute object
- custom object
  
  Additional properties are NOT allowed.
  Hide custom attributes Show custom attributes object
  
  duration string Required
  
  The duration of the schedule. It allows values in <integer><unit> format. <unit> is one of d, h, m, or s for hours, minutes, seconds. For example: 1d, 5h, 30m, 5000s.
  
  recurring object
  
  Additional properties are NOT allowed.
  
  Hide recurring attributes Show recurring attributes object
  
  end string
  
  The end date of a recurring schedule, provided in ISO 8601 format and set to the UTC timezone. For example: 2025-04-01T00:00:00.000Z.
  
  every string
  
  The interval and frequency of a recurring schedule. It allows values in <integer><unit> format. <unit> is one of d, w, M, or y for days, weeks, months, years. For example: 15d, 2w, 3m, 1y.
  
  occurrences number
  
  The total number of recurrences of the schedule.
  
  Minimum value is 1.
  
  onMonth array[number]
  
  The specific months for a recurring schedule. Valid values are 1-12.
  
  At least 1 element. Minimum value of each is 1, maximum value of each is 12.
  
  onMonthDay array[number]
  
  The specific days of the month for a recurring schedule. Valid values are 1-31.
  
  At least 1 element. Minimum value of each is 1, maximum value of each is 31.
  
  onWeekDay array[string]
  
  The specific days of the week ([MO,TU,WE,TH,FR,SA,SU]) or nth day of month ([+1MO, -3FR, +2WE, -4SA, -5SU]) for a recurring schedule.
  
  At least 1 element.
  
  start string Required
  
  The start date and time of the schedule, provided in ISO 8601 format and set to the UTC timezone. For example: 2025-03-12T12:00:00.000Z.
  
  timezone string
  
  The timezone of the schedule. The default timezone is UTC.

Responses

200 application/json

Indicates a successful call.
Hide response attribute Show response attribute object
- body object Required
  
  Additional properties are NOT allowed.
  
  Hide body attribute Show body attribute object
  
  schedule object Required
  
  Additional properties are NOT allowed.
  
  Hide schedule attributes Show schedule attributes object
  
  custom object
  
  Additional properties are NOT allowed.
  
  Hide custom attributes Show custom attributes object
  
  duration string Required
  
  The duration of the schedule. It allows values in <integer><unit> format. <unit> is one of d, h, m, or s for hours, minutes, seconds. For example: 1d, 5h, 30m, 5000s.
  
  recurring object
  
  Additional properties are NOT allowed.
  
  Hide recurring attributes Show recurring attributes object
  
  end string
  
  The end date of a recurring schedule, provided in ISO 8601 format and set to the UTC timezone. For example: 2025-04-01T00:00:00.000Z.
  
  every string
  
  The interval and frequency of a recurring schedule. It allows values in <integer><unit> format. <unit> is one of d, w, M, or y for days, weeks, months, years. For example: 15d, 2w, 3m, 1y.
  
  occurrences number
  
  The total number of recurrences of the schedule.
  
  Minimum value is 1.
  
  onMonth array[number]
  
  The specific months for a recurring schedule. Valid values are 1-12.
  
  At least 1 element. Minimum value of each is 1, maximum value of each is 12.
  
  onMonthDay array[number]
  
  The specific days of the month for a recurring schedule. Valid values are 1-31.
  
  At least 1 element. Minimum value of each is 1, maximum value of each is 31.
  
  onWeekDay array[string]
  
  The specific days of the week ([MO,TU,WE,TH,FR,SA,SU]) or nth day of month ([+1MO, -3FR, +2WE, -4SA, -5SU]) for a recurring schedule.
  
  At least 1 element.
  
  start string Required
  
  The start date and time of the schedule, provided in ISO 8601 format and set to the UTC timezone. For example: 2025-03-12T12:00:00.000Z.
  
  timezone string
  
  The timezone of the schedule. The default timezone is UTC.
  
  id string Required
  
  Identifier of the snooze schedule.
400

Indicates an invalid schema.
403

Indicates that this call is forbidden.
404

Indicates a rule with the given id does not exist.

POST /api/alerting/rule/{id}/snooze_schedule

curl \
 --request POST 'https://<KIBANA_URL>/api/alerting/rule/{id}/snooze_schedule' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"schedule":{"custom":{"duration":"string","recurring":{"end":"string","every":"string","occurrences":42.0,"onMonth":[42.0],"onMonthDay":[42.0],"onWeekDay":["string"]},"start":"string","timezone":"string"}}}'

Mute an alert

POST /api/alerting/rule/{rule_id}/alert/{alert_id}/_mute

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

Path parameters

rule_id string Required

The identifier for the rule.
alert_id string Required

The identifier for the alert.

Responses

204

Indicates a successful call.
400

Indicates an invalid schema or parameters.
403

Indicates that this call is forbidden.
404

Indicates a rule or alert with the given ID does not exist.

POST /api/alerting/rule/{rule_id}/alert/{alert_id}/_mute

curl \
 --request POST 'https://<KIBANA_URL>/api/alerting/rule/{rule_id}/alert/{alert_id}/_mute' \
 --header "Authorization: $API_KEY" \
 --header "kbn-xsrf: true"

Unmute an alert

POST /api/alerting/rule/{rule_id}/alert/{alert_id}/_unmute

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

Path parameters

rule_id string Required

The identifier for the rule.
alert_id string Required

The identifier for the alert.

Responses

204

Indicates a successful call.
400

Indicates an invalid schema or parameters.
403

Indicates that this call is forbidden.
404

Indicates a rule or alert with the given ID does not exist.

POST /api/alerting/rule/{rule_id}/alert/{alert_id}/_unmute

curl \
 --request POST 'https://<KIBANA_URL>/api/alerting/rule/{rule_id}/alert/{alert_id}/_unmute' \
 --header "Authorization: $API_KEY" \
 --header "kbn-xsrf: true"

Delete a snooze schedule for a rule

DELETE /api/alerting/rule/{ruleId}/snooze_schedule/{scheduleId}

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

Path parameters

ruleId string Required

The identifier for the rule.
scheduleId string Required

The identifier for the snooze schedule.

Responses

204

Indicates a successful call.
400

Indicates an invalid schema.
403

Indicates that this call is forbidden.
404

Indicates a rule with the given id does not exist.

DELETE /api/alerting/rule/{ruleId}/snooze_schedule/{scheduleId}

curl \
 --request DELETE 'https://<KIBANA_URL>/api/alerting/rule/{ruleId}/snooze_schedule/{scheduleId}' \
 --header "Authorization: $API_KEY" \
 --header "kbn-xsrf: true"

Get information about rules

GET /api/alerting/rules/_find

Query parameters

per_page number

The number of rules to return per page.

Minimum value is 0. Default value is 10.
page number

The page number to return.

Minimum value is 1. Default value is 1.
search string

An Elasticsearch simple_query_string query that filters the objects in the response.
default_search_operator string

The default operator to use for the simple_query_string.

Values are OR or AND. Default value is OR.
search_fields array[string] | string

The fields to perform the simple_query_string parsed query against.
sort_field string

Determines which field is used to sort the results. The field must exist in the attributes key of the response.
sort_order string

Determines the sort order.

Values are asc or desc.
has_reference object | null

Filters the rules that have a relation with the reference objects with a specific type and identifier.

Additional properties are NOT allowed.
Hide has_reference attributes Show has_reference attributes object | null
- id string Required
- type string Required
fields array[string]

The fields to return in the attributes key of the response.
filter string

A KQL string that you filter with an attribute from your saved object. It should look like savedObjectType.attributes.title: "myTitle". However, if you used a direct attribute of a saved object, such as updatedAt, you must define your filter, for example, savedObjectType.updatedAt > 2018-12-22.
filter_consumers array[string]

List of consumers to filter.

Responses

200 application/json

Indicates a successful call.
Hide response attributes Show response attributes object
- actions array[object] Required
  
  Hide actions attributes Show actions attributes object
  
  alerts_filter object
  
  Defines a period that limits whether the action runs.
  
  Additional properties are NOT allowed.
  
  Hide alerts_filter attributes Show alerts_filter attributes object
  
  query object
  
  Additional properties are NOT allowed.
  
  Hide query attributes Show query attributes object
  
  dsl string
  
  A filter written in Elasticsearch Query Domain Specific Language (DSL).
  
  filters array[object] Required
  
  A filter written in Elasticsearch Query Domain Specific Language (DSL) as defined in the kbn-es-query package.
  
  Hide filters attributes Show filters attributes object
  
  $state object
  
  Additional properties are NOT allowed.
  
  Hide $state attribute Show $state attribute object
  
  store string Required
  
  A filter can be either specific to an application context or applied globally.
  
  Values are appState or globalState.
  
  meta object Required
  
  Additional properties are allowed.
  
  query object
  
  Additional properties are allowed.
  
  kql string Required
  
  A filter written in Kibana Query Language (KQL).
  
  timeframe object
  
  Additional properties are NOT allowed.
  
  Hide timeframe attributes Show timeframe attributes object
  
  days array[integer] Required
  
  Defines the days of the week that the action can run, represented as an array of numbers. For example, 1 represents Monday. An empty array is equivalent to specifying all the days of the week.
  
  Values are 1, 2, 3, 4, 5, 6, or 7.
  
  hours object Required
  
  Additional properties are NOT allowed.
  
  Hide hours attributes Show hours attributes object
  
  end string Required
  
  The end of the time frame in 24-hour notation (hh:mm).
  
  start string Required
  
  The start of the time frame in 24-hour notation (hh:mm).
  
  timezone string Required
  
  The ISO time zone for the hours values. Values such as UTC and UTC+1 also work but lack built-in daylight savings time support and are not recommended.
  
  connector_type_id string Required
  
  The type of connector. This property appears in responses but cannot be set in requests.
  
  frequency object
  
  Additional properties are NOT allowed.
  
  Hide frequency attributes Show frequency attributes object
  
  notify_when string Required
  
  Indicates how often alerts generate actions. Valid values include: onActionGroupChange: Actions run when the alert status changes; onActiveAlert: Actions run when the alert becomes active and at each check interval while the rule conditions are met; onThrottleInterval: Actions run when the alert becomes active and at the interval specified in the throttle property while the rule conditions are met. NOTE: You cannot specify notify_when at both the rule and action level. The recommended method is to set it for each action. If you set it at the rule level then update the rule in Kibana, it is automatically changed to use action-specific values.
  
  Values are onActionGroupChange, onActiveAlert, or onThrottleInterval.
  
  summary boolean Required
  
  Indicates whether the action is a summary.
  
  throttle string | null Required
  
  The throttle interval, which defines how often an alert generates repeated actions. It is specified in seconds, minutes, hours, or days and is applicable only if 'notify_when' is set to 'onThrottleInterval'. NOTE: You cannot specify the throttle interval at both the rule and action level. The recommended method is to set it for each action. If you set it at the rule level then update the rule in Kibana, it is automatically changed to use action-specific values.
  
  group string
  
  The group name, which affects when the action runs (for example, when the threshold is met or when the alert is recovered). Each rule type has a list of valid action group names. If you don't need to group actions, set to default.
  
  id string Required
  
  The identifier for the connector saved object.
  
  params object Required
  
  The parameters for the action, which are sent to the connector. The params are handled as Mustache templates and passed a default set of context.
  
  Additional properties are allowed.
  
  use_alert_data_for_template boolean
  
  Indicates whether to use alert data as a template.
  
  uuid string
  
  A universally unique identifier (UUID) for the action.
- active_snoozes array[string]
  
  List of active snoozes for the rule.
- alert_delay object
  
  Indicates that an alert occurs only when the specified number of consecutive runs met the rule conditions.
  
  Additional properties are NOT allowed.
  
  Hide alert_delay attribute Show alert_delay attribute object
  
  active number Required
  
  The number of consecutive runs that must meet the rule conditions.
- api_key_created_by_user boolean | null
  
  Indicates whether the API key that is associated with the rule was created by the user.
- api_key_owner string | null Required
  
  The owner of the API key that is associated with the rule and used to run background tasks.
- artifacts object
  
  Additional properties are NOT allowed.
  
  Hide artifacts attributes Show artifacts attributes object
  
  dashboards array[object]
  
  Hide dashboards attribute Show dashboards attribute object
  
  id string Required
  
  investigation_guide object
  
  Additional properties are NOT allowed.
  
  Hide investigation_guide attribute Show investigation_guide attribute object
  
  blob string Required
  
  User-created content that describes alert causes and remdiation.
- consumer string Required
  
  The name of the application or feature that owns the rule. For example: alerts, apm, discover, infrastructure, logs, metrics, ml, monitoring, securitySolution, siem, stackAlerts, or uptime.
- created_at string Required
  
  The date and time that the rule was created.
- created_by string | null Required
  
  The identifier for the user that created the rule.
- enabled boolean Required
  
  Indicates whether you want to run the rule on an interval basis after it is created.
- execution_status object Required
  
  Additional properties are NOT allowed.
  
  Hide execution_status attributes Show execution_status attributes object
  
  error object
  
  Additional properties are NOT allowed.
  
  Hide error attributes Show error attributes object
  
  message string Required
  
  Error message.
  
  reason string Required
  
  Reason for error.
  
  Values are read, decrypt, execute, unknown, license, timeout, disabled, or validate.
  
  last_duration number
  
  Duration of last execution of the rule.
  
  last_execution_date string Required
  
  The date and time when rule was executed last.
  
  status string Required
  
  Status of rule execution.
  
  Values are ok, active, error, warning, pending, or unknown.
  
  warning object
  
  Additional properties are NOT allowed.
  
  Hide warning attributes Show warning attributes object
  
  message string Required
  
  Warning message.
  
  reason string Required
  
  Reason for warning.
  
  Values are maxExecutableActions, maxAlerts, maxQueuedActions, or ruleExecution.
- flapping object | null
  
  When flapping detection is turned on, alerts that switch quickly between active and recovered states are identified as “flapping” and notifications are reduced.
  
  Additional properties are NOT allowed.
  
  Hide flapping attributes Show flapping attributes object | null
  
  look_back_window number Required
  
  The minimum number of runs in which the threshold must be met.
  
  Minimum value is 2, maximum value is 20.
  
  status_change_threshold number Required
  
  The minimum number of times an alert must switch states in the look back window.
  
  Minimum value is 2, maximum value is 20.
- id string Required
  
  The identifier for the rule.
- is_snoozed_until string | null
  
  The date when the rule will no longer be snoozed.
- last_run object | null
  
  Additional properties are NOT allowed.
  
  Hide last_run attributes Show last_run attributes object | null
  
  alerts_count object Required
  
  Additional properties are NOT allowed.
  
  Hide alerts_count attributes Show alerts_count attributes object
  
  active number | null
  
  Number of active alerts during last run.
  
  ignored number | null
  
  Number of ignored alerts during last run.
  
  new number | null
  
  Number of new alerts during last run.
  
  recovered number | null
  
  Number of recovered alerts during last run.
  
  outcome string Required
  
  Outcome of last run of the rule. Value could be succeeded, warning or failed.
  
  Values are succeeded, warning, or failed.
  
  outcome_msg array[string] | null
  
  Outcome message generated during last rule run.
  
  outcome_order number
  
  Order of the outcome.
  
  warning string | null
  
  Warning of last rule execution.
  
  Values are read, decrypt, execute, unknown, license, timeout, disabled, validate, maxExecutableActions, maxAlerts, maxQueuedActions, or ruleExecution.
- mapped_params object
  
  Additional properties are allowed.
- monitoring object
  
  Monitoring details of the rule.
  
  Additional properties are NOT allowed.
  
  Hide monitoring attribute Show monitoring attribute object
  
  run object Required
  
  Rule run details.
  
  Additional properties are NOT allowed.
  
  Hide run attributes Show run attributes object
  
  calculated_metrics object Required
  
  Calculation of different percentiles and success ratio.
  
  Additional properties are NOT allowed.
  
  Hide calculated_metrics attributes Show calculated_metrics attributes object
  
  p50 number
  
  p95 number
  
  p99 number
  
  success_ratio number Required
  
  history array[object] Required
  
  History of the rule run.
  
  Hide history attributes Show history attributes object
  
  duration number
  
  Duration of the rule run.
  
  outcome string
  
  Outcome of last run of the rule. Value could be succeeded, warning or failed.
  
  Values are succeeded, warning, or failed.
  
  success boolean Required
  
  Indicates whether the rule run was successful.
  
  timestamp number Required
  
  Time of rule run.
  
  last_run object Required
  
  Additional properties are NOT allowed.
  
  Hide last_run attributes Show last_run attributes object
  
  metrics object Required
  
  Additional properties are NOT allowed.
  
  Hide metrics attributes Show metrics attributes object
  
  duration number
  
  Duration of most recent rule run.
  
  gap_duration_s number | null
  
  Duration in seconds of rule run gap.
  
  gap_range object | null
  
  Additional properties are NOT allowed.
  
  Hide gap_range attributes Show gap_range attributes object | null
  
  gte string Required
  
  End of the gap range.
  
  lte string Required
  
  Start of the gap range.
  
  total_alerts_created number | null
  
  Total number of alerts created during last rule run.
  
  total_alerts_detected number | null
  
  Total number of alerts detected during last rule run.
  
  total_indexing_duration_ms number | null
  
  Total time spent indexing documents during last rule run in milliseconds.
  
  total_search_duration_ms number | null
  
  Total time spent performing Elasticsearch searches as measured by Kibana; includes network latency and time spent serializing or deserializing the request and response.
  
  timestamp string Required
  
  Time of the most recent rule run.
- mute_all boolean Required
  
  Indicates whether all alerts are muted.
- muted_alert_ids array[string] Required
  
  List of identifiers of muted alerts.
- name string Required
  
  The name of the rule.
- next_run string | null
  
  Date and time of the next run of the rule.
- notify_when string | null
  
  Indicates how often alerts generate actions. Valid values include: onActionGroupChange: Actions run when the alert status changes; onActiveAlert: Actions run when the alert becomes active and at each check interval while the rule conditions are met; onThrottleInterval: Actions run when the alert becomes active and at the interval specified in the throttle property while the rule conditions are met. NOTE: You cannot specify notify_when at both the rule and action level. The recommended method is to set it for each action. If you set it at the rule level then update the rule in Kibana, it is automatically changed to use action-specific values.
  
  Values are onActionGroupChange, onActiveAlert, or onThrottleInterval.
- params object Required
  
  The parameters for the rule.
  
  Additional properties are allowed.
- revision number Required
  
  The rule revision number.
- rule_type_id string Required
  
  The rule type identifier.
- running boolean | null
  
  Indicates whether the rule is running.
- schedule object Required
  
  Additional properties are NOT allowed.
  
  Hide schedule attribute Show schedule attribute object
  
  interval string Required
  
  The interval is specified in seconds, minutes, hours, or days.
- scheduled_task_id string
  
  Identifier of the scheduled task.
- snooze_schedule array[object]
  
  Hide snooze_schedule attributes Show snooze_schedule attributes object
  
  duration number Required
  
  Duration of the rule snooze schedule.
  
  id string
  
  Identifier of the rule snooze schedule.
  
  rRule object Required
  
  Additional properties are NOT allowed.
  
  Hide rRule attributes Show rRule attributes object
  
  byhour array[number] | null
  
  Indicates hours of the day to recur.
  
  byminute array[number] | null
  
  Indicates minutes of the hour to recur.
  
  bymonth array[number] | null
  
  Indicates months of the year that this rule should recur.
  
  bymonthday array[number] | null
  
  Indicates the days of the month to recur.
  
  bysecond array[number] | null
  
  Indicates seconds of the day to recur.
  
  bysetpos array[number] | null
  
  A positive or negative integer affecting the nth day of the month. For example, -2 combined with byweekday of FR is 2nd to last Friday of the month. It is recommended to not set this manually and just use byweekday.
  
  byweekday array[string | number] | null
  
  Indicates the days of the week to recur or else nth-day-of-month strings. For example, "+2TU" second Tuesday of month, "-1FR" last Friday of the month, which are internally converted to a byweekday/bysetpos combination.
  
  byweekno array[number] | null
  
  Indicates number of the week hours to recur.
  
  byyearday array[number] | null
  
  Indicates the days of the year that this rule should recur.
  
  count number
  
  Number of times the rule should recur until it stops.
  
  dtstart string Required
  
  Rule start date in Coordinated Universal Time (UTC).
  
  freq integer
  
  Indicates frequency of the rule. Options are YEARLY, MONTHLY, WEEKLY, DAILY.
  
  Values are 0, 1, 2, 3, 4, 5, or 6.
  
  interval number
  
  Indicates the interval of frequency. For example, 1 and YEARLY is every 1 year, 2 and WEEKLY is every 2 weeks.
  
  tzid string Required
  
  Indicates timezone abbreviation.
  
  until string
  
  Recur the rule until this date.
  
  wkst string
  
  Indicates the start of week, defaults to Monday.
  
  Values are MO, TU, WE, TH, FR, SA, or SU.
  
  skipRecurrences array[string]
  
  Skips recurrence of rule on this date.
- tags array[string] Required
  
  The tags for the rule.
- throttle string | null Deprecated
  
  Deprecated in 8.13.0. Use the throttle property in the action frequency object instead. The throttle interval, which defines how often an alert generates repeated actions. NOTE: You cannot specify the throttle interval at both the rule and action level. If you set it at the rule level then update the rule in Kibana, it is automatically changed to use action-specific values.
- updated_at string Required
  
  The date and time that the rule was updated most recently.
- updated_by string | null Required
  
  The identifier for the user that updated this rule most recently.
- view_in_app_relative_url string | null
  
  Relative URL to view rule in the app.
400

Indicates an invalid schema or parameters.
403

Indicates that this call is forbidden.

GET /api/alerting/rules/_find

curl \
 --request GET 'https://<KIBANA_URL>/api/alerting/rules/_find' \
 --header "Authorization: $API_KEY"

Response examples (200)

A response that contains information about an index threshold rule.

{
  "data": [
    {
      "id": "3583a470-74f6-11ed-9801-35303b735aef",
      "name": "my alert",
      "tags": [
        "cpu"
      ],
      "params": {
        "index": [
          "test-index"
        ],
        "aggType": "avg",
        "groupBy": "top",
        "aggField": "sheet.version",
        "termSize": 6,
        "termField": "name.keyword",
        "threshold": [
          1000
        ],
        "timeField": "@timestamp",
        "timeWindowSize": 5,
        "timeWindowUnit": "m",
        "thresholdComparator": ">"
      },
      "actions": [
        {
          "id": "9dca3e00-74f5-11ed-9801-35303b735aef",
          "uuid": "1c7a1280-f28c-4e06-96b2-e4e5f05d1d61",
          "group": "threshold met",
          "params": {
            "level": "info",
            "message": "Rule {{rule.name}} is active for group {{context.group}}:\n\n- Value: {{context.value}}\n- Conditions Met: {{context.conditions}} over {{rule.params.timeWindowSize}}{{rule.params.timeWindowUnit}}\n- Timestamp: {{context.date}}",
            "connector_type_id": ".server-log"
          },
          "frequency": {
            "summary": false,
            "throttle": null,
            "notify_when": "onActionGroupChange"
          }
        }
      ],
      "enabled": true,
      "consumer": "alerts",
      "last_run": {
        "outcome": "succeeded",
        "warning": null,
        "outcome_msg": null,
        "alerts_count": {
          "new": 0,
          "active": 0,
          "ignored": 0,
          "recovered": 0
        }
      },
      "mute_all": false,
      "next_run": "2022-12-06T01:45:23.912Z",
      "revision": 1,
      "schedule": {
        "interval": "1m"
      },
      "throttle": null,
      "created_at": "2022-12-05T23:40:33.132Z",
      "created_by": "elastic",
      "updated_at": "2022-12-05T23:40:33.132Z",
      "updated_by": "elastic",
      "rule_type_id": ".index-threshold",
      "api_key_owner": "elastic",
      "muted_alert_ids": [],
      "execution_status": {
        "status": "ok",
        "last_duration": 48,
        "last_execution_date": "2022-12-06T01:44:23.983Z"
      },
      "scheduled_task_id": "3583a470-74f6-11ed-9801-35303b735aef",
      "api_key_created_by_user": false
    }
  ],
  "page": 1,
  "total": 1,
  "per_page": 10
}

A response that contains information about a security rule that has conditional actions.

{
  "data": [
    {
      "id": "6107a8f0-f401-11ed-9f8e-399c75a2deeb",
      "name": "security_rule",
      "tags": [],
      "params": {
        "to": "now",
        "from": "now-3660s",
        "meta": {
          "from": "1h",
          "kibana_siem_app_url": "https://localhost:5601/app/security"
        },
        "type": "threshold",
        "index": [
          "kibana_sample_data_logs"
        ],
        "query": "*",
        "author": [],
        "ruleId": "an_internal_rule_id",
        "threat": [],
        "filters": [],
        "license": "",
        "version": 1,
        "language": "kuery",
        "severity": "low",
        "immutable": false,
        "riskScore": 21,
        "threshold": {
          "field": [
            "bytes"
          ],
          "value": 1,
          "cardinality": []
        },
        "maxSignals": 100,
        "references": [],
        "description": "A security threshold rule.",
        "outputIndex": "",
        "exceptionsList": [],
        "falsePositives": [],
        "severityMapping": [],
        "riskScoreMapping": []
      },
      "actions": [
        {
          "id": "49eae970-f401-11ed-9f8e-399c75a2deeb",
          "uuid": "1c7a1280-f28c-4e06-96b2-e4e5f05d1d61",
          "group": "default",
          "params": {
            "documents": [
              {
                "rule_id": {
                  "[object Object]": null
                },
                "alert_id": {
                  "[object Object]": null
                },
                "rule_name": {
                  "[object Object]": null
                },
                "context_message": {
                  "[object Object]": null
                }
              }
            ]
          },
          "frequency": {
            "summary": true,
            "throttle": null,
            "notify_when": "onActiveAlert"
          },
          "alerts_filter": {
            "query": {
              "kql": "",
              "filters": [
                {
                  "meta": {
                    "key": "client.geo.region_iso_code",
                    "alias": null,
                    "field": "client.geo.region_iso_code",
                    "index": "c4bdca79-e69e-4d80-82a1-e5192c621bea",
                    "negate": false,
                    "params": {
                      "type": "phrase",
                      "query": "CA-QC"
                    },
                    "disabled": false
                  },
                  "query": {
                    "match_phrase": {
                      "client.geo.region_iso_code": "CA-QC"
                    }
                  },
                  "$state": {
                    "store": "appState"
                  }
                }
              ]
            },
            "timeframe": {
              "days": [
                7
              ],
              "hours": {
                "end": "17:00",
                "start": "08:00"
              },
              "timezone": "UTC"
            }
          },
          "connector_type_id": ".index"
        }
      ],
      "enabled": true,
      "running": false,
      "consumer": "siem",
      "last_run": {
        "outcome": "succeeded",
        "warning": null,
        "outcome_msg": [
          "Rule execution completed successfully"
        ],
        "alerts_count": {
          "new": 0,
          "active": 0,
          "ignored": 0,
          "recovered": 0
        },
        "outcome_order": 0
      },
      "mute_all": false,
      "next_run": "2023-05-16T20:27:49.507Z",
      "revision": 1,
      "schedule": {
        "interval": "1m"
      },
      "throttle": null,
      "created_at": "2023-05-16T15:50:28.358Z",
      "created_by": "elastic",
      "updated_at": "2023-05-16T20:25:42.559Z",
      "updated_by": "elastic",
      "notify_when": null,
      "rule_type_id": "siem.thresholdRule",
      "api_key_owner": "elastic",
      "muted_alert_ids": [],
      "execution_status": {
        "status": "ok",
        "last_duration": 166,
        "last_execution_date": "2023-05-16T20:26:49.590Z"
      },
      "scheduled_task_id": "6107a8f0-f401-11ed-9f8e-399c75a2deeb",
      "api_key_created_by_user": false
    }
  ],
  "page": 1,
  "total": 1,
  "per_page": 10
}

Get a list of agent configurations

GET /api/apm/settings/agent-configuration

Headers

elastic-api-version string Required

The version of the API to use

Value is 2023-10-31. Default value is 2023-10-31.

Responses

200 application/json

Successful response
Hide response attribute Show response attribute object
- configurations array[object]
  
  Agent configuration
  
  Agent configuration
  
  Hide configurations attributes Show configurations attributes object
  
  @timestamp number Required
  
  Timestamp
  
  agent_name string
  
  Agent name
  
  applied_by_agent boolean
  
  Applied by agent
  
  etag string Required
  
  etag is sent by the APM agent to indicate the etag of the last successfully applied configuration. If the etag matches an existing configuration its applied_by_agent property will be set to true. Every time a configuration is edited applied_by_agent is reset to false.
  
  service object Required
  
  Service
  
  Hide service attributes Show service attributes object
  
  environment string
  
  The environment of the service.
  
  name string
  
  The name of the service.
  
  settings object Required
  
  Agent configuration settings
  
  Hide settings attribute Show settings attribute object
  
  * string Additional properties
400 application/json

Bad Request response
Hide response attributes Show response attributes object
- error string
  
  Error type
- message string
  
  Error message
- statusCode number
  
  Error status code
401 application/json

Unauthorized response
Hide response attributes Show response attributes object
- error string
  
  Error type
- message string
  
  Error message
- statusCode number
  
  Error status code
404 application/json

Not found response
Hide response attributes Show response attributes object
- error string
  
  Error type
- message string
  
  Error message
- statusCode number
  
  Error status code

GET /api/apm/settings/agent-configuration

curl \
 --request GET 'https://<KIBANA_URL>/api/apm/settings/agent-configuration' \
 --header "Authorization: $API_KEY" \
 --header "elastic-api-version: 2023-10-31"

Response examples (200)

An example of a successful response from `GET /api/apm/settings/agent-configuration`.

[
  {
      "agent_name": "go",
      "service": {
      "name": "opbeans-go",
      "environment": "production"
      },
      "settings": {
      "transaction_sample_rate": "1",
      "capture_body": "off",
      "transaction_max_spans": "200"
      },
      "@timestamp": 1581934104843,
      "applied_by_agent": false,
      "etag": "1e58c178efeebae15c25c539da740d21dee422fc"
  },
  {
      "agent_name": "go",
      "service": {
      "name": "opbeans-go"
      },
      "settings": {
      "transaction_sample_rate": "1",
      "capture_body": "off",
      "transaction_max_spans": "300"
      },
      "@timestamp": 1581934111727,
      "applied_by_agent": false,
      "etag": "3eed916d3db434d9fb7f039daa681c7a04539a64"
  },
  {
      "agent_name": "nodejs",
      "service": {
      "name": "frontend"
      },
      "settings": {
      "transaction_sample_rate": "1",
      },
      "@timestamp": 1582031336265,
      "applied_by_agent": false,
      "etag": "5080ed25785b7b19f32713681e79f46996801a5b"
  }
]

Create or update agent configuration

PUT /api/apm/settings/agent-configuration

Headers

elastic-api-version string Required

The version of the API to use

Value is 2023-10-31. Default value is 2023-10-31.
kbn-xsrf string Required

A required header to protect against CSRF attacks

Query parameters

overwrite boolean

If the config exists ?overwrite=true is required

application/json

Body Required

agent_name string

The agent name is used by the UI to determine which settings to display.
service object Required

Service
Hide service attributes Show service attributes object
- environment string
  
  The environment of the service.
- name string
  
  The name of the service.
settings object Required

Agent configuration settings
Hide settings attribute Show settings attribute object
- * string Additional properties

Responses

200 application/json

Successful response

Additional properties are NOT allowed.
400 application/json

Bad Request response
Hide response attributes Show response attributes object
- error string
  
  Error type
- message string
  
  Error message
- statusCode number
  
  Error status code
401 application/json

Unauthorized response
Hide response attributes Show response attributes object
- error string
  
  Error type
- message string
  
  Error message
- statusCode number
  
  Error status code
403 application/json

Forbidden response
Hide response attributes Show response attributes object
- error string
  
  Error type
- message string
  
  Error message
- statusCode number
  
  Error status code
404 application/json

Not found response
Hide response attributes Show response attributes object
- error string
  
  Error type
- message string
  
  Error message
- statusCode number
  
  Error status code

PUT /api/apm/settings/agent-configuration

curl \
 --request PUT 'https://<KIBANA_URL>/api/apm/settings/agent-configuration' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "elastic-api-version: 2023-10-31" \
 --header "kbn-xsrf: true" \
 --data '"{\n    \"service\": {\n        \"name\": \"frontend\",\n        \"environment\": \"production\"\n    },\n    \"settings\": {\n        \"transaction_sample_rate\": \"0.4\",\n        \"capture_body\": \"off\",\n        \"transaction_max_spans\": \"500\"\n    },\n    \"agent_name\": \"nodejs\"\n}\n"'

Request example

Run `PUT /api/apm/settings/agent-configuration` to create or update configuration details.

{
    "service": {
        "name": "frontend",
        "environment": "production"
    },
    "settings": {
        "transaction_sample_rate": "0.4",
        "capture_body": "off",
        "transaction_max_spans": "500"
    },
    "agent_name": "nodejs"
}

Delete agent configuration

DELETE /api/apm/settings/agent-configuration

Headers

elastic-api-version string Required

The version of the API to use

Value is 2023-10-31. Default value is 2023-10-31.
kbn-xsrf string Required

A required header to protect against CSRF attacks

application/json

Body Required

environment string

The environment of the service.
name string

The name of the service.

Responses

200 application/json

Successful response
Hide response attribute Show response attribute object
- result string
  
  Result
400 application/json

Bad Request response
Hide response attributes Show response attributes object
- error string
  
  Error type
- message string
  
  Error message
- statusCode number
  
  Error status code
401 application/json

Unauthorized response
Hide response attributes Show response attributes object
- error string
  
  Error type
- message string
  
  Error message
- statusCode number
  
  Error status code
403 application/json

Forbidden response
Hide response attributes Show response attributes object
- error string
  
  Error type
- message string
  
  Error message
- statusCode number
  
  Error status code
404 application/json

Not found response
Hide response attributes Show response attributes object
- error string
  
  Error type
- message string
  
  Error message
- statusCode number
  
  Error status code

DELETE /api/apm/settings/agent-configuration

curl \
 --request DELETE 'https://<KIBANA_URL>/api/apm/settings/agent-configuration' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "elastic-api-version: 2023-10-31" \
 --header "kbn-xsrf: true" \
 --data '"{\n    \"service\" : {\n        \"name\": \"frontend\",\n        \"environment\": \"production\"\n    }\n}\n"'

Request example

Run `DELETE /api/apm/settings/agent-configuration` to delete a configuration.

{
    "service" : {
        "name": "frontend",
        "environment": "production"
    }
}

Get agent name for service

GET /api/apm/settings/agent-configuration/agent_name

Retrieve agentName for a service.

Headers

elastic-api-version string Required

The version of the API to use

Value is 2023-10-31. Default value is 2023-10-31.

Query parameters

serviceName string Required

The name of the service

Responses

200 application/json

Successful response
Hide response attribute Show response attribute object
- agentName string
  
  Agent name
400 application/json

Bad Request response
Hide response attributes Show response attributes object
- error string
  
  Error type
- message string
  
  Error message
- statusCode number
  
  Error status code
401 application/json

Unauthorized response
Hide response attributes Show response attributes object
- error string
  
  Error type
- message string
  
  Error message
- statusCode number
  
  Error status code
404 application/json

Not found response
Hide response attributes Show response attributes object
- error string
  
  Error type
- message string
  
  Error message
- statusCode number
  
  Error status code

GET /api/apm/settings/agent-configuration/agent_name

curl \
 --request GET 'https://<KIBANA_URL>/api/apm/settings/agent-configuration/agent_name?serviceName=node' \
 --header "Authorization: $API_KEY" \
 --header "elastic-api-version: 2023-10-31"

Get environments for service

GET /api/apm/settings/agent-configuration/environments

Headers

elastic-api-version string Required

The version of the API to use

Value is 2023-10-31. Default value is 2023-10-31.

Query parameters

serviceName string

The name of the service

Responses

200 application/json

Successful response
Hide response attribute Show response attribute object
- environments array[object]
  
  Service environment list
  
  Hide environments attributes Show environments attributes object
  
  alreadyConfigured boolean
  
  Already configured
  
  name string
  
  Service environment name
400 application/json

Bad Request response
Hide response attributes Show response attributes object
- error string
  
  Error type
- message string
  
  Error message
- statusCode number
  
  Error status code
401 application/json

Unauthorized response
Hide response attributes Show response attributes object
- error string
  
  Error type
- message string
  
  Error message
- statusCode number
  
  Error status code
404 application/json

Not found response
Hide response attributes Show response attributes object
- error string
  
  Error type
- message string
  
  Error message
- statusCode number
  
  Error status code

GET /api/apm/settings/agent-configuration/environments

curl \
 --request GET 'https://<KIBANA_URL>/api/apm/settings/agent-configuration/environments' \
 --header "Authorization: $API_KEY" \
 --header "elastic-api-version: 2023-10-31"

Lookup single agent configuration

POST /api/apm/settings/agent-configuration/search

This endpoint enables you to search for a single agent configuration and update the 'applied_by_agent' field.

Headers

elastic-api-version string Required

The version of the API to use

Value is 2023-10-31. Default value is 2023-10-31.
kbn-xsrf string Required

A required header to protect against CSRF attacks

application/json

Body Required

etag string

If etags match then applied_by_agent field will be set to true
mark_as_applied_by_agent boolean

markAsAppliedByAgent=true means "force setting it to true regardless of etag". This is needed for Jaeger agent that doesn't have etags
service object Required

Service
Hide service attributes Show service attributes object
- environment string
  
  The environment of the service.
- name string
  
  The name of the service.

Responses

200 application/json

Successful response
Hide response attributes Show response attributes object
- _id string
  
  Identifier
- _index string
  
  Index
- _score number
  
  Score
- _source object
  
  Agent configuration
  
  Hide _source attributes Show _source attributes object
  
  @timestamp number Required
  
  Timestamp
  
  agent_name string
  
  Agent name
  
  applied_by_agent boolean
  
  Applied by agent
  
  etag string Required
  
  etag is sent by the APM agent to indicate the etag of the last successfully applied configuration. If the etag matches an existing configuration its applied_by_agent property will be set to true. Every time a configuration is edited applied_by_agent is reset to false.
  
  service object Required
  
  Service
  
  Hide service attributes Show service attributes object
  
  environment string
  
  The environment of the service.
  
  name string
  
  The name of the service.
  
  settings object Required
  
  Agent configuration settings
  
  Hide settings attribute Show settings attribute object
  
  * string Additional properties
400 application/json

Bad Request response
Hide response attributes Show response attributes object
- error string
  
  Error type
- message string
  
  Error message
- statusCode number
  
  Error status code
401 application/json

Unauthorized response
Hide response attributes Show response attributes object
- error string
  
  Error type
- message string
  
  Error message
- statusCode number
  
  Error status code
404 application/json

Not found response
Hide response attributes Show response attributes object
- error string
  
  Error type
- message string
  
  Error message
- statusCode number
  
  Error status code

POST /api/apm/settings/agent-configuration/search

curl \
 --request POST 'https://<KIBANA_URL>/api/apm/settings/agent-configuration/search' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "elastic-api-version: 2023-10-31" \
 --header "kbn-xsrf: true" \
 --data '"{\n    \"etag\": \"1e58c178efeebae15c25c539da740d21dee422fc\",\n    \"service\" : {\n        \"name\": \"frontend\",\n        \"environment\": \"production\"\n    }\n}\n"'

Request example

Run `POST /api/apm/settings/agent-configuration/search` to search configuration details.

{
    "etag": "1e58c178efeebae15c25c539da740d21dee422fc",
    "service" : {
        "name": "frontend",
        "environment": "production"
    }
}

Response examples (200)

An example of a successful response from `POST /api/apm/settings/agent-configuration/search`.

{
  "_index": ".apm-agent-configuration",
  "_id": "CIaqXXABmQCdPphWj8EJ",
  "_score": 2,
  "_source": {
    "agent_name": "nodejs",
    "service": {
      "name": "frontend"
    },
    "settings": {
      "transaction_sample_rate": "1",
    },
    "@timestamp": 1582031336265,
    "applied_by_agent": false,
    "etag": "5080ed25785b7b19f32713681e79f46996801a5b"
  }
}

Get single agent configuration

GET /api/apm/settings/agent-configuration/view

Headers

elastic-api-version string Required

The version of the API to use

Value is 2023-10-31. Default value is 2023-10-31.

Query parameters

name string

Service name
environment string

Service environment

Responses

200 application/json

Successful response
Hide response attributes Show response attributes object
- id string Required
- @timestamp number Required
  
  Timestamp
- agent_name string
  
  Agent name
- applied_by_agent boolean
  
  Applied by agent
- etag string Required
  
  etag is sent by the APM agent to indicate the etag of the last successfully applied configuration. If the etag matches an existing configuration its applied_by_agent property will be set to true. Every time a configuration is edited applied_by_agent is reset to false.
- service object Required
  
  Service
  
  Hide service attributes Show service attributes object
  
  environment string
  
  The environment of the service.
  
  name string
  
  The name of the service.
- settings object Required
  
  Agent configuration settings
  
  Hide settings attribute Show settings attribute object
  
  * string Additional properties
400 application/json

Bad Request response
Hide response attributes Show response attributes object
- error string
  
  Error type
- message string
  
  Error message
- statusCode number
  
  Error status code
401 application/json

Unauthorized response
Hide response attributes Show response attributes object
- error string
  
  Error type
- message string
  
  Error message
- statusCode number
  
  Error status code
404 application/json

Not found response
Hide response attributes Show response attributes object
- error string
  
  Error type
- message string
  
  Error message
- statusCode number
  
  Error status code

GET /api/apm/settings/agent-configuration/view

curl \
 --request GET 'https://<KIBANA_URL>/api/apm/settings/agent-configuration/view' \
 --header "Authorization: $API_KEY" \
 --header "elastic-api-version: 2023-10-31"

Create an APM agent key

POST /api/apm/agent_keys

Create a new agent key for APM. The user creating an APM agent API key must have at least the manage_own_api_key cluster privilege and the APM application-level privileges that it wishes to grant. After it is created, you can copy the API key (Base64 encoded) and use it to to authorize requests from APM agents to the APM Server.

Headers

elastic-api-version string Required

The version of the API to use

Value is 2023-10-31. Default value is 2023-10-31.
kbn-xsrf string Required

A required header to protect against CSRF attacks

application/json

Body Required

name string Required

The name of the APM agent key.
privileges array[string] Required
The APM agent key privileges. It can take one or more of the following values:
- event:write, which is required for ingesting APM agent events. * config_agent:read, which is required for APM agents to read agent configuration remotely.
Values are event:write or config_agent:read.

Responses

200 application/json

Agent key created successfully
Hide response attribute Show response attribute object
- agentKey object
  
  Agent key
  
  Hide agentKey attributes Show agentKey attributes object
  
  api_key string Required
  
  encoded string Required
  
  expiration integer(int64)
  
  id string Required
  
  name string Required
400 application/json

Bad Request response
Hide response attributes Show response attributes object
- error string
  
  Error type
- message string
  
  Error message
- statusCode number
  
  Error status code
401 application/json

Unauthorized response
Hide response attributes Show response attributes object
- error string
  
  Error type
- message string
  
  Error message
- statusCode number
  
  Error status code
403 application/json

Forbidden response
Hide response attributes Show response attributes object
- error string
  
  Error type
- message string
  
  Error message
- statusCode number
  
  Error status code
500 application/json

Internal Server Error response
Hide response attributes Show response attributes object
- error string
  
  Error type
- message string
  
  Error message
- statusCode number
  
  Error status code

POST /api/apm/agent_keys

curl \
 --request POST 'https://<KIBANA_URL>/api/apm/agent_keys' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "elastic-api-version: 2023-10-31" \
 --header "kbn-xsrf: true" \
 --data '"{\n    \"name\": \"apm-key\",\n    \"privileges\": [\"event:write\", \"config_agent:read\"]\n}\n"'

Request example

Run `POST /api/apm/agent_keys` to create an APM agent API key with the specified privileges.

{
    "name": "apm-key",
    "privileges": ["event:write", "config_agent:read"]
}

Response examples (200)

An example of a successful response from `POST /api/apm/agent_keys`, which creates an APM agent API key.

{
  "agentKey": {
    "id": "3DCLmn0B3ZMhLUa7WBG9",
    "name": "apm-key",
    "api_key": "PjGloCGOTzaZr8ilUPvkjA",
    "encoded": "M0RDTG1uMEIzWk1oTFVhN1dCRzk6UGpHbG9DR09UemFacjhpbFVQdmtqQQ=="
  }
}

Create a service annotation

POST /api/apm/services/{serviceName}/annotation

Create a new annotation for a specific service.

Headers

elastic-api-version string Required

The version of the API to use

Value is 2023-10-31. Default value is 2023-10-31.
kbn-xsrf string Required

A required header to protect against CSRF attacks

Path parameters

serviceName string Required

The name of the service

application/json

Body Required

@timestamp string Required

The date and time of the annotation. It must be in ISO 8601 format.
message string

The message displayed in the annotation. It defaults to service.version.
service object Required

The service that identifies the configuration to create or update.
Hide service attributes Show service attributes object
- environment string
  
  The environment of the service.
- version string Required
  
  The version of the service.
tags array[string]

Tags are used by the Applications UI to distinguish APM annotations from other annotations. Tags may have additional functionality in future releases. It defaults to [apm]. While you can add additional tags, you cannot remove the apm tag.

Responses

200 application/json

Annotation created successfully
Hide response attributes Show response attributes object
- _id string
  
  Identifier
- _index string
  
  Index
- _source object
  
  Response
  
  Hide _source attributes Show _source attributes object
  
  @timestamp string
  
  annotation object
  
  Hide annotation attributes Show annotation attributes object
  
  title string
  
  type string
  
  event object
  
  Hide event attribute Show event attribute object
  
  created string
  
  message string
  
  service object
  
  Hide service attributes Show service attributes object
  
  environment string
  
  name string
  
  version string
  
  tags array[string]
400 application/json

Bad Request response
Hide response attributes Show response attributes object
- error string
  
  Error type
- message string
  
  Error message
- statusCode number
  
  Error status code
401 application/json

Unauthorized response
Hide response attributes Show response attributes object
- error string
  
  Error type
- message string
  
  Error message
- statusCode number
  
  Error status code
403 application/json

Forbidden response
Hide response attributes Show response attributes object
- error string
  
  Error type
- message string
  
  Error message
- statusCode number
  
  Error status code
404 application/json

Not found response
Hide response attributes Show response attributes object
- error string
  
  Error type
- message string
  
  Error message
- statusCode number
  
  Error status code

POST /api/apm/services/{serviceName}/annotation

curl -X POST \
http://localhost:5601/api/apm/services/opbeans-java/annotation \
-H 'Content-Type: application/json' \
-H 'kbn-xsrf: true' \
-H 'Authorization: Basic YhUlubWZhM0FDbnlQeE6WRtaW49FQmSGZ4RUWXdX' \
-d '{
    "@timestamp": "2020-05-08T10:31:30.452Z",
    "service": {
        "version": "1.2"
    },
    "message": "Deployment 1.2"
    }'

Response examples (200)

An example of a successful response from `POST /api/apm/services/opbeans-java/annotation`, which creates an annotation for a service named `opbeans-java`.

{
  "_index": "observability-annotations",
  "_id": "Lc9I93EBh6DbmkeV7nFX",
  "_version": 1,
  "_seq_no": 12,
  "_primary_term": 1,
  "found": true,
  "_source": {
    "message": "Deployment 1.2",
    "@timestamp": "2020-05-08T10:31:30.452Z",
    "service": {
      "version": "1.2",
      "name": "opbeans-java"
    },
    "tags": [
      "apm",
      "elastic.co",
      "customer"
    ],
    "annotation": {
      "type": "deployment"
    },
    "event": {
      "created": "2020-05-09T02:34:43.937Z"
    }
  }
}

Search for annotations

GET /api/apm/services/{serviceName}/annotation/search

Search for annotations related to a specific service.

Headers

elastic-api-version string Required

The version of the API to use

Value is 2023-10-31. Default value is 2023-10-31.

Path parameters

serviceName string Required

The name of the service

Query parameters

environment string

The environment to filter annotations by
start string

The start date for the search
end string

The end date for the search

Responses

200 application/json

Successful response
Hide response attribute Show response attribute object
- annotations array[object]
  
  Annotations
  
  Hide annotations attributes Show annotations attributes object
  
  @timestamp number
  
  id string
  
  text string
  
  type string
  
  Value is version.
400 application/json

Bad Request response
Hide response attributes Show response attributes object
- error string
  
  Error type
- message string
  
  Error message
- statusCode number
  
  Error status code
401 application/json

Unauthorized response
Hide response attributes Show response attributes object
- error string
  
  Error type
- message string
  
  Error message
- statusCode number
  
  Error status code
500 application/json

Internal Server Error response
Hide response attributes Show response attributes object
- error string
  
  Error type
- message string
  
  Error message
- statusCode number
  
  Error status code

GET /api/apm/services/{serviceName}/annotation/search

curl \
 --request GET 'https://<KIBANA_URL>/api/apm/services/{serviceName}/annotation/search' \
 --header "Authorization: $API_KEY" \
 --header "elastic-api-version: 2023-10-31"

Save APM server schema

POST /api/apm/fleet/apm_server_schema

Headers

elastic-api-version string Required

The version of the API to use

Value is 2023-10-31. Default value is 2023-10-31.
kbn-xsrf string Required

A required header to protect against CSRF attacks

application/json

Body Required

schema object

Schema object

Additional properties are allowed.

Responses

200 application/json

Successful response

Additional properties are NOT allowed.
400 application/json

Bad Request response
Hide response attributes Show response attributes object
- error string
  
  Error type
- message string
  
  Error message
- statusCode number
  
  Error status code
401 application/json

Unauthorized response
Hide response attributes Show response attributes object
- error string
  
  Error type
- message string
  
  Error message
- statusCode number
  
  Error status code
403 application/json

Forbidden response
Hide response attributes Show response attributes object
- error string
  
  Error type
- message string
  
  Error message
- statusCode number
  
  Error status code
404 application/json

Not found response
Hide response attributes Show response attributes object
- error string
  
  Error type
- message string
  
  Error message
- statusCode number
  
  Error status code

POST /api/apm/fleet/apm_server_schema

curl \
 --request POST 'https://<KIBANA_URL>/api/apm/fleet/apm_server_schema' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "elastic-api-version: 2023-10-31" \
 --header "kbn-xsrf: true" \
 --data '{"schema":{"foo":"bar"}}'

APM sourcemaps

Configure APM source maps. A source map allows minified files to be mapped back to original source code--allowing you to maintain the speed advantage of minified code, without losing the ability to quickly and easily debug your application. For best results, uploading source maps should become a part of your deployment procedure, and not something you only do when you see unhelpful errors. That's because uploading source maps after errors happen won't make old errors magically readable--errors must occur again for source mapping to occur.

Get source maps

GET /api/apm/sourcemaps

Get an array of Fleet artifacts, including source map uploads. You must have read or all Kibana privileges for the APM and User Experience feature.

Headers

elastic-api-version string Required

The version of the API to use

Value is 2023-10-31. Default value is 2023-10-31.

Query parameters

page number

Page number
perPage number

Number of records per page

Responses

200 application/json

Successful response
Hide response attribute Show response attribute object
- artifacts array[object]
  
  Artifacts
  
  Hide artifacts attributes Show artifacts attributes object
  
  body object
  
  Hide body attributes Show body attributes object
  
  bundleFilepath string
  
  serviceName string
  
  serviceVersion string
  
  sourceMap object
  
  Hide sourceMap attributes Show sourceMap attributes object
  
  file string
  
  mappings string
  
  sourceRoot string
  
  sources array[string]
  
  sourcesContent array[string]
  
  version number
  
  compressionAlgorithm string
  
  Compression Algorithm
  
  created string
  
  Created date
  
  decodedSha256 string
  
  Decoded SHA-256
  
  decodedSize number
  
  Decoded size
  
  encodedSha256 string
  
  Encoded SHA-256
  
  encodedSize number
  
  Encoded size
  
  encryptionAlgorithm string
  
  Encryption Algorithm
  
  id string
  
  Identifier
  
  identifier string
  
  Identifier
  
  packageName string
  
  Package name
  
  relative_url string
  
  Relative URL
  
  type string
  
  Type
400 application/json

Bad Request response
Hide response attributes Show response attributes object
- error string
  
  Error type
- message string
  
  Error message
- statusCode number
  
  Error status code
401 application/json

Unauthorized response
Hide response attributes Show response attributes object
- error string
  
  Error type
- message string
  
  Error message
- statusCode number
  
  Error status code
500 application/json

Internal Server Error response
Hide response attributes Show response attributes object
- error string
  
  Error type
- message string
  
  Error message
- statusCode number
  
  Error status code
501 application/json

Not Implemented response
Hide response attributes Show response attributes object
- error string
  
  Error type
- message string
  
  Error message
- statusCode number
  
  Error status code

GET /api/apm/sourcemaps

curl -X GET "http://localhost:5601/api/apm/sourcemaps" \
-H 'Content-Type: application/json' \
-H 'kbn-xsrf: true' \
-H 'Authorization: ApiKey ${YOUR_API_KEY}'

Response examples (200)

A successful response from `GET /api/apm/sourcemaps`.

{
  "artifacts": [
    {
      "type": "sourcemap",
      "identifier": "foo-1.0.0",
      "relative_url": "/api/fleet/artifacts/foo-1.0.0/644fd5a997d1ddd90ee131ba18e2b3d03931d89dd1fe4599143c0b3264b3e456",
      "body": {
        "serviceName": "foo",
        "serviceVersion": "1.0.0",
        "bundleFilepath": "/test/e2e/general-usecase/bundle.js",
        "sourceMap": {
          "version": 3,
          "file": "static/js/main.chunk.js",
          "sources": [
            "fleet-source-map-client/src/index.css",
            "fleet-source-map-client/src/App.js",
            "webpack:///./src/index.css?bb0a",
            "fleet-source-map-client/src/index.js",
            "fleet-source-map-client/src/reportWebVitals.js"
          ],
          "sourcesContent": [
            "content"
          ],
          "mappings": "mapping",
          "sourceRoot": ""
        }
      },
      "created": "2021-07-09T20:47:44.812Z",
      "id": "apm:foo-1.0.0-644fd5a997d1ddd90ee131ba18e2b3d03931d89dd1fe4599143c0b3264b3e456",
      "compressionAlgorithm": "zlib",
      "decodedSha256": "644fd5a997d1ddd90ee131ba18e2b3d03931d89dd1fe4599143c0b3264b3e456",
      "decodedSize": 441,
      "encodedSha256": "024c72749c3e3dd411b103f7040ae62633558608f480bce4b108cf5b2275bd24",
      "encodedSize": 237,
      "encryptionAlgorithm": "none",
      "packageName": "apm"
    }
  ]
}

Upload a source map

POST /api/apm/sourcemaps

Upload a source map for a specific service and version. You must have all Kibana privileges for the APM and User Experience feature. The maximum payload size is 1mb. If you attempt to upload a source map that exceeds the maximum payload size, you will get a 413 error. Before uploading source maps that exceed this default, change the maximum payload size allowed by Kibana with the server.maxPayload variable.

Headers

elastic-api-version string Required

The version of the API to use

Value is 2023-10-31. Default value is 2023-10-31.
kbn-xsrf string Required

A required header to protect against CSRF attacks

multipart/form-data

Body Required

bundle_filepath string Required

The absolute path of the final bundle as used in the web application.
service_name string Required

The name of the service that the service map should apply to.
service_version string Required

The version of the service that the service map should apply to.
sourcemap string(binary) Required

The source map. It can be a string or file upload. It must follow the source map format specification.

Responses

200 application/json

Successful response
Hide response attributes Show response attributes object
- body string
- compressionAlgorithm string
  
  Compression Algorithm
- created string
  
  Created date
- decodedSha256 string
  
  Decoded SHA-256
- decodedSize number
  
  Decoded size
- encodedSha256 string
  
  Encoded SHA-256
- encodedSize number
  
  Encoded size
- encryptionAlgorithm string
  
  Encryption Algorithm
- id string
  
  Identifier
- identifier string
  
  Identifier
- packageName string
  
  Package name
- relative_url string
  
  Relative URL
- type string
  
  Type
400 application/json

Bad Request response
Hide response attributes Show response attributes object
- error string
  
  Error type
- message string
  
  Error message
- statusCode number
  
  Error status code
401 application/json

Unauthorized response
Hide response attributes Show response attributes object
- error string
  
  Error type
- message string
  
  Error message
- statusCode number
  
  Error status code
403 application/json

Forbidden response
Hide response attributes Show response attributes object
- error string
  
  Error type
- message string
  
  Error message
- statusCode number
  
  Error status code
500 application/json

Internal Server Error response
Hide response attributes Show response attributes object
- error string
  
  Error type
- message string
  
  Error message
- statusCode number
  
  Error status code
501 application/json

Not Implemented response
Hide response attributes Show response attributes object
- error string
  
  Error type
- message string
  
  Error message
- statusCode number
  
  Error status code

POST /api/apm/sourcemaps

curl -X POST "http://localhost:5601/api/apm/sourcemaps" \
-H 'Content-Type: multipart/form-data' \
-H 'kbn-xsrf: true' \
-H 'Authorization: ApiKey ${YOUR_API_KEY}' \
-F 'service_name="foo"' \
-F 'service_version="1.0.0"' \
-F 'bundle_filepath="/test/e2e/general-usecase/bundle.js"' \
-F 'sourcemap="{\"version\":3,\"file\":\"static/js/main.chunk.js\",\"sources\":[\"fleet-source-map-client/src/index.css\",\"fleet-source-map-client/src/App.js\",\"webpack:///./src/index.css?bb0a\",\"fleet-source-map-client/src/index.js\",\"fleet-source-map-client/src/reportWebVitals.js\"],\"sourcesContent\":[\"content\"],\"mappings\":\"mapping\",\"sourceRoot\":\"\"}"'

Response examples (200)

A successful response from `POST /api/apm/sourcemaps`.

{
  "id": "apm:foo-1.0.0-644fd5a997d1ddd90ee131ba18e2b3d03931d89dd1fe4599143c0b3264b3e456",
  "body": "eJyFkL1OwzAUhd/Fc+MbYMuCEBIbHRjKgBgc96R16tiWr1OQqr47NwqJxEK3q/PzWccXxchnZ7E1A1SjuhjVZtF2yOxiEPlO17oWox3D3uPFeSRTjmJQARfCPeiAgGx8NTKsYdAc1T3rwaSJGcds8Sp3c1HnhfywUZ3QhMTFFGepZxqMC9oex3CS9tpk1XyozgOlmoVKuJX1DqEQZ0su7PGtLU+V/3JPKc3cL7TJ2FNDRPov4bFta3MDM4f7W69lpJjLO9qdK8bzVPhcJz3HUCQ4LbO/p5hCSC4cZPByrp/wFqOklbpefwAhzpqI",
  "type": "sourcemap",
  "created": "2021-07-09T20:47:44.812Z",
  "identifier": "foo-1.0.0",
  "decodedSize": 441,
  "encodedSize": 237,
  "packageName": "apm",
  "relative_url": "/api/fleet/artifacts/foo-1.0.0/644fd5a997d1ddd90ee131ba18e2b3d03931d89dd1fe4599143c0b3264b3e456",
  "decodedSha256": "644fd5a997d1ddd90ee131ba18e2b3d03931d89dd1fe4599143c0b3264b3e456",
  "encodedSha256": "024c72749c3e3dd411b103f7040ae62633558608f480bce4b108cf5b2275bd24",
  "encryptionAlgorithm": "none",
  "compressionAlgorithm": "zlib"
}

Delete source map

DELETE /api/apm/sourcemaps/{id}

Delete a previously uploaded source map. You must have all Kibana privileges for the APM and User Experience feature.

Headers

elastic-api-version string Required

The version of the API to use

Value is 2023-10-31. Default value is 2023-10-31.
kbn-xsrf string Required

A required header to protect against CSRF attacks

Path parameters

id string Required

Source map identifier

Responses

200 application/json

Successful response

Additional properties are NOT allowed.
400 application/json

Bad Request response
Hide response attributes Show response attributes object
- error string
  
  Error type
- message string
  
  Error message
- statusCode number
  
  Error status code
401 application/json

Unauthorized response
Hide response attributes Show response attributes object
- error string
  
  Error type
- message string
  
  Error message
- statusCode number
  
  Error status code
403 application/json

Forbidden response
Hide response attributes Show response attributes object
- error string
  
  Error type
- message string
  
  Error message
- statusCode number
  
  Error status code
500 application/json

Internal Server Error response
Hide response attributes Show response attributes object
- error string
  
  Error type
- message string
  
  Error message
- statusCode number
  
  Error status code
501 application/json

Not Implemented response
Hide response attributes Show response attributes object
- error string
  
  Error type
- message string
  
  Error message
- statusCode number
  
  Error status code

DELETE /api/apm/sourcemaps/{id}

curl -X DELETE "http://localhost:5601/api/apm/sourcemaps/apm:foo-1.0.0-644fd5a9" \
-H 'Content-Type: application/json' \
-H 'kbn-xsrf: true' \
-H 'Authorization: ApiKey ${YOUR_API_KEY}'

Get CCR Remote synced integrations status by outputId

GET /api/fleet/remote_synced_integrations/{outputId}/remote_status

[Required authorization] Route required privileges: fleet-settings-read AND integrations-read.

Path parameters

outputId string Required

Responses

200 application/json
Hide response attributes Show response attributes object
- custom_assets object
  
  Hide custom_assets attribute Show custom_assets attribute object
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  error string
  
  is_deleted boolean
  
  name string Required
  
  package_name string Required
  
  package_version string Required
  
  sync_status string Required
  
  Values are completed, synchronizing, or failed.
  
  type string Required
- error string
- integrations array[object] Required
  
  Hide integrations attributes Show integrations attributes object
  
  error string
  
  id string
  
  package_name string
  
  package_version string
  
  sync_status string Required
  
  Values are completed, synchronizing, or failed.
  
  updated_at string
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

GET /api/fleet/remote_synced_integrations/{outputId}/remote_status

curl \
 --request GET 'https://<KIBANA_URL>/api/fleet/remote_synced_integrations/{outputId}/remote_status' \
 --header "Authorization: $API_KEY"

Get CCR Remote synced integrations status

GET /api/fleet/remote_synced_integrations/status

[Required authorization] Route required privileges: fleet-settings-read AND integrations-read.

Responses

200 application/json
Hide response attributes Show response attributes object
- custom_assets object
  
  Hide custom_assets attribute Show custom_assets attribute object
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  error string
  
  is_deleted boolean
  
  name string Required
  
  package_name string Required
  
  package_version string Required
  
  sync_status string Required
  
  Values are completed, synchronizing, or failed.
  
  type string Required
- error string
- integrations array[object] Required
  
  Hide integrations attributes Show integrations attributes object
  
  error string
  
  id string
  
  package_name string
  
  package_version string
  
  sync_status string Required
  
  Values are completed, synchronizing, or failed.
  
  updated_at string
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

GET /api/fleet/remote_synced_integrations/status

curl \
 --request GET 'https://<KIBANA_URL>/api/fleet/remote_synced_integrations/status' \
 --header "Authorization: $API_KEY"

Get connector types

GET /api/actions/connector_types

You do not need any Kibana feature privileges to run this API.

Query parameters

feature_id string

A filter to limit the retrieved connector types to those that support a specific feature (such as alerting or cases).

Responses

200 application/json

Indicates a successful call.

GET /api/actions/connector_types

curl \
 --request GET 'https://<KIBANA_URL>/api/actions/connector_types' \
 --header "Authorization: $API_KEY"

Response examples (200)

[
  {
    "id": ".gen-ai",
    "name": "OpenAI",
    "enabled": true,
    "enabled_in_config": true,
    "enabled_in_license": true,
    "is_system_action_type": false,
    "supported_feature_ids": [
      "generativeAIForSecurity",
      "generativeAIForObservability",
      "generativeAIForSearchPlayground"
    ],
    "minimum_license_required": "enterprise"
  },
  {
    "id": ".bedrock",
    "name": "AWS Bedrock",
    "enabled": true,
    "enabled_in_config": true,
    "enabled_in_license": true,
    "is_system_action_type": false,
    "supported_feature_ids": [
      "generativeAIForSecurity",
      "generativeAIForObservability",
      "generativeAIForSearchPlayground"
    ],
    "minimum_license_required": "enterprise"
  },
  {
    "id": ".gemini",
    "name": "Google Gemini",
    "enabled": true,
    "enabled_in_config": true,
    "enabled_in_license": true,
    "is_system_action_type": false,
    "supported_feature_ids": [
      "generativeAIForSecurity"
    ],
    "minimum_license_required": "enterprise"
  }
]

Get connector information

GET /api/actions/connector/{id}

Path parameters

id string Required

An identifier for the connector.

Responses

200 application/json

Indicates a successful call.
Hide response attributes Show response attributes object
- config object
  
  Additional properties are allowed.
- connector_type_id string Required
  
  The connector type identifier.
- id string Required
  
  The identifier for the connector.
- is_deprecated boolean Required
  
  Indicates whether the connector is deprecated.
- is_missing_secrets boolean
  
  Indicates whether the connector is missing secrets.
- is_preconfigured boolean Required
  
  Indicates whether the connector is preconfigured. If true, the config and is_missing_secrets properties are omitted from the response.
- is_system_action boolean Required
  
  Indicates whether the connector is used for system actions.
- name string Required
  
  The name of the rule.

GET /api/actions/connector/{id}

curl \
 --request GET 'https://<KIBANA_URL>/api/actions/connector/{id}' \
 --header "Authorization: $API_KEY"

Response examples (200)

{
  "id": "df770e30-8b8b-11ed-a780-3b746c987a81",
  "name": "my_server_log_connector",
  "config": {},
  "is_deprecated": false,
  "is_preconfigured": false,
  "is_system_action": false,
  "connector_type_id": ".server-log",
  "is_missing_secrets": false
}

Update a connector

PUT /api/actions/connector/{id}

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

Path parameters

id string Required

An identifier for the connector.

application/json

Body

name string Required

The display name for the connector.
config object

The connector configuration details.
One of:
bedrock_config object crowdstrike_config object d3security_config object email_config object gemini_config object resilient_config object index_config object jira_config object genai_azure_config object genai_openai_config object opsgenie_config object pagerduty_config object sentinelone_config object servicenow_config object servicenow_itom_config object slack_api_config object swimlane_config object thehive_config object tines_config object torq_config object webhook_config object cases_webhook_config object xmatters_config object
Defines properties for connectors when type is .bedrock.
Hide attributes Show attributes

apiUrl string Required

The Amazon Bedrock request URL.

defaultModel string

The generative artificial intelligence model for Amazon Bedrock to use. Current support is for the Anthropic Claude models.

Default value is anthropic.claude-3-5-sonnet-20240620-v1:0.
Defines config properties for connectors when type is .crowdstrike.
Hide attribute Show attribute

url string Required

The CrowdStrike tenant URL. If you are using the xpack.actions.allowedHosts setting, add the hostname to the allowed hosts.
Defines properties for connectors when type is .d3security.
Hide attribute Show attribute

url string Required

The D3 Security API request URL. If you are using the xpack.actions.allowedHosts setting, add the hostname to the allowed hosts.
Defines properties for connectors when type is .email.
Hide attributes Show attributes

clientId string | null

The client identifier, which is a part of OAuth 2.0 client credentials authentication, in GUID format. If service is exchange_server, this property is required.

from string Required

The from address for all emails sent by the connector. It must be specified in user@host-name format.

hasAuth boolean

Specifies whether a user and password are required inside the secrets configuration.

Default value is true.

host string

The host name of the service provider. If the service is elastic_cloud (for Elastic Cloud notifications) or one of Nodemailer's well-known email service providers, this property is ignored. If service is other, this property must be defined.

oauthTokenUrl string | null

port integer

The port to connect to on the service provider. If the service is elastic_cloud (for Elastic Cloud notifications) or one of Nodemailer's well-known email service providers, this property is ignored. If service is other, this property must be defined.

secure boolean

Specifies whether the connection to the service provider will use TLS. If the service is elastic_cloud (for Elastic Cloud notifications) or one of Nodemailer's well-known email service providers, this property is ignored.

service string

The name of the email service.

Values are elastic_cloud, exchange_server, gmail, other, outlook365, or ses.

tenantId string | null

The tenant identifier, which is part of OAuth 2.0 client credentials authentication, in GUID format. If service is exchange_server, this property is required.
Defines properties for connectors when type is .gemini.
Hide attributes Show attributes

apiUrl string Required

The Google Gemini request URL.

defaultModel string

The generative artificial intelligence model for Google Gemini to use.

Default value is gemini-1.5-pro-002.

gcpRegion string Required

The GCP region where the Vertex AI endpoint enabled.

gcpProjectID string Required

The Google ProjectID that has Vertex AI endpoint enabled.
Defines properties for connectors when type is .resilient.
Hide attributes Show attributes

apiUrl string Required

The IBM Resilient instance URL.

orgId string Required

The IBM Resilient organization ID.
Defines properties for connectors when type is .index.
Hide attributes Show attributes

executionTimeField string | null

A field that indicates when the document was indexed.

index string Required

The Elasticsearch index to be written to.

refresh boolean

The refresh policy for the write request, which affects when changes are made visible to search. Refer to the refresh setting for Elasticsearch document APIs.

Default value is false.
Defines properties for connectors when type is .jira.
Hide attributes Show attributes

apiUrl string Required

The Jira instance URL.

projectKey string Required

The Jira project key.
Defines properties for connectors when type is .gen-ai and the API provider is Azure OpenAI.
Hide attributes Show attributes

apiProvider string Required

The OpenAI API provider.

Value is Azure OpenAI.

apiUrl string Required

The OpenAI API endpoint.
Defines properties for connectors when type is .gen-ai and the API provider is OpenAI.
Hide attributes Show attributes

apiProvider string Required

The OpenAI API provider.

Value is OpenAI.

apiUrl string Required

The OpenAI API endpoint.

defaultModel string

The default model to use for requests.
Defines properties for connectors when type is .opsgenie.
Hide attribute Show attribute

apiUrl string Required

The Opsgenie URL. For example, https://api.opsgenie.com or https://api.eu.opsgenie.com. If you are using the xpack.actions.allowedHosts setting, add the hostname to the allowed hosts.
Defines properties for connectors when type is .pagerduty.
Hide attribute Show attribute

apiUrl string | null

The PagerDuty event URL.
Defines properties for connectors when type is .sentinelone.
Hide attribute Show attribute

url string Required

The SentinelOne tenant URL. If you are using the xpack.actions.allowedHosts setting, add the hostname to the allowed hosts.
Defines properties for connectors when type is .servicenow.
Hide attributes Show attributes

apiUrl string Required

The ServiceNow instance URL.

clientId string

The client ID assigned to your OAuth application. This property is required when isOAuth is true.

isOAuth boolean

The type of authentication to use. The default value is false, which means basic authentication is used instead of open authorization (OAuth).

Default value is false.

jwtKeyId string

The key identifier assigned to the JWT verifier map of your OAuth application. This property is required when isOAuth is true.

userIdentifierValue string

The identifier to use for OAuth authentication. This identifier should be the user field you selected when you created an OAuth JWT API endpoint for external clients in your ServiceNow instance. For example, if the selected user field is Email, the user identifier should be the user's email address. This property is required when isOAuth is true.

usesTableApi boolean

Determines whether the connector uses the Table API or the Import Set API. This property is supported only for ServiceNow ITSM and ServiceNow SecOps connectors. NOTE: If this property is set to false, the Elastic application should be installed in ServiceNow.

Default value is true.
Defines properties for connectors when type is .servicenow-itom.
Hide attributes Show attributes

apiUrl string Required

The ServiceNow instance URL.

clientId string

The client ID assigned to your OAuth application. This property is required when isOAuth is true.

isOAuth boolean

The type of authentication to use. The default value is false, which means basic authentication is used instead of open authorization (OAuth).

Default value is false.

jwtKeyId string

The key identifier assigned to the JWT verifier map of your OAuth application. This property is required when isOAuth is true.

userIdentifierValue string

The identifier to use for OAuth authentication. This identifier should be the user field you selected when you created an OAuth JWT API endpoint for external clients in your ServiceNow instance. For example, if the selected user field is Email, the user identifier should be the user's email address. This property is required when isOAuth is true.
Defines properties for connectors when type is .slack_api.
Hide attribute Show attribute

allowedChannels array[object]

A list of valid Slack channels.

Hide allowedChannels attributes Show allowedChannels attributes object

id string Required

The Slack channel ID.

Minimum length is 1.

name string Required

The Slack channel name.

Minimum length is 1.
Defines properties for connectors when type is .swimlane.
Hide attributes Show attributes

apiUrl string Required

The Swimlane instance URL.

appId string Required

The Swimlane application ID.

connectorType string Required

The type of connector. Valid values are all, alerts, and cases.

Values are all, alerts, or cases.

mappings object

The field mapping.

Hide mappings attributes Show mappings attributes object

alertIdConfig object

Mapping for the alert ID.

Hide alertIdConfig attributes Show alertIdConfig attributes object

fieldType string Required

The type of field in Swimlane.

id string Required

The identifier for the field in Swimlane.

key string Required

The key for the field in Swimlane.

name string Required

The name of the field in Swimlane.

caseIdConfig object

Mapping for the case ID.

Hide caseIdConfig attributes Show caseIdConfig attributes object

fieldType string Required

The type of field in Swimlane.

id string Required

The identifier for the field in Swimlane.

key string Required

The key for the field in Swimlane.

name string Required

The name of the field in Swimlane.

caseNameConfig object

Mapping for the case name.

Hide caseNameConfig attributes Show caseNameConfig attributes object

fieldType string Required

The type of field in Swimlane.

id string Required

The identifier for the field in Swimlane.

key string Required

The key for the field in Swimlane.

name string Required

The name of the field in Swimlane.

commentsConfig object

Mapping for the case comments.

Hide commentsConfig attributes Show commentsConfig attributes object

fieldType string Required

The type of field in Swimlane.

id string Required

The identifier for the field in Swimlane.

key string Required

The key for the field in Swimlane.

name string Required

The name of the field in Swimlane.

descriptionConfig object

Mapping for the case description.

Hide descriptionConfig attributes Show descriptionConfig attributes object

fieldType string Required

The type of field in Swimlane.

id string Required

The identifier for the field in Swimlane.

key string Required

The key for the field in Swimlane.

name string Required

The name of the field in Swimlane.

ruleNameConfig object

Mapping for the name of the alert's rule.

Hide ruleNameConfig attributes Show ruleNameConfig attributes object

fieldType string Required

The type of field in Swimlane.

id string Required

The identifier for the field in Swimlane.

key string Required

The key for the field in Swimlane.

name string Required

The name of the field in Swimlane.

severityConfig object

Mapping for the severity.

Hide severityConfig attributes Show severityConfig attributes object

fieldType string Required

The type of field in Swimlane.

id string Required

The identifier for the field in Swimlane.

key string Required

The key for the field in Swimlane.

name string Required

The name of the field in Swimlane.
Defines configuration properties for connectors when type is .thehive.
Hide attributes Show attributes

organisation string

The organisation in TheHive that will contain the alerts or cases. By default, the connector uses the default organisation of the user account that created the API key.

url string Required

The instance URL in TheHive. If you are using the xpack.actions.allowedHosts setting, add the hostname to the allowed hosts.
Defines properties for connectors when type is .tines.
Hide attribute Show attribute

url string Required

The Tines tenant URL. If you are using the xpack.actions.allowedHosts setting, make sure this hostname is added to the allowed hosts.
Defines properties for connectors when type is .torq.
Hide attribute Show attribute

webhookIntegrationUrl string Required

The endpoint URL of the Elastic Security integration in Torq.
Defines properties for connectors when type is .webhook.
Hide attributes Show attributes

authType string | null

The type of authentication to use: basic, SSL, or none.

Values are webhook-authentication-basic or webhook-authentication-ssl.

ca string

A base64 encoded version of the certificate authority file that the connector can trust to sign and validate certificates. This option is available for all authentication types.

certType string

If the authType is webhook-authentication-ssl, specifies whether the certificate authentication data is in a CRT and key file format or a PFX file format.

Values are ssl-crt-key or ssl-pfx.

hasAuth boolean

If true, a username and password for login type authentication must be provided.

Default value is true.

headers object | null

A set of key-value pairs sent as headers with the request.

method string

The HTTP request method, either post or put.

Values are post or put. Default value is post.

url string

The request URL. If you are using the xpack.actions.allowedHosts setting, add the hostname to the allowed hosts.

verificationMode string

Controls the verification of certificates. Use full to validate that the certificate has an issue date within the not_before and not_after dates, chains to a trusted certificate authority (CA), and has a hostname or IP address that matches the names within the certificate. Use certificate to validate the certificate and verify that it is signed by a trusted authority; this option does not check the certificate hostname. Use none to skip certificate validation.

Values are certificate, full, or none. Default value is full.
Defines properties for connectors when type is .cases-webhook.
Hide attributes Show attributes

authType string | null

The type of authentication to use: basic, SSL, or none.

Values are webhook-authentication-basic or webhook-authentication-ssl.

ca string

A base64 encoded version of the certificate authority file that the connector can trust to sign and validate certificates. This option is available for all authentication types.

certType string

If the authType is webhook-authentication-ssl, specifies whether the certificate authentication data is in a CRT and key file format or a PFX file format.

Values are ssl-crt-key or ssl-pfx.

createCommentJson string

A JSON payload sent to the create comment URL to create a case comment. You can use variables to add Kibana Cases data to the payload. The required variable is case.comment. Due to Mustache template variables (the text enclosed in triple braces, for example, {{{case.title}}}), the JSON is not validated when you create the connector. The JSON is validated once the Mustache variables have been placed when the REST method runs. Manually ensure that the JSON is valid, disregarding the Mustache variables, so the later validation will pass.

createCommentMethod string

The REST API HTTP request method to create a case comment in the third-party system. Valid values are patch, post, and put.

Values are patch, post, or put. Default value is put.

createCommentUrl string

The REST API URL to create a case comment by ID in the third-party system. You can use a variable to add the external system ID to the URL. If you are using the xpack.actions.allowedHosts setting, add the hostname to the allowed hosts.

createIncidentJson string Required

A JSON payload sent to the create case URL to create a case. You can use variables to add case data to the payload. Required variables are case.title and case.description. Due to Mustache template variables (which is the text enclosed in triple braces, for example, {{{case.title}}}), the JSON is not validated when you create the connector. The JSON is validated after the Mustache variables have been placed when REST method runs. Manually ensure that the JSON is valid to avoid future validation errors; disregard Mustache variables during your review.

createIncidentMethod string

The REST API HTTP request method to create a case in the third-party system. Valid values are patch, post, and put.

Values are patch, post, or put. Default value is post.

createIncidentResponseKey string Required

The JSON key in the create external case response that contains the case ID.

createIncidentUrl string Required

The REST API URL to create a case in the third-party system. If you are using the xpack.actions.allowedHosts setting, add the hostname to the allowed hosts.

getIncidentResponseExternalTitleKey string Required

The JSON key in get external case response that contains the case title.

getIncidentUrl string Required

The REST API URL to get the case by ID from the third-party system. If you are using the xpack.actions.allowedHosts setting, add the hostname to the allowed hosts. You can use a variable to add the external system ID to the URL. Due to Mustache template variables (the text enclosed in triple braces, for example, {{{case.title}}}), the JSON is not validated when you create the connector. The JSON is validated after the Mustache variables have been placed when REST method runs. Manually ensure that the JSON is valid, disregarding the Mustache variables, so the later validation will pass.

hasAuth boolean

If true, a username and password for login type authentication must be provided.

Default value is true.

headers string

A set of key-value pairs sent as headers with the request URLs for the create case, update case, get case, and create comment methods.

updateIncidentJson string Required

The JSON payload sent to the update case URL to update the case. You can use variables to add Kibana Cases data to the payload. Required variables are case.title and case.description. Due to Mustache template variables (which is the text enclosed in triple braces, for example, {{{case.title}}}), the JSON is not validated when you create the connector. The JSON is validated after the Mustache variables have been placed when REST method runs. Manually ensure that the JSON is valid to avoid future validation errors; disregard Mustache variables during your review.

updateIncidentMethod string

The REST API HTTP request method to update the case in the third-party system. Valid values are patch, post, and put.

Values are patch, post, or put. Default value is put.

updateIncidentUrl string Required

The REST API URL to update the case by ID in the third-party system. You can use a variable to add the external system ID to the URL. If you are using the xpack.actions.allowedHosts setting, add the hostname to the allowed hosts.

verificationMode string

Controls the verification of certificates. Use full to validate that the certificate has an issue date within the not_before and not_after dates, chains to a trusted certificate authority (CA), and has a hostname or IP address that matches the names within the certificate. Use certificate to validate the certificate and verify that it is signed by a trusted authority; this option does not check the certificate hostname. Use none to skip certificate validation.

Values are certificate, full, or none. Default value is full.

viewIncidentUrl string Required

The URL to view the case in the external system. You can use variables to add the external system ID or external system title to the URL.
Defines properties for connectors when type is .xmatters.
Hide attributes Show attributes

configUrl string | null

The request URL for the Elastic Alerts trigger in xMatters. It is applicable only when usesBasic is true.

usesBasic boolean

Specifies whether the connector uses HTTP basic authentication (true) or URL authentication (false).

Default value is true.
secrets object
One of:
bedrock_secrets object crowdstrike_secrets object d3security_secrets object email_secrets object gemini_secrets object resilient_secrets object jira_secrets object teams_secrets object genai_secrets object opsgenie_secrets object pagerduty_secrets object sentinelone_secrets object servicenow_secrets object slack_api_secrets object swimlane_secrets object thehive_secrets object tines_secrets object torq_secrets object webhook_secrets object cases_webhook_secrets object xmatters_secrets object
Defines secrets for connectors when type is .bedrock.
Hide attributes Show attributes

accessKey string Required

The AWS access key for authentication.

secret string Required

The AWS secret for authentication.
Defines secrets for connectors when type is .crowdstrike.
Hide attributes Show attributes

clientId string Required

The CrowdStrike API client identifier.

clientSecret string Required

The CrowdStrike API client secret to authenticate the clientId.
Defines secrets for connectors when type is .d3security.
Hide attribute Show attribute

token string Required

The D3 Security token.
Defines secrets for connectors when type is .email.
Hide attributes Show attributes

clientSecret string

The Microsoft Exchange Client secret for OAuth 2.0 client credentials authentication. It must be URL-encoded. If service is exchange_server, this property is required.

password string

The password for HTTP basic authentication. If hasAuth is set to true, this property is required.

user string

The username for HTTP basic authentication. If hasAuth is set to true, this property is required.
Defines secrets for connectors when type is .gemini.
Hide attribute Show attribute

credentialsJson string Required

The service account credentials JSON file. The service account should have Vertex AI user IAM role assigned to it.
Defines secrets for connectors when type is .resilient.
Hide attributes Show attributes

apiKeyId string Required

The authentication key ID for HTTP Basic authentication.

apiKeySecret string Required

The authentication key secret for HTTP Basic authentication.
Defines secrets for connectors when type is .jira.
Hide attributes Show attributes

apiToken string Required

The Jira API authentication token for HTTP basic authentication.

email string Required

The account email for HTTP Basic authentication.
Defines secrets for connectors when type is .teams.
Hide attribute Show attribute

webhookUrl string Required

The URL of the incoming webhook. If you are using the xpack.actions.allowedHosts setting, add the hostname to the allowed hosts.
Defines secrets for connectors when type is .gen-ai.
Hide attribute Show attribute

apiKey string

The OpenAI API key.
Defines secrets for connectors when type is .opsgenie.
Hide attribute Show attribute

apiKey string Required

The Opsgenie API authentication key for HTTP Basic authentication.
Defines secrets for connectors when type is .pagerduty.
Hide attribute Show attribute

routingKey string Required

A 32 character PagerDuty Integration Key for an integration on a service.
Defines secrets for connectors when type is .sentinelone.
Hide attribute Show attribute

token string Required

The A SentinelOne API token.
Defines secrets for connectors when type is .servicenow, .servicenow-sir, or .servicenow-itom.
Hide attributes Show attributes

clientSecret string

The client secret assigned to your OAuth application. This property is required when isOAuth is true.

password string

The password for HTTP basic authentication. This property is required when isOAuth is false.

privateKey string

The RSA private key that you created for use in ServiceNow. This property is required when isOAuth is true.

privateKeyPassword string

The password for the RSA private key. This property is required when isOAuth is true and you set a password on your private key.

username string

The username for HTTP basic authentication. This property is required when isOAuth is false.
Defines secrets for connectors when type is .slack.
Hide attribute Show attribute

token string Required

Slack bot user OAuth token.
Defines secrets for connectors when type is .swimlane.
Hide attribute Show attribute

apiToken string

Swimlane API authentication token.
Defines secrets for connectors when type is .thehive.
Hide attribute Show attribute

apiKey string Required

The API key for authentication in TheHive.
Defines secrets for connectors when type is .tines.
Hide attributes Show attributes

email string Required

The email used to sign in to Tines.

token string Required

The Tines API token.
Defines secrets for connectors when type is .torq.
Hide attribute Show attribute

token string Required

The secret of the webhook authentication header.
Defines secrets for connectors when type is .webhook.
Hide attributes Show attributes

crt string

If authType is webhook-authentication-ssl and certType is ssl-crt-key, it is a base64 encoded version of the CRT or CERT file.

key string

If authType is webhook-authentication-ssl and certType is ssl-crt-key, it is a base64 encoded version of the KEY file.

pfx string

If authType is webhook-authentication-ssl and certType is ssl-pfx, it is a base64 encoded version of the PFX or P12 file.

password string

The password for HTTP basic authentication or the passphrase for the SSL certificate files. If hasAuth is set to true and authType is webhook-authentication-basic, this property is required.

user string

The username for HTTP basic authentication. If hasAuth is set to true and authType is webhook-authentication-basic, this property is required.
Hide attributes Show attributes

crt string

If authType is webhook-authentication-ssl and certType is ssl-crt-key, it is a base64 encoded version of the CRT or CERT file.

key string

If authType is webhook-authentication-ssl and certType is ssl-crt-key, it is a base64 encoded version of the KEY file.

pfx string

If authType is webhook-authentication-ssl and certType is ssl-pfx, it is a base64 encoded version of the PFX or P12 file.

password string

The password for HTTP basic authentication. If hasAuth is set to true and and authType is webhook-authentication-basic, this property is required.

user string

The username for HTTP basic authentication. If hasAuth is set to true and authType is webhook-authentication-basic, this property is required.
Defines secrets for connectors when type is .xmatters.
Hide attributes Show attributes

password string

A user name for HTTP basic authentication. It is applicable only when usesBasic is true.

secretsUrl string

The request URL for the Elastic Alerts trigger in xMatters with the API key included in the URL. It is applicable only when usesBasic is false.

user string

A password for HTTP basic authentication. It is applicable only when usesBasic is true.

Responses

200 application/json

Indicates a successful call.
Hide response attributes Show response attributes object
- config object
  
  Additional properties are allowed.
- connector_type_id string Required
  
  The connector type identifier.
- id string Required
  
  The identifier for the connector.
- is_deprecated boolean Required
  
  Indicates whether the connector is deprecated.
- is_missing_secrets boolean
  
  Indicates whether the connector is missing secrets.
- is_preconfigured boolean Required
  
  Indicates whether the connector is preconfigured. If true, the config and is_missing_secrets properties are omitted from the response.
- is_system_action boolean Required
  
  Indicates whether the connector is used for system actions.
- name string Required
  
  The name of the rule.

PUT /api/actions/connector/{id}

curl \
 --request PUT 'https://<KIBANA_URL>/api/actions/connector/{id}' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"name":"updated-connector","config":{"index":"updated-index"}}'

Request example

{
  "name": "updated-connector",
  "config": {
    "index": "updated-index"
  }
}

Create a connector

POST /api/actions/connector/{id}

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

Path parameters

id string Required

An identifier for the connector.

application/json

Body

connector_type_id string Required

The type of connector.
name string Required

The display name for the connector.
config object

The connector configuration details.
One of:
bedrock_config object crowdstrike_config object d3security_config object email_config object gemini_config object resilient_config object index_config object jira_config object genai_azure_config object genai_openai_config object opsgenie_config object pagerduty_config object sentinelone_config object servicenow_config object servicenow_itom_config object slack_api_config object swimlane_config object thehive_config object tines_config object torq_config object webhook_config object cases_webhook_config object xmatters_config object
Defines properties for connectors when type is .bedrock.
Hide attributes Show attributes

apiUrl string Required

The Amazon Bedrock request URL.

defaultModel string

The generative artificial intelligence model for Amazon Bedrock to use. Current support is for the Anthropic Claude models.

Default value is anthropic.claude-3-5-sonnet-20240620-v1:0.
Defines config properties for connectors when type is .crowdstrike.
Hide attribute Show attribute

url string Required

The CrowdStrike tenant URL. If you are using the xpack.actions.allowedHosts setting, add the hostname to the allowed hosts.
Defines properties for connectors when type is .d3security.
Hide attribute Show attribute

url string Required

The D3 Security API request URL. If you are using the xpack.actions.allowedHosts setting, add the hostname to the allowed hosts.
Defines properties for connectors when type is .email.
Hide attributes Show attributes

clientId string | null

The client identifier, which is a part of OAuth 2.0 client credentials authentication, in GUID format. If service is exchange_server, this property is required.

from string Required

The from address for all emails sent by the connector. It must be specified in user@host-name format.

hasAuth boolean

Specifies whether a user and password are required inside the secrets configuration.

Default value is true.

host string

The host name of the service provider. If the service is elastic_cloud (for Elastic Cloud notifications) or one of Nodemailer's well-known email service providers, this property is ignored. If service is other, this property must be defined.

oauthTokenUrl string | null

port integer

The port to connect to on the service provider. If the service is elastic_cloud (for Elastic Cloud notifications) or one of Nodemailer's well-known email service providers, this property is ignored. If service is other, this property must be defined.

secure boolean

Specifies whether the connection to the service provider will use TLS. If the service is elastic_cloud (for Elastic Cloud notifications) or one of Nodemailer's well-known email service providers, this property is ignored.

service string

The name of the email service.

Values are elastic_cloud, exchange_server, gmail, other, outlook365, or ses.

tenantId string | null

The tenant identifier, which is part of OAuth 2.0 client credentials authentication, in GUID format. If service is exchange_server, this property is required.
Defines properties for connectors when type is .gemini.
Hide attributes Show attributes

apiUrl string Required

The Google Gemini request URL.

defaultModel string

The generative artificial intelligence model for Google Gemini to use.

Default value is gemini-1.5-pro-002.

gcpRegion string Required

The GCP region where the Vertex AI endpoint enabled.

gcpProjectID string Required

The Google ProjectID that has Vertex AI endpoint enabled.
Defines properties for connectors when type is .resilient.
Hide attributes Show attributes

apiUrl string Required

The IBM Resilient instance URL.

orgId string Required

The IBM Resilient organization ID.
Defines properties for connectors when type is .index.
Hide attributes Show attributes

executionTimeField string | null

A field that indicates when the document was indexed.

index string Required

The Elasticsearch index to be written to.

refresh boolean

The refresh policy for the write request, which affects when changes are made visible to search. Refer to the refresh setting for Elasticsearch document APIs.

Default value is false.
Defines properties for connectors when type is .jira.
Hide attributes Show attributes

apiUrl string Required

The Jira instance URL.

projectKey string Required

The Jira project key.
Defines properties for connectors when type is .gen-ai and the API provider is Azure OpenAI.
Hide attributes Show attributes

apiProvider string Required

The OpenAI API provider.

Value is Azure OpenAI.

apiUrl string Required

The OpenAI API endpoint.
Defines properties for connectors when type is .gen-ai and the API provider is OpenAI.
Hide attributes Show attributes

apiProvider string Required

The OpenAI API provider.

Value is OpenAI.

apiUrl string Required

The OpenAI API endpoint.

defaultModel string

The default model to use for requests.
Defines properties for connectors when type is .opsgenie.
Hide attribute Show attribute

apiUrl string Required

The Opsgenie URL. For example, https://api.opsgenie.com or https://api.eu.opsgenie.com. If you are using the xpack.actions.allowedHosts setting, add the hostname to the allowed hosts.
Defines properties for connectors when type is .pagerduty.
Hide attribute Show attribute

apiUrl string | null

The PagerDuty event URL.
Defines properties for connectors when type is .sentinelone.
Hide attribute Show attribute

url string Required

The SentinelOne tenant URL. If you are using the xpack.actions.allowedHosts setting, add the hostname to the allowed hosts.
Defines properties for connectors when type is .servicenow.
Hide attributes Show attributes

apiUrl string Required

The ServiceNow instance URL.

clientId string

The client ID assigned to your OAuth application. This property is required when isOAuth is true.

isOAuth boolean

The type of authentication to use. The default value is false, which means basic authentication is used instead of open authorization (OAuth).

Default value is false.

jwtKeyId string

The key identifier assigned to the JWT verifier map of your OAuth application. This property is required when isOAuth is true.

userIdentifierValue string

The identifier to use for OAuth authentication. This identifier should be the user field you selected when you created an OAuth JWT API endpoint for external clients in your ServiceNow instance. For example, if the selected user field is Email, the user identifier should be the user's email address. This property is required when isOAuth is true.

usesTableApi boolean

Determines whether the connector uses the Table API or the Import Set API. This property is supported only for ServiceNow ITSM and ServiceNow SecOps connectors. NOTE: If this property is set to false, the Elastic application should be installed in ServiceNow.

Default value is true.
Defines properties for connectors when type is .servicenow-itom.
Hide attributes Show attributes

apiUrl string Required

The ServiceNow instance URL.

clientId string

The client ID assigned to your OAuth application. This property is required when isOAuth is true.

isOAuth boolean

The type of authentication to use. The default value is false, which means basic authentication is used instead of open authorization (OAuth).

Default value is false.

jwtKeyId string

The key identifier assigned to the JWT verifier map of your OAuth application. This property is required when isOAuth is true.

userIdentifierValue string

The identifier to use for OAuth authentication. This identifier should be the user field you selected when you created an OAuth JWT API endpoint for external clients in your ServiceNow instance. For example, if the selected user field is Email, the user identifier should be the user's email address. This property is required when isOAuth is true.
Defines properties for connectors when type is .slack_api.
Hide attribute Show attribute

allowedChannels array[object]

A list of valid Slack channels.

Hide allowedChannels attributes Show allowedChannels attributes object

id string Required

The Slack channel ID.

Minimum length is 1.

name string Required

The Slack channel name.

Minimum length is 1.
Defines properties for connectors when type is .swimlane.
Hide attributes Show attributes

apiUrl string Required

The Swimlane instance URL.

appId string Required

The Swimlane application ID.

connectorType string Required

The type of connector. Valid values are all, alerts, and cases.

Values are all, alerts, or cases.

mappings object

The field mapping.

Hide mappings attributes Show mappings attributes object

alertIdConfig object

Mapping for the alert ID.

Hide alertIdConfig attributes Show alertIdConfig attributes object

fieldType string Required

The type of field in Swimlane.

id string Required

The identifier for the field in Swimlane.

key string Required

The key for the field in Swimlane.

name string Required

The name of the field in Swimlane.

caseIdConfig object

Mapping for the case ID.

Hide caseIdConfig attributes Show caseIdConfig attributes object

fieldType string Required

The type of field in Swimlane.

id string Required

The identifier for the field in Swimlane.

key string Required

The key for the field in Swimlane.

name string Required

The name of the field in Swimlane.

caseNameConfig object

Mapping for the case name.

Hide caseNameConfig attributes Show caseNameConfig attributes object

fieldType string Required

The type of field in Swimlane.

id string Required

The identifier for the field in Swimlane.

key string Required

The key for the field in Swimlane.

name string Required

The name of the field in Swimlane.

commentsConfig object

Mapping for the case comments.

Hide commentsConfig attributes Show commentsConfig attributes object

fieldType string Required

The type of field in Swimlane.

id string Required

The identifier for the field in Swimlane.

key string Required

The key for the field in Swimlane.

name string Required

The name of the field in Swimlane.

descriptionConfig object

Mapping for the case description.

Hide descriptionConfig attributes Show descriptionConfig attributes object

fieldType string Required

The type of field in Swimlane.

id string Required

The identifier for the field in Swimlane.

key string Required

The key for the field in Swimlane.

name string Required

The name of the field in Swimlane.

ruleNameConfig object

Mapping for the name of the alert's rule.

Hide ruleNameConfig attributes Show ruleNameConfig attributes object

fieldType string Required

The type of field in Swimlane.

id string Required

The identifier for the field in Swimlane.

key string Required

The key for the field in Swimlane.

name string Required

The name of the field in Swimlane.

severityConfig object

Mapping for the severity.

Hide severityConfig attributes Show severityConfig attributes object

fieldType string Required

The type of field in Swimlane.

id string Required

The identifier for the field in Swimlane.

key string Required

The key for the field in Swimlane.

name string Required

The name of the field in Swimlane.
Defines configuration properties for connectors when type is .thehive.
Hide attributes Show attributes

organisation string

The organisation in TheHive that will contain the alerts or cases. By default, the connector uses the default organisation of the user account that created the API key.

url string Required

The instance URL in TheHive. If you are using the xpack.actions.allowedHosts setting, add the hostname to the allowed hosts.
Defines properties for connectors when type is .tines.
Hide attribute Show attribute

url string Required

The Tines tenant URL. If you are using the xpack.actions.allowedHosts setting, make sure this hostname is added to the allowed hosts.
Defines properties for connectors when type is .torq.
Hide attribute Show attribute

webhookIntegrationUrl string Required

The endpoint URL of the Elastic Security integration in Torq.
Defines properties for connectors when type is .webhook.
Hide attributes Show attributes

authType string | null

The type of authentication to use: basic, SSL, or none.

Values are webhook-authentication-basic or webhook-authentication-ssl.

ca string

A base64 encoded version of the certificate authority file that the connector can trust to sign and validate certificates. This option is available for all authentication types.

certType string

If the authType is webhook-authentication-ssl, specifies whether the certificate authentication data is in a CRT and key file format or a PFX file format.

Values are ssl-crt-key or ssl-pfx.

hasAuth boolean

If true, a username and password for login type authentication must be provided.

Default value is true.

headers object | null

A set of key-value pairs sent as headers with the request.

method string

The HTTP request method, either post or put.

Values are post or put. Default value is post.

url string

The request URL. If you are using the xpack.actions.allowedHosts setting, add the hostname to the allowed hosts.

verificationMode string

Controls the verification of certificates. Use full to validate that the certificate has an issue date within the not_before and not_after dates, chains to a trusted certificate authority (CA), and has a hostname or IP address that matches the names within the certificate. Use certificate to validate the certificate and verify that it is signed by a trusted authority; this option does not check the certificate hostname. Use none to skip certificate validation.

Values are certificate, full, or none. Default value is full.
Defines properties for connectors when type is .cases-webhook.
Hide attributes Show attributes

authType string | null

The type of authentication to use: basic, SSL, or none.

Values are webhook-authentication-basic or webhook-authentication-ssl.

ca string

A base64 encoded version of the certificate authority file that the connector can trust to sign and validate certificates. This option is available for all authentication types.

certType string

If the authType is webhook-authentication-ssl, specifies whether the certificate authentication data is in a CRT and key file format or a PFX file format.

Values are ssl-crt-key or ssl-pfx.

createCommentJson string

A JSON payload sent to the create comment URL to create a case comment. You can use variables to add Kibana Cases data to the payload. The required variable is case.comment. Due to Mustache template variables (the text enclosed in triple braces, for example, {{{case.title}}}), the JSON is not validated when you create the connector. The JSON is validated once the Mustache variables have been placed when the REST method runs. Manually ensure that the JSON is valid, disregarding the Mustache variables, so the later validation will pass.

createCommentMethod string

The REST API HTTP request method to create a case comment in the third-party system. Valid values are patch, post, and put.

Values are patch, post, or put. Default value is put.

createCommentUrl string

The REST API URL to create a case comment by ID in the third-party system. You can use a variable to add the external system ID to the URL. If you are using the xpack.actions.allowedHosts setting, add the hostname to the allowed hosts.

createIncidentJson string Required

A JSON payload sent to the create case URL to create a case. You can use variables to add case data to the payload. Required variables are case.title and case.description. Due to Mustache template variables (which is the text enclosed in triple braces, for example, {{{case.title}}}), the JSON is not validated when you create the connector. The JSON is validated after the Mustache variables have been placed when REST method runs. Manually ensure that the JSON is valid to avoid future validation errors; disregard Mustache variables during your review.

createIncidentMethod string

The REST API HTTP request method to create a case in the third-party system. Valid values are patch, post, and put.

Values are patch, post, or put. Default value is post.

createIncidentResponseKey string Required

The JSON key in the create external case response that contains the case ID.

createIncidentUrl string Required

The REST API URL to create a case in the third-party system. If you are using the xpack.actions.allowedHosts setting, add the hostname to the allowed hosts.

getIncidentResponseExternalTitleKey string Required

The JSON key in get external case response that contains the case title.

getIncidentUrl string Required

The REST API URL to get the case by ID from the third-party system. If you are using the xpack.actions.allowedHosts setting, add the hostname to the allowed hosts. You can use a variable to add the external system ID to the URL. Due to Mustache template variables (the text enclosed in triple braces, for example, {{{case.title}}}), the JSON is not validated when you create the connector. The JSON is validated after the Mustache variables have been placed when REST method runs. Manually ensure that the JSON is valid, disregarding the Mustache variables, so the later validation will pass.

hasAuth boolean

If true, a username and password for login type authentication must be provided.

Default value is true.

headers string

A set of key-value pairs sent as headers with the request URLs for the create case, update case, get case, and create comment methods.

updateIncidentJson string Required

The JSON payload sent to the update case URL to update the case. You can use variables to add Kibana Cases data to the payload. Required variables are case.title and case.description. Due to Mustache template variables (which is the text enclosed in triple braces, for example, {{{case.title}}}), the JSON is not validated when you create the connector. The JSON is validated after the Mustache variables have been placed when REST method runs. Manually ensure that the JSON is valid to avoid future validation errors; disregard Mustache variables during your review.

updateIncidentMethod string

The REST API HTTP request method to update the case in the third-party system. Valid values are patch, post, and put.

Values are patch, post, or put. Default value is put.

updateIncidentUrl string Required

The REST API URL to update the case by ID in the third-party system. You can use a variable to add the external system ID to the URL. If you are using the xpack.actions.allowedHosts setting, add the hostname to the allowed hosts.

verificationMode string

Controls the verification of certificates. Use full to validate that the certificate has an issue date within the not_before and not_after dates, chains to a trusted certificate authority (CA), and has a hostname or IP address that matches the names within the certificate. Use certificate to validate the certificate and verify that it is signed by a trusted authority; this option does not check the certificate hostname. Use none to skip certificate validation.

Values are certificate, full, or none. Default value is full.

viewIncidentUrl string Required

The URL to view the case in the external system. You can use variables to add the external system ID or external system title to the URL.
Defines properties for connectors when type is .xmatters.
Hide attributes Show attributes

configUrl string | null

The request URL for the Elastic Alerts trigger in xMatters. It is applicable only when usesBasic is true.

usesBasic boolean

Specifies whether the connector uses HTTP basic authentication (true) or URL authentication (false).

Default value is true.
secrets object
One of:
bedrock_secrets object crowdstrike_secrets object d3security_secrets object email_secrets object gemini_secrets object resilient_secrets object jira_secrets object teams_secrets object genai_secrets object opsgenie_secrets object pagerduty_secrets object sentinelone_secrets object servicenow_secrets object slack_api_secrets object swimlane_secrets object thehive_secrets object tines_secrets object torq_secrets object webhook_secrets object cases_webhook_secrets object xmatters_secrets object
Defines secrets for connectors when type is .bedrock.
Hide attributes Show attributes

accessKey string Required

The AWS access key for authentication.

secret string Required

The AWS secret for authentication.
Defines secrets for connectors when type is .crowdstrike.
Hide attributes Show attributes

clientId string Required

The CrowdStrike API client identifier.

clientSecret string Required

The CrowdStrike API client secret to authenticate the clientId.
Defines secrets for connectors when type is .d3security.
Hide attribute Show attribute

token string Required

The D3 Security token.
Defines secrets for connectors when type is .email.
Hide attributes Show attributes

clientSecret string

The Microsoft Exchange Client secret for OAuth 2.0 client credentials authentication. It must be URL-encoded. If service is exchange_server, this property is required.

password string

The password for HTTP basic authentication. If hasAuth is set to true, this property is required.

user string

The username for HTTP basic authentication. If hasAuth is set to true, this property is required.
Defines secrets for connectors when type is .gemini.
Hide attribute Show attribute

credentialsJson string Required

The service account credentials JSON file. The service account should have Vertex AI user IAM role assigned to it.
Defines secrets for connectors when type is .resilient.
Hide attributes Show attributes

apiKeyId string Required

The authentication key ID for HTTP Basic authentication.

apiKeySecret string Required

The authentication key secret for HTTP Basic authentication.
Defines secrets for connectors when type is .jira.
Hide attributes Show attributes

apiToken string Required

The Jira API authentication token for HTTP basic authentication.

email string Required

The account email for HTTP Basic authentication.
Defines secrets for connectors when type is .teams.
Hide attribute Show attribute

webhookUrl string Required

The URL of the incoming webhook. If you are using the xpack.actions.allowedHosts setting, add the hostname to the allowed hosts.
Defines secrets for connectors when type is .gen-ai.
Hide attribute Show attribute

apiKey string

The OpenAI API key.
Defines secrets for connectors when type is .opsgenie.
Hide attribute Show attribute

apiKey string Required

The Opsgenie API authentication key for HTTP Basic authentication.
Defines secrets for connectors when type is .pagerduty.
Hide attribute Show attribute

routingKey string Required

A 32 character PagerDuty Integration Key for an integration on a service.
Defines secrets for connectors when type is .sentinelone.
Hide attribute Show attribute

token string Required

The A SentinelOne API token.
Defines secrets for connectors when type is .servicenow, .servicenow-sir, or .servicenow-itom.
Hide attributes Show attributes

clientSecret string

The client secret assigned to your OAuth application. This property is required when isOAuth is true.

password string

The password for HTTP basic authentication. This property is required when isOAuth is false.

privateKey string

The RSA private key that you created for use in ServiceNow. This property is required when isOAuth is true.

privateKeyPassword string

The password for the RSA private key. This property is required when isOAuth is true and you set a password on your private key.

username string

The username for HTTP basic authentication. This property is required when isOAuth is false.
Defines secrets for connectors when type is .slack.
Hide attribute Show attribute

token string Required

Slack bot user OAuth token.
Defines secrets for connectors when type is .swimlane.
Hide attribute Show attribute

apiToken string

Swimlane API authentication token.
Defines secrets for connectors when type is .thehive.
Hide attribute Show attribute

apiKey string Required

The API key for authentication in TheHive.
Defines secrets for connectors when type is .tines.
Hide attributes Show attributes

email string Required

The email used to sign in to Tines.

token string Required

The Tines API token.
Defines secrets for connectors when type is .torq.
Hide attribute Show attribute

token string Required

The secret of the webhook authentication header.
Defines secrets for connectors when type is .webhook.
Hide attributes Show attributes

crt string

If authType is webhook-authentication-ssl and certType is ssl-crt-key, it is a base64 encoded version of the CRT or CERT file.

key string

If authType is webhook-authentication-ssl and certType is ssl-crt-key, it is a base64 encoded version of the KEY file.

pfx string

If authType is webhook-authentication-ssl and certType is ssl-pfx, it is a base64 encoded version of the PFX or P12 file.

password string

The password for HTTP basic authentication or the passphrase for the SSL certificate files. If hasAuth is set to true and authType is webhook-authentication-basic, this property is required.

user string

The username for HTTP basic authentication. If hasAuth is set to true and authType is webhook-authentication-basic, this property is required.
Hide attributes Show attributes

crt string

If authType is webhook-authentication-ssl and certType is ssl-crt-key, it is a base64 encoded version of the CRT or CERT file.

key string

If authType is webhook-authentication-ssl and certType is ssl-crt-key, it is a base64 encoded version of the KEY file.

pfx string

If authType is webhook-authentication-ssl and certType is ssl-pfx, it is a base64 encoded version of the PFX or P12 file.

password string

The password for HTTP basic authentication. If hasAuth is set to true and and authType is webhook-authentication-basic, this property is required.

user string

The username for HTTP basic authentication. If hasAuth is set to true and authType is webhook-authentication-basic, this property is required.
Defines secrets for connectors when type is .xmatters.
Hide attributes Show attributes

password string

A user name for HTTP basic authentication. It is applicable only when usesBasic is true.

secretsUrl string

The request URL for the Elastic Alerts trigger in xMatters with the API key included in the URL. It is applicable only when usesBasic is false.

user string

A password for HTTP basic authentication. It is applicable only when usesBasic is true.

Responses

200 application/json

Indicates a successful call.
Hide response attributes Show response attributes object
- config object
  
  Additional properties are allowed.
- connector_type_id string Required
  
  The connector type identifier.
- id string Required
  
  The identifier for the connector.
- is_deprecated boolean Required
  
  Indicates whether the connector is deprecated.
- is_missing_secrets boolean
  
  Indicates whether the connector is missing secrets.
- is_preconfigured boolean Required
  
  Indicates whether the connector is preconfigured. If true, the config and is_missing_secrets properties are omitted from the response.
- is_system_action boolean Required
  
  Indicates whether the connector is used for system actions.
- name string Required
  
  The name of the rule.

POST /api/actions/connector/{id}

curl \
 --request POST 'https://<KIBANA_URL>/api/actions/connector/{id}' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"name":"email-connector-1","config":{"from":"tester@example.com","host":"https://example.com","port":1025,"secure":false,"hasAuth":true,"service":"other"},"secrets":{"user":"username","password":"password"},"connector_type_id":".email"}'

Request examples

{
  "name": "email-connector-1",
  "config": {
    "from": "tester@example.com",
    "host": "https://example.com",
    "port": 1025,
    "secure": false,
    "hasAuth": true,
    "service": "other"
  },
  "secrets": {
    "user": "username",
    "password": "password"
  },
  "connector_type_id": ".email"
}

{
  "name": "my-connector",
  "config": {
    "index": "test-index"
  },
  "connector_type_id": ".index"
}

{
  "name": "my-webhook-connector",
  "config": {
    "url": "https://example.com",
    "method": "post",
    "authType": "webhook-authentication-ssl",
    "certType": "ssl-crt-key"
  },
  "secrets": {
    "crt": "QmFnIEF0dH...",
    "key": "LS0tLS1CRUdJ...",
    "password": "my-passphrase"
  },
  "connector_type_id": ".webhook"
}

{
  "name": "my-xmatters-connector",
  "config": {
    "usesBasic": false
  },
  "secrets": {
    "secretsUrl": "https://example.com?apiKey=xxxxx"
  },
  "connector_type_id": ".xmatters"
}

Response examples (200)

{
  "id": "90a82c60-478f-11ee-a343-f98a117c727f",
  "name": "email-connector-1",
  "config": {
    "from": "tester@example.com",
    "host": "https://example.com",
    "port": 1025,
    "secure": false,
    "hasAuth": true,
    "service": "other",
    "clientId": null,
    "tenantId": null,
    "oauthTokenUrl": null
  },
  "is_deprecated": false,
  "is_preconfigured": false,
  "is_system_action": false,
  "connector_type_id": ".email",
  "is_missing_secrets": false
}

{
  "id": "c55b6eb0-6bad-11eb-9f3b-611eebc6c3ad",
  "name": "my-connector",
  "config": {
    "index": "test-index",
    "refresh": false,
    "executionTimeField": null
  },
  "is_deprecated": false,
  "is_preconfigured": false,
  "is_system_action": false,
  "connector_type_id": ".index",
  "is_missing_secrets": false
}

{
  "id": "900eb010-3b9d-11ee-a642-8ffbb94e38bd",
  "name": "my-webhook-connector",
  "config": {
    "url": "https://example.com",
    "method": "post",
    "hasAuth": true,
    "headers": null,
    "authType": "webhook-authentication-ssl",
    "certType": "ssl-crt-key",
    "verificationMode": "full"
  },
  "is_deprecated": false,
  "is_preconfigured": false,
  "is_system_action": false,
  "connector_type_id": ".webhook",
  "is_missing_secrets": false
}

{
  "id": "df770e30-8b8b-11ed-a780-3b746c987a81",
  "name": "my_server_log_connector",
  "config": {},
  "is_deprecated": false,
  "is_preconfigured": false,
  "is_system_action": false,
  "connector_type_id": ".server-log",
  "is_missing_secrets": false
}

Delete a connector

DELETE /api/actions/connector/{id}

WARNING: When you delete a connector, it cannot be recovered.

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

Path parameters

id string Required

An identifier for the connector.

Responses

204

Indicates a successful call.

DELETE /api/actions/connector/{id}

curl \
 --request DELETE 'https://<KIBANA_URL>/api/actions/connector/{id}' \
 --header "Authorization: $API_KEY" \
 --header "kbn-xsrf: true"

Run a connector

POST /api/actions/connector/{id}/_execute

You can use this API to test an action that involves interaction with Kibana services or integrations with third-party systems.

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

Path parameters

id string Required

An identifier for the connector.

application/json

Body

params object Required
One of:
run_acknowledge_resolve_pagerduty object run_documents object run_message_email object run_message_serverlog object run_message_slack object run_trigger_pagerduty object run_addevent object run_closealert object run_closeincident object run_createalert object run_fieldsbyissuetype object run_getchoices object run_getfields object run_getincident object run_issue object run_issues object run_issuetypes object run_postmessage object run_pushtoservice object run_validchannelid object
Test an action that acknowledges or resolves a PagerDuty alert.
Hide attributes Show attributes

dedupKey string Required

The deduplication key for the PagerDuty alert.

Maximum length is 255.

eventAction string Required

The type of event.

Values are acknowledge or resolve.
Test an action that indexes a document into Elasticsearch.
Hide attribute Show attribute

documents array[object] Required

The documents in JSON format for index connectors.

Additional properties are allowed.
Test an action that sends an email message. There must be at least one recipient in to, cc, or bcc.
Hide attributes Show attributes

bcc array[string]

A list of "blind carbon copy" email addresses. Addresses can be specified in user@host-name format or in name <user@host-name> format

cc array[string]

A list of "carbon copy" email addresses. Addresses can be specified in user@host-name format or in name <user@host-name> format

message string Required

The email message text. Markdown format is supported.

subject string Required

The subject line of the email.

to array[string]

A list of email addresses. Addresses can be specified in user@host-name format or in name <user@host-name> format.
Test an action that writes an entry to the Kibana server log.
Hide attributes Show attributes

level string

The log level of the message for server log connectors.

Values are debug, error, fatal, info, trace, or warn. Default value is info.

message string Required

The message for server log connectors.
Test an action that sends a message to Slack. It is applicable only when the connector type is .slack.
Hide attribute Show attribute

message string Required

The Slack message text, which cannot contain Markdown, images, or other advanced formatting.
Test an action that triggers a PagerDuty alert.
Hide attributes Show attributes

class string

The class or type of the event.

component string

The component of the source machine that is responsible for the event.

customDetails object

Additional details to add to the event.

dedupKey string

All actions sharing this key will be associated with the same PagerDuty alert. This value is used to correlate trigger and resolution.

Maximum length is 255.

eventAction string Required

The type of event.

Value is trigger.

group string

The logical grouping of components of a service.

links array[object]

A list of links to add to the event.

Hide links attributes Show links attributes object

href string

The URL for the link.

text string

A plain text description of the purpose of the link.

severity string

The severity of the event on the affected system.

Values are critical, error, info, or warning. Default value is info.

source string

The affected system, such as a hostname or fully qualified domain name. Defaults to the Kibana saved object id of the action.

summary string

A summery of the event.

Maximum length is 1024.

timestamp string(date-time)

An ISO-8601 timestamp that indicates when the event was detected or generated.
The addEvent subaction for ServiceNow ITOM connectors.
Hide attributes Show attributes

subAction string Required

The action to test.

Value is addEvent.

subActionParams object

The set of configuration properties for the action.

Hide subActionParams attributes Show subActionParams attributes object

additional_info string

Additional information about the event.

description string

The details about the event.

event_class string

A specific instance of the source.

message_key string

All actions sharing this key are associated with the same ServiceNow alert. The default value is <rule ID>:<alert instance ID>.

metric_name string

The name of the metric.

node string

The host that the event was triggered for.

resource string

The name of the resource.

severity string

The severity of the event.

source string

The name of the event source type.

time_of_event string

The time of the event.

type string

The type of event.
The closeAlert subaction for Opsgenie connectors.
Hide attributes Show attributes

subAction string Required

The action to test.

Value is closeAlert.

subActionParams object Required

Hide subActionParams attributes Show subActionParams attributes object

alias string Required

The unique identifier used for alert deduplication in Opsgenie. The alias must match the value used when creating the alert.

note string

Additional information for the alert.

source string

The display name for the source of the alert.

user string

The display name for the owner.
The closeIncident subaction for ServiceNow ITSM connectors.
Hide attributes Show attributes

subAction string Required

The action to test.

Value is closeIncident.

subActionParams object Required

Hide subActionParams attribute Show subActionParams attribute object

incident object Required

Any of:
object-1 object object-2 object

Hide attributes Show attributes

correlation_id string | null Required

An identifier that is assigned to the incident when it is created by the connector. NOTE: If you use the default value and the rule generates multiple alerts that use the same alert IDs, the latest open incident for this correlation ID is closed unless you specify the external ID.

Maximum length is 100. Default value is {{rule.id}}:{{alert.id}}.

externalId string | null

The unique identifier (incidentId) for the incident in ServiceNow.

Hide attributes Show attributes

correlation_id string | null

An identifier that is assigned to the incident when it is created by the connector. NOTE: If you use the default value and the rule generates multiple alerts that use the same alert IDs, the latest open incident for this correlation ID is closed unless you specify the external ID.

Maximum length is 100. Default value is {{rule.id}}:{{alert.id}}.

externalId string | null Required

The unique identifier (incidentId) for the incident in ServiceNow.
The createAlert subaction for Opsgenie and TheHive connectors.
Hide attributes Show attributes

subAction string Required

The action to test.

Value is createAlert.

subActionParams object Required

Hide subActionParams attributes Show subActionParams attributes object

actions array[string]

The custom actions available to the alert in Opsgenie connectors.

alias string

The unique identifier used for alert deduplication in Opsgenie.

description string

A description that provides detailed information about the alert.

details object

The custom properties of the alert in Opsgenie connectors.

Additional properties are allowed.

entity string

The domain of the alert in Opsgenie connectors. For example, the application or server name.

message string

The alert message in Opsgenie connectors.

note string

Additional information for the alert in Opsgenie connectors.

priority string

The priority level for the alert in Opsgenie connectors.

Values are P1, P2, P3, P4, or P5.

responders array[object]

The entities to receive notifications about the alert in Opsgenie connectors. If type is user, either id or username is required. If type is team, either id or name is required.

Hide responders attributes Show responders attributes object

id string

The identifier for the entity.

name string

The name of the entity.

type string

The type of responders, in this case escalation.

Values are escalation, schedule, team, or user.

username string

A valid email address for the user.

severity integer

The severity of the incident for TheHive connectors. The value ranges from 1 (low) to 4 (critical) with a default value of 2 (medium).

Minimum value is 1, maximum value is 4.

source string

The display name for the source of the alert in Opsgenie and TheHive connectors.

sourceRef string

A source reference for the alert in TheHive connectors.

tags array[string]

The tags for the alert in Opsgenie and TheHive connectors.

title string

A title for the incident for TheHive connectors. It is used for searching the contents of the knowledge base.

tlp integer

The traffic light protocol designation for the incident in TheHive connectors. Valid values include: 0 (clear), 1 (green), 2 (amber), 3 (amber and strict), and 4 (red).

Minimum value is 0, maximum value is 4. Default value is 2.

type string

The type of alert in TheHive connectors.

user string

The display name for the owner.

visibleTo array[object]

The teams and users that the alert will be visible to without sending a notification. Only one of id, name, or username is required.

Hide visibleTo attributes Show visibleTo attributes object

id string

The identifier for the entity.

name string

The name of the entity.

type string Required

Valid values are team and user.

Values are team or user.

username string

The user name. This property is required only when the type is user.
The fieldsByIssueType subaction for Jira connectors.
Hide attributes Show attributes

subAction string Required

The action to test.

Value is fieldsByIssueType.

subActionParams object Required

Hide subActionParams attribute Show subActionParams attribute object

id string Required

The Jira issue type identifier.
The getChoices subaction for ServiceNow ITOM, ServiceNow ITSM, and ServiceNow SecOps connectors.
Hide attributes Show attributes

subAction string Required

The action to test.

Value is getChoices.

subActionParams object Required

The set of configuration properties for the action.

Hide subActionParams attribute Show subActionParams attribute object

fields array[string] Required

An array of fields.
The getFields subaction for Jira, ServiceNow ITSM, and ServiceNow SecOps connectors.
Hide attribute Show attribute

subAction string Required

The action to test.

Value is getFields.
The getIncident subaction for Jira, ServiceNow ITSM, and ServiceNow SecOps connectors.
Hide attributes Show attributes

subAction string Required

The action to test.

Value is getIncident.

subActionParams object Required

Hide subActionParams attribute Show subActionParams attribute object

externalId string Required

The Jira, ServiceNow ITSM, or ServiceNow SecOps issue identifier.
The issue subaction for Jira connectors.
Hide attributes Show attributes

subAction string Required

The action to test.

Value is issue.

subActionParams object

Hide subActionParams attribute Show subActionParams attribute object

id string Required

The Jira issue identifier.
The issues subaction for Jira connectors.
Hide attributes Show attributes

subAction string Required

The action to test.

Value is issues.

subActionParams object Required

Hide subActionParams attribute Show subActionParams attribute object

title string Required

The title of the Jira issue.
The issueTypes subaction for Jira connectors.
Hide attribute Show attribute

subAction string Required

The action to test.

Value is issueTypes.
Test an action that sends a message to Slack. It is applicable only when the connector type is .slack_api.
Hide attributes Show attributes

subAction string Required

The action to test.

Value is postMessage.

subActionParams object Required

The set of configuration properties for the action.

Hide subActionParams attributes Show subActionParams attributes object

channelIds array[string]

The Slack channel identifier, which must be one of the allowedChannels in the connector configuration.

Not more than 1 element.

channels array[string] Deprecated

The name of a channel that your Slack app has access to.

Not more than 1 element.

text string

The Slack message text. If it is a Slack webhook connector, the text cannot contain Markdown, images, or other advanced formatting. If it is a Slack web API connector, it can contain either plain text or block kit messages.

Minimum length is 1.
The pushToService subaction for Jira, ServiceNow ITSM, ServiceNow SecOps, Swimlane, TheHive, and Webhook - Case Management connectors.
Hide attributes Show attributes

subAction string Required

The action to test.

Value is pushToService.

subActionParams object Required

The set of configuration properties for the action.

Hide subActionParams attributes Show subActionParams attributes object

comments array[object]

Additional information that is sent to Jira, ServiceNow ITSM, ServiceNow SecOps, Swimlane, or TheHive.

Hide comments attributes Show comments attributes object

comment string

A comment related to the incident. For example, describe how to troubleshoot the issue.

commentId integer

A unique identifier for the comment.

incident object

Information necessary to create or update a Jira, ServiceNow ITSM, ServiveNow SecOps, Swimlane, or TheHive incident.

Hide incident attributes Show incident attributes object

additional_fields string | null

Additional fields for ServiceNow ITSM and ServiveNow SecOps connectors. The fields must exist in the Elastic ServiceNow application and must be specified in JSON format.

Maximum length is 20.

alertId string

The alert identifier for Swimlane connectors.

caseId string

The case identifier for the incident for Swimlane connectors.

caseName string

The case name for the incident for Swimlane connectors.

category string

The category of the incident for ServiceNow ITSM and ServiceNow SecOps connectors.

correlation_display string

A descriptive label of the alert for correlation purposes for ServiceNow ITSM and ServiceNow SecOps connectors.

correlation_id string

The correlation identifier for the security incident for ServiceNow ITSM and ServiveNow SecOps connectors. Connectors using the same correlation ID are associated with the same ServiceNow incident. This value determines whether a new ServiceNow incident is created or an existing one is updated. Modifying this value is optional; if not modified, the rule ID and alert ID are combined as {{ruleID}}:{{alert ID}} to form the correlation ID value in ServiceNow. The maximum character length for this value is 100 characters. NOTE: Using the default configuration of {{ruleID}}:{{alert ID}} ensures that ServiceNow creates a separate incident record for every generated alert that uses a unique alert ID. If the rule generates multiple alerts that use the same alert IDs, ServiceNow creates and continually updates a single incident record for the alert.

description string

The description of the incident for Jira, ServiceNow ITSM, ServiceNow SecOps, Swimlane, TheHive, and Webhook - Case Management connectors.

dest_ip string | array[string]

A list of destination IP addresses related to the security incident for ServiceNow SecOps connectors. The IPs are added as observables to the security incident.

One of:
string-1 string array-2 array[string]

externalId string

The Jira, ServiceNow ITSM, or ServiceNow SecOps issue identifier. If present, the incident is updated. Otherwise, a new incident is created.

id string

The external case identifier for Webhook - Case Management connectors.

impact string

The impact of the incident for ServiceNow ITSM connectors.

issueType integer

The type of incident for Jira connectors. For example, 10006. To obtain the list of valid values, set subAction to issueTypes.

labels array[string]

The labels for the incident for Jira connectors. NOTE: Labels cannot contain spaces.

malware_hash string | array[string]

A list of malware hashes related to the security incident for ServiceNow SecOps connectors. The hashes are added as observables to the security incident.

One of:
string-1 string array-2 array[string]

malware_url string | array[string]

A list of malware URLs related to the security incident for ServiceNow SecOps connectors. The URLs are added as observables to the security incident.

One of:
string-1 string array-2 array[string]

otherFields object

Custom field identifiers and their values for Jira connectors.

Additional properties are allowed.

parent string

The ID or key of the parent issue for Jira connectors. Applies only to Sub-task types of issues.

priority string

The priority of the incident in Jira and ServiceNow SecOps connectors.

ruleName string

The rule name for Swimlane connectors.

severity integer

The severity of the incident for ServiceNow ITSM, Swimlane, and TheHive connectors. In TheHive connectors, the severity value ranges from 1 (low) to 4 (critical) with a default value of 2 (medium).

short_description string

A short description of the incident for ServiceNow ITSM and ServiceNow SecOps connectors. It is used for searching the contents of the knowledge base.

source_ip string | array[string]

A list of source IP addresses related to the security incident for ServiceNow SecOps connectors. The IPs are added as observables to the security incident.

One of:
string-1 string array-2 array[string]

status string

The status of the incident for Webhook - Case Management connectors.

subcategory string

The subcategory of the incident for ServiceNow ITSM and ServiceNow SecOps connectors.

summary string

A summary of the incident for Jira connectors.

tags array[string]

A list of tags for TheHive and Webhook - Case Management connectors.

title string

A title for the incident for Jira, TheHive, and Webhook - Case Management connectors. It is used for searching the contents of the knowledge base.

tlp integer

The traffic light protocol designation for the incident in TheHive connectors. Valid values include: 0 (clear), 1 (green), 2 (amber), 3 (amber and strict), and 4 (red).

Minimum value is 0, maximum value is 4. Default value is 2.

urgency string

The urgency of the incident for ServiceNow ITSM connectors.
Retrieves information about a valid Slack channel identifier. It is applicable only when the connector type is .slack_api.
Hide attributes Show attributes

subAction string Required

The action to test.

Value is validChannelId.

subActionParams object Required

Hide subActionParams attribute Show subActionParams attribute object

channelId string Required

The Slack channel identifier.

Responses

200 application/json

Indicates a successful call.
Hide response attributes Show response attributes object
- config object
  
  Additional properties are allowed.
- connector_type_id string Required
  
  The connector type identifier.
- id string Required
  
  The identifier for the connector.
- is_deprecated boolean Required
  
  Indicates whether the connector is deprecated.
- is_missing_secrets boolean
  
  Indicates whether the connector is missing secrets.
- is_preconfigured boolean Required
  
  Indicates whether the connector is preconfigured. If true, the config and is_missing_secrets properties are omitted from the response.
- is_system_action boolean Required
  
  Indicates whether the connector is used for system actions.
- name string Required
  
  The name of the rule.

POST /api/actions/connector/{id}/_execute

curl \
 --request POST 'https://<KIBANA_URL>/api/actions/connector/{id}/_execute' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"params":{"documents":[{"id":"my_doc_id","name":"my_doc_name","message":"hello, world"}]}}'

Request examples

{
  "params": {
    "documents": [
      {
        "id": "my_doc_id",
        "name": "my_doc_name",
        "message": "hello, world"
      }
    ]
  }
}

{
  "params": {
    "subAction": "issueTypes"
  }
}

{
  "params": {
    "subAction": "getChoices",
    "subActionParams": {
      "fields": [
        "severity",
        "urgency"
      ]
    }
  }
}

{
  "params": {
    "subAction": "postMessage",
    "subActionParams": {
      "text": "A test message.",
      "channelIds": [
        "C123ABC456"
      ]
    }
  }
}

{
  "params": {
    "subAction": "pushToService",
    "subActionParams": {
      "comments": [
        {
          "comment": "A comment about the incident.",
          "commentId": 1
        }
      ],
      "incident": {
        "caseId": "1000",
        "caseName": "Case name",
        "description": "Description of the incident."
      }
    }
  }
}

Response examples (200)

{
  "data": {
    "took": 135,
    "items": [
      {
        "create": {
          "_id": "4JtvwYUBrcyxt2NnfW3y",
          "_index": "my-index",
          "result": "created",
          "status": 201,
          "_seq_no": 0,
          "_shards": {
            "total": 2,
            "failed": 0,
            "successful": 1
          },
          "_version": 1,
          "_primary_term": 1
        }
      }
    ],
    "errors": false
  },
  "status": "ok",
  "connector_id": "fd38c600-96a5-11ed-bb79-353b74189cba"
}

{
  "data": [
    {
      "id": 10024,
      "name": "Improvement"
    },
    {
      "id": 10006,
      "name": "Task"
    },
    {
      "id": 10007,
      "name": "Sub-task"
    },
    {
      "id": 10025,
      "name": "New Feature"
    },
    {
      "id": 10023,
      "name": "Bug"
    },
    {
      "id": 10000,
      "name": "Epic"
    }
  ],
  "status": "ok",
  "connector_id": "b3aad810-edbe-11ec-82d1-11348ecbf4a6"
}

{
  "status": "ok",
  "connector_id": "7fc7b9a0-ecc9-11ec-8736-e7d63118c907"
}

{
  "data": [
    {
      "label": "Critical",
      "value": 1,
      "element": "severity",
      "dependent_value": ""
    },
    {
      "label": "Major",
      "value": 2,
      "element": "severity",
      "dependent_value": ""
    },
    {
      "label": "Minor",
      "value": 3,
      "element": "severity",
      "dependent_value": ""
    },
    {
      "label": "Warning",
      "value": 4,
      "element": "severity",
      "dependent_value": ""
    },
    {
      "label": "OK",
      "value": 5,
      "element": "severity",
      "dependent_value": ""
    },
    {
      "label": "Clear",
      "value": 0,
      "element": "severity",
      "dependent_value": ""
    },
    {
      "label": "1 - High",
      "value": 1,
      "element": "urgency",
      "dependent_value": ""
    },
    {
      "label": "2 - Medium",
      "value": 2,
      "element": "urgency",
      "dependent_value": ""
    },
    {
      "label": "3 - Low",
      "value": 3,
      "element": "urgency",
      "dependent_value": ""
    }
  ],
  "status": "ok",
  "connector_id": "9d9be270-2fd2-11ed-b0e0-87533c532698"
}

{
  "data": {
    "ok": true,
    "ts": "1234567890.123456",
    "channel": "C123ABC456",
    "message": {
      "ts": "1234567890.123456",
      "team": "T01ABCDE2F",
      "text": "A test message",
      "type": "message",
      "user": "U12A345BC6D",
      "app_id": "A01BC2D34EF",
      "blocks": [
        {
          "type": "rich_text",
          "block_id": "/NXe",
          "elements": [
            {
              "type": "rich_text_section",
              "elements": [
                {
                  "text": "A test message.",
                  "type": "text"
                }
              ]
            }
          ]
        }
      ],
      "bot_id": "B12BCDEFGHI",
      "bot_profile": {
        "id": "B12BCDEFGHI",
        "name": "test",
        "icons": {
          "image_36": "https://a.slack-edge.com/80588/img/plugins/app/bot_36.png"
        },
        "app_id": "A01BC2D34EF",
        "deleted": false,
        "team_id": "T01ABCDE2F",
        "updated": 1672169705
      }
    }
  },
  "status": "ok",
  "connector_id": ".slack_api"
}

{
  "data": {
    "id": "aKPmBHWzmdRQtx6Mx",
    "url": "https://elastic.swimlane.url.us/record/aNcL2xniGHGpa2AHb/aKPmBHWzmdRQtx6Mx",
    "title": "TEST-457",
    "comments": [
      {
        "commentId": 1,
        "pushedDate": "2022-09-08T16:52:27.865Z"
      }
    ],
    "pushedDate": "2022-09-08T16:52:27.866Z"
  },
  "status": "ok",
  "connector_id": "a4746470-2f94-11ed-b0e0-87533c532698"
}

Get all connectors

GET /api/actions/connectors

Responses

200 application/json

Indicates a successful call.

GET /api/actions/connectors

curl \
 --request GET 'https://<KIBANA_URL>/api/actions/connectors' \
 --header "Authorization: $API_KEY"

Response examples (200)

[
  {
    "id": "preconfigured-email-connector",
    "name": "my-preconfigured-email-notification",
    "is_deprecated": false,
    "is_preconfigured": true,
    "is_system_action": false,
    "connector_type_id": ".email",
    "referenced_by_count": 0
  },
  {
    "id": "e07d0c80-8b8b-11ed-a780-3b746c987a81",
    "name": "my-index-connector",
    "config": {
      "index": "test-index",
      "refresh": false,
      "executionTimeField": null
    },
    "is_deprecated": false,
    "is_preconfigured": false,
    "is_system_action": false,
    "connector_type_id": ".index",
    "is_missing_secrets": false,
    "referenced_by_count": 2
  }
]

Get a list of dashboards Technical Preview

GET /api/dashboards/dashboard

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

Query parameters

page number

The page number to return. Default is "1".

Minimum value is 1. Default value is 1.
perPage number

The number of dashboards to display on each page (max 1000). Default is "20".

Minimum value is 1, maximum value is 1000.

Responses

200 application/json
Hide response attributes Show response attributes object
- items array[object] Required
  
  Hide items attributes Show items attributes object
  
  attributes object Required
  
  Additional properties are NOT allowed.
  
  Hide attributes attributes Show attributes attributes object
  
  description string
  
  A short description.
  
  Default value is empty.
  
  tags array[string]
  
  An array of tags applied to this dashboard
  
  timeRestore boolean
  
  Whether to restore time upon viewing this dashboard
  
  Default value is false.
  
  title string Required
  
  A human-readable title for the dashboard
  
  createdAt string
  
  createdBy string
  
  error object
  
  Additional properties are NOT allowed.
  
  Hide error attributes Show error attributes object
  
  error string Required
  
  message string Required
  
  metadata object
  
  Additional properties are allowed.
  
  statusCode number Required
  
  id string Required
  
  managed boolean
  
  namespaces array[string]
  
  originId string
  
  references array[object] Required
  
  Hide references attributes Show references attributes object
  
  id string Required
  
  name string Required
  
  type string Required
  
  type string Required
  
  updatedAt string
  
  updatedBy string
  
  version string
- total number Required

GET /api/dashboards/dashboard

curl \
 --request GET 'https://<KIBANA_URL>/api/dashboards/dashboard' \
 --header "Authorization: $API_KEY"

Get a dashboard Technical Preview

GET /api/dashboards/dashboard/{id}

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

Path parameters

id string Required

A unique identifier for the dashboard.

Responses

200 application/json
Hide response attributes Show response attributes object
- item object Required
  
  Additional properties are allowed.
  
  Hide item attributes Show item attributes object
  
  attributes object Required
  
  Additional properties are NOT allowed.
  
  Hide attributes attributes Show attributes attributes object
  
  controlGroupInput object
  
  Additional properties are NOT allowed.
  
  Hide controlGroupInput attributes Show controlGroupInput attributes object
  
  autoApplySelections boolean
  
  Show apply selections button in controls.
  
  Default value is true.
  
  chainingSystem string
  
  The chaining strategy for multiple controls. For example, "HIERARCHICAL" or "NONE".
  
  Values are NONE or HIERARCHICAL. Default value is HIERARCHICAL.
  
  controls array[object]
  
  An array of control panels and their state in the control group.
  
  Default value is [] (empty).
  
  Hide controls attributes Show controls attributes object
  
  controlConfig object
  
  Additional properties are allowed.
  
  grow boolean
  
  Expand width of the control panel to fit available space.
  
  Default value is false.
  
  id string
  
  The unique ID of the control.
  
  order number Required
  
  The order of the control panel in the control group.
  
  type string Required
  
  The type of the control panel.
  
  width string
  
  Minimum width of the control panel in the control group.
  
  Values are small, medium, or large. Default value is medium.
  
  enhancements object
  
  Additional properties are allowed.
  
  ignoreParentSettings object Required
  
  Additional properties are NOT allowed.
  
  Hide ignoreParentSettings attributes Show ignoreParentSettings attributes object
  
  ignoreFilters boolean
  
  Ignore global filters in controls.
  
  Default value is false.
  
  ignoreQuery boolean
  
  Ignore the global query bar in controls.
  
  Default value is false.
  
  ignoreTimerange boolean
  
  Ignore the global time range in controls.
  
  Default value is false.
  
  ignoreValidations boolean
  
  Ignore validations in controls.
  
  Default value is false.
  
  labelPosition string
  
  Position of the labels for controls. For example, "oneLine", "twoLine".
  
  Values are oneLine or twoLine. Default value is oneLine.
  
  description string
  
  A short description.
  
  Default value is empty.
  
  kibanaSavedObjectMeta object
  
  A container for various metadata
  
  Default value is {} (empty). Additional properties are NOT allowed.
  
  Hide kibanaSavedObjectMeta attribute Show kibanaSavedObjectMeta attribute object
  
  searchSource object
  
  Additional properties are allowed.
  
  Hide searchSource attributes Show searchSource attributes object
  
  filter array[object]
  
  A filter for the search source.
  
  Hide filter attributes Show filter attributes object
  
  $state object
  
  Additional properties are NOT allowed.
  
  Hide $state attribute Show $state attribute object
  
  store string Required
  
  Denote whether a filter is specific to an application's context (e.g. 'appState') or whether it should be applied globally (e.g. 'globalState').
  
  Values are appState or globalState.
  
  meta object Required
  
  Additional properties are allowed.
  
  Hide meta attributes Show meta attributes object
  
  alias string | null
  
  controlledBy string
  
  disabled boolean
  
  field string
  
  group string
  
  index string
  
  isMultiIndex boolean
  
  key string
  
  negate boolean
  
  type string
  
  value string
  
  query object
  
  Additional properties are allowed.
  
  query object
  
  Additional properties are NOT allowed.
  
  Hide query attributes Show query attributes object
  
  language string Required
  
  The query language such as KQL or Lucene.
  
  query string | object Required
  
  Any of:
  string-1 string object-2 object
  
  A text-based query such as Kibana Query Language (KQL) or Lucene query language.
  
  sort array[object]
  
  type string
  
  options object Required
  
  Additional properties are NOT allowed.
  
  Hide options attributes Show options attributes object
  
  hidePanelTitles boolean
  
  Hide the panel titles in the dashboard.
  
  Default value is false.
  
  syncColors boolean
  
  Synchronize colors between related panels in the dashboard.
  
  Default value is true.
  
  syncCursor boolean
  
  Synchronize cursor position between related panels in the dashboard.
  
  Default value is true.
  
  syncTooltips boolean
  
  Synchronize tooltips between related panels in the dashboard.
  
  Default value is true.
  
  useMargins boolean
  
  Show margins between panels in the dashboard layout.
  
  Default value is true.
  
  panels array[object]
  
  Default value is [] (empty).
  
  Hide panels attributes Show panels attributes object
  
  gridData object Required
  
  Additional properties are NOT allowed.
  
  Hide gridData attributes Show gridData attributes object
  
  h number
  
  The height of the panel in grid units
  
  Minimum value is 1. Default value is 15.
  
  i string Required
  
  w number
  
  The width of the panel in grid units
  
  Minimum value is 1, maximum value is 48. Default value is 24.
  
  x number Required
  
  The x coordinate of the panel in grid units
  
  y number Required
  
  The y coordinate of the panel in grid units
  
  id string
  
  The saved object id for by reference panels
  
  panelConfig object Required
  
  Additional properties are allowed.
  
  Hide panelConfig attributes Show panelConfig attributes object
  
  description string
  
  The description of the panel
  
  enhancements object
  
  Additional properties are allowed.
  
  hidePanelTitles boolean
  
  Set to true to hide the panel title in its container.
  
  savedObjectId string
  
  The unique id of the library item to construct the embeddable.
  
  title string
  
  The title of the panel
  
  version string
  
  The version of the embeddable in the panel.
  
  panelIndex string Required
  
  panelRefName string
  
  title string
  
  The title of the panel
  
  type string Required
  
  The embeddable type
  
  version string Deprecated
  
  The version was used to store Kibana version information from versions 7.3.0 -> 8.11.0. As of version 8.11.0, the versioning information is now per-embeddable-type and is stored on the embeddable's input. (panelConfig in this type).
  
  refreshInterval object
  
  A container for various refresh interval settings
  
  Additional properties are NOT allowed.
  
  Hide refreshInterval attributes Show refreshInterval attributes object
  
  display string Deprecated
  
  A human-readable string indicating the refresh frequency. No longer used.
  
  pause boolean Required
  
  Whether the refresh interval is set to be paused while viewing the dashboard.
  
  section number Deprecated
  
  No longer used.
  
  value number Required
  
  A numeric value indicating refresh frequency in milliseconds.
  
  tags array[string]
  
  An array of tags applied to this dashboard
  
  timeFrom string
  
  An ISO string indicating when to restore time from
  
  timeRestore boolean
  
  Whether to restore time upon viewing this dashboard
  
  Default value is false.
  
  timeTo string
  
  An ISO string indicating when to restore time from
  
  title string Required
  
  A human-readable title for the dashboard
  
  version number Deprecated
  
  createdAt string
  
  createdBy string
  
  error object
  
  Additional properties are NOT allowed.
  
  Hide error attributes Show error attributes object
  
  error string Required
  
  message string Required
  
  metadata object
  
  Additional properties are allowed.
  
  statusCode number Required
  
  id string Required
  
  managed boolean
  
  namespaces array[string]
  
  originId string
  
  references array[object] Required
  
  Hide references attributes Show references attributes object
  
  id string Required
  
  name string Required
  
  type string Required
  
  type string Required
  
  updatedAt string
  
  updatedBy string
  
  version string
- meta object Required
  
  Additional properties are NOT allowed.
  
  Hide meta attributes Show meta attributes object
  
  aliasPurpose string
  
  Values are savedObjectConversion or savedObjectImport.
  
  aliasTargetId string
  
  outcome string Required
  
  Values are exactMatch, aliasMatch, or conflict.

GET /api/dashboards/dashboard/{id}

curl \
 --request GET 'https://<KIBANA_URL>/api/dashboards/dashboard/{id}' \
 --header "Authorization: $API_KEY"

Update an existing dashboard Technical Preview

PUT /api/dashboards/dashboard/{id}

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

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

Path parameters

id string Required

A unique identifier for the dashboard.

application/json

Body

attributes object Required

Additional properties are NOT allowed.
Hide attributes attributes Show attributes attributes object
- controlGroupInput object
  
  Additional properties are NOT allowed.
  Hide controlGroupInput attributes Show controlGroupInput attributes object
  
  autoApplySelections boolean
  
  Show apply selections button in controls.
  
  Default value is true.
  
  chainingSystem string
  
  The chaining strategy for multiple controls. For example, "HIERARCHICAL" or "NONE".
  
  Values are NONE or HIERARCHICAL. Default value is HIERARCHICAL.
  
  controls array[object]
  
  An array of control panels and their state in the control group.
  
  Default value is [] (empty).
  
  Hide controls attributes Show controls attributes object
  
  controlConfig object
  
  Additional properties are allowed.
  
  grow boolean
  
  Expand width of the control panel to fit available space.
  
  Default value is false.
  
  id string
  
  The unique ID of the control.
  
  order number Required
  
  The order of the control panel in the control group.
  
  type string Required
  
  The type of the control panel.
  
  width string
  
  Minimum width of the control panel in the control group.
  
  Values are small, medium, or large. Default value is medium.
  
  enhancements object
  
  Additional properties are allowed.
  
  ignoreParentSettings object Required
  
  Additional properties are NOT allowed.
  
  Hide ignoreParentSettings attributes Show ignoreParentSettings attributes object
  
  ignoreFilters boolean
  
  Ignore global filters in controls.
  
  Default value is false.
  
  ignoreQuery boolean
  
  Ignore the global query bar in controls.
  
  Default value is false.
  
  ignoreTimerange boolean
  
  Ignore the global time range in controls.
  
  Default value is false.
  
  ignoreValidations boolean
  
  Ignore validations in controls.
  
  Default value is false.
  
  labelPosition string
  
  Position of the labels for controls. For example, "oneLine", "twoLine".
  
  Values are oneLine or twoLine. Default value is oneLine.
- description string
  
  A short description.
  
  Default value is empty.
- kibanaSavedObjectMeta object
  
  A container for various metadata
  
  Default value is {} (empty). Additional properties are NOT allowed.
  Hide kibanaSavedObjectMeta attribute Show kibanaSavedObjectMeta attribute object
  
  searchSource object
  
  Additional properties are allowed.
  
  Hide searchSource attributes Show searchSource attributes object
  
  filter array[object]
  
  A filter for the search source.
  
  Hide filter attributes Show filter attributes object
  
  $state object
  
  Additional properties are NOT allowed.
  
  Hide $state attribute Show $state attribute object
  
  store string Required
  
  Denote whether a filter is specific to an application's context (e.g. 'appState') or whether it should be applied globally (e.g. 'globalState').
  
  Values are appState or globalState.
  
  meta object Required
  
  Additional properties are allowed.
  
  Hide meta attributes Show meta attributes object
  
  alias string | null
  
  controlledBy string
  
  disabled boolean
  
  field string
  
  group string
  
  index string
  
  isMultiIndex boolean
  
  key string
  
  negate boolean
  
  type string
  
  value string
  
  query object
  
  Additional properties are allowed.
  
  query object
  
  Additional properties are NOT allowed.
  
  Hide query attributes Show query attributes object
  
  language string Required
  
  The query language such as KQL or Lucene.
  
  query string | object Required
  
  Any of:
  string-1 string object-2 object
  
  A text-based query such as Kibana Query Language (KQL) or Lucene query language.
  
  sort array[object]
  
  type string
- options object Required
  
  Additional properties are NOT allowed.
  Hide options attributes Show options attributes object
  
  hidePanelTitles boolean
  
  Hide the panel titles in the dashboard.
  
  Default value is false.
  
  syncColors boolean
  
  Synchronize colors between related panels in the dashboard.
  
  Default value is true.
  
  syncCursor boolean
  
  Synchronize cursor position between related panels in the dashboard.
  
  Default value is true.
  
  syncTooltips boolean
  
  Synchronize tooltips between related panels in the dashboard.
  
  Default value is true.
  
  useMargins boolean
  
  Show margins between panels in the dashboard layout.
  
  Default value is true.
- panels array[object]
  
  Default value is [] (empty).
  Hide panels attributes Show panels attributes object
  
  gridData object Required
  
  Additional properties are NOT allowed.
  
  Hide gridData attributes Show gridData attributes object
  
  h number
  
  The height of the panel in grid units
  
  Minimum value is 1. Default value is 15.
  
  i string
  
  The unique identifier of the panel
  
  w number
  
  The width of the panel in grid units
  
  Minimum value is 1, maximum value is 48. Default value is 24.
  
  x number Required
  
  The x coordinate of the panel in grid units
  
  y number Required
  
  The y coordinate of the panel in grid units
  
  id string
  
  The saved object id for by reference panels
  
  panelConfig object Required
  
  Additional properties are allowed.
  
  Hide panelConfig attributes Show panelConfig attributes object
  
  description string
  
  The description of the panel
  
  enhancements object
  
  Additional properties are allowed.
  
  hidePanelTitles boolean
  
  Set to true to hide the panel title in its container.
  
  savedObjectId string
  
  The unique id of the library item to construct the embeddable.
  
  title string
  
  The title of the panel
  
  version string
  
  The version of the embeddable in the panel.
  
  panelIndex string
  
  The unique ID of the panel.
  
  panelRefName string
  
  title string
  
  The title of the panel
  
  type string Required
  
  The embeddable type
  
  version string Deprecated
  
  The version was used to store Kibana version information from versions 7.3.0 -> 8.11.0. As of version 8.11.0, the versioning information is now per-embeddable-type and is stored on the embeddable's input. (panelConfig in this type).
- refreshInterval object
  
  A container for various refresh interval settings
  
  Additional properties are NOT allowed.
  Hide refreshInterval attributes Show refreshInterval attributes object
  
  display string Deprecated
  
  A human-readable string indicating the refresh frequency. No longer used.
  
  pause boolean Required
  
  Whether the refresh interval is set to be paused while viewing the dashboard.
  
  section number Deprecated
  
  No longer used.
  
  value number Required
  
  A numeric value indicating refresh frequency in milliseconds.
- tags array[string]
  
  An array of tags applied to this dashboard
- timeFrom string
  
  An ISO string indicating when to restore time from
- timeRestore boolean
  
  Whether to restore time upon viewing this dashboard
  
  Default value is false.
- timeTo string
  
  An ISO string indicating when to restore time from
- title string Required
  
  A human-readable title for the dashboard
- version number Deprecated
references array[object]
Hide references attributes Show references attributes object
- id string Required
- name string Required
- type string Required

Responses

200 application/json
Hide response attribute Show response attribute object
- item object Required
  
  Additional properties are allowed.
  
  Hide item attributes Show item attributes object
  
  attributes object Required
  
  Additional properties are NOT allowed.
  
  Hide attributes attributes Show attributes attributes object
  
  controlGroupInput object
  
  Additional properties are NOT allowed.
  
  Hide controlGroupInput attributes Show controlGroupInput attributes object
  
  autoApplySelections boolean
  
  Show apply selections button in controls.
  
  Default value is true.
  
  chainingSystem string
  
  The chaining strategy for multiple controls. For example, "HIERARCHICAL" or "NONE".
  
  Values are NONE or HIERARCHICAL. Default value is HIERARCHICAL.
  
  controls array[object]
  
  An array of control panels and their state in the control group.
  
  Default value is [] (empty).
  
  Hide controls attributes Show controls attributes object
  
  controlConfig object
  
  Additional properties are allowed.
  
  grow boolean
  
  Expand width of the control panel to fit available space.
  
  Default value is false.
  
  id string
  
  The unique ID of the control.
  
  order number Required
  
  The order of the control panel in the control group.
  
  type string Required
  
  The type of the control panel.
  
  width string
  
  Minimum width of the control panel in the control group.
  
  Values are small, medium, or large. Default value is medium.
  
  enhancements object
  
  Additional properties are allowed.
  
  ignoreParentSettings object Required
  
  Additional properties are NOT allowed.
  
  Hide ignoreParentSettings attributes Show ignoreParentSettings attributes object
  
  ignoreFilters boolean
  
  Ignore global filters in controls.
  
  Default value is false.
  
  ignoreQuery boolean
  
  Ignore the global query bar in controls.
  
  Default value is false.
  
  ignoreTimerange boolean
  
  Ignore the global time range in controls.
  
  Default value is false.
  
  ignoreValidations boolean
  
  Ignore validations in controls.
  
  Default value is false.
  
  labelPosition string
  
  Position of the labels for controls. For example, "oneLine", "twoLine".
  
  Values are oneLine or twoLine. Default value is oneLine.
  
  description string
  
  A short description.
  
  Default value is empty.
  
  kibanaSavedObjectMeta object
  
  A container for various metadata
  
  Default value is {} (empty). Additional properties are NOT allowed.
  
  Hide kibanaSavedObjectMeta attribute Show kibanaSavedObjectMeta attribute object
  
  searchSource object
  
  Additional properties are allowed.
  
  Hide searchSource attributes Show searchSource attributes object
  
  filter array[object]
  
  A filter for the search source.
  
  Hide filter attributes Show filter attributes object
  
  $state object
  
  Additional properties are NOT allowed.
  
  Hide $state attribute Show $state attribute object
  
  store string Required
  
  Denote whether a filter is specific to an application's context (e.g. 'appState') or whether it should be applied globally (e.g. 'globalState').
  
  Values are appState or globalState.
  
  meta object Required
  
  Additional properties are allowed.
  
  Hide meta attributes Show meta attributes object
  
  alias string | null
  
  controlledBy string
  
  disabled boolean
  
  field string
  
  group string
  
  index string
  
  isMultiIndex boolean
  
  key string
  
  negate boolean
  
  type string
  
  value string
  
  query object
  
  Additional properties are allowed.
  
  query object
  
  Additional properties are NOT allowed.
  
  Hide query attributes Show query attributes object
  
  language string Required
  
  The query language such as KQL or Lucene.
  
  query string | object Required
  
  Any of:
  string-1 string object-2 object
  
  A text-based query such as Kibana Query Language (KQL) or Lucene query language.
  
  sort array[object]
  
  type string
  
  options object Required
  
  Additional properties are NOT allowed.
  
  Hide options attributes Show options attributes object
  
  hidePanelTitles boolean
  
  Hide the panel titles in the dashboard.
  
  Default value is false.
  
  syncColors boolean
  
  Synchronize colors between related panels in the dashboard.
  
  Default value is true.
  
  syncCursor boolean
  
  Synchronize cursor position between related panels in the dashboard.
  
  Default value is true.
  
  syncTooltips boolean
  
  Synchronize tooltips between related panels in the dashboard.
  
  Default value is true.
  
  useMargins boolean
  
  Show margins between panels in the dashboard layout.
  
  Default value is true.
  
  panels array[object]
  
  Default value is [] (empty).
  
  Hide panels attributes Show panels attributes object
  
  gridData object Required
  
  Additional properties are NOT allowed.
  
  Hide gridData attributes Show gridData attributes object
  
  h number
  
  The height of the panel in grid units
  
  Minimum value is 1. Default value is 15.
  
  i string Required
  
  w number
  
  The width of the panel in grid units
  
  Minimum value is 1, maximum value is 48. Default value is 24.
  
  x number Required
  
  The x coordinate of the panel in grid units
  
  y number Required
  
  The y coordinate of the panel in grid units
  
  id string
  
  The saved object id for by reference panels
  
  panelConfig object Required
  
  Additional properties are allowed.
  
  Hide panelConfig attributes Show panelConfig attributes object
  
  description string
  
  The description of the panel
  
  enhancements object
  
  Additional properties are allowed.
  
  hidePanelTitles boolean
  
  Set to true to hide the panel title in its container.
  
  savedObjectId string
  
  The unique id of the library item to construct the embeddable.
  
  title string
  
  The title of the panel
  
  version string
  
  The version of the embeddable in the panel.
  
  panelIndex string Required
  
  panelRefName string
  
  title string
  
  The title of the panel
  
  type string Required
  
  The embeddable type
  
  version string Deprecated
  
  The version was used to store Kibana version information from versions 7.3.0 -> 8.11.0. As of version 8.11.0, the versioning information is now per-embeddable-type and is stored on the embeddable's input. (panelConfig in this type).
  
  refreshInterval object
  
  A container for various refresh interval settings
  
  Additional properties are NOT allowed.
  
  Hide refreshInterval attributes Show refreshInterval attributes object
  
  display string Deprecated
  
  A human-readable string indicating the refresh frequency. No longer used.
  
  pause boolean Required
  
  Whether the refresh interval is set to be paused while viewing the dashboard.
  
  section number Deprecated
  
  No longer used.
  
  value number Required
  
  A numeric value indicating refresh frequency in milliseconds.
  
  tags array[string]
  
  An array of tags applied to this dashboard
  
  timeFrom string
  
  An ISO string indicating when to restore time from
  
  timeRestore boolean
  
  Whether to restore time upon viewing this dashboard
  
  Default value is false.
  
  timeTo string
  
  An ISO string indicating when to restore time from
  
  title string Required
  
  A human-readable title for the dashboard
  
  version number Deprecated
  
  createdAt string
  
  createdBy string
  
  error object
  
  Additional properties are NOT allowed.
  
  Hide error attributes Show error attributes object
  
  error string Required
  
  message string Required
  
  metadata object
  
  Additional properties are allowed.
  
  statusCode number Required
  
  id string Required
  
  managed boolean
  
  namespaces array[string]
  
  originId string
  
  references array[object] Required
  
  Hide references attributes Show references attributes object
  
  id string Required
  
  name string Required
  
  type string Required
  
  type string Required
  
  updatedAt string
  
  updatedBy string
  
  version string

PUT /api/dashboards/dashboard/{id}

curl \
 --request PUT 'https://<KIBANA_URL>/api/dashboards/dashboard/{id}' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"attributes":{"controlGroupInput":{"autoApplySelections":true,"chainingSystem":"HIERARCHICAL","controls":[{"controlConfig":{},"grow":false,"id":"string","order":42.0,"type":"string","width":"medium"}],"enhancements":{},"ignoreParentSettings":{"ignoreFilters":false,"ignoreQuery":false,"ignoreTimerange":false,"ignoreValidations":false},"labelPosition":"oneLine"},"description":"","kibanaSavedObjectMeta":{"searchSource":{"filter":[{"$state":{"store":"appState"},"meta":{"alias":"string","controlledBy":"string","disabled":true,"field":"string","group":"string","index":"string","isMultiIndex":true,"key":"string","negate":true,"type":"string","value":"string"},"query":{}}],"query":{"language":"string","query":"string"},"sort":[{}],"type":"string"}},"options":{"hidePanelTitles":false,"syncColors":true,"syncCursor":true,"syncTooltips":true,"useMargins":true},"panels":[{"gridData":{"h":15,"i":"string","w":24,"x":42.0,"y":42.0},"id":"string","panelConfig":{"description":"string","enhancements":{},"hidePanelTitles":true,"savedObjectId":"string","title":"string","version":"string"},"panelIndex":"string","panelRefName":"string","title":"string","type":"string","version":"string"}],"refreshInterval":{"display":"string","pause":true,"section":42.0,"value":42.0},"tags":["string"],"timeFrom":"string","timeRestore":false,"timeTo":"string","title":"string","version":42.0},"references":[{"id":"string","name":"string","type":"string"}]}'

Create a dashboard Technical Preview

POST /api/dashboards/dashboard/{id}

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

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

Path parameters

id string

A unique identifier for the dashboard.

application/json

Body

attributes object Required

Additional properties are NOT allowed.
Hide attributes attributes Show attributes attributes object
- controlGroupInput object
  
  Additional properties are NOT allowed.
  Hide controlGroupInput attributes Show controlGroupInput attributes object
  
  autoApplySelections boolean
  
  Show apply selections button in controls.
  
  Default value is true.
  
  chainingSystem string
  
  The chaining strategy for multiple controls. For example, "HIERARCHICAL" or "NONE".
  
  Values are NONE or HIERARCHICAL. Default value is HIERARCHICAL.
  
  controls array[object]
  
  An array of control panels and their state in the control group.
  
  Default value is [] (empty).
  
  Hide controls attributes Show controls attributes object
  
  controlConfig object
  
  Additional properties are allowed.
  
  grow boolean
  
  Expand width of the control panel to fit available space.
  
  Default value is false.
  
  id string
  
  The unique ID of the control.
  
  order number Required
  
  The order of the control panel in the control group.
  
  type string Required
  
  The type of the control panel.
  
  width string
  
  Minimum width of the control panel in the control group.
  
  Values are small, medium, or large. Default value is medium.
  
  enhancements object
  
  Additional properties are allowed.
  
  ignoreParentSettings object Required
  
  Additional properties are NOT allowed.
  
  Hide ignoreParentSettings attributes Show ignoreParentSettings attributes object
  
  ignoreFilters boolean
  
  Ignore global filters in controls.
  
  Default value is false.
  
  ignoreQuery boolean
  
  Ignore the global query bar in controls.
  
  Default value is false.
  
  ignoreTimerange boolean
  
  Ignore the global time range in controls.
  
  Default value is false.
  
  ignoreValidations boolean
  
  Ignore validations in controls.
  
  Default value is false.
  
  labelPosition string
  
  Position of the labels for controls. For example, "oneLine", "twoLine".
  
  Values are oneLine or twoLine. Default value is oneLine.
- description string
  
  A short description.
  
  Default value is empty.
- kibanaSavedObjectMeta object
  
  A container for various metadata
  
  Default value is {} (empty). Additional properties are NOT allowed.
  Hide kibanaSavedObjectMeta attribute Show kibanaSavedObjectMeta attribute object
  
  searchSource object
  
  Additional properties are allowed.
  
  Hide searchSource attributes Show searchSource attributes object
  
  filter array[object]
  
  A filter for the search source.
  
  Hide filter attributes Show filter attributes object
  
  $state object
  
  Additional properties are NOT allowed.
  
  Hide $state attribute Show $state attribute object
  
  store string Required
  
  Denote whether a filter is specific to an application's context (e.g. 'appState') or whether it should be applied globally (e.g. 'globalState').
  
  Values are appState or globalState.
  
  meta object Required
  
  Additional properties are allowed.
  
  Hide meta attributes Show meta attributes object
  
  alias string | null
  
  controlledBy string
  
  disabled boolean
  
  field string
  
  group string
  
  index string
  
  isMultiIndex boolean
  
  key string
  
  negate boolean
  
  type string
  
  value string
  
  query object
  
  Additional properties are allowed.
  
  query object
  
  Additional properties are NOT allowed.
  
  Hide query attributes Show query attributes object
  
  language string Required
  
  The query language such as KQL or Lucene.
  
  query string | object Required
  
  Any of:
  string-1 string object-2 object
  
  A text-based query such as Kibana Query Language (KQL) or Lucene query language.
  
  sort array[object]
  
  type string
- options object Required
  
  Additional properties are NOT allowed.
  Hide options attributes Show options attributes object
  
  hidePanelTitles boolean
  
  Hide the panel titles in the dashboard.
  
  Default value is false.
  
  syncColors boolean
  
  Synchronize colors between related panels in the dashboard.
  
  Default value is true.
  
  syncCursor boolean
  
  Synchronize cursor position between related panels in the dashboard.
  
  Default value is true.
  
  syncTooltips boolean
  
  Synchronize tooltips between related panels in the dashboard.
  
  Default value is true.
  
  useMargins boolean
  
  Show margins between panels in the dashboard layout.
  
  Default value is true.
- panels array[object]
  
  Default value is [] (empty).
  Hide panels attributes Show panels attributes object
  
  gridData object Required
  
  Additional properties are NOT allowed.
  
  Hide gridData attributes Show gridData attributes object
  
  h number
  
  The height of the panel in grid units
  
  Minimum value is 1. Default value is 15.
  
  i string
  
  The unique identifier of the panel
  
  w number
  
  The width of the panel in grid units
  
  Minimum value is 1, maximum value is 48. Default value is 24.
  
  x number Required
  
  The x coordinate of the panel in grid units
  
  y number Required
  
  The y coordinate of the panel in grid units
  
  id string
  
  The saved object id for by reference panels
  
  panelConfig object Required
  
  Additional properties are allowed.
  
  Hide panelConfig attributes Show panelConfig attributes object
  
  description string
  
  The description of the panel
  
  enhancements object
  
  Additional properties are allowed.
  
  hidePanelTitles boolean
  
  Set to true to hide the panel title in its container.
  
  savedObjectId string
  
  The unique id of the library item to construct the embeddable.
  
  title string
  
  The title of the panel
  
  version string
  
  The version of the embeddable in the panel.
  
  panelIndex string
  
  The unique ID of the panel.
  
  panelRefName string
  
  title string
  
  The title of the panel
  
  type string Required
  
  The embeddable type
  
  version string Deprecated
  
  The version was used to store Kibana version information from versions 7.3.0 -> 8.11.0. As of version 8.11.0, the versioning information is now per-embeddable-type and is stored on the embeddable's input. (panelConfig in this type).
- refreshInterval object
  
  A container for various refresh interval settings
  
  Additional properties are NOT allowed.
  Hide refreshInterval attributes Show refreshInterval attributes object
  
  display string Deprecated
  
  A human-readable string indicating the refresh frequency. No longer used.
  
  pause boolean Required
  
  Whether the refresh interval is set to be paused while viewing the dashboard.
  
  section number Deprecated
  
  No longer used.
  
  value number Required
  
  A numeric value indicating refresh frequency in milliseconds.
- tags array[string]
  
  An array of tags applied to this dashboard
- timeFrom string
  
  An ISO string indicating when to restore time from
- timeRestore boolean
  
  Whether to restore time upon viewing this dashboard
  
  Default value is false.
- timeTo string
  
  An ISO string indicating when to restore time from
- title string Required
  
  A human-readable title for the dashboard
- version number Deprecated
references array[object]
Hide references attributes Show references attributes object
- id string Required
- name string Required
- type string Required
spaces array[string]

Responses

200 application/json
Hide response attribute Show response attribute object
- item object Required
  
  Additional properties are allowed.
  
  Hide item attributes Show item attributes object
  
  attributes object Required
  
  Additional properties are NOT allowed.
  
  Hide attributes attributes Show attributes attributes object
  
  controlGroupInput object
  
  Additional properties are NOT allowed.
  
  Hide controlGroupInput attributes Show controlGroupInput attributes object
  
  autoApplySelections boolean
  
  Show apply selections button in controls.
  
  Default value is true.
  
  chainingSystem string
  
  The chaining strategy for multiple controls. For example, "HIERARCHICAL" or "NONE".
  
  Values are NONE or HIERARCHICAL. Default value is HIERARCHICAL.
  
  controls array[object]
  
  An array of control panels and their state in the control group.
  
  Default value is [] (empty).
  
  Hide controls attributes Show controls attributes object
  
  controlConfig object
  
  Additional properties are allowed.
  
  grow boolean
  
  Expand width of the control panel to fit available space.
  
  Default value is false.
  
  id string
  
  The unique ID of the control.
  
  order number Required
  
  The order of the control panel in the control group.
  
  type string Required
  
  The type of the control panel.
  
  width string
  
  Minimum width of the control panel in the control group.
  
  Values are small, medium, or large. Default value is medium.
  
  enhancements object
  
  Additional properties are allowed.
  
  ignoreParentSettings object Required
  
  Additional properties are NOT allowed.
  
  Hide ignoreParentSettings attributes Show ignoreParentSettings attributes object
  
  ignoreFilters boolean
  
  Ignore global filters in controls.
  
  Default value is false.
  
  ignoreQuery boolean
  
  Ignore the global query bar in controls.
  
  Default value is false.
  
  ignoreTimerange boolean
  
  Ignore the global time range in controls.
  
  Default value is false.
  
  ignoreValidations boolean
  
  Ignore validations in controls.
  
  Default value is false.
  
  labelPosition string
  
  Position of the labels for controls. For example, "oneLine", "twoLine".
  
  Values are oneLine or twoLine. Default value is oneLine.
  
  description string
  
  A short description.
  
  Default value is empty.
  
  kibanaSavedObjectMeta object
  
  A container for various metadata
  
  Default value is {} (empty). Additional properties are NOT allowed.
  
  Hide kibanaSavedObjectMeta attribute Show kibanaSavedObjectMeta attribute object
  
  searchSource object
  
  Additional properties are allowed.
  
  Hide searchSource attributes Show searchSource attributes object
  
  filter array[object]
  
  A filter for the search source.
  
  Hide filter attributes Show filter attributes object
  
  $state object
  
  Additional properties are NOT allowed.
  
  Hide $state attribute Show $state attribute object
  
  store string Required
  
  Denote whether a filter is specific to an application's context (e.g. 'appState') or whether it should be applied globally (e.g. 'globalState').
  
  Values are appState or globalState.
  
  meta object Required
  
  Additional properties are allowed.
  
  Hide meta attributes Show meta attributes object
  
  alias string | null
  
  controlledBy string
  
  disabled boolean
  
  field string
  
  group string
  
  index string
  
  isMultiIndex boolean
  
  key string
  
  negate boolean
  
  type string
  
  value string
  
  query object
  
  Additional properties are allowed.
  
  query object
  
  Additional properties are NOT allowed.
  
  Hide query attributes Show query attributes object
  
  language string Required
  
  The query language such as KQL or Lucene.
  
  query string | object Required
  
  Any of:
  string-1 string object-2 object
  
  A text-based query such as Kibana Query Language (KQL) or Lucene query language.
  
  sort array[object]
  
  type string
  
  options object Required
  
  Additional properties are NOT allowed.
  
  Hide options attributes Show options attributes object
  
  hidePanelTitles boolean
  
  Hide the panel titles in the dashboard.
  
  Default value is false.
  
  syncColors boolean
  
  Synchronize colors between related panels in the dashboard.
  
  Default value is true.
  
  syncCursor boolean
  
  Synchronize cursor position between related panels in the dashboard.
  
  Default value is true.
  
  syncTooltips boolean
  
  Synchronize tooltips between related panels in the dashboard.
  
  Default value is true.
  
  useMargins boolean
  
  Show margins between panels in the dashboard layout.
  
  Default value is true.
  
  panels array[object]
  
  Default value is [] (empty).
  
  Hide panels attributes Show panels attributes object
  
  gridData object Required
  
  Additional properties are NOT allowed.
  
  Hide gridData attributes Show gridData attributes object
  
  h number
  
  The height of the panel in grid units
  
  Minimum value is 1. Default value is 15.
  
  i string Required
  
  w number
  
  The width of the panel in grid units
  
  Minimum value is 1, maximum value is 48. Default value is 24.
  
  x number Required
  
  The x coordinate of the panel in grid units
  
  y number Required
  
  The y coordinate of the panel in grid units
  
  id string
  
  The saved object id for by reference panels
  
  panelConfig object Required
  
  Additional properties are allowed.
  
  Hide panelConfig attributes Show panelConfig attributes object
  
  description string
  
  The description of the panel
  
  enhancements object
  
  Additional properties are allowed.
  
  hidePanelTitles boolean
  
  Set to true to hide the panel title in its container.
  
  savedObjectId string
  
  The unique id of the library item to construct the embeddable.
  
  title string
  
  The title of the panel
  
  version string
  
  The version of the embeddable in the panel.
  
  panelIndex string Required
  
  panelRefName string
  
  title string
  
  The title of the panel
  
  type string Required
  
  The embeddable type
  
  version string Deprecated
  
  The version was used to store Kibana version information from versions 7.3.0 -> 8.11.0. As of version 8.11.0, the versioning information is now per-embeddable-type and is stored on the embeddable's input. (panelConfig in this type).
  
  refreshInterval object
  
  A container for various refresh interval settings
  
  Additional properties are NOT allowed.
  
  Hide refreshInterval attributes Show refreshInterval attributes object
  
  display string Deprecated
  
  A human-readable string indicating the refresh frequency. No longer used.
  
  pause boolean Required
  
  Whether the refresh interval is set to be paused while viewing the dashboard.
  
  section number Deprecated
  
  No longer used.
  
  value number Required
  
  A numeric value indicating refresh frequency in milliseconds.
  
  tags array[string]
  
  An array of tags applied to this dashboard
  
  timeFrom string
  
  An ISO string indicating when to restore time from
  
  timeRestore boolean
  
  Whether to restore time upon viewing this dashboard
  
  Default value is false.
  
  timeTo string
  
  An ISO string indicating when to restore time from
  
  title string Required
  
  A human-readable title for the dashboard
  
  version number Deprecated
  
  createdAt string
  
  createdBy string
  
  error object
  
  Additional properties are NOT allowed.
  
  Hide error attributes Show error attributes object
  
  error string Required
  
  message string Required
  
  metadata object
  
  Additional properties are allowed.
  
  statusCode number Required
  
  id string Required
  
  managed boolean
  
  namespaces array[string]
  
  originId string
  
  references array[object] Required
  
  Hide references attributes Show references attributes object
  
  id string Required
  
  name string Required
  
  type string Required
  
  type string Required
  
  updatedAt string
  
  updatedBy string
  
  version string

POST /api/dashboards/dashboard/{id}

curl \
 --request POST 'https://<KIBANA_URL>/api/dashboards/dashboard/{id}' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"attributes":{"controlGroupInput":{"autoApplySelections":true,"chainingSystem":"HIERARCHICAL","controls":[{"controlConfig":{},"grow":false,"id":"string","order":42.0,"type":"string","width":"medium"}],"enhancements":{},"ignoreParentSettings":{"ignoreFilters":false,"ignoreQuery":false,"ignoreTimerange":false,"ignoreValidations":false},"labelPosition":"oneLine"},"description":"","kibanaSavedObjectMeta":{"searchSource":{"filter":[{"$state":{"store":"appState"},"meta":{"alias":"string","controlledBy":"string","disabled":true,"field":"string","group":"string","index":"string","isMultiIndex":true,"key":"string","negate":true,"type":"string","value":"string"},"query":{}}],"query":{"language":"string","query":"string"},"sort":[{}],"type":"string"}},"options":{"hidePanelTitles":false,"syncColors":true,"syncCursor":true,"syncTooltips":true,"useMargins":true},"panels":[{"gridData":{"h":15,"i":"string","w":24,"x":42.0,"y":42.0},"id":"string","panelConfig":{"description":"string","enhancements":{},"hidePanelTitles":true,"savedObjectId":"string","title":"string","version":"string"},"panelIndex":"string","panelRefName":"string","title":"string","type":"string","version":"string"}],"refreshInterval":{"display":"string","pause":true,"section":42.0,"value":42.0},"tags":["string"],"timeFrom":"string","timeRestore":false,"timeTo":"string","title":"string","version":42.0},"references":[{"id":"string","name":"string","type":"string"}],"spaces":["string"]}'

Delete a dashboard Technical Preview

DELETE /api/dashboards/dashboard/{id}

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

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

Path parameters

id string Required

A unique identifier for the dashboard.

DELETE /api/dashboards/dashboard/{id}

curl \
 --request DELETE 'https://<KIBANA_URL>/api/dashboards/dashboard/{id}' \
 --header "Authorization: $API_KEY" \
 --header "kbn-xsrf: true"

Get data streams

GET /api/fleet/data_streams

[Required authorization] Route required privileges: fleet-agents-all AND fleet-agent-policies-all AND fleet-settings-all.

Responses

200 application/json
Hide response attribute Show response attribute object
- data_streams array[object] Required
  
  Hide data_streams attributes Show data_streams attributes object
  
  dashboards array[object] Required
  
  Hide dashboards attributes Show dashboards attributes object
  
  id string Required
  
  title string Required
  
  dataset string Required
  
  index string Required
  
  last_activity_ms number Required
  
  namespace string Required
  
  package string Required
  
  package_version string Required
  
  serviceDetails object | null Required
  
  Additional properties are NOT allowed.
  
  Hide serviceDetails attributes Show serviceDetails attributes object | null
  
  environment string Required
  
  serviceName string Required
  
  size_in_bytes number Required
  
  size_in_bytes_formatted number | string Required
  
  Any of:
  number-1 number string-2 string
  
  type string Required
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

GET /api/fleet/data_streams

curl \
 --request GET 'https://<KIBANA_URL>/api/fleet/data_streams' \
 --header "Authorization: $API_KEY"

Get data streams

GET /api/fleet/epm/data_streams

[Required authorization] Route required privileges: integrations-read OR fleet-setup OR fleet-all.

Query parameters

type string

Values are logs, metrics, traces, synthetics, or profiling.
datasetQuery string
sortOrder string

Values are asc or desc. Default value is asc.
uncategorisedOnly boolean

Default value is false.

Responses

200 application/json
Hide response attribute Show response attribute object
- items array[object] Required
  
  Hide items attribute Show items attribute object
  
  name string Required
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

GET /api/fleet/epm/data_streams

curl \
 --request GET 'https://<KIBANA_URL>/api/fleet/epm/data_streams' \
 --header "Authorization: $API_KEY"

Get all data views

GET /api/data_views

Responses

200 application/json

Indicates a successful call.
Hide response attribute Show response attribute object
- data_view array[object]
  
  Hide data_view attributes Show data_view attributes object
  
  id string
  
  name string
  
  namespaces array[string]
  
  title string
  
  typeMeta object
400 application/json

Bad request
Hide response attributes Show response attributes object
- error string Required
- message string Required
- statusCode number Required

GET /api/data_views

curl \
 --request GET 'https://<KIBANA_URL>/api/data_views' \
 --header "Authorization: $API_KEY"

Response examples (200)

{
  "data_view": [
    {
      "id": "ff959d40-b880-11e8-a6d9-e546fe2bba5f",
      "name": "Kibana Sample Data eCommerce",
      "title": "kibana_sample_data_ecommerce",
      "typeMeta": {},
      "namespaces": [
        "default"
      ]
    },
    {
      "id": "d3d7af60-4c81-11e8-b3d7-01146121b73d",
      "name": "Kibana Sample Data Flights",
      "title": "kibana_sample_data_flights",
      "namespaces": [
        "default"
      ]
    },
    {
      "id": "90943e30-9a47-11e8-b64d-95841ca0b247",
      "name": "Kibana Sample Data Logs",
      "title": "kibana_sample_data_logs",
      "namespaces": [
        "default"
      ]
    }
  ]
}

Create a data view

POST /api/data_views/data_view

Headers

kbn-xsrf string Required

Cross-site request forgery protection

application/json

Body Required

data_view object Required

The data view object.
Hide data_view attributes Show data_view attributes object
- allowNoIndex boolean
  
  Allows the data view saved object to exist before the data is available.
- fieldAttrs object
  Hide fieldAttrs attribute Show fieldAttrs attribute object
  
  * object Additional properties
  
  A map of field attributes by field name.
  
  Hide * attributes Show * attributes object
  
  count integer
  
  Popularity count for the field.
  
  customDescription string
  
  Custom description for the field.
  
  Maximum length is 300.
  
  customLabel string
  
  Custom label for the field.
- fieldFormats object
  
  A map of field formats by field name.
- fields object
- id string
- name string
  
  The data view name.
- namespaces array[string]
  
  An array of space identifiers for sharing the data view between multiple spaces.
  
  Default value is default.
- runtimeFieldMap object
  Hide runtimeFieldMap attribute Show runtimeFieldMap attribute object
  
  * object Additional properties
  
  A map of runtime field definitions by field name.
  
  Hide * attributes Show * attributes object
  
  script object Required
  
  Hide script attribute Show script attribute object
  
  source string
  
  Script for the runtime field.
  
  type string Required
  
  Mapping type of the runtime field.
- sourceFilters array[object]
  
  The array of field names you want to filter out in Discover.
  Hide sourceFilters attribute Show sourceFilters attribute object
  
  value string Required
- timeFieldName string
  
  The timestamp field name, which you use for time-based data views.
- title string Required
  
  Comma-separated list of data streams, indices, and aliases that you want to search. Supports wildcards (*).
- type string
  
  When set to rollup, identifies the rollup data views.
- typeMeta object
  
  When you use rollup indices, contains the field list for the rollup data view API endpoints.
  Hide typeMeta attributes Show typeMeta attributes object
  
  aggs object Required
  
  A map of rollup restrictions by aggregation type and field name.
  
  params object Required
  
  Properties for retrieving rollup fields.
- version string
override boolean

Override an existing data view if a data view with the provided title already exists.

Default value is false.

Responses

200 application/json

Indicates a successful call.
Hide response attribute Show response attribute object
- data_view object
  
  Hide data_view attributes Show data_view attributes object
  
  allowNoIndex boolean
  
  Allows the data view saved object to exist before the data is available.
  
  fieldAttrs object
  
  Hide fieldAttrs attribute Show fieldAttrs attribute object
  
  * object Additional properties
  
  A map of field attributes by field name.
  
  Hide * attributes Show * attributes object
  
  count integer
  
  Popularity count for the field.
  
  customDescription string
  
  Custom description for the field.
  
  Maximum length is 300.
  
  customLabel string
  
  Custom label for the field.
  
  fieldFormats object
  
  A map of field formats by field name.
  
  fields object
  
  id string
  
  name string
  
  The data view name.
  
  namespaces array[string]
  
  An array of space identifiers for sharing the data view between multiple spaces.
  
  Default value is default.
  
  runtimeFieldMap object
  
  Hide runtimeFieldMap attribute Show runtimeFieldMap attribute object
  
  * object Additional properties
  
  A map of runtime field definitions by field name.
  
  Hide * attributes Show * attributes object
  
  script object Required
  
  Hide script attribute Show script attribute object
  
  source string
  
  Script for the runtime field.
  
  type string Required
  
  Mapping type of the runtime field.
  
  sourceFilters array[object]
  
  The array of field names you want to filter out in Discover.
  
  Hide sourceFilters attribute Show sourceFilters attribute object
  
  value string Required
  
  timeFieldName string
  
  The timestamp field name, which you use for time-based data views.
  
  title string
  
  Comma-separated list of data streams, indices, and aliases that you want to search. Supports wildcards (*).
  
  typeMeta object | null
  
  When you use rollup indices, contains the field list for the rollup data view API endpoints.
  
  Hide typeMeta attributes Show typeMeta attributes object | null
  
  aggs object
  
  A map of rollup restrictions by aggregation type and field name.
  
  params object
  
  Properties for retrieving rollup fields.
  
  version string
400 application/json

Bad request
Hide response attributes Show response attributes object
- error string Required
- message string Required
- statusCode number Required

POST /api/data_views/data_view

curl \
 --request POST 'https://<KIBANA_URL>/api/data_views/data_view' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: string" \
 --data '{"data_view":{"name":"My Logstash data view","title":"logstash-*","runtimeFieldMap":{"runtime_shape_name":{"type":"keyword","script":{"source":"emit(doc['shape_name'].value)"}}}}}'

Request example

{
  "data_view": {
    "name": "My Logstash data view",
    "title": "logstash-*",
    "runtimeFieldMap": {
      "runtime_shape_name": {
        "type": "keyword",
        "script": {
          "source": "emit(doc['shape_name'].value)"
        }
      }
    }
  }
}

Get a data view

GET /api/data_views/data_view/{viewId}

Path parameters

viewId string Required

An identifier for the data view.

Responses

200 application/json

Indicates a successful call.
Hide response attribute Show response attribute object
- data_view object
  
  Hide data_view attributes Show data_view attributes object
  
  allowNoIndex boolean
  
  Allows the data view saved object to exist before the data is available.
  
  fieldAttrs object
  
  Hide fieldAttrs attribute Show fieldAttrs attribute object
  
  * object Additional properties
  
  A map of field attributes by field name.
  
  Hide * attributes Show * attributes object
  
  count integer
  
  Popularity count for the field.
  
  customDescription string
  
  Custom description for the field.
  
  Maximum length is 300.
  
  customLabel string
  
  Custom label for the field.
  
  fieldFormats object
  
  A map of field formats by field name.
  
  fields object
  
  id string
  
  name string
  
  The data view name.
  
  namespaces array[string]
  
  An array of space identifiers for sharing the data view between multiple spaces.
  
  Default value is default.
  
  runtimeFieldMap object
  
  Hide runtimeFieldMap attribute Show runtimeFieldMap attribute object
  
  * object Additional properties
  
  A map of runtime field definitions by field name.
  
  Hide * attributes Show * attributes object
  
  script object Required
  
  Hide script attribute Show script attribute object
  
  source string
  
  Script for the runtime field.
  
  type string Required
  
  Mapping type of the runtime field.
  
  sourceFilters array[object]
  
  The array of field names you want to filter out in Discover.
  
  Hide sourceFilters attribute Show sourceFilters attribute object
  
  value string Required
  
  timeFieldName string
  
  The timestamp field name, which you use for time-based data views.
  
  title string
  
  Comma-separated list of data streams, indices, and aliases that you want to search. Supports wildcards (*).
  
  typeMeta object | null
  
  When you use rollup indices, contains the field list for the rollup data view API endpoints.
  
  Hide typeMeta attributes Show typeMeta attributes object | null
  
  aggs object
  
  A map of rollup restrictions by aggregation type and field name.
  
  params object
  
  Properties for retrieving rollup fields.
  
  version string
404 application/json

Object is not found.
Hide response attributes Show response attributes object
- error string
  
  Value is Not Found.
- message string
- statusCode integer
  
  Value is 404.

GET /api/data_views/data_view/{viewId}

curl \
 --request GET 'https://<KIBANA_URL>/api/data_views/data_view/ff959d40-b880-11e8-a6d9-e546fe2bba5f' \
 --header "Authorization: $API_KEY"

Response examples (200)

{
  "data_view": {
    "id": "ff959d40-b880-11e8-a6d9-e546fe2bba5f",
    "name": "Kibana Sample Data eCommerce",
    "title": "kibana_sample_data_ecommerce",
    "fields": {
      "_id": {
        "name": "_id",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "_id"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": false,
        "shortDotsEnable": false,
        "readFromDocValues": false
      },
      "sku": {
        "name": "sku",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "keyword"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "type": {
        "name": "type",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "keyword"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "user": {
        "name": "user",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "keyword"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "email": {
        "name": "email",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "keyword"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "_index": {
        "name": "_index",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "_index"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": false
      },
      "_score": {
        "name": "_score",
        "type": "number",
        "count": 0,
        "format": {
          "id": "number"
        },
        "isMapped": true,
        "scripted": false,
        "searchable": false,
        "aggregatable": false,
        "shortDotsEnable": false,
        "readFromDocValues": false
      },
      "_source": {
        "name": "_source",
        "type": "_source",
        "count": 0,
        "format": {
          "id": "_source"
        },
        "esTypes": [
          "_source"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": false,
        "aggregatable": false,
        "shortDotsEnable": false,
        "readFromDocValues": false
      },
      "category": {
        "name": "category",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "text"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": false,
        "shortDotsEnable": false,
        "readFromDocValues": false
      },
      "currency": {
        "name": "currency",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "keyword"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "order_id": {
        "name": "order_id",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "keyword"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "order_date": {
        "name": "order_date",
        "type": "date",
        "count": 0,
        "format": {
          "id": "date"
        },
        "esTypes": [
          "date"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "customer_id": {
        "name": "customer_id",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "keyword"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "day_of_week": {
        "name": "day_of_week",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "keyword"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "manufacturer": {
        "name": "manufacturer",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "text"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": false,
        "shortDotsEnable": false,
        "readFromDocValues": false
      },
      "products._id": {
        "name": "products._id",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "text"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": false,
        "shortDotsEnable": false,
        "readFromDocValues": false
      },
      "products.sku": {
        "name": "products.sku",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "keyword"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "day_of_week_i": {
        "name": "day_of_week_i",
        "type": "number",
        "count": 0,
        "format": {
          "id": "number"
        },
        "esTypes": [
          "integer"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "event.dataset": {
        "name": "event.dataset",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "keyword"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "customer_phone": {
        "name": "customer_phone",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "keyword"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "geoip.location": {
        "name": "geoip.location",
        "type": "geo_point",
        "count": 0,
        "format": {
          "id": "geo_point",
          "params": {
            "transform": "wkt"
          }
        },
        "esTypes": [
          "geo_point"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "products.price": {
        "name": "products.price",
        "type": "number",
        "count": 1,
        "format": {
          "id": "number",
          "params": {
            "pattern": "$0,0.00"
          }
        },
        "esTypes": [
          "half_float"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "total_quantity": {
        "name": "total_quantity",
        "type": "number",
        "count": 1,
        "format": {
          "id": "number"
        },
        "esTypes": [
          "integer"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "customer_gender": {
        "name": "customer_gender",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "keyword"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "geoip.city_name": {
        "name": "geoip.city_name",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "keyword"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "category.keyword": {
        "name": "category.keyword",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "keyword"
        ],
        "subType": {
          "multi": {
            "parent": "category"
          }
        },
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "geoip.region_name": {
        "name": "geoip.region_name",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "keyword"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "products.category": {
        "name": "products.category",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "text"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": false,
        "shortDotsEnable": false,
        "readFromDocValues": false
      },
      "products.quantity": {
        "name": "products.quantity",
        "type": "number",
        "count": 0,
        "format": {
          "id": "number"
        },
        "esTypes": [
          "integer"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "customer_full_name": {
        "name": "customer_full_name",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "text"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": false,
        "shortDotsEnable": false,
        "readFromDocValues": false
      },
      "customer_last_name": {
        "name": "customer_last_name",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "text"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": false,
        "shortDotsEnable": false,
        "readFromDocValues": false
      },
      "products.min_price": {
        "name": "products.min_price",
        "type": "number",
        "count": 0,
        "format": {
          "id": "number",
          "params": {
            "pattern": "$0,0.00"
          }
        },
        "esTypes": [
          "half_float"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "taxful_total_price": {
        "name": "taxful_total_price",
        "type": "number",
        "count": 0,
        "format": {
          "id": "number",
          "params": {
            "pattern": "$0,0.[00]"
          }
        },
        "esTypes": [
          "half_float"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "customer_birth_date": {
        "name": "customer_birth_date",
        "type": "date",
        "count": 0,
        "format": {
          "id": "date"
        },
        "esTypes": [
          "date"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "customer_first_name": {
        "name": "customer_first_name",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "text"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": false,
        "shortDotsEnable": false,
        "readFromDocValues": false
      },
      "products.base_price": {
        "name": "products.base_price",
        "type": "number",
        "count": 0,
        "format": {
          "id": "number",
          "params": {
            "pattern": "$0,0.00"
          }
        },
        "esTypes": [
          "half_float"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "products.created_on": {
        "name": "products.created_on",
        "type": "date",
        "count": 0,
        "format": {
          "id": "date"
        },
        "esTypes": [
          "date"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "products.product_id": {
        "name": "products.product_id",
        "type": "number",
        "count": 0,
        "format": {
          "id": "number"
        },
        "esTypes": [
          "long"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "products.tax_amount": {
        "name": "products.tax_amount",
        "type": "number",
        "count": 0,
        "format": {
          "id": "number"
        },
        "esTypes": [
          "half_float"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "taxless_total_price": {
        "name": "taxless_total_price",
        "type": "number",
        "count": 0,
        "format": {
          "id": "number",
          "params": {
            "pattern": "$0,0.00"
          }
        },
        "esTypes": [
          "half_float"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "geoip.continent_name": {
        "name": "geoip.continent_name",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "keyword"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "manufacturer.keyword": {
        "name": "manufacturer.keyword",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "keyword"
        ],
        "subType": {
          "multi": {
            "parent": "manufacturer"
          }
        },
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "products._id.keyword": {
        "name": "products._id.keyword",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "keyword"
        ],
        "subType": {
          "multi": {
            "parent": "products._id"
          }
        },
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "products.manufacturer": {
        "name": "products.manufacturer",
        "type": "string",
        "count": 1,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "text"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": false,
        "shortDotsEnable": false,
        "readFromDocValues": false
      },
      "products.product_name": {
        "name": "products.product_name",
        "type": "string",
        "count": 1,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "text"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": false,
        "shortDotsEnable": false,
        "readFromDocValues": false
      },
      "products.taxful_price": {
        "name": "products.taxful_price",
        "type": "number",
        "count": 0,
        "format": {
          "id": "number",
          "params": {
            "pattern": "$0,0.00"
          }
        },
        "esTypes": [
          "half_float"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "total_unique_products": {
        "name": "total_unique_products",
        "type": "number",
        "count": 0,
        "format": {
          "id": "number"
        },
        "esTypes": [
          "integer"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "geoip.country_iso_code": {
        "name": "geoip.country_iso_code",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "keyword"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "products.taxless_price": {
        "name": "products.taxless_price",
        "type": "number",
        "count": 0,
        "format": {
          "id": "number",
          "params": {
            "pattern": "$0,0.00"
          }
        },
        "esTypes": [
          "half_float"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "products.base_unit_price": {
        "name": "products.base_unit_price",
        "type": "number",
        "count": 0,
        "format": {
          "id": "number",
          "params": {
            "pattern": "$0,0.00"
          }
        },
        "esTypes": [
          "half_float"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "products.discount_amount": {
        "name": "products.discount_amount",
        "type": "number",
        "count": 0,
        "format": {
          "id": "number"
        },
        "esTypes": [
          "half_float"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "products.category.keyword": {
        "name": "products.category.keyword",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "keyword"
        ],
        "subType": {
          "multi": {
            "parent": "products.category"
          }
        },
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "customer_full_name.keyword": {
        "name": "customer_full_name.keyword",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "keyword"
        ],
        "subType": {
          "multi": {
            "parent": "customer_full_name"
          }
        },
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "customer_last_name.keyword": {
        "name": "customer_last_name.keyword",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "keyword"
        ],
        "subType": {
          "multi": {
            "parent": "customer_last_name"
          }
        },
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "customer_first_name.keyword": {
        "name": "customer_first_name.keyword",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "keyword"
        ],
        "subType": {
          "multi": {
            "parent": "customer_first_name"
          }
        },
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "products.discount_percentage": {
        "name": "products.discount_percentage",
        "type": "number",
        "count": 0,
        "format": {
          "id": "number"
        },
        "esTypes": [
          "half_float"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "products.manufacturer.keyword": {
        "name": "products.manufacturer.keyword",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "keyword"
        ],
        "subType": {
          "multi": {
            "parent": "products.manufacturer"
          }
        },
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "products.product_name.keyword": {
        "name": "products.product_name.keyword",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "keyword"
        ],
        "subType": {
          "multi": {
            "parent": "products.product_name"
          }
        },
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "products.unit_discount_amount": {
        "name": "products.unit_discount_amount",
        "type": "number",
        "count": 0,
        "format": {
          "id": "number"
        },
        "esTypes": [
          "half_float"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      }
    },
    "version": "WzUsMV0=",
    "typeMeta": {},
    "fieldAttrs": {
      "products.price": {
        "count": 1
      },
      "total_quantity": {
        "count": 1
      },
      "products.manufacturer": {
        "count": 1
      },
      "products.product_name": {
        "count": 1
      }
    },
    "namespaces": [
      "default"
    ],
    "allowNoIndex": false,
    "fieldFormats": {
      "products.price": {
        "id": "number",
        "params": {
          "pattern": "$0,0.00"
        }
      },
      "products.min_price": {
        "id": "number",
        "params": {
          "pattern": "$0,0.00"
        }
      },
      "taxful_total_price": {
        "id": "number",
        "params": {
          "pattern": "$0,0.[00]"
        }
      },
      "products.base_price": {
        "id": "number",
        "params": {
          "pattern": "$0,0.00"
        }
      },
      "taxless_total_price": {
        "id": "number",
        "params": {
          "pattern": "$0,0.00"
        }
      },
      "products.taxful_price": {
        "id": "number",
        "params": {
          "pattern": "$0,0.00"
        }
      },
      "products.taxless_price": {
        "id": "number",
        "params": {
          "pattern": "$0,0.00"
        }
      },
      "products.base_unit_price": {
        "id": "number",
        "params": {
          "pattern": "$0,0.00"
        }
      }
    },
    "sourceFilters": [],
    "timeFieldName": "order_date",
    "runtimeFieldMap": {}
  }
}

Update a data view

POST /api/data_views/data_view/{viewId}

Headers

kbn-xsrf string Required

Cross-site request forgery protection

Path parameters

viewId string Required

An identifier for the data view.

application/json

Body Required

data_view object Required

The data view properties you want to update. Only the specified properties are updated in the data view. Unspecified fields stay as they are persisted.
Hide data_view attributes Show data_view attributes object
- allowNoIndex boolean
  
  Allows the data view saved object to exist before the data is available.
- fieldFormats object
  
  A map of field formats by field name.
- fields object
- name string
- runtimeFieldMap object
  Hide runtimeFieldMap attribute Show runtimeFieldMap attribute object
  
  * object Additional properties
  
  A map of runtime field definitions by field name.
  
  Hide * attributes Show * attributes object
  
  script object Required
  
  Hide script attribute Show script attribute object
  
  source string
  
  Script for the runtime field.
  
  type string Required
  
  Mapping type of the runtime field.
- sourceFilters array[object]
  
  The array of field names you want to filter out in Discover.
  Hide sourceFilters attribute Show sourceFilters attribute object
  
  value string Required
- timeFieldName string
  
  The timestamp field name, which you use for time-based data views.
- title string
  
  Comma-separated list of data streams, indices, and aliases that you want to search. Supports wildcards (*).
- type string
  
  When set to rollup, identifies the rollup data views.
- typeMeta object
  
  When you use rollup indices, contains the field list for the rollup data view API endpoints.
  Hide typeMeta attributes Show typeMeta attributes object
  
  aggs object Required
  
  A map of rollup restrictions by aggregation type and field name.
  
  params object Required
  
  Properties for retrieving rollup fields.
refresh_fields boolean

Reloads the data view fields after the data view is updated.

Default value is false.

Responses

200 application/json

Indicates a successful call.
Hide response attribute Show response attribute object
- data_view object
  
  Hide data_view attributes Show data_view attributes object
  
  allowNoIndex boolean
  
  Allows the data view saved object to exist before the data is available.
  
  fieldAttrs object
  
  Hide fieldAttrs attribute Show fieldAttrs attribute object
  
  * object Additional properties
  
  A map of field attributes by field name.
  
  Hide * attributes Show * attributes object
  
  count integer
  
  Popularity count for the field.
  
  customDescription string
  
  Custom description for the field.
  
  Maximum length is 300.
  
  customLabel string
  
  Custom label for the field.
  
  fieldFormats object
  
  A map of field formats by field name.
  
  fields object
  
  id string
  
  name string
  
  The data view name.
  
  namespaces array[string]
  
  An array of space identifiers for sharing the data view between multiple spaces.
  
  Default value is default.
  
  runtimeFieldMap object
  
  Hide runtimeFieldMap attribute Show runtimeFieldMap attribute object
  
  * object Additional properties
  
  A map of runtime field definitions by field name.
  
  Hide * attributes Show * attributes object
  
  script object Required
  
  Hide script attribute Show script attribute object
  
  source string
  
  Script for the runtime field.
  
  type string Required
  
  Mapping type of the runtime field.
  
  sourceFilters array[object]
  
  The array of field names you want to filter out in Discover.
  
  Hide sourceFilters attribute Show sourceFilters attribute object
  
  value string Required
  
  timeFieldName string
  
  The timestamp field name, which you use for time-based data views.
  
  title string
  
  Comma-separated list of data streams, indices, and aliases that you want to search. Supports wildcards (*).
  
  typeMeta object | null
  
  When you use rollup indices, contains the field list for the rollup data view API endpoints.
  
  Hide typeMeta attributes Show typeMeta attributes object | null
  
  aggs object
  
  A map of rollup restrictions by aggregation type and field name.
  
  params object
  
  Properties for retrieving rollup fields.
  
  version string
400 application/json

Bad request
Hide response attributes Show response attributes object
- error string Required
- message string Required
- statusCode number Required

POST /api/data_views/data_view/{viewId}

curl \
 --request POST 'https://<KIBANA_URL>/api/data_views/data_view/ff959d40-b880-11e8-a6d9-e546fe2bba5f' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: string" \
 --data '{"data_view":{"name":"Kibana Sample Data eCommerce","title":"kibana_sample_data_ecommerce","allowNoIndex":false,"timeFieldName":"order_date"},"refresh_fields":true}'

Request example

{
  "data_view": {
    "name": "Kibana Sample Data eCommerce",
    "title": "kibana_sample_data_ecommerce",
    "allowNoIndex": false,
    "timeFieldName": "order_date"
  },
  "refresh_fields": true
}

Delete a data view

DELETE /api/data_views/data_view/{viewId}

WARNING: When you delete a data view, it cannot be recovered.

Headers

kbn-xsrf string Required

Cross-site request forgery protection

Path parameters

viewId string Required

An identifier for the data view.

Responses

204

Indicates a successful call.
404 application/json

Object is not found.
Hide response attributes Show response attributes object
- error string
  
  Value is Not Found.
- message string
- statusCode integer
  
  Value is 404.

DELETE /api/data_views/data_view/{viewId}

curl \
 --request DELETE 'https://<KIBANA_URL>/api/data_views/data_view/ff959d40-b880-11e8-a6d9-e546fe2bba5f' \
 --header "Authorization: $API_KEY" \
 --header "kbn-xsrf: string"

Update data view fields metadata

POST /api/data_views/data_view/{viewId}/fields

Update fields presentation metadata such as count, customLabel, customDescription, and format.

Headers

kbn-xsrf string Required

Cross-site request forgery protection

Path parameters

viewId string Required

An identifier for the data view.

application/json

Body Required

fields object Required

The field object.

Responses

200 application/json

Indicates a successful call.
Hide response attribute Show response attribute object
- acknowledged boolean
400 application/json

Bad request
Hide response attributes Show response attributes object
- error string Required
- message string Required
- statusCode number Required

POST /api/data_views/data_view/{viewId}/fields

curl \
 --request POST 'https://<KIBANA_URL>/api/data_views/data_view/ff959d40-b880-11e8-a6d9-e546fe2bba5f/fields' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: string" \
 --data '{"fields":{"field1":{"count":123,"customLabel":"Field 1 label"},"field2":{"customLabel":"Field 2 label","customDescription":"Field 2 description"}}}'

Request example

{
  "fields": {
    "field1": {
      "count": 123,
      "customLabel": "Field 1 label"
    },
    "field2": {
      "customLabel": "Field 2 label",
      "customDescription": "Field 2 description"
    }
  }
}

Create or update a runtime field

PUT /api/data_views/data_view/{viewId}/runtime_field

Headers

kbn-xsrf string Required

Cross-site request forgery protection

Path parameters

viewId string Required

The ID of the data view fields you want to update.

application/json

Body Required

name string Required

The name for a runtime field.
runtimeField object Required

The runtime field definition object.

Responses

200 application/json

Indicates a successful call.
Hide response attributes Show response attributes object
- data_view object
- fields array[object]
400 application/json

Bad request
Hide response attributes Show response attributes object
- error string Required
- message string Required
- statusCode number Required

PUT /api/data_views/data_view/{viewId}/runtime_field

curl \
 --request PUT 'https://<KIBANA_URL>/api/data_views/data_view/{viewId}/runtime_field' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: string" \
 --data '{"name":"runtimeFoo","runtimeField":{"type":"long","script":{"source":"emit(doc[\"foo\"].value)"}}}'

Request example

{
  "name": "runtimeFoo",
  "runtimeField": {
    "type": "long",
    "script": {
      "source": "emit(doc[\"foo\"].value)"
    }
  }
}

Create a runtime field

POST /api/data_views/data_view/{viewId}/runtime_field

Headers

kbn-xsrf string Required

Cross-site request forgery protection

Path parameters

viewId string Required

An identifier for the data view.

application/json

Body Required

name string Required

The name for a runtime field.
runtimeField object Required

The runtime field definition object.

Responses

200 application/json

Indicates a successful call.

POST /api/data_views/data_view/{viewId}/runtime_field

curl \
 --request POST 'https://<KIBANA_URL>/api/data_views/data_view/ff959d40-b880-11e8-a6d9-e546fe2bba5f/runtime_field' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: string" \
 --data '{"name":"runtimeFoo","runtimeField":{"type":"long","script":{"source":"emit(doc[\"foo\"].value)"}}}'

Request example

{
  "name": "runtimeFoo",
  "runtimeField": {
    "type": "long",
    "script": {
      "source": "emit(doc[\"foo\"].value)"
    }
  }
}

Get a runtime field

GET /api/data_views/data_view/{viewId}/runtime_field/{fieldName}

Path parameters

fieldName string Required

The name of the runtime field.
viewId string Required

An identifier for the data view.

Responses

200 application/json

Indicates a successful call.
Hide response attributes Show response attributes object
- data_view object
- fields array[object]
404 application/json

Object is not found.
Hide response attributes Show response attributes object
- error string
  
  Value is Not Found.
- message string
- statusCode integer
  
  Value is 404.

GET /api/data_views/data_view/{viewId}/runtime_field/{fieldName}

curl \
 --request GET 'https://<KIBANA_URL>/api/data_views/data_view/ff959d40-b880-11e8-a6d9-e546fe2bba5f/runtime_field/hour_of_day' \
 --header "Authorization: $API_KEY"

Response examples (200)

{
  "fields": [
    {
      "name": "hour_of_day",
      "type": "number",
      "count": 0,
      "esTypes": [
        "long"
      ],
      "scripted": false,
      "searchable": true,
      "aggregatable": true,
      "runtimeField": {
        "type": "long",
        "script": {
          "source": "emit(doc['timestamp'].value.getHour());"
        }
      },
      "shortDotsEnable": false,
      "readFromDocValues": false
    }
  ],
  "data_view": {
    "id": "d3d7af60-4c81-11e8-b3d7-01146121b73d",
    "name": "Kibana Sample Data Flights",
    "title": "kibana_sample_data_flights",
    "fields": {
      "_id": {
        "name": "_id",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "_id"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": false,
        "shortDotsEnable": false,
        "readFromDocValues": false
      },
      "Dest": {
        "name": "Dest",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "keyword"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "Origin": {
        "name": "Origin",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "keyword"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "_index": {
        "name": "_index",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "_index"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": false
      },
      "_score": {
        "name": "_score",
        "type": "number",
        "count": 0,
        "format": {
          "id": "number"
        },
        "isMapped": true,
        "scripted": false,
        "searchable": false,
        "aggregatable": false,
        "shortDotsEnable": false,
        "readFromDocValues": false
      },
      "Carrier": {
        "name": "Carrier",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "keyword"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "_source": {
        "name": "_source",
        "type": "_source",
        "count": 0,
        "format": {
          "id": "_source"
        },
        "esTypes": [
          "_source"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": false,
        "aggregatable": false,
        "shortDotsEnable": false,
        "readFromDocValues": false
      },
      "Cancelled": {
        "name": "Cancelled",
        "type": "boolean",
        "count": 0,
        "format": {
          "id": "boolean"
        },
        "esTypes": [
          "boolean"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "FlightNum": {
        "name": "FlightNum",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "keyword"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "dayOfWeek": {
        "name": "dayOfWeek",
        "type": "number",
        "count": 0,
        "format": {
          "id": "number"
        },
        "esTypes": [
          "integer"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "timestamp": {
        "name": "timestamp",
        "type": "date",
        "count": 0,
        "format": {
          "id": "date"
        },
        "esTypes": [
          "date"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "DestRegion": {
        "name": "DestRegion",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "keyword"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "DestCountry": {
        "name": "DestCountry",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "keyword"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "DestWeather": {
        "name": "DestWeather",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "keyword"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "FlightDelay": {
        "name": "FlightDelay",
        "type": "boolean",
        "count": 0,
        "format": {
          "id": "boolean"
        },
        "esTypes": [
          "boolean"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "hour_of_day": {
        "name": "hour_of_day",
        "type": "number",
        "count": 0,
        "format": {
          "id": "number",
          "params": {
            "pattern": "00"
          }
        },
        "esTypes": [
          "long"
        ],
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "runtimeField": {
          "type": "long",
          "script": {
            "source": "emit(doc['timestamp'].value.getHour());"
          }
        },
        "shortDotsEnable": false,
        "readFromDocValues": false
      },
      "DestCityName": {
        "name": "DestCityName",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "keyword"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "DestLocation": {
        "name": "DestLocation",
        "type": "geo_point",
        "count": 0,
        "format": {
          "id": "geo_point",
          "params": {
            "transform": "wkt"
          }
        },
        "esTypes": [
          "geo_point"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "OriginRegion": {
        "name": "OriginRegion",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "keyword"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "DestAirportID": {
        "name": "DestAirportID",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "keyword"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "DistanceMiles": {
        "name": "DistanceMiles",
        "type": "number",
        "count": 0,
        "format": {
          "id": "number"
        },
        "esTypes": [
          "float"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "FlightTimeMin": {
        "name": "FlightTimeMin",
        "type": "number",
        "count": 0,
        "format": {
          "id": "number"
        },
        "esTypes": [
          "float"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "OriginCountry": {
        "name": "OriginCountry",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "keyword"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "OriginWeather": {
        "name": "OriginWeather",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "keyword"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "AvgTicketPrice": {
        "name": "AvgTicketPrice",
        "type": "number",
        "count": 0,
        "format": {
          "id": "number",
          "params": {
            "pattern": "$0,0.[00]"
          }
        },
        "esTypes": [
          "float"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "FlightDelayMin": {
        "name": "FlightDelayMin",
        "type": "number",
        "count": 0,
        "format": {
          "id": "number"
        },
        "esTypes": [
          "integer"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "FlightTimeHour": {
        "name": "FlightTimeHour",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "keyword"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "OriginCityName": {
        "name": "OriginCityName",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "keyword"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "OriginLocation": {
        "name": "OriginLocation",
        "type": "geo_point",
        "count": 0,
        "format": {
          "id": "geo_point",
          "params": {
            "transform": "wkt"
          }
        },
        "esTypes": [
          "geo_point"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "FlightDelayType": {
        "name": "FlightDelayType",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "keyword"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "OriginAirportID": {
        "name": "OriginAirportID",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "keyword"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "DistanceKilometers": {
        "name": "DistanceKilometers",
        "type": "number",
        "count": 0,
        "format": {
          "id": "number"
        },
        "esTypes": [
          "float"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      }
    },
    "version": "WzM2LDJd",
    "fieldAttrs": {},
    "allowNoIndex": false,
    "fieldFormats": {
      "hour_of_day": {
        "id": "number",
        "params": {
          "pattern": "00"
        }
      },
      "AvgTicketPrice": {
        "id": "number",
        "params": {
          "pattern": "$0,0.[00]"
        }
      }
    },
    "sourceFilters": [],
    "timeFieldName": "timestamp",
    "runtimeFieldMap": {
      "hour_of_day": {
        "type": "long",
        "script": {
          "source": "emit(doc['timestamp'].value.getHour());"
        }
      }
    }
  }
}

Update a runtime field

POST /api/data_views/data_view/{viewId}/runtime_field/{fieldName}

Path parameters

fieldName string Required

The name of the runtime field.
viewId string Required

An identifier for the data view.

application/json

Body Required

runtimeField object Required
The runtime field definition object.

You can update following fields:
- type
- script

Responses

200

Indicates a successful call.
400 application/json

Bad request
Hide response attributes Show response attributes object
- error string Required
- message string Required
- statusCode number Required

POST /api/data_views/data_view/{viewId}/runtime_field/{fieldName}

curl \
 --request POST 'https://<KIBANA_URL>/api/data_views/data_view/ff959d40-b880-11e8-a6d9-e546fe2bba5f/runtime_field/hour_of_day' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"runtimeField":{"script":{"source":"emit(doc[\"bar\"].value)"}}}'

Request example

{
  "runtimeField": {
    "script": {
      "source": "emit(doc[\"bar\"].value)"
    }
  }
}

Delete a runtime field from a data view

DELETE /api/data_views/data_view/{viewId}/runtime_field/{fieldName}

Path parameters

fieldName string Required

The name of the runtime field.
viewId string Required

An identifier for the data view.

Responses

200

Indicates a successful call.
404 application/json

Object is not found.
Hide response attributes Show response attributes object
- error string
  
  Value is Not Found.
- message string
- statusCode integer
  
  Value is 404.

DELETE /api/data_views/data_view/{viewId}/runtime_field/{fieldName}

curl \
 --request DELETE 'https://<KIBANA_URL>/api/data_views/data_view/ff959d40-b880-11e8-a6d9-e546fe2bba5f/runtime_field/hour_of_day' \
 --header "Authorization: $API_KEY"

Get the default data view

GET /api/data_views/default

Responses

200 application/json

Indicates a successful call.
Hide response attribute Show response attribute object
- data_view_id string
400 application/json

Bad request
Hide response attributes Show response attributes object
- error string Required
- message string Required
- statusCode number Required

GET /api/data_views/default

curl \
 --request GET 'https://<KIBANA_URL>/api/data_views/default' \
 --header "Authorization: $API_KEY"

Response examples (200)

{
  "data_view_id": "ff959d40-b880-11e8-a6d9-e546fe2bba5f"
}

Set the default data view

POST /api/data_views/default

Headers

kbn-xsrf string Required

Cross-site request forgery protection

application/json

Body Required

data_view_id string | null Required

The data view identifier. NOTE: The API does not validate whether it is a valid identifier. Use null to unset the default data view.
force boolean

Update an existing default data view identifier.

Default value is false.

Responses

200 application/json

Indicates a successful call.
Hide response attribute Show response attribute object
- acknowledged boolean
400 application/json

Bad request
Hide response attributes Show response attributes object
- error string Required
- message string Required
- statusCode number Required

POST /api/data_views/default

curl \
 --request POST 'https://<KIBANA_URL>/api/data_views/default' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: string" \
 --data '{"force":true,"data_view_id":"ff959d40-b880-11e8-a6d9-e546fe2bba5f"}'

Request example

{
  "force": true,
  "data_view_id": "ff959d40-b880-11e8-a6d9-e546fe2bba5f"
}

Swap saved object references

POST /api/data_views/swap_references

Changes saved object references from one data view identifier to another. WARNING: Misuse can break large numbers of saved objects! Practicing with a backup is recommended.

Headers

kbn-xsrf string Required

Cross-site request forgery protection

application/json

Body Required

delete boolean

Deletes referenced saved object if all references are removed.
forId string | array[string]

Limit the affected saved objects to one or more by identifier.

One of:
string-1 string array-2 array[string]
forType string

Limit the affected saved objects by type.
fromId string Required

The saved object reference to change.
fromType string

Specify the type of the saved object reference to alter. The default value is index-pattern for data views.
toId string Required

New saved object reference value to replace the old value.

Responses

200 application/json

Indicates a successful call.
Hide response attributes Show response attributes object
- deleteStatus object
  
  Hide deleteStatus attributes Show deleteStatus attributes object
  
  deletePerformed boolean
  
  remainingRefs integer
- result array[object]
  
  Hide result attributes Show result attributes object
  
  id string
  
  A saved object identifier.
  
  type string
  
  The saved object type.

POST /api/data_views/swap_references

curl \
 --request POST 'https://<KIBANA_URL>/api/data_views/swap_references' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: string" \
 --data '{"toId":"xyz-123","delete":true,"fromId":"abcd-efg"}'

Request example

{
  "toId": "xyz-123",
  "delete": true,
  "fromId": "abcd-efg"
}

Preview a saved object reference swap

POST /api/data_views/swap_references/_preview

Preview the impact of swapping saved object references from one data view identifier to another.

Headers

kbn-xsrf string Required

Cross-site request forgery protection

application/json

Body Required

delete boolean

Deletes referenced saved object if all references are removed.
forId string | array[string]

Limit the affected saved objects to one or more by identifier.

One of:
string-1 string array-2 array[string]
forType string

Limit the affected saved objects by type.
fromId string Required

The saved object reference to change.
fromType string

Specify the type of the saved object reference to alter. The default value is index-pattern for data views.
toId string Required

New saved object reference value to replace the old value.

Responses

200 application/json

Indicates a successful call.
Hide response attribute Show response attribute object
- result array[object]
  
  Hide result attributes Show result attributes object
  
  id string
  
  A saved object identifier.
  
  type string
  
  The saved object type.

POST /api/data_views/swap_references/_preview

curl \
 --request POST 'https://<KIBANA_URL>/api/data_views/swap_references/_preview' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: string" \
 --data '{"toId":"xyz-123","fromId":"abcd-efg"}'

Request example

{
  "toId": "xyz-123",
  "fromId": "abcd-efg"
}

Create an agent action

POST /api/fleet/agents/{agentId}/actions

[Required authorization] Route required privileges: fleet-agents-all.

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

Path parameters

agentId string Required

application/json

Body

action object Required
Any of:
object-1 object object-2 object
Hide attribute Show attribute

type string Required

Values are UNENROLL, UPGRADE, or POLICY_REASSIGN.
Hide attributes Show attributes

data object Required

Additional properties are NOT allowed.

Hide data attribute Show data attribute object

log_level string | null Required

Values are debug, info, warning, or error.

type string Required

Value is SETTINGS.

Responses

200 application/json
Hide response attribute Show response attribute object
- item object Required
  
  Additional properties are NOT allowed.
  
  Hide item attributes Show item attributes object
  
  agents array[string]
  
  created_at string Required
  
  expiration string
  
  id string Required
  
  minimum_execution_duration number
  
  namespaces array[string]
  
  rollout_duration_seconds number
  
  sent_at string
  
  source_uri string
  
  start_time string
  
  total number
  
  type string Required
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

POST /api/fleet/agents/{agentId}/actions

curl \
 --request POST 'https://<KIBANA_URL>/api/fleet/agents/{agentId}/actions' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"action":{"type":"UNENROLL"}}'

Reassign an agent

POST /api/fleet/agents/{agentId}/reassign

[Required authorization] Route required privileges: fleet-agents-all.

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

Path parameters

agentId string Required

application/json

Body

policy_id string Required

Responses

200 application/json

Additional properties are NOT allowed.
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

POST /api/fleet/agents/{agentId}/reassign

curl \
 --request POST 'https://<KIBANA_URL>/api/fleet/agents/{agentId}/reassign' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"policy_id":"string"}'

Request agent diagnostics

POST /api/fleet/agents/{agentId}/request_diagnostics

[Required authorization] Route required privileges: fleet-agents-read.

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

Path parameters

agentId string Required

application/json

Body

additional_metrics array[string]

Value is CPU.

Responses

200 application/json
Hide response attribute Show response attribute object
- actionId string Required
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

POST /api/fleet/agents/{agentId}/request_diagnostics

curl \
 --request POST 'https://<KIBANA_URL>/api/fleet/agents/{agentId}/request_diagnostics' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"additional_metrics":["CPU"]}'

Unenroll an agent

POST /api/fleet/agents/{agentId}/unenroll

[Required authorization] Route required privileges: fleet-agents-all.

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

Path parameters

agentId string Required

application/json

Body

force boolean
revoke boolean

POST /api/fleet/agents/{agentId}/unenroll

curl \
 --request POST 'https://<KIBANA_URL>/api/fleet/agents/{agentId}/unenroll' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"force":true,"revoke":true}'

Upgrade an agent

POST /api/fleet/agents/{agentId}/upgrade

[Required authorization] Route required privileges: fleet-agents-all.

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

Path parameters

agentId string Required

application/json

Body

force boolean
skipRateLimitCheck boolean
source_uri string
version string Required

Responses

200 application/json

Additional properties are NOT allowed.
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

POST /api/fleet/agents/{agentId}/upgrade

curl \
 --request POST 'https://<KIBANA_URL>/api/fleet/agents/{agentId}/upgrade' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"force":true,"skipRateLimitCheck":true,"source_uri":"string","version":"string"}'

Get an agent action status

GET /api/fleet/agents/action_status

[Required authorization] Route required privileges: fleet-agents-read.

Query parameters

page number

Default value is 0.
perPage number

Default value is 20.
date string
latest number
errorSize number

Default value is 5.

Responses

200 application/json
Hide response attribute Show response attribute object
- items array[object] Required
  
  Hide items attributes Show items attributes object
  
  actionId string Required
  
  cancellationTime string
  
  completionTime string
  
  creationTime string Required
  
  creation time of action
  
  expiration string
  
  hasRolloutPeriod boolean
  
  is_automatic boolean
  
  latestErrors array[object]
  
  latest errors that happened when the agents executed the action
  
  Hide latestErrors attributes Show latestErrors attributes object
  
  agentId string Required
  
  error string Required
  
  hostname string
  
  timestamp string Required
  
  nbAgentsAck number Required
  
  number of agents that acknowledged the action
  
  nbAgentsActionCreated number Required
  
  number of agents included in action from kibana
  
  nbAgentsActioned number Required
  
  number of agents actioned
  
  nbAgentsFailed number Required
  
  number of agents that failed to execute the action
  
  newPolicyId string
  
  new policy id (POLICY_REASSIGN action)
  
  policyId string
  
  policy id (POLICY_CHANGE action)
  
  revision number
  
  new policy revision (POLICY_CHANGE action)
  
  startTime string
  
  start time of action (scheduled actions)
  
  status string Required
  
  Values are COMPLETE, EXPIRED, CANCELLED, FAILED, IN_PROGRESS, or ROLLOUT_PASSED.
  
  type string Required
  
  Values are UPGRADE, UNENROLL, SETTINGS, POLICY_REASSIGN, CANCEL, FORCE_UNENROLL, REQUEST_DIAGNOSTICS, UPDATE_TAGS, POLICY_CHANGE, or INPUT_ACTION.
  
  version string
  
  agent version number (UPGRADE action)
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

GET /api/fleet/agents/action_status

curl \
 --request GET 'https://<KIBANA_URL>/api/fleet/agents/action_status' \
 --header "Authorization: $API_KEY"

Cancel an agent action

POST /api/fleet/agents/actions/{actionId}/cancel

[Required authorization] Route required privileges: fleet-agents-all.

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

Path parameters

actionId string Required

Responses

200 application/json
Hide response attribute Show response attribute object
- item object Required
  
  Additional properties are NOT allowed.
  
  Hide item attributes Show item attributes object
  
  agents array[string]
  
  created_at string Required
  
  expiration string
  
  id string Required
  
  minimum_execution_duration number
  
  namespaces array[string]
  
  rollout_duration_seconds number
  
  sent_at string
  
  source_uri string
  
  start_time string
  
  total number
  
  type string Required
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

POST /api/fleet/agents/actions/{actionId}/cancel

curl \
 --request POST 'https://<KIBANA_URL>/api/fleet/agents/actions/{actionId}/cancel' \
 --header "Authorization: $API_KEY" \
 --header "kbn-xsrf: true"

Bulk reassign agents

POST /api/fleet/agents/bulk_reassign

[Required authorization] Route required privileges: fleet-agents-all.

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

application/json

Body

agents array[string] | string Required

Any of:
array-1 array[string] string-2 string
batchSize number
includeInactive boolean

Default value is false.
policy_id string Required

Responses

200 application/json
Hide response attribute Show response attribute object
- actionId string Required
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

POST /api/fleet/agents/bulk_reassign

curl \
 --request POST 'https://<KIBANA_URL>/api/fleet/agents/bulk_reassign' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"agents":["string"],"batchSize":42.0,"includeInactive":false,"policy_id":"string"}'

Bulk request diagnostics from agents

POST /api/fleet/agents/bulk_request_diagnostics

[Required authorization] Route required privileges: fleet-agents-read.

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

application/json

Body

additional_metrics array[string]

Value is CPU.
agents array[string] | string Required

Any of:
array-1 array[string] string-2 string
batchSize number

Responses

200 application/json
Hide response attribute Show response attribute object
- actionId string Required
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

POST /api/fleet/agents/bulk_request_diagnostics

curl \
 --request POST 'https://<KIBANA_URL>/api/fleet/agents/bulk_request_diagnostics' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"additional_metrics":["CPU"],"agents":["string"],"batchSize":42.0}'

Bulk unenroll agents

POST /api/fleet/agents/bulk_unenroll

[Required authorization] Route required privileges: fleet-agents-all.

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

application/json

Body

agents array[string] | string Required

Any of:
array-1 array[string] string-2 string

KQL query string, leave empty to action all agents
batchSize number
force boolean

Unenrolls hosted agents too
includeInactive boolean

When passing agents by KQL query, unenrolls inactive agents too
revoke boolean

Revokes API keys of agents

Responses

200 application/json
Hide response attribute Show response attribute object
- actionId string Required
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

POST /api/fleet/agents/bulk_unenroll

curl \
 --request POST 'https://<KIBANA_URL>/api/fleet/agents/bulk_unenroll' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"agents":["string"],"batchSize":42.0,"force":true,"includeInactive":true,"revoke":true}'

Bulk update agent tags

POST /api/fleet/agents/bulk_update_agent_tags

[Required authorization] Route required privileges: fleet-agents-all.

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

application/json

Body

agents array[string] | string Required

Any of:
array-1 array[string] string-2 string
batchSize number
includeInactive boolean

Default value is false.
tagsToAdd array[string]
tagsToRemove array[string]

Responses

200 application/json
Hide response attribute Show response attribute object
- actionId string Required
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

POST /api/fleet/agents/bulk_update_agent_tags

curl \
 --request POST 'https://<KIBANA_URL>/api/fleet/agents/bulk_update_agent_tags' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"agents":["string"],"batchSize":42.0,"includeInactive":false,"tagsToAdd":["string"],"tagsToRemove":["string"]}'

Bulk upgrade agents

POST /api/fleet/agents/bulk_upgrade

[Required authorization] Route required privileges: fleet-agents-all.

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

application/json

Body

agents array[string] | string Required

Any of:
array-1 array[string] string-2 string
batchSize number
force boolean
includeInactive boolean

Default value is false.
rollout_duration_seconds number

Minimum value is 600.
skipRateLimitCheck boolean
source_uri string
start_time string
version string Required

Responses

200 application/json
Hide response attribute Show response attribute object
- actionId string Required
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

POST /api/fleet/agents/bulk_upgrade

curl \
 --request POST 'https://<KIBANA_URL>/api/fleet/agents/bulk_upgrade' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"agents":["string"],"batchSize":42.0,"force":true,"includeInactive":false,"rollout_duration_seconds":42.0,"skipRateLimitCheck":true,"source_uri":"string","start_time":"string","version":"string"}'

Get agent binary download sources

GET /api/fleet/agent_download_sources

[Required authorization] Route required privileges: fleet-agent-policies-read OR fleet-settings-read.

Responses

200 application/json
Hide response attributes Show response attributes object
- items array[object] Required
  
  Hide items attributes Show items attributes object
  
  host string(uri) Required
  
  id string Required
  
  is_default boolean
  
  Default value is false.
  
  name string Required
  
  proxy_id string | null
  
  The ID of the proxy to use for this download source. See the proxies API for more information.
  
  secrets object
  
  Additional properties are NOT allowed.
  
  Hide secrets attribute Show secrets attribute object
  
  ssl object
  
  Additional properties are NOT allowed.
  
  Hide ssl attribute Show ssl attribute object
  
  key object | string
  
  Any of:
  object-1 object string-2 string
  
  Hide attribute Show attribute
  
  id string Required
  
  ssl object
  
  Additional properties are NOT allowed.
  
  Hide ssl attributes Show ssl attributes object
  
  certificate string
  
  certificate_authorities array[string]
  
  key string
- page number Required
- perPage number Required
- total number Required
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

GET /api/fleet/agent_download_sources

curl \
 --request GET 'https://<KIBANA_URL>/api/fleet/agent_download_sources' \
 --header "Authorization: $API_KEY"

Create an agent binary download source

POST /api/fleet/agent_download_sources

[Required authorization] Route required privileges: fleet-settings-all.

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

application/json

Body

host string(uri) Required
id string
is_default boolean

Default value is false.
name string Required
proxy_id string | null

The ID of the proxy to use for this download source. See the proxies API for more information.
secrets object

Additional properties are NOT allowed.
Hide secrets attribute Show secrets attribute object
- ssl object
  
  Additional properties are NOT allowed.
  Hide ssl attribute Show ssl attribute object
  
  key object | string
  
  Any of:
  object-1 object string-2 string
  
  Hide attribute Show attribute
  
  id string Required
ssl object

Additional properties are NOT allowed.
Hide ssl attributes Show ssl attributes object
- certificate string
- certificate_authorities array[string]
- key string

Responses

200 application/json
Hide response attribute Show response attribute object
- item object Required
  
  Additional properties are NOT allowed.
  
  Hide item attributes Show item attributes object
  
  host string(uri) Required
  
  id string Required
  
  is_default boolean
  
  Default value is false.
  
  name string Required
  
  proxy_id string | null
  
  The ID of the proxy to use for this download source. See the proxies API for more information.
  
  secrets object
  
  Additional properties are NOT allowed.
  
  Hide secrets attribute Show secrets attribute object
  
  ssl object
  
  Additional properties are NOT allowed.
  
  Hide ssl attribute Show ssl attribute object
  
  key object | string
  
  Any of:
  object-1 object string-2 string
  
  Hide attribute Show attribute
  
  id string Required
  
  ssl object
  
  Additional properties are NOT allowed.
  
  Hide ssl attributes Show ssl attributes object
  
  certificate string
  
  certificate_authorities array[string]
  
  key string
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

POST /api/fleet/agent_download_sources

curl \
 --request POST 'https://<KIBANA_URL>/api/fleet/agent_download_sources' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"host":"https://example.com","id":"string","is_default":false,"name":"string","proxy_id":"string","secrets":{"ssl":{"key":{"id":"string"}}},"ssl":{"certificate":"string","certificate_authorities":["string"],"key":"string"}}'

Get an agent binary download source

GET /api/fleet/agent_download_sources/{sourceId}

Get an agent binary download source by ID.

[Required authorization] Route required privileges: fleet-agent-policies-read OR fleet-settings-read.

Path parameters

sourceId string Required

Responses

200 application/json
Hide response attribute Show response attribute object
- item object Required
  
  Additional properties are NOT allowed.
  
  Hide item attributes Show item attributes object
  
  host string(uri) Required
  
  id string Required
  
  is_default boolean
  
  Default value is false.
  
  name string Required
  
  proxy_id string | null
  
  The ID of the proxy to use for this download source. See the proxies API for more information.
  
  secrets object
  
  Additional properties are NOT allowed.
  
  Hide secrets attribute Show secrets attribute object
  
  ssl object
  
  Additional properties are NOT allowed.
  
  Hide ssl attribute Show ssl attribute object
  
  key object | string
  
  Any of:
  object-1 object string-2 string
  
  Hide attribute Show attribute
  
  id string Required
  
  ssl object
  
  Additional properties are NOT allowed.
  
  Hide ssl attributes Show ssl attributes object
  
  certificate string
  
  certificate_authorities array[string]
  
  key string
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

GET /api/fleet/agent_download_sources/{sourceId}

curl \
 --request GET 'https://<KIBANA_URL>/api/fleet/agent_download_sources/{sourceId}' \
 --header "Authorization: $API_KEY"

Update an agent binary download source

PUT /api/fleet/agent_download_sources/{sourceId}

Update an agent binary download source by ID.

[Required authorization] Route required privileges: fleet-settings-all.

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

Path parameters

sourceId string Required

application/json

Body

host string(uri) Required
id string
is_default boolean

Default value is false.
name string Required
proxy_id string | null

The ID of the proxy to use for this download source. See the proxies API for more information.
secrets object

Additional properties are NOT allowed.
Hide secrets attribute Show secrets attribute object
- ssl object
  
  Additional properties are NOT allowed.
  Hide ssl attribute Show ssl attribute object
  
  key object | string
  
  Any of:
  object-1 object string-2 string
  
  Hide attribute Show attribute
  
  id string Required
ssl object

Additional properties are NOT allowed.
Hide ssl attributes Show ssl attributes object
- certificate string
- certificate_authorities array[string]
- key string

Responses

200 application/json
Hide response attribute Show response attribute object
- item object Required
  
  Additional properties are NOT allowed.
  
  Hide item attributes Show item attributes object
  
  host string(uri) Required
  
  id string Required
  
  is_default boolean
  
  Default value is false.
  
  name string Required
  
  proxy_id string | null
  
  The ID of the proxy to use for this download source. See the proxies API for more information.
  
  secrets object
  
  Additional properties are NOT allowed.
  
  Hide secrets attribute Show secrets attribute object
  
  ssl object
  
  Additional properties are NOT allowed.
  
  Hide ssl attribute Show ssl attribute object
  
  key object | string
  
  Any of:
  object-1 object string-2 string
  
  Hide attribute Show attribute
  
  id string Required
  
  ssl object
  
  Additional properties are NOT allowed.
  
  Hide ssl attributes Show ssl attributes object
  
  certificate string
  
  certificate_authorities array[string]
  
  key string
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

PUT /api/fleet/agent_download_sources/{sourceId}

curl \
 --request PUT 'https://<KIBANA_URL>/api/fleet/agent_download_sources/{sourceId}' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"host":"https://example.com","id":"string","is_default":false,"name":"string","proxy_id":"string","secrets":{"ssl":{"key":{"id":"string"}}},"ssl":{"certificate":"string","certificate_authorities":["string"],"key":"string"}}'

Delete an agent binary download source

DELETE /api/fleet/agent_download_sources/{sourceId}

Delete an agent binary download source by ID.

[Required authorization] Route required privileges: fleet-settings-all.

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

Path parameters

sourceId string Required

Responses

200 application/json
Hide response attribute Show response attribute object
- id string Required
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

DELETE /api/fleet/agent_download_sources/{sourceId}

curl \
 --request DELETE 'https://<KIBANA_URL>/api/fleet/agent_download_sources/{sourceId}' \
 --header "Authorization: $API_KEY" \
 --header "kbn-xsrf: true"

Get agent policies

GET /api/fleet/agent_policies

[Required authorization] Route required privileges: fleet-agent-policies-read OR fleet-agents-read OR fleet-setup.

Query parameters

page number
perPage number
sortField string
sortOrder string

Values are desc or asc.
showUpgradeable boolean
kuery string
noAgentCount boolean Deprecated

use withAgentCount instead
withAgentCount boolean

get policies with agent count
full boolean

get full policies with package policies populated
format string

Values are simplified or legacy.

Responses

200 application/json
Hide response attributes Show response attributes object
- items array[object] Required
  
  Hide items attributes Show items attributes object
  
  advanced_settings object
  
  Additional properties are NOT allowed.
  
  Hide advanced_settings attributes Show advanced_settings attributes object
  
  agent_download_target_directory
  
  agent_download_timeout
  
  agent_limits_go_max_procs
  
  agent_logging_files_interval
  
  agent_logging_files_keepfiles
  
  agent_logging_files_rotateeverybytes
  
  agent_logging_level
  
  agent_logging_metrics_period
  
  agent_logging_to_files
  
  agent_features array[object]
  
  Hide agent_features attributes Show agent_features attributes object
  
  enabled boolean Required
  
  name string Required
  
  agentless object
  
  Additional properties are NOT allowed.
  
  Hide agentless attributes Show agentless attributes object
  
  cloud_connectors object
  
  Additional properties are NOT allowed.
  
  Hide cloud_connectors attributes Show cloud_connectors attributes object
  
  enabled boolean Required
  
  target_csp string
  
  resources object
  
  Additional properties are NOT allowed.
  
  Hide resources attribute Show resources attribute object
  
  requests object
  
  Additional properties are NOT allowed.
  
  Hide requests attributes Show requests attributes object
  
  cpu string
  
  memory string
  
  agents number
  
  data_output_id string | null
  
  description string
  
  download_source_id string | null
  
  fleet_server_host_id string | null
  
  global_data_tags array[object]
  
  User defined data tags that are added to all of the inputs. The values can be strings or numbers.
  
  Hide global_data_tags attributes Show global_data_tags attributes object
  
  name string Required
  
  value string | number Required
  
  Any of:
  string-1 string number-2 number
  
  has_fleet_server boolean
  
  id string Required
  
  inactivity_timeout number
  
  Minimum value is 0. Default value is 1209600.
  
  is_default boolean
  
  is_default_fleet_server boolean
  
  is_managed boolean Required
  
  is_preconfigured boolean
  
  is_protected boolean Required
  
  Indicates whether the agent policy has tamper protection enabled. Default false.
  
  keep_monitoring_alive boolean | null
  
  When set to true, monitoring will be enabled but logs/metrics collection will be disabled
  
  Default value is false.
  
  monitoring_diagnostics object
  
  Additional properties are NOT allowed.
  
  Hide monitoring_diagnostics attributes Show monitoring_diagnostics attributes object
  
  limit object
  
  Additional properties are NOT allowed.
  
  Hide limit attributes Show limit attributes object
  
  burst number
  
  interval string
  
  uploader object
  
  Additional properties are NOT allowed.
  
  Hide uploader attributes Show uploader attributes object
  
  init_dur string
  
  max_dur string
  
  max_retries number
  
  monitoring_enabled array[string]
  
  Values are logs, metrics, or traces.
  
  monitoring_http object
  
  Additional properties are NOT allowed.
  
  Hide monitoring_http attributes Show monitoring_http attributes object
  
  buffer object
  
  Additional properties are NOT allowed.
  
  Hide buffer attribute Show buffer attribute object
  
  enabled boolean
  
  Default value is false.
  
  enabled boolean
  
  host string
  
  port number
  
  Minimum value is 0, maximum value is 65353.
  
  monitoring_output_id string | null
  
  monitoring_pprof_enabled boolean
  
  name string Required
  
  Minimum length is 1.
  
  namespace string Required
  
  Minimum length is 1.
  
  overrides object | null
  
  Override settings that are defined in the agent policy. Input settings cannot be overridden. The override option should be used only in unusual circumstances and not as a routine procedure.
  
  Additional properties are allowed.
  
  package_policies array[string] | array[object]
  
  Any of:
  array-1 array[string] array-2 array[object]
  
  This field is present only when retrieving a single agent policy, or when retrieving a list of agent policies with the ?full=true parameter
  
  Hide attributes Show attributes object
  
  additional_datastreams_permissions array[string] | null
  
  Additional datastream permissions, that will be added to the agent policy.
  
  agents number
  
  created_at string Required
  
  created_by string Required
  
  description string
  
  Package policy description
  
  elasticsearch object
  
  Additional properties are allowed.
  
  Hide elasticsearch attribute Show elasticsearch attribute object
  
  privileges object
  
  Additional properties are allowed.
  
  Hide privileges attribute Show privileges attribute object
  
  cluster array[string]
  
  enabled boolean Required
  
  id string Required
  
  inputs array[object] | object Required
  
  Any of:
  array-1 array[object] object-2 object
  
  Hide attributes Show attributes object
  
  config object
  
  Package variable (see integration documentation for more information)
  
  Hide config attribute Show config attribute object
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  frozen boolean
  
  type string
  
  enabled boolean Required
  
  id string
  
  keep_enabled boolean
  
  policy_template string
  
  streams array[object] Required
  
  Hide streams attributes Show streams attributes object
  
  config object
  
  Package variable (see integration documentation for more information)
  
  Hide config attribute Show config attribute object
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  frozen boolean
  
  type string
  
  data_stream object Required
  
  Additional properties are NOT allowed.
  
  Hide data_stream attributes Show data_stream attributes object
  
  dataset string Required
  
  elasticsearch object
  
  Additional properties are NOT allowed.
  
  Hide elasticsearch attributes Show elasticsearch attributes object
  
  dynamic_dataset boolean
  
  dynamic_namespace boolean
  
  privileges object
  
  Additional properties are NOT allowed.
  
  Hide privileges attribute Show privileges attribute object
  
  indices array[string]
  
  type string Required
  
  enabled boolean Required
  
  id string
  
  keep_enabled boolean
  
  release string
  
  Values are ga, beta, or experimental.
  
  vars object
  
  Package variable (see integration documentation for more information)
  
  Hide vars attribute Show vars attribute object
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  frozen boolean
  
  type string
  
  type string Required
  
  vars object
  
  Package variable (see integration documentation for more information)
  
  Hide vars attribute Show vars attribute object
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  frozen boolean
  
  type string
  
  Package policy inputs (see integration documentation to know what inputs are available)
  
  Hide attribute Show attribute
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  enabled boolean
  
  enable or disable that input, (default to true)
  
  streams object
  
  Input streams (see integration documentation to know what streams are available)
  
  Hide streams attribute Show streams attribute object
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  enabled boolean
  
  enable or disable that stream, (default to true)
  
  vars object
  
  Input/stream level variable (see integration documentation for more information)
  
  vars object
  
  Input/stream level variable (see integration documentation for more information)
  
  is_managed boolean
  
  name string Required
  
  Package policy name (should be unique)
  
  namespace string
  
  The package policy namespace. Leave blank to inherit the agent policy's namespace.
  
  output_id string | null
  
  overrides object | null
  
  Override settings that are defined in the package policy. The override option should be used only in unusual circumstances and not as a routine procedure.
  
  Additional properties are NOT allowed.
  
  Hide overrides attribute Show overrides attribute object | null
  
  inputs object
  
  Additional properties are allowed.
  
  package object
  
  Additional properties are NOT allowed.
  
  Hide package attributes Show package attributes object
  
  experimental_data_stream_features array[object]
  
  Hide experimental_data_stream_features attributes Show experimental_data_stream_features attributes object
  
  data_stream string Required
  
  features object Required
  
  Additional properties are NOT allowed.
  
  Hide features attributes Show features attributes object
  
  doc_value_only_numeric boolean
  
  doc_value_only_other boolean
  
  synthetic_source boolean
  
  tsdb boolean
  
  name string Required
  
  Package name
  
  requires_root boolean
  
  title string
  
  version string Required
  
  Package version
  
  policy_id string | null Deprecated
  
  Agent policy ID where that package policy will be added
  
  policy_ids array[string]
  
  Agent policy IDs where that package policy will be added
  
  revision number Required
  
  secret_references array[object]
  
  Hide secret_references attribute Show secret_references attribute object
  
  id string Required
  
  spaceIds array[string]
  
  supports_agentless boolean | null
  
  Indicates whether the package policy belongs to an agentless agent policy.
  
  Default value is false.
  
  updated_at string Required
  
  updated_by string Required
  
  vars object
  
  Any of:
  object-1 object object-2 object
  
  Package variable (see integration documentation for more information)
  
  Hide attribute Show attribute
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  frozen boolean
  
  type string
  
  version string
  
  required_versions array[object] | null
  
  Hide required_versions attributes Show required_versions attributes object
  
  percentage number Required
  
  Target percentage of agents to auto upgrade
  
  Minimum value is 0, maximum value is 100.
  
  version string Required
  
  Target version for automatic agent upgrade
  
  revision number Required
  
  schema_version string
  
  space_ids array[string]
  
  status string Required
  
  Values are active or inactive.
  
  supports_agentless boolean | null
  
  Indicates whether the agent policy supports agentless integrations.
  
  Default value is false.
  
  unenroll_timeout number
  
  Minimum value is 0.
  
  unprivileged_agents number
  
  updated_at string Required
  
  updated_by string Required
  
  version string
- page number Required
- perPage number Required
- total number Required
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

GET /api/fleet/agent_policies

curl \
 --request GET 'https://<KIBANA_URL>/api/fleet/agent_policies' \
 --header "Authorization: $API_KEY"

Create an agent policy

POST /api/fleet/agent_policies

[Required authorization] Route required privileges: fleet-agent-policies-all.

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

Query parameters

sys_monitoring boolean

application/json

Body

advanced_settings object

Additional properties are NOT allowed.
Hide advanced_settings attributes Show advanced_settings attributes object
agent_features array[object]
Hide agent_features attributes Show agent_features attributes object
- enabled boolean Required
- name string Required
agentless object

Additional properties are NOT allowed.
Hide agentless attributes Show agentless attributes object
- cloud_connectors object
  
  Additional properties are NOT allowed.
  Hide cloud_connectors attributes Show cloud_connectors attributes object
  
  enabled boolean Required
  
  target_csp string
- resources object
  
  Additional properties are NOT allowed.
  Hide resources attribute Show resources attribute object
  
  requests object
  
  Additional properties are NOT allowed.
  
  Hide requests attributes Show requests attributes object
  
  cpu string
  
  memory string
data_output_id string | null
description string
download_source_id string | null
fleet_server_host_id string | null
force boolean
global_data_tags array[object]

User defined data tags that are added to all of the inputs. The values can be strings or numbers.
Hide global_data_tags attributes Show global_data_tags attributes object
- name string Required
- value string | number Required
  
  Any of:
  string-1 string number-2 number
has_fleet_server boolean
id string
inactivity_timeout number

Minimum value is 0. Default value is 1209600.
is_default boolean
is_default_fleet_server boolean
is_managed boolean
is_protected boolean
keep_monitoring_alive boolean | null

When set to true, monitoring will be enabled but logs/metrics collection will be disabled

Default value is false.
monitoring_diagnostics object

Additional properties are NOT allowed.
Hide monitoring_diagnostics attributes Show monitoring_diagnostics attributes object
- limit object
  
  Additional properties are NOT allowed.
  Hide limit attributes Show limit attributes object
  
  burst number
  
  interval string
- uploader object
  
  Additional properties are NOT allowed.
  Hide uploader attributes Show uploader attributes object
  
  init_dur string
  
  max_dur string
  
  max_retries number
monitoring_enabled array[string]

Values are logs, metrics, or traces.
monitoring_http object

Additional properties are NOT allowed.
Hide monitoring_http attributes Show monitoring_http attributes object
- buffer object
  
  Additional properties are NOT allowed.
  Hide buffer attribute Show buffer attribute object
  
  enabled boolean
  
  Default value is false.
- enabled boolean
- host string
- port number
  
  Minimum value is 0, maximum value is 65353.
monitoring_output_id string | null
monitoring_pprof_enabled boolean
name string Required

Minimum length is 1.
namespace string Required

Minimum length is 1.
overrides object | null

Override settings that are defined in the agent policy. Input settings cannot be overridden. The override option should be used only in unusual circumstances and not as a routine procedure.

Additional properties are allowed.
required_versions array[object] | null
Hide required_versions attributes Show required_versions attributes object
- percentage number Required
  
  Target percentage of agents to auto upgrade
  
  Minimum value is 0, maximum value is 100.
- version string Required
  
  Target version for automatic agent upgrade
space_ids array[string]
supports_agentless boolean | null

Indicates whether the agent policy supports agentless integrations.

Default value is false.
unenroll_timeout number

Minimum value is 0.

Responses

200 application/json
Hide response attribute Show response attribute object
- item object Required
  
  Additional properties are NOT allowed.
  
  Hide item attributes Show item attributes object
  
  advanced_settings object
  
  Additional properties are NOT allowed.
  
  Hide advanced_settings attributes Show advanced_settings attributes object
  
  agent_download_target_directory
  
  agent_download_timeout
  
  agent_limits_go_max_procs
  
  agent_logging_files_interval
  
  agent_logging_files_keepfiles
  
  agent_logging_files_rotateeverybytes
  
  agent_logging_level
  
  agent_logging_metrics_period
  
  agent_logging_to_files
  
  agent_features array[object]
  
  Hide agent_features attributes Show agent_features attributes object
  
  enabled boolean Required
  
  name string Required
  
  agentless object
  
  Additional properties are NOT allowed.
  
  Hide agentless attributes Show agentless attributes object
  
  cloud_connectors object
  
  Additional properties are NOT allowed.
  
  Hide cloud_connectors attributes Show cloud_connectors attributes object
  
  enabled boolean Required
  
  target_csp string
  
  resources object
  
  Additional properties are NOT allowed.
  
  Hide resources attribute Show resources attribute object
  
  requests object
  
  Additional properties are NOT allowed.
  
  Hide requests attributes Show requests attributes object
  
  cpu string
  
  memory string
  
  agents number
  
  data_output_id string | null
  
  description string
  
  download_source_id string | null
  
  fleet_server_host_id string | null
  
  global_data_tags array[object]
  
  User defined data tags that are added to all of the inputs. The values can be strings or numbers.
  
  Hide global_data_tags attributes Show global_data_tags attributes object
  
  name string Required
  
  value string | number Required
  
  Any of:
  string-1 string number-2 number
  
  has_fleet_server boolean
  
  id string Required
  
  inactivity_timeout number
  
  Minimum value is 0. Default value is 1209600.
  
  is_default boolean
  
  is_default_fleet_server boolean
  
  is_managed boolean Required
  
  is_preconfigured boolean
  
  is_protected boolean Required
  
  Indicates whether the agent policy has tamper protection enabled. Default false.
  
  keep_monitoring_alive boolean | null
  
  When set to true, monitoring will be enabled but logs/metrics collection will be disabled
  
  Default value is false.
  
  monitoring_diagnostics object
  
  Additional properties are NOT allowed.
  
  Hide monitoring_diagnostics attributes Show monitoring_diagnostics attributes object
  
  limit object
  
  Additional properties are NOT allowed.
  
  Hide limit attributes Show limit attributes object
  
  burst number
  
  interval string
  
  uploader object
  
  Additional properties are NOT allowed.
  
  Hide uploader attributes Show uploader attributes object
  
  init_dur string
  
  max_dur string
  
  max_retries number
  
  monitoring_enabled array[string]
  
  Values are logs, metrics, or traces.
  
  monitoring_http object
  
  Additional properties are NOT allowed.
  
  Hide monitoring_http attributes Show monitoring_http attributes object
  
  buffer object
  
  Additional properties are NOT allowed.
  
  Hide buffer attribute Show buffer attribute object
  
  enabled boolean
  
  Default value is false.
  
  enabled boolean
  
  host string
  
  port number
  
  Minimum value is 0, maximum value is 65353.
  
  monitoring_output_id string | null
  
  monitoring_pprof_enabled boolean
  
  name string Required
  
  Minimum length is 1.
  
  namespace string Required
  
  Minimum length is 1.
  
  overrides object | null
  
  Override settings that are defined in the agent policy. Input settings cannot be overridden. The override option should be used only in unusual circumstances and not as a routine procedure.
  
  Additional properties are allowed.
  
  package_policies array[string] | array[object]
  
  Any of:
  array-1 array[string] array-2 array[object]
  
  This field is present only when retrieving a single agent policy, or when retrieving a list of agent policies with the ?full=true parameter
  
  Hide attributes Show attributes object
  
  additional_datastreams_permissions array[string] | null
  
  Additional datastream permissions, that will be added to the agent policy.
  
  agents number
  
  created_at string Required
  
  created_by string Required
  
  description string
  
  Package policy description
  
  elasticsearch object
  
  Additional properties are allowed.
  
  Hide elasticsearch attribute Show elasticsearch attribute object
  
  privileges object
  
  Additional properties are allowed.
  
  Hide privileges attribute Show privileges attribute object
  
  cluster array[string]
  
  enabled boolean Required
  
  id string Required
  
  inputs array[object] | object Required
  
  Any of:
  array-1 array[object] object-2 object
  
  Hide attributes Show attributes object
  
  config object
  
  Package variable (see integration documentation for more information)
  
  Hide config attribute Show config attribute object
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  frozen boolean
  
  type string
  
  enabled boolean Required
  
  id string
  
  keep_enabled boolean
  
  policy_template string
  
  streams array[object] Required
  
  Hide streams attributes Show streams attributes object
  
  config object
  
  Package variable (see integration documentation for more information)
  
  Hide config attribute Show config attribute object
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  frozen boolean
  
  type string
  
  data_stream object Required
  
  Additional properties are NOT allowed.
  
  Hide data_stream attributes Show data_stream attributes object
  
  dataset string Required
  
  elasticsearch object
  
  Additional properties are NOT allowed.
  
  Hide elasticsearch attributes Show elasticsearch attributes object
  
  dynamic_dataset boolean
  
  dynamic_namespace boolean
  
  privileges object
  
  Additional properties are NOT allowed.
  
  Hide privileges attribute Show privileges attribute object
  
  indices array[string]
  
  type string Required
  
  enabled boolean Required
  
  id string
  
  keep_enabled boolean
  
  release string
  
  Values are ga, beta, or experimental.
  
  vars object
  
  Package variable (see integration documentation for more information)
  
  Hide vars attribute Show vars attribute object
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  frozen boolean
  
  type string
  
  type string Required
  
  vars object
  
  Package variable (see integration documentation for more information)
  
  Hide vars attribute Show vars attribute object
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  frozen boolean
  
  type string
  
  Package policy inputs (see integration documentation to know what inputs are available)
  
  Hide attribute Show attribute
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  enabled boolean
  
  enable or disable that input, (default to true)
  
  streams object
  
  Input streams (see integration documentation to know what streams are available)
  
  Hide streams attribute Show streams attribute object
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  enabled boolean
  
  enable or disable that stream, (default to true)
  
  vars object
  
  Input/stream level variable (see integration documentation for more information)
  
  vars object
  
  Input/stream level variable (see integration documentation for more information)
  
  is_managed boolean
  
  name string Required
  
  Package policy name (should be unique)
  
  namespace string
  
  The package policy namespace. Leave blank to inherit the agent policy's namespace.
  
  output_id string | null
  
  overrides object | null
  
  Override settings that are defined in the package policy. The override option should be used only in unusual circumstances and not as a routine procedure.
  
  Additional properties are NOT allowed.
  
  Hide overrides attribute Show overrides attribute object | null
  
  inputs object
  
  Additional properties are allowed.
  
  package object
  
  Additional properties are NOT allowed.
  
  Hide package attributes Show package attributes object
  
  experimental_data_stream_features array[object]
  
  Hide experimental_data_stream_features attributes Show experimental_data_stream_features attributes object
  
  data_stream string Required
  
  features object Required
  
  Additional properties are NOT allowed.
  
  Hide features attributes Show features attributes object
  
  doc_value_only_numeric boolean
  
  doc_value_only_other boolean
  
  synthetic_source boolean
  
  tsdb boolean
  
  name string Required
  
  Package name
  
  requires_root boolean
  
  title string
  
  version string Required
  
  Package version
  
  policy_id string | null Deprecated
  
  Agent policy ID where that package policy will be added
  
  policy_ids array[string]
  
  Agent policy IDs where that package policy will be added
  
  revision number Required
  
  secret_references array[object]
  
  Hide secret_references attribute Show secret_references attribute object
  
  id string Required
  
  spaceIds array[string]
  
  supports_agentless boolean | null
  
  Indicates whether the package policy belongs to an agentless agent policy.
  
  Default value is false.
  
  updated_at string Required
  
  updated_by string Required
  
  vars object
  
  Any of:
  object-1 object object-2 object
  
  Package variable (see integration documentation for more information)
  
  Hide attribute Show attribute
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  frozen boolean
  
  type string
  
  version string
  
  required_versions array[object] | null
  
  Hide required_versions attributes Show required_versions attributes object
  
  percentage number Required
  
  Target percentage of agents to auto upgrade
  
  Minimum value is 0, maximum value is 100.
  
  version string Required
  
  Target version for automatic agent upgrade
  
  revision number Required
  
  schema_version string
  
  space_ids array[string]
  
  status string Required
  
  Values are active or inactive.
  
  supports_agentless boolean | null
  
  Indicates whether the agent policy supports agentless integrations.
  
  Default value is false.
  
  unenroll_timeout number
  
  Minimum value is 0.
  
  unprivileged_agents number
  
  updated_at string Required
  
  updated_by string Required
  
  version string
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

POST /api/fleet/agent_policies

curl \
 --request POST 'https://<KIBANA_URL>/api/fleet/agent_policies' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"advanced_settings":{},"agent_features":[{"enabled":true,"name":"string"}],"agentless":{"cloud_connectors":{"enabled":true,"target_csp":"string"},"resources":{"requests":{"cpu":"string","memory":"string"}}},"data_output_id":"string","description":"string","download_source_id":"string","fleet_server_host_id":"string","force":true,"global_data_tags":[{"name":"string","value":"string"}],"has_fleet_server":true,"id":"string","inactivity_timeout":1209600,"is_default":true,"is_default_fleet_server":true,"is_managed":true,"is_protected":true,"keep_monitoring_alive":false,"monitoring_diagnostics":{"limit":{"burst":42.0,"interval":"string"},"uploader":{"init_dur":"string","max_dur":"string","max_retries":42.0}},"monitoring_enabled":["logs"],"monitoring_http":{"buffer":{"enabled":false},"enabled":true,"host":"string","port":42.0},"monitoring_output_id":"string","monitoring_pprof_enabled":true,"name":"string","namespace":"string","overrides":{},"required_versions":[{"percentage":42.0,"version":"string"}],"space_ids":["string"],"supports_agentless":false,"unenroll_timeout":42.0}'

Bulk get agent policies

POST /api/fleet/agent_policies/_bulk_get

[Required authorization] Route required privileges: fleet-agent-policies-read OR fleet-agents-read OR fleet-setup.

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

Query parameters

format string

Values are simplified or legacy.

application/json

Body

full boolean

get full policies with package policies populated
ids array[string] Required

list of package policy ids
ignoreMissing boolean

Responses

200 application/json
Hide response attribute Show response attribute object
- items array[object] Required
  
  Hide items attributes Show items attributes object
  
  advanced_settings object
  
  Additional properties are NOT allowed.
  
  Hide advanced_settings attributes Show advanced_settings attributes object
  
  agent_download_target_directory
  
  agent_download_timeout
  
  agent_limits_go_max_procs
  
  agent_logging_files_interval
  
  agent_logging_files_keepfiles
  
  agent_logging_files_rotateeverybytes
  
  agent_logging_level
  
  agent_logging_metrics_period
  
  agent_logging_to_files
  
  agent_features array[object]
  
  Hide agent_features attributes Show agent_features attributes object
  
  enabled boolean Required
  
  name string Required
  
  agentless object
  
  Additional properties are NOT allowed.
  
  Hide agentless attributes Show agentless attributes object
  
  cloud_connectors object
  
  Additional properties are NOT allowed.
  
  Hide cloud_connectors attributes Show cloud_connectors attributes object
  
  enabled boolean Required
  
  target_csp string
  
  resources object
  
  Additional properties are NOT allowed.
  
  Hide resources attribute Show resources attribute object
  
  requests object
  
  Additional properties are NOT allowed.
  
  Hide requests attributes Show requests attributes object
  
  cpu string
  
  memory string
  
  agents number
  
  data_output_id string | null
  
  description string
  
  download_source_id string | null
  
  fleet_server_host_id string | null
  
  global_data_tags array[object]
  
  User defined data tags that are added to all of the inputs. The values can be strings or numbers.
  
  Hide global_data_tags attributes Show global_data_tags attributes object
  
  name string Required
  
  value string | number Required
  
  Any of:
  string-1 string number-2 number
  
  has_fleet_server boolean
  
  id string Required
  
  inactivity_timeout number
  
  Minimum value is 0. Default value is 1209600.
  
  is_default boolean
  
  is_default_fleet_server boolean
  
  is_managed boolean Required
  
  is_preconfigured boolean
  
  is_protected boolean Required
  
  Indicates whether the agent policy has tamper protection enabled. Default false.
  
  keep_monitoring_alive boolean | null
  
  When set to true, monitoring will be enabled but logs/metrics collection will be disabled
  
  Default value is false.
  
  monitoring_diagnostics object
  
  Additional properties are NOT allowed.
  
  Hide monitoring_diagnostics attributes Show monitoring_diagnostics attributes object
  
  limit object
  
  Additional properties are NOT allowed.
  
  Hide limit attributes Show limit attributes object
  
  burst number
  
  interval string
  
  uploader object
  
  Additional properties are NOT allowed.
  
  Hide uploader attributes Show uploader attributes object
  
  init_dur string
  
  max_dur string
  
  max_retries number
  
  monitoring_enabled array[string]
  
  Values are logs, metrics, or traces.
  
  monitoring_http object
  
  Additional properties are NOT allowed.
  
  Hide monitoring_http attributes Show monitoring_http attributes object
  
  buffer object
  
  Additional properties are NOT allowed.
  
  Hide buffer attribute Show buffer attribute object
  
  enabled boolean
  
  Default value is false.
  
  enabled boolean
  
  host string
  
  port number
  
  Minimum value is 0, maximum value is 65353.
  
  monitoring_output_id string | null
  
  monitoring_pprof_enabled boolean
  
  name string Required
  
  Minimum length is 1.
  
  namespace string Required
  
  Minimum length is 1.
  
  overrides object | null
  
  Override settings that are defined in the agent policy. Input settings cannot be overridden. The override option should be used only in unusual circumstances and not as a routine procedure.
  
  Additional properties are allowed.
  
  package_policies array[string] | array[object]
  
  Any of:
  array-1 array[string] array-2 array[object]
  
  This field is present only when retrieving a single agent policy, or when retrieving a list of agent policies with the ?full=true parameter
  
  Hide attributes Show attributes object
  
  additional_datastreams_permissions array[string] | null
  
  Additional datastream permissions, that will be added to the agent policy.
  
  agents number
  
  created_at string Required
  
  created_by string Required
  
  description string
  
  Package policy description
  
  elasticsearch object
  
  Additional properties are allowed.
  
  Hide elasticsearch attribute Show elasticsearch attribute object
  
  privileges object
  
  Additional properties are allowed.
  
  Hide privileges attribute Show privileges attribute object
  
  cluster array[string]
  
  enabled boolean Required
  
  id string Required
  
  inputs array[object] | object Required
  
  Any of:
  array-1 array[object] object-2 object
  
  Hide attributes Show attributes object
  
  config object
  
  Package variable (see integration documentation for more information)
  
  Hide config attribute Show config attribute object
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  frozen boolean
  
  type string
  
  enabled boolean Required
  
  id string
  
  keep_enabled boolean
  
  policy_template string
  
  streams array[object] Required
  
  Hide streams attributes Show streams attributes object
  
  config object
  
  Package variable (see integration documentation for more information)
  
  Hide config attribute Show config attribute object
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  frozen boolean
  
  type string
  
  data_stream object Required
  
  Additional properties are NOT allowed.
  
  Hide data_stream attributes Show data_stream attributes object
  
  dataset string Required
  
  elasticsearch object
  
  Additional properties are NOT allowed.
  
  Hide elasticsearch attributes Show elasticsearch attributes object
  
  dynamic_dataset boolean
  
  dynamic_namespace boolean
  
  privileges object
  
  Additional properties are NOT allowed.
  
  Hide privileges attribute Show privileges attribute object
  
  indices array[string]
  
  type string Required
  
  enabled boolean Required
  
  id string
  
  keep_enabled boolean
  
  release string
  
  Values are ga, beta, or experimental.
  
  vars object
  
  Package variable (see integration documentation for more information)
  
  Hide vars attribute Show vars attribute object
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  frozen boolean
  
  type string
  
  type string Required
  
  vars object
  
  Package variable (see integration documentation for more information)
  
  Hide vars attribute Show vars attribute object
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  frozen boolean
  
  type string
  
  Package policy inputs (see integration documentation to know what inputs are available)
  
  Hide attribute Show attribute
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  enabled boolean
  
  enable or disable that input, (default to true)
  
  streams object
  
  Input streams (see integration documentation to know what streams are available)
  
  Hide streams attribute Show streams attribute object
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  enabled boolean
  
  enable or disable that stream, (default to true)
  
  vars object
  
  Input/stream level variable (see integration documentation for more information)
  
  vars object
  
  Input/stream level variable (see integration documentation for more information)
  
  is_managed boolean
  
  name string Required
  
  Package policy name (should be unique)
  
  namespace string
  
  The package policy namespace. Leave blank to inherit the agent policy's namespace.
  
  output_id string | null
  
  overrides object | null
  
  Override settings that are defined in the package policy. The override option should be used only in unusual circumstances and not as a routine procedure.
  
  Additional properties are NOT allowed.
  
  Hide overrides attribute Show overrides attribute object | null
  
  inputs object
  
  Additional properties are allowed.
  
  package object
  
  Additional properties are NOT allowed.
  
  Hide package attributes Show package attributes object
  
  experimental_data_stream_features array[object]
  
  Hide experimental_data_stream_features attributes Show experimental_data_stream_features attributes object
  
  data_stream string Required
  
  features object Required
  
  Additional properties are NOT allowed.
  
  Hide features attributes Show features attributes object
  
  doc_value_only_numeric boolean
  
  doc_value_only_other boolean
  
  synthetic_source boolean
  
  tsdb boolean
  
  name string Required
  
  Package name
  
  requires_root boolean
  
  title string
  
  version string Required
  
  Package version
  
  policy_id string | null Deprecated
  
  Agent policy ID where that package policy will be added
  
  policy_ids array[string]
  
  Agent policy IDs where that package policy will be added
  
  revision number Required
  
  secret_references array[object]
  
  Hide secret_references attribute Show secret_references attribute object
  
  id string Required
  
  spaceIds array[string]
  
  supports_agentless boolean | null
  
  Indicates whether the package policy belongs to an agentless agent policy.
  
  Default value is false.
  
  updated_at string Required
  
  updated_by string Required
  
  vars object
  
  Any of:
  object-1 object object-2 object
  
  Package variable (see integration documentation for more information)
  
  Hide attribute Show attribute
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  frozen boolean
  
  type string
  
  version string
  
  required_versions array[object] | null
  
  Hide required_versions attributes Show required_versions attributes object
  
  percentage number Required
  
  Target percentage of agents to auto upgrade
  
  Minimum value is 0, maximum value is 100.
  
  version string Required
  
  Target version for automatic agent upgrade
  
  revision number Required
  
  schema_version string
  
  space_ids array[string]
  
  status string Required
  
  Values are active or inactive.
  
  supports_agentless boolean | null
  
  Indicates whether the agent policy supports agentless integrations.
  
  Default value is false.
  
  unenroll_timeout number
  
  Minimum value is 0.
  
  unprivileged_agents number
  
  updated_at string Required
  
  updated_by string Required
  
  version string
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

POST /api/fleet/agent_policies/_bulk_get

curl \
 --request POST 'https://<KIBANA_URL>/api/fleet/agent_policies/_bulk_get' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"full":true,"ids":["string"],"ignoreMissing":true}'

Get an agent policy

GET /api/fleet/agent_policies/{agentPolicyId}

Get an agent policy by ID.

[Required authorization] Route required privileges: fleet-agent-policies-read OR fleet-agents-read OR fleet-setup.

Path parameters

agentPolicyId string Required

Query parameters

format string

Values are simplified or legacy.

Responses

200 application/json
Hide response attribute Show response attribute object
- item object Required
  
  Additional properties are NOT allowed.
  
  Hide item attributes Show item attributes object
  
  advanced_settings object
  
  Additional properties are NOT allowed.
  
  Hide advanced_settings attributes Show advanced_settings attributes object
  
  agent_download_target_directory
  
  agent_download_timeout
  
  agent_limits_go_max_procs
  
  agent_logging_files_interval
  
  agent_logging_files_keepfiles
  
  agent_logging_files_rotateeverybytes
  
  agent_logging_level
  
  agent_logging_metrics_period
  
  agent_logging_to_files
  
  agent_features array[object]
  
  Hide agent_features attributes Show agent_features attributes object
  
  enabled boolean Required
  
  name string Required
  
  agentless object
  
  Additional properties are NOT allowed.
  
  Hide agentless attributes Show agentless attributes object
  
  cloud_connectors object
  
  Additional properties are NOT allowed.
  
  Hide cloud_connectors attributes Show cloud_connectors attributes object
  
  enabled boolean Required
  
  target_csp string
  
  resources object
  
  Additional properties are NOT allowed.
  
  Hide resources attribute Show resources attribute object
  
  requests object
  
  Additional properties are NOT allowed.
  
  Hide requests attributes Show requests attributes object
  
  cpu string
  
  memory string
  
  agents number
  
  data_output_id string | null
  
  description string
  
  download_source_id string | null
  
  fleet_server_host_id string | null
  
  global_data_tags array[object]
  
  User defined data tags that are added to all of the inputs. The values can be strings or numbers.
  
  Hide global_data_tags attributes Show global_data_tags attributes object
  
  name string Required
  
  value string | number Required
  
  Any of:
  string-1 string number-2 number
  
  has_fleet_server boolean
  
  id string Required
  
  inactivity_timeout number
  
  Minimum value is 0. Default value is 1209600.
  
  is_default boolean
  
  is_default_fleet_server boolean
  
  is_managed boolean Required
  
  is_preconfigured boolean
  
  is_protected boolean Required
  
  Indicates whether the agent policy has tamper protection enabled. Default false.
  
  keep_monitoring_alive boolean | null
  
  When set to true, monitoring will be enabled but logs/metrics collection will be disabled
  
  Default value is false.
  
  monitoring_diagnostics object
  
  Additional properties are NOT allowed.
  
  Hide monitoring_diagnostics attributes Show monitoring_diagnostics attributes object
  
  limit object
  
  Additional properties are NOT allowed.
  
  Hide limit attributes Show limit attributes object
  
  burst number
  
  interval string
  
  uploader object
  
  Additional properties are NOT allowed.
  
  Hide uploader attributes Show uploader attributes object
  
  init_dur string
  
  max_dur string
  
  max_retries number
  
  monitoring_enabled array[string]
  
  Values are logs, metrics, or traces.
  
  monitoring_http object
  
  Additional properties are NOT allowed.
  
  Hide monitoring_http attributes Show monitoring_http attributes object
  
  buffer object
  
  Additional properties are NOT allowed.
  
  Hide buffer attribute Show buffer attribute object
  
  enabled boolean
  
  Default value is false.
  
  enabled boolean
  
  host string
  
  port number
  
  Minimum value is 0, maximum value is 65353.
  
  monitoring_output_id string | null
  
  monitoring_pprof_enabled boolean
  
  name string Required
  
  Minimum length is 1.
  
  namespace string Required
  
  Minimum length is 1.
  
  overrides object | null
  
  Override settings that are defined in the agent policy. Input settings cannot be overridden. The override option should be used only in unusual circumstances and not as a routine procedure.
  
  Additional properties are allowed.
  
  package_policies array[string] | array[object]
  
  Any of:
  array-1 array[string] array-2 array[object]
  
  This field is present only when retrieving a single agent policy, or when retrieving a list of agent policies with the ?full=true parameter
  
  Hide attributes Show attributes object
  
  additional_datastreams_permissions array[string] | null
  
  Additional datastream permissions, that will be added to the agent policy.
  
  agents number
  
  created_at string Required
  
  created_by string Required
  
  description string
  
  Package policy description
  
  elasticsearch object
  
  Additional properties are allowed.
  
  Hide elasticsearch attribute Show elasticsearch attribute object
  
  privileges object
  
  Additional properties are allowed.
  
  Hide privileges attribute Show privileges attribute object
  
  cluster array[string]
  
  enabled boolean Required
  
  id string Required
  
  inputs array[object] | object Required
  
  Any of:
  array-1 array[object] object-2 object
  
  Hide attributes Show attributes object
  
  config object
  
  Package variable (see integration documentation for more information)
  
  Hide config attribute Show config attribute object
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  frozen boolean
  
  type string
  
  enabled boolean Required
  
  id string
  
  keep_enabled boolean
  
  policy_template string
  
  streams array[object] Required
  
  Hide streams attributes Show streams attributes object
  
  config object
  
  Package variable (see integration documentation for more information)
  
  Hide config attribute Show config attribute object
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  frozen boolean
  
  type string
  
  data_stream object Required
  
  Additional properties are NOT allowed.
  
  Hide data_stream attributes Show data_stream attributes object
  
  dataset string Required
  
  elasticsearch object
  
  Additional properties are NOT allowed.
  
  Hide elasticsearch attributes Show elasticsearch attributes object
  
  dynamic_dataset boolean
  
  dynamic_namespace boolean
  
  privileges object
  
  Additional properties are NOT allowed.
  
  Hide privileges attribute Show privileges attribute object
  
  indices array[string]
  
  type string Required
  
  enabled boolean Required
  
  id string
  
  keep_enabled boolean
  
  release string
  
  Values are ga, beta, or experimental.
  
  vars object
  
  Package variable (see integration documentation for more information)
  
  Hide vars attribute Show vars attribute object
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  frozen boolean
  
  type string
  
  type string Required
  
  vars object
  
  Package variable (see integration documentation for more information)
  
  Hide vars attribute Show vars attribute object
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  frozen boolean
  
  type string
  
  Package policy inputs (see integration documentation to know what inputs are available)
  
  Hide attribute Show attribute
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  enabled boolean
  
  enable or disable that input, (default to true)
  
  streams object
  
  Input streams (see integration documentation to know what streams are available)
  
  Hide streams attribute Show streams attribute object
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  enabled boolean
  
  enable or disable that stream, (default to true)
  
  vars object
  
  Input/stream level variable (see integration documentation for more information)
  
  vars object
  
  Input/stream level variable (see integration documentation for more information)
  
  is_managed boolean
  
  name string Required
  
  Package policy name (should be unique)
  
  namespace string
  
  The package policy namespace. Leave blank to inherit the agent policy's namespace.
  
  output_id string | null
  
  overrides object | null
  
  Override settings that are defined in the package policy. The override option should be used only in unusual circumstances and not as a routine procedure.
  
  Additional properties are NOT allowed.
  
  Hide overrides attribute Show overrides attribute object | null
  
  inputs object
  
  Additional properties are allowed.
  
  package object
  
  Additional properties are NOT allowed.
  
  Hide package attributes Show package attributes object
  
  experimental_data_stream_features array[object]
  
  Hide experimental_data_stream_features attributes Show experimental_data_stream_features attributes object
  
  data_stream string Required
  
  features object Required
  
  Additional properties are NOT allowed.
  
  Hide features attributes Show features attributes object
  
  doc_value_only_numeric boolean
  
  doc_value_only_other boolean
  
  synthetic_source boolean
  
  tsdb boolean
  
  name string Required
  
  Package name
  
  requires_root boolean
  
  title string
  
  version string Required
  
  Package version
  
  policy_id string | null Deprecated
  
  Agent policy ID where that package policy will be added
  
  policy_ids array[string]
  
  Agent policy IDs where that package policy will be added
  
  revision number Required
  
  secret_references array[object]
  
  Hide secret_references attribute Show secret_references attribute object
  
  id string Required
  
  spaceIds array[string]
  
  supports_agentless boolean | null
  
  Indicates whether the package policy belongs to an agentless agent policy.
  
  Default value is false.
  
  updated_at string Required
  
  updated_by string Required
  
  vars object
  
  Any of:
  object-1 object object-2 object
  
  Package variable (see integration documentation for more information)
  
  Hide attribute Show attribute
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  frozen boolean
  
  type string
  
  version string
  
  required_versions array[object] | null
  
  Hide required_versions attributes Show required_versions attributes object
  
  percentage number Required
  
  Target percentage of agents to auto upgrade
  
  Minimum value is 0, maximum value is 100.
  
  version string Required
  
  Target version for automatic agent upgrade
  
  revision number Required
  
  schema_version string
  
  space_ids array[string]
  
  status string Required
  
  Values are active or inactive.
  
  supports_agentless boolean | null
  
  Indicates whether the agent policy supports agentless integrations.
  
  Default value is false.
  
  unenroll_timeout number
  
  Minimum value is 0.
  
  unprivileged_agents number
  
  updated_at string Required
  
  updated_by string Required
  
  version string
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

GET /api/fleet/agent_policies/{agentPolicyId}

curl \
 --request GET 'https://<KIBANA_URL>/api/fleet/agent_policies/{agentPolicyId}' \
 --header "Authorization: $API_KEY"

Update an agent policy

PUT /api/fleet/agent_policies/{agentPolicyId}

Update an agent policy by ID.

[Required authorization] Route required privileges: fleet-agent-policies-all.

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

Path parameters

agentPolicyId string Required

Query parameters

format string

Values are simplified or legacy.

application/json

Body

advanced_settings object

Additional properties are NOT allowed.
Hide advanced_settings attributes Show advanced_settings attributes object
agent_features array[object]
Hide agent_features attributes Show agent_features attributes object
- enabled boolean Required
- name string Required
agentless object

Additional properties are NOT allowed.
Hide agentless attributes Show agentless attributes object
- cloud_connectors object
  
  Additional properties are NOT allowed.
  Hide cloud_connectors attributes Show cloud_connectors attributes object
  
  enabled boolean Required
  
  target_csp string
- resources object
  
  Additional properties are NOT allowed.
  Hide resources attribute Show resources attribute object
  
  requests object
  
  Additional properties are NOT allowed.
  
  Hide requests attributes Show requests attributes object
  
  cpu string
  
  memory string
bumpRevision boolean
data_output_id string | null
description string
download_source_id string | null
fleet_server_host_id string | null
force boolean
global_data_tags array[object]

User defined data tags that are added to all of the inputs. The values can be strings or numbers.
Hide global_data_tags attributes Show global_data_tags attributes object
- name string Required
- value string | number Required
  
  Any of:
  string-1 string number-2 number
has_fleet_server boolean
id string
inactivity_timeout number

Minimum value is 0. Default value is 1209600.
is_default boolean
is_default_fleet_server boolean
is_managed boolean
is_protected boolean
keep_monitoring_alive boolean | null

When set to true, monitoring will be enabled but logs/metrics collection will be disabled

Default value is false.
monitoring_diagnostics object

Additional properties are NOT allowed.
Hide monitoring_diagnostics attributes Show monitoring_diagnostics attributes object
- limit object
  
  Additional properties are NOT allowed.
  Hide limit attributes Show limit attributes object
  
  burst number
  
  interval string
- uploader object
  
  Additional properties are NOT allowed.
  Hide uploader attributes Show uploader attributes object
  
  init_dur string
  
  max_dur string
  
  max_retries number
monitoring_enabled array[string]

Values are logs, metrics, or traces.
monitoring_http object

Additional properties are NOT allowed.
Hide monitoring_http attributes Show monitoring_http attributes object
- buffer object
  
  Additional properties are NOT allowed.
  Hide buffer attribute Show buffer attribute object
  
  enabled boolean
  
  Default value is false.
- enabled boolean
- host string
- port number
  
  Minimum value is 0, maximum value is 65353.
monitoring_output_id string | null
monitoring_pprof_enabled boolean
name string Required

Minimum length is 1.
namespace string Required

Minimum length is 1.
overrides object | null

Override settings that are defined in the agent policy. Input settings cannot be overridden. The override option should be used only in unusual circumstances and not as a routine procedure.

Additional properties are allowed.
required_versions array[object] | null
Hide required_versions attributes Show required_versions attributes object
- percentage number Required
  
  Target percentage of agents to auto upgrade
  
  Minimum value is 0, maximum value is 100.
- version string Required
  
  Target version for automatic agent upgrade
space_ids array[string]
supports_agentless boolean | null

Indicates whether the agent policy supports agentless integrations.

Default value is false.
unenroll_timeout number

Minimum value is 0.

Responses

200 application/json
Hide response attribute Show response attribute object
- item object Required
  
  Additional properties are NOT allowed.
  
  Hide item attributes Show item attributes object
  
  advanced_settings object
  
  Additional properties are NOT allowed.
  
  Hide advanced_settings attributes Show advanced_settings attributes object
  
  agent_download_target_directory
  
  agent_download_timeout
  
  agent_limits_go_max_procs
  
  agent_logging_files_interval
  
  agent_logging_files_keepfiles
  
  agent_logging_files_rotateeverybytes
  
  agent_logging_level
  
  agent_logging_metrics_period
  
  agent_logging_to_files
  
  agent_features array[object]
  
  Hide agent_features attributes Show agent_features attributes object
  
  enabled boolean Required
  
  name string Required
  
  agentless object
  
  Additional properties are NOT allowed.
  
  Hide agentless attributes Show agentless attributes object
  
  cloud_connectors object
  
  Additional properties are NOT allowed.
  
  Hide cloud_connectors attributes Show cloud_connectors attributes object
  
  enabled boolean Required
  
  target_csp string
  
  resources object
  
  Additional properties are NOT allowed.
  
  Hide resources attribute Show resources attribute object
  
  requests object
  
  Additional properties are NOT allowed.
  
  Hide requests attributes Show requests attributes object
  
  cpu string
  
  memory string
  
  agents number
  
  data_output_id string | null
  
  description string
  
  download_source_id string | null
  
  fleet_server_host_id string | null
  
  global_data_tags array[object]
  
  User defined data tags that are added to all of the inputs. The values can be strings or numbers.
  
  Hide global_data_tags attributes Show global_data_tags attributes object
  
  name string Required
  
  value string | number Required
  
  Any of:
  string-1 string number-2 number
  
  has_fleet_server boolean
  
  id string Required
  
  inactivity_timeout number
  
  Minimum value is 0. Default value is 1209600.
  
  is_default boolean
  
  is_default_fleet_server boolean
  
  is_managed boolean Required
  
  is_preconfigured boolean
  
  is_protected boolean Required
  
  Indicates whether the agent policy has tamper protection enabled. Default false.
  
  keep_monitoring_alive boolean | null
  
  When set to true, monitoring will be enabled but logs/metrics collection will be disabled
  
  Default value is false.
  
  monitoring_diagnostics object
  
  Additional properties are NOT allowed.
  
  Hide monitoring_diagnostics attributes Show monitoring_diagnostics attributes object
  
  limit object
  
  Additional properties are NOT allowed.
  
  Hide limit attributes Show limit attributes object
  
  burst number
  
  interval string
  
  uploader object
  
  Additional properties are NOT allowed.
  
  Hide uploader attributes Show uploader attributes object
  
  init_dur string
  
  max_dur string
  
  max_retries number
  
  monitoring_enabled array[string]
  
  Values are logs, metrics, or traces.
  
  monitoring_http object
  
  Additional properties are NOT allowed.
  
  Hide monitoring_http attributes Show monitoring_http attributes object
  
  buffer object
  
  Additional properties are NOT allowed.
  
  Hide buffer attribute Show buffer attribute object
  
  enabled boolean
  
  Default value is false.
  
  enabled boolean
  
  host string
  
  port number
  
  Minimum value is 0, maximum value is 65353.
  
  monitoring_output_id string | null
  
  monitoring_pprof_enabled boolean
  
  name string Required
  
  Minimum length is 1.
  
  namespace string Required
  
  Minimum length is 1.
  
  overrides object | null
  
  Override settings that are defined in the agent policy. Input settings cannot be overridden. The override option should be used only in unusual circumstances and not as a routine procedure.
  
  Additional properties are allowed.
  
  package_policies array[string] | array[object]
  
  Any of:
  array-1 array[string] array-2 array[object]
  
  This field is present only when retrieving a single agent policy, or when retrieving a list of agent policies with the ?full=true parameter
  
  Hide attributes Show attributes object
  
  additional_datastreams_permissions array[string] | null
  
  Additional datastream permissions, that will be added to the agent policy.
  
  agents number
  
  created_at string Required
  
  created_by string Required
  
  description string
  
  Package policy description
  
  elasticsearch object
  
  Additional properties are allowed.
  
  Hide elasticsearch attribute Show elasticsearch attribute object
  
  privileges object
  
  Additional properties are allowed.
  
  Hide privileges attribute Show privileges attribute object
  
  cluster array[string]
  
  enabled boolean Required
  
  id string Required
  
  inputs array[object] | object Required
  
  Any of:
  array-1 array[object] object-2 object
  
  Hide attributes Show attributes object
  
  config object
  
  Package variable (see integration documentation for more information)
  
  Hide config attribute Show config attribute object
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  frozen boolean
  
  type string
  
  enabled boolean Required
  
  id string
  
  keep_enabled boolean
  
  policy_template string
  
  streams array[object] Required
  
  Hide streams attributes Show streams attributes object
  
  config object
  
  Package variable (see integration documentation for more information)
  
  Hide config attribute Show config attribute object
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  frozen boolean
  
  type string
  
  data_stream object Required
  
  Additional properties are NOT allowed.
  
  Hide data_stream attributes Show data_stream attributes object
  
  dataset string Required
  
  elasticsearch object
  
  Additional properties are NOT allowed.
  
  Hide elasticsearch attributes Show elasticsearch attributes object
  
  dynamic_dataset boolean
  
  dynamic_namespace boolean
  
  privileges object
  
  Additional properties are NOT allowed.
  
  Hide privileges attribute Show privileges attribute object
  
  indices array[string]
  
  type string Required
  
  enabled boolean Required
  
  id string
  
  keep_enabled boolean
  
  release string
  
  Values are ga, beta, or experimental.
  
  vars object
  
  Package variable (see integration documentation for more information)
  
  Hide vars attribute Show vars attribute object
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  frozen boolean
  
  type string
  
  type string Required
  
  vars object
  
  Package variable (see integration documentation for more information)
  
  Hide vars attribute Show vars attribute object
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  frozen boolean
  
  type string
  
  Package policy inputs (see integration documentation to know what inputs are available)
  
  Hide attribute Show attribute
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  enabled boolean
  
  enable or disable that input, (default to true)
  
  streams object
  
  Input streams (see integration documentation to know what streams are available)
  
  Hide streams attribute Show streams attribute object
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  enabled boolean
  
  enable or disable that stream, (default to true)
  
  vars object
  
  Input/stream level variable (see integration documentation for more information)
  
  vars object
  
  Input/stream level variable (see integration documentation for more information)
  
  is_managed boolean
  
  name string Required
  
  Package policy name (should be unique)
  
  namespace string
  
  The package policy namespace. Leave blank to inherit the agent policy's namespace.
  
  output_id string | null
  
  overrides object | null
  
  Override settings that are defined in the package policy. The override option should be used only in unusual circumstances and not as a routine procedure.
  
  Additional properties are NOT allowed.
  
  Hide overrides attribute Show overrides attribute object | null
  
  inputs object
  
  Additional properties are allowed.
  
  package object
  
  Additional properties are NOT allowed.
  
  Hide package attributes Show package attributes object
  
  experimental_data_stream_features array[object]
  
  Hide experimental_data_stream_features attributes Show experimental_data_stream_features attributes object
  
  data_stream string Required
  
  features object Required
  
  Additional properties are NOT allowed.
  
  Hide features attributes Show features attributes object
  
  doc_value_only_numeric boolean
  
  doc_value_only_other boolean
  
  synthetic_source boolean
  
  tsdb boolean
  
  name string Required
  
  Package name
  
  requires_root boolean
  
  title string
  
  version string Required
  
  Package version
  
  policy_id string | null Deprecated
  
  Agent policy ID where that package policy will be added
  
  policy_ids array[string]
  
  Agent policy IDs where that package policy will be added
  
  revision number Required
  
  secret_references array[object]
  
  Hide secret_references attribute Show secret_references attribute object
  
  id string Required
  
  spaceIds array[string]
  
  supports_agentless boolean | null
  
  Indicates whether the package policy belongs to an agentless agent policy.
  
  Default value is false.
  
  updated_at string Required
  
  updated_by string Required
  
  vars object
  
  Any of:
  object-1 object object-2 object
  
  Package variable (see integration documentation for more information)
  
  Hide attribute Show attribute
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  frozen boolean
  
  type string
  
  version string
  
  required_versions array[object] | null
  
  Hide required_versions attributes Show required_versions attributes object
  
  percentage number Required
  
  Target percentage of agents to auto upgrade
  
  Minimum value is 0, maximum value is 100.
  
  version string Required
  
  Target version for automatic agent upgrade
  
  revision number Required
  
  schema_version string
  
  space_ids array[string]
  
  status string Required
  
  Values are active or inactive.
  
  supports_agentless boolean | null
  
  Indicates whether the agent policy supports agentless integrations.
  
  Default value is false.
  
  unenroll_timeout number
  
  Minimum value is 0.
  
  unprivileged_agents number
  
  updated_at string Required
  
  updated_by string Required
  
  version string
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

PUT /api/fleet/agent_policies/{agentPolicyId}

curl \
 --request PUT 'https://<KIBANA_URL>/api/fleet/agent_policies/{agentPolicyId}' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"advanced_settings":{},"agent_features":[{"enabled":true,"name":"string"}],"agentless":{"cloud_connectors":{"enabled":true,"target_csp":"string"},"resources":{"requests":{"cpu":"string","memory":"string"}}},"bumpRevision":true,"data_output_id":"string","description":"string","download_source_id":"string","fleet_server_host_id":"string","force":true,"global_data_tags":[{"name":"string","value":"string"}],"has_fleet_server":true,"id":"string","inactivity_timeout":1209600,"is_default":true,"is_default_fleet_server":true,"is_managed":true,"is_protected":true,"keep_monitoring_alive":false,"monitoring_diagnostics":{"limit":{"burst":42.0,"interval":"string"},"uploader":{"init_dur":"string","max_dur":"string","max_retries":42.0}},"monitoring_enabled":["logs"],"monitoring_http":{"buffer":{"enabled":false},"enabled":true,"host":"string","port":42.0},"monitoring_output_id":"string","monitoring_pprof_enabled":true,"name":"string","namespace":"string","overrides":{},"required_versions":[{"percentage":42.0,"version":"string"}],"space_ids":["string"],"supports_agentless":false,"unenroll_timeout":42.0}'

Get auto upgrade agent status

GET /api/fleet/agent_policies/{agentPolicyId}/auto_upgrade_agents_status

Get auto upgrade agent status

[Required authorization] Route required privileges: fleet-agents-read.

Path parameters

agentPolicyId string Required

Responses

200 application/json
Hide response attributes Show response attributes object
- currentVersions array[object] Required
  
  Hide currentVersions attributes Show currentVersions attributes object
  
  agents number Required
  
  failedUpgradeAgents number Required
  
  version string Required
- totalAgents number Required
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

GET /api/fleet/agent_policies/{agentPolicyId}/auto_upgrade_agents_status

curl \
 --request GET 'https://<KIBANA_URL>/api/fleet/agent_policies/{agentPolicyId}/auto_upgrade_agents_status' \
 --header "Authorization: $API_KEY"

Copy an agent policy

POST /api/fleet/agent_policies/{agentPolicyId}/copy

Copy an agent policy by ID.

[Required authorization] Route required privileges: fleet-agent-policies-all.

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

Path parameters

agentPolicyId string Required

Query parameters

format string

Values are simplified or legacy.

application/json

Body

description string
name string Required

Minimum length is 1.

Responses

200 application/json
Hide response attribute Show response attribute object
- item object Required
  
  Additional properties are NOT allowed.
  
  Hide item attributes Show item attributes object
  
  advanced_settings object
  
  Additional properties are NOT allowed.
  
  Hide advanced_settings attributes Show advanced_settings attributes object
  
  agent_download_target_directory
  
  agent_download_timeout
  
  agent_limits_go_max_procs
  
  agent_logging_files_interval
  
  agent_logging_files_keepfiles
  
  agent_logging_files_rotateeverybytes
  
  agent_logging_level
  
  agent_logging_metrics_period
  
  agent_logging_to_files
  
  agent_features array[object]
  
  Hide agent_features attributes Show agent_features attributes object
  
  enabled boolean Required
  
  name string Required
  
  agentless object
  
  Additional properties are NOT allowed.
  
  Hide agentless attributes Show agentless attributes object
  
  cloud_connectors object
  
  Additional properties are NOT allowed.
  
  Hide cloud_connectors attributes Show cloud_connectors attributes object
  
  enabled boolean Required
  
  target_csp string
  
  resources object
  
  Additional properties are NOT allowed.
  
  Hide resources attribute Show resources attribute object
  
  requests object
  
  Additional properties are NOT allowed.
  
  Hide requests attributes Show requests attributes object
  
  cpu string
  
  memory string
  
  agents number
  
  data_output_id string | null
  
  description string
  
  download_source_id string | null
  
  fleet_server_host_id string | null
  
  global_data_tags array[object]
  
  User defined data tags that are added to all of the inputs. The values can be strings or numbers.
  
  Hide global_data_tags attributes Show global_data_tags attributes object
  
  name string Required
  
  value string | number Required
  
  Any of:
  string-1 string number-2 number
  
  has_fleet_server boolean
  
  id string Required
  
  inactivity_timeout number
  
  Minimum value is 0. Default value is 1209600.
  
  is_default boolean
  
  is_default_fleet_server boolean
  
  is_managed boolean Required
  
  is_preconfigured boolean
  
  is_protected boolean Required
  
  Indicates whether the agent policy has tamper protection enabled. Default false.
  
  keep_monitoring_alive boolean | null
  
  When set to true, monitoring will be enabled but logs/metrics collection will be disabled
  
  Default value is false.
  
  monitoring_diagnostics object
  
  Additional properties are NOT allowed.
  
  Hide monitoring_diagnostics attributes Show monitoring_diagnostics attributes object
  
  limit object
  
  Additional properties are NOT allowed.
  
  Hide limit attributes Show limit attributes object
  
  burst number
  
  interval string
  
  uploader object
  
  Additional properties are NOT allowed.
  
  Hide uploader attributes Show uploader attributes object
  
  init_dur string
  
  max_dur string
  
  max_retries number
  
  monitoring_enabled array[string]
  
  Values are logs, metrics, or traces.
  
  monitoring_http object
  
  Additional properties are NOT allowed.
  
  Hide monitoring_http attributes Show monitoring_http attributes object
  
  buffer object
  
  Additional properties are NOT allowed.
  
  Hide buffer attribute Show buffer attribute object
  
  enabled boolean
  
  Default value is false.
  
  enabled boolean
  
  host string
  
  port number
  
  Minimum value is 0, maximum value is 65353.
  
  monitoring_output_id string | null
  
  monitoring_pprof_enabled boolean
  
  name string Required
  
  Minimum length is 1.
  
  namespace string Required
  
  Minimum length is 1.
  
  overrides object | null
  
  Override settings that are defined in the agent policy. Input settings cannot be overridden. The override option should be used only in unusual circumstances and not as a routine procedure.
  
  Additional properties are allowed.
  
  package_policies array[string] | array[object]
  
  Any of:
  array-1 array[string] array-2 array[object]
  
  This field is present only when retrieving a single agent policy, or when retrieving a list of agent policies with the ?full=true parameter
  
  Hide attributes Show attributes object
  
  additional_datastreams_permissions array[string] | null
  
  Additional datastream permissions, that will be added to the agent policy.
  
  agents number
  
  created_at string Required
  
  created_by string Required
  
  description string
  
  Package policy description
  
  elasticsearch object
  
  Additional properties are allowed.
  
  Hide elasticsearch attribute Show elasticsearch attribute object
  
  privileges object
  
  Additional properties are allowed.
  
  Hide privileges attribute Show privileges attribute object
  
  cluster array[string]
  
  enabled boolean Required
  
  id string Required
  
  inputs array[object] | object Required
  
  Any of:
  array-1 array[object] object-2 object
  
  Hide attributes Show attributes object
  
  config object
  
  Package variable (see integration documentation for more information)
  
  Hide config attribute Show config attribute object
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  frozen boolean
  
  type string
  
  enabled boolean Required
  
  id string
  
  keep_enabled boolean
  
  policy_template string
  
  streams array[object] Required
  
  Hide streams attributes Show streams attributes object
  
  config object
  
  Package variable (see integration documentation for more information)
  
  Hide config attribute Show config attribute object
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  frozen boolean
  
  type string
  
  data_stream object Required
  
  Additional properties are NOT allowed.
  
  Hide data_stream attributes Show data_stream attributes object
  
  dataset string Required
  
  elasticsearch object
  
  Additional properties are NOT allowed.
  
  Hide elasticsearch attributes Show elasticsearch attributes object
  
  dynamic_dataset boolean
  
  dynamic_namespace boolean
  
  privileges object
  
  Additional properties are NOT allowed.
  
  Hide privileges attribute Show privileges attribute object
  
  indices array[string]
  
  type string Required
  
  enabled boolean Required
  
  id string
  
  keep_enabled boolean
  
  release string
  
  Values are ga, beta, or experimental.
  
  vars object
  
  Package variable (see integration documentation for more information)
  
  Hide vars attribute Show vars attribute object
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  frozen boolean
  
  type string
  
  type string Required
  
  vars object
  
  Package variable (see integration documentation for more information)
  
  Hide vars attribute Show vars attribute object
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  frozen boolean
  
  type string
  
  Package policy inputs (see integration documentation to know what inputs are available)
  
  Hide attribute Show attribute
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  enabled boolean
  
  enable or disable that input, (default to true)
  
  streams object
  
  Input streams (see integration documentation to know what streams are available)
  
  Hide streams attribute Show streams attribute object
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  enabled boolean
  
  enable or disable that stream, (default to true)
  
  vars object
  
  Input/stream level variable (see integration documentation for more information)
  
  vars object
  
  Input/stream level variable (see integration documentation for more information)
  
  is_managed boolean
  
  name string Required
  
  Package policy name (should be unique)
  
  namespace string
  
  The package policy namespace. Leave blank to inherit the agent policy's namespace.
  
  output_id string | null
  
  overrides object | null
  
  Override settings that are defined in the package policy. The override option should be used only in unusual circumstances and not as a routine procedure.
  
  Additional properties are NOT allowed.
  
  Hide overrides attribute Show overrides attribute object | null
  
  inputs object
  
  Additional properties are allowed.
  
  package object
  
  Additional properties are NOT allowed.
  
  Hide package attributes Show package attributes object
  
  experimental_data_stream_features array[object]
  
  Hide experimental_data_stream_features attributes Show experimental_data_stream_features attributes object
  
  data_stream string Required
  
  features object Required
  
  Additional properties are NOT allowed.
  
  Hide features attributes Show features attributes object
  
  doc_value_only_numeric boolean
  
  doc_value_only_other boolean
  
  synthetic_source boolean
  
  tsdb boolean
  
  name string Required
  
  Package name
  
  requires_root boolean
  
  title string
  
  version string Required
  
  Package version
  
  policy_id string | null Deprecated
  
  Agent policy ID where that package policy will be added
  
  policy_ids array[string]
  
  Agent policy IDs where that package policy will be added
  
  revision number Required
  
  secret_references array[object]
  
  Hide secret_references attribute Show secret_references attribute object
  
  id string Required
  
  spaceIds array[string]
  
  supports_agentless boolean | null
  
  Indicates whether the package policy belongs to an agentless agent policy.
  
  Default value is false.
  
  updated_at string Required
  
  updated_by string Required
  
  vars object
  
  Any of:
  object-1 object object-2 object
  
  Package variable (see integration documentation for more information)
  
  Hide attribute Show attribute
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  frozen boolean
  
  type string
  
  version string
  
  required_versions array[object] | null
  
  Hide required_versions attributes Show required_versions attributes object
  
  percentage number Required
  
  Target percentage of agents to auto upgrade
  
  Minimum value is 0, maximum value is 100.
  
  version string Required
  
  Target version for automatic agent upgrade
  
  revision number Required
  
  schema_version string
  
  space_ids array[string]
  
  status string Required
  
  Values are active or inactive.
  
  supports_agentless boolean | null
  
  Indicates whether the agent policy supports agentless integrations.
  
  Default value is false.
  
  unenroll_timeout number
  
  Minimum value is 0.
  
  unprivileged_agents number
  
  updated_at string Required
  
  updated_by string Required
  
  version string
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

POST /api/fleet/agent_policies/{agentPolicyId}/copy

curl \
 --request POST 'https://<KIBANA_URL>/api/fleet/agent_policies/{agentPolicyId}/copy' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"description":"string","name":"string"}'

Download an agent policy

GET /api/fleet/agent_policies/{agentPolicyId}/download

Download an agent policy by ID.

[Required authorization] Route required privileges: fleet-agent-policies-read AND fleet-setup.

Path parameters

agentPolicyId string Required

Query parameters

download boolean
standalone boolean
kubernetes boolean

Responses

200 application/json
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number
404 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

GET /api/fleet/agent_policies/{agentPolicyId}/download

curl \
 --request GET 'https://<KIBANA_URL>/api/fleet/agent_policies/{agentPolicyId}/download' \
 --header "Authorization: $API_KEY"

Get a full agent policy

GET /api/fleet/agent_policies/{agentPolicyId}/full

Get a full agent policy by ID.

[Required authorization] Route required privileges: fleet-agent-policies-read.

Path parameters

agentPolicyId string Required

Query parameters

download boolean
standalone boolean
kubernetes boolean

Responses

200 application/json
Hide response attribute Show response attribute object
- item string | object Required
  
  Any of:
  string-1 string object-2 object
  
  Hide attributes Show attributes
  
  agent object
  
  Additional properties are NOT allowed.
  
  Hide agent attributes Show agent attributes object
  
  download object Required
  
  Additional properties are NOT allowed.
  
  Hide download attributes Show download attributes object
  
  secrets object
  
  Additional properties are allowed.
  
  Hide secrets attribute Show secrets attribute object
  
  ssl object
  
  Additional properties are allowed.
  
  Hide ssl attribute Show ssl attribute object
  
  key object Required
  
  Additional properties are allowed.
  
  Hide key attribute Show key attribute object
  
  id string
  
  sourceURI string Required
  
  ssl object
  
  Additional properties are NOT allowed.
  
  Hide ssl attributes Show ssl attributes object
  
  certificate string
  
  certificate_authorities array[string]
  
  key string
  
  renegotiation string
  
  verification_mode string
  
  features object Required
  
  Hide features attribute Show features attribute object
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attribute Show * attribute object
  
  enabled boolean Required
  
  limits object
  
  Additional properties are NOT allowed.
  
  Hide limits attribute Show limits attribute object
  
  go_max_procs number
  
  logging object
  
  Additional properties are NOT allowed.
  
  Hide logging attributes Show logging attributes object
  
  files object
  
  Additional properties are NOT allowed.
  
  Hide files attributes Show files attributes object
  
  interval string
  
  keepfiles number
  
  rotateeverybytes number
  
  level string
  
  to_files boolean
  
  monitoring object Required
  
  Additional properties are NOT allowed.
  
  Hide monitoring attributes Show monitoring attributes object
  
  enabled boolean Required
  
  logs boolean Required
  
  metrics boolean Required
  
  namespace string
  
  traces boolean Required
  
  use_output string
  
  protection object
  
  Additional properties are NOT allowed.
  
  Hide protection attributes Show protection attributes object
  
  enabled boolean Required
  
  signing_key string Required
  
  uninstall_token_hash string Required
  
  fleet object
  
  Any of:
  object-1 object object-2 object
  
  Hide attributes Show attributes
  
  hosts array[string] Required
  
  proxy_url string
  
  secrets object
  
  Additional properties are allowed.
  
  Hide secrets attribute Show secrets attribute object
  
  ssl object
  
  Additional properties are allowed.
  
  Hide ssl attribute Show ssl attribute object
  
  key object Required
  
  Additional properties are allowed.
  
  Hide key attribute Show key attribute object
  
  id string
  
  ssl object
  
  Additional properties are NOT allowed.
  
  Hide ssl attributes Show ssl attributes object
  
  certificate string
  
  certificate_authorities array[string]
  
  key string
  
  renegotiation string
  
  verification_mode string
  
  Hide attribute Show attribute
  
  kibana object Required
  
  Additional properties are NOT allowed.
  
  Hide kibana attributes Show kibana attributes object
  
  hosts array[string] Required
  
  path string
  
  protocol string Required
  
  id string Required
  
  inputs array[object] Required
  
  Hide inputs attributes Show inputs attributes object
  
  data_stream object Required
  
  Additional properties are allowed.
  
  Hide data_stream attribute Show data_stream attribute object
  
  namespace string Required
  
  id string Required
  
  meta object
  
  Additional properties are allowed.
  
  Hide meta attribute Show meta attribute object
  
  package object
  
  Additional properties are allowed.
  
  Hide package attributes Show package attributes object
  
  name string Required
  
  version string Required
  
  name string Required
  
  package_policy_id string Required
  
  processors array[object]
  
  Hide processors attribute Show processors attribute object
  
  add_fields object Required
  
  Additional properties are allowed.
  
  Hide add_fields attributes Show add_fields attributes object
  
  fields object Required
  
  target string Required
  
  revision number Required
  
  streams array[object]
  
  Hide streams attributes Show streams attributes object
  
  data_stream object Required
  
  Additional properties are allowed.
  
  Hide data_stream attributes Show data_stream attributes object
  
  dataset string Required
  
  type string
  
  id string Required
  
  type string Required
  
  use_output string Required
  
  namespaces array[string]
  
  output_permissions object
  
  Hide output_permissions attribute Show output_permissions attribute object
  
  * object Additional properties
  
  Additional properties are allowed.
  
  outputs object Required
  
  Hide outputs attribute Show outputs attribute object
  
  * object Additional properties
  
  Additional properties are allowed.
  
  Hide * attributes Show * attributes object
  
  ca_sha256 string | null
  
  hosts array[string]
  
  proxy_url string
  
  type string Required
  
  revision number
  
  secret_references array[object]
  
  Hide secret_references attribute Show secret_references attribute object
  
  id string Required
  
  signed object
  
  Additional properties are NOT allowed.
  
  Hide signed attributes Show signed attributes object
  
  data string Required
  
  signature string Required
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

GET /api/fleet/agent_policies/{agentPolicyId}/full

curl \
 --request GET 'https://<KIBANA_URL>/api/fleet/agent_policies/{agentPolicyId}/full' \
 --header "Authorization: $API_KEY"

Get outputs for an agent policy

GET /api/fleet/agent_policies/{agentPolicyId}/outputs

Get a list of outputs associated with agent policy by policy id.

[Required authorization] Route required privileges: fleet-agent-policies-read AND fleet-settings-read.

Path parameters

agentPolicyId string Required

Responses

200 application/json
Hide response attribute Show response attribute object
- item object Required
  
  Additional properties are NOT allowed.
  
  Hide item attributes Show item attributes object
  
  agentPolicyId string
  
  data object Required
  
  Additional properties are NOT allowed.
  
  Hide data attributes Show data attributes object
  
  integrations array[object]
  
  Hide integrations attributes Show integrations attributes object
  
  id string
  
  integrationPolicyName string
  
  name string
  
  pkgName string
  
  output object Required
  
  Additional properties are NOT allowed.
  
  Hide output attributes Show output attributes object
  
  id string Required
  
  name string Required
  
  monitoring object Required
  
  Additional properties are NOT allowed.
  
  Hide monitoring attribute Show monitoring attribute object
  
  output object Required
  
  Additional properties are NOT allowed.
  
  Hide output attributes Show output attributes object
  
  id string Required
  
  name string Required
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

GET /api/fleet/agent_policies/{agentPolicyId}/outputs

curl \
 --request GET 'https://<KIBANA_URL>/api/fleet/agent_policies/{agentPolicyId}/outputs' \
 --header "Authorization: $API_KEY"

Delete an agent policy

POST /api/fleet/agent_policies/delete

Delete an agent policy by ID.

[Required authorization] Route required privileges: fleet-agent-policies-all.

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

application/json

Body

agentPolicyId string Required
force boolean

bypass validation checks that can prevent agent policy deletion

Responses

200 application/json
Hide response attributes Show response attributes object
- id string Required
- name string Required
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

POST /api/fleet/agent_policies/delete

curl \
 --request POST 'https://<KIBANA_URL>/api/fleet/agent_policies/delete' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"agentPolicyId":"string","force":true}'

Get outputs for agent policies

POST /api/fleet/agent_policies/outputs

Get a list of outputs associated with agent policies.

[Required authorization] Route required privileges: fleet-agent-policies-read AND fleet-settings-read.

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

application/json

Body

ids array[string] Required

list of package policy ids

Responses

200 application/json
Hide response attribute Show response attribute object
- items array[object] Required
  
  Hide items attributes Show items attributes object
  
  agentPolicyId string
  
  data object Required
  
  Additional properties are NOT allowed.
  
  Hide data attributes Show data attributes object
  
  integrations array[object]
  
  Hide integrations attributes Show integrations attributes object
  
  id string
  
  integrationPolicyName string
  
  name string
  
  pkgName string
  
  output object Required
  
  Additional properties are NOT allowed.
  
  Hide output attributes Show output attributes object
  
  id string Required
  
  name string Required
  
  monitoring object Required
  
  Additional properties are NOT allowed.
  
  Hide monitoring attribute Show monitoring attribute object
  
  output object Required
  
  Additional properties are NOT allowed.
  
  Hide output attributes Show output attributes object
  
  id string Required
  
  name string Required
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

POST /api/fleet/agent_policies/outputs

curl \
 --request POST 'https://<KIBANA_URL>/api/fleet/agent_policies/outputs' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"ids":["string"]}'

Get a full K8s agent manifest

GET /api/fleet/kubernetes

[Required authorization] Route required privileges: fleet-agent-policies-read AND fleet-setup.

Query parameters

download boolean
fleetServer string
enrolToken string

Responses

200 application/json
Hide response attribute Show response attribute object
- item string Required
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

GET /api/fleet/kubernetes

curl \
 --request GET 'https://<KIBANA_URL>/api/fleet/kubernetes' \
 --header "Authorization: $API_KEY"

Download an agent manifest

GET /api/fleet/kubernetes/download

[Required authorization] Route required privileges: fleet-agent-policies-read AND fleet-setup.

Query parameters

download boolean
fleetServer string
enrolToken string

Responses

200 application/json
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number
404 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

GET /api/fleet/kubernetes/download

curl \
 --request GET 'https://<KIBANA_URL>/api/fleet/kubernetes/download' \
 --header "Authorization: $API_KEY"

Get an agent status summary

GET /api/fleet/agent_status

Query parameters

policyId string
policyIds array[string] | string
kuery string

Responses

200 application/json
Hide response attribute Show response attribute object
- results object Required
  
  Additional properties are NOT allowed.
  
  Hide results attributes Show results attributes object
  
  active number Required
  
  all number Required
  
  error number Required
  
  events number Required
  
  inactive number Required
  
  offline number Required
  
  online number Required
  
  orphaned number
  
  other number Required
  
  unenrolled number Required
  
  uninstalled number
  
  updating number Required
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

GET /api/fleet/agent_status

curl \
 --request GET 'https://<KIBANA_URL>/api/fleet/agent_status' \
 --header "Authorization: $API_KEY"

Get incoming agent data

GET /api/fleet/agent_status/data

[Required authorization] Route required privileges: fleet-agents-read.

Query parameters

agentsIds array[string] | string Required
pkgName string
pkgVersion string
previewData boolean

Default value is false.

Responses

200 application/json
Hide response attributes Show response attributes object
- dataPreview array Required
- items array[object] Required
  
  Hide items attribute Show items attribute object
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attribute Show * attribute object
  
  data boolean Required
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

GET /api/fleet/agent_status/data

curl \
 --request GET 'https://<KIBANA_URL>/api/fleet/agent_status/data?agentsIds=string' \
 --header "Authorization: $API_KEY"

Get agents

GET /api/fleet/agents

[Required authorization] Route required privileges: fleet-agents-read.

Query parameters

page number
perPage number

Default value is 20.
kuery string
showInactive boolean

Default value is false.
withMetrics boolean

Default value is false.
showUpgradeable boolean

Default value is false.
getStatusSummary boolean

Default value is false.
sortField string
sortOrder string

Values are asc or desc.
searchAfter string
openPit boolean
pitId string
pitKeepAlive string

Responses

200 application/json
Hide response attributes Show response attributes object
- items array[object] Required
  
  Hide items attributes Show items attributes object
  
  access_api_key string
  
  access_api_key_id string
  
  active boolean Required
  
  agent object
  
  Additional properties are allowed.
  
  Hide agent attributes Show agent attributes object
  
  id string Required
  
  version string Required
  
  audit_unenrolled_reason string
  
  components array[object]
  
  Hide components attributes Show components attributes object
  
  id string Required
  
  message string Required
  
  status string Required
  
  Values are STARTING, CONFIGURING, HEALTHY, DEGRADED, FAILED, STOPPING, or STOPPED.
  
  type string Required
  
  units array[object]
  
  Hide units attributes Show units attributes object
  
  id string Required
  
  message string Required
  
  payload object
  
  Additional properties are allowed.
  
  status string Required
  
  Values are STARTING, CONFIGURING, HEALTHY, DEGRADED, FAILED, STOPPING, or STOPPED.
  
  type string Required
  
  Values are input or output.
  
  default_api_key string
  
  default_api_key_history array[object]
  
  Hide default_api_key_history attributes Show default_api_key_history attributes object Deprecated
  
  id string Required
  
  retired_at string Required
  
  default_api_key_id string
  
  enrolled_at string Required
  
  id string Required
  
  last_checkin string
  
  last_checkin_message string
  
  last_checkin_status string
  
  Values are error, online, degraded, updating, or starting.
  
  local_metadata object Required
  
  Additional properties are allowed.
  
  metrics object
  
  Additional properties are NOT allowed.
  
  Hide metrics attributes Show metrics attributes object
  
  cpu_avg number
  
  memory_size_byte_avg number
  
  namespaces array[string]
  
  outputs object
  
  Hide outputs attribute Show outputs attribute object
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  api_key_id string
  
  to_retire_api_key_ids array[object]
  
  Hide to_retire_api_key_ids attributes Show to_retire_api_key_ids attributes object
  
  id string Required
  
  retired_at string Required
  
  type string
  
  packages array[string] Required
  
  policy_id string
  
  policy_revision number | null
  
  sort array
  
  status string
  
  Values are offline, error, online, inactive, enrolling, unenrolling, unenrolled, updating, degraded, uninstalled, or orphaned.
  
  tags array[string]
  
  type string Required
  
  Values are PERMANENT, EPHEMERAL, or TEMPORARY.
  
  unenrolled_at string
  
  unenrollment_started_at string
  
  unhealthy_reason array[string] | null
  
  Values are input, output, or other.
  
  upgrade_attempts array[string] | null
  
  upgrade_details object | null
  
  Additional properties are NOT allowed.
  
  Hide upgrade_details attributes Show upgrade_details attributes object | null
  
  action_id string Required
  
  metadata object
  
  Additional properties are NOT allowed.
  
  Hide metadata attributes Show metadata attributes object
  
  download_percent number
  
  download_rate number
  
  error_msg string
  
  failed_state string
  
  Values are UPG_REQUESTED, UPG_SCHEDULED, UPG_DOWNLOADING, UPG_EXTRACTING, UPG_REPLACING, UPG_RESTARTING, UPG_FAILED, UPG_WATCHING, or UPG_ROLLBACK.
  
  retry_error_msg string
  
  retry_until string
  
  scheduled_at string
  
  state string Required
  
  Values are UPG_REQUESTED, UPG_SCHEDULED, UPG_DOWNLOADING, UPG_EXTRACTING, UPG_REPLACING, UPG_RESTARTING, UPG_FAILED, UPG_WATCHING, or UPG_ROLLBACK.
  
  target_version string Required
  
  upgrade_started_at string | null
  
  upgraded_at string | null
  
  user_provided_metadata object
  
  Additional properties are allowed.
- nextSearchAfter string
- page number Required
- perPage number Required
- pit string
- statusSummary object
  
  Hide statusSummary attribute Show statusSummary attribute object
  
  * number Additional properties
- total number Required
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

GET /api/fleet/agents

curl \
 --request GET 'https://<KIBANA_URL>/api/fleet/agents' \
 --header "Authorization: $API_KEY"

Get agents by action ids

POST /api/fleet/agents

[Required authorization] Route required privileges: fleet-agents-read.

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

application/json

Body

actionIds array[string] Required

Responses

200 application/json
Hide response attribute Show response attribute object
- items array[string] Required
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

POST /api/fleet/agents

curl \
 --request POST 'https://<KIBANA_URL>/api/fleet/agents' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"actionIds":["string"]}'

Get an agent

GET /api/fleet/agents/{agentId}

Get an agent by ID.

[Required authorization] Route required privileges: fleet-agents-read.

Path parameters

agentId string Required

Query parameters

withMetrics boolean

Default value is false.

Responses

200 application/json
Hide response attribute Show response attribute object
- item object Required
  
  Additional properties are NOT allowed.
  
  Hide item attributes Show item attributes object
  
  access_api_key string
  
  access_api_key_id string
  
  active boolean Required
  
  agent object
  
  Additional properties are allowed.
  
  Hide agent attributes Show agent attributes object
  
  id string Required
  
  version string Required
  
  audit_unenrolled_reason string
  
  components array[object]
  
  Hide components attributes Show components attributes object
  
  id string Required
  
  message string Required
  
  status string Required
  
  Values are STARTING, CONFIGURING, HEALTHY, DEGRADED, FAILED, STOPPING, or STOPPED.
  
  type string Required
  
  units array[object]
  
  Hide units attributes Show units attributes object
  
  id string Required
  
  message string Required
  
  payload object
  
  Additional properties are allowed.
  
  status string Required
  
  Values are STARTING, CONFIGURING, HEALTHY, DEGRADED, FAILED, STOPPING, or STOPPED.
  
  type string Required
  
  Values are input or output.
  
  default_api_key string
  
  default_api_key_history array[object]
  
  Hide default_api_key_history attributes Show default_api_key_history attributes object Deprecated
  
  id string Required
  
  retired_at string Required
  
  default_api_key_id string
  
  enrolled_at string Required
  
  id string Required
  
  last_checkin string
  
  last_checkin_message string
  
  last_checkin_status string
  
  Values are error, online, degraded, updating, or starting.
  
  local_metadata object Required
  
  Additional properties are allowed.
  
  metrics object
  
  Additional properties are NOT allowed.
  
  Hide metrics attributes Show metrics attributes object
  
  cpu_avg number
  
  memory_size_byte_avg number
  
  namespaces array[string]
  
  outputs object
  
  Hide outputs attribute Show outputs attribute object
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  api_key_id string
  
  to_retire_api_key_ids array[object]
  
  Hide to_retire_api_key_ids attributes Show to_retire_api_key_ids attributes object
  
  id string Required
  
  retired_at string Required
  
  type string
  
  packages array[string] Required
  
  policy_id string
  
  policy_revision number | null
  
  sort array
  
  status string
  
  Values are offline, error, online, inactive, enrolling, unenrolling, unenrolled, updating, degraded, uninstalled, or orphaned.
  
  tags array[string]
  
  type string Required
  
  Values are PERMANENT, EPHEMERAL, or TEMPORARY.
  
  unenrolled_at string
  
  unenrollment_started_at string
  
  unhealthy_reason array[string] | null
  
  Values are input, output, or other.
  
  upgrade_attempts array[string] | null
  
  upgrade_details object | null
  
  Additional properties are NOT allowed.
  
  Hide upgrade_details attributes Show upgrade_details attributes object | null
  
  action_id string Required
  
  metadata object
  
  Additional properties are NOT allowed.
  
  Hide metadata attributes Show metadata attributes object
  
  download_percent number
  
  download_rate number
  
  error_msg string
  
  failed_state string
  
  Values are UPG_REQUESTED, UPG_SCHEDULED, UPG_DOWNLOADING, UPG_EXTRACTING, UPG_REPLACING, UPG_RESTARTING, UPG_FAILED, UPG_WATCHING, or UPG_ROLLBACK.
  
  retry_error_msg string
  
  retry_until string
  
  scheduled_at string
  
  state string Required
  
  Values are UPG_REQUESTED, UPG_SCHEDULED, UPG_DOWNLOADING, UPG_EXTRACTING, UPG_REPLACING, UPG_RESTARTING, UPG_FAILED, UPG_WATCHING, or UPG_ROLLBACK.
  
  target_version string Required
  
  upgrade_started_at string | null
  
  upgraded_at string | null
  
  user_provided_metadata object
  
  Additional properties are allowed.
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

GET /api/fleet/agents/{agentId}

curl \
 --request GET 'https://<KIBANA_URL>/api/fleet/agents/{agentId}' \
 --header "Authorization: $API_KEY"

Update an agent

PUT /api/fleet/agents/{agentId}

Update an agent by ID.

[Required authorization] Route required privileges: fleet-agents-all.

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

Path parameters

agentId string Required

application/json

Body

tags array[string]
user_provided_metadata object

Additional properties are allowed.

Responses

200 application/json
Hide response attribute Show response attribute object
- item object Required
  
  Additional properties are NOT allowed.
  
  Hide item attributes Show item attributes object
  
  access_api_key string
  
  access_api_key_id string
  
  active boolean Required
  
  agent object
  
  Additional properties are allowed.
  
  Hide agent attributes Show agent attributes object
  
  id string Required
  
  version string Required
  
  audit_unenrolled_reason string
  
  components array[object]
  
  Hide components attributes Show components attributes object
  
  id string Required
  
  message string Required
  
  status string Required
  
  Values are STARTING, CONFIGURING, HEALTHY, DEGRADED, FAILED, STOPPING, or STOPPED.
  
  type string Required
  
  units array[object]
  
  Hide units attributes Show units attributes object
  
  id string Required
  
  message string Required
  
  payload object
  
  Additional properties are allowed.
  
  status string Required
  
  Values are STARTING, CONFIGURING, HEALTHY, DEGRADED, FAILED, STOPPING, or STOPPED.
  
  type string Required
  
  Values are input or output.
  
  default_api_key string
  
  default_api_key_history array[object]
  
  Hide default_api_key_history attributes Show default_api_key_history attributes object Deprecated
  
  id string Required
  
  retired_at string Required
  
  default_api_key_id string
  
  enrolled_at string Required
  
  id string Required
  
  last_checkin string
  
  last_checkin_message string
  
  last_checkin_status string
  
  Values are error, online, degraded, updating, or starting.
  
  local_metadata object Required
  
  Additional properties are allowed.
  
  metrics object
  
  Additional properties are NOT allowed.
  
  Hide metrics attributes Show metrics attributes object
  
  cpu_avg number
  
  memory_size_byte_avg number
  
  namespaces array[string]
  
  outputs object
  
  Hide outputs attribute Show outputs attribute object
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  api_key_id string
  
  to_retire_api_key_ids array[object]
  
  Hide to_retire_api_key_ids attributes Show to_retire_api_key_ids attributes object
  
  id string Required
  
  retired_at string Required
  
  type string
  
  packages array[string] Required
  
  policy_id string
  
  policy_revision number | null
  
  sort array
  
  status string
  
  Values are offline, error, online, inactive, enrolling, unenrolling, unenrolled, updating, degraded, uninstalled, or orphaned.
  
  tags array[string]
  
  type string Required
  
  Values are PERMANENT, EPHEMERAL, or TEMPORARY.
  
  unenrolled_at string
  
  unenrollment_started_at string
  
  unhealthy_reason array[string] | null
  
  Values are input, output, or other.
  
  upgrade_attempts array[string] | null
  
  upgrade_details object | null
  
  Additional properties are NOT allowed.
  
  Hide upgrade_details attributes Show upgrade_details attributes object | null
  
  action_id string Required
  
  metadata object
  
  Additional properties are NOT allowed.
  
  Hide metadata attributes Show metadata attributes object
  
  download_percent number
  
  download_rate number
  
  error_msg string
  
  failed_state string
  
  Values are UPG_REQUESTED, UPG_SCHEDULED, UPG_DOWNLOADING, UPG_EXTRACTING, UPG_REPLACING, UPG_RESTARTING, UPG_FAILED, UPG_WATCHING, or UPG_ROLLBACK.
  
  retry_error_msg string
  
  retry_until string
  
  scheduled_at string
  
  state string Required
  
  Values are UPG_REQUESTED, UPG_SCHEDULED, UPG_DOWNLOADING, UPG_EXTRACTING, UPG_REPLACING, UPG_RESTARTING, UPG_FAILED, UPG_WATCHING, or UPG_ROLLBACK.
  
  target_version string Required
  
  upgrade_started_at string | null
  
  upgraded_at string | null
  
  user_provided_metadata object
  
  Additional properties are allowed.
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

PUT /api/fleet/agents/{agentId}

curl \
 --request PUT 'https://<KIBANA_URL>/api/fleet/agents/{agentId}' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"tags":["string"],"user_provided_metadata":{}}'

Delete an agent

DELETE /api/fleet/agents/{agentId}

Delete an agent by ID.

[Required authorization] Route required privileges: fleet-agents-all.

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

Path parameters

agentId string Required

Responses

200 application/json
Hide response attribute Show response attribute object
- action string Required
  
  Value is deleted.
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

DELETE /api/fleet/agents/{agentId}

curl \
 --request DELETE 'https://<KIBANA_URL>/api/fleet/agents/{agentId}' \
 --header "Authorization: $API_KEY" \
 --header "kbn-xsrf: true"

Get agent uploads

GET /api/fleet/agents/{agentId}/uploads

[Required authorization] Route required privileges: fleet-agents-read.

Path parameters

agentId string Required

Responses

200 application/json
Hide response attribute Show response attribute object
- items array[object] Required
  
  Hide items attributes Show items attributes object
  
  actionId string Required
  
  createTime string Required
  
  error string
  
  filePath string Required
  
  id string Required
  
  name string Required
  
  status string Required
  
  Values are READY, AWAITING_UPLOAD, DELETED, EXPIRED, IN_PROGRESS, or FAILED.
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

GET /api/fleet/agents/{agentId}/uploads

curl \
 --request GET 'https://<KIBANA_URL>/api/fleet/agents/{agentId}/uploads' \
 --header "Authorization: $API_KEY"

Get available agent versions

GET /api/fleet/agents/available_versions

[Required authorization] Route required privileges: fleet-agents-read.

Responses

200 application/json
Hide response attribute Show response attribute object
- items array[string] Required
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

GET /api/fleet/agents/available_versions

curl \
 --request GET 'https://<KIBANA_URL>/api/fleet/agents/available_versions' \
 --header "Authorization: $API_KEY"

Delete an uploaded file

DELETE /api/fleet/agents/files/{fileId}

Delete a file uploaded by an agent.

[Required authorization] Route required privileges: fleet-agents-all.

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

Path parameters

fileId string Required

Responses

200 application/json
Hide response attributes Show response attributes object
- deleted boolean Required
- id string Required
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

DELETE /api/fleet/agents/files/{fileId}

curl \
 --request DELETE 'https://<KIBANA_URL>/api/fleet/agents/files/{fileId}' \
 --header "Authorization: $API_KEY" \
 --header "kbn-xsrf: true"

Get an uploaded file

GET /api/fleet/agents/files/{fileId}/{fileName}

Get a file uploaded by an agent.

[Required authorization] Route required privileges: fleet-agents-read.

Path parameters

fileId string Required
fileName string Required

Responses

200 application/json
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

GET /api/fleet/agents/files/{fileId}/{fileName}

curl \
 --request GET 'https://<KIBANA_URL>/api/fleet/agents/files/{fileId}/{fileName}' \
 --header "Authorization: $API_KEY"

Get agent setup info

GET /api/fleet/agents/setup

[Required authorization] Route required privileges: fleet-agents-read OR fleet-agent-policies-read OR fleet-settings-read OR fleet-setup.

Responses

200 application/json
Hide response attributes Show response attributes object
- is_secrets_storage_enabled boolean
- is_space_awareness_enabled boolean
- isReady boolean Required
- missing_optional_features array[string] Required
  
  Value is encrypted_saved_object_encryption_key_required.
- missing_requirements array[string] Required
  
  Values are security_required, tls_required, api_keys, fleet_admin_user, or fleet_server.
- package_verification_key_id string
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

GET /api/fleet/agents/setup

curl \
 --request GET 'https://<KIBANA_URL>/api/fleet/agents/setup' \
 --header "Authorization: $API_KEY"

Initiate agent setup

POST /api/fleet/agents/setup

[Required authorization] Route required privileges: fleet-agents-read OR fleet-agent-policies-read OR fleet-settings-read OR fleet-setup.

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

Responses

200 application/json
Hide response attributes Show response attributes object
- isInitialized boolean Required
- nonFatalErrors array[object] Required
  
  Hide nonFatalErrors attributes Show nonFatalErrors attributes object
  
  message string Required
  
  name string Required
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

POST /api/fleet/agents/setup

curl \
 --request POST 'https://<KIBANA_URL>/api/fleet/agents/setup' \
 --header "Authorization: $API_KEY" \
 --header "kbn-xsrf: true"

Get agent tags

GET /api/fleet/agents/tags

[Required authorization] Route required privileges: fleet-agents-read.

Query parameters

kuery string
showInactive boolean

Default value is false.

Responses

200 application/json
Hide response attribute Show response attribute object
- items array[string] Required
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

GET /api/fleet/agents/tags

curl \
 --request GET 'https://<KIBANA_URL>/api/fleet/agents/tags' \
 --header "Authorization: $API_KEY"

Bulk get assets

POST /api/fleet/epm/bulk_assets

[Required authorization] Route required privileges: integrations-read OR fleet-setup OR fleet-all.

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

application/json

Body

assetIds array[object] Required
Hide assetIds attributes Show assetIds attributes object
- id string Required
- type string Required

Responses

200 application/json
Hide response attribute Show response attribute object
- items array[object] Required
  
  Hide items attributes Show items attributes object
  
  appLink string
  
  attributes object Required
  
  Additional properties are NOT allowed.
  
  Hide attributes attributes Show attributes attributes object
  
  description string
  
  service string
  
  title string
  
  id string Required
  
  type string Required
  
  updatedAt string
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

POST /api/fleet/epm/bulk_assets

curl \
 --request POST 'https://<KIBANA_URL>/api/fleet/epm/bulk_assets' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"assetIds":[{"id":"string","type":"string"}]}'

Get package categories

GET /api/fleet/epm/categories

[Required authorization] Route required privileges: integrations-read OR fleet-setup OR fleet-all.

Query parameters

prerelease boolean
include_policy_templates boolean

Responses

200 application/json
Hide response attribute Show response attribute object
- items array[object] Required
  
  Hide items attributes Show items attributes object
  
  count number Required
  
  id string Required
  
  parent_id string
  
  parent_title string
  
  title string Required
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

GET /api/fleet/epm/categories

curl \
 --request GET 'https://<KIBANA_URL>/api/fleet/epm/categories' \
 --header "Authorization: $API_KEY"

Create a custom integration

POST /api/fleet/epm/custom_integrations

[Required authorization] Route required privileges: integrations-all AND fleet-agent-policies-all.

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

application/json

Body

datasets array[object] Required
Hide datasets attributes Show datasets attributes object
- name string Required
- type string Required
  
  Values are logs, metrics, traces, synthetics, or profiling.
force boolean
integrationName string Required

Responses

200 application/json
Hide response attributes Show response attributes object
- _meta object Required
  
  Additional properties are NOT allowed.
  
  Hide _meta attribute Show _meta attribute object
  
  install_source string Required
- items array[object] Required
  
  Any of:
  object-1 object object-2 object
  
  Hide attributes Show attributes
  
  id string Required
  
  originId string
  
  type string Required
  
  Any of:
  string-1 string string-2 string
  
  Values are dashboard, lens, visualization, search, index-pattern, map, ml-module, security-rule, csp-rule-template, osquery-pack-asset, osquery-saved-query, or tag.
  
  Hide attributes Show attributes
  
  deferred boolean
  
  id string Required
  
  type string Required
  
  Values are index, index_template, component_template, ingest_pipeline, ilm_policy, data_stream_ilm_policy, transform, or ml_model.
  
  version string
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

POST /api/fleet/epm/custom_integrations

curl \
 --request POST 'https://<KIBANA_URL>/api/fleet/epm/custom_integrations' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"datasets":[{"name":"string","type":"logs"}],"force":true,"integrationName":"string"}'

Update a custom integration

PUT /api/fleet/epm/custom_integrations/{pkgName}

[Required authorization] Route required privileges: fleet-settings-all AND integrations-all.

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

Path parameters

pkgName string Required

application/json

Body

categories array[string]
readMeData string Required

Responses

200
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

PUT /api/fleet/epm/custom_integrations/{pkgName}

curl \
 --request PUT 'https://<KIBANA_URL>/api/fleet/epm/custom_integrations/{pkgName}' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"categories":["string"],"readMeData":"string"}'

Get packages

GET /api/fleet/epm/packages

[Required authorization] Route required privileges: integrations-read OR fleet-setup OR fleet-all.

Query parameters

Responses

200 application/json
Hide response attribute Show response attribute object
- items array[object] Required
  
  Hide items attributes Show items attributes object
  
  categories array[string]
  
  conditions object
  
  Additional properties are allowed.
  
  Hide conditions attributes Show conditions attributes object
  
  elastic object
  
  Additional properties are allowed.
  
  Hide elastic attributes Show elastic attributes object
  
  capabilities array[string]
  
  subscription string
  
  kibana object
  
  Additional properties are allowed.
  
  Hide kibana attribute Show kibana attribute object
  
  version string
  
  data_streams array[object]
  
  Additional properties are allowed.
  
  description string
  
  discovery object
  
  Additional properties are allowed.
  
  Hide discovery attribute Show discovery attribute object
  
  fields array[object]
  
  Hide fields attribute Show fields attribute object
  
  name string Required
  
  download string
  
  format_version string
  
  icons array[object]
  
  Hide icons attributes Show icons attributes object
  
  dark_mode boolean
  
  path string
  
  size string
  
  src string Required
  
  title string
  
  type string
  
  id string Required
  
  installationInfo object
  
  Additional properties are allowed.
  
  Hide installationInfo attributes Show installationInfo attributes object
  
  additional_spaces_installed_kibana object
  
  Hide additional_spaces_installed_kibana attribute Show additional_spaces_installed_kibana attribute object
  
  * array[object] Additional properties
  
  Hide * attributes Show * attributes object
  
  id string Required
  
  originId string
  
  type string Required
  
  Any of:
  string-1 string string-2 string
  
  Values are dashboard, lens, visualization, search, index-pattern, map, ml-module, security-rule, csp-rule-template, osquery-pack-asset, osquery-saved-query, or tag.
  
  created_at string
  
  experimental_data_stream_features array[object]
  
  Hide experimental_data_stream_features attributes Show experimental_data_stream_features attributes object
  
  data_stream string Required
  
  features object Required
  
  Additional properties are allowed.
  
  Hide features attributes Show features attributes object
  
  doc_value_only_numeric boolean
  
  doc_value_only_other boolean
  
  synthetic_source boolean
  
  tsdb boolean
  
  install_format_schema_version string
  
  install_source string Required
  
  Values are registry, upload, bundled, or custom.
  
  install_status string Required
  
  Values are installed, installing, or install_failed.
  
  installed_es array[object] Required
  
  Hide installed_es attributes Show installed_es attributes object
  
  deferred boolean
  
  id string Required
  
  type string Required
  
  Values are index, index_template, component_template, ingest_pipeline, ilm_policy, data_stream_ilm_policy, transform, or ml_model.
  
  version string
  
  installed_kibana array[object] Required
  
  Hide installed_kibana attributes Show installed_kibana attributes object
  
  id string Required
  
  originId string
  
  type string Required
  
  Any of:
  string-1 string string-2 string
  
  Values are dashboard, lens, visualization, search, index-pattern, map, ml-module, security-rule, csp-rule-template, osquery-pack-asset, osquery-saved-query, or tag.
  
  installed_kibana_space_id string
  
  latest_executed_state object
  
  Additional properties are allowed.
  
  Hide latest_executed_state attributes Show latest_executed_state attributes object
  
  error string
  
  name string
  
  started_at string
  
  latest_install_failed_attempts array[object]
  
  Hide latest_install_failed_attempts attributes Show latest_install_failed_attempts attributes object
  
  created_at string Required
  
  error object Required
  
  Additional properties are allowed.
  
  Hide error attributes Show error attributes object
  
  message string Required
  
  name string Required
  
  stack string
  
  target_version string Required
  
  name string Required
  
  namespaces array[string]
  
  type string Required
  
  updated_at string
  
  verification_key_id string | null
  
  verification_status string Required
  
  Values are unverified, verified, or unknown.
  
  version string Required
  
  integration string
  
  internal boolean
  
  latestVersion string
  
  name string Required
  
  owner object
  
  Additional properties are allowed.
  
  Hide owner attributes Show owner attributes object
  
  github string
  
  type string
  
  Values are elastic, partner, or community.
  
  path string
  
  policy_templates array[object]
  
  Additional properties are allowed.
  
  readme string
  
  release string
  
  Values are ga, beta, or experimental.
  
  signature_path string
  
  source object
  
  Additional properties are allowed.
  
  Hide source attribute Show source attribute object
  
  license string Required
  
  status string
  
  title string Required
  
  type string
  
  Any of:
  string-1 string string-2 string string-3 string string-4 string
  
  Value is integration.
  
  vars array[object]
  
  Additional properties are allowed.
  
  version string Required
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

GET /api/fleet/epm/packages

curl \
 --request GET 'https://<KIBANA_URL>/api/fleet/epm/packages' \
 --header "Authorization: $API_KEY"

Install a package by upload

POST /api/fleet/epm/packages

[Required authorization] Route required privileges: integrations-all AND fleet-agent-policies-all.

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

Query parameters

ignoreMappingUpdateErrors boolean

Default value is false.
skipDataStreamRollover boolean

Default value is false.

application/gzip; application/zip

Body

string(binary)

Responses

200 application/gzip; application/zip
Hide response attributes Show response attributes object
- _meta object Required
  
  Additional properties are NOT allowed.
  
  Hide _meta attribute Show _meta attribute object
  
  install_source string Required
- items array[object] Required
  
  Any of:
  object-1 object object-2 object
  
  Hide attributes Show attributes
  
  id string Required
  
  originId string
  
  type string Required
  
  Any of:
  string-1 string string-2 string
  
  Values are dashboard, lens, visualization, search, index-pattern, map, ml-module, security-rule, csp-rule-template, osquery-pack-asset, osquery-saved-query, or tag.
  
  Hide attributes Show attributes
  
  deferred boolean
  
  id string Required
  
  type string Required
  
  Values are index, index_template, component_template, ingest_pipeline, ilm_policy, data_stream_ilm_policy, transform, or ml_model.
  
  version string
400 application/gzip; application/zip
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

POST /api/fleet/epm/packages

curl \
 --request POST 'https://<KIBANA_URL>/api/fleet/epm/packages' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/gzip; application/zip" \
 --header "kbn-xsrf: true" \
 --data-binary '@file'

Bulk install packages

POST /api/fleet/epm/packages/_bulk

[Required authorization] Route required privileges: integrations-all AND fleet-agent-policies-all.

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

Query parameters

prerelease boolean

application/json

Body

force boolean

Default value is false.
packages array[string | object] Required

At least 1 element.
Any of:
string-1 string object-2 object
Hide attributes Show attributes

name string Required

prerelease boolean

version string Required

Responses

200 application/json
Hide response attribute Show response attribute object
- items array[object] Required
  
  Any of:
  object-1 object object-2 object
  
  Hide attributes Show attributes
  
  name string Required
  
  result object Required
  
  Additional properties are NOT allowed.
  
  Hide result attributes Show result attributes object
  
  assets array[object]
  
  Any of:
  object-1 object object-2 object
  
  Hide attributes Show attributes
  
  id string Required
  
  originId string
  
  type string Required
  
  Any of:
  string-1 string string-2 string
  
  Values are dashboard, lens, visualization, search, index-pattern, map, ml-module, security-rule, csp-rule-template, osquery-pack-asset, osquery-saved-query, or tag.
  
  Hide attributes Show attributes
  
  deferred boolean
  
  id string Required
  
  type string Required
  
  Values are index, index_template, component_template, ingest_pipeline, ilm_policy, data_stream_ilm_policy, transform, or ml_model.
  
  version string
  
  installSource string
  
  installType string Required
  
  status string
  
  Values are installed or already_installed.
  
  version string Required
  
  Hide attributes Show attributes
  
  error string Required
  
  Any of:
  string-1 string 2
  
  name string Required
  
  statusCode number Required
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

POST /api/fleet/epm/packages/_bulk

curl \
 --request POST 'https://<KIBANA_URL>/api/fleet/epm/packages/_bulk' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"force":false,"packages":["string"]}'

Get a package

GET /api/fleet/epm/packages/{pkgName}/{pkgVersion}

Path parameters

pkgName string Required
pkgVersion string

Query parameters

ignoreUnverified boolean
prerelease boolean
full boolean
withMetadata boolean

Default value is false.

Responses

200 application/json
Hide response attributes Show response attributes object
- item object Required
  
  Additional properties are allowed.
  
  Hide item attributes Show item attributes object
  
  agent object
  
  Additional properties are NOT allowed.
  
  Hide agent attribute Show agent attribute object
  
  privileges object
  
  Additional properties are NOT allowed.
  
  Hide privileges attribute Show privileges attribute object
  
  root boolean
  
  asset_tags array[object]
  
  Hide asset_tags attributes Show asset_tags attributes object
  
  asset_ids array[string]
  
  asset_types array[string]
  
  text string Required
  
  assets object Required
  
  Additional properties are allowed.
  
  categories array[string]
  
  conditions object
  
  Additional properties are allowed.
  
  Hide conditions attributes Show conditions attributes object
  
  elastic object
  
  Additional properties are allowed.
  
  Hide elastic attributes Show elastic attributes object
  
  capabilities array[string]
  
  subscription string
  
  kibana object
  
  Additional properties are allowed.
  
  Hide kibana attribute Show kibana attribute object
  
  version string
  
  data_streams array[object]
  
  Additional properties are allowed.
  
  description string
  
  discovery object
  
  Additional properties are allowed.
  
  Hide discovery attribute Show discovery attribute object
  
  fields array[object]
  
  Hide fields attribute Show fields attribute object
  
  name string Required
  
  download string
  
  elasticsearch object
  
  Additional properties are allowed.
  
  format_version string
  
  icons array[object]
  
  Hide icons attributes Show icons attributes object
  
  dark_mode boolean
  
  path string
  
  size string
  
  src string Required
  
  title string
  
  type string
  
  installationInfo object
  
  Additional properties are allowed.
  
  Hide installationInfo attributes Show installationInfo attributes object
  
  additional_spaces_installed_kibana object
  
  Hide additional_spaces_installed_kibana attribute Show additional_spaces_installed_kibana attribute object
  
  * array[object] Additional properties
  
  Hide * attributes Show * attributes object
  
  id string Required
  
  originId string
  
  type string Required
  
  Any of:
  string-1 string string-2 string
  
  Values are dashboard, lens, visualization, search, index-pattern, map, ml-module, security-rule, csp-rule-template, osquery-pack-asset, osquery-saved-query, or tag.
  
  created_at string
  
  experimental_data_stream_features array[object]
  
  Hide experimental_data_stream_features attributes Show experimental_data_stream_features attributes object
  
  data_stream string Required
  
  features object Required
  
  Additional properties are allowed.
  
  Hide features attributes Show features attributes object
  
  doc_value_only_numeric boolean
  
  doc_value_only_other boolean
  
  synthetic_source boolean
  
  tsdb boolean
  
  install_format_schema_version string
  
  install_source string Required
  
  Values are registry, upload, bundled, or custom.
  
  install_status string Required
  
  Values are installed, installing, or install_failed.
  
  installed_es array[object] Required
  
  Hide installed_es attributes Show installed_es attributes object
  
  deferred boolean
  
  id string Required
  
  type string Required
  
  Values are index, index_template, component_template, ingest_pipeline, ilm_policy, data_stream_ilm_policy, transform, or ml_model.
  
  version string
  
  installed_kibana array[object] Required
  
  Hide installed_kibana attributes Show installed_kibana attributes object
  
  id string Required
  
  originId string
  
  type string Required
  
  Any of:
  string-1 string string-2 string
  
  Values are dashboard, lens, visualization, search, index-pattern, map, ml-module, security-rule, csp-rule-template, osquery-pack-asset, osquery-saved-query, or tag.
  
  installed_kibana_space_id string
  
  latest_executed_state object
  
  Additional properties are allowed.
  
  Hide latest_executed_state attributes Show latest_executed_state attributes object
  
  error string
  
  name string
  
  started_at string
  
  latest_install_failed_attempts array[object]
  
  Hide latest_install_failed_attempts attributes Show latest_install_failed_attempts attributes object
  
  created_at string Required
  
  error object Required
  
  Additional properties are allowed.
  
  Hide error attributes Show error attributes object
  
  message string Required
  
  name string Required
  
  stack string
  
  target_version string Required
  
  name string Required
  
  namespaces array[string]
  
  type string Required
  
  updated_at string
  
  verification_key_id string | null
  
  verification_status string Required
  
  Values are unverified, verified, or unknown.
  
  version string Required
  
  internal boolean
  
  keepPoliciesUpToDate boolean
  
  latestVersion string
  
  license string
  
  licensePath string
  
  name string Required
  
  notice string
  
  owner object
  
  Additional properties are allowed.
  
  Hide owner attributes Show owner attributes object
  
  github string
  
  type string
  
  Values are elastic, partner, or community.
  
  path string
  
  policy_templates array[object]
  
  Additional properties are allowed.
  
  readme string
  
  release string
  
  Values are ga, beta, or experimental.
  
  screenshots array[object]
  
  Hide screenshots attributes Show screenshots attributes object
  
  dark_mode boolean
  
  path string
  
  size string
  
  src string Required
  
  title string
  
  type string
  
  signature_path string
  
  source object
  
  Additional properties are allowed.
  
  Hide source attribute Show source attribute object
  
  license string Required
  
  status string
  
  title string Required
  
  type string
  
  Any of:
  string-1 string string-2 string string-3 string string-4 string
  
  Value is integration.
  
  vars array[object]
  
  Additional properties are allowed.
  
  version string Required
- metadata object
  
  Additional properties are NOT allowed.
  
  Hide metadata attribute Show metadata attribute object
  
  has_policies boolean Required
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

GET /api/fleet/epm/packages/{pkgName}/{pkgVersion}

curl \
 --request GET 'https://<KIBANA_URL>/api/fleet/epm/packages/{pkgName}/{pkgVersion}' \
 --header "Authorization: $API_KEY"

Update package settings

PUT /api/fleet/epm/packages/{pkgName}/{pkgVersion}

[Required authorization] Route required privileges: integrations-all AND fleet-agent-policies-all.

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

Path parameters

pkgName string Required
pkgVersion string

application/json

Body

keepPoliciesUpToDate boolean Required

Responses

200 application/json
Hide response attribute Show response attribute object
- item object Required
  
  Additional properties are allowed.
  
  Hide item attributes Show item attributes object
  
  agent object
  
  Additional properties are NOT allowed.
  
  Hide agent attribute Show agent attribute object
  
  privileges object
  
  Additional properties are NOT allowed.
  
  Hide privileges attribute Show privileges attribute object
  
  root boolean
  
  asset_tags array[object]
  
  Hide asset_tags attributes Show asset_tags attributes object
  
  asset_ids array[string]
  
  asset_types array[string]
  
  text string Required
  
  assets object Required
  
  Additional properties are allowed.
  
  categories array[string]
  
  conditions object
  
  Additional properties are allowed.
  
  Hide conditions attributes Show conditions attributes object
  
  elastic object
  
  Additional properties are allowed.
  
  Hide elastic attributes Show elastic attributes object
  
  capabilities array[string]
  
  subscription string
  
  kibana object
  
  Additional properties are allowed.
  
  Hide kibana attribute Show kibana attribute object
  
  version string
  
  data_streams array[object]
  
  Additional properties are allowed.
  
  description string
  
  discovery object
  
  Additional properties are allowed.
  
  Hide discovery attribute Show discovery attribute object
  
  fields array[object]
  
  Hide fields attribute Show fields attribute object
  
  name string Required
  
  download string
  
  elasticsearch object
  
  Additional properties are allowed.
  
  format_version string
  
  icons array[object]
  
  Hide icons attributes Show icons attributes object
  
  dark_mode boolean
  
  path string
  
  size string
  
  src string Required
  
  title string
  
  type string
  
  installationInfo object
  
  Additional properties are allowed.
  
  Hide installationInfo attributes Show installationInfo attributes object
  
  additional_spaces_installed_kibana object
  
  Hide additional_spaces_installed_kibana attribute Show additional_spaces_installed_kibana attribute object
  
  * array[object] Additional properties
  
  Hide * attributes Show * attributes object
  
  id string Required
  
  originId string
  
  type string Required
  
  Any of:
  string-1 string string-2 string
  
  Values are dashboard, lens, visualization, search, index-pattern, map, ml-module, security-rule, csp-rule-template, osquery-pack-asset, osquery-saved-query, or tag.
  
  created_at string
  
  experimental_data_stream_features array[object]
  
  Hide experimental_data_stream_features attributes Show experimental_data_stream_features attributes object
  
  data_stream string Required
  
  features object Required
  
  Additional properties are allowed.
  
  Hide features attributes Show features attributes object
  
  doc_value_only_numeric boolean
  
  doc_value_only_other boolean
  
  synthetic_source boolean
  
  tsdb boolean
  
  install_format_schema_version string
  
  install_source string Required
  
  Values are registry, upload, bundled, or custom.
  
  install_status string Required
  
  Values are installed, installing, or install_failed.
  
  installed_es array[object] Required
  
  Hide installed_es attributes Show installed_es attributes object
  
  deferred boolean
  
  id string Required
  
  type string Required
  
  Values are index, index_template, component_template, ingest_pipeline, ilm_policy, data_stream_ilm_policy, transform, or ml_model.
  
  version string
  
  installed_kibana array[object] Required
  
  Hide installed_kibana attributes Show installed_kibana attributes object
  
  id string Required
  
  originId string
  
  type string Required
  
  Any of:
  string-1 string string-2 string
  
  Values are dashboard, lens, visualization, search, index-pattern, map, ml-module, security-rule, csp-rule-template, osquery-pack-asset, osquery-saved-query, or tag.
  
  installed_kibana_space_id string
  
  latest_executed_state object
  
  Additional properties are allowed.
  
  Hide latest_executed_state attributes Show latest_executed_state attributes object
  
  error string
  
  name string
  
  started_at string
  
  latest_install_failed_attempts array[object]
  
  Hide latest_install_failed_attempts attributes Show latest_install_failed_attempts attributes object
  
  created_at string Required
  
  error object Required
  
  Additional properties are allowed.
  
  Hide error attributes Show error attributes object
  
  message string Required
  
  name string Required
  
  stack string
  
  target_version string Required
  
  name string Required
  
  namespaces array[string]
  
  type string Required
  
  updated_at string
  
  verification_key_id string | null
  
  verification_status string Required
  
  Values are unverified, verified, or unknown.
  
  version string Required
  
  internal boolean
  
  keepPoliciesUpToDate boolean
  
  latestVersion string
  
  license string
  
  licensePath string
  
  name string Required
  
  notice string
  
  owner object
  
  Additional properties are allowed.
  
  Hide owner attributes Show owner attributes object
  
  github string
  
  type string
  
  Values are elastic, partner, or community.
  
  path string
  
  policy_templates array[object]
  
  Additional properties are allowed.
  
  readme string
  
  release string
  
  Values are ga, beta, or experimental.
  
  screenshots array[object]
  
  Hide screenshots attributes Show screenshots attributes object
  
  dark_mode boolean
  
  path string
  
  size string
  
  src string Required
  
  title string
  
  type string
  
  signature_path string
  
  source object
  
  Additional properties are allowed.
  
  Hide source attribute Show source attribute object
  
  license string Required
  
  status string
  
  title string Required
  
  type string
  
  Any of:
  string-1 string string-2 string string-3 string string-4 string
  
  Value is integration.
  
  vars array[object]
  
  Additional properties are allowed.
  
  version string Required
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

PUT /api/fleet/epm/packages/{pkgName}/{pkgVersion}

curl \
 --request PUT 'https://<KIBANA_URL>/api/fleet/epm/packages/{pkgName}/{pkgVersion}' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"keepPoliciesUpToDate":true}'

Install a package from the registry

POST /api/fleet/epm/packages/{pkgName}/{pkgVersion}

[Required authorization] Route required privileges: integrations-all AND fleet-agent-policies-all.

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

Path parameters

pkgName string Required
pkgVersion string

Query parameters

prerelease boolean
ignoreMappingUpdateErrors boolean

Default value is false.
skipDataStreamRollover boolean

Default value is false.

application/json

Body

force boolean

Default value is false.
ignore_constraints boolean

Default value is false.

Responses

200 application/json
Hide response attributes Show response attributes object
- _meta object Required
  
  Additional properties are NOT allowed.
  
  Hide _meta attribute Show _meta attribute object
  
  install_source string Required
- items array[object] Required
  
  Any of:
  object-1 object object-2 object
  
  Hide attributes Show attributes
  
  id string Required
  
  originId string
  
  type string Required
  
  Any of:
  string-1 string string-2 string
  
  Values are dashboard, lens, visualization, search, index-pattern, map, ml-module, security-rule, csp-rule-template, osquery-pack-asset, osquery-saved-query, or tag.
  
  Hide attributes Show attributes
  
  deferred boolean
  
  id string Required
  
  type string Required
  
  Values are index, index_template, component_template, ingest_pipeline, ilm_policy, data_stream_ilm_policy, transform, or ml_model.
  
  version string
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

POST /api/fleet/epm/packages/{pkgName}/{pkgVersion}

curl \
 --request POST 'https://<KIBANA_URL>/api/fleet/epm/packages/{pkgName}/{pkgVersion}' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"force":false,"ignore_constraints":false}'

Delete a package

DELETE /api/fleet/epm/packages/{pkgName}/{pkgVersion}

[Required authorization] Route required privileges: integrations-all AND fleet-agent-policies-all.

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

Path parameters

pkgName string Required
pkgVersion string

Query parameters

force boolean

Responses

200 application/json
Hide response attribute Show response attribute object
- items array[object] Required
  
  Any of:
  object-1 object object-2 object
  
  Hide attributes Show attributes
  
  id string Required
  
  originId string
  
  type string Required
  
  Any of:
  string-1 string string-2 string
  
  Values are dashboard, lens, visualization, search, index-pattern, map, ml-module, security-rule, csp-rule-template, osquery-pack-asset, osquery-saved-query, or tag.
  
  Hide attributes Show attributes
  
  deferred boolean
  
  id string Required
  
  type string Required
  
  Values are index, index_template, component_template, ingest_pipeline, ilm_policy, data_stream_ilm_policy, transform, or ml_model.
  
  version string
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

DELETE /api/fleet/epm/packages/{pkgName}/{pkgVersion}

curl \
 --request DELETE 'https://<KIBANA_URL>/api/fleet/epm/packages/{pkgName}/{pkgVersion}' \
 --header "Authorization: $API_KEY" \
 --header "kbn-xsrf: true"

Get a package file

GET /api/fleet/epm/packages/{pkgName}/{pkgVersion}/{filePath}

[Required authorization] Route required privileges: integrations-read OR fleet-setup OR fleet-all.

Path parameters

pkgName string Required
pkgVersion string Required
filePath string Required

Responses

200 application/json
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

GET /api/fleet/epm/packages/{pkgName}/{pkgVersion}/{filePath}

curl \
 --request GET 'https://<KIBANA_URL>/api/fleet/epm/packages/{pkgName}/{pkgVersion}/{filePath}' \
 --header "Authorization: $API_KEY"

Install Kibana assets for a package

POST /api/fleet/epm/packages/{pkgName}/{pkgVersion}/kibana_assets

[Required authorization] Route required privileges: integrations-all AND fleet-agent-policies-all.

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

Path parameters

pkgName string Required
pkgVersion string Required

application/json

Body

force boolean
space_ids array[string]

When provided install assets in the specified spaces instead of the current space.

At least 1 element.

Responses

200 application/json
Hide response attribute Show response attribute object
- success boolean Required
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

POST /api/fleet/epm/packages/{pkgName}/{pkgVersion}/kibana_assets

curl \
 --request POST 'https://<KIBANA_URL>/api/fleet/epm/packages/{pkgName}/{pkgVersion}/kibana_assets' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"force":true,"space_ids":["string"]}'

Delete Kibana assets for a package

DELETE /api/fleet/epm/packages/{pkgName}/{pkgVersion}/kibana_assets

[Required authorization] Route required privileges: integrations-all AND fleet-agent-policies-all.

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

Path parameters

pkgName string Required
pkgVersion string Required

Responses

200 application/json
Hide response attribute Show response attribute object
- success boolean Required
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

DELETE /api/fleet/epm/packages/{pkgName}/{pkgVersion}/kibana_assets

curl \
 --request DELETE 'https://<KIBANA_URL>/api/fleet/epm/packages/{pkgName}/{pkgVersion}/kibana_assets' \
 --header "Authorization: $API_KEY" \
 --header "kbn-xsrf: true"

Authorize transforms

POST /api/fleet/epm/packages/{pkgName}/{pkgVersion}/transforms/authorize

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

Path parameters

pkgName string Required
pkgVersion string Required

Query parameters

prerelease boolean

application/json

Body

transforms array[object] Required
Hide transforms attribute Show transforms attribute object
- transformId string Required

Responses

200 application/json
Hide response attributes Show response attributes object
- error Required
- success boolean Required
- transformId string Required
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

POST /api/fleet/epm/packages/{pkgName}/{pkgVersion}/transforms/authorize

curl \
 --request POST 'https://<KIBANA_URL>/api/fleet/epm/packages/{pkgName}/{pkgVersion}/transforms/authorize' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"transforms":[{"transformId":"string"}]}'

Get package stats

GET /api/fleet/epm/packages/{pkgName}/stats

[Required authorization] Route required privileges: integrations-read OR fleet-setup OR fleet-all.

Path parameters

pkgName string Required

Responses

200 application/json
Hide response attribute Show response attribute object
- response object Required
  
  Additional properties are NOT allowed.
  
  Hide response attribute Show response attribute object
  
  agent_policy_count number Required
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

GET /api/fleet/epm/packages/{pkgName}/stats

curl \
 --request GET 'https://<KIBANA_URL>/api/fleet/epm/packages/{pkgName}/stats' \
 --header "Authorization: $API_KEY"

Get installed packages

GET /api/fleet/epm/packages/installed

[Required authorization] Route required privileges: integrations-read OR fleet-setup OR fleet-all.

Query parameters

dataStreamType string

Values are logs, metrics, traces, synthetics, or profiling.
showOnlyActiveDataStreams boolean
nameQuery string
searchAfter array[string | number]
perPage number

Default value is 15.
sortOrder string

Values are asc or desc. Default value is asc.

Responses

200 application/json
Hide response attributes Show response attributes object
- items array[object] Required
  
  Hide items attributes Show items attributes object
  
  dataStreams array[object] Required
  
  Hide dataStreams attributes Show dataStreams attributes object
  
  name string Required
  
  title string Required
  
  description string
  
  icons array[object]
  
  Hide icons attributes Show icons attributes object
  
  dark_mode boolean
  
  path string
  
  size string
  
  src string Required
  
  title string
  
  type string
  
  name string Required
  
  status string Required
  
  title string
  
  version string Required
- searchAfter array[string | number | boolean]
- total number Required
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

GET /api/fleet/epm/packages/installed

curl \
 --request GET 'https://<KIBANA_URL>/api/fleet/epm/packages/installed' \
 --header "Authorization: $API_KEY"

Get a limited package list

GET /api/fleet/epm/packages/limited

[Required authorization] Route required privileges: integrations-read OR fleet-setup OR fleet-all.

Responses

200 application/json
Hide response attribute Show response attribute object
- items array[string] Required
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

GET /api/fleet/epm/packages/limited

curl \
 --request GET 'https://<KIBANA_URL>/api/fleet/epm/packages/limited' \
 --header "Authorization: $API_KEY"

Get an inputs template

GET /api/fleet/epm/templates/{pkgName}/{pkgVersion}/inputs

[Required authorization] Route required privileges: integrations-read OR fleet-setup OR fleet-all.

Path parameters

pkgName string Required
pkgVersion string Required

Query parameters

format string

Values are json, yml, or yaml. Default value is json.
prerelease boolean
ignoreUnverified boolean

Responses

200 application/json
Any of:
string-1 string object-2 object
Hide attribute Show attribute

inputs array[object] Required

Hide inputs attributes Show inputs attributes object

id string Required

streams array[object]

Hide streams attributes Show streams attributes object

data_stream object Required

Additional properties are allowed.

Hide data_stream attributes Show data_stream attributes object

dataset string Required

type string

id string Required

type string Required
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

GET /api/fleet/epm/templates/{pkgName}/{pkgVersion}/inputs

curl \
 --request GET 'https://<KIBANA_URL>/api/fleet/epm/templates/{pkgName}/{pkgVersion}/inputs' \
 --header "Authorization: $API_KEY"

Get a package signature verification key ID

GET /api/fleet/epm/verification_key_id

[Required authorization] Route required privileges: integrations-read OR fleet-setup OR fleet-all.

Responses

200 application/json
Hide response attribute Show response attribute object
- id string | null Required
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

GET /api/fleet/epm/verification_key_id

curl \
 --request GET 'https://<KIBANA_URL>/api/fleet/epm/verification_key_id' \
 --header "Authorization: $API_KEY"

Get enrollment API keys

GET /api/fleet/enrollment_api_keys

[Required authorization] Route required privileges: fleet-agents-all OR fleet-setup.

Query parameters

page number

Default value is 1.
perPage number

Default value is 20.
kuery string

Responses

200 application/json
Hide response attributes Show response attributes object
- items array[object] Required
  
  Hide items attributes Show items attributes object
  
  active boolean Required
  
  When false, the enrollment API key is revoked and cannot be used for enrolling Elastic Agents.
  
  api_key string Required
  
  The enrollment API key (token) used for enrolling Elastic Agents.
  
  api_key_id string Required
  
  The ID of the API key in the Security API.
  
  created_at string Required
  
  hidden boolean
  
  id string Required
  
  name string
  
  The name of the enrollment API key.
  
  policy_id string
  
  The ID of the agent policy the Elastic Agent will be enrolled in.
- list array[object] Required Deprecated
  
  Hide list attributes Show list attributes object
  
  active boolean Required
  
  When false, the enrollment API key is revoked and cannot be used for enrolling Elastic Agents.
  
  api_key string Required
  
  The enrollment API key (token) used for enrolling Elastic Agents.
  
  api_key_id string Required
  
  The ID of the API key in the Security API.
  
  created_at string Required
  
  hidden boolean
  
  id string Required
  
  name string
  
  The name of the enrollment API key.
  
  policy_id string
  
  The ID of the agent policy the Elastic Agent will be enrolled in.
- page number Required
- perPage number Required
- total number Required
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

GET /api/fleet/enrollment_api_keys

curl \
 --request GET 'https://<KIBANA_URL>/api/fleet/enrollment_api_keys' \
 --header "Authorization: $API_KEY"

Create an enrollment API key

POST /api/fleet/enrollment_api_keys

[Required authorization] Route required privileges: fleet-agents-all.

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

application/json

Body

expiration string
name string
policy_id string Required

Responses

200 application/json
Hide response attributes Show response attributes object
- action string Required
  
  Value is created.
- item object Required
  
  Additional properties are NOT allowed.
  
  Hide item attributes Show item attributes object
  
  active boolean Required
  
  When false, the enrollment API key is revoked and cannot be used for enrolling Elastic Agents.
  
  api_key string Required
  
  The enrollment API key (token) used for enrolling Elastic Agents.
  
  api_key_id string Required
  
  The ID of the API key in the Security API.
  
  created_at string Required
  
  hidden boolean
  
  id string Required
  
  name string
  
  The name of the enrollment API key.
  
  policy_id string
  
  The ID of the agent policy the Elastic Agent will be enrolled in.
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

POST /api/fleet/enrollment_api_keys

curl \
 --request POST 'https://<KIBANA_URL>/api/fleet/enrollment_api_keys' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"expiration":"string","name":"string","policy_id":"string"}'

Get an enrollment API key

GET /api/fleet/enrollment_api_keys/{keyId}

Get an enrollment API key by ID.

[Required authorization] Route required privileges: fleet-agents-all OR fleet-setup.

Path parameters

keyId string Required

Responses

200 application/json
Hide response attribute Show response attribute object
- item object Required
  
  Additional properties are NOT allowed.
  
  Hide item attributes Show item attributes object
  
  active boolean Required
  
  When false, the enrollment API key is revoked and cannot be used for enrolling Elastic Agents.
  
  api_key string Required
  
  The enrollment API key (token) used for enrolling Elastic Agents.
  
  api_key_id string Required
  
  The ID of the API key in the Security API.
  
  created_at string Required
  
  hidden boolean
  
  id string Required
  
  name string
  
  The name of the enrollment API key.
  
  policy_id string
  
  The ID of the agent policy the Elastic Agent will be enrolled in.
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

GET /api/fleet/enrollment_api_keys/{keyId}

curl \
 --request GET 'https://<KIBANA_URL>/api/fleet/enrollment_api_keys/{keyId}' \
 --header "Authorization: $API_KEY"

Revoke an enrollment API key

DELETE /api/fleet/enrollment_api_keys/{keyId}

Revoke an enrollment API key by ID by marking it as inactive.

[Required authorization] Route required privileges: fleet-agents-all.

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

Path parameters

keyId string Required

Responses

200 application/json
Hide response attribute Show response attribute object
- action string Required
  
  Value is deleted.
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

DELETE /api/fleet/enrollment_api_keys/{keyId}

curl \
 --request DELETE 'https://<KIBANA_URL>/api/fleet/enrollment_api_keys/{keyId}' \
 --header "Authorization: $API_KEY" \
 --header "kbn-xsrf: true"

Check permissions

GET /api/fleet/check-permissions

Query parameters

fleetServerSetup boolean

Responses

200 application/json
Hide response attributes Show response attributes object
- error string
  
  Values are MISSING_SECURITY, MISSING_PRIVILEGES, or MISSING_FLEET_SERVER_SETUP_PRIVILEGES.
- success boolean Required
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

GET /api/fleet/check-permissions

curl \
 --request GET 'https://<KIBANA_URL>/api/fleet/check-permissions' \
 --header "Authorization: $API_KEY"

Check Fleet Server health

POST /api/fleet/health_check

[Required authorization] Route required privileges: fleet-settings-all.

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

application/json

Body

id string Required

Responses

200 application/json
Hide response attributes Show response attributes object
- host_id string
- name string
- status string Required
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number
404 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

POST /api/fleet/health_check

curl \
 --request POST 'https://<KIBANA_URL>/api/fleet/health_check' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"id":"string"}'

Get settings

GET /api/fleet/settings

[Required authorization] Route required privileges: fleet-settings-read.

Responses

200 application/json
Hide response attribute Show response attribute object
- item object Required
  
  Additional properties are NOT allowed.
  
  Hide item attributes Show item attributes object
  
  delete_unenrolled_agents object
  
  Additional properties are NOT allowed.
  
  Hide delete_unenrolled_agents attributes Show delete_unenrolled_agents attributes object
  
  enabled boolean Required
  
  is_preconfigured boolean Required
  
  has_seen_add_data_notice boolean
  
  id string Required
  
  output_secret_storage_requirements_met boolean
  
  preconfigured_fields array[string]
  
  Value is fleet_server_hosts.
  
  prerelease_integrations_enabled boolean
  
  secret_storage_requirements_met boolean
  
  use_space_awareness_migration_started_at string | null
  
  use_space_awareness_migration_status string
  
  Values are pending, success, or error.
  
  version string
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number
404 application/json
Hide response attribute Show response attribute object
- message string Required

GET /api/fleet/settings

curl \
 --request GET 'https://<KIBANA_URL>/api/fleet/settings' \
 --header "Authorization: $API_KEY"

Update settings

PUT /api/fleet/settings

[Required authorization] Route required privileges: fleet-settings-all.

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

application/json

Body

additional_yaml_config string
delete_unenrolled_agents object

Additional properties are NOT allowed.
Hide delete_unenrolled_agents attributes Show delete_unenrolled_agents attributes object
- enabled boolean Required
- is_preconfigured boolean Required
has_seen_add_data_notice boolean
kibana_ca_sha256 string
kibana_urls array[string(uri)]
prerelease_integrations_enabled boolean

Responses

200 application/json
Hide response attribute Show response attribute object
- item object Required
  
  Additional properties are NOT allowed.
  
  Hide item attributes Show item attributes object
  
  delete_unenrolled_agents object
  
  Additional properties are NOT allowed.
  
  Hide delete_unenrolled_agents attributes Show delete_unenrolled_agents attributes object
  
  enabled boolean Required
  
  is_preconfigured boolean Required
  
  has_seen_add_data_notice boolean
  
  id string Required
  
  output_secret_storage_requirements_met boolean
  
  preconfigured_fields array[string]
  
  Value is fleet_server_hosts.
  
  prerelease_integrations_enabled boolean
  
  secret_storage_requirements_met boolean
  
  use_space_awareness_migration_started_at string | null
  
  use_space_awareness_migration_status string
  
  Values are pending, success, or error.
  
  version string
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number
404 application/json
Hide response attribute Show response attribute object
- message string Required

PUT /api/fleet/settings

curl \
 --request PUT 'https://<KIBANA_URL>/api/fleet/settings' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"additional_yaml_config":"string","delete_unenrolled_agents":{"enabled":true,"is_preconfigured":true},"has_seen_add_data_notice":true,"kibana_ca_sha256":"string","kibana_urls":["https://example.com"],"prerelease_integrations_enabled":true}'

Initiate Fleet setup

POST /api/fleet/setup

[Required authorization] Route required privileges: fleet-agents-read OR fleet-agent-policies-read OR fleet-settings-read OR fleet-setup.

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

Responses

200 application/json
Hide response attributes Show response attributes object
- isInitialized boolean Required
- nonFatalErrors array[object] Required
  
  Hide nonFatalErrors attributes Show nonFatalErrors attributes object
  
  message string Required
  
  name string Required
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number
500 application/json
Hide response attribute Show response attribute object
- message string Required

POST /api/fleet/setup

curl \
 --request POST 'https://<KIBANA_URL>/api/fleet/setup' \
 --header "Authorization: $API_KEY" \
 --header "kbn-xsrf: true"

Generate a Logstash API key

POST /api/fleet/logstash_api_keys

[Required authorization] Route required privileges: fleet-settings-all.

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

Responses

200 application/json
Hide response attribute Show response attribute object
- api_key string Required
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

POST /api/fleet/logstash_api_keys

curl \
 --request POST 'https://<KIBANA_URL>/api/fleet/logstash_api_keys' \
 --header "Authorization: $API_KEY" \
 --header "kbn-xsrf: true"

Get outputs

GET /api/fleet/outputs

[Required authorization] Route required privileges: fleet-settings-read OR fleet-agent-policies-read.

Responses

200 application/json
Hide response attributes Show response attributes object
- items array[object] Required
  
  Any of:
  object-1 object object-2 object object-3 object object-4 object
  
  Hide attributes Show attributes
  
  allow_edit array[string]
  
  ca_sha256 string | null
  
  ca_trusted_fingerprint string | null
  
  config_yaml string | null
  
  hosts array[string(uri)] Required
  
  At least 1 element.
  
  id string
  
  is_default boolean
  
  Default value is false.
  
  is_default_monitoring boolean
  
  Default value is false.
  
  is_internal boolean
  
  is_preconfigured boolean
  
  name string Required
  
  preset string
  
  Values are balanced, custom, throughput, scale, or latency.
  
  proxy_id string | null
  
  secrets object
  
  Additional properties are allowed.
  
  Hide secrets attribute Show secrets attribute object
  
  ssl object
  
  Additional properties are allowed.
  
  Hide ssl attribute Show ssl attribute object
  
  key object | string
  
  Any of:
  object-1 object string-2 string
  
  Hide attribute Show attribute
  
  id string Required
  
  shipper object | null
  
  Additional properties are allowed.
  
  Hide shipper attributes Show shipper attributes object | null
  
  compression_level number | null Required
  
  disk_queue_compression_enabled boolean | null Required
  
  disk_queue_enabled boolean | null
  
  Default value is false.
  
  disk_queue_encryption_enabled boolean | null Required
  
  disk_queue_max_size number | null Required
  
  disk_queue_path string | null Required
  
  loadbalance boolean | null Required
  
  max_batch_bytes number | null Required
  
  mem_queue_events number | null Required
  
  queue_flush_timeout number | null Required
  
  ssl object | null
  
  Additional properties are allowed.
  
  Hide ssl attributes Show ssl attributes object | null
  
  certificate string
  
  certificate_authorities array[string]
  
  key string
  
  verification_mode string
  
  Values are full, none, certificate, or strict.
  
  type string Required
  
  Value is elasticsearch.
  
  Hide attributes Show attributes
  
  allow_edit array[string]
  
  ca_sha256 string | null
  
  ca_trusted_fingerprint string | null
  
  config_yaml string | null
  
  hosts array[string(uri)] Required
  
  At least 1 element.
  
  id string
  
  is_default boolean
  
  Default value is false.
  
  is_default_monitoring boolean
  
  Default value is false.
  
  is_internal boolean
  
  is_preconfigured boolean
  
  kibana_api_key string | null
  
  kibana_url string | null
  
  name string Required
  
  preset string
  
  Values are balanced, custom, throughput, scale, or latency.
  
  proxy_id string | null
  
  secrets object
  
  Additional properties are allowed.
  
  Hide secrets attributes Show secrets attributes object
  
  service_token object | string
  
  Any of:
  object-1 object string-2 string
  
  Hide attribute Show attribute
  
  id string Required
  
  ssl object
  
  Additional properties are allowed.
  
  Hide ssl attribute Show ssl attribute object
  
  key object | string
  
  Any of:
  object-1 object string-2 string
  
  Hide attribute Show attribute
  
  id string Required
  
  service_token string | null
  
  shipper object | null
  
  Additional properties are allowed.
  
  Hide shipper attributes Show shipper attributes object | null
  
  compression_level number | null Required
  
  disk_queue_compression_enabled boolean | null Required
  
  disk_queue_enabled boolean | null
  
  Default value is false.
  
  disk_queue_encryption_enabled boolean | null Required
  
  disk_queue_max_size number | null Required
  
  disk_queue_path string | null Required
  
  loadbalance boolean | null Required
  
  max_batch_bytes number | null Required
  
  mem_queue_events number | null Required
  
  queue_flush_timeout number | null Required
  
  ssl object | null
  
  Additional properties are allowed.
  
  Hide ssl attributes Show ssl attributes object | null
  
  certificate string
  
  certificate_authorities array[string]
  
  key string
  
  verification_mode string
  
  Values are full, none, certificate, or strict.
  
  sync_integrations boolean
  
  sync_uninstalled_integrations boolean
  
  type string Required
  
  Value is remote_elasticsearch.
  
  Hide attributes Show attributes
  
  allow_edit array[string]
  
  ca_sha256 string | null
  
  ca_trusted_fingerprint string | null
  
  config_yaml string | null
  
  hosts array[string] Required
  
  At least 1 element.
  
  id string
  
  is_default boolean
  
  Default value is false.
  
  is_default_monitoring boolean
  
  Default value is false.
  
  is_internal boolean
  
  is_preconfigured boolean
  
  name string Required
  
  proxy_id string | null
  
  secrets object
  
  Additional properties are allowed.
  
  Hide secrets attribute Show secrets attribute object
  
  ssl object
  
  Additional properties are allowed.
  
  Hide ssl attribute Show ssl attribute object
  
  key object | string
  
  Any of:
  object-1 object string-2 string
  
  Hide attribute Show attribute
  
  id string Required
  
  shipper object | null
  
  Additional properties are allowed.
  
  Hide shipper attributes Show shipper attributes object | null
  
  compression_level number | null Required
  
  disk_queue_compression_enabled boolean | null Required
  
  disk_queue_enabled boolean | null
  
  Default value is false.
  
  disk_queue_encryption_enabled boolean | null Required
  
  disk_queue_max_size number | null Required
  
  disk_queue_path string | null Required
  
  loadbalance boolean | null Required
  
  max_batch_bytes number | null Required
  
  mem_queue_events number | null Required
  
  queue_flush_timeout number | null Required
  
  ssl object | null
  
  Additional properties are allowed.
  
  Hide ssl attributes Show ssl attributes object | null
  
  certificate string
  
  certificate_authorities array[string]
  
  key string
  
  verification_mode string
  
  Values are full, none, certificate, or strict.
  
  type string Required
  
  Value is logstash.
  
  Hide attributes Show attributes
  
  allow_edit array[string]
  
  auth_type string Required
  
  Values are none, user_pass, ssl, or kerberos.
  
  broker_timeout number
  
  ca_sha256 string | null
  
  ca_trusted_fingerprint string | null
  
  client_id string
  
  compression string
  
  Values are gzip, snappy, lz4, or none.
  
  compression_level array | null | boolean | number | object | string Required
  
  Any of:
  array-1 array | null boolean-2 boolean | null number-3 number | null object-4 object | null string-5 string | null
  
  config_yaml string | null
  
  connection_type array | null | boolean | number | object | string Required
  
  Any of:
  array-1 array | null boolean-2 boolean | null number-3 number | null object-4 object | null string-5 string | null
  
  hash object
  
  Additional properties are allowed.
  
  Hide hash attributes Show hash attributes object
  
  hash string
  
  random boolean
  
  headers array[object]
  
  Hide headers attributes Show headers attributes object
  
  key string Required
  
  value string Required
  
  hosts array[string] Required
  
  At least 1 element.
  
  id string
  
  is_default boolean
  
  Default value is false.
  
  is_default_monitoring boolean
  
  Default value is false.
  
  is_internal boolean
  
  is_preconfigured boolean
  
  key string
  
  name string Required
  
  partition string
  
  Values are random, round_robin, or hash.
  
  password array | null | boolean | number | object | string Required
  
  Any of:
  array-1 array | null boolean-2 boolean | null number-3 number | null object-4 object | null string-5 string | null
  
  proxy_id string | null
  
  random object
  
  Additional properties are allowed.
  
  Hide random attribute Show random attribute object
  
  group_events number
  
  required_acks integer
  
  Values are 1, 0, or -1.
  
  round_robin object
  
  Additional properties are allowed.
  
  Hide round_robin attribute Show round_robin attribute object
  
  group_events number
  
  sasl object | null
  
  Additional properties are allowed.
  
  Hide sasl attribute Show sasl attribute object | null
  
  mechanism string
  
  Values are PLAIN, SCRAM-SHA-256, or SCRAM-SHA-512.
  
  secrets object
  
  Additional properties are allowed.
  
  Hide secrets attributes Show secrets attributes object
  
  password object | string
  
  Any of:
  object-1 object string-2 string
  
  Hide attribute Show attribute
  
  id string Required
  
  ssl object
  
  Additional properties are allowed.
  
  Hide ssl attribute Show ssl attribute object
  
  key object | string Required
  
  Any of:
  object-1 object string-2 string
  
  Hide attribute Show attribute
  
  id string Required
  
  shipper object | null
  
  Additional properties are allowed.
  
  Hide shipper attributes Show shipper attributes object | null
  
  compression_level number | null Required
  
  disk_queue_compression_enabled boolean | null Required
  
  disk_queue_enabled boolean | null
  
  Default value is false.
  
  disk_queue_encryption_enabled boolean | null Required
  
  disk_queue_max_size number | null Required
  
  disk_queue_path string | null Required
  
  loadbalance boolean | null Required
  
  max_batch_bytes number | null Required
  
  mem_queue_events number | null Required
  
  queue_flush_timeout number | null Required
  
  ssl object | null
  
  Additional properties are allowed.
  
  Hide ssl attributes Show ssl attributes object | null
  
  certificate string
  
  certificate_authorities array[string]
  
  key string
  
  verification_mode string
  
  Values are full, none, certificate, or strict.
  
  timeout number
  
  topic string
  
  type string Required
  
  Value is kafka.
  
  username array | null | boolean | number | object | string Required
  
  Any of:
  array-1 array | null boolean-2 boolean | null number-3 number | null object-4 object | null string-5 string | null
  
  version string
- page number Required
- perPage number Required
- total number Required
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

GET /api/fleet/outputs

curl \
 --request GET 'https://<KIBANA_URL>/api/fleet/outputs' \
 --header "Authorization: $API_KEY"

Create output

POST /api/fleet/outputs

[Required authorization] Route required privileges: fleet-settings-all.

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

application/json

Body object

allow_edit array[string]
ca_sha256 string | null
ca_trusted_fingerprint string | null
config_yaml string | null
hosts array[string(uri)] Required

At least 1 element.
id string
is_default boolean

Default value is false.
is_default_monitoring boolean

Default value is false.
is_internal boolean
is_preconfigured boolean
name string Required
preset string

Values are balanced, custom, throughput, scale, or latency.
proxy_id string | null
secrets object

Additional properties are NOT allowed.
Hide secrets attribute Show secrets attribute object
- ssl object
  
  Additional properties are NOT allowed.
  Hide ssl attribute Show ssl attribute object
  
  key object | string
  
  Any of:
  object-1 object string-2 string
  
  Hide attribute Show attribute
  
  id string Required
shipper object | null

Additional properties are NOT allowed.
Hide shipper attributes Show shipper attributes object | null
- compression_level number | null Required
- disk_queue_compression_enabled boolean | null Required
- disk_queue_enabled boolean | null
  
  Default value is false.
- disk_queue_encryption_enabled boolean | null Required
- disk_queue_max_size number | null Required
- disk_queue_path string | null Required
- loadbalance boolean | null Required
- max_batch_bytes number | null Required
- mem_queue_events number | null Required
- queue_flush_timeout number | null Required
ssl object | null

Additional properties are NOT allowed.
Hide ssl attributes Show ssl attributes object | null
- certificate string
- certificate_authorities array[string]
- key string
- verification_mode string
  
  Values are full, none, certificate, or strict.
type string Required

Value is elasticsearch.

allow_edit array[string]
ca_sha256 string | null
ca_trusted_fingerprint string | null
config_yaml string | null
hosts array[string(uri)] Required

At least 1 element.
id string
is_default boolean

Default value is false.
is_default_monitoring boolean

Default value is false.
is_internal boolean
is_preconfigured boolean
kibana_api_key string | null
kibana_url string | null
name string Required
preset string

Values are balanced, custom, throughput, scale, or latency.
proxy_id string | null
secrets object

Additional properties are NOT allowed.
Hide secrets attributes Show secrets attributes object
- service_token object | string
  
  Any of:
  object-1 object string-2 string
  
  Hide attribute Show attribute
  
  id string Required
- ssl object
  
  Additional properties are NOT allowed.
  Hide ssl attribute Show ssl attribute object
  
  key object | string
  
  Any of:
  object-1 object string-2 string
  
  Hide attribute Show attribute
  
  id string Required
service_token string | null
shipper object | null

Additional properties are NOT allowed.
Hide shipper attributes Show shipper attributes object | null
- compression_level number | null Required
- disk_queue_compression_enabled boolean | null Required
- disk_queue_enabled boolean | null
  
  Default value is false.
- disk_queue_encryption_enabled boolean | null Required
- disk_queue_max_size number | null Required
- disk_queue_path string | null Required
- loadbalance boolean | null Required
- max_batch_bytes number | null Required
- mem_queue_events number | null Required
- queue_flush_timeout number | null Required
ssl object | null

Additional properties are NOT allowed.
Hide ssl attributes Show ssl attributes object | null
- certificate string
- certificate_authorities array[string]
- key string
- verification_mode string
  
  Values are full, none, certificate, or strict.
sync_integrations boolean
sync_uninstalled_integrations boolean
type string Required

Value is remote_elasticsearch.

allow_edit array[string]
ca_sha256 string | null
ca_trusted_fingerprint string | null
config_yaml string | null
hosts array[string] Required

At least 1 element.
id string
is_default boolean

Default value is false.
is_default_monitoring boolean

Default value is false.
is_internal boolean
is_preconfigured boolean
name string Required
proxy_id string | null
secrets object

Additional properties are NOT allowed.
Hide secrets attribute Show secrets attribute object
- ssl object
  
  Additional properties are NOT allowed.
  Hide ssl attribute Show ssl attribute object
  
  key object | string
  
  Any of:
  object-1 object string-2 string
  
  Hide attribute Show attribute
  
  id string Required
shipper object | null

Additional properties are NOT allowed.
Hide shipper attributes Show shipper attributes object | null
- compression_level number | null Required
- disk_queue_compression_enabled boolean | null Required
- disk_queue_enabled boolean | null
  
  Default value is false.
- disk_queue_encryption_enabled boolean | null Required
- disk_queue_max_size number | null Required
- disk_queue_path string | null Required
- loadbalance boolean | null Required
- max_batch_bytes number | null Required
- mem_queue_events number | null Required
- queue_flush_timeout number | null Required
ssl object | null

Additional properties are NOT allowed.
Hide ssl attributes Show ssl attributes object | null
- certificate string
- certificate_authorities array[string]
- key string
- verification_mode string
  
  Values are full, none, certificate, or strict.
type string Required

Value is logstash.

allow_edit array[string]
auth_type string Required

Values are none, user_pass, ssl, or kerberos.
broker_timeout number
ca_sha256 string | null
ca_trusted_fingerprint string | null
client_id string
compression string

Values are gzip, snappy, lz4, or none.
compression_level array | null | boolean | number | object | string Required

Any of:
array-1 array | null boolean-2 boolean | null number-3 number | null object-4 object | null string-5 string | null
config_yaml string | null
connection_type array | null | boolean | number | object | string Required

Any of:
array-1 array | null boolean-2 boolean | null number-3 number | null object-4 object | null string-5 string | null
hash object

Additional properties are NOT allowed.
Hide hash attributes Show hash attributes object
- hash string
- random boolean
headers array[object]
Hide headers attributes Show headers attributes object
- key string Required
- value string Required
hosts array[string] Required

At least 1 element.
id string
is_default boolean

Default value is false.
is_default_monitoring boolean

Default value is false.
is_internal boolean
is_preconfigured boolean
key string
name string Required
partition string

Values are random, round_robin, or hash.
password array | null | boolean | number | object | string Required

Any of:
array-1 array | null boolean-2 boolean | null number-3 number | null object-4 object | null string-5 string | null
proxy_id string | null
random object

Additional properties are NOT allowed.
Hide random attribute Show random attribute object
- group_events number
required_acks integer

Values are 1, 0, or -1.
round_robin object

Additional properties are NOT allowed.
Hide round_robin attribute Show round_robin attribute object
- group_events number
sasl object | null

Additional properties are NOT allowed.
Hide sasl attribute Show sasl attribute object | null
- mechanism string
  
  Values are PLAIN, SCRAM-SHA-256, or SCRAM-SHA-512.
secrets object

Additional properties are NOT allowed.
Hide secrets attributes Show secrets attributes object
- password object | string
  
  Any of:
  object-1 object string-2 string
  
  Hide attribute Show attribute
  
  id string Required
- ssl object
  
  Additional properties are NOT allowed.
  Hide ssl attribute Show ssl attribute object
  
  key object | string Required
  
  Any of:
  object-1 object string-2 string
  
  Hide attribute Show attribute
  
  id string Required
shipper object | null

Additional properties are NOT allowed.
Hide shipper attributes Show shipper attributes object | null
- compression_level number | null Required
- disk_queue_compression_enabled boolean | null Required
- disk_queue_enabled boolean | null
  
  Default value is false.
- disk_queue_encryption_enabled boolean | null Required
- disk_queue_max_size number | null Required
- disk_queue_path string | null Required
- loadbalance boolean | null Required
- max_batch_bytes number | null Required
- mem_queue_events number | null Required
- queue_flush_timeout number | null Required
ssl object | null

Additional properties are NOT allowed.
Hide ssl attributes Show ssl attributes object | null
- certificate string
- certificate_authorities array[string]
- key string
- verification_mode string
  
  Values are full, none, certificate, or strict.
timeout number
topic string
type string Required

Value is kafka.
username array | null | boolean | number | object | string Required

Any of:
array-1 array | null boolean-2 boolean | null number-3 number | null object-4 object | null string-5 string | null
version string

Responses

200 application/json
Hide response attribute Show response attribute object
- item object Required
  
  Any of:
  object-1 object object-2 object object-3 object object-4 object
  
  Hide attributes Show attributes
  
  allow_edit array[string]
  
  ca_sha256 string | null
  
  ca_trusted_fingerprint string | null
  
  config_yaml string | null
  
  hosts array[string(uri)] Required
  
  At least 1 element.
  
  id string
  
  is_default boolean
  
  Default value is false.
  
  is_default_monitoring boolean
  
  Default value is false.
  
  is_internal boolean
  
  is_preconfigured boolean
  
  name string Required
  
  preset string
  
  Values are balanced, custom, throughput, scale, or latency.
  
  proxy_id string | null
  
  secrets object
  
  Additional properties are allowed.
  
  Hide secrets attribute Show secrets attribute object
  
  ssl object
  
  Additional properties are allowed.
  
  Hide ssl attribute Show ssl attribute object
  
  key object | string
  
  Any of:
  object-1 object string-2 string
  
  Hide attribute Show attribute
  
  id string Required
  
  shipper object | null
  
  Additional properties are allowed.
  
  Hide shipper attributes Show shipper attributes object | null
  
  compression_level number | null Required
  
  disk_queue_compression_enabled boolean | null Required
  
  disk_queue_enabled boolean | null
  
  Default value is false.
  
  disk_queue_encryption_enabled boolean | null Required
  
  disk_queue_max_size number | null Required
  
  disk_queue_path string | null Required
  
  loadbalance boolean | null Required
  
  max_batch_bytes number | null Required
  
  mem_queue_events number | null Required
  
  queue_flush_timeout number | null Required
  
  ssl object | null
  
  Additional properties are allowed.
  
  Hide ssl attributes Show ssl attributes object | null
  
  certificate string
  
  certificate_authorities array[string]
  
  key string
  
  verification_mode string
  
  Values are full, none, certificate, or strict.
  
  type string Required
  
  Value is elasticsearch.
  
  Hide attributes Show attributes
  
  allow_edit array[string]
  
  ca_sha256 string | null
  
  ca_trusted_fingerprint string | null
  
  config_yaml string | null
  
  hosts array[string(uri)] Required
  
  At least 1 element.
  
  id string
  
  is_default boolean
  
  Default value is false.
  
  is_default_monitoring boolean
  
  Default value is false.
  
  is_internal boolean
  
  is_preconfigured boolean
  
  kibana_api_key string | null
  
  kibana_url string | null
  
  name string Required
  
  preset string
  
  Values are balanced, custom, throughput, scale, or latency.
  
  proxy_id string | null
  
  secrets object
  
  Additional properties are allowed.
  
  Hide secrets attributes Show secrets attributes object
  
  service_token object | string
  
  Any of:
  object-1 object string-2 string
  
  Hide attribute Show attribute
  
  id string Required
  
  ssl object
  
  Additional properties are allowed.
  
  Hide ssl attribute Show ssl attribute object
  
  key object | string
  
  Any of:
  object-1 object string-2 string
  
  Hide attribute Show attribute
  
  id string Required
  
  service_token string | null
  
  shipper object | null
  
  Additional properties are allowed.
  
  Hide shipper attributes Show shipper attributes object | null
  
  compression_level number | null Required
  
  disk_queue_compression_enabled boolean | null Required
  
  disk_queue_enabled boolean | null
  
  Default value is false.
  
  disk_queue_encryption_enabled boolean | null Required
  
  disk_queue_max_size number | null Required
  
  disk_queue_path string | null Required
  
  loadbalance boolean | null Required
  
  max_batch_bytes number | null Required
  
  mem_queue_events number | null Required
  
  queue_flush_timeout number | null Required
  
  ssl object | null
  
  Additional properties are allowed.
  
  Hide ssl attributes Show ssl attributes object | null
  
  certificate string
  
  certificate_authorities array[string]
  
  key string
  
  verification_mode string
  
  Values are full, none, certificate, or strict.
  
  sync_integrations boolean
  
  sync_uninstalled_integrations boolean
  
  type string Required
  
  Value is remote_elasticsearch.
  
  Hide attributes Show attributes
  
  allow_edit array[string]
  
  ca_sha256 string | null
  
  ca_trusted_fingerprint string | null
  
  config_yaml string | null
  
  hosts array[string] Required
  
  At least 1 element.
  
  id string
  
  is_default boolean
  
  Default value is false.
  
  is_default_monitoring boolean
  
  Default value is false.
  
  is_internal boolean
  
  is_preconfigured boolean
  
  name string Required
  
  proxy_id string | null
  
  secrets object
  
  Additional properties are allowed.
  
  Hide secrets attribute Show secrets attribute object
  
  ssl object
  
  Additional properties are allowed.
  
  Hide ssl attribute Show ssl attribute object
  
  key object | string
  
  Any of:
  object-1 object string-2 string
  
  Hide attribute Show attribute
  
  id string Required
  
  shipper object | null
  
  Additional properties are allowed.
  
  Hide shipper attributes Show shipper attributes object | null
  
  compression_level number | null Required
  
  disk_queue_compression_enabled boolean | null Required
  
  disk_queue_enabled boolean | null
  
  Default value is false.
  
  disk_queue_encryption_enabled boolean | null Required
  
  disk_queue_max_size number | null Required
  
  disk_queue_path string | null Required
  
  loadbalance boolean | null Required
  
  max_batch_bytes number | null Required
  
  mem_queue_events number | null Required
  
  queue_flush_timeout number | null Required
  
  ssl object | null
  
  Additional properties are allowed.
  
  Hide ssl attributes Show ssl attributes object | null
  
  certificate string
  
  certificate_authorities array[string]
  
  key string
  
  verification_mode string
  
  Values are full, none, certificate, or strict.
  
  type string Required
  
  Value is logstash.
  
  Hide attributes Show attributes
  
  allow_edit array[string]
  
  auth_type string Required
  
  Values are none, user_pass, ssl, or kerberos.
  
  broker_timeout number
  
  ca_sha256 string | null
  
  ca_trusted_fingerprint string | null
  
  client_id string
  
  compression string
  
  Values are gzip, snappy, lz4, or none.
  
  compression_level array | null | boolean | number | object | string Required
  
  Any of:
  array-1 array | null boolean-2 boolean | null number-3 number | null object-4 object | null string-5 string | null
  
  config_yaml string | null
  
  connection_type array | null | boolean | number | object | string Required
  
  Any of:
  array-1 array | null boolean-2 boolean | null number-3 number | null object-4 object | null string-5 string | null
  
  hash object
  
  Additional properties are allowed.
  
  Hide hash attributes Show hash attributes object
  
  hash string
  
  random boolean
  
  headers array[object]
  
  Hide headers attributes Show headers attributes object
  
  key string Required
  
  value string Required
  
  hosts array[string] Required
  
  At least 1 element.
  
  id string
  
  is_default boolean
  
  Default value is false.
  
  is_default_monitoring boolean
  
  Default value is false.
  
  is_internal boolean
  
  is_preconfigured boolean
  
  key string
  
  name string Required
  
  partition string
  
  Values are random, round_robin, or hash.
  
  password array | null | boolean | number | object | string Required
  
  Any of:
  array-1 array | null boolean-2 boolean | null number-3 number | null object-4 object | null string-5 string | null
  
  proxy_id string | null
  
  random object
  
  Additional properties are allowed.
  
  Hide random attribute Show random attribute object
  
  group_events number
  
  required_acks integer
  
  Values are 1, 0, or -1.
  
  round_robin object
  
  Additional properties are allowed.
  
  Hide round_robin attribute Show round_robin attribute object
  
  group_events number
  
  sasl object | null
  
  Additional properties are allowed.
  
  Hide sasl attribute Show sasl attribute object | null
  
  mechanism string
  
  Values are PLAIN, SCRAM-SHA-256, or SCRAM-SHA-512.
  
  secrets object
  
  Additional properties are allowed.
  
  Hide secrets attributes Show secrets attributes object
  
  password object | string
  
  Any of:
  object-1 object string-2 string
  
  Hide attribute Show attribute
  
  id string Required
  
  ssl object
  
  Additional properties are allowed.
  
  Hide ssl attribute Show ssl attribute object
  
  key object | string Required
  
  Any of:
  object-1 object string-2 string
  
  Hide attribute Show attribute
  
  id string Required
  
  shipper object | null
  
  Additional properties are allowed.
  
  Hide shipper attributes Show shipper attributes object | null
  
  compression_level number | null Required
  
  disk_queue_compression_enabled boolean | null Required
  
  disk_queue_enabled boolean | null
  
  Default value is false.
  
  disk_queue_encryption_enabled boolean | null Required
  
  disk_queue_max_size number | null Required
  
  disk_queue_path string | null Required
  
  loadbalance boolean | null Required
  
  max_batch_bytes number | null Required
  
  mem_queue_events number | null Required
  
  queue_flush_timeout number | null Required
  
  ssl object | null
  
  Additional properties are allowed.
  
  Hide ssl attributes Show ssl attributes object | null
  
  certificate string
  
  certificate_authorities array[string]
  
  key string
  
  verification_mode string
  
  Values are full, none, certificate, or strict.
  
  timeout number
  
  topic string
  
  type string Required
  
  Value is kafka.
  
  username array | null | boolean | number | object | string Required
  
  Any of:
  array-1 array | null boolean-2 boolean | null number-3 number | null object-4 object | null string-5 string | null
  
  version string
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

POST /api/fleet/outputs

curl \
 --request POST 'https://<KIBANA_URL>/api/fleet/outputs' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"allow_edit":["string"],"ca_sha256":"string","ca_trusted_fingerprint":"string","config_yaml":"string","hosts":["https://example.com"],"id":"string","is_default":false,"is_default_monitoring":false,"is_internal":true,"is_preconfigured":true,"name":"string","preset":"balanced","proxy_id":"string","secrets":{"ssl":{"key":{"id":"string"}}},"shipper":{"compression_level":42.0,"disk_queue_compression_enabled":true,"disk_queue_enabled":false,"disk_queue_encryption_enabled":true,"disk_queue_max_size":42.0,"disk_queue_path":"string","loadbalance":true,"max_batch_bytes":42.0,"mem_queue_events":42.0,"queue_flush_timeout":42.0},"ssl":{"certificate":"string","certificate_authorities":["string"],"key":"string","verification_mode":"full"},"type":"elasticsearch"}'

Get output

GET /api/fleet/outputs/{outputId}

Get output by ID.

[Required authorization] Route required privileges: fleet-settings-read OR fleet-agent-policies-read.

Path parameters

outputId string Required

Responses

200 application/json
Hide response attribute Show response attribute object
- item object Required
  
  Any of:
  object-1 object object-2 object object-3 object object-4 object
  
  Hide attributes Show attributes
  
  allow_edit array[string]
  
  ca_sha256 string | null
  
  ca_trusted_fingerprint string | null
  
  config_yaml string | null
  
  hosts array[string(uri)] Required
  
  At least 1 element.
  
  id string
  
  is_default boolean
  
  Default value is false.
  
  is_default_monitoring boolean
  
  Default value is false.
  
  is_internal boolean
  
  is_preconfigured boolean
  
  name string Required
  
  preset string
  
  Values are balanced, custom, throughput, scale, or latency.
  
  proxy_id string | null
  
  secrets object
  
  Additional properties are allowed.
  
  Hide secrets attribute Show secrets attribute object
  
  ssl object
  
  Additional properties are allowed.
  
  Hide ssl attribute Show ssl attribute object
  
  key object | string
  
  Any of:
  object-1 object string-2 string
  
  Hide attribute Show attribute
  
  id string Required
  
  shipper object | null
  
  Additional properties are allowed.
  
  Hide shipper attributes Show shipper attributes object | null
  
  compression_level number | null Required
  
  disk_queue_compression_enabled boolean | null Required
  
  disk_queue_enabled boolean | null
  
  Default value is false.
  
  disk_queue_encryption_enabled boolean | null Required
  
  disk_queue_max_size number | null Required
  
  disk_queue_path string | null Required
  
  loadbalance boolean | null Required
  
  max_batch_bytes number | null Required
  
  mem_queue_events number | null Required
  
  queue_flush_timeout number | null Required
  
  ssl object | null
  
  Additional properties are allowed.
  
  Hide ssl attributes Show ssl attributes object | null
  
  certificate string
  
  certificate_authorities array[string]
  
  key string
  
  verification_mode string
  
  Values are full, none, certificate, or strict.
  
  type string Required
  
  Value is elasticsearch.
  
  Hide attributes Show attributes
  
  allow_edit array[string]
  
  ca_sha256 string | null
  
  ca_trusted_fingerprint string | null
  
  config_yaml string | null
  
  hosts array[string(uri)] Required
  
  At least 1 element.
  
  id string
  
  is_default boolean
  
  Default value is false.
  
  is_default_monitoring boolean
  
  Default value is false.
  
  is_internal boolean
  
  is_preconfigured boolean
  
  kibana_api_key string | null
  
  kibana_url string | null
  
  name string Required
  
  preset string
  
  Values are balanced, custom, throughput, scale, or latency.
  
  proxy_id string | null
  
  secrets object
  
  Additional properties are allowed.
  
  Hide secrets attributes Show secrets attributes object
  
  service_token object | string
  
  Any of:
  object-1 object string-2 string
  
  Hide attribute Show attribute
  
  id string Required
  
  ssl object
  
  Additional properties are allowed.
  
  Hide ssl attribute Show ssl attribute object
  
  key object | string
  
  Any of:
  object-1 object string-2 string
  
  Hide attribute Show attribute
  
  id string Required
  
  service_token string | null
  
  shipper object | null
  
  Additional properties are allowed.
  
  Hide shipper attributes Show shipper attributes object | null
  
  compression_level number | null Required
  
  disk_queue_compression_enabled boolean | null Required
  
  disk_queue_enabled boolean | null
  
  Default value is false.
  
  disk_queue_encryption_enabled boolean | null Required
  
  disk_queue_max_size number | null Required
  
  disk_queue_path string | null Required
  
  loadbalance boolean | null Required
  
  max_batch_bytes number | null Required
  
  mem_queue_events number | null Required
  
  queue_flush_timeout number | null Required
  
  ssl object | null
  
  Additional properties are allowed.
  
  Hide ssl attributes Show ssl attributes object | null
  
  certificate string
  
  certificate_authorities array[string]
  
  key string
  
  verification_mode string
  
  Values are full, none, certificate, or strict.
  
  sync_integrations boolean
  
  sync_uninstalled_integrations boolean
  
  type string Required
  
  Value is remote_elasticsearch.
  
  Hide attributes Show attributes
  
  allow_edit array[string]
  
  ca_sha256 string | null
  
  ca_trusted_fingerprint string | null
  
  config_yaml string | null
  
  hosts array[string] Required
  
  At least 1 element.
  
  id string
  
  is_default boolean
  
  Default value is false.
  
  is_default_monitoring boolean
  
  Default value is false.
  
  is_internal boolean
  
  is_preconfigured boolean
  
  name string Required
  
  proxy_id string | null
  
  secrets object
  
  Additional properties are allowed.
  
  Hide secrets attribute Show secrets attribute object
  
  ssl object
  
  Additional properties are allowed.
  
  Hide ssl attribute Show ssl attribute object
  
  key object | string
  
  Any of:
  object-1 object string-2 string
  
  Hide attribute Show attribute
  
  id string Required
  
  shipper object | null
  
  Additional properties are allowed.
  
  Hide shipper attributes Show shipper attributes object | null
  
  compression_level number | null Required
  
  disk_queue_compression_enabled boolean | null Required
  
  disk_queue_enabled boolean | null
  
  Default value is false.
  
  disk_queue_encryption_enabled boolean | null Required
  
  disk_queue_max_size number | null Required
  
  disk_queue_path string | null Required
  
  loadbalance boolean | null Required
  
  max_batch_bytes number | null Required
  
  mem_queue_events number | null Required
  
  queue_flush_timeout number | null Required
  
  ssl object | null
  
  Additional properties are allowed.
  
  Hide ssl attributes Show ssl attributes object | null
  
  certificate string
  
  certificate_authorities array[string]
  
  key string
  
  verification_mode string
  
  Values are full, none, certificate, or strict.
  
  type string Required
  
  Value is logstash.
  
  Hide attributes Show attributes
  
  allow_edit array[string]
  
  auth_type string Required
  
  Values are none, user_pass, ssl, or kerberos.
  
  broker_timeout number
  
  ca_sha256 string | null
  
  ca_trusted_fingerprint string | null
  
  client_id string
  
  compression string
  
  Values are gzip, snappy, lz4, or none.
  
  compression_level array | null | boolean | number | object | string Required
  
  Any of:
  array-1 array | null boolean-2 boolean | null number-3 number | null object-4 object | null string-5 string | null
  
  config_yaml string | null
  
  connection_type array | null | boolean | number | object | string Required
  
  Any of:
  array-1 array | null boolean-2 boolean | null number-3 number | null object-4 object | null string-5 string | null
  
  hash object
  
  Additional properties are allowed.
  
  Hide hash attributes Show hash attributes object
  
  hash string
  
  random boolean
  
  headers array[object]
  
  Hide headers attributes Show headers attributes object
  
  key string Required
  
  value string Required
  
  hosts array[string] Required
  
  At least 1 element.
  
  id string
  
  is_default boolean
  
  Default value is false.
  
  is_default_monitoring boolean
  
  Default value is false.
  
  is_internal boolean
  
  is_preconfigured boolean
  
  key string
  
  name string Required
  
  partition string
  
  Values are random, round_robin, or hash.
  
  password array | null | boolean | number | object | string Required
  
  Any of:
  array-1 array | null boolean-2 boolean | null number-3 number | null object-4 object | null string-5 string | null
  
  proxy_id string | null
  
  random object
  
  Additional properties are allowed.
  
  Hide random attribute Show random attribute object
  
  group_events number
  
  required_acks integer
  
  Values are 1, 0, or -1.
  
  round_robin object
  
  Additional properties are allowed.
  
  Hide round_robin attribute Show round_robin attribute object
  
  group_events number
  
  sasl object | null
  
  Additional properties are allowed.
  
  Hide sasl attribute Show sasl attribute object | null
  
  mechanism string
  
  Values are PLAIN, SCRAM-SHA-256, or SCRAM-SHA-512.
  
  secrets object
  
  Additional properties are allowed.
  
  Hide secrets attributes Show secrets attributes object
  
  password object | string
  
  Any of:
  object-1 object string-2 string
  
  Hide attribute Show attribute
  
  id string Required
  
  ssl object
  
  Additional properties are allowed.
  
  Hide ssl attribute Show ssl attribute object
  
  key object | string Required
  
  Any of:
  object-1 object string-2 string
  
  Hide attribute Show attribute
  
  id string Required
  
  shipper object | null
  
  Additional properties are allowed.
  
  Hide shipper attributes Show shipper attributes object | null
  
  compression_level number | null Required
  
  disk_queue_compression_enabled boolean | null Required
  
  disk_queue_enabled boolean | null
  
  Default value is false.
  
  disk_queue_encryption_enabled boolean | null Required
  
  disk_queue_max_size number | null Required
  
  disk_queue_path string | null Required
  
  loadbalance boolean | null Required
  
  max_batch_bytes number | null Required
  
  mem_queue_events number | null Required
  
  queue_flush_timeout number | null Required
  
  ssl object | null
  
  Additional properties are allowed.
  
  Hide ssl attributes Show ssl attributes object | null
  
  certificate string
  
  certificate_authorities array[string]
  
  key string
  
  verification_mode string
  
  Values are full, none, certificate, or strict.
  
  timeout number
  
  topic string
  
  type string Required
  
  Value is kafka.
  
  username array | null | boolean | number | object | string Required
  
  Any of:
  array-1 array | null boolean-2 boolean | null number-3 number | null object-4 object | null string-5 string | null
  
  version string
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

GET /api/fleet/outputs/{outputId}

curl \
 --request GET 'https://<KIBANA_URL>/api/fleet/outputs/{outputId}' \
 --header "Authorization: $API_KEY"

Update output

PUT /api/fleet/outputs/{outputId}

Update output by ID.

[Required authorization] Route required privileges: fleet-settings-all OR fleet-agent-policies-all.

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

Path parameters

outputId string Required

application/json

Body object

allow_edit array[string]
ca_sha256 string | null
ca_trusted_fingerprint string | null
config_yaml string | null
hosts array[string(uri)]

At least 1 element.
id string
is_default boolean
is_default_monitoring boolean
is_internal boolean
is_preconfigured boolean
name string
preset string

Values are balanced, custom, throughput, scale, or latency.
proxy_id string | null
secrets object

Additional properties are NOT allowed.
Hide secrets attribute Show secrets attribute object
- ssl object
  
  Additional properties are NOT allowed.
  Hide ssl attribute Show ssl attribute object
  
  key object | string
  
  Any of:
  object-1 object string-2 string
  
  Hide attribute Show attribute
  
  id string Required
shipper object | null

Additional properties are NOT allowed.
Hide shipper attributes Show shipper attributes object | null
- compression_level number | null Required
- disk_queue_compression_enabled boolean | null Required
- disk_queue_enabled boolean | null
  
  Default value is false.
- disk_queue_encryption_enabled boolean | null Required
- disk_queue_max_size number | null Required
- disk_queue_path string | null Required
- loadbalance boolean | null Required
- max_batch_bytes number | null Required
- mem_queue_events number | null Required
- queue_flush_timeout number | null Required
ssl object | null

Additional properties are NOT allowed.
Hide ssl attributes Show ssl attributes object | null
- certificate string
- certificate_authorities array[string]
- key string
- verification_mode string
  
  Values are full, none, certificate, or strict.
type string

Value is elasticsearch.

allow_edit array[string]
ca_sha256 string | null
ca_trusted_fingerprint string | null
config_yaml string | null
hosts array[string(uri)]

At least 1 element.
id string
is_default boolean
is_default_monitoring boolean
is_internal boolean
is_preconfigured boolean
kibana_api_key string | null
kibana_url string | null
name string
preset string

Values are balanced, custom, throughput, scale, or latency.
proxy_id string | null
secrets object

Additional properties are NOT allowed.
Hide secrets attributes Show secrets attributes object
- service_token object | string
  
  Any of:
  object-1 object string-2 string
  
  Hide attribute Show attribute
  
  id string Required
- ssl object
  
  Additional properties are NOT allowed.
  Hide ssl attribute Show ssl attribute object
  
  key object | string
  
  Any of:
  object-1 object string-2 string
  
  Hide attribute Show attribute
  
  id string Required
service_token string | null
shipper object | null

Additional properties are NOT allowed.
Hide shipper attributes Show shipper attributes object | null
- compression_level number | null Required
- disk_queue_compression_enabled boolean | null Required
- disk_queue_enabled boolean | null
  
  Default value is false.
- disk_queue_encryption_enabled boolean | null Required
- disk_queue_max_size number | null Required
- disk_queue_path string | null Required
- loadbalance boolean | null Required
- max_batch_bytes number | null Required
- mem_queue_events number | null Required
- queue_flush_timeout number | null Required
ssl object | null

Additional properties are NOT allowed.
Hide ssl attributes Show ssl attributes object | null
- certificate string
- certificate_authorities array[string]
- key string
- verification_mode string
  
  Values are full, none, certificate, or strict.
sync_integrations boolean
sync_uninstalled_integrations boolean
type string

Value is remote_elasticsearch.

allow_edit array[string]
ca_sha256 string | null
ca_trusted_fingerprint string | null
config_yaml string | null
hosts array[string]

At least 1 element.
id string
is_default boolean
is_default_monitoring boolean
is_internal boolean
is_preconfigured boolean
name string
proxy_id string | null
secrets object

Additional properties are NOT allowed.
Hide secrets attribute Show secrets attribute object
- ssl object
  
  Additional properties are NOT allowed.
  Hide ssl attribute Show ssl attribute object
  
  key object | string
  
  Any of:
  object-1 object string-2 string
  
  Hide attribute Show attribute
  
  id string Required
shipper object | null

Additional properties are NOT allowed.
Hide shipper attributes Show shipper attributes object | null
- compression_level number | null Required
- disk_queue_compression_enabled boolean | null Required
- disk_queue_enabled boolean | null
  
  Default value is false.
- disk_queue_encryption_enabled boolean | null Required
- disk_queue_max_size number | null Required
- disk_queue_path string | null Required
- loadbalance boolean | null Required
- max_batch_bytes number | null Required
- mem_queue_events number | null Required
- queue_flush_timeout number | null Required
ssl object | null

Additional properties are NOT allowed.
Hide ssl attributes Show ssl attributes object | null
- certificate string
- certificate_authorities array[string]
- key string
- verification_mode string
  
  Values are full, none, certificate, or strict.
type string

Value is logstash.

allow_edit array[string]
auth_type string

Values are none, user_pass, ssl, or kerberos.
broker_timeout number
ca_sha256 string | null
ca_trusted_fingerprint string | null
client_id string
compression string

Values are gzip, snappy, lz4, or none.
compression_level array | null | boolean | number | object | string Required

Any of:
array-1 array | null boolean-2 boolean | null number-3 number | null object-4 object | null string-5 string | null
config_yaml string | null
connection_type array | null | boolean | number | object | string Required

Any of:
array-1 array | null boolean-2 boolean | null number-3 number | null object-4 object | null string-5 string | null
hash object

Additional properties are NOT allowed.
Hide hash attributes Show hash attributes object
- hash string
- random boolean
headers array[object]
Hide headers attributes Show headers attributes object
- key string Required
- value string Required
hosts array[string]

At least 1 element.
id string
is_default boolean

Default value is false.
is_default_monitoring boolean

Default value is false.
is_internal boolean
is_preconfigured boolean
key string
name string Required
partition string

Values are random, round_robin, or hash.
password array | null | boolean | number | object | string Required

Any of:
array-1 array | null boolean-2 boolean | null number-3 number | null object-4 object | null string-5 string | null
proxy_id string | null
random object

Additional properties are NOT allowed.
Hide random attribute Show random attribute object
- group_events number
required_acks integer

Values are 1, 0, or -1.
round_robin object

Additional properties are NOT allowed.
Hide round_robin attribute Show round_robin attribute object
- group_events number
sasl object | null

Additional properties are NOT allowed.
Hide sasl attribute Show sasl attribute object | null
- mechanism string
  
  Values are PLAIN, SCRAM-SHA-256, or SCRAM-SHA-512.
secrets object

Additional properties are NOT allowed.
Hide secrets attributes Show secrets attributes object
- password object | string
  
  Any of:
  object-1 object string-2 string
  
  Hide attribute Show attribute
  
  id string Required
- ssl object
  
  Additional properties are NOT allowed.
  Hide ssl attribute Show ssl attribute object
  
  key object | string Required
  
  Any of:
  object-1 object string-2 string
  
  Hide attribute Show attribute
  
  id string Required
shipper object | null

Additional properties are NOT allowed.
Hide shipper attributes Show shipper attributes object | null
- compression_level number | null Required
- disk_queue_compression_enabled boolean | null Required
- disk_queue_enabled boolean | null
  
  Default value is false.
- disk_queue_encryption_enabled boolean | null Required
- disk_queue_max_size number | null Required
- disk_queue_path string | null Required
- loadbalance boolean | null Required
- max_batch_bytes number | null Required
- mem_queue_events number | null Required
- queue_flush_timeout number | null Required
ssl object | null

Additional properties are NOT allowed.
Hide ssl attributes Show ssl attributes object | null
- certificate string
- certificate_authorities array[string]
- key string
- verification_mode string
  
  Values are full, none, certificate, or strict.
timeout number
topic string
type string

Value is kafka.
username array | null | boolean | number | object | string Required

Any of:
array-1 array | null boolean-2 boolean | null number-3 number | null object-4 object | null string-5 string | null
version string

Responses

200 application/json
Hide response attribute Show response attribute object
- item object Required
  
  Any of:
  object-1 object object-2 object object-3 object object-4 object
  
  Hide attributes Show attributes
  
  allow_edit array[string]
  
  ca_sha256 string | null
  
  ca_trusted_fingerprint string | null
  
  config_yaml string | null
  
  hosts array[string(uri)] Required
  
  At least 1 element.
  
  id string
  
  is_default boolean
  
  Default value is false.
  
  is_default_monitoring boolean
  
  Default value is false.
  
  is_internal boolean
  
  is_preconfigured boolean
  
  name string Required
  
  preset string
  
  Values are balanced, custom, throughput, scale, or latency.
  
  proxy_id string | null
  
  secrets object
  
  Additional properties are allowed.
  
  Hide secrets attribute Show secrets attribute object
  
  ssl object
  
  Additional properties are allowed.
  
  Hide ssl attribute Show ssl attribute object
  
  key object | string
  
  Any of:
  object-1 object string-2 string
  
  Hide attribute Show attribute
  
  id string Required
  
  shipper object | null
  
  Additional properties are allowed.
  
  Hide shipper attributes Show shipper attributes object | null
  
  compression_level number | null Required
  
  disk_queue_compression_enabled boolean | null Required
  
  disk_queue_enabled boolean | null
  
  Default value is false.
  
  disk_queue_encryption_enabled boolean | null Required
  
  disk_queue_max_size number | null Required
  
  disk_queue_path string | null Required
  
  loadbalance boolean | null Required
  
  max_batch_bytes number | null Required
  
  mem_queue_events number | null Required
  
  queue_flush_timeout number | null Required
  
  ssl object | null
  
  Additional properties are allowed.
  
  Hide ssl attributes Show ssl attributes object | null
  
  certificate string
  
  certificate_authorities array[string]
  
  key string
  
  verification_mode string
  
  Values are full, none, certificate, or strict.
  
  type string Required
  
  Value is elasticsearch.
  
  Hide attributes Show attributes
  
  allow_edit array[string]
  
  ca_sha256 string | null
  
  ca_trusted_fingerprint string | null
  
  config_yaml string | null
  
  hosts array[string(uri)] Required
  
  At least 1 element.
  
  id string
  
  is_default boolean
  
  Default value is false.
  
  is_default_monitoring boolean
  
  Default value is false.
  
  is_internal boolean
  
  is_preconfigured boolean
  
  kibana_api_key string | null
  
  kibana_url string | null
  
  name string Required
  
  preset string
  
  Values are balanced, custom, throughput, scale, or latency.
  
  proxy_id string | null
  
  secrets object
  
  Additional properties are allowed.
  
  Hide secrets attributes Show secrets attributes object
  
  service_token object | string
  
  Any of:
  object-1 object string-2 string
  
  Hide attribute Show attribute
  
  id string Required
  
  ssl object
  
  Additional properties are allowed.
  
  Hide ssl attribute Show ssl attribute object
  
  key object | string
  
  Any of:
  object-1 object string-2 string
  
  Hide attribute Show attribute
  
  id string Required
  
  service_token string | null
  
  shipper object | null
  
  Additional properties are allowed.
  
  Hide shipper attributes Show shipper attributes object | null
  
  compression_level number | null Required
  
  disk_queue_compression_enabled boolean | null Required
  
  disk_queue_enabled boolean | null
  
  Default value is false.
  
  disk_queue_encryption_enabled boolean | null Required
  
  disk_queue_max_size number | null Required
  
  disk_queue_path string | null Required
  
  loadbalance boolean | null Required
  
  max_batch_bytes number | null Required
  
  mem_queue_events number | null Required
  
  queue_flush_timeout number | null Required
  
  ssl object | null
  
  Additional properties are allowed.
  
  Hide ssl attributes Show ssl attributes object | null
  
  certificate string
  
  certificate_authorities array[string]
  
  key string
  
  verification_mode string
  
  Values are full, none, certificate, or strict.
  
  sync_integrations boolean
  
  sync_uninstalled_integrations boolean
  
  type string Required
  
  Value is remote_elasticsearch.
  
  Hide attributes Show attributes
  
  allow_edit array[string]
  
  ca_sha256 string | null
  
  ca_trusted_fingerprint string | null
  
  config_yaml string | null
  
  hosts array[string] Required
  
  At least 1 element.
  
  id string
  
  is_default boolean
  
  Default value is false.
  
  is_default_monitoring boolean
  
  Default value is false.
  
  is_internal boolean
  
  is_preconfigured boolean
  
  name string Required
  
  proxy_id string | null
  
  secrets object
  
  Additional properties are allowed.
  
  Hide secrets attribute Show secrets attribute object
  
  ssl object
  
  Additional properties are allowed.
  
  Hide ssl attribute Show ssl attribute object
  
  key object | string
  
  Any of:
  object-1 object string-2 string
  
  Hide attribute Show attribute
  
  id string Required
  
  shipper object | null
  
  Additional properties are allowed.
  
  Hide shipper attributes Show shipper attributes object | null
  
  compression_level number | null Required
  
  disk_queue_compression_enabled boolean | null Required
  
  disk_queue_enabled boolean | null
  
  Default value is false.
  
  disk_queue_encryption_enabled boolean | null Required
  
  disk_queue_max_size number | null Required
  
  disk_queue_path string | null Required
  
  loadbalance boolean | null Required
  
  max_batch_bytes number | null Required
  
  mem_queue_events number | null Required
  
  queue_flush_timeout number | null Required
  
  ssl object | null
  
  Additional properties are allowed.
  
  Hide ssl attributes Show ssl attributes object | null
  
  certificate string
  
  certificate_authorities array[string]
  
  key string
  
  verification_mode string
  
  Values are full, none, certificate, or strict.
  
  type string Required
  
  Value is logstash.
  
  Hide attributes Show attributes
  
  allow_edit array[string]
  
  auth_type string Required
  
  Values are none, user_pass, ssl, or kerberos.
  
  broker_timeout number
  
  ca_sha256 string | null
  
  ca_trusted_fingerprint string | null
  
  client_id string
  
  compression string
  
  Values are gzip, snappy, lz4, or none.
  
  compression_level array | null | boolean | number | object | string Required
  
  Any of:
  array-1 array | null boolean-2 boolean | null number-3 number | null object-4 object | null string-5 string | null
  
  config_yaml string | null
  
  connection_type array | null | boolean | number | object | string Required
  
  Any of:
  array-1 array | null boolean-2 boolean | null number-3 number | null object-4 object | null string-5 string | null
  
  hash object
  
  Additional properties are allowed.
  
  Hide hash attributes Show hash attributes object
  
  hash string
  
  random boolean
  
  headers array[object]
  
  Hide headers attributes Show headers attributes object
  
  key string Required
  
  value string Required
  
  hosts array[string] Required
  
  At least 1 element.
  
  id string
  
  is_default boolean
  
  Default value is false.
  
  is_default_monitoring boolean
  
  Default value is false.
  
  is_internal boolean
  
  is_preconfigured boolean
  
  key string
  
  name string Required
  
  partition string
  
  Values are random, round_robin, or hash.
  
  password array | null | boolean | number | object | string Required
  
  Any of:
  array-1 array | null boolean-2 boolean | null number-3 number | null object-4 object | null string-5 string | null
  
  proxy_id string | null
  
  random object
  
  Additional properties are allowed.
  
  Hide random attribute Show random attribute object
  
  group_events number
  
  required_acks integer
  
  Values are 1, 0, or -1.
  
  round_robin object
  
  Additional properties are allowed.
  
  Hide round_robin attribute Show round_robin attribute object
  
  group_events number
  
  sasl object | null
  
  Additional properties are allowed.
  
  Hide sasl attribute Show sasl attribute object | null
  
  mechanism string
  
  Values are PLAIN, SCRAM-SHA-256, or SCRAM-SHA-512.
  
  secrets object
  
  Additional properties are allowed.
  
  Hide secrets attributes Show secrets attributes object
  
  password object | string
  
  Any of:
  object-1 object string-2 string
  
  Hide attribute Show attribute
  
  id string Required
  
  ssl object
  
  Additional properties are allowed.
  
  Hide ssl attribute Show ssl attribute object
  
  key object | string Required
  
  Any of:
  object-1 object string-2 string
  
  Hide attribute Show attribute
  
  id string Required
  
  shipper object | null
  
  Additional properties are allowed.
  
  Hide shipper attributes Show shipper attributes object | null
  
  compression_level number | null Required
  
  disk_queue_compression_enabled boolean | null Required
  
  disk_queue_enabled boolean | null
  
  Default value is false.
  
  disk_queue_encryption_enabled boolean | null Required
  
  disk_queue_max_size number | null Required
  
  disk_queue_path string | null Required
  
  loadbalance boolean | null Required
  
  max_batch_bytes number | null Required
  
  mem_queue_events number | null Required
  
  queue_flush_timeout number | null Required
  
  ssl object | null
  
  Additional properties are allowed.
  
  Hide ssl attributes Show ssl attributes object | null
  
  certificate string
  
  certificate_authorities array[string]
  
  key string
  
  verification_mode string
  
  Values are full, none, certificate, or strict.
  
  timeout number
  
  topic string
  
  type string Required
  
  Value is kafka.
  
  username array | null | boolean | number | object | string Required
  
  Any of:
  array-1 array | null boolean-2 boolean | null number-3 number | null object-4 object | null string-5 string | null
  
  version string
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

PUT /api/fleet/outputs/{outputId}

curl \
 --request PUT 'https://<KIBANA_URL>/api/fleet/outputs/{outputId}' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"allow_edit":["string"],"ca_sha256":"string","ca_trusted_fingerprint":"string","config_yaml":"string","hosts":["https://example.com"],"id":"string","is_default":true,"is_default_monitoring":true,"is_internal":true,"is_preconfigured":true,"name":"string","preset":"balanced","proxy_id":"string","secrets":{"ssl":{"key":{"id":"string"}}},"shipper":{"compression_level":42.0,"disk_queue_compression_enabled":true,"disk_queue_enabled":false,"disk_queue_encryption_enabled":true,"disk_queue_max_size":42.0,"disk_queue_path":"string","loadbalance":true,"max_batch_bytes":42.0,"mem_queue_events":42.0,"queue_flush_timeout":42.0},"ssl":{"certificate":"string","certificate_authorities":["string"],"key":"string","verification_mode":"full"},"type":"elasticsearch"}'

Delete output

DELETE /api/fleet/outputs/{outputId}

Delete output by ID.

[Required authorization] Route required privileges: fleet-settings-all.

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

Path parameters

outputId string Required

Responses

200 application/json
Hide response attribute Show response attribute object
- id string Required
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number
404 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

DELETE /api/fleet/outputs/{outputId}

curl \
 --request DELETE 'https://<KIBANA_URL>/api/fleet/outputs/{outputId}' \
 --header "Authorization: $API_KEY" \
 --header "kbn-xsrf: true"

Get the latest output health

GET /api/fleet/outputs/{outputId}/health

[Required authorization] Route required privileges: fleet-settings-read.

Path parameters

outputId string Required

Responses

200 application/json
Hide response attributes Show response attributes object
- message string Required
  
  long message if unhealthy
- state string Required
  
  state of output, HEALTHY or DEGRADED
- timestamp string Required
  
  timestamp of reported state
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

GET /api/fleet/outputs/{outputId}/health

curl \
 --request GET 'https://<KIBANA_URL>/api/fleet/outputs/{outputId}/health' \
 --header "Authorization: $API_KEY"

Get package policies

GET /api/fleet/package_policies

Query parameters

page number
perPage number
sortField string
sortOrder string

Values are desc or asc.
showUpgradeable boolean
kuery string
format string

Values are simplified or legacy.
withAgentCount boolean

Responses

200 application/json
Hide response attributes Show response attributes object
- items array[object] Required
  
  Hide items attributes Show items attributes object
  
  additional_datastreams_permissions array[string] | null
  
  Additional datastream permissions, that will be added to the agent policy.
  
  agents number
  
  created_at string Required
  
  created_by string Required
  
  description string
  
  Package policy description
  
  elasticsearch object
  
  Additional properties are allowed.
  
  Hide elasticsearch attribute Show elasticsearch attribute object
  
  privileges object
  
  Additional properties are allowed.
  
  Hide privileges attribute Show privileges attribute object
  
  cluster array[string]
  
  enabled boolean Required
  
  id string Required
  
  inputs array[object] | object Required
  
  Any of:
  array-1 array[object] object-2 object
  
  Hide attributes Show attributes object
  
  config object
  
  Package variable (see integration documentation for more information)
  
  Hide config attribute Show config attribute object
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  frozen boolean
  
  type string
  
  enabled boolean Required
  
  id string
  
  keep_enabled boolean
  
  policy_template string
  
  streams array[object] Required
  
  Hide streams attributes Show streams attributes object
  
  config object
  
  Package variable (see integration documentation for more information)
  
  Hide config attribute Show config attribute object
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  frozen boolean
  
  type string
  
  data_stream object Required
  
  Additional properties are NOT allowed.
  
  Hide data_stream attributes Show data_stream attributes object
  
  dataset string Required
  
  elasticsearch object
  
  Additional properties are NOT allowed.
  
  Hide elasticsearch attributes Show elasticsearch attributes object
  
  dynamic_dataset boolean
  
  dynamic_namespace boolean
  
  privileges object
  
  Additional properties are NOT allowed.
  
  Hide privileges attribute Show privileges attribute object
  
  indices array[string]
  
  type string Required
  
  enabled boolean Required
  
  id string
  
  keep_enabled boolean
  
  release string
  
  Values are ga, beta, or experimental.
  
  vars object
  
  Package variable (see integration documentation for more information)
  
  Hide vars attribute Show vars attribute object
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  frozen boolean
  
  type string
  
  type string Required
  
  vars object
  
  Package variable (see integration documentation for more information)
  
  Hide vars attribute Show vars attribute object
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  frozen boolean
  
  type string
  
  Package policy inputs (see integration documentation to know what inputs are available)
  
  Hide attribute Show attribute
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  enabled boolean
  
  enable or disable that input, (default to true)
  
  streams object
  
  Input streams (see integration documentation to know what streams are available)
  
  Hide streams attribute Show streams attribute object
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  enabled boolean
  
  enable or disable that stream, (default to true)
  
  vars object
  
  Input/stream level variable (see integration documentation for more information)
  
  vars object
  
  Input/stream level variable (see integration documentation for more information)
  
  is_managed boolean
  
  name string Required
  
  Package policy name (should be unique)
  
  namespace string
  
  The package policy namespace. Leave blank to inherit the agent policy's namespace.
  
  output_id string | null
  
  overrides object | null
  
  Override settings that are defined in the package policy. The override option should be used only in unusual circumstances and not as a routine procedure.
  
  Additional properties are NOT allowed.
  
  Hide overrides attribute Show overrides attribute object | null
  
  inputs object
  
  Additional properties are allowed.
  
  package object
  
  Additional properties are NOT allowed.
  
  Hide package attributes Show package attributes object
  
  experimental_data_stream_features array[object]
  
  Hide experimental_data_stream_features attributes Show experimental_data_stream_features attributes object
  
  data_stream string Required
  
  features object Required
  
  Additional properties are NOT allowed.
  
  Hide features attributes Show features attributes object
  
  doc_value_only_numeric boolean
  
  doc_value_only_other boolean
  
  synthetic_source boolean
  
  tsdb boolean
  
  name string Required
  
  Package name
  
  requires_root boolean
  
  title string
  
  version string Required
  
  Package version
  
  policy_id string | null Deprecated
  
  Agent policy ID where that package policy will be added
  
  policy_ids array[string]
  
  Agent policy IDs where that package policy will be added
  
  revision number Required
  
  secret_references array[object]
  
  Hide secret_references attribute Show secret_references attribute object
  
  id string Required
  
  spaceIds array[string]
  
  supports_agentless boolean | null
  
  Indicates whether the package policy belongs to an agentless agent policy.
  
  Default value is false.
  
  updated_at string Required
  
  updated_by string Required
  
  vars object
  
  Any of:
  object-1 object object-2 object
  
  Package variable (see integration documentation for more information)
  
  Hide attribute Show attribute
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  frozen boolean
  
  type string
  
  version string
- page number Required
- perPage number Required
- total number Required
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

GET /api/fleet/package_policies

curl \
 --request GET 'https://<KIBANA_URL>/api/fleet/package_policies' \
 --header "Authorization: $API_KEY"

Create a package policy

POST /api/fleet/package_policies

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

Query parameters

format string

Values are simplified or legacy.

application/json

Body object

You should use inputs as an object and not use the deprecated inputs array.

additional_datastreams_permissions array[string] | null

Additional datastream permissions, that will be added to the agent policy.
description string

Package policy description
enabled boolean
force boolean

Force package policy creation even if package is not verified, or if the agent policy is managed.
id string

Package policy unique identifier
inputs array[object] Required
Hide inputs attributes Show inputs attributes object
- config object
  
  Package variable (see integration documentation for more information)
  Hide config attribute Show config attribute object
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  frozen boolean
  
  type string
- enabled boolean Required
- id string
- keep_enabled boolean
- policy_template string
- streams array[object]
  Hide streams attributes Show streams attributes object
  
  config object
  
  Package variable (see integration documentation for more information)
  
  Hide config attribute Show config attribute object
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  frozen boolean
  
  type string
  
  data_stream object Required
  
  Additional properties are NOT allowed.
  
  Hide data_stream attributes Show data_stream attributes object
  
  dataset string Required
  
  elasticsearch object
  
  Additional properties are NOT allowed.
  
  Hide elasticsearch attributes Show elasticsearch attributes object
  
  dynamic_dataset boolean
  
  dynamic_namespace boolean
  
  privileges object
  
  Additional properties are NOT allowed.
  
  Hide privileges attribute Show privileges attribute object
  
  indices array[string]
  
  type string Required
  
  enabled boolean Required
  
  id string
  
  keep_enabled boolean
  
  release string
  
  Values are ga, beta, or experimental.
  
  vars object
  
  Package variable (see integration documentation for more information)
  
  Hide vars attribute Show vars attribute object
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  frozen boolean
  
  type string
- type string Required
- vars object
  
  Package variable (see integration documentation for more information)
  Hide vars attribute Show vars attribute object
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  frozen boolean
  
  type string
is_managed boolean
name string Required

Package policy name (should be unique)
namespace string

The package policy namespace. Leave blank to inherit the agent policy's namespace.
output_id string | null
overrides object | null

Override settings that are defined in the package policy. The override option should be used only in unusual circumstances and not as a routine procedure.

Additional properties are NOT allowed.
Hide overrides attribute Show overrides attribute object | null
- inputs object
  
  Additional properties are allowed.
package object

Additional properties are NOT allowed.
Hide package attributes Show package attributes object
- experimental_data_stream_features array[object]
  Hide experimental_data_stream_features attributes Show experimental_data_stream_features attributes object
  
  data_stream string Required
  
  features object Required
  
  Additional properties are NOT allowed.
  
  Hide features attributes Show features attributes object
  
  doc_value_only_numeric boolean
  
  doc_value_only_other boolean
  
  synthetic_source boolean
  
  tsdb boolean
- name string Required
  
  Package name
- requires_root boolean
- title string
- version string Required
  
  Package version
policy_id string | null Deprecated

Agent policy ID where that package policy will be added
policy_ids array[string]

Agent policy IDs where that package policy will be added
spaceIds array[string]
supports_agentless boolean | null

Indicates whether the package policy belongs to an agentless agent policy.

Default value is false.
vars object

Package variable (see integration documentation for more information)
Hide vars attribute Show vars attribute object
- * object Additional properties
  
  Additional properties are NOT allowed.
  Hide * attributes Show * attributes object
  
  frozen boolean
  
  type string

additional_datastreams_permissions array[string] | null

Additional datastream permissions, that will be added to the agent policy.
description string
force boolean
id string
inputs object

Package policy inputs (see integration documentation to know what inputs are available)
Hide inputs attribute Show inputs attribute object
- * object Additional properties
  
  Additional properties are NOT allowed.
  Hide * attributes Show * attributes object
  
  enabled boolean
  
  enable or disable that input, (default to true)
  
  streams object
  
  Input streams (see integration documentation to know what streams are available)
  
  Hide streams attribute Show streams attribute object
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  enabled boolean
  
  enable or disable that stream, (default to true)
  
  vars object
  
  Input/stream level variable (see integration documentation for more information)
  
  vars object
  
  Input/stream level variable (see integration documentation for more information)
name string Required
namespace string
output_id string | null
package object Required

Additional properties are NOT allowed.
Hide package attributes Show package attributes object
- experimental_data_stream_features array[object]
  Hide experimental_data_stream_features attributes Show experimental_data_stream_features attributes object
  
  data_stream string Required
  
  features object Required
  
  Additional properties are NOT allowed.
  
  Hide features attributes Show features attributes object
  
  doc_value_only_numeric boolean
  
  doc_value_only_other boolean
  
  synthetic_source boolean
  
  tsdb boolean
- name string Required
  
  Package name
- requires_root boolean
- title string
- version string Required
  
  Package version
policy_id string | null
policy_ids array[string]
supports_agentless boolean | null

Indicates whether the package policy belongs to an agentless agent policy.

Default value is false.
vars object

Input/stream level variable (see integration documentation for more information)

Responses

200 application/json
Hide response attribute Show response attribute object
- item object Required
  
  Additional properties are NOT allowed.
  
  Hide item attributes Show item attributes object
  
  additional_datastreams_permissions array[string] | null
  
  Additional datastream permissions, that will be added to the agent policy.
  
  agents number
  
  created_at string Required
  
  created_by string Required
  
  description string
  
  Package policy description
  
  elasticsearch object
  
  Additional properties are allowed.
  
  Hide elasticsearch attribute Show elasticsearch attribute object
  
  privileges object
  
  Additional properties are allowed.
  
  Hide privileges attribute Show privileges attribute object
  
  cluster array[string]
  
  enabled boolean Required
  
  id string Required
  
  inputs array[object] | object Required
  
  Any of:
  array-1 array[object] object-2 object
  
  Hide attributes Show attributes object
  
  config object
  
  Package variable (see integration documentation for more information)
  
  Hide config attribute Show config attribute object
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  frozen boolean
  
  type string
  
  enabled boolean Required
  
  id string
  
  keep_enabled boolean
  
  policy_template string
  
  streams array[object] Required
  
  Hide streams attributes Show streams attributes object
  
  config object
  
  Package variable (see integration documentation for more information)
  
  Hide config attribute Show config attribute object
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  frozen boolean
  
  type string
  
  data_stream object Required
  
  Additional properties are NOT allowed.
  
  Hide data_stream attributes Show data_stream attributes object
  
  dataset string Required
  
  elasticsearch object
  
  Additional properties are NOT allowed.
  
  Hide elasticsearch attributes Show elasticsearch attributes object
  
  dynamic_dataset boolean
  
  dynamic_namespace boolean
  
  privileges object
  
  Additional properties are NOT allowed.
  
  Hide privileges attribute Show privileges attribute object
  
  indices array[string]
  
  type string Required
  
  enabled boolean Required
  
  id string
  
  keep_enabled boolean
  
  release string
  
  Values are ga, beta, or experimental.
  
  vars object
  
  Package variable (see integration documentation for more information)
  
  Hide vars attribute Show vars attribute object
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  frozen boolean
  
  type string
  
  type string Required
  
  vars object
  
  Package variable (see integration documentation for more information)
  
  Hide vars attribute Show vars attribute object
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  frozen boolean
  
  type string
  
  Package policy inputs (see integration documentation to know what inputs are available)
  
  Hide attribute Show attribute
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  enabled boolean
  
  enable or disable that input, (default to true)
  
  streams object
  
  Input streams (see integration documentation to know what streams are available)
  
  Hide streams attribute Show streams attribute object
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  enabled boolean
  
  enable or disable that stream, (default to true)
  
  vars object
  
  Input/stream level variable (see integration documentation for more information)
  
  vars object
  
  Input/stream level variable (see integration documentation for more information)
  
  is_managed boolean
  
  name string Required
  
  Package policy name (should be unique)
  
  namespace string
  
  The package policy namespace. Leave blank to inherit the agent policy's namespace.
  
  output_id string | null
  
  overrides object | null
  
  Override settings that are defined in the package policy. The override option should be used only in unusual circumstances and not as a routine procedure.
  
  Additional properties are NOT allowed.
  
  Hide overrides attribute Show overrides attribute object | null
  
  inputs object
  
  Additional properties are allowed.
  
  package object
  
  Additional properties are NOT allowed.
  
  Hide package attributes Show package attributes object
  
  experimental_data_stream_features array[object]
  
  Hide experimental_data_stream_features attributes Show experimental_data_stream_features attributes object
  
  data_stream string Required
  
  features object Required
  
  Additional properties are NOT allowed.
  
  Hide features attributes Show features attributes object
  
  doc_value_only_numeric boolean
  
  doc_value_only_other boolean
  
  synthetic_source boolean
  
  tsdb boolean
  
  name string Required
  
  Package name
  
  requires_root boolean
  
  title string
  
  version string Required
  
  Package version
  
  policy_id string | null Deprecated
  
  Agent policy ID where that package policy will be added
  
  policy_ids array[string]
  
  Agent policy IDs where that package policy will be added
  
  revision number Required
  
  secret_references array[object]
  
  Hide secret_references attribute Show secret_references attribute object
  
  id string Required
  
  spaceIds array[string]
  
  supports_agentless boolean | null
  
  Indicates whether the package policy belongs to an agentless agent policy.
  
  Default value is false.
  
  updated_at string Required
  
  updated_by string Required
  
  vars object
  
  Any of:
  object-1 object object-2 object
  
  Package variable (see integration documentation for more information)
  
  Hide attribute Show attribute
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  frozen boolean
  
  type string
  
  version string
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number
409 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

POST /api/fleet/package_policies

curl \
 --request POST 'https://<KIBANA_URL>/api/fleet/package_policies' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"additional_datastreams_permissions":["string"],"description":"string","enabled":true,"force":true,"id":"string","inputs":[{"config":{"additionalProperty1":{"frozen":true,"type":"string"},"additionalProperty2":{"frozen":true,"type":"string"}},"enabled":true,"id":"string","keep_enabled":true,"policy_template":"string","streams":[{"config":{"additionalProperty1":{"frozen":true,"type":"string"},"additionalProperty2":{"frozen":true,"type":"string"}},"data_stream":{"dataset":"string","elasticsearch":{"dynamic_dataset":true,"dynamic_namespace":true,"privileges":{"indices":["string"]}},"type":"string"},"enabled":true,"id":"string","keep_enabled":true,"release":"ga","vars":{"additionalProperty1":{"frozen":true,"type":"string"},"additionalProperty2":{"frozen":true,"type":"string"}}}],"type":"string","vars":{"additionalProperty1":{"frozen":true,"type":"string"},"additionalProperty2":{"frozen":true,"type":"string"}}}],"is_managed":true,"name":"string","namespace":"string","output_id":"string","overrides":{"inputs":{}},"package":{"experimental_data_stream_features":[{"data_stream":"string","features":{"doc_value_only_numeric":true,"doc_value_only_other":true,"synthetic_source":true,"tsdb":true}}],"name":"string","requires_root":true,"title":"string","version":"string"},"policy_id":"string","policy_ids":["string"],"spaceIds":["string"],"supports_agentless":false,"vars":{"additionalProperty1":{"frozen":true,"type":"string"},"additionalProperty2":{"frozen":true,"type":"string"}}}'

Bulk get package policies

POST /api/fleet/package_policies/_bulk_get

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

Query parameters

format string

Values are simplified or legacy.

application/json

Body

ids array[string] Required

list of package policy ids
ignoreMissing boolean

Responses

200 application/json
Hide response attribute Show response attribute object
- items array[object] Required
  
  Hide items attributes Show items attributes object
  
  additional_datastreams_permissions array[string] | null
  
  Additional datastream permissions, that will be added to the agent policy.
  
  agents number
  
  created_at string Required
  
  created_by string Required
  
  description string
  
  Package policy description
  
  elasticsearch object
  
  Additional properties are allowed.
  
  Hide elasticsearch attribute Show elasticsearch attribute object
  
  privileges object
  
  Additional properties are allowed.
  
  Hide privileges attribute Show privileges attribute object
  
  cluster array[string]
  
  enabled boolean Required
  
  id string Required
  
  inputs array[object] | object Required
  
  Any of:
  array-1 array[object] object-2 object
  
  Hide attributes Show attributes object
  
  config object
  
  Package variable (see integration documentation for more information)
  
  Hide config attribute Show config attribute object
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  frozen boolean
  
  type string
  
  enabled boolean Required
  
  id string
  
  keep_enabled boolean
  
  policy_template string
  
  streams array[object] Required
  
  Hide streams attributes Show streams attributes object
  
  config object
  
  Package variable (see integration documentation for more information)
  
  Hide config attribute Show config attribute object
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  frozen boolean
  
  type string
  
  data_stream object Required
  
  Additional properties are NOT allowed.
  
  Hide data_stream attributes Show data_stream attributes object
  
  dataset string Required
  
  elasticsearch object
  
  Additional properties are NOT allowed.
  
  Hide elasticsearch attributes Show elasticsearch attributes object
  
  dynamic_dataset boolean
  
  dynamic_namespace boolean
  
  privileges object
  
  Additional properties are NOT allowed.
  
  Hide privileges attribute Show privileges attribute object
  
  indices array[string]
  
  type string Required
  
  enabled boolean Required
  
  id string
  
  keep_enabled boolean
  
  release string
  
  Values are ga, beta, or experimental.
  
  vars object
  
  Package variable (see integration documentation for more information)
  
  Hide vars attribute Show vars attribute object
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  frozen boolean
  
  type string
  
  type string Required
  
  vars object
  
  Package variable (see integration documentation for more information)
  
  Hide vars attribute Show vars attribute object
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  frozen boolean
  
  type string
  
  Package policy inputs (see integration documentation to know what inputs are available)
  
  Hide attribute Show attribute
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  enabled boolean
  
  enable or disable that input, (default to true)
  
  streams object
  
  Input streams (see integration documentation to know what streams are available)
  
  Hide streams attribute Show streams attribute object
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  enabled boolean
  
  enable or disable that stream, (default to true)
  
  vars object
  
  Input/stream level variable (see integration documentation for more information)
  
  vars object
  
  Input/stream level variable (see integration documentation for more information)
  
  is_managed boolean
  
  name string Required
  
  Package policy name (should be unique)
  
  namespace string
  
  The package policy namespace. Leave blank to inherit the agent policy's namespace.
  
  output_id string | null
  
  overrides object | null
  
  Override settings that are defined in the package policy. The override option should be used only in unusual circumstances and not as a routine procedure.
  
  Additional properties are NOT allowed.
  
  Hide overrides attribute Show overrides attribute object | null
  
  inputs object
  
  Additional properties are allowed.
  
  package object
  
  Additional properties are NOT allowed.
  
  Hide package attributes Show package attributes object
  
  experimental_data_stream_features array[object]
  
  Hide experimental_data_stream_features attributes Show experimental_data_stream_features attributes object
  
  data_stream string Required
  
  features object Required
  
  Additional properties are NOT allowed.
  
  Hide features attributes Show features attributes object
  
  doc_value_only_numeric boolean
  
  doc_value_only_other boolean
  
  synthetic_source boolean
  
  tsdb boolean
  
  name string Required
  
  Package name
  
  requires_root boolean
  
  title string
  
  version string Required
  
  Package version
  
  policy_id string | null Deprecated
  
  Agent policy ID where that package policy will be added
  
  policy_ids array[string]
  
  Agent policy IDs where that package policy will be added
  
  revision number Required
  
  secret_references array[object]
  
  Hide secret_references attribute Show secret_references attribute object
  
  id string Required
  
  spaceIds array[string]
  
  supports_agentless boolean | null
  
  Indicates whether the package policy belongs to an agentless agent policy.
  
  Default value is false.
  
  updated_at string Required
  
  updated_by string Required
  
  vars object
  
  Any of:
  object-1 object object-2 object
  
  Package variable (see integration documentation for more information)
  
  Hide attribute Show attribute
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  frozen boolean
  
  type string
  
  version string
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number
404 application/json
Hide response attribute Show response attribute object
- message string Required

POST /api/fleet/package_policies/_bulk_get

curl \
 --request POST 'https://<KIBANA_URL>/api/fleet/package_policies/_bulk_get' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"ids":["string"],"ignoreMissing":true}'

Get a package policy

GET /api/fleet/package_policies/{packagePolicyId}

Get a package policy by ID.

Path parameters

packagePolicyId string Required

Query parameters

format string

Values are simplified or legacy.

Responses

200 application/json
Hide response attribute Show response attribute object
- item object Required
  
  Additional properties are NOT allowed.
  
  Hide item attributes Show item attributes object
  
  additional_datastreams_permissions array[string] | null
  
  Additional datastream permissions, that will be added to the agent policy.
  
  agents number
  
  created_at string Required
  
  created_by string Required
  
  description string
  
  Package policy description
  
  elasticsearch object
  
  Additional properties are allowed.
  
  Hide elasticsearch attribute Show elasticsearch attribute object
  
  privileges object
  
  Additional properties are allowed.
  
  Hide privileges attribute Show privileges attribute object
  
  cluster array[string]
  
  enabled boolean Required
  
  id string Required
  
  inputs array[object] | object Required
  
  Any of:
  array-1 array[object] object-2 object
  
  Hide attributes Show attributes object
  
  config object
  
  Package variable (see integration documentation for more information)
  
  Hide config attribute Show config attribute object
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  frozen boolean
  
  type string
  
  enabled boolean Required
  
  id string
  
  keep_enabled boolean
  
  policy_template string
  
  streams array[object] Required
  
  Hide streams attributes Show streams attributes object
  
  config object
  
  Package variable (see integration documentation for more information)
  
  Hide config attribute Show config attribute object
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  frozen boolean
  
  type string
  
  data_stream object Required
  
  Additional properties are NOT allowed.
  
  Hide data_stream attributes Show data_stream attributes object
  
  dataset string Required
  
  elasticsearch object
  
  Additional properties are NOT allowed.
  
  Hide elasticsearch attributes Show elasticsearch attributes object
  
  dynamic_dataset boolean
  
  dynamic_namespace boolean
  
  privileges object
  
  Additional properties are NOT allowed.
  
  Hide privileges attribute Show privileges attribute object
  
  indices array[string]
  
  type string Required
  
  enabled boolean Required
  
  id string
  
  keep_enabled boolean
  
  release string
  
  Values are ga, beta, or experimental.
  
  vars object
  
  Package variable (see integration documentation for more information)
  
  Hide vars attribute Show vars attribute object
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  frozen boolean
  
  type string
  
  type string Required
  
  vars object
  
  Package variable (see integration documentation for more information)
  
  Hide vars attribute Show vars attribute object
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  frozen boolean
  
  type string
  
  Package policy inputs (see integration documentation to know what inputs are available)
  
  Hide attribute Show attribute
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  enabled boolean
  
  enable or disable that input, (default to true)
  
  streams object
  
  Input streams (see integration documentation to know what streams are available)
  
  Hide streams attribute Show streams attribute object
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  enabled boolean
  
  enable or disable that stream, (default to true)
  
  vars object
  
  Input/stream level variable (see integration documentation for more information)
  
  vars object
  
  Input/stream level variable (see integration documentation for more information)
  
  is_managed boolean
  
  name string Required
  
  Package policy name (should be unique)
  
  namespace string
  
  The package policy namespace. Leave blank to inherit the agent policy's namespace.
  
  output_id string | null
  
  overrides object | null
  
  Override settings that are defined in the package policy. The override option should be used only in unusual circumstances and not as a routine procedure.
  
  Additional properties are NOT allowed.
  
  Hide overrides attribute Show overrides attribute object | null
  
  inputs object
  
  Additional properties are allowed.
  
  package object
  
  Additional properties are NOT allowed.
  
  Hide package attributes Show package attributes object
  
  experimental_data_stream_features array[object]
  
  Hide experimental_data_stream_features attributes Show experimental_data_stream_features attributes object
  
  data_stream string Required
  
  features object Required
  
  Additional properties are NOT allowed.
  
  Hide features attributes Show features attributes object
  
  doc_value_only_numeric boolean
  
  doc_value_only_other boolean
  
  synthetic_source boolean
  
  tsdb boolean
  
  name string Required
  
  Package name
  
  requires_root boolean
  
  title string
  
  version string Required
  
  Package version
  
  policy_id string | null Deprecated
  
  Agent policy ID where that package policy will be added
  
  policy_ids array[string]
  
  Agent policy IDs where that package policy will be added
  
  revision number Required
  
  secret_references array[object]
  
  Hide secret_references attribute Show secret_references attribute object
  
  id string Required
  
  spaceIds array[string]
  
  supports_agentless boolean | null
  
  Indicates whether the package policy belongs to an agentless agent policy.
  
  Default value is false.
  
  updated_at string Required
  
  updated_by string Required
  
  vars object
  
  Any of:
  object-1 object object-2 object
  
  Package variable (see integration documentation for more information)
  
  Hide attribute Show attribute
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  frozen boolean
  
  type string
  
  version string
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number
404 application/json
Hide response attribute Show response attribute object
- message string Required

GET /api/fleet/package_policies/{packagePolicyId}

curl \
 --request GET 'https://<KIBANA_URL>/api/fleet/package_policies/{packagePolicyId}' \
 --header "Authorization: $API_KEY"

Update a package policy

PUT /api/fleet/package_policies/{packagePolicyId}

Update a package policy by ID.

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

Path parameters

packagePolicyId string Required

Query parameters

format string

Values are simplified or legacy.

application/json

Body object

additional_datastreams_permissions array[string] | null

Additional datastream permissions, that will be added to the agent policy.
description string

Package policy description
enabled boolean
force boolean
inputs array[object]
Hide inputs attributes Show inputs attributes object
- config object
  
  Package variable (see integration documentation for more information)
  Hide config attribute Show config attribute object
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  frozen boolean
  
  type string
- enabled boolean Required
- id string
- keep_enabled boolean
- policy_template string
- streams array[object]
  Hide streams attributes Show streams attributes object
  
  config object
  
  Package variable (see integration documentation for more information)
  
  Hide config attribute Show config attribute object
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  frozen boolean
  
  type string
  
  data_stream object Required
  
  Additional properties are NOT allowed.
  
  Hide data_stream attributes Show data_stream attributes object
  
  dataset string Required
  
  elasticsearch object
  
  Additional properties are NOT allowed.
  
  Hide elasticsearch attributes Show elasticsearch attributes object
  
  dynamic_dataset boolean
  
  dynamic_namespace boolean
  
  privileges object
  
  Additional properties are NOT allowed.
  
  Hide privileges attribute Show privileges attribute object
  
  indices array[string]
  
  type string Required
  
  enabled boolean Required
  
  id string
  
  keep_enabled boolean
  
  release string
  
  Values are ga, beta, or experimental.
  
  vars object
  
  Package variable (see integration documentation for more information)
  
  Hide vars attribute Show vars attribute object
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  frozen boolean
  
  type string
- type string Required
- vars object
  
  Package variable (see integration documentation for more information)
  Hide vars attribute Show vars attribute object
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  frozen boolean
  
  type string
is_managed boolean
name string
namespace string

The package policy namespace. Leave blank to inherit the agent policy's namespace.
output_id string | null
overrides object | null

Override settings that are defined in the package policy. The override option should be used only in unusual circumstances and not as a routine procedure.

Additional properties are NOT allowed.
Hide overrides attribute Show overrides attribute object | null
- inputs object
  
  Additional properties are allowed.
package object

Additional properties are NOT allowed.
Hide package attributes Show package attributes object
- experimental_data_stream_features array[object]
  Hide experimental_data_stream_features attributes Show experimental_data_stream_features attributes object
  
  data_stream string Required
  
  features object Required
  
  Additional properties are NOT allowed.
  
  Hide features attributes Show features attributes object
  
  doc_value_only_numeric boolean
  
  doc_value_only_other boolean
  
  synthetic_source boolean
  
  tsdb boolean
- name string Required
  
  Package name
- requires_root boolean
- title string
- version string Required
  
  Package version
policy_id string | null Deprecated

Agent policy ID where that package policy will be added
policy_ids array[string]

Agent policy IDs where that package policy will be added
spaceIds array[string]
supports_agentless boolean | null

Indicates whether the package policy belongs to an agentless agent policy.

Default value is false.
vars object

Package variable (see integration documentation for more information)
Hide vars attribute Show vars attribute object
- * object Additional properties
  
  Additional properties are NOT allowed.
  Hide * attributes Show * attributes object
  
  frozen boolean
  
  type string
version string

additional_datastreams_permissions array[string] | null

Additional datastream permissions, that will be added to the agent policy.
description string
force boolean
id string
inputs object

Package policy inputs (see integration documentation to know what inputs are available)
Hide inputs attribute Show inputs attribute object
- * object Additional properties
  
  Additional properties are NOT allowed.
  Hide * attributes Show * attributes object
  
  enabled boolean
  
  enable or disable that input, (default to true)
  
  streams object
  
  Input streams (see integration documentation to know what streams are available)
  
  Hide streams attribute Show streams attribute object
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  enabled boolean
  
  enable or disable that stream, (default to true)
  
  vars object
  
  Input/stream level variable (see integration documentation for more information)
  
  vars object
  
  Input/stream level variable (see integration documentation for more information)
name string Required
namespace string
output_id string | null
package object Required

Additional properties are NOT allowed.
Hide package attributes Show package attributes object
- experimental_data_stream_features array[object]
  Hide experimental_data_stream_features attributes Show experimental_data_stream_features attributes object
  
  data_stream string Required
  
  features object Required
  
  Additional properties are NOT allowed.
  
  Hide features attributes Show features attributes object
  
  doc_value_only_numeric boolean
  
  doc_value_only_other boolean
  
  synthetic_source boolean
  
  tsdb boolean
- name string Required
  
  Package name
- requires_root boolean
- title string
- version string Required
  
  Package version
policy_id string | null
policy_ids array[string]
supports_agentless boolean | null

Indicates whether the package policy belongs to an agentless agent policy.

Default value is false.
vars object

Input/stream level variable (see integration documentation for more information)

Responses

200 application/json
Hide response attribute Show response attribute object
- item object Required
  
  Additional properties are NOT allowed.
  
  Hide item attributes Show item attributes object
  
  additional_datastreams_permissions array[string] | null
  
  Additional datastream permissions, that will be added to the agent policy.
  
  agents number
  
  created_at string Required
  
  created_by string Required
  
  description string
  
  Package policy description
  
  elasticsearch object
  
  Additional properties are allowed.
  
  Hide elasticsearch attribute Show elasticsearch attribute object
  
  privileges object
  
  Additional properties are allowed.
  
  Hide privileges attribute Show privileges attribute object
  
  cluster array[string]
  
  enabled boolean Required
  
  id string Required
  
  inputs array[object] | object Required
  
  Any of:
  array-1 array[object] object-2 object
  
  Hide attributes Show attributes object
  
  config object
  
  Package variable (see integration documentation for more information)
  
  Hide config attribute Show config attribute object
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  frozen boolean
  
  type string
  
  enabled boolean Required
  
  id string
  
  keep_enabled boolean
  
  policy_template string
  
  streams array[object] Required
  
  Hide streams attributes Show streams attributes object
  
  config object
  
  Package variable (see integration documentation for more information)
  
  Hide config attribute Show config attribute object
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  frozen boolean
  
  type string
  
  data_stream object Required
  
  Additional properties are NOT allowed.
  
  Hide data_stream attributes Show data_stream attributes object
  
  dataset string Required
  
  elasticsearch object
  
  Additional properties are NOT allowed.
  
  Hide elasticsearch attributes Show elasticsearch attributes object
  
  dynamic_dataset boolean
  
  dynamic_namespace boolean
  
  privileges object
  
  Additional properties are NOT allowed.
  
  Hide privileges attribute Show privileges attribute object
  
  indices array[string]
  
  type string Required
  
  enabled boolean Required
  
  id string
  
  keep_enabled boolean
  
  release string
  
  Values are ga, beta, or experimental.
  
  vars object
  
  Package variable (see integration documentation for more information)
  
  Hide vars attribute Show vars attribute object
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  frozen boolean
  
  type string
  
  type string Required
  
  vars object
  
  Package variable (see integration documentation for more information)
  
  Hide vars attribute Show vars attribute object
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  frozen boolean
  
  type string
  
  Package policy inputs (see integration documentation to know what inputs are available)
  
  Hide attribute Show attribute
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  enabled boolean
  
  enable or disable that input, (default to true)
  
  streams object
  
  Input streams (see integration documentation to know what streams are available)
  
  Hide streams attribute Show streams attribute object
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  enabled boolean
  
  enable or disable that stream, (default to true)
  
  vars object
  
  Input/stream level variable (see integration documentation for more information)
  
  vars object
  
  Input/stream level variable (see integration documentation for more information)
  
  is_managed boolean
  
  name string Required
  
  Package policy name (should be unique)
  
  namespace string
  
  The package policy namespace. Leave blank to inherit the agent policy's namespace.
  
  output_id string | null
  
  overrides object | null
  
  Override settings that are defined in the package policy. The override option should be used only in unusual circumstances and not as a routine procedure.
  
  Additional properties are NOT allowed.
  
  Hide overrides attribute Show overrides attribute object | null
  
  inputs object
  
  Additional properties are allowed.
  
  package object
  
  Additional properties are NOT allowed.
  
  Hide package attributes Show package attributes object
  
  experimental_data_stream_features array[object]
  
  Hide experimental_data_stream_features attributes Show experimental_data_stream_features attributes object
  
  data_stream string Required
  
  features object Required
  
  Additional properties are NOT allowed.
  
  Hide features attributes Show features attributes object
  
  doc_value_only_numeric boolean
  
  doc_value_only_other boolean
  
  synthetic_source boolean
  
  tsdb boolean
  
  name string Required
  
  Package name
  
  requires_root boolean
  
  title string
  
  version string Required
  
  Package version
  
  policy_id string | null Deprecated
  
  Agent policy ID where that package policy will be added
  
  policy_ids array[string]
  
  Agent policy IDs where that package policy will be added
  
  revision number Required
  
  secret_references array[object]
  
  Hide secret_references attribute Show secret_references attribute object
  
  id string Required
  
  spaceIds array[string]
  
  supports_agentless boolean | null
  
  Indicates whether the package policy belongs to an agentless agent policy.
  
  Default value is false.
  
  updated_at string Required
  
  updated_by string Required
  
  vars object
  
  Any of:
  object-1 object object-2 object
  
  Package variable (see integration documentation for more information)
  
  Hide attribute Show attribute
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  frozen boolean
  
  type string
  
  version string
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number
403 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

PUT /api/fleet/package_policies/{packagePolicyId}

curl \
 --request PUT 'https://<KIBANA_URL>/api/fleet/package_policies/{packagePolicyId}' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"additional_datastreams_permissions":["string"],"description":"string","enabled":true,"force":true,"inputs":[{"config":{"additionalProperty1":{"frozen":true,"type":"string"},"additionalProperty2":{"frozen":true,"type":"string"}},"enabled":true,"id":"string","keep_enabled":true,"policy_template":"string","streams":[{"config":{"additionalProperty1":{"frozen":true,"type":"string"},"additionalProperty2":{"frozen":true,"type":"string"}},"data_stream":{"dataset":"string","elasticsearch":{"dynamic_dataset":true,"dynamic_namespace":true,"privileges":{"indices":["string"]}},"type":"string"},"enabled":true,"id":"string","keep_enabled":true,"release":"ga","vars":{"additionalProperty1":{"frozen":true,"type":"string"},"additionalProperty2":{"frozen":true,"type":"string"}}}],"type":"string","vars":{"additionalProperty1":{"frozen":true,"type":"string"},"additionalProperty2":{"frozen":true,"type":"string"}}}],"is_managed":true,"name":"string","namespace":"string","output_id":"string","overrides":{"inputs":{}},"package":{"experimental_data_stream_features":[{"data_stream":"string","features":{"doc_value_only_numeric":true,"doc_value_only_other":true,"synthetic_source":true,"tsdb":true}}],"name":"string","requires_root":true,"title":"string","version":"string"},"policy_id":"string","policy_ids":["string"],"spaceIds":["string"],"supports_agentless":false,"vars":{"additionalProperty1":{"frozen":true,"type":"string"},"additionalProperty2":{"frozen":true,"type":"string"}},"version":"string"}'

Delete a package policy

DELETE /api/fleet/package_policies/{packagePolicyId}

Delete a package policy by ID.

[Required authorization] Route required privileges: fleet-agent-policies-all AND integrations-all.

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

Path parameters

packagePolicyId string Required

Query parameters

force boolean

Responses

200 application/json
Hide response attribute Show response attribute object
- id string Required
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

DELETE /api/fleet/package_policies/{packagePolicyId}

curl \
 --request DELETE 'https://<KIBANA_URL>/api/fleet/package_policies/{packagePolicyId}' \
 --header "Authorization: $API_KEY" \
 --header "kbn-xsrf: true"

Bulk delete package policies

POST /api/fleet/package_policies/delete

[Required authorization] Route required privileges: fleet-agent-policies-all AND integrations-all.

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

application/json

Body

force boolean
packagePolicyIds array[string] Required

Responses

200 application/json
Hide response attributes Show response attributes object
- body object
  
  Additional properties are NOT allowed.
  
  Hide body attribute Show body attribute object
  
  message string Required
- id string Required
- name string
- output_id string | null
- package object Required
  
  Additional properties are NOT allowed.
  
  Hide package attributes Show package attributes object
  
  experimental_data_stream_features array[object]
  
  Hide experimental_data_stream_features attributes Show experimental_data_stream_features attributes object
  
  data_stream string Required
  
  features object Required
  
  Additional properties are NOT allowed.
  
  Hide features attributes Show features attributes object
  
  doc_value_only_numeric boolean
  
  doc_value_only_other boolean
  
  synthetic_source boolean
  
  tsdb boolean
  
  name string Required
  
  Package name
  
  requires_root boolean
  
  title string
  
  version string Required
  
  Package version
- policy_id string | null Deprecated
  
  Use policy_ids instead
- policy_ids array[string] Required
- statusCode number
- success boolean Required
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

POST /api/fleet/package_policies/delete

curl \
 --request POST 'https://<KIBANA_URL>/api/fleet/package_policies/delete' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"force":true,"packagePolicyIds":["string"]}'

Upgrade a package policy

POST /api/fleet/package_policies/upgrade

Upgrade a package policy to a newer package version.

[Required authorization] Route required privileges: fleet-agent-policies-all AND integrations-all.

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

application/json

Body

packagePolicyIds array[string] Required

Responses

200 application/json
Hide response attributes Show response attributes object
- body object
  
  Additional properties are NOT allowed.
  
  Hide body attribute Show body attribute object
  
  message string Required
- id string Required
- name string
- statusCode number
- success boolean Required
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

POST /api/fleet/package_policies/upgrade

curl \
 --request POST 'https://<KIBANA_URL>/api/fleet/package_policies/upgrade' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"packagePolicyIds":["string"]}'

Dry run a package policy upgrade

POST /api/fleet/package_policies/upgrade/dryrun

[Required authorization] Route required privileges: fleet-agent-policies-read AND integrations-read.

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

application/json

Body

packagePolicyIds array[string] Required
packageVersion string

Responses

200 application/json
Hide response attributes Show response attributes object
- agent_diff array[array]
  
  Hide agent_diff attributes Show agent_diff attributes object
  
  data_stream object Required
  
  Additional properties are allowed.
  
  Hide data_stream attribute Show data_stream attribute object
  
  namespace string Required
  
  id string Required
  
  meta object
  
  Additional properties are allowed.
  
  Hide meta attribute Show meta attribute object
  
  package object Required
  
  Additional properties are allowed.
  
  Hide package attributes Show package attributes object
  
  name string Required
  
  version string Required
  
  name string Required
  
  package_policy_id string Required
  
  processors array[object]
  
  Hide processors attribute Show processors attribute object
  
  add_fields object Required
  
  Additional properties are allowed.
  
  Hide add_fields attributes Show add_fields attributes object
  
  fields object Required
  
  target string Required
  
  revision number Required
  
  streams array[object]
  
  Hide streams attributes Show streams attributes object
  
  data_stream object Required
  
  Additional properties are allowed.
  
  Hide data_stream attributes Show data_stream attributes object
  
  dataset string Required
  
  type string
  
  id string
  
  type string Required
  
  use_output string Required
- body object
  
  Additional properties are NOT allowed.
  
  Hide body attribute Show body attribute object
  
  message string Required
- diff array[object]
  
  Any of:
  object-1 object object-2 object
  
  Hide attributes Show attributes
  
  additional_datastreams_permissions array[string] | null
  
  Additional datastream permissions, that will be added to the agent policy.
  
  agents number
  
  created_at string Required
  
  created_by string Required
  
  description string
  
  Package policy description
  
  elasticsearch object
  
  Additional properties are allowed.
  
  Hide elasticsearch attribute Show elasticsearch attribute object
  
  privileges object
  
  Additional properties are allowed.
  
  Hide privileges attribute Show privileges attribute object
  
  cluster array[string]
  
  enabled boolean Required
  
  id string
  
  inputs array[object] | object Required
  
  Any of:
  array-1 array[object] object-2 object
  
  Hide attributes Show attributes object
  
  config object
  
  Package variable (see integration documentation for more information)
  
  Hide config attribute Show config attribute object
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  frozen boolean
  
  type string
  
  enabled boolean Required
  
  id string
  
  keep_enabled boolean
  
  policy_template string
  
  streams array[object] Required
  
  Hide streams attributes Show streams attributes object
  
  config object
  
  Package variable (see integration documentation for more information)
  
  Hide config attribute Show config attribute object
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  frozen boolean
  
  type string
  
  data_stream object Required
  
  Additional properties are NOT allowed.
  
  Hide data_stream attributes Show data_stream attributes object
  
  dataset string Required
  
  elasticsearch object
  
  Additional properties are NOT allowed.
  
  Hide elasticsearch attributes Show elasticsearch attributes object
  
  dynamic_dataset boolean
  
  dynamic_namespace boolean
  
  privileges object
  
  Additional properties are NOT allowed.
  
  Hide privileges attribute Show privileges attribute object
  
  indices array[string]
  
  type string Required
  
  enabled boolean Required
  
  id string
  
  keep_enabled boolean
  
  release string
  
  Values are ga, beta, or experimental.
  
  vars object
  
  Package variable (see integration documentation for more information)
  
  Hide vars attribute Show vars attribute object
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  frozen boolean
  
  type string
  
  type string Required
  
  vars object
  
  Package variable (see integration documentation for more information)
  
  Hide vars attribute Show vars attribute object
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  frozen boolean
  
  type string
  
  Package policy inputs (see integration documentation to know what inputs are available)
  
  Hide attribute Show attribute
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  enabled boolean
  
  enable or disable that input, (default to true)
  
  streams object
  
  Input streams (see integration documentation to know what streams are available)
  
  Hide streams attribute Show streams attribute object
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  enabled boolean
  
  enable or disable that stream, (default to true)
  
  vars object
  
  Input/stream level variable (see integration documentation for more information)
  
  vars object
  
  Input/stream level variable (see integration documentation for more information)
  
  is_managed boolean
  
  name string Required
  
  Package policy name (should be unique)
  
  namespace string
  
  The package policy namespace. Leave blank to inherit the agent policy's namespace.
  
  output_id string | null
  
  overrides object | null
  
  Override settings that are defined in the package policy. The override option should be used only in unusual circumstances and not as a routine procedure.
  
  Additional properties are NOT allowed.
  
  Hide overrides attribute Show overrides attribute object | null
  
  inputs object
  
  Additional properties are allowed.
  
  package object
  
  Additional properties are NOT allowed.
  
  Hide package attributes Show package attributes object
  
  experimental_data_stream_features array[object]
  
  Hide experimental_data_stream_features attributes Show experimental_data_stream_features attributes object
  
  data_stream string Required
  
  features object Required
  
  Additional properties are NOT allowed.
  
  Hide features attributes Show features attributes object
  
  doc_value_only_numeric boolean
  
  doc_value_only_other boolean
  
  synthetic_source boolean
  
  tsdb boolean
  
  name string Required
  
  Package name
  
  requires_root boolean
  
  title string
  
  version string Required
  
  Package version
  
  policy_id string | null Deprecated
  
  Agent policy ID where that package policy will be added
  
  policy_ids array[string]
  
  Agent policy IDs where that package policy will be added
  
  revision number Required
  
  secret_references array[object]
  
  Hide secret_references attribute Show secret_references attribute object
  
  id string Required
  
  spaceIds array[string]
  
  supports_agentless boolean | null
  
  Indicates whether the package policy belongs to an agentless agent policy.
  
  Default value is false.
  
  updated_at string Required
  
  updated_by string Required
  
  vars object
  
  Any of:
  object-1 object object-2 object
  
  Package variable (see integration documentation for more information)
  
  Hide attribute Show attribute
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  frozen boolean
  
  type string
  
  version string
  
  Hide attributes Show attributes
  
  additional_datastreams_permissions array[string] | null
  
  Additional datastream permissions, that will be added to the agent policy.
  
  created_at string
  
  created_by string
  
  description string
  
  Package policy description
  
  elasticsearch object
  
  Additional properties are allowed.
  
  Hide elasticsearch attribute Show elasticsearch attribute object
  
  privileges object
  
  Additional properties are allowed.
  
  Hide privileges attribute Show privileges attribute object
  
  cluster array[string]
  
  enabled boolean Required
  
  errors array[object]
  
  Hide errors attributes Show errors attributes object
  
  key string
  
  message string Required
  
  force boolean
  
  id string
  
  inputs array[object] Required
  
  Hide inputs attributes Show inputs attributes object
  
  config object
  
  Package variable (see integration documentation for more information)
  
  Hide config attribute Show config attribute object
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  frozen boolean
  
  type string
  
  enabled boolean Required
  
  id string
  
  keep_enabled boolean
  
  policy_template string
  
  streams array[object] Required
  
  Hide streams attributes Show streams attributes object
  
  config object
  
  Package variable (see integration documentation for more information)
  
  Hide config attribute Show config attribute object
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  frozen boolean
  
  type string
  
  data_stream object Required
  
  Additional properties are NOT allowed.
  
  Hide data_stream attributes Show data_stream attributes object
  
  dataset string Required
  
  elasticsearch object
  
  Additional properties are NOT allowed.
  
  Hide elasticsearch attributes Show elasticsearch attributes object
  
  dynamic_dataset boolean
  
  dynamic_namespace boolean
  
  privileges object
  
  Additional properties are NOT allowed.
  
  Hide privileges attribute Show privileges attribute object
  
  indices array[string]
  
  type string Required
  
  enabled boolean Required
  
  id string
  
  keep_enabled boolean
  
  release string
  
  Values are ga, beta, or experimental.
  
  vars object
  
  Package variable (see integration documentation for more information)
  
  Hide vars attribute Show vars attribute object
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  frozen boolean
  
  type string
  
  type string Required
  
  vars object
  
  Package variable (see integration documentation for more information)
  
  Hide vars attribute Show vars attribute object
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  frozen boolean
  
  type string
  
  is_managed boolean
  
  missingVars array[string]
  
  name string Required
  
  Package policy name (should be unique)
  
  namespace string
  
  The package policy namespace. Leave blank to inherit the agent policy's namespace.
  
  output_id string | null
  
  overrides object | null
  
  Override settings that are defined in the package policy. The override option should be used only in unusual circumstances and not as a routine procedure.
  
  Additional properties are NOT allowed.
  
  Hide overrides attribute Show overrides attribute object | null
  
  inputs object
  
  Additional properties are allowed.
  
  package object
  
  Additional properties are NOT allowed.
  
  Hide package attributes Show package attributes object
  
  experimental_data_stream_features array[object]
  
  Hide experimental_data_stream_features attributes Show experimental_data_stream_features attributes object
  
  data_stream string Required
  
  features object Required
  
  Additional properties are NOT allowed.
  
  Hide features attributes Show features attributes object
  
  doc_value_only_numeric boolean
  
  doc_value_only_other boolean
  
  synthetic_source boolean
  
  tsdb boolean
  
  name string Required
  
  Package name
  
  requires_root boolean
  
  title string
  
  version string Required
  
  Package version
  
  policy_id string | null Deprecated
  
  Agent policy ID where that package policy will be added
  
  policy_ids array[string]
  
  Agent policy IDs where that package policy will be added
  
  revision number
  
  secret_references array[object]
  
  Hide secret_references attribute Show secret_references attribute object
  
  id string Required
  
  supports_agentless boolean | null
  
  Indicates whether the package policy belongs to an agentless agent policy.
  
  Default value is false.
  
  updated_at string
  
  updated_by string
  
  vars object
  
  Package variable (see integration documentation for more information)
  
  Hide vars attribute Show vars attribute object
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  frozen boolean
  
  type string
  
  version string
- hasErrors boolean Required
- name string
- statusCode number
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

POST /api/fleet/package_policies/upgrade/dryrun

curl \
 --request POST 'https://<KIBANA_URL>/api/fleet/package_policies/upgrade/dryrun' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"packagePolicyIds":["string"],"packageVersion":"string"}'

Get proxies

GET /api/fleet/proxies

[Required authorization] Route required privileges: fleet-settings-read.

Responses

200 application/json
Hide response attributes Show response attributes object
- items array[object] Required
  
  Hide items attributes Show items attributes object
  
  certificate string | null
  
  certificate_authorities string | null
  
  certificate_key string | null
  
  id string Required
  
  is_preconfigured boolean
  
  Default value is false.
  
  name string Required
  
  proxy_headers object | null
  
  url string Required
- page number Required
- perPage number Required
- total number Required
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

GET /api/fleet/proxies

curl \
 --request GET 'https://<KIBANA_URL>/api/fleet/proxies' \
 --header "Authorization: $API_KEY"

Create a proxy

POST /api/fleet/proxies

[Required authorization] Route required privileges: fleet-settings-all.

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

application/json

Body

certificate string | null
certificate_authorities string | null
certificate_key string | null
id string
is_preconfigured boolean

Default value is false.
name string Required
proxy_headers object | null
url string Required

Responses

200 application/json
Hide response attribute Show response attribute object
- item object Required
  
  Additional properties are NOT allowed.
  
  Hide item attributes Show item attributes object
  
  certificate string | null
  
  certificate_authorities string | null
  
  certificate_key string | null
  
  id string Required
  
  is_preconfigured boolean
  
  Default value is false.
  
  name string Required
  
  proxy_headers object | null
  
  url string Required
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

POST /api/fleet/proxies

curl \
 --request POST 'https://<KIBANA_URL>/api/fleet/proxies' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"certificate":"string","certificate_authorities":"string","certificate_key":"string","id":"string","is_preconfigured":false,"name":"string","proxy_headers":{},"url":"string"}'

Get a proxy

GET /api/fleet/proxies/{itemId}

Get a proxy by ID.

[Required authorization] Route required privileges: fleet-settings-read.

Path parameters

itemId string Required

Responses

200 application/json
Hide response attribute Show response attribute object
- item object Required
  
  Additional properties are NOT allowed.
  
  Hide item attributes Show item attributes object
  
  certificate string | null
  
  certificate_authorities string | null
  
  certificate_key string | null
  
  id string Required
  
  is_preconfigured boolean
  
  Default value is false.
  
  name string Required
  
  proxy_headers object | null
  
  url string Required
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

GET /api/fleet/proxies/{itemId}

curl \
 --request GET 'https://<KIBANA_URL>/api/fleet/proxies/{itemId}' \
 --header "Authorization: $API_KEY"

Update a proxy

PUT /api/fleet/proxies/{itemId}

Update a proxy by ID.

[Required authorization] Route required privileges: fleet-settings-all.

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

Path parameters

itemId string Required

application/json

Body

certificate string | null Required
certificate_authorities string | null Required
certificate_key string | null Required
name string
proxy_headers object | null Required
url string

Responses

200 application/json
Hide response attribute Show response attribute object
- item object Required
  
  Additional properties are NOT allowed.
  
  Hide item attributes Show item attributes object
  
  certificate string | null
  
  certificate_authorities string | null
  
  certificate_key string | null
  
  id string Required
  
  is_preconfigured boolean
  
  Default value is false.
  
  name string Required
  
  proxy_headers object | null
  
  url string Required
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

PUT /api/fleet/proxies/{itemId}

curl \
 --request PUT 'https://<KIBANA_URL>/api/fleet/proxies/{itemId}' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"certificate":"string","certificate_authorities":"string","certificate_key":"string","name":"string","proxy_headers":{},"url":"string"}'

Delete a proxy

DELETE /api/fleet/proxies/{itemId}

Delete a proxy by ID

[Required authorization] Route required privileges: fleet-settings-all.

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

Path parameters

itemId string Required

Responses

200 application/json
Hide response attribute Show response attribute object
- id string Required
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

DELETE /api/fleet/proxies/{itemId}

curl \
 --request DELETE 'https://<KIBANA_URL>/api/fleet/proxies/{itemId}' \
 --header "Authorization: $API_KEY" \
 --header "kbn-xsrf: true"

Get Fleet Server hosts

GET /api/fleet/fleet_server_hosts

[Required authorization] Route required privileges: fleet-agents-all OR fleet-settings-read.

Responses

200 application/json
Hide response attributes Show response attributes object
- items array[object] Required
  
  Hide items attributes Show items attributes object
  
  host_urls array[string] Required
  
  At least 1 element.
  
  id string Required
  
  is_default boolean
  
  Default value is false.
  
  is_internal boolean
  
  is_preconfigured boolean
  
  Default value is false.
  
  name string Required
  
  proxy_id string | null
  
  secrets object
  
  Additional properties are NOT allowed.
  
  Hide secrets attribute Show secrets attribute object
  
  ssl object
  
  Additional properties are NOT allowed.
  
  Hide ssl attributes Show ssl attributes object
  
  es_key object | string
  
  Any of:
  object-1 object string-2 string
  
  Hide attribute Show attribute
  
  id string Required
  
  key object | string
  
  Any of:
  object-1 object string-2 string
  
  Hide attribute Show attribute
  
  id string Required
  
  ssl object | null
  
  Additional properties are NOT allowed.
  
  Hide ssl attributes Show ssl attributes object | null
  
  certificate string
  
  certificate_authorities array[string]
  
  client_auth string
  
  Values are optional, required, or none.
  
  es_certificate string
  
  es_certificate_authorities array[string]
  
  es_key string
  
  key string
- page number Required
- perPage number Required
- total number Required
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

GET /api/fleet/fleet_server_hosts

curl \
 --request GET 'https://<KIBANA_URL>/api/fleet/fleet_server_hosts' \
 --header "Authorization: $API_KEY"

Create a Fleet Server host

POST /api/fleet/fleet_server_hosts

[Required authorization] Route required privileges: fleet-settings-all.

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

application/json

Body

host_urls array[string] Required

At least 1 element.
id string
is_default boolean

Default value is false.
is_internal boolean
is_preconfigured boolean

Default value is false.
name string Required
proxy_id string | null
secrets object

Additional properties are NOT allowed.
Hide secrets attribute Show secrets attribute object
- ssl object
  
  Additional properties are NOT allowed.
  Hide ssl attributes Show ssl attributes object
  
  es_key object | string
  
  Any of:
  object-1 object string-2 string
  
  Hide attribute Show attribute
  
  id string Required
  
  key object | string
  
  Any of:
  object-1 object string-2 string
  
  Hide attribute Show attribute
  
  id string Required
ssl object | null

Additional properties are NOT allowed.
Hide ssl attributes Show ssl attributes object | null
- certificate string
- certificate_authorities array[string]
- client_auth string
  
  Values are optional, required, or none.
- es_certificate string
- es_certificate_authorities array[string]
- es_key string
- key string

Responses

200 application/json
Hide response attribute Show response attribute object
- item object Required
  
  Additional properties are NOT allowed.
  
  Hide item attributes Show item attributes object
  
  host_urls array[string] Required
  
  At least 1 element.
  
  id string Required
  
  is_default boolean
  
  Default value is false.
  
  is_internal boolean
  
  is_preconfigured boolean
  
  Default value is false.
  
  name string Required
  
  proxy_id string | null
  
  secrets object
  
  Additional properties are NOT allowed.
  
  Hide secrets attribute Show secrets attribute object
  
  ssl object
  
  Additional properties are NOT allowed.
  
  Hide ssl attributes Show ssl attributes object
  
  es_key object | string
  
  Any of:
  object-1 object string-2 string
  
  Hide attribute Show attribute
  
  id string Required
  
  key object | string
  
  Any of:
  object-1 object string-2 string
  
  Hide attribute Show attribute
  
  id string Required
  
  ssl object | null
  
  Additional properties are NOT allowed.
  
  Hide ssl attributes Show ssl attributes object | null
  
  certificate string
  
  certificate_authorities array[string]
  
  client_auth string
  
  Values are optional, required, or none.
  
  es_certificate string
  
  es_certificate_authorities array[string]
  
  es_key string
  
  key string
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

POST /api/fleet/fleet_server_hosts

curl \
 --request POST 'https://<KIBANA_URL>/api/fleet/fleet_server_hosts' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"host_urls":["string"],"id":"string","is_default":false,"is_internal":true,"is_preconfigured":false,"name":"string","proxy_id":"string","secrets":{"ssl":{"es_key":{"id":"string"},"key":{"id":"string"}}},"ssl":{"certificate":"string","certificate_authorities":["string"],"client_auth":"optional","es_certificate":"string","es_certificate_authorities":["string"],"es_key":"string","key":"string"}}'

Get a Fleet Server host

GET /api/fleet/fleet_server_hosts/{itemId}

Get a Fleet Server host by ID.

[Required authorization] Route required privileges: fleet-settings-read.

Path parameters

itemId string Required

Responses

200 application/json
Hide response attribute Show response attribute object
- item object Required
  
  Additional properties are NOT allowed.
  
  Hide item attributes Show item attributes object
  
  host_urls array[string] Required
  
  At least 1 element.
  
  id string Required
  
  is_default boolean
  
  Default value is false.
  
  is_internal boolean
  
  is_preconfigured boolean
  
  Default value is false.
  
  name string Required
  
  proxy_id string | null
  
  secrets object
  
  Additional properties are NOT allowed.
  
  Hide secrets attribute Show secrets attribute object
  
  ssl object
  
  Additional properties are NOT allowed.
  
  Hide ssl attributes Show ssl attributes object
  
  es_key object | string
  
  Any of:
  object-1 object string-2 string
  
  Hide attribute Show attribute
  
  id string Required
  
  key object | string
  
  Any of:
  object-1 object string-2 string
  
  Hide attribute Show attribute
  
  id string Required
  
  ssl object | null
  
  Additional properties are NOT allowed.
  
  Hide ssl attributes Show ssl attributes object | null
  
  certificate string
  
  certificate_authorities array[string]
  
  client_auth string
  
  Values are optional, required, or none.
  
  es_certificate string
  
  es_certificate_authorities array[string]
  
  es_key string
  
  key string
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

GET /api/fleet/fleet_server_hosts/{itemId}

curl \
 --request GET 'https://<KIBANA_URL>/api/fleet/fleet_server_hosts/{itemId}' \
 --header "Authorization: $API_KEY"

Update a Fleet Server host

PUT /api/fleet/fleet_server_hosts/{itemId}

Update a Fleet Server host by ID.

[Required authorization] Route required privileges: fleet-settings-all.

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

Path parameters

itemId string Required

application/json

Body

host_urls array[string]

At least 1 element.
is_default boolean
is_internal boolean
name string
proxy_id string | null Required
secrets object

Additional properties are NOT allowed.
Hide secrets attribute Show secrets attribute object
- ssl object
  
  Additional properties are NOT allowed.
  Hide ssl attributes Show ssl attributes object
  
  es_key object | string
  
  Any of:
  object-1 object string-2 string
  
  Hide attribute Show attribute
  
  id string Required
  
  key object | string
  
  Any of:
  object-1 object string-2 string
  
  Hide attribute Show attribute
  
  id string Required
ssl object | null

Additional properties are NOT allowed.
Hide ssl attributes Show ssl attributes object | null
- certificate string
- certificate_authorities array[string]
- client_auth string
  
  Values are optional, required, or none.
- es_certificate string
- es_certificate_authorities array[string]
- es_key string
- key string

Responses

200 application/json
Hide response attribute Show response attribute object
- item object Required
  
  Additional properties are NOT allowed.
  
  Hide item attributes Show item attributes object
  
  host_urls array[string] Required
  
  At least 1 element.
  
  id string Required
  
  is_default boolean
  
  Default value is false.
  
  is_internal boolean
  
  is_preconfigured boolean
  
  Default value is false.
  
  name string Required
  
  proxy_id string | null
  
  secrets object
  
  Additional properties are NOT allowed.
  
  Hide secrets attribute Show secrets attribute object
  
  ssl object
  
  Additional properties are NOT allowed.
  
  Hide ssl attributes Show ssl attributes object
  
  es_key object | string
  
  Any of:
  object-1 object string-2 string
  
  Hide attribute Show attribute
  
  id string Required
  
  key object | string
  
  Any of:
  object-1 object string-2 string
  
  Hide attribute Show attribute
  
  id string Required
  
  ssl object | null
  
  Additional properties are NOT allowed.
  
  Hide ssl attributes Show ssl attributes object | null
  
  certificate string
  
  certificate_authorities array[string]
  
  client_auth string
  
  Values are optional, required, or none.
  
  es_certificate string
  
  es_certificate_authorities array[string]
  
  es_key string
  
  key string
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

PUT /api/fleet/fleet_server_hosts/{itemId}

curl \
 --request PUT 'https://<KIBANA_URL>/api/fleet/fleet_server_hosts/{itemId}' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"host_urls":["string"],"is_default":true,"is_internal":true,"name":"string","proxy_id":"string","secrets":{"ssl":{"es_key":{"id":"string"},"key":{"id":"string"}}},"ssl":{"certificate":"string","certificate_authorities":["string"],"client_auth":"optional","es_certificate":"string","es_certificate_authorities":["string"],"es_key":"string","key":"string"}}'

Delete a Fleet Server host

DELETE /api/fleet/fleet_server_hosts/{itemId}

Delete a Fleet Server host by ID.

[Required authorization] Route required privileges: fleet-settings-all.

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

Path parameters

itemId string Required

Responses

200 application/json
Hide response attribute Show response attribute object
- id string Required
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

DELETE /api/fleet/fleet_server_hosts/{itemId}

curl \
 --request DELETE 'https://<KIBANA_URL>/api/fleet/fleet_server_hosts/{itemId}' \
 --header "Authorization: $API_KEY" \
 --header "kbn-xsrf: true"

Create a service token

POST /api/fleet/service_tokens

[Required authorization] Route required privileges: fleet-agents-all.

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

application/json

Body

remote boolean

Default value is false.

Responses

200 application/json
Hide response attributes Show response attributes object
- name string Required
- value string Required
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

POST /api/fleet/service_tokens

curl \
 --request POST 'https://<KIBANA_URL>/api/fleet/service_tokens' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"remote":false}'

Get metadata for latest uninstall tokens

GET /api/fleet/uninstall_tokens

List the metadata for the latest uninstall tokens per agent policy.

[Required authorization] Route required privileges: fleet-agents-all.

Query parameters

policyId string

Partial match filtering for policy IDs

Maximum length is 50.
search string

Maximum length is 50.
perPage number

The number of items to return

Minimum value is 5.
page number

Minimum value is 1.

Responses

200 application/json
Hide response attributes Show response attributes object
- items array[object] Required
  
  Hide items attributes Show items attributes object
  
  created_at string Required
  
  id string Required
  
  namespaces array[string]
  
  policy_id string Required
  
  policy_name string | null
- page number Required
- perPage number Required
- total number Required
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

GET /api/fleet/uninstall_tokens

curl \
 --request GET 'https://<KIBANA_URL>/api/fleet/uninstall_tokens' \
 --header "Authorization: $API_KEY"

Get a decrypted uninstall token

GET /api/fleet/uninstall_tokens/{uninstallTokenId}

Get one decrypted uninstall token by its ID.

[Required authorization] Route required privileges: fleet-agents-all.

Path parameters

uninstallTokenId string Required

Responses

200 application/json
Hide response attribute Show response attribute object
- item object Required
  
  Additional properties are NOT allowed.
  
  Hide item attributes Show item attributes object
  
  created_at string Required
  
  id string Required
  
  namespaces array[string]
  
  policy_id string Required
  
  policy_name string | null
  
  token string Required
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

GET /api/fleet/uninstall_tokens/{uninstallTokenId}

curl \
 --request GET 'https://<KIBANA_URL>/api/fleet/uninstall_tokens/{uninstallTokenId}' \
 --header "Authorization: $API_KEY"

Rotate a Fleet message signing key pair

POST /api/fleet/message_signing_service/rotate_key_pair

[Required authorization] Route required privileges: fleet-agents-all AND fleet-agent-policies-all AND fleet-settings-all.

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

Query parameters

acknowledge boolean

Default value is false.

Responses

200 application/json
Hide response attribute Show response attribute object
- message string Required
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number
500 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

POST /api/fleet/message_signing_service/rotate_key_pair

curl \
 --request POST 'https://<KIBANA_URL>/api/fleet/message_signing_service/rotate_key_pair' \
 --header "Authorization: $API_KEY" \
 --header "kbn-xsrf: true"

Sync machine learning saved objects

GET /api/ml/saved_objects/sync

Synchronizes Kibana saved objects for machine learning jobs and trained models. This API runs automatically when you start Kibana and periodically thereafter.

Query parameters

simulate boolean

When true, simulates the synchronization by returning only the list of actions that would be performed.

Responses

200 application/json

Indicates a successful call
Hide response attributes Show response attributes object
- datafeedsAdded object
  
  If a saved object for an anomaly detection job is missing a datafeed identifier, it is added when you run the sync machine learning saved objects API.
  
  Hide datafeedsAdded attribute Show datafeedsAdded attribute object
  
  * object Additional properties
  
  The sync machine learning saved objects API response contains this object when there are datafeeds affected by the synchronization. There is an object for each relevant datafeed, which contains the synchronization status.
  
  Hide * attribute Show * attribute object
  
  success boolean
  
  The success or failure of the synchronization.
- datafeedsRemoved object
  
  If a saved object for an anomaly detection job references a datafeed that no longer exists, it is deleted when you run the sync machine learning saved objects API.
  
  Hide datafeedsRemoved attribute Show datafeedsRemoved attribute object
  
  * object Additional properties
  
  The sync machine learning saved objects API response contains this object when there are datafeeds affected by the synchronization. There is an object for each relevant datafeed, which contains the synchronization status.
  
  Hide * attribute Show * attribute object
  
  success boolean
  
  The success or failure of the synchronization.
- savedObjectsCreated object
  
  If saved objects are missing for machine learning jobs or trained models, they are created when you run the sync machine learning saved objects API.
  
  Hide savedObjectsCreated attributes Show savedObjectsCreated attributes object
  
  anomaly-detector object
  
  If saved objects are missing for anomaly detection jobs, they are created.
  
  Hide anomaly-detector attribute Show anomaly-detector attribute object
  
  * object Additional properties
  
  The sync machine learning saved objects API response contains this object when there are anomaly detection jobs affected by the synchronization. There is an object for each relevant job, which contains the synchronization status.
  
  Hide * attribute Show * attribute object
  
  success boolean
  
  The success or failure of the synchronization.
  
  data-frame-analytics object
  
  If saved objects are missing for data frame analytics jobs, they are created.
  
  Hide data-frame-analytics attribute Show data-frame-analytics attribute object
  
  * object Additional properties
  
  The sync machine learning saved objects API response contains this object when there are data frame analytics jobs affected by the synchronization. There is an object for each relevant job, which contains the synchronization status.
  
  Hide * attribute Show * attribute object
  
  success boolean
  
  The success or failure of the synchronization.
  
  trained-model object
  
  If saved objects are missing for trained models, they are created.
  
  Hide trained-model attribute Show trained-model attribute object
  
  * object Additional properties
  
  The sync machine learning saved objects API response contains this object when there are trained models affected by the synchronization. There is an object for each relevant trained model, which contains the synchronization status.
  
  Hide * attribute Show * attribute object
  
  success boolean
  
  The success or failure of the synchronization.
- savedObjectsDeleted object
  
  If saved objects exist for machine learning jobs or trained models that no longer exist, they are deleted when you run the sync machine learning saved objects API.
  
  Hide savedObjectsDeleted attributes Show savedObjectsDeleted attributes object
  
  anomaly-detector object
  
  If there are saved objects exist for nonexistent anomaly detection jobs, they are deleted.
  
  Hide anomaly-detector attribute Show anomaly-detector attribute object
  
  * object Additional properties
  
  The sync machine learning saved objects API response contains this object when there are anomaly detection jobs affected by the synchronization. There is an object for each relevant job, which contains the synchronization status.
  
  Hide * attribute Show * attribute object
  
  success boolean
  
  The success or failure of the synchronization.
  
  data-frame-analytics object
  
  If there are saved objects exist for nonexistent data frame analytics jobs, they are deleted.
  
  Hide data-frame-analytics attribute Show data-frame-analytics attribute object
  
  * object Additional properties
  
  The sync machine learning saved objects API response contains this object when there are data frame analytics jobs affected by the synchronization. There is an object for each relevant job, which contains the synchronization status.
  
  Hide * attribute Show * attribute object
  
  success boolean
  
  The success or failure of the synchronization.
  
  trained-model object
  
  If there are saved objects exist for nonexistent trained models, they are deleted.
  
  Hide trained-model attribute Show trained-model attribute object
  
  * object Additional properties
  
  The sync machine learning saved objects API response contains this object when there are trained models affected by the synchronization. There is an object for each relevant trained model, which contains the synchronization status.
  
  Hide * attribute Show * attribute object
  
  success boolean
  
  The success or failure of the synchronization.
401 application/json

Authorization information is missing or invalid.
Hide response attributes Show response attributes object
- error string
- message string
- statusCode integer

GET /api/ml/saved_objects/sync

curl \
 --request GET 'https://<KIBANA_URL>/api/ml/saved_objects/sync' \
 --header "Authorization: $API_KEY"

Response examples (200)

{
  "datafeedsAdded": {},
  "datafeedsRemoved": {},
  "savedObjectsCreated": {
    "anomaly-detector": {
      "myjob1": {
        "success": true
      },
      "myjob2": {
        "success": true
      }
    }
  },
  "savedObjectsDeleted": {}
}

Get all roles

GET /api/security/role

Query parameters

replaceDeprecatedPrivileges boolean

If true and the response contains any privileges that are associated with deprecated features, they are omitted in favor of details about the appropriate replacement feature privileges.

Responses

200

Indicates a successful call.

GET /api/security/role

curl \
 --request GET 'https://<KIBANA_URL>/api/security/role' \
 --header "Authorization: $API_KEY"

Get a role

GET /api/security/role/{name}

Path parameters

name string Required

The role name.

Minimum length is 1.

Query parameters

replaceDeprecatedPrivileges boolean

If true and the response contains any privileges that are associated with deprecated features, they are omitted in favor of details about the appropriate replacement feature privileges.

Responses

200

Indicates a successful call.

GET /api/security/role/{name}

curl \
 --request GET 'https://<KIBANA_URL>/api/security/role/{name}' \
 --header "Authorization: $API_KEY"

Create or update a role

PUT /api/security/role/{name}

Create a new Kibana role or update the attributes of an existing role. Kibana roles are stored in the Elasticsearch native realm.

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

Path parameters

name string Required

The role name.

Minimum length is 1, maximum length is 1024.

Query parameters

createOnly boolean

When true, a role is not overwritten if it already exists.

Default value is false.

application/json

Body

description string

A description for the role.

Maximum length is 2048.
elasticsearch object Required

Additional properties are NOT allowed.
Hide elasticsearch attributes Show elasticsearch attributes object
- cluster array[string]
  
  Cluster privileges that define the cluster level actions that users can perform.
- indices array[object]
  Hide indices attributes Show indices attributes object
  
  allow_restricted_indices boolean
  
  Restricted indices are a special category of indices that are used internally to store configuration data and should not be directly accessed. Only internal system roles should normally grant privileges over the restricted indices. Toggling this flag is very strongly discouraged because it could effectively grant unrestricted operations on critical data, making the entire system unstable or leaking sensitive information. If for administrative purposes you need to create a role with privileges covering restricted indices, however, you can set this property to true. In that case, the names field covers the restricted indices too.
  
  field_security object
  
  Hide field_security attribute Show field_security attribute object
  
  * array[string] Additional properties
  
  The document fields that the role members have read access to.
  
  names array[string] Required
  
  The data streams, indices, and aliases to which the permissions in this entry apply. It supports wildcards (*).
  
  At least 1 element.
  
  privileges array[string] Required
  
  The index level privileges that the role members have for the data streams and indices.
  
  At least 1 element.
  
  query string
  
  A search query that defines the documents the role members have read access to. A document within the specified data streams and indices must match this query in order for it to be accessible by the role members.
- remote_cluster array[object]
  Hide remote_cluster attributes Show remote_cluster attributes object
  
  clusters array[string] Required
  
  A list of remote cluster aliases. It supports literal strings as well as wildcards and regular expressions.
  
  At least 1 element.
  
  privileges array[string] Required
  
  The cluster level privileges for the remote cluster. The allowed values are a subset of the cluster privileges.
  
  At least 1 element.
- remote_indices array[object]
  Hide remote_indices attributes Show remote_indices attributes object
  
  allow_restricted_indices boolean
  
  Restricted indices are a special category of indices that are used internally to store configuration data and should not be directly accessed. Only internal system roles should normally grant privileges over the restricted indices. Toggling this flag is very strongly discouraged because it could effectively grant unrestricted operations on critical data, making the entire system unstable or leaking sensitive information. If for administrative purposes you need to create a role with privileges covering restricted indices, however, you can set this property to true. In that case, the names field will cover the restricted indices too.
  
  clusters array[string] Required
  
  A list of remote cluster aliases. It supports literal strings as well as wildcards and regular expressions.
  
  At least 1 element.
  
  field_security object
  
  Hide field_security attribute Show field_security attribute object
  
  * array[string] Additional properties
  
  The document fields that the role members have read access to.
  
  names array[string] Required
  
  A list of remote aliases, data streams, or indices to which the permissions apply. It supports wildcards (*).
  
  At least 1 element.
  
  privileges array[string] Required
  
  The index level privileges that role members have for the specified indices.
  
  At least 1 element.
  
  query string
  
  A search query that defines the documents the role members have read access to. A document within the specified data streams and indices must match this query in order for it to be accessible by the role members.
- run_as array[string]
  
  A user name that the role member can impersonate.
kibana array[object]
Hide kibana attributes Show kibana attributes object
- base array | null | boolean | number | object | string Required
  
  Any of:
  array-1 array | null boolean-2 boolean | null number-3 number | null object-4 object | null string-5 string | null
- feature object
  Hide feature attribute Show feature attribute object
  
  * array[string] Additional properties
  
  The privileges that the role member has for the feature.
- spaces array[string]
  
  Any of:
  array-1 array[string] array-2 array[string]
  
  At least 1 but not more than 1 element. Value is *. Default value is ["*"].
metadata object

Additional properties are allowed.

Responses

204

Indicates a successful call.

PUT /api/security/role/{name}

curl \
 --request PUT 'https://<KIBANA_URL>/api/security/role/{name}' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"description":"string","elasticsearch":{"cluster":["string"],"indices":[{"allow_restricted_indices":true,"field_security":{"additionalProperty1":["string"],"additionalProperty2":["string"]},"names":["string"],"privileges":["string"],"query":"string"}],"remote_cluster":[{"clusters":["string"],"privileges":["string"]}],"remote_indices":[{"allow_restricted_indices":true,"clusters":["string"],"field_security":{"additionalProperty1":["string"],"additionalProperty2":["string"]},"names":["string"],"privileges":["string"],"query":"string"}],"run_as":["string"]},"kibana":[{"base":[],"feature":{"additionalProperty1":["string"],"additionalProperty2":["string"]},"spaces":["*"]}],"metadata":{}}'

Delete a role

DELETE /api/security/role/{name}

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

Path parameters

name string Required

Minimum length is 1.

Responses

204

Indicates a successful call.

DELETE /api/security/role/{name}

curl \
 --request DELETE 'https://<KIBANA_URL>/api/security/role/{name}' \
 --header "Authorization: $API_KEY" \
 --header "kbn-xsrf: true"

Create or update roles

POST /api/security/roles

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

application/json

Body

roles object Required
Hide roles attribute Show roles attribute object
- * object Additional properties
  
  Additional properties are NOT allowed.
  Hide * attributes Show * attributes object
  
  description string
  
  A description for the role.
  
  Maximum length is 2048.
  
  elasticsearch object Required
  
  Additional properties are NOT allowed.
  
  Hide elasticsearch attributes Show elasticsearch attributes object
  
  cluster array[string]
  
  Cluster privileges that define the cluster level actions that users can perform.
  
  indices array[object]
  
  Hide indices attributes Show indices attributes object
  
  allow_restricted_indices boolean
  
  Restricted indices are a special category of indices that are used internally to store configuration data and should not be directly accessed. Only internal system roles should normally grant privileges over the restricted indices. Toggling this flag is very strongly discouraged because it could effectively grant unrestricted operations on critical data, making the entire system unstable or leaking sensitive information. If for administrative purposes you need to create a role with privileges covering restricted indices, however, you can set this property to true. In that case, the names field covers the restricted indices too.
  
  field_security object
  
  Hide field_security attribute Show field_security attribute object
  
  * array[string] Additional properties
  
  The document fields that the role members have read access to.
  
  names array[string] Required
  
  The data streams, indices, and aliases to which the permissions in this entry apply. It supports wildcards (*).
  
  At least 1 element.
  
  privileges array[string] Required
  
  The index level privileges that the role members have for the data streams and indices.
  
  At least 1 element.
  
  query string
  
  A search query that defines the documents the role members have read access to. A document within the specified data streams and indices must match this query in order for it to be accessible by the role members.
  
  remote_cluster array[object]
  
  Hide remote_cluster attributes Show remote_cluster attributes object
  
  clusters array[string] Required
  
  A list of remote cluster aliases. It supports literal strings as well as wildcards and regular expressions.
  
  At least 1 element.
  
  privileges array[string] Required
  
  The cluster level privileges for the remote cluster. The allowed values are a subset of the cluster privileges.
  
  At least 1 element.
  
  remote_indices array[object]
  
  Hide remote_indices attributes Show remote_indices attributes object
  
  allow_restricted_indices boolean
  
  Restricted indices are a special category of indices that are used internally to store configuration data and should not be directly accessed. Only internal system roles should normally grant privileges over the restricted indices. Toggling this flag is very strongly discouraged because it could effectively grant unrestricted operations on critical data, making the entire system unstable or leaking sensitive information. If for administrative purposes you need to create a role with privileges covering restricted indices, however, you can set this property to true. In that case, the names field will cover the restricted indices too.
  
  clusters array[string] Required
  
  A list of remote cluster aliases. It supports literal strings as well as wildcards and regular expressions.
  
  At least 1 element.
  
  field_security object
  
  Hide field_security attribute Show field_security attribute object
  
  * array[string] Additional properties
  
  The document fields that the role members have read access to.
  
  names array[string] Required
  
  A list of remote aliases, data streams, or indices to which the permissions apply. It supports wildcards (*).
  
  At least 1 element.
  
  privileges array[string] Required
  
  The index level privileges that role members have for the specified indices.
  
  At least 1 element.
  
  query string
  
  A search query that defines the documents the role members have read access to. A document within the specified data streams and indices must match this query in order for it to be accessible by the role members.
  
  run_as array[string]
  
  A user name that the role member can impersonate.
  
  kibana array[object]
  
  Hide kibana attributes Show kibana attributes object
  
  base array | null | boolean | number | object | string Required
  
  Any of:
  array-1 array | null boolean-2 boolean | null number-3 number | null object-4 object | null string-5 string | null
  
  feature object
  
  Hide feature attribute Show feature attribute object
  
  * array[string] Additional properties
  
  The privileges that the role member has for the feature.
  
  spaces array[string]
  
  Any of:
  array-1 array[string] array-2 array[string]
  
  At least 1 but not more than 1 element. Value is *. Default value is ["*"].
  
  metadata object
  
  Additional properties are allowed.

Responses

200

Indicates a successful call.

POST /api/security/roles

curl \
 --request POST 'https://<KIBANA_URL>/api/security/roles' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"roles":{"additionalProperty1":{"description":"string","elasticsearch":{"cluster":["string"],"indices":[{"allow_restricted_indices":true,"field_security":{"additionalProperty1":["string"],"additionalProperty2":["string"]},"names":["string"],"privileges":["string"],"query":"string"}],"remote_cluster":[{"clusters":["string"],"privileges":["string"]}],"remote_indices":[{"allow_restricted_indices":true,"clusters":["string"],"field_security":{"additionalProperty1":["string"],"additionalProperty2":["string"]},"names":["string"],"privileges":["string"],"query":"string"}],"run_as":["string"]},"kibana":[{"base":[],"feature":{"additionalProperty1":["string"],"additionalProperty2":["string"]},"spaces":["*"]}],"metadata":{}},"additionalProperty2":{"description":"string","elasticsearch":{"cluster":["string"],"indices":[{"allow_restricted_indices":true,"field_security":{"additionalProperty1":["string"],"additionalProperty2":["string"]},"names":["string"],"privileges":["string"],"query":"string"}],"remote_cluster":[{"clusters":["string"],"privileges":["string"]}],"remote_indices":[{"allow_restricted_indices":true,"clusters":["string"],"field_security":{"additionalProperty1":["string"],"additionalProperty2":["string"]},"names":["string"],"privileges":["string"],"query":"string"}],"run_as":["string"]},"kibana":[{"base":[],"feature":{"additionalProperty1":["string"],"additionalProperty2":["string"]},"spaces":["*"]}],"metadata":{}}}}'

Export saved objects

POST /api/saved_objects/_export

Retrieve sets of saved objects that you want to import into Kibana. You must include type or objects in the request body.

Exported saved objects are not backwards compatible and cannot be imported into an older version of Kibana.

NOTE: The savedObjects.maxImportExportSize configuration setting limits the number of saved objects which may be exported.

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

application/json

Body

excludeExportDetails boolean

Do not add export details entry at the end of the stream.

Default value is false.
hasReference object | array[object]
Any of:
object-1 object array-2 array[object]
Hide attributes Show attributes

id string Required

type string Required
Hide attributes Show attributes object

id string Required

type string Required
includeReferencesDeep boolean

Includes all of the referenced objects in the exported objects.

Default value is false.
objects array[object]

A list of objects to export. NOTE: this optiona cannot be combined with types option

Not more than 10000 elements.
Hide objects attributes Show objects attributes object
- id string Required
- type string Required
search string

Search for documents to export using the Elasticsearch Simple Query String syntax.
type string | array[string]

The saved object types to include in the export. Use * to export all the types.

Any of:
string-1 string array-2 array[string]

Responses

200 application/x-ndjson

Indicates a successfull call.
400 application/json

Bad request.
Hide response attributes Show response attributes object
- error string Required
- message string Required
- statusCode integer Required
  
  Value is 400.

POST /api/saved_objects/_export

curl \
 --request POST 'https://<KIBANA_URL>/api/saved_objects/_export' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"objects":[{"id":"de71f4f0-1902-11e9-919b-ffe5949a18d2","type":"map"}],"excludeExportDetails":true,"includeReferencesDeep":false}'

Request example

{
  "objects": [
    {
      "id": "de71f4f0-1902-11e9-919b-ffe5949a18d2",
      "type": "map"
    }
  ],
  "excludeExportDetails": true,
  "includeReferencesDeep": false
}

Response examples (200)

{
  "id": "de71f4f0-1902-11e9-919b-ffe5949a18d2",
  "type": "map",
  "managed": false,
  "version": "WzEzLDFd",
  "attributes": {
    "title": "[Logs] Total Requests and Bytes",
    "description": "",
    "uiStateJSON": "{\"isDarkMode\":false}",
    "mapStateJSON": "{\"zoom\":3.64,\"center\":{\"lon\":-88.92107,\"lat\":42.16337},\"timeFilters\":{\"from\":\"now-7d\",\"to\":\"now\"},\"refreshConfig\":{\"isPaused\":true,\"interval\":0},\"query\":{\"language\":\"kuery\",\"query\":\"\"},\"settings\":{\"autoFitToDataBounds\":false}}",
    "layerListJSON": "[{\"id\":\"0hmz5\",\"alpha\":1,\"sourceDescriptor\":{\"type\":\"EMS_TMS\",\"isAutoSelect\":true,\"lightModeDefault\":\"road_map_desaturated\"},\"visible\":true,\"style\":{},\"type\":\"EMS_VECTOR_TILE\",\"minZoom\":0,\"maxZoom\":24},{\"id\":\"edh66\",\"label\":\"Total Requests by Destination\",\"minZoom\":0,\"maxZoom\":24,\"alpha\":0.5,\"sourceDescriptor\":{\"type\":\"EMS_FILE\",\"id\":\"world_countries\",\"tooltipProperties\":[\"name\",\"iso2\"]},\"visible\":true,\"style\":{\"type\":\"VECTOR\",\"properties\":{\"fillColor\":{\"type\":\"DYNAMIC\",\"options\":{\"field\":{\"name\":\"__kbnjoin__count__673ff994-fc75-4c67-909b-69fcb0e1060e\",\"origin\":\"join\"},\"color\":\"Greys\",\"fieldMetaOptions\":{\"isEnabled\":false,\"sigma\":3}}},\"lineColor\":{\"type\":\"STATIC\",\"options\":{\"color\":\"#FFFFFF\"}},\"lineWidth\":{\"type\":\"STATIC\",\"options\":{\"size\":1}},\"iconSize\":{\"type\":\"STATIC\",\"options\":{\"size\":10}},\"symbolizeAs\":{\"options\":{\"value\":\"circle\"}},\"icon\":{\"type\":\"STATIC\",\"options\":{\"value\":\"marker\"}}}},\"type\":\"GEOJSON_VECTOR\",\"joins\":[{\"leftField\":\"iso2\",\"right\":{\"type\":\"ES_TERM_SOURCE\",\"id\":\"673ff994-fc75-4c67-909b-69fcb0e1060e\",\"indexPatternTitle\":\"kibana_sample_data_logs\",\"term\":\"geo.dest\",\"indexPatternRefName\":\"layer_1_join_0_index_pattern\",\"metrics\":[{\"type\":\"count\",\"label\":\"web logs count\"}],\"applyGlobalQuery\":true}}]},{\"id\":\"gaxya\",\"label\":\"Actual Requests\",\"minZoom\":9,\"maxZoom\":24,\"alpha\":1,\"sourceDescriptor\":{\"id\":\"b7486535-171b-4d3b-bb2e-33c1a0a2854c\",\"type\":\"ES_SEARCH\",\"geoField\":\"geo.coordinates\",\"limit\":2048,\"filterByMapBounds\":true,\"tooltipProperties\":[\"clientip\",\"timestamp\",\"host\",\"request\",\"response\",\"machine.os\",\"agent\",\"bytes\"],\"indexPatternRefName\":\"layer_2_source_index_pattern\",\"applyGlobalQuery\":true,\"scalingType\":\"LIMIT\"},\"visible\":true,\"style\":{\"type\":\"VECTOR\",\"properties\":{\"fillColor\":{\"type\":\"STATIC\",\"options\":{\"color\":\"#2200ff\"}},\"lineColor\":{\"type\":\"STATIC\",\"options\":{\"color\":\"#FFFFFF\"}},\"lineWidth\":{\"type\":\"STATIC\",\"options\":{\"size\":2}},\"iconSize\":{\"type\":\"DYNAMIC\",\"options\":{\"field\":{\"name\":\"bytes\",\"origin\":\"source\"},\"minSize\":1,\"maxSize\":23,\"fieldMetaOptions\":{\"isEnabled\":false,\"sigma\":3}}},\"symbolizeAs\":{\"options\":{\"value\":\"circle\"}},\"icon\":{\"type\":\"STATIC\",\"options\":{\"value\":\"marker\"}}}},\"type\":\"GEOJSON_VECTOR\"},{\"id\":\"tfi3f\",\"label\":\"Total Requests and Bytes\",\"minZoom\":0,\"maxZoom\":9,\"alpha\":1,\"sourceDescriptor\":{\"type\":\"ES_GEO_GRID\",\"resolution\":\"COARSE\",\"id\":\"8aaa65b5-a4e9-448b-9560-c98cb1c5ac5b\",\"geoField\":\"geo.coordinates\",\"requestType\":\"point\",\"metrics\":[{\"type\":\"count\",\"label\":\"web logs count\"},{\"type\":\"sum\",\"field\":\"bytes\"}],\"indexPatternRefName\":\"layer_3_source_index_pattern\",\"applyGlobalQuery\":true},\"visible\":true,\"style\":{\"type\":\"VECTOR\",\"properties\":{\"fillColor\":{\"type\":\"DYNAMIC\",\"options\":{\"field\":{\"name\":\"doc_count\",\"origin\":\"source\"},\"color\":\"Blues\",\"fieldMetaOptions\":{\"isEnabled\":false,\"sigma\":3}}},\"lineColor\":{\"type\":\"STATIC\",\"options\":{\"color\":\"#cccccc\"}},\"lineWidth\":{\"type\":\"STATIC\",\"options\":{\"size\":1}},\"iconSize\":{\"type\":\"DYNAMIC\",\"options\":{\"field\":{\"name\":\"sum_of_bytes\",\"origin\":\"source\"},\"minSize\":7,\"maxSize\":25,\"fieldMetaOptions\":{\"isEnabled\":false,\"sigma\":3}}},\"labelText\":{\"type\":\"DYNAMIC\",\"options\":{\"field\":{\"name\":\"doc_count\",\"origin\":\"source\"},\"fieldMetaOptions\":{\"isEnabled\":false,\"sigma\":3}}},\"labelSize\":{\"type\":\"DYNAMIC\",\"options\":{\"field\":{\"name\":\"doc_count\",\"origin\":\"source\"},\"minSize\":12,\"maxSize\":24,\"fieldMetaOptions\":{\"isEnabled\":false,\"sigma\":3}}},\"symbolizeAs\":{\"options\":{\"value\":\"circle\"}},\"icon\":{\"type\":\"STATIC\",\"options\":{\"value\":\"marker\"}}}},\"type\":\"GEOJSON_VECTOR\"}]"
  },
  "created_at": "2023-08-23T20:03:32.204Z",
  "references": [
    {
      "id": "90943e30-9a47-11e8-b64d-95841ca0b247",
      "name": "layer_1_join_0_index_pattern",
      "type": "index-pattern"
    },
    {
      "id": "90943e30-9a47-11e8-b64d-95841ca0b247",
      "name": "layer_2_source_index_pattern",
      "type": "index-pattern"
    },
    {
      "id": "90943e30-9a47-11e8-b64d-95841ca0b247",
      "name": "layer_3_source_index_pattern",
      "type": "index-pattern"
    }
  ],
  "updated_at": "2023-08-23T20:03:32.204Z",
  "coreMigrationVersion": "8.8.0",
  "typeMigrationVersion": "8.4.0"
}

Import saved objects

POST /api/saved_objects/_import

Create sets of Kibana saved objects from a file created by the export API. Saved objects can only be imported into the same version, a newer minor on the same major, or the next major. Exported saved objects are not backwards compatible and cannot be imported into an older version of Kibana.

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

Query parameters

overwrite boolean

Overwrites saved objects when they already exist. When used, potential conflict errors are automatically resolved by overwriting the destination object. NOTE: This option cannot be used with the createNewCopies option.

Default value is false.
createNewCopies boolean

Creates copies of saved objects, regenerates each object ID, and resets the origin. When used, potential conflict errors are avoided. NOTE: This option cannot be used with the overwrite and compatibilityMode options.

Default value is false.
compatibilityMode boolean

Applies various adjustments to the saved objects that are being imported to maintain compatibility between different Kibana versions. Use this option only if you encounter issues with imported saved objects. NOTE: This option cannot be used with the createNewCopies option.

Default value is false.

multipart/form-data

Body

file object Required

A file exported using the export API. Changing the contents of the exported file in any way before importing it can cause errors, crashes or data loss. NOTE: The savedObjects.maxImportExportSize configuration setting limits the number of saved objects which may be included in this file. Similarly, the savedObjects.maxImportPayloadBytes setting limits the overall size of the file that can be imported.

Responses

200 application/json

Indicates a successful call.
Hide response attributes Show response attributes object
- errors array[object] Required
  
  Indicates the import was unsuccessful and specifies the objects that failed to import.
  
  NOTE: One object may result in multiple errors, which requires separate steps to resolve. For instance, a missing_references error and conflict error.
  
  Additional properties are allowed.
- success boolean Required
  
  Indicates when the import was successfully completed. When set to false, some objects may not have been created. For additional information, refer to the errors and successResults properties.
- successCount number Required
  
  Indicates the number of successfully imported records.
- successResults array[object] Required
  
  Indicates the objects that are successfully imported, with any metadata if applicable.
  
  NOTE: Objects are created only when all resolvable errors are addressed, including conflicts and missing references. If objects are created as new copies, each entry in the successResults array includes a destinationId attribute.
  
  Additional properties are allowed.
400 application/json

Bad request.
Hide response attributes Show response attributes object
- error string Required
- message string Required
- statusCode integer Required
  
  Value is 400.

POST /api/saved_objects/_import

curl \
  -X POST api/saved_objects/_import?createNewCopies=true
  -H "kbn-xsrf: true"
  --form file=@file.ndjson

Request example

{"file"=>"file.ndjson"}

Response examples (200)

{
  "success": true,
  "successCount": 1,
  "successResults": [
    {
      "id": "90943e30-9a47-11e8-b64d-95841ca0b247",
      "meta": {
        "icon": "indexPatternApp",
        "title": "Kibana Sample Data Logs"
      },
      "type": "index-pattern",
      "managed": false,
      "destinationId": "82d2760c-468f-49cf-83aa-b9a35b6a8943"
    }
  ]
}

Apply a bulk action to anonymization fields

POST /api/security_ai_assistant/anonymization_fields/_bulk_action

Apply a bulk action to multiple anonymization fields. The bulk action is applied to all anonymization fields that match the filter or to the list of anonymization fields by their IDs.

application/json

Body

create array[object]
Hide create attributes Show create attributes object
- allowed boolean
- anonymized boolean
- field string Required
delete object
Hide delete attributes Show delete attributes object
- ids array[string]
  
  Array of anonymization fields IDs
  
  At least 1 element.
- query string
  
  Query to filter anonymization fields
update array[object]
Hide update attributes Show update attributes object
- allowed boolean
- anonymized boolean
- id string Required

Responses

200 application/json

Indicates a successful call.
Hide response attributes Show response attributes object
- anonymization_fields_count integer
- attributes object Required
  
  Hide attributes attributes Show attributes attributes object
  
  errors array[object]
  
  Hide errors attributes Show errors attributes object
  
  anonymization_fields array[object] Required
  
  Hide anonymization_fields attributes Show anonymization_fields attributes object
  
  id string Required
  
  name string
  
  err_code string
  
  message string Required
  
  status_code integer Required
  
  results object Required
  
  Hide results attributes Show results attributes object
  
  created array[object] Required
  
  Hide created attributes Show created attributes object
  
  allowed boolean
  
  anonymized boolean
  
  createdAt string
  
  createdBy string
  
  field string Required
  
  id string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  namespace string
  
  Kibana space
  
  timestamp string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  updatedAt string
  
  updatedBy string
  
  deleted array[string] Required
  
  skipped array[object] Required
  
  Hide skipped attributes Show skipped attributes object
  
  id string Required
  
  name string
  
  skip_reason string Required
  
  Value is ANONYMIZATION_FIELD_NOT_MODIFIED.
  
  updated array[object] Required
  
  Hide updated attributes Show updated attributes object
  
  allowed boolean
  
  anonymized boolean
  
  createdAt string
  
  createdBy string
  
  field string Required
  
  id string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  namespace string
  
  Kibana space
  
  timestamp string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  updatedAt string
  
  updatedBy string
  
  summary object Required
  
  Hide summary attributes Show summary attributes object
  
  failed integer Required
  
  skipped integer Required
  
  succeeded integer Required
  
  total integer Required
- message string
- status_code integer
- success boolean
400 application/json

Generic Error
Hide response attributes Show response attributes object
- error string
- message string
- statusCode number

POST /api/security_ai_assistant/anonymization_fields/_bulk_action

curl \
 --request POST 'https://<KIBANA_URL>/api/security_ai_assistant/anonymization_fields/_bulk_action' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"create":[{"allowed":true,"anonymized":true,"field":"string"}],"delete":{"ids":["string"],"query":"string"},"update":[{"allowed":true,"anonymized":true,"id":"string"}]}'

Get anonymization fields

GET /api/security_ai_assistant/anonymization_fields/_find

Get a list of all anonymization fields.

Query parameters

fields array[string]
filter string

Search query
sort_field string

Field to sort by

Values are created_at, anonymized, allowed, field, or updated_at.
sort_order string

Sort order

Values are asc or desc.
page integer

Page number

Minimum value is 1. Default value is 1.
per_page integer

AnonymizationFields per page

Minimum value is 0. Default value is 20.

Responses

200 application/json

Successful response
Hide response attributes Show response attributes object
- data array[object] Required
  
  Hide data attributes Show data attributes object
  
  allowed boolean
  
  anonymized boolean
  
  createdAt string
  
  createdBy string
  
  field string Required
  
  id string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  namespace string
  
  Kibana space
  
  timestamp string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  updatedAt string
  
  updatedBy string
- page integer Required
- perPage integer Required
- total integer Required
400 application/json

Generic Error
Hide response attributes Show response attributes object
- error string
- message string
- statusCode number

GET /api/security_ai_assistant/anonymization_fields/_find

curl \
 --request GET 'https://<KIBANA_URL>/api/security_ai_assistant/anonymization_fields/_find' \
 --header "Authorization: $API_KEY"

Create a model response

POST /api/security_ai_assistant/chat/complete

Create a model response for the given chat conversation.

Query parameters

content_references_disabled boolean

If true, the response will not include content references.

Default value is false.

application/json

Body Required

connectorId string Required
conversationId string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.
isStream boolean
langSmithApiKey string
langSmithProject string
messages array[object] Required

AI assistant message.
Hide messages attributes Show messages attributes object
- content string
  
  Message content.
- data object
  
  ECS object to attach to the context of the message.
  
  Additional properties are allowed.
- fields_to_anonymize array[string]
- role string Required
  
  Message role.
  
  Values are system, user, or assistant.
model string
persist boolean Required
promptId string
responseLanguage string

Responses

200 application/octet-stream

Indicates a successful call.
400 application/json

Generic Error
Hide response attributes Show response attributes object
- error string
- message string
- statusCode number

POST /api/security_ai_assistant/chat/complete

curl \
 --request POST 'https://<KIBANA_URL>/api/security_ai_assistant/chat/complete' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"connectorId":"string","conversationId":"string","isStream":true,"langSmithApiKey":"string","langSmithProject":"string","messages":[{"content":"string","data":{},"fields_to_anonymize":["string"],"role":"system"}],"model":"string","persist":true,"promptId":"string","responseLanguage":"string"}'

Create a conversation

POST /api/security_ai_assistant/current_user/conversations

Create a new Security AI Assistant conversation.

application/json

Body Required

apiConfig object

LLM API configuration.
Hide apiConfig attributes Show apiConfig attributes object
- actionTypeId string Required
  
  action type id
- connectorId string Required
  
  connector id
- defaultSystemPromptId string
  
  defaultSystemPromptId
- model string
  
  model
- provider string
  
  Provider
  
  Values are OpenAI, Azure OpenAI, or Other.
category string

The conversation category.

Values are assistant or insights.
excludeFromLastConversationStorage boolean

excludeFromLastConversationStorage.
id string

The conversation id.
messages array[object]

The conversation messages.

AI assistant conversation message.
Hide messages attributes Show messages attributes object
- content string Required
  
  Message content.
- isError boolean
  
  Is error message.
- metadata object
  
  metadata
  Hide metadata attribute Show metadata attribute object
  
  contentReferences object
  
  Data refered to by the message content.
- reader object
  
  Message content.
  
  Additional properties are allowed.
- role string Required
  
  Message role.
  
  Values are system, user, or assistant.
- timestamp string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- traceData object
  
  trace Data
  Hide traceData attributes Show traceData attributes object
  
  traceId string
  
  Could be any string, not necessarily a UUID
  
  transactionId string
  
  Could be any string, not necessarily a UUID
replacements object

Replacements object used to anonymize/deanomymize messsages
Hide replacements attribute Show replacements attribute object
- * string Additional properties
title string Required

The conversation title.

Responses

200 application/json

Indicates a successful call.
Hide response attributes Show response attributes object
- apiConfig object
  
  LLM API configuration.
  
  Hide apiConfig attributes Show apiConfig attributes object
  
  actionTypeId string Required
  
  action type id
  
  connectorId string Required
  
  connector id
  
  defaultSystemPromptId string
  
  defaultSystemPromptId
  
  model string
  
  model
  
  provider string
  
  Provider
  
  Values are OpenAI, Azure OpenAI, or Other.
- category string Required
  
  The conversation category.
  
  Values are assistant or insights.
- createdAt string Required
  
  The time conversation was created.
- excludeFromLastConversationStorage boolean
  
  excludeFromLastConversationStorage.
- id string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- messages array[object]
  
  The conversation messages.
  
  AI assistant conversation message.
  
  Hide messages attributes Show messages attributes object
  
  content string Required
  
  Message content.
  
  isError boolean
  
  Is error message.
  
  metadata object
  
  metadata
  
  Hide metadata attribute Show metadata attribute object
  
  contentReferences object
  
  Data refered to by the message content.
  
  reader object
  
  Message content.
  
  Additional properties are allowed.
  
  role string Required
  
  Message role.
  
  Values are system, user, or assistant.
  
  timestamp string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  traceData object
  
  trace Data
  
  Hide traceData attributes Show traceData attributes object
  
  traceId string
  
  Could be any string, not necessarily a UUID
  
  transactionId string
  
  Could be any string, not necessarily a UUID
- namespace string Required
  
  Kibana space
- replacements object
  
  Replacements object used to anonymize/deanomymize messsages
  
  Hide replacements attribute Show replacements attribute object
  
  * string Additional properties
- summary object
  
  Hide summary attributes Show summary attributes object
  
  confidence string
  
  How confident you are about this being a correct and useful learning.
  
  Values are low, medium, or high.
  
  content string
  
  Summary text of the conversation over time.
  
  public boolean
  
  Define if summary is marked as publicly available.
  
  timestamp string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- timestamp string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- title string Required
  
  The conversation title.
- updatedAt string
  
  The last time conversation was updated.
- users array[object] Required
  
  Could be any string, not necessarily a UUID
  
  Hide users attributes Show users attributes object
  
  id string
  
  User id
  
  name string
  
  User name
400 application/json

Generic Error
Hide response attributes Show response attributes object
- error string
- message string
- statusCode number

POST /api/security_ai_assistant/current_user/conversations

curl \
 --request POST 'https://<KIBANA_URL>/api/security_ai_assistant/current_user/conversations' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"apiConfig":{"actionTypeId":"string","connectorId":"string","defaultSystemPromptId":"string","model":"string","provider":"OpenAI"},"category":"assistant","excludeFromLastConversationStorage":true,"id":"string","messages":[{"content":"string","isError":true,"metadata":{"contentReferences":{}},"reader":{},"role":"system","timestamp":"string","traceData":{"traceId":"string","transactionId":"string"}}],"replacements":{"additionalProperty1":"string","additionalProperty2":"string"},"title":"string"}'

Get conversations

GET /api/security_ai_assistant/current_user/conversations/_find

Get a list of all conversations for the current user.

Query parameters

fields array[string]
filter string

Search query
sort_field string

Field to sort by

Values are created_at, title, or updated_at.
sort_order string

Sort order

Values are asc or desc.
page integer

Page number

Minimum value is 1. Default value is 1.
per_page integer

Conversations per page

Minimum value is 0. Default value is 20.

Responses

200 application/json

Successful response
Hide response attributes Show response attributes object
- data array[object] Required
  
  Hide data attributes Show data attributes object
  
  apiConfig object
  
  LLM API configuration.
  
  Hide apiConfig attributes Show apiConfig attributes object
  
  actionTypeId string Required
  
  action type id
  
  connectorId string Required
  
  connector id
  
  defaultSystemPromptId string
  
  defaultSystemPromptId
  
  model string
  
  model
  
  provider string
  
  Provider
  
  Values are OpenAI, Azure OpenAI, or Other.
  
  category string Required
  
  The conversation category.
  
  Values are assistant or insights.
  
  createdAt string Required
  
  The time conversation was created.
  
  excludeFromLastConversationStorage boolean
  
  excludeFromLastConversationStorage.
  
  id string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  messages array[object]
  
  The conversation messages.
  
  AI assistant conversation message.
  
  Hide messages attributes Show messages attributes object
  
  content string Required
  
  Message content.
  
  isError boolean
  
  Is error message.
  
  metadata object
  
  metadata
  
  Hide metadata attribute Show metadata attribute object
  
  contentReferences object
  
  Data refered to by the message content.
  
  reader object
  
  Message content.
  
  Additional properties are allowed.
  
  role string Required
  
  Message role.
  
  Values are system, user, or assistant.
  
  timestamp string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  traceData object
  
  trace Data
  
  Hide traceData attributes Show traceData attributes object
  
  traceId string
  
  Could be any string, not necessarily a UUID
  
  transactionId string
  
  Could be any string, not necessarily a UUID
  
  namespace string Required
  
  Kibana space
  
  replacements object
  
  Replacements object used to anonymize/deanomymize messsages
  
  Hide replacements attribute Show replacements attribute object
  
  * string Additional properties
  
  summary object
  
  Hide summary attributes Show summary attributes object
  
  confidence string
  
  How confident you are about this being a correct and useful learning.
  
  Values are low, medium, or high.
  
  content string
  
  Summary text of the conversation over time.
  
  public boolean
  
  Define if summary is marked as publicly available.
  
  timestamp string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  timestamp string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  title string Required
  
  The conversation title.
  
  updatedAt string
  
  The last time conversation was updated.
  
  users array[object] Required
  
  Could be any string, not necessarily a UUID
  
  Hide users attributes Show users attributes object
  
  id string
  
  User id
  
  name string
  
  User name
- page integer Required
- perPage integer Required
- total integer Required
400 application/json

Generic Error
Hide response attributes Show response attributes object
- error string
- message string
- statusCode number

GET /api/security_ai_assistant/current_user/conversations/_find

curl \
 --request GET 'https://<KIBANA_URL>/api/security_ai_assistant/current_user/conversations/_find' \
 --header "Authorization: $API_KEY"

Get a conversation

GET /api/security_ai_assistant/current_user/conversations/{id}

Get the details of an existing conversation using the conversation ID.

Path parameters

id string(nonempty) Required

The conversation's id value.

Minimum length is 1.

Responses

200 application/json

Indicates a successful call.
Hide response attributes Show response attributes object
- apiConfig object
  
  LLM API configuration.
  
  Hide apiConfig attributes Show apiConfig attributes object
  
  actionTypeId string Required
  
  action type id
  
  connectorId string Required
  
  connector id
  
  defaultSystemPromptId string
  
  defaultSystemPromptId
  
  model string
  
  model
  
  provider string
  
  Provider
  
  Values are OpenAI, Azure OpenAI, or Other.
- category string Required
  
  The conversation category.
  
  Values are assistant or insights.
- createdAt string Required
  
  The time conversation was created.
- excludeFromLastConversationStorage boolean
  
  excludeFromLastConversationStorage.
- id string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- messages array[object]
  
  The conversation messages.
  
  AI assistant conversation message.
  
  Hide messages attributes Show messages attributes object
  
  content string Required
  
  Message content.
  
  isError boolean
  
  Is error message.
  
  metadata object
  
  metadata
  
  Hide metadata attribute Show metadata attribute object
  
  contentReferences object
  
  Data refered to by the message content.
  
  reader object
  
  Message content.
  
  Additional properties are allowed.
  
  role string Required
  
  Message role.
  
  Values are system, user, or assistant.
  
  timestamp string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  traceData object
  
  trace Data
  
  Hide traceData attributes Show traceData attributes object
  
  traceId string
  
  Could be any string, not necessarily a UUID
  
  transactionId string
  
  Could be any string, not necessarily a UUID
- namespace string Required
  
  Kibana space
- replacements object
  
  Replacements object used to anonymize/deanomymize messsages
  
  Hide replacements attribute Show replacements attribute object
  
  * string Additional properties
- summary object
  
  Hide summary attributes Show summary attributes object
  
  confidence string
  
  How confident you are about this being a correct and useful learning.
  
  Values are low, medium, or high.
  
  content string
  
  Summary text of the conversation over time.
  
  public boolean
  
  Define if summary is marked as publicly available.
  
  timestamp string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- timestamp string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- title string Required
  
  The conversation title.
- updatedAt string
  
  The last time conversation was updated.
- users array[object] Required
  
  Could be any string, not necessarily a UUID
  
  Hide users attributes Show users attributes object
  
  id string
  
  User id
  
  name string
  
  User name
400 application/json

Generic Error
Hide response attributes Show response attributes object
- error string
- message string
- statusCode number

GET /api/security_ai_assistant/current_user/conversations/{id}

curl \
 --request GET 'https://<KIBANA_URL>/api/security_ai_assistant/current_user/conversations/{id}' \
 --header "Authorization: $API_KEY"

Update a conversation

PUT /api/security_ai_assistant/current_user/conversations/{id}

Update an existing conversation using the conversation ID.

Path parameters

id string(nonempty) Required

The conversation's id value.

Minimum length is 1.

application/json

Body Required

apiConfig object

LLM API configuration.
Hide apiConfig attributes Show apiConfig attributes object
- actionTypeId string Required
  
  action type id
- connectorId string Required
  
  connector id
- defaultSystemPromptId string
  
  defaultSystemPromptId
- model string
  
  model
- provider string
  
  Provider
  
  Values are OpenAI, Azure OpenAI, or Other.
category string

The conversation category.

Values are assistant or insights.
excludeFromLastConversationStorage boolean

excludeFromLastConversationStorage.
id string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.
messages array[object]

The conversation messages.

AI assistant conversation message.
Hide messages attributes Show messages attributes object
- content string Required
  
  Message content.
- isError boolean
  
  Is error message.
- metadata object
  
  metadata
  Hide metadata attribute Show metadata attribute object
  
  contentReferences object
  
  Data refered to by the message content.
- reader object
  
  Message content.
  
  Additional properties are allowed.
- role string Required
  
  Message role.
  
  Values are system, user, or assistant.
- timestamp string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- traceData object
  
  trace Data
  Hide traceData attributes Show traceData attributes object
  
  traceId string
  
  Could be any string, not necessarily a UUID
  
  transactionId string
  
  Could be any string, not necessarily a UUID
replacements object

Replacements object used to anonymize/deanomymize messsages
Hide replacements attribute Show replacements attribute object
- * string Additional properties
summary object
Hide summary attributes Show summary attributes object
- confidence string
  
  How confident you are about this being a correct and useful learning.
  
  Values are low, medium, or high.
- content string
  
  Summary text of the conversation over time.
- public boolean
  
  Define if summary is marked as publicly available.
- timestamp string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
title string

The conversation title.

Responses

200 application/json

Indicates a successful call.
Hide response attributes Show response attributes object
- apiConfig object
  
  LLM API configuration.
  
  Hide apiConfig attributes Show apiConfig attributes object
  
  actionTypeId string Required
  
  action type id
  
  connectorId string Required
  
  connector id
  
  defaultSystemPromptId string
  
  defaultSystemPromptId
  
  model string
  
  model
  
  provider string
  
  Provider
  
  Values are OpenAI, Azure OpenAI, or Other.
- category string Required
  
  The conversation category.
  
  Values are assistant or insights.
- createdAt string Required
  
  The time conversation was created.
- excludeFromLastConversationStorage boolean
  
  excludeFromLastConversationStorage.
- id string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- messages array[object]
  
  The conversation messages.
  
  AI assistant conversation message.
  
  Hide messages attributes Show messages attributes object
  
  content string Required
  
  Message content.
  
  isError boolean
  
  Is error message.
  
  metadata object
  
  metadata
  
  Hide metadata attribute Show metadata attribute object
  
  contentReferences object
  
  Data refered to by the message content.
  
  reader object
  
  Message content.
  
  Additional properties are allowed.
  
  role string Required
  
  Message role.
  
  Values are system, user, or assistant.
  
  timestamp string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  traceData object
  
  trace Data
  
  Hide traceData attributes Show traceData attributes object
  
  traceId string
  
  Could be any string, not necessarily a UUID
  
  transactionId string
  
  Could be any string, not necessarily a UUID
- namespace string Required
  
  Kibana space
- replacements object
  
  Replacements object used to anonymize/deanomymize messsages
  
  Hide replacements attribute Show replacements attribute object
  
  * string Additional properties
- summary object
  
  Hide summary attributes Show summary attributes object
  
  confidence string
  
  How confident you are about this being a correct and useful learning.
  
  Values are low, medium, or high.
  
  content string
  
  Summary text of the conversation over time.
  
  public boolean
  
  Define if summary is marked as publicly available.
  
  timestamp string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- timestamp string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- title string Required
  
  The conversation title.
- updatedAt string
  
  The last time conversation was updated.
- users array[object] Required
  
  Could be any string, not necessarily a UUID
  
  Hide users attributes Show users attributes object
  
  id string
  
  User id
  
  name string
  
  User name
400 application/json

Generic Error
Hide response attributes Show response attributes object
- error string
- message string
- statusCode number

PUT /api/security_ai_assistant/current_user/conversations/{id}

curl \
 --request PUT 'https://<KIBANA_URL>/api/security_ai_assistant/current_user/conversations/{id}' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"apiConfig":{"actionTypeId":"string","connectorId":"string","defaultSystemPromptId":"string","model":"string","provider":"OpenAI"},"category":"assistant","excludeFromLastConversationStorage":true,"id":"string","messages":[{"content":"string","isError":true,"metadata":{"contentReferences":{}},"reader":{},"role":"system","timestamp":"string","traceData":{"traceId":"string","transactionId":"string"}}],"replacements":{"additionalProperty1":"string","additionalProperty2":"string"},"summary":{"confidence":"low","content":"string","public":true,"timestamp":"string"},"title":"string"}'

Delete a conversation

DELETE /api/security_ai_assistant/current_user/conversations/{id}

Delete an existing conversation using the conversation ID.

Path parameters

id string(nonempty) Required

The conversation's id value.

Minimum length is 1.

Responses

200 application/json

Indicates a successful call.
Hide response attributes Show response attributes object
- apiConfig object
  
  LLM API configuration.
  
  Hide apiConfig attributes Show apiConfig attributes object
  
  actionTypeId string Required
  
  action type id
  
  connectorId string Required
  
  connector id
  
  defaultSystemPromptId string
  
  defaultSystemPromptId
  
  model string
  
  model
  
  provider string
  
  Provider
  
  Values are OpenAI, Azure OpenAI, or Other.
- category string Required
  
  The conversation category.
  
  Values are assistant or insights.
- createdAt string Required
  
  The time conversation was created.
- excludeFromLastConversationStorage boolean
  
  excludeFromLastConversationStorage.
- id string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- messages array[object]
  
  The conversation messages.
  
  AI assistant conversation message.
  
  Hide messages attributes Show messages attributes object
  
  content string Required
  
  Message content.
  
  isError boolean
  
  Is error message.
  
  metadata object
  
  metadata
  
  Hide metadata attribute Show metadata attribute object
  
  contentReferences object
  
  Data refered to by the message content.
  
  reader object
  
  Message content.
  
  Additional properties are allowed.
  
  role string Required
  
  Message role.
  
  Values are system, user, or assistant.
  
  timestamp string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  traceData object
  
  trace Data
  
  Hide traceData attributes Show traceData attributes object
  
  traceId string
  
  Could be any string, not necessarily a UUID
  
  transactionId string
  
  Could be any string, not necessarily a UUID
- namespace string Required
  
  Kibana space
- replacements object
  
  Replacements object used to anonymize/deanomymize messsages
  
  Hide replacements attribute Show replacements attribute object
  
  * string Additional properties
- summary object
  
  Hide summary attributes Show summary attributes object
  
  confidence string
  
  How confident you are about this being a correct and useful learning.
  
  Values are low, medium, or high.
  
  content string
  
  Summary text of the conversation over time.
  
  public boolean
  
  Define if summary is marked as publicly available.
  
  timestamp string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- timestamp string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- title string Required
  
  The conversation title.
- updatedAt string
  
  The last time conversation was updated.
- users array[object] Required
  
  Could be any string, not necessarily a UUID
  
  Hide users attributes Show users attributes object
  
  id string
  
  User id
  
  name string
  
  User name
400 application/json

Generic Error
Hide response attributes Show response attributes object
- error string
- message string
- statusCode number

DELETE /api/security_ai_assistant/current_user/conversations/{id}

curl \
 --request DELETE 'https://<KIBANA_URL>/api/security_ai_assistant/current_user/conversations/{id}' \
 --header "Authorization: $API_KEY"

Read a KnowledgeBase

GET /api/security_ai_assistant/knowledge_base/{resource}

Read a single KB

Path parameters

resource string

The KnowledgeBase resource value.

Responses

200 application/json

Indicates a successful call.
Hide response attributes Show response attributes object
- elser_exists boolean
- is_setup_available boolean
- is_setup_in_progress boolean
- product_documentation_status string
- security_labs_exists boolean
- user_data_exists boolean
400 application/json

Generic Error
Hide response attributes Show response attributes object
- error string
- message string
- statusCode number

GET /api/security_ai_assistant/knowledge_base/{resource}

curl \
 --request GET 'https://<KIBANA_URL>/api/security_ai_assistant/knowledge_base/{resource}' \
 --header "Authorization: $API_KEY"

Create a KnowledgeBase

POST /api/security_ai_assistant/knowledge_base/{resource}

Create a KnowledgeBase

Path parameters

resource string

The KnowledgeBase resource value.

Query parameters

modelId string

Optional ELSER modelId to use when setting up the Knowledge Base
ignoreSecurityLabs boolean

Indicates whether we should or should not install Security Labs docs when setting up the Knowledge Base

Default value is false.

Responses

200 application/json

Indicates a successful call.
Hide response attribute Show response attribute object
- success boolean
  
  Identify the success of the method execution.
400 application/json

Generic Error
Hide response attributes Show response attributes object
- error string
- message string
- statusCode number

POST /api/security_ai_assistant/knowledge_base/{resource}

curl \
 --request POST 'https://<KIBANA_URL>/api/security_ai_assistant/knowledge_base/{resource}' \
 --header "Authorization: $API_KEY"

Create a Knowledge Base Entry

POST /api/security_ai_assistant/knowledge_base/entries

Create a Knowledge Base Entry

application/json

Body object Required

global boolean

Whether this Knowledge Base Entry is global, defaults to false
name string Required

Name of the Knowledge Base Entry
namespace string

Kibana Space, defaults to 'default' space
users array[object]

Users who have access to the Knowledge Base Entry, defaults to current user. Empty array provides access to all users.

Could be any string, not necessarily a UUID
Hide users attributes Show users attributes object
- id string
  
  User id
- name string
  
  User name
kbResource string Required

Knowledge Base resource name for grouping entries, e.g. 'security_labs', 'user', etc

Values are security_labs or user.
source string Required

Source document name or filepath
text string Required

Knowledge Base Entry content
type string Required Discriminator

Entry type

Value is document.
required boolean

Whether this resource should always be included, defaults to false
vector object

Object containing Knowledge Base Entry text embeddings and modelId used to create the embeddings
Hide vector attributes Show vector attributes object
- modelId string Required
  
  ID of the model used to create the embeddings
- tokens object Required
  
  Tokens with their corresponding values
  Hide tokens attribute Show tokens attribute object
  
  * number Additional properties

global boolean

Whether this Knowledge Base Entry is global, defaults to false
name string Required

Name of the Knowledge Base Entry
namespace string

Kibana Space, defaults to 'default' space
users array[object]

Users who have access to the Knowledge Base Entry, defaults to current user. Empty array provides access to all users.

Could be any string, not necessarily a UUID
Hide users attributes Show users attributes object
- id string
  
  User id
- name string
  
  User name
description string Required

Description for when this index or data stream should be queried for Knowledge Base content. Passed to the LLM as a tool description
field string Required

Field to query for Knowledge Base content
index string Required

Index or Data Stream to query for Knowledge Base content
queryDescription string Required

Description of query field used to fetch Knowledge Base content. Passed to the LLM as part of the tool input schema
type string Required Discriminator

Entry type

Value is index.
inputSchema array[object]

Array of objects defining the input schema, allowing the LLM to extract structured data to be used in retrieval
Hide inputSchema attributes Show inputSchema attributes object
- description string Required
  
  Description of the field
- fieldName string Required
  
  Name of the field
- fieldType string Required
  
  Type of the field
outputFields array[string]

Fields to extract from the query result, defaults to all fields if not provided or empty

Responses

200 application/json

Successful request returning Knowledge Base Entries
Any of:
Security_AI_Assistant_API_DocumentEntryResponseFields object Security_AI_Assistant_API_IndexEntryResponseFields object
Hide attributes Show attributes

global boolean Required

Whether this Knowledge Base Entry is global, defaults to false

name string Required

Name of the Knowledge Base Entry

namespace string Required

Kibana Space, defaults to 'default' space

users array[object] Required

Users who have access to the Knowledge Base Entry, defaults to current user. Empty array provides access to all users.

Could be any string, not necessarily a UUID

Hide users attributes Show users attributes object

id string

User id

name string

User name

createdAt string Required

Time the Knowledge Base Entry was created

createdBy string Required

User who created the Knowledge Base Entry

id string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

updatedAt string Required

Time the Knowledge Base Entry was last updated

updatedBy string Required

User who last updated the Knowledge Base Entry

kbResource string Required

Knowledge Base resource name for grouping entries, e.g. 'security_labs', 'user', etc

Values are security_labs or user.

source string Required

Source document name or filepath

text string Required

Knowledge Base Entry content

type string Required Discriminator

Entry type

Value is document.

required boolean

Whether this resource should always be included, defaults to false

vector object

Object containing Knowledge Base Entry text embeddings and modelId used to create the embeddings

Hide vector attributes Show vector attributes object

modelId string Required

ID of the model used to create the embeddings

tokens object Required

Tokens with their corresponding values

Hide tokens attribute Show tokens attribute object

* number Additional properties
Hide attributes Show attributes

global boolean Required

Whether this Knowledge Base Entry is global, defaults to false

name string Required

Name of the Knowledge Base Entry

namespace string Required

Kibana Space, defaults to 'default' space

users array[object] Required

Users who have access to the Knowledge Base Entry, defaults to current user. Empty array provides access to all users.

Could be any string, not necessarily a UUID

Hide users attributes Show users attributes object

id string

User id

name string

User name

createdAt string Required

Time the Knowledge Base Entry was created

createdBy string Required

User who created the Knowledge Base Entry

id string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

updatedAt string Required

Time the Knowledge Base Entry was last updated

updatedBy string Required

User who last updated the Knowledge Base Entry

description string Required

Description for when this index or data stream should be queried for Knowledge Base content. Passed to the LLM as a tool description

field string Required

Field to query for Knowledge Base content

index string Required

Index or Data Stream to query for Knowledge Base content

queryDescription string Required

Description of query field used to fetch Knowledge Base content. Passed to the LLM as part of the tool input schema

type string Required Discriminator

Entry type

Value is index.

inputSchema array[object]

Array of objects defining the input schema, allowing the LLM to extract structured data to be used in retrieval

Hide inputSchema attributes Show inputSchema attributes object

description string Required

Description of the field

fieldName string Required

Name of the field

fieldType string Required

Type of the field

outputFields array[string]

Fields to extract from the query result, defaults to all fields if not provided or empty
400 application/json

Generic Error
Hide response attributes Show response attributes object
- error string Required
- message string Required
- statusCode number Required

POST /api/security_ai_assistant/knowledge_base/entries

curl \
 --request POST 'https://<KIBANA_URL>/api/security_ai_assistant/knowledge_base/entries' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"global":true,"name":"string","namespace":"string","users":[{"id":"string","name":"string"}],"kbResource":"security_labs","source":"string","text":"string","type":"document","required":true,"vector":{"modelId":"string","tokens":{"additionalProperty1":42.0,"additionalProperty2":42.0}}}'

Applies a bulk action to multiple Knowledge Base Entries

POST /api/security_ai_assistant/knowledge_base/entries/_bulk_action

The bulk action is applied to all Knowledge Base Entries that match the filter or to the list of Knowledge Base Entries by their IDs

application/json

Body

create array[object]
Any of:
Security_AI_Assistant_API_DocumentEntryCreateFields object Security_AI_Assistant_API_IndexEntryCreateFields object
Hide attributes Show attributes

global boolean

Whether this Knowledge Base Entry is global, defaults to false

name string Required

Name of the Knowledge Base Entry

namespace string

Kibana Space, defaults to 'default' space

users array[object]

Users who have access to the Knowledge Base Entry, defaults to current user. Empty array provides access to all users.

Could be any string, not necessarily a UUID

Hide users attributes Show users attributes object

id string

User id

name string

User name

kbResource string Required

Knowledge Base resource name for grouping entries, e.g. 'security_labs', 'user', etc

Values are security_labs or user.

source string Required

Source document name or filepath

text string Required

Knowledge Base Entry content

type string Required Discriminator

Entry type

Value is document.

required boolean

Whether this resource should always be included, defaults to false

vector object

Object containing Knowledge Base Entry text embeddings and modelId used to create the embeddings

Hide vector attributes Show vector attributes object

modelId string Required

ID of the model used to create the embeddings

tokens object Required

Tokens with their corresponding values

Hide tokens attribute Show tokens attribute object

* number Additional properties
Hide attributes Show attributes

global boolean

Whether this Knowledge Base Entry is global, defaults to false

name string Required

Name of the Knowledge Base Entry

namespace string

Kibana Space, defaults to 'default' space

users array[object]

Users who have access to the Knowledge Base Entry, defaults to current user. Empty array provides access to all users.

Could be any string, not necessarily a UUID

Hide users attributes Show users attributes object

id string

User id

name string

User name

description string Required

Description for when this index or data stream should be queried for Knowledge Base content. Passed to the LLM as a tool description

field string Required

Field to query for Knowledge Base content

index string Required

Index or Data Stream to query for Knowledge Base content

queryDescription string Required

Description of query field used to fetch Knowledge Base content. Passed to the LLM as part of the tool input schema

type string Required Discriminator

Entry type

Value is index.

inputSchema array[object]

Array of objects defining the input schema, allowing the LLM to extract structured data to be used in retrieval

Hide inputSchema attributes Show inputSchema attributes object

description string Required

Description of the field

fieldName string Required

Name of the field

fieldType string Required

Type of the field

outputFields array[string]

Fields to extract from the query result, defaults to all fields if not provided or empty
delete object
Hide delete attributes Show delete attributes object
- ids array[string]
  
  Array of Knowledge base Entry IDs
  
  At least 1 element.
- query string
  
  Query to filter Knowledge Base Entries
update array[object]
Any of:
Security_AI_Assistant_API_DocumentEntryCreateFields object Security_AI_Assistant_API_IndexEntryCreateFields object
Hide attributes Show attributes

global boolean

Whether this Knowledge Base Entry is global, defaults to false

id string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

name string Required

Name of the Knowledge Base Entry

namespace string

Kibana Space, defaults to 'default' space

users array[object]

Users who have access to the Knowledge Base Entry, defaults to current user. Empty array provides access to all users.

Could be any string, not necessarily a UUID

Hide users attributes Show users attributes object

id string

User id

name string

User name

kbResource string Required

Knowledge Base resource name for grouping entries, e.g. 'security_labs', 'user', etc

Values are security_labs or user.

source string Required

Source document name or filepath

text string Required

Knowledge Base Entry content

type string Required Discriminator

Entry type

Value is document.

required boolean

Whether this resource should always be included, defaults to false

vector object

Object containing Knowledge Base Entry text embeddings and modelId used to create the embeddings

Hide vector attributes Show vector attributes object

modelId string Required

ID of the model used to create the embeddings

tokens object Required

Tokens with their corresponding values

Hide tokens attribute Show tokens attribute object

* number Additional properties
Hide attributes Show attributes

global boolean

Whether this Knowledge Base Entry is global, defaults to false

id string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

name string Required

Name of the Knowledge Base Entry

namespace string

Kibana Space, defaults to 'default' space

users array[object]

Users who have access to the Knowledge Base Entry, defaults to current user. Empty array provides access to all users.

Could be any string, not necessarily a UUID

Hide users attributes Show users attributes object

id string

User id

name string

User name

description string Required

Description for when this index or data stream should be queried for Knowledge Base content. Passed to the LLM as a tool description

field string Required

Field to query for Knowledge Base content

index string Required

Index or Data Stream to query for Knowledge Base content

queryDescription string Required

Description of query field used to fetch Knowledge Base content. Passed to the LLM as part of the tool input schema

type string Required Discriminator

Entry type

Value is index.

inputSchema array[object]

Array of objects defining the input schema, allowing the LLM to extract structured data to be used in retrieval

Hide inputSchema attributes Show inputSchema attributes object

description string Required

Description of the field

fieldName string Required

Name of the field

fieldType string Required

Type of the field

outputFields array[string]

Fields to extract from the query result, defaults to all fields if not provided or empty

Responses

200 application/json

Successful bulk operation request
Hide response attributes Show response attributes object
- attributes object Required
  
  Hide attributes attributes Show attributes attributes object
  
  errors array[object]
  
  Hide errors attributes Show errors attributes object
  
  err_code string
  
  knowledgeBaseEntries array[object] Required
  
  Hide knowledgeBaseEntries attributes Show knowledgeBaseEntries attributes object
  
  id string Required
  
  name string
  
  message string Required
  
  statusCode integer Required
  
  results object Required
  
  Hide results attributes Show results attributes object
  
  created array[object] Required
  
  Any of:
  Security_AI_Assistant_API_DocumentEntryResponseFields object Security_AI_Assistant_API_IndexEntryResponseFields object
  
  Hide attributes Show attributes
  
  global boolean Required
  
  Whether this Knowledge Base Entry is global, defaults to false
  
  name string Required
  
  Name of the Knowledge Base Entry
  
  namespace string Required
  
  Kibana Space, defaults to 'default' space
  
  users array[object] Required
  
  Users who have access to the Knowledge Base Entry, defaults to current user. Empty array provides access to all users.
  
  Could be any string, not necessarily a UUID
  
  Hide users attributes Show users attributes object
  
  id string
  
  User id
  
  name string
  
  User name
  
  createdAt string Required
  
  Time the Knowledge Base Entry was created
  
  createdBy string Required
  
  User who created the Knowledge Base Entry
  
  id string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  updatedAt string Required
  
  Time the Knowledge Base Entry was last updated
  
  updatedBy string Required
  
  User who last updated the Knowledge Base Entry
  
  kbResource string Required
  
  Knowledge Base resource name for grouping entries, e.g. 'security_labs', 'user', etc
  
  Values are security_labs or user.
  
  source string Required
  
  Source document name or filepath
  
  text string Required
  
  Knowledge Base Entry content
  
  type string Required Discriminator
  
  Entry type
  
  Value is document.
  
  required boolean
  
  Whether this resource should always be included, defaults to false
  
  vector object
  
  Object containing Knowledge Base Entry text embeddings and modelId used to create the embeddings
  
  Hide vector attributes Show vector attributes object
  
  modelId string Required
  
  ID of the model used to create the embeddings
  
  tokens object Required
  
  Tokens with their corresponding values
  
  Hide tokens attribute Show tokens attribute object
  
  * number Additional properties
  
  Hide attributes Show attributes
  
  global boolean Required
  
  Whether this Knowledge Base Entry is global, defaults to false
  
  name string Required
  
  Name of the Knowledge Base Entry
  
  namespace string Required
  
  Kibana Space, defaults to 'default' space
  
  users array[object] Required
  
  Users who have access to the Knowledge Base Entry, defaults to current user. Empty array provides access to all users.
  
  Could be any string, not necessarily a UUID
  
  Hide users attributes Show users attributes object
  
  id string
  
  User id
  
  name string
  
  User name
  
  createdAt string Required
  
  Time the Knowledge Base Entry was created
  
  createdBy string Required
  
  User who created the Knowledge Base Entry
  
  id string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  updatedAt string Required
  
  Time the Knowledge Base Entry was last updated
  
  updatedBy string Required
  
  User who last updated the Knowledge Base Entry
  
  description string Required
  
  Description for when this index or data stream should be queried for Knowledge Base content. Passed to the LLM as a tool description
  
  field string Required
  
  Field to query for Knowledge Base content
  
  index string Required
  
  Index or Data Stream to query for Knowledge Base content
  
  queryDescription string Required
  
  Description of query field used to fetch Knowledge Base content. Passed to the LLM as part of the tool input schema
  
  type string Required Discriminator
  
  Entry type
  
  Value is index.
  
  inputSchema array[object]
  
  Array of objects defining the input schema, allowing the LLM to extract structured data to be used in retrieval
  
  Hide inputSchema attributes Show inputSchema attributes object
  
  description string Required
  
  Description of the field
  
  fieldName string Required
  
  Name of the field
  
  fieldType string Required
  
  Type of the field
  
  outputFields array[string]
  
  Fields to extract from the query result, defaults to all fields if not provided or empty
  
  deleted array[string] Required
  
  skipped array[object] Required
  
  Hide skipped attributes Show skipped attributes object
  
  id string Required
  
  name string
  
  skip_reason string Required
  
  Value is KNOWLEDGE_BASE_ENTRY_NOT_MODIFIED.
  
  updated array[object] Required
  
  Any of:
  Security_AI_Assistant_API_DocumentEntryResponseFields object Security_AI_Assistant_API_IndexEntryResponseFields object
  
  Hide attributes Show attributes
  
  global boolean Required
  
  Whether this Knowledge Base Entry is global, defaults to false
  
  name string Required
  
  Name of the Knowledge Base Entry
  
  namespace string Required
  
  Kibana Space, defaults to 'default' space
  
  users array[object] Required
  
  Users who have access to the Knowledge Base Entry, defaults to current user. Empty array provides access to all users.
  
  Could be any string, not necessarily a UUID
  
  Hide users attributes Show users attributes object
  
  id string
  
  User id
  
  name string
  
  User name
  
  createdAt string Required
  
  Time the Knowledge Base Entry was created
  
  createdBy string Required
  
  User who created the Knowledge Base Entry
  
  id string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  updatedAt string Required
  
  Time the Knowledge Base Entry was last updated
  
  updatedBy string Required
  
  User who last updated the Knowledge Base Entry
  
  kbResource string Required
  
  Knowledge Base resource name for grouping entries, e.g. 'security_labs', 'user', etc
  
  Values are security_labs or user.
  
  source string Required
  
  Source document name or filepath
  
  text string Required
  
  Knowledge Base Entry content
  
  type string Required Discriminator
  
  Entry type
  
  Value is document.
  
  required boolean
  
  Whether this resource should always be included, defaults to false
  
  vector object
  
  Object containing Knowledge Base Entry text embeddings and modelId used to create the embeddings
  
  Hide vector attributes Show vector attributes object
  
  modelId string Required
  
  ID of the model used to create the embeddings
  
  tokens object Required
  
  Tokens with their corresponding values
  
  Hide tokens attribute Show tokens attribute object
  
  * number Additional properties
  
  Hide attributes Show attributes
  
  global boolean Required
  
  Whether this Knowledge Base Entry is global, defaults to false
  
  name string Required
  
  Name of the Knowledge Base Entry
  
  namespace string Required
  
  Kibana Space, defaults to 'default' space
  
  users array[object] Required
  
  Users who have access to the Knowledge Base Entry, defaults to current user. Empty array provides access to all users.
  
  Could be any string, not necessarily a UUID
  
  Hide users attributes Show users attributes object
  
  id string
  
  User id
  
  name string
  
  User name
  
  createdAt string Required
  
  Time the Knowledge Base Entry was created
  
  createdBy string Required
  
  User who created the Knowledge Base Entry
  
  id string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  updatedAt string Required
  
  Time the Knowledge Base Entry was last updated
  
  updatedBy string Required
  
  User who last updated the Knowledge Base Entry
  
  description string Required
  
  Description for when this index or data stream should be queried for Knowledge Base content. Passed to the LLM as a tool description
  
  field string Required
  
  Field to query for Knowledge Base content
  
  index string Required
  
  Index or Data Stream to query for Knowledge Base content
  
  queryDescription string Required
  
  Description of query field used to fetch Knowledge Base content. Passed to the LLM as part of the tool input schema
  
  type string Required Discriminator
  
  Entry type
  
  Value is index.
  
  inputSchema array[object]
  
  Array of objects defining the input schema, allowing the LLM to extract structured data to be used in retrieval
  
  Hide inputSchema attributes Show inputSchema attributes object
  
  description string Required
  
  Description of the field
  
  fieldName string Required
  
  Name of the field
  
  fieldType string Required
  
  Type of the field
  
  outputFields array[string]
  
  Fields to extract from the query result, defaults to all fields if not provided or empty
  
  summary object Required
  
  Hide summary attributes Show summary attributes object
  
  failed integer Required
  
  skipped integer Required
  
  succeeded integer Required
  
  total integer Required
- knowledgeBaseEntriesCount integer
- message string
- statusCode integer
- success boolean
400 application/json

Generic Error
Hide response attributes Show response attributes object
- error string Required
- message string Required
- statusCode number Required

POST /api/security_ai_assistant/knowledge_base/entries/_bulk_action

curl \
 --request POST 'https://<KIBANA_URL>/api/security_ai_assistant/knowledge_base/entries/_bulk_action' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"create":[{"global":true,"name":"string","namespace":"string","users":[{"id":"string","name":"string"}],"kbResource":"security_labs","source":"string","text":"string","type":"document","required":true,"vector":{"modelId":"string","tokens":{"additionalProperty1":42.0,"additionalProperty2":42.0}}}],"delete":{"ids":["string"],"query":"string"},"update":[{"global":true,"id":"string","name":"string","namespace":"string","users":[{"id":"string","name":"string"}],"kbResource":"security_labs","source":"string","text":"string","type":"document","required":true,"vector":{"modelId":"string","tokens":{"additionalProperty1":42.0,"additionalProperty2":42.0}}}]}'

Finds Knowledge Base Entries that match the given query.

GET /api/security_ai_assistant/knowledge_base/entries/_find

Finds Knowledge Base Entries that match the given query.

Query parameters

fields array[string]
filter string

Search query
sort_field string

Field to sort by

Values are created_at, is_default, title, or updated_at.
sort_order string

Sort order

Values are asc or desc.
page integer

Page number

Minimum value is 1. Default value is 1.
per_page integer

Knowledge Base Entries per page

Minimum value is 0. Default value is 20.

Responses

200 application/json

Successful response
Hide response attributes Show response attributes object
- data array[object] Required
  
  Any of:
  Security_AI_Assistant_API_DocumentEntryResponseFields object Security_AI_Assistant_API_IndexEntryResponseFields object
  
  Hide attributes Show attributes
  
  global boolean Required
  
  Whether this Knowledge Base Entry is global, defaults to false
  
  name string Required
  
  Name of the Knowledge Base Entry
  
  namespace string Required
  
  Kibana Space, defaults to 'default' space
  
  users array[object] Required
  
  Users who have access to the Knowledge Base Entry, defaults to current user. Empty array provides access to all users.
  
  Could be any string, not necessarily a UUID
  
  Hide users attributes Show users attributes object
  
  id string
  
  User id
  
  name string
  
  User name
  
  createdAt string Required
  
  Time the Knowledge Base Entry was created
  
  createdBy string Required
  
  User who created the Knowledge Base Entry
  
  id string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  updatedAt string Required
  
  Time the Knowledge Base Entry was last updated
  
  updatedBy string Required
  
  User who last updated the Knowledge Base Entry
  
  kbResource string Required
  
  Knowledge Base resource name for grouping entries, e.g. 'security_labs', 'user', etc
  
  Values are security_labs or user.
  
  source string Required
  
  Source document name or filepath
  
  text string Required
  
  Knowledge Base Entry content
  
  type string Required Discriminator
  
  Entry type
  
  Value is document.
  
  required boolean
  
  Whether this resource should always be included, defaults to false
  
  vector object
  
  Object containing Knowledge Base Entry text embeddings and modelId used to create the embeddings
  
  Hide vector attributes Show vector attributes object
  
  modelId string Required
  
  ID of the model used to create the embeddings
  
  tokens object Required
  
  Tokens with their corresponding values
  
  Hide tokens attribute Show tokens attribute object
  
  * number Additional properties
  
  Hide attributes Show attributes
  
  global boolean Required
  
  Whether this Knowledge Base Entry is global, defaults to false
  
  name string Required
  
  Name of the Knowledge Base Entry
  
  namespace string Required
  
  Kibana Space, defaults to 'default' space
  
  users array[object] Required
  
  Users who have access to the Knowledge Base Entry, defaults to current user. Empty array provides access to all users.
  
  Could be any string, not necessarily a UUID
  
  Hide users attributes Show users attributes object
  
  id string
  
  User id
  
  name string
  
  User name
  
  createdAt string Required
  
  Time the Knowledge Base Entry was created
  
  createdBy string Required
  
  User who created the Knowledge Base Entry
  
  id string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  updatedAt string Required
  
  Time the Knowledge Base Entry was last updated
  
  updatedBy string Required
  
  User who last updated the Knowledge Base Entry
  
  description string Required
  
  Description for when this index or data stream should be queried for Knowledge Base content. Passed to the LLM as a tool description
  
  field string Required
  
  Field to query for Knowledge Base content
  
  index string Required
  
  Index or Data Stream to query for Knowledge Base content
  
  queryDescription string Required
  
  Description of query field used to fetch Knowledge Base content. Passed to the LLM as part of the tool input schema
  
  type string Required Discriminator
  
  Entry type
  
  Value is index.
  
  inputSchema array[object]
  
  Array of objects defining the input schema, allowing the LLM to extract structured data to be used in retrieval
  
  Hide inputSchema attributes Show inputSchema attributes object
  
  description string Required
  
  Description of the field
  
  fieldName string Required
  
  Name of the field
  
  fieldType string Required
  
  Type of the field
  
  outputFields array[string]
  
  Fields to extract from the query result, defaults to all fields if not provided or empty
- page integer Required
- perPage integer Required
- total integer Required
400 application/json

Generic Error
Hide response attributes Show response attributes object
- error string
- message string
- statusCode number

GET /api/security_ai_assistant/knowledge_base/entries/_find

curl \
 --request GET 'https://<KIBANA_URL>/api/security_ai_assistant/knowledge_base/entries/_find' \
 --header "Authorization: $API_KEY"

Read a Knowledge Base Entry

GET /api/security_ai_assistant/knowledge_base/entries/{id}

Read a Knowledge Base Entry

Path parameters

id string(nonempty) Required

The Knowledge Base Entry's id value.

Minimum length is 1.

Responses

200 application/json

Successful request returning a Knowledge Base Entry
Any of:
Security_AI_Assistant_API_DocumentEntryResponseFields object Security_AI_Assistant_API_IndexEntryResponseFields object
Hide attributes Show attributes

global boolean Required

Whether this Knowledge Base Entry is global, defaults to false

name string Required

Name of the Knowledge Base Entry

namespace string Required

Kibana Space, defaults to 'default' space

users array[object] Required

Users who have access to the Knowledge Base Entry, defaults to current user. Empty array provides access to all users.

Could be any string, not necessarily a UUID

Hide users attributes Show users attributes object

id string

User id

name string

User name

createdAt string Required

Time the Knowledge Base Entry was created

createdBy string Required

User who created the Knowledge Base Entry

id string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

updatedAt string Required

Time the Knowledge Base Entry was last updated

updatedBy string Required

User who last updated the Knowledge Base Entry

kbResource string Required

Knowledge Base resource name for grouping entries, e.g. 'security_labs', 'user', etc

Values are security_labs or user.

source string Required

Source document name or filepath

text string Required

Knowledge Base Entry content

type string Required Discriminator

Entry type

Value is document.

required boolean

Whether this resource should always be included, defaults to false

vector object

Object containing Knowledge Base Entry text embeddings and modelId used to create the embeddings

Hide vector attributes Show vector attributes object

modelId string Required

ID of the model used to create the embeddings

tokens object Required

Tokens with their corresponding values

Hide tokens attribute Show tokens attribute object

* number Additional properties
Hide attributes Show attributes

global boolean Required

Whether this Knowledge Base Entry is global, defaults to false

name string Required

Name of the Knowledge Base Entry

namespace string Required

Kibana Space, defaults to 'default' space

users array[object] Required

Users who have access to the Knowledge Base Entry, defaults to current user. Empty array provides access to all users.

Could be any string, not necessarily a UUID

Hide users attributes Show users attributes object

id string

User id

name string

User name

createdAt string Required

Time the Knowledge Base Entry was created

createdBy string Required

User who created the Knowledge Base Entry

id string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

updatedAt string Required

Time the Knowledge Base Entry was last updated

updatedBy string Required

User who last updated the Knowledge Base Entry

description string Required

Description for when this index or data stream should be queried for Knowledge Base content. Passed to the LLM as a tool description

field string Required

Field to query for Knowledge Base content

index string Required

Index or Data Stream to query for Knowledge Base content

queryDescription string Required

Description of query field used to fetch Knowledge Base content. Passed to the LLM as part of the tool input schema

type string Required Discriminator

Entry type

Value is index.

inputSchema array[object]

Array of objects defining the input schema, allowing the LLM to extract structured data to be used in retrieval

Hide inputSchema attributes Show inputSchema attributes object

description string Required

Description of the field

fieldName string Required

Name of the field

fieldType string Required

Type of the field

outputFields array[string]

Fields to extract from the query result, defaults to all fields if not provided or empty
400 application/json

Generic Error
Hide response attributes Show response attributes object
- error string Required
- message string Required
- statusCode number Required

GET /api/security_ai_assistant/knowledge_base/entries/{id}

curl \
 --request GET 'https://<KIBANA_URL>/api/security_ai_assistant/knowledge_base/entries/{id}' \
 --header "Authorization: $API_KEY"

Update a Knowledge Base Entry

PUT /api/security_ai_assistant/knowledge_base/entries/{id}

Update a Knowledge Base Entry

Path parameters

id string(nonempty) Required

The Knowledge Base Entry's id value

Minimum length is 1.

application/json

Body object Required

global boolean

Whether this Knowledge Base Entry is global, defaults to false
name string Required

Name of the Knowledge Base Entry
namespace string

Kibana Space, defaults to 'default' space
users array[object]

Users who have access to the Knowledge Base Entry, defaults to current user. Empty array provides access to all users.

Could be any string, not necessarily a UUID
Hide users attributes Show users attributes object
- id string
  
  User id
- name string
  
  User name
kbResource string Required

Knowledge Base resource name for grouping entries, e.g. 'security_labs', 'user', etc

Values are security_labs or user.
source string Required

Source document name or filepath
text string Required

Knowledge Base Entry content
type string Required Discriminator

Entry type

Value is document.
required boolean

Whether this resource should always be included, defaults to false
vector object

Object containing Knowledge Base Entry text embeddings and modelId used to create the embeddings
Hide vector attributes Show vector attributes object
- modelId string Required
  
  ID of the model used to create the embeddings
- tokens object Required
  
  Tokens with their corresponding values
  Hide tokens attribute Show tokens attribute object
  
  * number Additional properties

global boolean

Whether this Knowledge Base Entry is global, defaults to false
name string Required

Name of the Knowledge Base Entry
namespace string

Kibana Space, defaults to 'default' space
users array[object]

Users who have access to the Knowledge Base Entry, defaults to current user. Empty array provides access to all users.

Could be any string, not necessarily a UUID
Hide users attributes Show users attributes object
- id string
  
  User id
- name string
  
  User name
description string Required

Description for when this index or data stream should be queried for Knowledge Base content. Passed to the LLM as a tool description
field string Required

Field to query for Knowledge Base content
index string Required

Index or Data Stream to query for Knowledge Base content
queryDescription string Required

Description of query field used to fetch Knowledge Base content. Passed to the LLM as part of the tool input schema
type string Required Discriminator

Entry type

Value is index.
inputSchema array[object]

Array of objects defining the input schema, allowing the LLM to extract structured data to be used in retrieval
Hide inputSchema attributes Show inputSchema attributes object
- description string Required
  
  Description of the field
- fieldName string Required
  
  Name of the field
- fieldType string Required
  
  Type of the field
outputFields array[string]

Fields to extract from the query result, defaults to all fields if not provided or empty

Responses

200 application/json

Successful request returning the updated Knowledge Base Entry
Any of:
Security_AI_Assistant_API_DocumentEntryResponseFields object Security_AI_Assistant_API_IndexEntryResponseFields object
Hide attributes Show attributes

global boolean Required

Whether this Knowledge Base Entry is global, defaults to false

name string Required

Name of the Knowledge Base Entry

namespace string Required

Kibana Space, defaults to 'default' space

users array[object] Required

Users who have access to the Knowledge Base Entry, defaults to current user. Empty array provides access to all users.

Could be any string, not necessarily a UUID

Hide users attributes Show users attributes object

id string

User id

name string

User name

createdAt string Required

Time the Knowledge Base Entry was created

createdBy string Required

User who created the Knowledge Base Entry

id string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

updatedAt string Required

Time the Knowledge Base Entry was last updated

updatedBy string Required

User who last updated the Knowledge Base Entry

kbResource string Required

Knowledge Base resource name for grouping entries, e.g. 'security_labs', 'user', etc

Values are security_labs or user.

source string Required

Source document name or filepath

text string Required

Knowledge Base Entry content

type string Required Discriminator

Entry type

Value is document.

required boolean

Whether this resource should always be included, defaults to false

vector object

Object containing Knowledge Base Entry text embeddings and modelId used to create the embeddings

Hide vector attributes Show vector attributes object

modelId string Required

ID of the model used to create the embeddings

tokens object Required

Tokens with their corresponding values

Hide tokens attribute Show tokens attribute object

* number Additional properties
Hide attributes Show attributes

global boolean Required

Whether this Knowledge Base Entry is global, defaults to false

name string Required

Name of the Knowledge Base Entry

namespace string Required

Kibana Space, defaults to 'default' space

users array[object] Required

Users who have access to the Knowledge Base Entry, defaults to current user. Empty array provides access to all users.

Could be any string, not necessarily a UUID

Hide users attributes Show users attributes object

id string

User id

name string

User name

createdAt string Required

Time the Knowledge Base Entry was created

createdBy string Required

User who created the Knowledge Base Entry

id string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

updatedAt string Required

Time the Knowledge Base Entry was last updated

updatedBy string Required

User who last updated the Knowledge Base Entry

description string Required

Description for when this index or data stream should be queried for Knowledge Base content. Passed to the LLM as a tool description

field string Required

Field to query for Knowledge Base content

index string Required

Index or Data Stream to query for Knowledge Base content

queryDescription string Required

Description of query field used to fetch Knowledge Base content. Passed to the LLM as part of the tool input schema

type string Required Discriminator

Entry type

Value is index.

inputSchema array[object]

Array of objects defining the input schema, allowing the LLM to extract structured data to be used in retrieval

Hide inputSchema attributes Show inputSchema attributes object

description string Required

Description of the field

fieldName string Required

Name of the field

fieldType string Required

Type of the field

outputFields array[string]

Fields to extract from the query result, defaults to all fields if not provided or empty
400 application/json

Generic Error
Hide response attributes Show response attributes object
- error string Required
- message string Required
- statusCode number Required

PUT /api/security_ai_assistant/knowledge_base/entries/{id}

curl \
 --request PUT 'https://<KIBANA_URL>/api/security_ai_assistant/knowledge_base/entries/{id}' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"global":true,"name":"string","namespace":"string","users":[{"id":"string","name":"string"}],"kbResource":"security_labs","source":"string","text":"string","type":"document","required":true,"vector":{"modelId":"string","tokens":{"additionalProperty1":42.0,"additionalProperty2":42.0}}}'

Deletes a single Knowledge Base Entry using the `id` field

DELETE /api/security_ai_assistant/knowledge_base/entries/{id}

Deletes a single Knowledge Base Entry using the id field

Path parameters

id string(nonempty) Required

The Knowledge Base Entry's id value

Minimum length is 1.

Responses

200 application/json

Successful request returning the deleted Knowledge Base Entry's ID
Hide response attribute Show response attribute object
- id string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
400 application/json

Generic Error
Hide response attributes Show response attributes object
- error string Required
- message string Required
- statusCode number Required

DELETE /api/security_ai_assistant/knowledge_base/entries/{id}

curl \
 --request DELETE 'https://<KIBANA_URL>/api/security_ai_assistant/knowledge_base/entries/{id}' \
 --header "Authorization: $API_KEY"

Apply a bulk action to prompts

POST /api/security_ai_assistant/prompts/_bulk_action

Apply a bulk action to multiple prompts. The bulk action is applied to all prompts that match the filter or to the list of prompts by their IDs.

application/json

Body

create array[object]
Hide create attributes Show create attributes object
- categories array[string]
- color string
- consumer string
- content string Required
- isDefault boolean
- isNewConversationDefault boolean
- name string Required
- promptType string Required
  
  Prompt type
  
  Values are system or quick.
delete object
Hide delete attributes Show delete attributes object
- ids array[string]
  
  Array of prompts IDs
  
  At least 1 element.
- query string
  
  Query to filter promps
update array[object]
Hide update attributes Show update attributes object
- categories array[string]
- color string
- consumer string
- content string
- id string Required
- isDefault boolean
- isNewConversationDefault boolean

Responses

200 application/json

Indicates a successful call.
Hide response attributes Show response attributes object
- attributes object Required
  
  Hide attributes attributes Show attributes attributes object
  
  errors array[object]
  
  Hide errors attributes Show errors attributes object
  
  err_code string
  
  message string Required
  
  prompts array[object] Required
  
  Hide prompts attributes Show prompts attributes object
  
  id string Required
  
  name string
  
  status_code integer Required
  
  results object Required
  
  Hide results attributes Show results attributes object
  
  created array[object] Required
  
  Hide created attributes Show created attributes object
  
  categories array[string]
  
  color string
  
  consumer string
  
  content string Required
  
  createdAt string
  
  createdBy string
  
  id string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  isDefault boolean
  
  isNewConversationDefault boolean
  
  name string Required
  
  namespace string
  
  Kibana space
  
  promptType string Required
  
  Prompt type
  
  Values are system or quick.
  
  timestamp string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  updatedAt string
  
  updatedBy string
  
  users array[object]
  
  Could be any string, not necessarily a UUID
  
  Hide users attributes Show users attributes object
  
  id string
  
  User id
  
  name string
  
  User name
  
  deleted array[string] Required
  
  skipped array[object] Required
  
  Hide skipped attributes Show skipped attributes object
  
  id string Required
  
  name string
  
  skip_reason string Required
  
  Value is PROMPT_FIELD_NOT_MODIFIED.
  
  updated array[object] Required
  
  Hide updated attributes Show updated attributes object
  
  categories array[string]
  
  color string
  
  consumer string
  
  content string Required
  
  createdAt string
  
  createdBy string
  
  id string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  isDefault boolean
  
  isNewConversationDefault boolean
  
  name string Required
  
  namespace string
  
  Kibana space
  
  promptType string Required
  
  Prompt type
  
  Values are system or quick.
  
  timestamp string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  updatedAt string
  
  updatedBy string
  
  users array[object]
  
  Could be any string, not necessarily a UUID
  
  Hide users attributes Show users attributes object
  
  id string
  
  User id
  
  name string
  
  User name
  
  summary object Required
  
  Hide summary attributes Show summary attributes object
  
  failed integer Required
  
  skipped integer Required
  
  succeeded integer Required
  
  total integer Required
- message string
- prompts_count integer
- status_code integer
- success boolean
400 application/json

Generic Error
Hide response attributes Show response attributes object
- error string
- message string
- statusCode number

POST /api/security_ai_assistant/prompts/_bulk_action

curl \
 --request POST 'https://<KIBANA_URL>/api/security_ai_assistant/prompts/_bulk_action' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"create":[{"categories":["string"],"color":"string","consumer":"string","content":"string","isDefault":true,"isNewConversationDefault":true,"name":"string","promptType":"system"}],"delete":{"ids":["string"],"query":"string"},"update":[{"categories":["string"],"color":"string","consumer":"string","content":"string","id":"string","isDefault":true,"isNewConversationDefault":true}]}'

Get prompts

GET /api/security_ai_assistant/prompts/_find

Get a list of all prompts.

Query parameters

fields array[string]
filter string

Search query
sort_field string

Field to sort by

Values are created_at, is_default, name, or updated_at.
sort_order string

Sort order

Values are asc or desc.
page integer

Page number

Minimum value is 1. Default value is 1.
per_page integer

Prompts per page

Minimum value is 0. Default value is 20.

Responses

200 application/json

Successful response
Hide response attributes Show response attributes object
- data array[object] Required
  
  Hide data attributes Show data attributes object
  
  categories array[string]
  
  color string
  
  consumer string
  
  content string Required
  
  createdAt string
  
  createdBy string
  
  id string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  isDefault boolean
  
  isNewConversationDefault boolean
  
  name string Required
  
  namespace string
  
  Kibana space
  
  promptType string Required
  
  Prompt type
  
  Values are system or quick.
  
  timestamp string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  updatedAt string
  
  updatedBy string
  
  users array[object]
  
  Could be any string, not necessarily a UUID
  
  Hide users attributes Show users attributes object
  
  id string
  
  User id
  
  name string
  
  User name
- page integer Required
- perPage integer Required
- total integer Required
400 application/json

Generic Error
Hide response attributes Show response attributes object
- error string
- message string
- statusCode number

GET /api/security_ai_assistant/prompts/_find

curl \
 --request GET 'https://<KIBANA_URL>/api/security_ai_assistant/prompts/_find' \
 --header "Authorization: $API_KEY"

Security detections

Use the detections APIs to create and manage detection rules. Detection rules search events and external alerts sent to Elastic Security and generate detection alerts from any hits. Alerts are displayed on the Alerts page and can be assigned and triaged, using the alert status to mark them as open, closed, or acknowledged.

This API supports both key-based authentication and basic authentication.

To use key-based authentication, create an API key, then specify the key in the header of your API calls.

To use basic authentication, provide a username and password; this automatically creates an API key that matches the current user’s privileges.

In both cases, the API key is subsequently used for authorization when the rule runs.

If the API key used for authorization has different privileges than the key that created or most recently updated a rule, the rule behavior might change.

If the API key that created a rule is deleted, or the user that created the rule becomes inactive, the rule will stop running.

To create and run rules, the user must meet specific requirements for the Kibana space. Refer to the Detections requirements for a complete list of requirements.

Returns user privileges for the Kibana space

GET /api/detection_engine/privileges

Retrieves whether or not the user is authenticated, and the user's Kibana space and index privileges, which determine if the user can create an index for the Elastic Security alerts generated by detection engine rules.

Responses

200 application/json

Successful response
Hide response attributes Show response attributes object
- has_encryption_key boolean Required
- is_authenticated boolean Required
401 application/json

Unsuccessful authentication response
Hide response attributes Show response attributes object
- error string Required
- message string Required
- statusCode integer Required
500 application/json

Internal server error response
Hide response attributes Show response attributes object
- message string Required
- status_code integer Required

GET /api/detection_engine/privileges

curl \
 --request GET 'https://<KIBANA_URL>/api/detection_engine/privileges' \
 --header "Authorization: $API_KEY"

Response examples (200)

{
  "index": {
    ".alerts-security.alerts-default": {
      "all": true,
      "read": true,
      "index": true,
      "write": true,
      "create": true,
      "delete": true,
      "manage": true,
      "monitor": true,
      "create_doc": true,
      "maintenance": true,
      "create_index": true,
      "delete_index": true,
      "view_index_metadata": true
    }
  },
  "cluster": {
    "all": true,
    "manage": true,
    "monitor": true,
    "manage_ml": true,
    "monitor_ml": true,
    "manage_api_key": true,
    "manage_pipeline": true,
    "manage_security": true,
    "manage_transform": true,
    "monitor_transform": true,
    "manage_own_api_key": true,
    "manage_index_templates": true
  },
  "username": "elastic",
  "application": {},
  "is_authenticated": true,
  "has_all_requested": true,
  "has_encryption_key": true
}

Retrieve a detection rule

GET /api/detection_engine/rules

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.

Query parameters

id string(uuid)

The rule's id value.
rule_id string

The rule's rule_id value.

Responses

200 application/json

Indicates a successful call.

These fields are under development and their usage or schema may change: execution_summary.
Any of:
Security_Detections_API_EqlRuleResponseFields object Security_Detections_API_QueryRuleResponseFields object Security_Detections_API_SavedQueryRuleResponseFields object Security_Detections_API_ThresholdRuleResponseFields object Security_Detections_API_ThreatMatchRuleResponseFields object Security_Detections_API_MachineLearningRuleResponseFields object Security_Detections_API_NewTermsRuleResponseFields object Security_Detections_API_EsqlRuleResponseFields object
Hide attributes Show attributes

actions array[object] Required

Array defining the automated actions (notifications) taken when alerts are generated.

Hide actions attributes Show actions attributes object

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.

Additional properties are allowed.

frequency object

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

Hide frequency attributes Show frequency attributes object

notifyWhen string Required

Defines how often rules run actions.

Values are onActiveAlert, onThrottleInterval, or 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 string | null Required

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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.

Additional properties are allowed.

uuid string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

alias_purpose string

Values are savedObjectConversion or savedObjectImport.

alias_target_id string

author array[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 Required

The rule’s description.

Minimum length is 1.

enabled boolean Required

Determines whether the rule is enabled. Defaults to true.

exceptions_list array[object] Required

Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.

Hide exceptions_list attributes Show exceptions_list attributes object

id string(nonempty) Required

ID of the exception container

Minimum length is 1.

list_id string(nonempty) Required

List ID of the exception container

Minimum length is 1.

namespace_type string Required

Determines the exceptions validity in rule's Kibana space

Values are agnostic or single.

type string Required

The exception type

Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.

false_positives array[string] Required

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.

from string(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.

Hide investigation_fields attribute Show investigation_fields attribute object

field_names array[string(nonempty)] Required

A string that does not contain only whitespace characters

At least 1 element. Minimum length of each is 1.

license string

The rule's license.

max_signals integer Required

Maximum number of alerts the rule can create during a single run (the rule’s Max alerts per run advanced setting value).

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.

Minimum value is 1. Default value is 100.

meta object

Placeholder for metadata about the rule.

This field is overwritten when you save changes to the rule’s settings.

Additional properties are allowed.

name string Required

A human-readable name for the rule.

Minimum length is 1.

namespace string

Has no effect.

note string

Notes to help investigate alerts produced by the rule.

outcome string

Values are exactMatch, aliasMatch, or conflict.

output_index string Deprecated

(deprecated) Has no effect.

references array[string] Required

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.

related_integrations array[object] Required

Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:

package: name of the package (required, unique id)

version: version of the package (required, semver-compatible)

integration: name of the integration of this package (optional, id within the package)

There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.

Hide related_integrations attributes Show related_integrations attributes object

integration string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

package string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

version string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

required_fields array[object] Required

Elasticsearch fields and their types that need to be present for the rule to function.

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.

Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.

Hide required_fields attributes Show required_fields attributes object

name string(nonempty) Required

Name of an Elasticsearch field

Minimum length is 1.

type string(nonempty) Required

Type of the Elasticsearch field

Minimum length is 1.

response_actions array[object]

One of:
Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object

Hide attributes Show attributes

action_type_id string Required

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

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

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[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.

Hide attributes Show attributes

action_type_id string Required

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object

Hide attributes Show attributes

command string Required

Value is isolate.

comment string

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.

risk_score integer 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

Minimum value is 0, maximum value is 100.

risk_score_mapping array[object] Required

Overrides generated alerts' risk_score with a value from the source event

Hide risk_score_mapping attributes Show risk_score_mapping attributes object

field string Required

Source event field used to override the default risk_score.

operator string Required

Value is equals.

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

Minimum value is 0, maximum value is 100.

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 string 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 are low, medium, high, or critical.

severity_mapping array[object] Required

Overrides generated alerts' severity with values from the source event

Hide severity_mapping attributes Show severity_mapping attributes object

field string Required

Source event field used to override the default severity.

operator string Required

Value is equals.

severity string 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 are low, medium, high, or critical.

value string Required

tags array[string] Required

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.

threat array[object] Required

Currently, only threats described using the MITRE ATT&CK™ framework are supported.

Hide threat attributes Show threat attributes object

framework string Required

Relevant attack framework

tactic object Required

Object containing information on the attack type

Hide tactic attributes Show tactic attributes object

id string Required

Tactic ID

name string Required

Tactic name

reference string Required

Tactic reference

technique array[object]

Array containing information on the attack techniques (optional)

Hide technique attributes Show technique attributes object

id string Required

Technique ID

name string Required

Technique name

reference string Required

Technique reference

subtechnique array[object]

Array containing more specific information on the attack technique.

Hide subtechnique attributes Show subtechnique attributes object

id string Required

Subtechnique ID

name string Required

Subtechnique name

reference string Required

Subtechnique reference

throttle string | null

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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 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.

It is not incremented on each update. Compare this to the revision field.

Minimum value is 1.

created_at string(date-time) Required

created_by string Required

execution_summary object

Summary of the last execution of a rule.

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

Hide execution_summary attribute Show execution_summary attribute object

last_execution object Required

Hide last_execution attributes Show last_execution attributes object

date string(date-time) Required

Date of the last execution

message string Required

metrics object Required

Hide metrics attributes Show metrics attributes object

execution_gap_duration_s integer

Duration in seconds of execution gap

Minimum value is 0.

frozen_indices_queried_count integer

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

Minimum value is 0.

gap_range object

Range of the execution gap

Hide gap_range attributes Show gap_range attributes object

gte string Required

Start date of the execution gap

lte string Required

End date of the execution gap

total_enrichment_duration_ms integer

Total time spent enriching documents during current rule execution cycle

Minimum value is 0.

total_indexing_duration_ms integer

Total time spent indexing documents during current rule execution cycle

Minimum value is 0.

total_search_duration_ms integer

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

Minimum value is 0.

status string Required

Status of the last execution

Values are going to run, running, partial failure, failed, or succeeded.

status_order integer Required

id string(uuid) Required

A dynamic unique identifier for the rule object. It is randomly generated when a rule is created and cannot be changed after that. It is always a UUID. It is unique within a given Kibana space. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have different object ids.

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

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.

Minimum value is 0.

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 object 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:
Security_Detections_API_ExternalRuleSource object Security_Detections_API_InternalRuleSource object

Type of rule source for externally sourced rules, i.e. rules that have an external source, such as the Elastic Prebuilt rules repo.

Hide attributes Show attributes

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

type string Required Discriminator

Value is external.

updated_at string(date-time) Required

updated_by string Required

language string Required

Query language to use

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

type string Required Discriminator

Rule type

Value is eql.

alert_suppression object

Defines alert suppression configuration.

Hide alert_suppression attributes Show alert_suppression attributes object

duration object

Hide duration attributes Show duration attributes object

unit string Required

Time unit

Values are s, m, or h.

value integer Required

Minimum value is 1.

group_by array[string] Required

At least 1 but not more than 3 elements.

missing_fields_strategy string

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 are doNotSuppress or suppress.

data_view_id string

event_category_override string

filters array

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

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.
Hide attributes Show attributes

actions array[object] Required

Array defining the automated actions (notifications) taken when alerts are generated.

Hide actions attributes Show actions attributes object

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.

Additional properties are allowed.

frequency object

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

Hide frequency attributes Show frequency attributes object

notifyWhen string Required

Defines how often rules run actions.

Values are onActiveAlert, onThrottleInterval, or 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 string | null Required

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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.

Additional properties are allowed.

uuid string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

alias_purpose string

Values are savedObjectConversion or savedObjectImport.

alias_target_id string

author array[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 Required

The rule’s description.

Minimum length is 1.

enabled boolean Required

Determines whether the rule is enabled. Defaults to true.

exceptions_list array[object] Required

Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.

Hide exceptions_list attributes Show exceptions_list attributes object

id string(nonempty) Required

ID of the exception container

Minimum length is 1.

list_id string(nonempty) Required

List ID of the exception container

Minimum length is 1.

namespace_type string Required

Determines the exceptions validity in rule's Kibana space

Values are agnostic or single.

type string Required

The exception type

Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.

false_positives array[string] Required

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.

from string(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.

Hide investigation_fields attribute Show investigation_fields attribute object

field_names array[string(nonempty)] Required

A string that does not contain only whitespace characters

At least 1 element. Minimum length of each is 1.

license string

The rule's license.

max_signals integer Required

Maximum number of alerts the rule can create during a single run (the rule’s Max alerts per run advanced setting value).

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.

Minimum value is 1. Default value is 100.

meta object

Placeholder for metadata about the rule.

This field is overwritten when you save changes to the rule’s settings.

Additional properties are allowed.

name string Required

A human-readable name for the rule.

Minimum length is 1.

namespace string

Has no effect.

note string

Notes to help investigate alerts produced by the rule.

outcome string

Values are exactMatch, aliasMatch, or conflict.

output_index string Deprecated

(deprecated) Has no effect.

references array[string] Required

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.

related_integrations array[object] Required

Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:

package: name of the package (required, unique id)

version: version of the package (required, semver-compatible)

integration: name of the integration of this package (optional, id within the package)

There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.

Hide related_integrations attributes Show related_integrations attributes object

integration string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

package string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

version string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

required_fields array[object] Required

Elasticsearch fields and their types that need to be present for the rule to function.

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.

Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.

Hide required_fields attributes Show required_fields attributes object

name string(nonempty) Required

Name of an Elasticsearch field

Minimum length is 1.

type string(nonempty) Required

Type of the Elasticsearch field

Minimum length is 1.

response_actions array[object]

One of:
Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object

Hide attributes Show attributes

action_type_id string Required

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

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

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[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.

Hide attributes Show attributes

action_type_id string Required

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object

Hide attributes Show attributes

command string Required

Value is isolate.

comment string

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.

risk_score integer 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

Minimum value is 0, maximum value is 100.

risk_score_mapping array[object] Required

Overrides generated alerts' risk_score with a value from the source event

Hide risk_score_mapping attributes Show risk_score_mapping attributes object

field string Required

Source event field used to override the default risk_score.

operator string Required

Value is equals.

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

Minimum value is 0, maximum value is 100.

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 string 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 are low, medium, high, or critical.

severity_mapping array[object] Required

Overrides generated alerts' severity with values from the source event

Hide severity_mapping attributes Show severity_mapping attributes object

field string Required

Source event field used to override the default severity.

operator string Required

Value is equals.

severity string 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 are low, medium, high, or critical.

value string Required

tags array[string] Required

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.

threat array[object] Required

Currently, only threats described using the MITRE ATT&CK™ framework are supported.

Hide threat attributes Show threat attributes object

framework string Required

Relevant attack framework

tactic object Required

Object containing information on the attack type

Hide tactic attributes Show tactic attributes object

id string Required

Tactic ID

name string Required

Tactic name

reference string Required

Tactic reference

technique array[object]

Array containing information on the attack techniques (optional)

Hide technique attributes Show technique attributes object

id string Required

Technique ID

name string Required

Technique name

reference string Required

Technique reference

subtechnique array[object]

Array containing more specific information on the attack technique.

Hide subtechnique attributes Show subtechnique attributes object

id string Required

Subtechnique ID

name string Required

Subtechnique name

reference string Required

Subtechnique reference

throttle string | null

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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 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.

It is not incremented on each update. Compare this to the revision field.

Minimum value is 1.

created_at string(date-time) Required

created_by string Required

execution_summary object

Summary of the last execution of a rule.

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

Hide execution_summary attribute Show execution_summary attribute object

last_execution object Required

Hide last_execution attributes Show last_execution attributes object

date string(date-time) Required

Date of the last execution

message string Required

metrics object Required

Hide metrics attributes Show metrics attributes object

execution_gap_duration_s integer

Duration in seconds of execution gap

Minimum value is 0.

frozen_indices_queried_count integer

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

Minimum value is 0.

gap_range object

Range of the execution gap

Hide gap_range attributes Show gap_range attributes object

gte string Required

Start date of the execution gap

lte string Required

End date of the execution gap

total_enrichment_duration_ms integer

Total time spent enriching documents during current rule execution cycle

Minimum value is 0.

total_indexing_duration_ms integer

Total time spent indexing documents during current rule execution cycle

Minimum value is 0.

total_search_duration_ms integer

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

Minimum value is 0.

status string Required

Status of the last execution

Values are going to run, running, partial failure, failed, or succeeded.

status_order integer Required

id string(uuid) Required

A dynamic unique identifier for the rule object. It is randomly generated when a rule is created and cannot be changed after that. It is always a UUID. It is unique within a given Kibana space. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have different object ids.

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

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.

Minimum value is 0.

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 object 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:
Security_Detections_API_ExternalRuleSource object Security_Detections_API_InternalRuleSource object

Type of rule source for externally sourced rules, i.e. rules that have an external source, such as the Elastic Prebuilt rules repo.

Hide attributes Show attributes

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

type string Required Discriminator

Value is external.

updated_at string(date-time) Required

updated_by string Required

type string Required Discriminator

Rule type

Value is query.

alert_suppression object

Defines alert suppression configuration.

Hide alert_suppression attributes Show alert_suppression attributes object

duration object

Hide duration attributes Show duration attributes object

unit string Required

Time unit

Values are s, m, or h.

value integer Required

Minimum value is 1.

group_by array[string] Required

At least 1 but not more than 3 elements.

missing_fields_strategy string

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 are doNotSuppress or suppress.

data_view_id string

filters array

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

saved_id string

Kibana saved search used by the rule to create alerts.

language string Required

Values are kuery or lucene.

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.
Hide attributes Show attributes

actions array[object] Required

Array defining the automated actions (notifications) taken when alerts are generated.

Hide actions attributes Show actions attributes object

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.

Additional properties are allowed.

frequency object

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

Hide frequency attributes Show frequency attributes object

notifyWhen string Required

Defines how often rules run actions.

Values are onActiveAlert, onThrottleInterval, or 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 string | null Required

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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.

Additional properties are allowed.

uuid string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

alias_purpose string

Values are savedObjectConversion or savedObjectImport.

alias_target_id string

author array[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 Required

The rule’s description.

Minimum length is 1.

enabled boolean Required

Determines whether the rule is enabled. Defaults to true.

exceptions_list array[object] Required

Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.

Hide exceptions_list attributes Show exceptions_list attributes object

id string(nonempty) Required

ID of the exception container

Minimum length is 1.

list_id string(nonempty) Required

List ID of the exception container

Minimum length is 1.

namespace_type string Required

Determines the exceptions validity in rule's Kibana space

Values are agnostic or single.

type string Required

The exception type

Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.

false_positives array[string] Required

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.

from string(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.

Hide investigation_fields attribute Show investigation_fields attribute object

field_names array[string(nonempty)] Required

A string that does not contain only whitespace characters

At least 1 element. Minimum length of each is 1.

license string

The rule's license.

max_signals integer Required

Maximum number of alerts the rule can create during a single run (the rule’s Max alerts per run advanced setting value).

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.

Minimum value is 1. Default value is 100.

meta object

Placeholder for metadata about the rule.

This field is overwritten when you save changes to the rule’s settings.

Additional properties are allowed.

name string Required

A human-readable name for the rule.

Minimum length is 1.

namespace string

Has no effect.

note string

Notes to help investigate alerts produced by the rule.

outcome string

Values are exactMatch, aliasMatch, or conflict.

output_index string Deprecated

(deprecated) Has no effect.

references array[string] Required

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.

related_integrations array[object] Required

Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:

package: name of the package (required, unique id)

version: version of the package (required, semver-compatible)

integration: name of the integration of this package (optional, id within the package)

There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.

Hide related_integrations attributes Show related_integrations attributes object

integration string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

package string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

version string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

required_fields array[object] Required

Elasticsearch fields and their types that need to be present for the rule to function.

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.

Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.

Hide required_fields attributes Show required_fields attributes object

name string(nonempty) Required

Name of an Elasticsearch field

Minimum length is 1.

type string(nonempty) Required

Type of the Elasticsearch field

Minimum length is 1.

response_actions array[object]

One of:
Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object

Hide attributes Show attributes

action_type_id string Required

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

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

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[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.

Hide attributes Show attributes

action_type_id string Required

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object

Hide attributes Show attributes

command string Required

Value is isolate.

comment string

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.

risk_score integer 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

Minimum value is 0, maximum value is 100.

risk_score_mapping array[object] Required

Overrides generated alerts' risk_score with a value from the source event

Hide risk_score_mapping attributes Show risk_score_mapping attributes object

field string Required

Source event field used to override the default risk_score.

operator string Required

Value is equals.

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

Minimum value is 0, maximum value is 100.

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 string 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 are low, medium, high, or critical.

severity_mapping array[object] Required

Overrides generated alerts' severity with values from the source event

Hide severity_mapping attributes Show severity_mapping attributes object

field string Required

Source event field used to override the default severity.

operator string Required

Value is equals.

severity string 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 are low, medium, high, or critical.

value string Required

tags array[string] Required

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.

threat array[object] Required

Currently, only threats described using the MITRE ATT&CK™ framework are supported.

Hide threat attributes Show threat attributes object

framework string Required

Relevant attack framework

tactic object Required

Object containing information on the attack type

Hide tactic attributes Show tactic attributes object

id string Required

Tactic ID

name string Required

Tactic name

reference string Required

Tactic reference

technique array[object]

Array containing information on the attack techniques (optional)

Hide technique attributes Show technique attributes object

id string Required

Technique ID

name string Required

Technique name

reference string Required

Technique reference

subtechnique array[object]

Array containing more specific information on the attack technique.

Hide subtechnique attributes Show subtechnique attributes object

id string Required

Subtechnique ID

name string Required

Subtechnique name

reference string Required

Subtechnique reference

throttle string | null

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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 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.

It is not incremented on each update. Compare this to the revision field.

Minimum value is 1.

created_at string(date-time) Required

created_by string Required

execution_summary object

Summary of the last execution of a rule.

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

Hide execution_summary attribute Show execution_summary attribute object

last_execution object Required

Hide last_execution attributes Show last_execution attributes object

date string(date-time) Required

Date of the last execution

message string Required

metrics object Required

Hide metrics attributes Show metrics attributes object

execution_gap_duration_s integer

Duration in seconds of execution gap

Minimum value is 0.

frozen_indices_queried_count integer

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

Minimum value is 0.

gap_range object

Range of the execution gap

Hide gap_range attributes Show gap_range attributes object

gte string Required

Start date of the execution gap

lte string Required

End date of the execution gap

total_enrichment_duration_ms integer

Total time spent enriching documents during current rule execution cycle

Minimum value is 0.

total_indexing_duration_ms integer

Total time spent indexing documents during current rule execution cycle

Minimum value is 0.

total_search_duration_ms integer

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

Minimum value is 0.

status string Required

Status of the last execution

Values are going to run, running, partial failure, failed, or succeeded.

status_order integer Required

id string(uuid) Required

A dynamic unique identifier for the rule object. It is randomly generated when a rule is created and cannot be changed after that. It is always a UUID. It is unique within a given Kibana space. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have different object ids.

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

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.

Minimum value is 0.

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 object 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:
Security_Detections_API_ExternalRuleSource object Security_Detections_API_InternalRuleSource object

Type of rule source for externally sourced rules, i.e. rules that have an external source, such as the Elastic Prebuilt rules repo.

Hide attributes Show attributes

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

type string Required Discriminator

Value is external.

updated_at string(date-time) Required

updated_by string Required

saved_id string Required

Kibana saved search used by the rule to create alerts.

type string Required Discriminator

Rule type

Value is saved_query.

alert_suppression object

Defines alert suppression configuration.

Hide alert_suppression attributes Show alert_suppression attributes object

duration object

Hide duration attributes Show duration attributes object

unit string Required

Time unit

Values are s, m, or h.

value integer Required

Minimum value is 1.

group_by array[string] Required

At least 1 but not more than 3 elements.

missing_fields_strategy string

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 are doNotSuppress or suppress.

data_view_id string

filters array

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

query string

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.

language string Required

Values are kuery or lucene.
Hide attributes Show attributes

actions array[object] Required

Array defining the automated actions (notifications) taken when alerts are generated.

Hide actions attributes Show actions attributes object

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.

Additional properties are allowed.

frequency object

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

Hide frequency attributes Show frequency attributes object

notifyWhen string Required

Defines how often rules run actions.

Values are onActiveAlert, onThrottleInterval, or 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 string | null Required

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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.

Additional properties are allowed.

uuid string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

alias_purpose string

Values are savedObjectConversion or savedObjectImport.

alias_target_id string

author array[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 Required

The rule’s description.

Minimum length is 1.

enabled boolean Required

Determines whether the rule is enabled. Defaults to true.

exceptions_list array[object] Required

Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.

Hide exceptions_list attributes Show exceptions_list attributes object

id string(nonempty) Required

ID of the exception container

Minimum length is 1.

list_id string(nonempty) Required

List ID of the exception container

Minimum length is 1.

namespace_type string Required

Determines the exceptions validity in rule's Kibana space

Values are agnostic or single.

type string Required

The exception type

Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.

false_positives array[string] Required

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.

from string(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.

Hide investigation_fields attribute Show investigation_fields attribute object

field_names array[string(nonempty)] Required

A string that does not contain only whitespace characters

At least 1 element. Minimum length of each is 1.

license string

The rule's license.

max_signals integer Required

Maximum number of alerts the rule can create during a single run (the rule’s Max alerts per run advanced setting value).

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.

Minimum value is 1. Default value is 100.

meta object

Placeholder for metadata about the rule.

This field is overwritten when you save changes to the rule’s settings.

Additional properties are allowed.

name string Required

A human-readable name for the rule.

Minimum length is 1.

namespace string

Has no effect.

note string

Notes to help investigate alerts produced by the rule.

outcome string

Values are exactMatch, aliasMatch, or conflict.

output_index string Deprecated

(deprecated) Has no effect.

references array[string] Required

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.

related_integrations array[object] Required

Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:

package: name of the package (required, unique id)

version: version of the package (required, semver-compatible)

integration: name of the integration of this package (optional, id within the package)

There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.

Hide related_integrations attributes Show related_integrations attributes object

integration string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

package string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

version string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

required_fields array[object] Required

Elasticsearch fields and their types that need to be present for the rule to function.

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.

Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.

Hide required_fields attributes Show required_fields attributes object

name string(nonempty) Required

Name of an Elasticsearch field

Minimum length is 1.

type string(nonempty) Required

Type of the Elasticsearch field

Minimum length is 1.

response_actions array[object]

One of:
Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object

Hide attributes Show attributes

action_type_id string Required

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

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

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[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.

Hide attributes Show attributes

action_type_id string Required

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object

Hide attributes Show attributes

command string Required

Value is isolate.

comment string

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.

risk_score integer 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

Minimum value is 0, maximum value is 100.

risk_score_mapping array[object] Required

Overrides generated alerts' risk_score with a value from the source event

Hide risk_score_mapping attributes Show risk_score_mapping attributes object

field string Required

Source event field used to override the default risk_score.

operator string Required

Value is equals.

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

Minimum value is 0, maximum value is 100.

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 string 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 are low, medium, high, or critical.

severity_mapping array[object] Required

Overrides generated alerts' severity with values from the source event

Hide severity_mapping attributes Show severity_mapping attributes object

field string Required

Source event field used to override the default severity.

operator string Required

Value is equals.

severity string 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 are low, medium, high, or critical.

value string Required

tags array[string] Required

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.

threat array[object] Required

Currently, only threats described using the MITRE ATT&CK™ framework are supported.

Hide threat attributes Show threat attributes object

framework string Required

Relevant attack framework

tactic object Required

Object containing information on the attack type

Hide tactic attributes Show tactic attributes object

id string Required

Tactic ID

name string Required

Tactic name

reference string Required

Tactic reference

technique array[object]

Array containing information on the attack techniques (optional)

Hide technique attributes Show technique attributes object

id string Required

Technique ID

name string Required

Technique name

reference string Required

Technique reference

subtechnique array[object]

Array containing more specific information on the attack technique.

Hide subtechnique attributes Show subtechnique attributes object

id string Required

Subtechnique ID

name string Required

Subtechnique name

reference string Required

Subtechnique reference

throttle string | null

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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 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.

It is not incremented on each update. Compare this to the revision field.

Minimum value is 1.

created_at string(date-time) Required

created_by string Required

execution_summary object

Summary of the last execution of a rule.

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

Hide execution_summary attribute Show execution_summary attribute object

last_execution object Required

Hide last_execution attributes Show last_execution attributes object

date string(date-time) Required

Date of the last execution

message string Required

metrics object Required

Hide metrics attributes Show metrics attributes object

execution_gap_duration_s integer

Duration in seconds of execution gap

Minimum value is 0.

frozen_indices_queried_count integer

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

Minimum value is 0.

gap_range object

Range of the execution gap

Hide gap_range attributes Show gap_range attributes object

gte string Required

Start date of the execution gap

lte string Required

End date of the execution gap

total_enrichment_duration_ms integer

Total time spent enriching documents during current rule execution cycle

Minimum value is 0.

total_indexing_duration_ms integer

Total time spent indexing documents during current rule execution cycle

Minimum value is 0.

total_search_duration_ms integer

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

Minimum value is 0.

status string Required

Status of the last execution

Values are going to run, running, partial failure, failed, or succeeded.

status_order integer Required

id string(uuid) Required

A dynamic unique identifier for the rule object. It is randomly generated when a rule is created and cannot be changed after that. It is always a UUID. It is unique within a given Kibana space. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have different object ids.

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

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.

Minimum value is 0.

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 object 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:
Security_Detections_API_ExternalRuleSource object Security_Detections_API_InternalRuleSource object

Type of rule source for externally sourced rules, i.e. rules that have an external source, such as the Elastic Prebuilt rules repo.

Hide attributes Show attributes

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

type string Required Discriminator

Value is external.

updated_at string(date-time) Required

updated_by string Required

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.

threshold object Required

Hide threshold attributes Show threshold attributes object

cardinality array[object]

The field on which the cardinality is applied.

Hide cardinality attributes Show cardinality attributes object

field string Required

The field on which to calculate and compare the cardinality.

value integer Required

The threshold value from which an alert is generated based on unique number of values of cardinality.field.

Minimum value is 0.

field string | array[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.

One of:
string-1 string array-2 array[string]

value integer Required

The threshold value from which an alert is generated.

Minimum value is 1.

type string Required Discriminator

Rule type

Value is threshold.

alert_suppression object

Defines alert suppression configuration.

Hide alert_suppression attribute Show alert_suppression attribute object

duration object Required

Hide duration attributes Show duration attributes object

unit string Required

Time unit

Values are s, m, or h.

value integer Required

Minimum value is 1.

data_view_id string

filters array

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

saved_id string

Kibana saved search used by the rule to create alerts.

language string Required

Values are kuery or lucene.
Hide attributes Show attributes

actions array[object] Required

Array defining the automated actions (notifications) taken when alerts are generated.

Hide actions attributes Show actions attributes object

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.

Additional properties are allowed.

frequency object

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

Hide frequency attributes Show frequency attributes object

notifyWhen string Required

Defines how often rules run actions.

Values are onActiveAlert, onThrottleInterval, or 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 string | null Required

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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.

Additional properties are allowed.

uuid string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

alias_purpose string

Values are savedObjectConversion or savedObjectImport.

alias_target_id string

author array[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 Required

The rule’s description.

Minimum length is 1.

enabled boolean Required

Determines whether the rule is enabled. Defaults to true.

exceptions_list array[object] Required

Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.

Hide exceptions_list attributes Show exceptions_list attributes object

id string(nonempty) Required

ID of the exception container

Minimum length is 1.

list_id string(nonempty) Required

List ID of the exception container

Minimum length is 1.

namespace_type string Required

Determines the exceptions validity in rule's Kibana space

Values are agnostic or single.

type string Required

The exception type

Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.

false_positives array[string] Required

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.

from string(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.

Hide investigation_fields attribute Show investigation_fields attribute object

field_names array[string(nonempty)] Required

A string that does not contain only whitespace characters

At least 1 element. Minimum length of each is 1.

license string

The rule's license.

max_signals integer Required

Maximum number of alerts the rule can create during a single run (the rule’s Max alerts per run advanced setting value).

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.

Minimum value is 1. Default value is 100.

meta object

Placeholder for metadata about the rule.

This field is overwritten when you save changes to the rule’s settings.

Additional properties are allowed.

name string Required

A human-readable name for the rule.

Minimum length is 1.

namespace string

Has no effect.

note string

Notes to help investigate alerts produced by the rule.

outcome string

Values are exactMatch, aliasMatch, or conflict.

output_index string Deprecated

(deprecated) Has no effect.

references array[string] Required

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.

related_integrations array[object] Required

Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:

package: name of the package (required, unique id)

version: version of the package (required, semver-compatible)

integration: name of the integration of this package (optional, id within the package)

There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.

Hide related_integrations attributes Show related_integrations attributes object

integration string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

package string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

version string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

required_fields array[object] Required

Elasticsearch fields and their types that need to be present for the rule to function.

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.

Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.

Hide required_fields attributes Show required_fields attributes object

name string(nonempty) Required

Name of an Elasticsearch field

Minimum length is 1.

type string(nonempty) Required

Type of the Elasticsearch field

Minimum length is 1.

response_actions array[object]

One of:
Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object

Hide attributes Show attributes

action_type_id string Required

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

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

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[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.

Hide attributes Show attributes

action_type_id string Required

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object

Hide attributes Show attributes

command string Required

Value is isolate.

comment string

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.

risk_score integer 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

Minimum value is 0, maximum value is 100.

risk_score_mapping array[object] Required

Overrides generated alerts' risk_score with a value from the source event

Hide risk_score_mapping attributes Show risk_score_mapping attributes object

field string Required

Source event field used to override the default risk_score.

operator string Required

Value is equals.

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

Minimum value is 0, maximum value is 100.

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 string 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 are low, medium, high, or critical.

severity_mapping array[object] Required

Overrides generated alerts' severity with values from the source event

Hide severity_mapping attributes Show severity_mapping attributes object

field string Required

Source event field used to override the default severity.

operator string Required

Value is equals.

severity string 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 are low, medium, high, or critical.

value string Required

tags array[string] Required

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.

threat array[object] Required

Currently, only threats described using the MITRE ATT&CK™ framework are supported.

Hide threat attributes Show threat attributes object

framework string Required

Relevant attack framework

tactic object Required

Object containing information on the attack type

Hide tactic attributes Show tactic attributes object

id string Required

Tactic ID

name string Required

Tactic name

reference string Required

Tactic reference

technique array[object]

Array containing information on the attack techniques (optional)

Hide technique attributes Show technique attributes object

id string Required

Technique ID

name string Required

Technique name

reference string Required

Technique reference

subtechnique array[object]

Array containing more specific information on the attack technique.

Hide subtechnique attributes Show subtechnique attributes object

id string Required

Subtechnique ID

name string Required

Subtechnique name

reference string Required

Subtechnique reference

throttle string | null

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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 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.

It is not incremented on each update. Compare this to the revision field.

Minimum value is 1.

created_at string(date-time) Required

created_by string Required

execution_summary object

Summary of the last execution of a rule.

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

Hide execution_summary attribute Show execution_summary attribute object

last_execution object Required

Hide last_execution attributes Show last_execution attributes object

date string(date-time) Required

Date of the last execution

message string Required

metrics object Required

Hide metrics attributes Show metrics attributes object

execution_gap_duration_s integer

Duration in seconds of execution gap

Minimum value is 0.

frozen_indices_queried_count integer

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

Minimum value is 0.

gap_range object

Range of the execution gap

Hide gap_range attributes Show gap_range attributes object

gte string Required

Start date of the execution gap

lte string Required

End date of the execution gap

total_enrichment_duration_ms integer

Total time spent enriching documents during current rule execution cycle

Minimum value is 0.

total_indexing_duration_ms integer

Total time spent indexing documents during current rule execution cycle

Minimum value is 0.

total_search_duration_ms integer

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

Minimum value is 0.

status string Required

Status of the last execution

Values are going to run, running, partial failure, failed, or succeeded.

status_order integer Required

id string(uuid) Required

A dynamic unique identifier for the rule object. It is randomly generated when a rule is created and cannot be changed after that. It is always a UUID. It is unique within a given Kibana space. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have different object ids.

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

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.

Minimum value is 0.

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 object 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:
Security_Detections_API_ExternalRuleSource object Security_Detections_API_InternalRuleSource object

Type of rule source for externally sourced rules, i.e. rules that have an external source, such as the Elastic Prebuilt rules repo.

Hide attributes Show attributes

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

type string Required Discriminator

Value is external.

updated_at string(date-time) Required

updated_by string Required

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.

threat_index array[string] Required

Elasticsearch indices used to check which field values generate alerts.

threat_mapping array[object] Required

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 Example of Threat Match rule which uses both and and or logic.

At least 1 element.

Hide threat_mapping attribute Show threat_mapping attribute object

entries array[object] Required

Hide entries attributes Show entries attributes object

field string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

type string Required

Value is mapping.

value string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

threat_query string Required

Query used to determine which fields in the Elasticsearch index are used for generating alerts.

type string Required Discriminator

Rule type

Value is threat_match.

alert_suppression object

Defines alert suppression configuration.

Hide alert_suppression attributes Show alert_suppression attributes object

duration object

Hide duration attributes Show duration attributes object

unit string Required

Time unit

Values are s, m, or h.

value integer Required

Minimum value is 1.

group_by array[string] Required

At least 1 but not more than 3 elements.

missing_fields_strategy string

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 are doNotSuppress or suppress.

concurrent_searches integer

Minimum value is 1.

data_view_id string

filters array

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

items_per_search integer

Minimum value is 1.

saved_id string

Kibana saved search used by the rule to create alerts.

threat_filters array

Query and filter context array used to filter documents from the Elasticsearch index containing the threat values

threat_indicator_path string

Defines the path to the threat indicator in the indicator documents (optional)

threat_language string

Values are kuery or lucene.

language string Required

Values are kuery or lucene.
Hide attributes Show attributes

actions array[object] Required

Array defining the automated actions (notifications) taken when alerts are generated.

Hide actions attributes Show actions attributes object

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.

Additional properties are allowed.

frequency object

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

Hide frequency attributes Show frequency attributes object

notifyWhen string Required

Defines how often rules run actions.

Values are onActiveAlert, onThrottleInterval, or 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 string | null Required

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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.

Additional properties are allowed.

uuid string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

alias_purpose string

Values are savedObjectConversion or savedObjectImport.

alias_target_id string

author array[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 Required

The rule’s description.

Minimum length is 1.

enabled boolean Required

Determines whether the rule is enabled. Defaults to true.

exceptions_list array[object] Required

Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.

Hide exceptions_list attributes Show exceptions_list attributes object

id string(nonempty) Required

ID of the exception container

Minimum length is 1.

list_id string(nonempty) Required

List ID of the exception container

Minimum length is 1.

namespace_type string Required

Determines the exceptions validity in rule's Kibana space

Values are agnostic or single.

type string Required

The exception type

Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.

false_positives array[string] Required

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.

from string(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.

Hide investigation_fields attribute Show investigation_fields attribute object

field_names array[string(nonempty)] Required

A string that does not contain only whitespace characters

At least 1 element. Minimum length of each is 1.

license string

The rule's license.

max_signals integer Required

Maximum number of alerts the rule can create during a single run (the rule’s Max alerts per run advanced setting value).

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.

Minimum value is 1. Default value is 100.

meta object

Placeholder for metadata about the rule.

This field is overwritten when you save changes to the rule’s settings.

Additional properties are allowed.

name string Required

A human-readable name for the rule.

Minimum length is 1.

namespace string

Has no effect.

note string

Notes to help investigate alerts produced by the rule.

outcome string

Values are exactMatch, aliasMatch, or conflict.

output_index string Deprecated

(deprecated) Has no effect.

references array[string] Required

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.

related_integrations array[object] Required

Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:

package: name of the package (required, unique id)

version: version of the package (required, semver-compatible)

integration: name of the integration of this package (optional, id within the package)

There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.

Hide related_integrations attributes Show related_integrations attributes object

integration string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

package string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

version string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

required_fields array[object] Required

Elasticsearch fields and their types that need to be present for the rule to function.

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.

Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.

Hide required_fields attributes Show required_fields attributes object

name string(nonempty) Required

Name of an Elasticsearch field

Minimum length is 1.

type string(nonempty) Required

Type of the Elasticsearch field

Minimum length is 1.

response_actions array[object]

One of:
Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object

Hide attributes Show attributes

action_type_id string Required

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

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

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[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.

Hide attributes Show attributes

action_type_id string Required

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object

Hide attributes Show attributes

command string Required

Value is isolate.

comment string

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.

risk_score integer 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

Minimum value is 0, maximum value is 100.

risk_score_mapping array[object] Required

Overrides generated alerts' risk_score with a value from the source event

Hide risk_score_mapping attributes Show risk_score_mapping attributes object

field string Required

Source event field used to override the default risk_score.

operator string Required

Value is equals.

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

Minimum value is 0, maximum value is 100.

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 string 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 are low, medium, high, or critical.

severity_mapping array[object] Required

Overrides generated alerts' severity with values from the source event

Hide severity_mapping attributes Show severity_mapping attributes object

field string Required

Source event field used to override the default severity.

operator string Required

Value is equals.

severity string 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 are low, medium, high, or critical.

value string Required

tags array[string] Required

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.

threat array[object] Required

Currently, only threats described using the MITRE ATT&CK™ framework are supported.

Hide threat attributes Show threat attributes object

framework string Required

Relevant attack framework

tactic object Required

Object containing information on the attack type

Hide tactic attributes Show tactic attributes object

id string Required

Tactic ID

name string Required

Tactic name

reference string Required

Tactic reference

technique array[object]

Array containing information on the attack techniques (optional)

Hide technique attributes Show technique attributes object

id string Required

Technique ID

name string Required

Technique name

reference string Required

Technique reference

subtechnique array[object]

Array containing more specific information on the attack technique.

Hide subtechnique attributes Show subtechnique attributes object

id string Required

Subtechnique ID

name string Required

Subtechnique name

reference string Required

Subtechnique reference

throttle string | null

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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 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.

It is not incremented on each update. Compare this to the revision field.

Minimum value is 1.

created_at string(date-time) Required

created_by string Required

execution_summary object

Summary of the last execution of a rule.

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

Hide execution_summary attribute Show execution_summary attribute object

last_execution object Required

Hide last_execution attributes Show last_execution attributes object

date string(date-time) Required

Date of the last execution

message string Required

metrics object Required

Hide metrics attributes Show metrics attributes object

execution_gap_duration_s integer

Duration in seconds of execution gap

Minimum value is 0.

frozen_indices_queried_count integer

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

Minimum value is 0.

gap_range object

Range of the execution gap

Hide gap_range attributes Show gap_range attributes object

gte string Required

Start date of the execution gap

lte string Required

End date of the execution gap

total_enrichment_duration_ms integer

Total time spent enriching documents during current rule execution cycle

Minimum value is 0.

total_indexing_duration_ms integer

Total time spent indexing documents during current rule execution cycle

Minimum value is 0.

total_search_duration_ms integer

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

Minimum value is 0.

status string Required

Status of the last execution

Values are going to run, running, partial failure, failed, or succeeded.

status_order integer Required

id string(uuid) Required

A dynamic unique identifier for the rule object. It is randomly generated when a rule is created and cannot be changed after that. It is always a UUID. It is unique within a given Kibana space. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have different object ids.

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

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.

Minimum value is 0.

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 object 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:
Security_Detections_API_ExternalRuleSource object Security_Detections_API_InternalRuleSource object

Type of rule source for externally sourced rules, i.e. rules that have an external source, such as the Elastic Prebuilt rules repo.

Hide attributes Show attributes

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

type string Required Discriminator

Value is external.

updated_at string(date-time) Required

updated_by string Required

anomaly_threshold integer Required

Anomaly score threshold above which the rule creates an alert. Valid values are from 0 to 100.

Minimum value is 0.

machine_learning_job_id string | array[string] Required

Machine learning job ID(s) the rule monitors for anomaly scores.

One of:
string-1 string array-2 array[string]

type string Required Discriminator

Rule type

Value is machine_learning.

alert_suppression object

Defines alert suppression configuration.

Hide alert_suppression attributes Show alert_suppression attributes object

duration object

Hide duration attributes Show duration attributes object

unit string Required

Time unit

Values are s, m, or h.

value integer Required

Minimum value is 1.

group_by array[string] Required

At least 1 but not more than 3 elements.

missing_fields_strategy string

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 are doNotSuppress or suppress.
Hide attributes Show attributes

actions array[object] Required

Array defining the automated actions (notifications) taken when alerts are generated.

Hide actions attributes Show actions attributes object

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.

Additional properties are allowed.

frequency object

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

Hide frequency attributes Show frequency attributes object

notifyWhen string Required

Defines how often rules run actions.

Values are onActiveAlert, onThrottleInterval, or 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 string | null Required

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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.

Additional properties are allowed.

uuid string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

alias_purpose string

Values are savedObjectConversion or savedObjectImport.

alias_target_id string

author array[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 Required

The rule’s description.

Minimum length is 1.

enabled boolean Required

Determines whether the rule is enabled. Defaults to true.

exceptions_list array[object] Required

Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.

Hide exceptions_list attributes Show exceptions_list attributes object

id string(nonempty) Required

ID of the exception container

Minimum length is 1.

list_id string(nonempty) Required

List ID of the exception container

Minimum length is 1.

namespace_type string Required

Determines the exceptions validity in rule's Kibana space

Values are agnostic or single.

type string Required

The exception type

Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.

false_positives array[string] Required

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.

from string(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.

Hide investigation_fields attribute Show investigation_fields attribute object

field_names array[string(nonempty)] Required

A string that does not contain only whitespace characters

At least 1 element. Minimum length of each is 1.

license string

The rule's license.

max_signals integer Required

Maximum number of alerts the rule can create during a single run (the rule’s Max alerts per run advanced setting value).

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.

Minimum value is 1. Default value is 100.

meta object

Placeholder for metadata about the rule.

This field is overwritten when you save changes to the rule’s settings.

Additional properties are allowed.

name string Required

A human-readable name for the rule.

Minimum length is 1.

namespace string

Has no effect.

note string

Notes to help investigate alerts produced by the rule.

outcome string

Values are exactMatch, aliasMatch, or conflict.

output_index string Deprecated

(deprecated) Has no effect.

references array[string] Required

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.

related_integrations array[object] Required

Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:

package: name of the package (required, unique id)

version: version of the package (required, semver-compatible)

integration: name of the integration of this package (optional, id within the package)

There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.

Hide related_integrations attributes Show related_integrations attributes object

integration string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

package string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

version string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

required_fields array[object] Required

Elasticsearch fields and their types that need to be present for the rule to function.

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.

Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.

Hide required_fields attributes Show required_fields attributes object

name string(nonempty) Required

Name of an Elasticsearch field

Minimum length is 1.

type string(nonempty) Required

Type of the Elasticsearch field

Minimum length is 1.

response_actions array[object]

One of:
Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object

Hide attributes Show attributes

action_type_id string Required

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

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

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[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.

Hide attributes Show attributes

action_type_id string Required

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object

Hide attributes Show attributes

command string Required

Value is isolate.

comment string

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.

risk_score integer 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

Minimum value is 0, maximum value is 100.

risk_score_mapping array[object] Required

Overrides generated alerts' risk_score with a value from the source event

Hide risk_score_mapping attributes Show risk_score_mapping attributes object

field string Required

Source event field used to override the default risk_score.

operator string Required

Value is equals.

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

Minimum value is 0, maximum value is 100.

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 string 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 are low, medium, high, or critical.

severity_mapping array[object] Required

Overrides generated alerts' severity with values from the source event

Hide severity_mapping attributes Show severity_mapping attributes object

field string Required

Source event field used to override the default severity.

operator string Required

Value is equals.

severity string 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 are low, medium, high, or critical.

value string Required

tags array[string] Required

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.

threat array[object] Required

Currently, only threats described using the MITRE ATT&CK™ framework are supported.

Hide threat attributes Show threat attributes object

framework string Required

Relevant attack framework

tactic object Required

Object containing information on the attack type

Hide tactic attributes Show tactic attributes object

id string Required

Tactic ID

name string Required

Tactic name

reference string Required

Tactic reference

technique array[object]

Array containing information on the attack techniques (optional)

Hide technique attributes Show technique attributes object

id string Required

Technique ID

name string Required

Technique name

reference string Required

Technique reference

subtechnique array[object]

Array containing more specific information on the attack technique.

Hide subtechnique attributes Show subtechnique attributes object

id string Required

Subtechnique ID

name string Required

Subtechnique name

reference string Required

Subtechnique reference

throttle string | null

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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 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.

It is not incremented on each update. Compare this to the revision field.

Minimum value is 1.

created_at string(date-time) Required

created_by string Required

execution_summary object

Summary of the last execution of a rule.

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

Hide execution_summary attribute Show execution_summary attribute object

last_execution object Required

Hide last_execution attributes Show last_execution attributes object

date string(date-time) Required

Date of the last execution

message string Required

metrics object Required

Hide metrics attributes Show metrics attributes object

execution_gap_duration_s integer

Duration in seconds of execution gap

Minimum value is 0.

frozen_indices_queried_count integer

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

Minimum value is 0.

gap_range object

Range of the execution gap

Hide gap_range attributes Show gap_range attributes object

gte string Required

Start date of the execution gap

lte string Required

End date of the execution gap

total_enrichment_duration_ms integer

Total time spent enriching documents during current rule execution cycle

Minimum value is 0.

total_indexing_duration_ms integer

Total time spent indexing documents during current rule execution cycle

Minimum value is 0.

total_search_duration_ms integer

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

Minimum value is 0.

status string Required

Status of the last execution

Values are going to run, running, partial failure, failed, or succeeded.

status_order integer Required

id string(uuid) Required

A dynamic unique identifier for the rule object. It is randomly generated when a rule is created and cannot be changed after that. It is always a UUID. It is unique within a given Kibana space. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have different object ids.

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

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.

Minimum value is 0.

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 object 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:
Security_Detections_API_ExternalRuleSource object Security_Detections_API_InternalRuleSource object

Type of rule source for externally sourced rules, i.e. rules that have an external source, such as the Elastic Prebuilt rules repo.

Hide attributes Show attributes

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

type string Required Discriminator

Value is external.

updated_at string(date-time) Required

updated_by string Required

history_window_start string(nonempty) Required

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.

Minimum length is 1.

new_terms_fields array[string] Required

Fields to monitor for new values.

At least 1 but not more than 3 elements.

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.

type string Required Discriminator

Rule type

Value is new_terms.

alert_suppression object

Defines alert suppression configuration.

Hide alert_suppression attributes Show alert_suppression attributes object

duration object

Hide duration attributes Show duration attributes object

unit string Required

Time unit

Values are s, m, or h.

value integer Required

Minimum value is 1.

group_by array[string] Required

At least 1 but not more than 3 elements.

missing_fields_strategy string

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 are doNotSuppress or suppress.

data_view_id string

filters array

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

language string Required

Values are kuery or lucene.
Hide attributes Show attributes

actions array[object] Required

Array defining the automated actions (notifications) taken when alerts are generated.

Hide actions attributes Show actions attributes object

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.

Additional properties are allowed.

frequency object

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

Hide frequency attributes Show frequency attributes object

notifyWhen string Required

Defines how often rules run actions.

Values are onActiveAlert, onThrottleInterval, or 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 string | null Required

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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.

Additional properties are allowed.

uuid string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

alias_purpose string

Values are savedObjectConversion or savedObjectImport.

alias_target_id string

author array[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 Required

The rule’s description.

Minimum length is 1.

enabled boolean Required

Determines whether the rule is enabled. Defaults to true.

exceptions_list array[object] Required

Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.

Hide exceptions_list attributes Show exceptions_list attributes object

id string(nonempty) Required

ID of the exception container

Minimum length is 1.

list_id string(nonempty) Required

List ID of the exception container

Minimum length is 1.

namespace_type string Required

Determines the exceptions validity in rule's Kibana space

Values are agnostic or single.

type string Required

The exception type

Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.

false_positives array[string] Required

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.

from string(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.

Hide investigation_fields attribute Show investigation_fields attribute object

field_names array[string(nonempty)] Required

A string that does not contain only whitespace characters

At least 1 element. Minimum length of each is 1.

license string

The rule's license.

max_signals integer Required

Maximum number of alerts the rule can create during a single run (the rule’s Max alerts per run advanced setting value).

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.

Minimum value is 1. Default value is 100.

meta object

Placeholder for metadata about the rule.

This field is overwritten when you save changes to the rule’s settings.

Additional properties are allowed.

name string Required

A human-readable name for the rule.

Minimum length is 1.

namespace string

Has no effect.

note string

Notes to help investigate alerts produced by the rule.

outcome string

Values are exactMatch, aliasMatch, or conflict.

output_index string Deprecated

(deprecated) Has no effect.

references array[string] Required

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.

related_integrations array[object] Required

Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:

package: name of the package (required, unique id)

version: version of the package (required, semver-compatible)

integration: name of the integration of this package (optional, id within the package)

There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.

Hide related_integrations attributes Show related_integrations attributes object

integration string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

package string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

version string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

required_fields array[object] Required

Elasticsearch fields and their types that need to be present for the rule to function.

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.

Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.

Hide required_fields attributes Show required_fields attributes object

name string(nonempty) Required

Name of an Elasticsearch field

Minimum length is 1.

type string(nonempty) Required

Type of the Elasticsearch field

Minimum length is 1.

response_actions array[object]

One of:
Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object

Hide attributes Show attributes

action_type_id string Required

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

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

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[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.

Hide attributes Show attributes

action_type_id string Required

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object

Hide attributes Show attributes

command string Required

Value is isolate.

comment string

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.

risk_score integer 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

Minimum value is 0, maximum value is 100.

risk_score_mapping array[object] Required

Overrides generated alerts' risk_score with a value from the source event

Hide risk_score_mapping attributes Show risk_score_mapping attributes object

field string Required

Source event field used to override the default risk_score.

operator string Required

Value is equals.

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

Minimum value is 0, maximum value is 100.

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 string 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 are low, medium, high, or critical.

severity_mapping array[object] Required

Overrides generated alerts' severity with values from the source event

Hide severity_mapping attributes Show severity_mapping attributes object

field string Required

Source event field used to override the default severity.

operator string Required

Value is equals.

severity string 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 are low, medium, high, or critical.

value string Required

tags array[string] Required

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.

threat array[object] Required

Currently, only threats described using the MITRE ATT&CK™ framework are supported.

Hide threat attributes Show threat attributes object

framework string Required

Relevant attack framework

tactic object Required

Object containing information on the attack type

Hide tactic attributes Show tactic attributes object

id string Required

Tactic ID

name string Required

Tactic name

reference string Required

Tactic reference

technique array[object]

Array containing information on the attack techniques (optional)

Hide technique attributes Show technique attributes object

id string Required

Technique ID

name string Required

Technique name

reference string Required

Technique reference

subtechnique array[object]

Array containing more specific information on the attack technique.

Hide subtechnique attributes Show subtechnique attributes object

id string Required

Subtechnique ID

name string Required

Subtechnique name

reference string Required

Subtechnique reference

throttle string | null

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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 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.

It is not incremented on each update. Compare this to the revision field.

Minimum value is 1.

created_at string(date-time) Required

created_by string Required

execution_summary object

Summary of the last execution of a rule.

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

Hide execution_summary attribute Show execution_summary attribute object

last_execution object Required

Hide last_execution attributes Show last_execution attributes object

date string(date-time) Required

Date of the last execution

message string Required

metrics object Required

Hide metrics attributes Show metrics attributes object

execution_gap_duration_s integer

Duration in seconds of execution gap

Minimum value is 0.

frozen_indices_queried_count integer

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

Minimum value is 0.

gap_range object

Range of the execution gap

Hide gap_range attributes Show gap_range attributes object

gte string Required

Start date of the execution gap

lte string Required

End date of the execution gap

total_enrichment_duration_ms integer

Total time spent enriching documents during current rule execution cycle

Minimum value is 0.

total_indexing_duration_ms integer

Total time spent indexing documents during current rule execution cycle

Minimum value is 0.

total_search_duration_ms integer

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

Minimum value is 0.

status string Required

Status of the last execution

Values are going to run, running, partial failure, failed, or succeeded.

status_order integer Required

id string(uuid) Required

A dynamic unique identifier for the rule object. It is randomly generated when a rule is created and cannot be changed after that. It is always a UUID. It is unique within a given Kibana space. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have different object ids.

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

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.

Minimum value is 0.

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 object 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:
Security_Detections_API_ExternalRuleSource object Security_Detections_API_InternalRuleSource object

Type of rule source for externally sourced rules, i.e. rules that have an external source, such as the Elastic Prebuilt rules repo.

Hide attributes Show attributes

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

type string Required Discriminator

Value is external.

updated_at string(date-time) Required

updated_by string Required

alert_suppression object

Defines alert suppression configuration.

Hide alert_suppression attributes Show alert_suppression attributes object

duration object

Hide duration attributes Show duration attributes object

unit string Required

Time unit

Values are s, m, or h.

value integer Required

Minimum value is 1.

group_by array[string] Required

At least 1 but not more than 3 elements.

missing_fields_strategy string

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 are doNotSuppress or suppress.

language string Required

Value is esql.

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.

type string Required Discriminator

Rule type

Value is esql.

GET /api/detection_engine/rules

curl \
  --request GET https://localhost:5601/api/detection_engine/rules?rule_id=bfeaf89b-a2a7-48a3-817f-e41829dc61ee \
  --header "Content-Type: application/json; Elastic-Api-Version=2023-10-31"

Response examples (200)

{
  "id": "c41d170b-8ba6-4de6-b8ec-76440a35ace3",
  "to": "now-300s",
  "from": "now-4200s",
  "name": "MS Office child process",
  "tags": [
    "child process",
    "ms office"
  ],
  "type": "query",
  "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",
  "setup": "",
  "threat": [
    {
      "tactic": {
        "id": "TA0001",
        "name": "Initial Access",
        "reference": "https://attack.mitre.org/tactics/TA0001"
      },
      "framework": "MITRE ATT&CK",
      "technique": [
        {
          "id": "T1193",
          "name": "Spearphishing Attachment",
          "reference": "https://attack.mitre.org/techniques/T1193"
        }
      ]
    }
  ],
  "enabled": false,
  "filters": [
    {
      "query": {
        "match": {
          "event.action": {
            "type": "phrase",
            "query": "Process Create (rule: ProcessCreate)"
          }
        }
      }
    }
  ],
  "rule_id": "process_started_by_ms_office_user_folder",
  "version": 1,
  "interval": "1h",
  "language": "kuery",
  "severity": "low",
  "immutable": false,
  "created_at": "2020-02-03T11:19:04.259Z",
  "created_by": "elastic",
  "references": [],
  "risk_score": 21,
  "updated_at": "2020-02-03T11:19:04.462Z",
  "updated_by": "elastic",
  "description": "Process started by MS Office program in user folder",
  "max_signals": 100,
  "false_positives": [],
  "required_fields": [
    {
      "ecs": true,
      "name": "process.name",
      "type": "keyword"
    },
    {
      "ecs": true,
      "name": "process.parent.name",
      "type": "keyword"
    }
  ],
  "execution_summary": {
    "last_execution": {
      "date": "2022-03-23T16:06:12.787Z",
      "status": "partial failure",
      "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": {
        "execution_gap_duration_s": 0,
        "total_search_duration_ms": 135,
        "total_indexing_duration_ms": 15
      },
      "status_order": 20
    }
  },
  "related_integrations": [
    {
      "package": "o365",
      "version": "^2.3.2"
    }
  ]
}

Update a detection rule

PUT /api/detection_engine/rules

Update a detection rule using the rule_id or id field. The original rule is replaced, and all unspecified fields are deleted.

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.

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.

application/json

Body object Required

All unspecified fields are deleted. You cannot modify the id or rule_id values.

actions array[object]

Array defining the automated actions (notifications) taken when alerts are generated.
Hide actions attributes Show actions attributes object
- 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.
  Additional properties are allowed.
- frequency object
  
  The action frequency defines when the action runs (for example, only on rule execution or at specific time intervals).
  Hide frequency attributes Show frequency attributes object
  
  notifyWhen string Required
  
  Defines how often rules run actions.
  
  Values are onActiveAlert, onThrottleInterval, or 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 string | null Required
  
  Defines how often rule actions are taken.
  
  One of:
  string-1 string | null string-2 string | null
  
  Values are no_actions or 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.
  Additional properties are allowed.
- uuid string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
alias_purpose string

Values are savedObjectConversion or savedObjectImport.
alias_target_id string
author array[string]

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 Required

The rule’s description.

Minimum length is 1.
enabled boolean

Determines whether the rule is enabled. Defaults to true.
exceptions_list array[object]

Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.
Hide exceptions_list attributes Show exceptions_list attributes object
- id string(nonempty) Required
  
  ID of the exception container
  
  Minimum length is 1.
- list_id string(nonempty) Required
  
  List ID of the exception container
  
  Minimum length is 1.
- namespace_type string Required
  
  Determines the exceptions validity in rule's Kibana space
  
  Values are agnostic or single.
- type string Required
  
  The exception type
  
  Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.
false_positives array[string]

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.
from string(date-math)

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).
id string(uuid)

A dynamic unique identifier for the rule object. It is randomly generated when a rule is created and cannot be changed after that. It is always a UUID. It is unique within a given Kibana space. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have different object ids.
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).
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.
Hide investigation_fields attribute Show investigation_fields attribute object
- field_names array[string(nonempty)] Required
  
  A string that does not contain only whitespace characters
  
  At least 1 element. Minimum length of each is 1.
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).

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.

Minimum value is 1. Default value is 100.
meta object

Placeholder for metadata about the rule.

This field is overwritten when you save changes to the rule’s settings.

Additional properties are allowed.
name string Required

A human-readable name for the rule.

Minimum length is 1.
namespace string

Has no effect.
note string

Notes to help investigate alerts produced by the rule.
outcome string

Values are exactMatch, aliasMatch, or conflict.
output_index string Deprecated

(deprecated) Has no effect.
references array[string]

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.
related_integrations array[object]
Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:
- package: name of the package (required, unique id)
- version: version of the package (required, semver-compatible)
- integration: name of the integration of this package (optional, id within the package)
There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.
Hide related_integrations attributes Show related_integrations attributes object
- integration string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- package string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- version string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
required_fields array[object]

Elasticsearch fields and their types that need to be present for the rule to function.

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.

Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.
Hide required_fields attributes Show required_fields attributes object
- name string(nonempty) Required
  
  Name of an Elasticsearch field
  
  Minimum length is 1.
- type string(nonempty) Required
  
  Type of the Elasticsearch field
  
  Minimum length is 1.
response_actions array[object]
One of:
Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object
Hide attributes Show attributes

action_type_id string Required

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

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

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[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.
Hide attributes Show attributes

action_type_id string Required

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object

Hide attributes Show attributes

command string Required

Value is isolate.

comment string

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.
risk_score integer 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
Minimum value is 0, maximum value is 100.
risk_score_mapping array[object]

Overrides generated alerts' risk_score with a value from the source event
Hide risk_score_mapping attributes Show risk_score_mapping attributes object
- field string Required
  
  Source event field used to override the default risk_score.
- operator string Required
  
  Value is equals.
- 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
  Minimum value is 0, maximum value is 100.
- value string Required
rule_id string

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

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 string 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 are low, medium, high, or critical.
severity_mapping array[object]

Overrides generated alerts' severity with values from the source event
Hide severity_mapping attributes Show severity_mapping attributes object
- field string Required
  
  Source event field used to override the default severity.
- operator string Required
  
  Value is equals.
- severity string 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 are low, medium, high, or critical.
- value string Required
tags array[string]

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.
threat array[object]

Currently, only threats described using the MITRE ATT&CK™ framework are supported.
Hide threat attributes Show threat attributes object
- framework string Required
  
  Relevant attack framework
- tactic object Required
  
  Object containing information on the attack type
  Hide tactic attributes Show tactic attributes object
  
  id string Required
  
  Tactic ID
  
  name string Required
  
  Tactic name
  
  reference string Required
  
  Tactic reference
- technique array[object]
  
  Array containing information on the attack techniques (optional)
  Hide technique attributes Show technique attributes object
  
  id string Required
  
  Technique ID
  
  name string Required
  
  Technique name
  
  reference string Required
  
  Technique reference
  
  subtechnique array[object]
  
  Array containing more specific information on the attack technique.
  
  Hide subtechnique attributes Show subtechnique attributes object
  
  id string Required
  
  Subtechnique ID
  
  name string Required
  
  Subtechnique name
  
  reference string Required
  
  Subtechnique reference
throttle string | null

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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
version integer
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.
It is not incremented on each update. Compare this to the revision field.
Minimum value is 1.
language string Required

Query language to use

Value is 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.
type string Required Discriminator

Rule type

Value is eql.
alert_suppression object

Defines alert suppression configuration.
Hide alert_suppression attributes Show alert_suppression attributes object
- duration object
  Hide duration attributes Show duration attributes object
  
  unit string Required
  
  Time unit
  
  Values are s, m, or h.
  
  value integer Required
  
  Minimum value is 1.
- group_by array[string] Required
  
  At least 1 but not more than 3 elements.
- missing_fields_strategy string
  
  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 are doNotSuppress or suppress.
data_view_id string
event_category_override string
filters array

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

actions array[object]

Array defining the automated actions (notifications) taken when alerts are generated.
Hide actions attributes Show actions attributes object
- 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.
  Additional properties are allowed.
- frequency object
  
  The action frequency defines when the action runs (for example, only on rule execution or at specific time intervals).
  Hide frequency attributes Show frequency attributes object
  
  notifyWhen string Required
  
  Defines how often rules run actions.
  
  Values are onActiveAlert, onThrottleInterval, or 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 string | null Required
  
  Defines how often rule actions are taken.
  
  One of:
  string-1 string | null string-2 string | null
  
  Values are no_actions or 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.
  Additional properties are allowed.
- uuid string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
alias_purpose string

Values are savedObjectConversion or savedObjectImport.
alias_target_id string
author array[string]

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 Required

The rule’s description.

Minimum length is 1.
enabled boolean

Determines whether the rule is enabled. Defaults to true.
exceptions_list array[object]

Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.
Hide exceptions_list attributes Show exceptions_list attributes object
- id string(nonempty) Required
  
  ID of the exception container
  
  Minimum length is 1.
- list_id string(nonempty) Required
  
  List ID of the exception container
  
  Minimum length is 1.
- namespace_type string Required
  
  Determines the exceptions validity in rule's Kibana space
  
  Values are agnostic or single.
- type string Required
  
  The exception type
  
  Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.
false_positives array[string]

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.
from string(date-math)

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).
id string(uuid)

A dynamic unique identifier for the rule object. It is randomly generated when a rule is created and cannot be changed after that. It is always a UUID. It is unique within a given Kibana space. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have different object ids.
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).
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.
Hide investigation_fields attribute Show investigation_fields attribute object
- field_names array[string(nonempty)] Required
  
  A string that does not contain only whitespace characters
  
  At least 1 element. Minimum length of each is 1.
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).

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.

Minimum value is 1. Default value is 100.
meta object

Placeholder for metadata about the rule.

This field is overwritten when you save changes to the rule’s settings.

Additional properties are allowed.
name string Required

A human-readable name for the rule.

Minimum length is 1.
namespace string

Has no effect.
note string

Notes to help investigate alerts produced by the rule.
outcome string

Values are exactMatch, aliasMatch, or conflict.
output_index string Deprecated

(deprecated) Has no effect.
references array[string]

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.
related_integrations array[object]
Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:
- package: name of the package (required, unique id)
- version: version of the package (required, semver-compatible)
- integration: name of the integration of this package (optional, id within the package)
There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.
Hide related_integrations attributes Show related_integrations attributes object
- integration string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- package string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- version string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
required_fields array[object]

Elasticsearch fields and their types that need to be present for the rule to function.

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.

Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.
Hide required_fields attributes Show required_fields attributes object
- name string(nonempty) Required
  
  Name of an Elasticsearch field
  
  Minimum length is 1.
- type string(nonempty) Required
  
  Type of the Elasticsearch field
  
  Minimum length is 1.
response_actions array[object]
One of:
Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object
Hide attributes Show attributes

action_type_id string Required

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

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

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[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.
Hide attributes Show attributes

action_type_id string Required

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object

Hide attributes Show attributes

command string Required

Value is isolate.

comment string

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.
risk_score integer 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
Minimum value is 0, maximum value is 100.
risk_score_mapping array[object]

Overrides generated alerts' risk_score with a value from the source event
Hide risk_score_mapping attributes Show risk_score_mapping attributes object
- field string Required
  
  Source event field used to override the default risk_score.
- operator string Required
  
  Value is equals.
- 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
  Minimum value is 0, maximum value is 100.
- value string Required
rule_id string

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

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 string 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 are low, medium, high, or critical.
severity_mapping array[object]

Overrides generated alerts' severity with values from the source event
Hide severity_mapping attributes Show severity_mapping attributes object
- field string Required
  
  Source event field used to override the default severity.
- operator string Required
  
  Value is equals.
- severity string 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 are low, medium, high, or critical.
- value string Required
tags array[string]

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.
threat array[object]

Currently, only threats described using the MITRE ATT&CK™ framework are supported.
Hide threat attributes Show threat attributes object
- framework string Required
  
  Relevant attack framework
- tactic object Required
  
  Object containing information on the attack type
  Hide tactic attributes Show tactic attributes object
  
  id string Required
  
  Tactic ID
  
  name string Required
  
  Tactic name
  
  reference string Required
  
  Tactic reference
- technique array[object]
  
  Array containing information on the attack techniques (optional)
  Hide technique attributes Show technique attributes object
  
  id string Required
  
  Technique ID
  
  name string Required
  
  Technique name
  
  reference string Required
  
  Technique reference
  
  subtechnique array[object]
  
  Array containing more specific information on the attack technique.
  
  Hide subtechnique attributes Show subtechnique attributes object
  
  id string Required
  
  Subtechnique ID
  
  name string Required
  
  Subtechnique name
  
  reference string Required
  
  Subtechnique reference
throttle string | null

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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
version integer
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.
It is not incremented on each update. Compare this to the revision field.
Minimum value is 1.
type string Required Discriminator

Rule type

Value is query.
alert_suppression object

Defines alert suppression configuration.
Hide alert_suppression attributes Show alert_suppression attributes object
- duration object
  Hide duration attributes Show duration attributes object
  
  unit string Required
  
  Time unit
  
  Values are s, m, or h.
  
  value integer Required
  
  Minimum value is 1.
- group_by array[string] Required
  
  At least 1 but not more than 3 elements.
- missing_fields_strategy string
  
  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 are doNotSuppress or suppress.
data_view_id string
filters array

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 array[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.
saved_id string

Kibana saved search used by the rule to create alerts.
language string

Values are kuery or lucene.
query string
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.

actions array[object]

Array defining the automated actions (notifications) taken when alerts are generated.
Hide actions attributes Show actions attributes object
- 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.
  Additional properties are allowed.
- frequency object
  
  The action frequency defines when the action runs (for example, only on rule execution or at specific time intervals).
  Hide frequency attributes Show frequency attributes object
  
  notifyWhen string Required
  
  Defines how often rules run actions.
  
  Values are onActiveAlert, onThrottleInterval, or 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 string | null Required
  
  Defines how often rule actions are taken.
  
  One of:
  string-1 string | null string-2 string | null
  
  Values are no_actions or 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.
  Additional properties are allowed.
- uuid string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
alias_purpose string

Values are savedObjectConversion or savedObjectImport.
alias_target_id string
author array[string]

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 Required

The rule’s description.

Minimum length is 1.
enabled boolean

Determines whether the rule is enabled. Defaults to true.
exceptions_list array[object]

Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.
Hide exceptions_list attributes Show exceptions_list attributes object
- id string(nonempty) Required
  
  ID of the exception container
  
  Minimum length is 1.
- list_id string(nonempty) Required
  
  List ID of the exception container
  
  Minimum length is 1.
- namespace_type string Required
  
  Determines the exceptions validity in rule's Kibana space
  
  Values are agnostic or single.
- type string Required
  
  The exception type
  
  Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.
false_positives array[string]

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.
from string(date-math)

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).
id string(uuid)

A dynamic unique identifier for the rule object. It is randomly generated when a rule is created and cannot be changed after that. It is always a UUID. It is unique within a given Kibana space. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have different object ids.
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).
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.
Hide investigation_fields attribute Show investigation_fields attribute object
- field_names array[string(nonempty)] Required
  
  A string that does not contain only whitespace characters
  
  At least 1 element. Minimum length of each is 1.
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).

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.

Minimum value is 1. Default value is 100.
meta object

Placeholder for metadata about the rule.

This field is overwritten when you save changes to the rule’s settings.

Additional properties are allowed.
name string Required

A human-readable name for the rule.

Minimum length is 1.
namespace string

Has no effect.
note string

Notes to help investigate alerts produced by the rule.
outcome string

Values are exactMatch, aliasMatch, or conflict.
output_index string Deprecated

(deprecated) Has no effect.
references array[string]

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.
related_integrations array[object]
Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:
- package: name of the package (required, unique id)
- version: version of the package (required, semver-compatible)
- integration: name of the integration of this package (optional, id within the package)
There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.
Hide related_integrations attributes Show related_integrations attributes object
- integration string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- package string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- version string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
required_fields array[object]

Elasticsearch fields and their types that need to be present for the rule to function.

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.

Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.
Hide required_fields attributes Show required_fields attributes object
- name string(nonempty) Required
  
  Name of an Elasticsearch field
  
  Minimum length is 1.
- type string(nonempty) Required
  
  Type of the Elasticsearch field
  
  Minimum length is 1.
response_actions array[object]
One of:
Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object
Hide attributes Show attributes

action_type_id string Required

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

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

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[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.
Hide attributes Show attributes

action_type_id string Required

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object

Hide attributes Show attributes

command string Required

Value is isolate.

comment string

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.
risk_score integer 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
Minimum value is 0, maximum value is 100.
risk_score_mapping array[object]

Overrides generated alerts' risk_score with a value from the source event
Hide risk_score_mapping attributes Show risk_score_mapping attributes object
- field string Required
  
  Source event field used to override the default risk_score.
- operator string Required
  
  Value is equals.
- 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
  Minimum value is 0, maximum value is 100.
- value string Required
rule_id string

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

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 string 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 are low, medium, high, or critical.
severity_mapping array[object]

Overrides generated alerts' severity with values from the source event
Hide severity_mapping attributes Show severity_mapping attributes object
- field string Required
  
  Source event field used to override the default severity.
- operator string Required
  
  Value is equals.
- severity string 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 are low, medium, high, or critical.
- value string Required
tags array[string]

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.
threat array[object]

Currently, only threats described using the MITRE ATT&CK™ framework are supported.
Hide threat attributes Show threat attributes object
- framework string Required
  
  Relevant attack framework
- tactic object Required
  
  Object containing information on the attack type
  Hide tactic attributes Show tactic attributes object
  
  id string Required
  
  Tactic ID
  
  name string Required
  
  Tactic name
  
  reference string Required
  
  Tactic reference
- technique array[object]
  
  Array containing information on the attack techniques (optional)
  Hide technique attributes Show technique attributes object
  
  id string Required
  
  Technique ID
  
  name string Required
  
  Technique name
  
  reference string Required
  
  Technique reference
  
  subtechnique array[object]
  
  Array containing more specific information on the attack technique.
  
  Hide subtechnique attributes Show subtechnique attributes object
  
  id string Required
  
  Subtechnique ID
  
  name string Required
  
  Subtechnique name
  
  reference string Required
  
  Subtechnique reference
throttle string | null

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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
version integer
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.
It is not incremented on each update. Compare this to the revision field.
Minimum value is 1.
saved_id string Required

Kibana saved search used by the rule to create alerts.
type string Required Discriminator

Rule type

Value is saved_query.
alert_suppression object

Defines alert suppression configuration.
Hide alert_suppression attributes Show alert_suppression attributes object
- duration object
  Hide duration attributes Show duration attributes object
  
  unit string Required
  
  Time unit
  
  Values are s, m, or h.
  
  value integer Required
  
  Minimum value is 1.
- group_by array[string] Required
  
  At least 1 but not more than 3 elements.
- missing_fields_strategy string
  
  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 are doNotSuppress or suppress.
data_view_id string
filters array

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 array[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.
query string
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.
language string

Values are kuery or lucene.

actions array[object]

Array defining the automated actions (notifications) taken when alerts are generated.
Hide actions attributes Show actions attributes object
- 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.
  Additional properties are allowed.
- frequency object
  
  The action frequency defines when the action runs (for example, only on rule execution or at specific time intervals).
  Hide frequency attributes Show frequency attributes object
  
  notifyWhen string Required
  
  Defines how often rules run actions.
  
  Values are onActiveAlert, onThrottleInterval, or 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 string | null Required
  
  Defines how often rule actions are taken.
  
  One of:
  string-1 string | null string-2 string | null
  
  Values are no_actions or 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.
  Additional properties are allowed.
- uuid string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
alias_purpose string

Values are savedObjectConversion or savedObjectImport.
alias_target_id string
author array[string]

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 Required

The rule’s description.

Minimum length is 1.
enabled boolean

Determines whether the rule is enabled. Defaults to true.
exceptions_list array[object]

Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.
Hide exceptions_list attributes Show exceptions_list attributes object
- id string(nonempty) Required
  
  ID of the exception container
  
  Minimum length is 1.
- list_id string(nonempty) Required
  
  List ID of the exception container
  
  Minimum length is 1.
- namespace_type string Required
  
  Determines the exceptions validity in rule's Kibana space
  
  Values are agnostic or single.
- type string Required
  
  The exception type
  
  Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.
false_positives array[string]

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.
from string(date-math)

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).
id string(uuid)

A dynamic unique identifier for the rule object. It is randomly generated when a rule is created and cannot be changed after that. It is always a UUID. It is unique within a given Kibana space. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have different object ids.
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).
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.
Hide investigation_fields attribute Show investigation_fields attribute object
- field_names array[string(nonempty)] Required
  
  A string that does not contain only whitespace characters
  
  At least 1 element. Minimum length of each is 1.
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).

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.

Minimum value is 1. Default value is 100.
meta object

Placeholder for metadata about the rule.

This field is overwritten when you save changes to the rule’s settings.

Additional properties are allowed.
name string Required

A human-readable name for the rule.

Minimum length is 1.
namespace string

Has no effect.
note string

Notes to help investigate alerts produced by the rule.
outcome string

Values are exactMatch, aliasMatch, or conflict.
output_index string Deprecated

(deprecated) Has no effect.
references array[string]

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.
related_integrations array[object]
Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:
- package: name of the package (required, unique id)
- version: version of the package (required, semver-compatible)
- integration: name of the integration of this package (optional, id within the package)
There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.
Hide related_integrations attributes Show related_integrations attributes object
- integration string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- package string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- version string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
required_fields array[object]

Elasticsearch fields and their types that need to be present for the rule to function.

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.

Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.
Hide required_fields attributes Show required_fields attributes object
- name string(nonempty) Required
  
  Name of an Elasticsearch field
  
  Minimum length is 1.
- type string(nonempty) Required
  
  Type of the Elasticsearch field
  
  Minimum length is 1.
response_actions array[object]
One of:
Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object
Hide attributes Show attributes

action_type_id string Required

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

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

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[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.
Hide attributes Show attributes

action_type_id string Required

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object

Hide attributes Show attributes

command string Required

Value is isolate.

comment string

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.
risk_score integer 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
Minimum value is 0, maximum value is 100.
risk_score_mapping array[object]

Overrides generated alerts' risk_score with a value from the source event
Hide risk_score_mapping attributes Show risk_score_mapping attributes object
- field string Required
  
  Source event field used to override the default risk_score.
- operator string Required
  
  Value is equals.
- 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
  Minimum value is 0, maximum value is 100.
- value string Required
rule_id string

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

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 string 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 are low, medium, high, or critical.
severity_mapping array[object]

Overrides generated alerts' severity with values from the source event
Hide severity_mapping attributes Show severity_mapping attributes object
- field string Required
  
  Source event field used to override the default severity.
- operator string Required
  
  Value is equals.
- severity string 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 are low, medium, high, or critical.
- value string Required
tags array[string]

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.
threat array[object]

Currently, only threats described using the MITRE ATT&CK™ framework are supported.
Hide threat attributes Show threat attributes object
- framework string Required
  
  Relevant attack framework
- tactic object Required
  
  Object containing information on the attack type
  Hide tactic attributes Show tactic attributes object
  
  id string Required
  
  Tactic ID
  
  name string Required
  
  Tactic name
  
  reference string Required
  
  Tactic reference
- technique array[object]
  
  Array containing information on the attack techniques (optional)
  Hide technique attributes Show technique attributes object
  
  id string Required
  
  Technique ID
  
  name string Required
  
  Technique name
  
  reference string Required
  
  Technique reference
  
  subtechnique array[object]
  
  Array containing more specific information on the attack technique.
  
  Hide subtechnique attributes Show subtechnique attributes object
  
  id string Required
  
  Subtechnique ID
  
  name string Required
  
  Subtechnique name
  
  reference string Required
  
  Subtechnique reference
throttle string | null

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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
version integer
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.
It is not incremented on each update. Compare this to the revision field.
Minimum value is 1.
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.
threshold object Required
Hide threshold attributes Show threshold attributes object
- cardinality array[object]
  
  The field on which the cardinality is applied.
  Hide cardinality attributes Show cardinality attributes object
  
  field string Required
  
  The field on which to calculate and compare the cardinality.
  
  value integer Required
  
  The threshold value from which an alert is generated based on unique number of values of cardinality.field.
  
  Minimum value is 0.
- field string | array[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.
  
  One of:
  string-1 string array-2 array[string]
- value integer Required
  
  The threshold value from which an alert is generated.
  
  Minimum value is 1.
type string Required Discriminator

Rule type

Value is threshold.
alert_suppression object

Defines alert suppression configuration.
Hide alert_suppression attribute Show alert_suppression attribute object
- duration object Required
  Hide duration attributes Show duration attributes object
  
  unit string Required
  
  Time unit
  
  Values are s, m, or h.
  
  value integer Required
  
  Minimum value is 1.
data_view_id string
filters array

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 array[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.
saved_id string

Kibana saved search used by the rule to create alerts.
language string

Values are kuery or lucene.

actions array[object]

Array defining the automated actions (notifications) taken when alerts are generated.
Hide actions attributes Show actions attributes object
- 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.
  Additional properties are allowed.
- frequency object
  
  The action frequency defines when the action runs (for example, only on rule execution or at specific time intervals).
  Hide frequency attributes Show frequency attributes object
  
  notifyWhen string Required
  
  Defines how often rules run actions.
  
  Values are onActiveAlert, onThrottleInterval, or 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 string | null Required
  
  Defines how often rule actions are taken.
  
  One of:
  string-1 string | null string-2 string | null
  
  Values are no_actions or 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.
  Additional properties are allowed.
- uuid string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
alias_purpose string

Values are savedObjectConversion or savedObjectImport.
alias_target_id string
author array[string]

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 Required

The rule’s description.

Minimum length is 1.
enabled boolean

Determines whether the rule is enabled. Defaults to true.
exceptions_list array[object]

Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.
Hide exceptions_list attributes Show exceptions_list attributes object
- id string(nonempty) Required
  
  ID of the exception container
  
  Minimum length is 1.
- list_id string(nonempty) Required
  
  List ID of the exception container
  
  Minimum length is 1.
- namespace_type string Required
  
  Determines the exceptions validity in rule's Kibana space
  
  Values are agnostic or single.
- type string Required
  
  The exception type
  
  Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.
false_positives array[string]

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.
from string(date-math)

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).
id string(uuid)

A dynamic unique identifier for the rule object. It is randomly generated when a rule is created and cannot be changed after that. It is always a UUID. It is unique within a given Kibana space. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have different object ids.
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).
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.
Hide investigation_fields attribute Show investigation_fields attribute object
- field_names array[string(nonempty)] Required
  
  A string that does not contain only whitespace characters
  
  At least 1 element. Minimum length of each is 1.
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).

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.

Minimum value is 1. Default value is 100.
meta object

Placeholder for metadata about the rule.

This field is overwritten when you save changes to the rule’s settings.

Additional properties are allowed.
name string Required

A human-readable name for the rule.

Minimum length is 1.
namespace string

Has no effect.
note string

Notes to help investigate alerts produced by the rule.
outcome string

Values are exactMatch, aliasMatch, or conflict.
output_index string Deprecated

(deprecated) Has no effect.
references array[string]

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.
related_integrations array[object]
Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:
- package: name of the package (required, unique id)
- version: version of the package (required, semver-compatible)
- integration: name of the integration of this package (optional, id within the package)
There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.
Hide related_integrations attributes Show related_integrations attributes object
- integration string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- package string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- version string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
required_fields array[object]

Elasticsearch fields and their types that need to be present for the rule to function.

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.

Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.
Hide required_fields attributes Show required_fields attributes object
- name string(nonempty) Required
  
  Name of an Elasticsearch field
  
  Minimum length is 1.
- type string(nonempty) Required
  
  Type of the Elasticsearch field
  
  Minimum length is 1.
response_actions array[object]
One of:
Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object
Hide attributes Show attributes

action_type_id string Required

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

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

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[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.
Hide attributes Show attributes

action_type_id string Required

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object

Hide attributes Show attributes

command string Required

Value is isolate.

comment string

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.
risk_score integer 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
Minimum value is 0, maximum value is 100.
risk_score_mapping array[object]

Overrides generated alerts' risk_score with a value from the source event
Hide risk_score_mapping attributes Show risk_score_mapping attributes object
- field string Required
  
  Source event field used to override the default risk_score.
- operator string Required
  
  Value is equals.
- 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
  Minimum value is 0, maximum value is 100.
- value string Required
rule_id string

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

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 string 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 are low, medium, high, or critical.
severity_mapping array[object]

Overrides generated alerts' severity with values from the source event
Hide severity_mapping attributes Show severity_mapping attributes object
- field string Required
  
  Source event field used to override the default severity.
- operator string Required
  
  Value is equals.
- severity string 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 are low, medium, high, or critical.
- value string Required
tags array[string]

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.
threat array[object]

Currently, only threats described using the MITRE ATT&CK™ framework are supported.
Hide threat attributes Show threat attributes object
- framework string Required
  
  Relevant attack framework
- tactic object Required
  
  Object containing information on the attack type
  Hide tactic attributes Show tactic attributes object
  
  id string Required
  
  Tactic ID
  
  name string Required
  
  Tactic name
  
  reference string Required
  
  Tactic reference
- technique array[object]
  
  Array containing information on the attack techniques (optional)
  Hide technique attributes Show technique attributes object
  
  id string Required
  
  Technique ID
  
  name string Required
  
  Technique name
  
  reference string Required
  
  Technique reference
  
  subtechnique array[object]
  
  Array containing more specific information on the attack technique.
  
  Hide subtechnique attributes Show subtechnique attributes object
  
  id string Required
  
  Subtechnique ID
  
  name string Required
  
  Subtechnique name
  
  reference string Required
  
  Subtechnique reference
throttle string | null

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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
version integer
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.
It is not incremented on each update. Compare this to the revision field.
Minimum value is 1.
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.
threat_index array[string] Required

Elasticsearch indices used to check which field values generate alerts.
threat_mapping array[object] Required
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 Example of Threat Match rule which uses both and and or logic.
At least 1 element.
Hide threat_mapping attribute Show threat_mapping attribute object
- entries array[object] Required
  Hide entries attributes Show entries attributes object
  
  field string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  type string Required
  
  Value is mapping.
  
  value string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
threat_query string Required

Query used to determine which fields in the Elasticsearch index are used for generating alerts.
type string Required Discriminator

Rule type

Value is threat_match.
alert_suppression object

Defines alert suppression configuration.
Hide alert_suppression attributes Show alert_suppression attributes object
- duration object
  Hide duration attributes Show duration attributes object
  
  unit string Required
  
  Time unit
  
  Values are s, m, or h.
  
  value integer Required
  
  Minimum value is 1.
- group_by array[string] Required
  
  At least 1 but not more than 3 elements.
- missing_fields_strategy string
  
  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 are doNotSuppress or suppress.
concurrent_searches integer

Minimum value is 1.
data_view_id string
filters array

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 array[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.
items_per_search integer

Minimum value is 1.
saved_id string

Kibana saved search used by the rule to create alerts.
threat_filters array

Query and filter context array used to filter documents from the Elasticsearch index containing the threat values
threat_indicator_path string

Defines the path to the threat indicator in the indicator documents (optional)
threat_language string

Values are kuery or lucene.
language string

Values are kuery or lucene.

actions array[object]

Array defining the automated actions (notifications) taken when alerts are generated.
Hide actions attributes Show actions attributes object
- 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.
  Additional properties are allowed.
- frequency object
  
  The action frequency defines when the action runs (for example, only on rule execution or at specific time intervals).
  Hide frequency attributes Show frequency attributes object
  
  notifyWhen string Required
  
  Defines how often rules run actions.
  
  Values are onActiveAlert, onThrottleInterval, or 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 string | null Required
  
  Defines how often rule actions are taken.
  
  One of:
  string-1 string | null string-2 string | null
  
  Values are no_actions or 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.
  Additional properties are allowed.
- uuid string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
alias_purpose string

Values are savedObjectConversion or savedObjectImport.
alias_target_id string
author array[string]

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 Required

The rule’s description.

Minimum length is 1.
enabled boolean

Determines whether the rule is enabled. Defaults to true.
exceptions_list array[object]

Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.
Hide exceptions_list attributes Show exceptions_list attributes object
- id string(nonempty) Required
  
  ID of the exception container
  
  Minimum length is 1.
- list_id string(nonempty) Required
  
  List ID of the exception container
  
  Minimum length is 1.
- namespace_type string Required
  
  Determines the exceptions validity in rule's Kibana space
  
  Values are agnostic or single.
- type string Required
  
  The exception type
  
  Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.
false_positives array[string]

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.
from string(date-math)

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).
id string(uuid)

A dynamic unique identifier for the rule object. It is randomly generated when a rule is created and cannot be changed after that. It is always a UUID. It is unique within a given Kibana space. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have different object ids.
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).
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.
Hide investigation_fields attribute Show investigation_fields attribute object
- field_names array[string(nonempty)] Required
  
  A string that does not contain only whitespace characters
  
  At least 1 element. Minimum length of each is 1.
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).

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.

Minimum value is 1. Default value is 100.
meta object

Placeholder for metadata about the rule.

This field is overwritten when you save changes to the rule’s settings.

Additional properties are allowed.
name string Required

A human-readable name for the rule.

Minimum length is 1.
namespace string

Has no effect.
note string

Notes to help investigate alerts produced by the rule.
outcome string

Values are exactMatch, aliasMatch, or conflict.
output_index string Deprecated

(deprecated) Has no effect.
references array[string]

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.
related_integrations array[object]
Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:
- package: name of the package (required, unique id)
- version: version of the package (required, semver-compatible)
- integration: name of the integration of this package (optional, id within the package)
There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.
Hide related_integrations attributes Show related_integrations attributes object
- integration string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- package string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- version string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
required_fields array[object]

Elasticsearch fields and their types that need to be present for the rule to function.

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.

Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.
Hide required_fields attributes Show required_fields attributes object
- name string(nonempty) Required
  
  Name of an Elasticsearch field
  
  Minimum length is 1.
- type string(nonempty) Required
  
  Type of the Elasticsearch field
  
  Minimum length is 1.
response_actions array[object]
One of:
Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object
Hide attributes Show attributes

action_type_id string Required

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

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

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[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.
Hide attributes Show attributes

action_type_id string Required

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object

Hide attributes Show attributes

command string Required

Value is isolate.

comment string

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.
risk_score integer 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
Minimum value is 0, maximum value is 100.
risk_score_mapping array[object]

Overrides generated alerts' risk_score with a value from the source event
Hide risk_score_mapping attributes Show risk_score_mapping attributes object
- field string Required
  
  Source event field used to override the default risk_score.
- operator string Required
  
  Value is equals.
- 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
  Minimum value is 0, maximum value is 100.
- value string Required
rule_id string

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

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 string 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 are low, medium, high, or critical.
severity_mapping array[object]

Overrides generated alerts' severity with values from the source event
Hide severity_mapping attributes Show severity_mapping attributes object
- field string Required
  
  Source event field used to override the default severity.
- operator string Required
  
  Value is equals.
- severity string 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 are low, medium, high, or critical.
- value string Required
tags array[string]

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.
threat array[object]

Currently, only threats described using the MITRE ATT&CK™ framework are supported.
Hide threat attributes Show threat attributes object
- framework string Required
  
  Relevant attack framework
- tactic object Required
  
  Object containing information on the attack type
  Hide tactic attributes Show tactic attributes object
  
  id string Required
  
  Tactic ID
  
  name string Required
  
  Tactic name
  
  reference string Required
  
  Tactic reference
- technique array[object]
  
  Array containing information on the attack techniques (optional)
  Hide technique attributes Show technique attributes object
  
  id string Required
  
  Technique ID
  
  name string Required
  
  Technique name
  
  reference string Required
  
  Technique reference
  
  subtechnique array[object]
  
  Array containing more specific information on the attack technique.
  
  Hide subtechnique attributes Show subtechnique attributes object
  
  id string Required
  
  Subtechnique ID
  
  name string Required
  
  Subtechnique name
  
  reference string Required
  
  Subtechnique reference
throttle string | null

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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
version integer
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.
It is not incremented on each update. Compare this to the revision field.
Minimum value is 1.
anomaly_threshold integer Required

Anomaly score threshold above which the rule creates an alert. Valid values are from 0 to 100.

Minimum value is 0.
machine_learning_job_id string | array[string] Required

Machine learning job ID(s) the rule monitors for anomaly scores.

One of:
string-1 string array-2 array[string]
type string Required Discriminator

Rule type

Value is machine_learning.
alert_suppression object

Defines alert suppression configuration.
Hide alert_suppression attributes Show alert_suppression attributes object
- duration object
  Hide duration attributes Show duration attributes object
  
  unit string Required
  
  Time unit
  
  Values are s, m, or h.
  
  value integer Required
  
  Minimum value is 1.
- group_by array[string] Required
  
  At least 1 but not more than 3 elements.
- missing_fields_strategy string
  
  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 are doNotSuppress or suppress.

actions array[object]

Array defining the automated actions (notifications) taken when alerts are generated.
Hide actions attributes Show actions attributes object
- 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.
  Additional properties are allowed.
- frequency object
  
  The action frequency defines when the action runs (for example, only on rule execution or at specific time intervals).
  Hide frequency attributes Show frequency attributes object
  
  notifyWhen string Required
  
  Defines how often rules run actions.
  
  Values are onActiveAlert, onThrottleInterval, or 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 string | null Required
  
  Defines how often rule actions are taken.
  
  One of:
  string-1 string | null string-2 string | null
  
  Values are no_actions or 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.
  Additional properties are allowed.
- uuid string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
alias_purpose string

Values are savedObjectConversion or savedObjectImport.
alias_target_id string
author array[string]

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 Required

The rule’s description.

Minimum length is 1.
enabled boolean

Determines whether the rule is enabled. Defaults to true.
exceptions_list array[object]

Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.
Hide exceptions_list attributes Show exceptions_list attributes object
- id string(nonempty) Required
  
  ID of the exception container
  
  Minimum length is 1.
- list_id string(nonempty) Required
  
  List ID of the exception container
  
  Minimum length is 1.
- namespace_type string Required
  
  Determines the exceptions validity in rule's Kibana space
  
  Values are agnostic or single.
- type string Required
  
  The exception type
  
  Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.
false_positives array[string]

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.
from string(date-math)

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).
id string(uuid)

A dynamic unique identifier for the rule object. It is randomly generated when a rule is created and cannot be changed after that. It is always a UUID. It is unique within a given Kibana space. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have different object ids.
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).
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.
Hide investigation_fields attribute Show investigation_fields attribute object
- field_names array[string(nonempty)] Required
  
  A string that does not contain only whitespace characters
  
  At least 1 element. Minimum length of each is 1.
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).

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.

Minimum value is 1. Default value is 100.
meta object

Placeholder for metadata about the rule.

This field is overwritten when you save changes to the rule’s settings.

Additional properties are allowed.
name string Required

A human-readable name for the rule.

Minimum length is 1.
namespace string

Has no effect.
note string

Notes to help investigate alerts produced by the rule.
outcome string

Values are exactMatch, aliasMatch, or conflict.
output_index string Deprecated

(deprecated) Has no effect.
references array[string]

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.
related_integrations array[object]
Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:
- package: name of the package (required, unique id)
- version: version of the package (required, semver-compatible)
- integration: name of the integration of this package (optional, id within the package)
There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.
Hide related_integrations attributes Show related_integrations attributes object
- integration string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- package string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- version string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
required_fields array[object]

Elasticsearch fields and their types that need to be present for the rule to function.

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.

Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.
Hide required_fields attributes Show required_fields attributes object
- name string(nonempty) Required
  
  Name of an Elasticsearch field
  
  Minimum length is 1.
- type string(nonempty) Required
  
  Type of the Elasticsearch field
  
  Minimum length is 1.
response_actions array[object]
One of:
Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object
Hide attributes Show attributes

action_type_id string Required

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

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

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[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.
Hide attributes Show attributes

action_type_id string Required

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object

Hide attributes Show attributes

command string Required

Value is isolate.

comment string

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.
risk_score integer 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
Minimum value is 0, maximum value is 100.
risk_score_mapping array[object]

Overrides generated alerts' risk_score with a value from the source event
Hide risk_score_mapping attributes Show risk_score_mapping attributes object
- field string Required
  
  Source event field used to override the default risk_score.
- operator string Required
  
  Value is equals.
- 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
  Minimum value is 0, maximum value is 100.
- value string Required
rule_id string

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

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 string 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 are low, medium, high, or critical.
severity_mapping array[object]

Overrides generated alerts' severity with values from the source event
Hide severity_mapping attributes Show severity_mapping attributes object
- field string Required
  
  Source event field used to override the default severity.
- operator string Required
  
  Value is equals.
- severity string 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 are low, medium, high, or critical.
- value string Required
tags array[string]

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.
threat array[object]

Currently, only threats described using the MITRE ATT&CK™ framework are supported.
Hide threat attributes Show threat attributes object
- framework string Required
  
  Relevant attack framework
- tactic object Required
  
  Object containing information on the attack type
  Hide tactic attributes Show tactic attributes object
  
  id string Required
  
  Tactic ID
  
  name string Required
  
  Tactic name
  
  reference string Required
  
  Tactic reference
- technique array[object]
  
  Array containing information on the attack techniques (optional)
  Hide technique attributes Show technique attributes object
  
  id string Required
  
  Technique ID
  
  name string Required
  
  Technique name
  
  reference string Required
  
  Technique reference
  
  subtechnique array[object]
  
  Array containing more specific information on the attack technique.
  
  Hide subtechnique attributes Show subtechnique attributes object
  
  id string Required
  
  Subtechnique ID
  
  name string Required
  
  Subtechnique name
  
  reference string Required
  
  Subtechnique reference
throttle string | null

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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
version integer
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.
It is not incremented on each update. Compare this to the revision field.
Minimum value is 1.
history_window_start string(nonempty) Required

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.

Minimum length is 1.
new_terms_fields array[string] Required

Fields to monitor for new values.

At least 1 but not more than 3 elements.
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.
type string Required Discriminator

Rule type

Value is new_terms.
alert_suppression object

Defines alert suppression configuration.
Hide alert_suppression attributes Show alert_suppression attributes object
- duration object
  Hide duration attributes Show duration attributes object
  
  unit string Required
  
  Time unit
  
  Values are s, m, or h.
  
  value integer Required
  
  Minimum value is 1.
- group_by array[string] Required
  
  At least 1 but not more than 3 elements.
- missing_fields_strategy string
  
  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 are doNotSuppress or suppress.
data_view_id string
filters array

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 array[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.
language string

Values are kuery or lucene.

actions array[object]

Array defining the automated actions (notifications) taken when alerts are generated.
Hide actions attributes Show actions attributes object
- 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.
  Additional properties are allowed.
- frequency object
  
  The action frequency defines when the action runs (for example, only on rule execution or at specific time intervals).
  Hide frequency attributes Show frequency attributes object
  
  notifyWhen string Required
  
  Defines how often rules run actions.
  
  Values are onActiveAlert, onThrottleInterval, or 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 string | null Required
  
  Defines how often rule actions are taken.
  
  One of:
  string-1 string | null string-2 string | null
  
  Values are no_actions or 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.
  Additional properties are allowed.
- uuid string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
alias_purpose string

Values are savedObjectConversion or savedObjectImport.
alias_target_id string
author array[string]

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 Required

The rule’s description.

Minimum length is 1.
enabled boolean

Determines whether the rule is enabled. Defaults to true.
exceptions_list array[object]

Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.
Hide exceptions_list attributes Show exceptions_list attributes object
- id string(nonempty) Required
  
  ID of the exception container
  
  Minimum length is 1.
- list_id string(nonempty) Required
  
  List ID of the exception container
  
  Minimum length is 1.
- namespace_type string Required
  
  Determines the exceptions validity in rule's Kibana space
  
  Values are agnostic or single.
- type string Required
  
  The exception type
  
  Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.
false_positives array[string]

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.
from string(date-math)

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).
id string(uuid)

A dynamic unique identifier for the rule object. It is randomly generated when a rule is created and cannot be changed after that. It is always a UUID. It is unique within a given Kibana space. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have different object ids.
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).
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.
Hide investigation_fields attribute Show investigation_fields attribute object
- field_names array[string(nonempty)] Required
  
  A string that does not contain only whitespace characters
  
  At least 1 element. Minimum length of each is 1.
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).

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.

Minimum value is 1. Default value is 100.
meta object

Placeholder for metadata about the rule.

This field is overwritten when you save changes to the rule’s settings.

Additional properties are allowed.
name string Required

A human-readable name for the rule.

Minimum length is 1.
namespace string

Has no effect.
note string

Notes to help investigate alerts produced by the rule.
outcome string

Values are exactMatch, aliasMatch, or conflict.
output_index string Deprecated

(deprecated) Has no effect.
references array[string]

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.
related_integrations array[object]
Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:
- package: name of the package (required, unique id)
- version: version of the package (required, semver-compatible)
- integration: name of the integration of this package (optional, id within the package)
There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.
Hide related_integrations attributes Show related_integrations attributes object
- integration string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- package string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- version string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
required_fields array[object]

Elasticsearch fields and their types that need to be present for the rule to function.

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.

Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.
Hide required_fields attributes Show required_fields attributes object
- name string(nonempty) Required
  
  Name of an Elasticsearch field
  
  Minimum length is 1.
- type string(nonempty) Required
  
  Type of the Elasticsearch field
  
  Minimum length is 1.
response_actions array[object]
One of:
Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object
Hide attributes Show attributes

action_type_id string Required

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

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

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[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.
Hide attributes Show attributes

action_type_id string Required

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object

Hide attributes Show attributes

command string Required

Value is isolate.

comment string

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.
risk_score integer 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
Minimum value is 0, maximum value is 100.
risk_score_mapping array[object]

Overrides generated alerts' risk_score with a value from the source event
Hide risk_score_mapping attributes Show risk_score_mapping attributes object
- field string Required
  
  Source event field used to override the default risk_score.
- operator string Required
  
  Value is equals.
- 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
  Minimum value is 0, maximum value is 100.
- value string Required
rule_id string

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

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 string 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 are low, medium, high, or critical.
severity_mapping array[object]

Overrides generated alerts' severity with values from the source event
Hide severity_mapping attributes Show severity_mapping attributes object
- field string Required
  
  Source event field used to override the default severity.
- operator string Required
  
  Value is equals.
- severity string 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 are low, medium, high, or critical.
- value string Required
tags array[string]

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.
threat array[object]

Currently, only threats described using the MITRE ATT&CK™ framework are supported.
Hide threat attributes Show threat attributes object
- framework string Required
  
  Relevant attack framework
- tactic object Required
  
  Object containing information on the attack type
  Hide tactic attributes Show tactic attributes object
  
  id string Required
  
  Tactic ID
  
  name string Required
  
  Tactic name
  
  reference string Required
  
  Tactic reference
- technique array[object]
  
  Array containing information on the attack techniques (optional)
  Hide technique attributes Show technique attributes object
  
  id string Required
  
  Technique ID
  
  name string Required
  
  Technique name
  
  reference string Required
  
  Technique reference
  
  subtechnique array[object]
  
  Array containing more specific information on the attack technique.
  
  Hide subtechnique attributes Show subtechnique attributes object
  
  id string Required
  
  Subtechnique ID
  
  name string Required
  
  Subtechnique name
  
  reference string Required
  
  Subtechnique reference
throttle string | null

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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
version integer
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.
It is not incremented on each update. Compare this to the revision field.
Minimum value is 1.
alert_suppression object

Defines alert suppression configuration.
Hide alert_suppression attributes Show alert_suppression attributes object
- duration object
  Hide duration attributes Show duration attributes object
  
  unit string Required
  
  Time unit
  
  Values are s, m, or h.
  
  value integer Required
  
  Minimum value is 1.
- group_by array[string] Required
  
  At least 1 but not more than 3 elements.
- missing_fields_strategy string
  
  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 are doNotSuppress or suppress.
language string Required

Value is esql.
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.
type string Required Discriminator

Rule type

Value is esql.

Responses

200 application/json

Indicates a successful call.
Any of:
Security_Detections_API_EqlRuleResponseFields object Security_Detections_API_QueryRuleResponseFields object Security_Detections_API_SavedQueryRuleResponseFields object Security_Detections_API_ThresholdRuleResponseFields object Security_Detections_API_ThreatMatchRuleResponseFields object Security_Detections_API_MachineLearningRuleResponseFields object Security_Detections_API_NewTermsRuleResponseFields object Security_Detections_API_EsqlRuleResponseFields object
Hide attributes Show attributes

actions array[object] Required

Array defining the automated actions (notifications) taken when alerts are generated.

Hide actions attributes Show actions attributes object

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.

Additional properties are allowed.

frequency object

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

Hide frequency attributes Show frequency attributes object

notifyWhen string Required

Defines how often rules run actions.

Values are onActiveAlert, onThrottleInterval, or 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 string | null Required

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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.

Additional properties are allowed.

uuid string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

alias_purpose string

Values are savedObjectConversion or savedObjectImport.

alias_target_id string

author array[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 Required

The rule’s description.

Minimum length is 1.

enabled boolean Required

Determines whether the rule is enabled. Defaults to true.

exceptions_list array[object] Required

Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.

Hide exceptions_list attributes Show exceptions_list attributes object

id string(nonempty) Required

ID of the exception container

Minimum length is 1.

list_id string(nonempty) Required

List ID of the exception container

Minimum length is 1.

namespace_type string Required

Determines the exceptions validity in rule's Kibana space

Values are agnostic or single.

type string Required

The exception type

Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.

false_positives array[string] Required

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.

from string(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.

Hide investigation_fields attribute Show investigation_fields attribute object

field_names array[string(nonempty)] Required

A string that does not contain only whitespace characters

At least 1 element. Minimum length of each is 1.

license string

The rule's license.

max_signals integer Required

Maximum number of alerts the rule can create during a single run (the rule’s Max alerts per run advanced setting value).

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.

Minimum value is 1. Default value is 100.

meta object

Placeholder for metadata about the rule.

This field is overwritten when you save changes to the rule’s settings.

Additional properties are allowed.

name string Required

A human-readable name for the rule.

Minimum length is 1.

namespace string

Has no effect.

note string

Notes to help investigate alerts produced by the rule.

outcome string

Values are exactMatch, aliasMatch, or conflict.

output_index string Deprecated

(deprecated) Has no effect.

references array[string] Required

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.

related_integrations array[object] Required

Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:

package: name of the package (required, unique id)

version: version of the package (required, semver-compatible)

integration: name of the integration of this package (optional, id within the package)

There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.

Hide related_integrations attributes Show related_integrations attributes object

integration string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

package string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

version string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

required_fields array[object] Required

Elasticsearch fields and their types that need to be present for the rule to function.

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.

Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.

Hide required_fields attributes Show required_fields attributes object

name string(nonempty) Required

Name of an Elasticsearch field

Minimum length is 1.

type string(nonempty) Required

Type of the Elasticsearch field

Minimum length is 1.

response_actions array[object]

One of:
Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object

Hide attributes Show attributes

action_type_id string Required

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

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

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[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.

Hide attributes Show attributes

action_type_id string Required

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object

Hide attributes Show attributes

command string Required

Value is isolate.

comment string

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.

risk_score integer 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

Minimum value is 0, maximum value is 100.

risk_score_mapping array[object] Required

Overrides generated alerts' risk_score with a value from the source event

Hide risk_score_mapping attributes Show risk_score_mapping attributes object

field string Required

Source event field used to override the default risk_score.

operator string Required

Value is equals.

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

Minimum value is 0, maximum value is 100.

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 string 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 are low, medium, high, or critical.

severity_mapping array[object] Required

Overrides generated alerts' severity with values from the source event

Hide severity_mapping attributes Show severity_mapping attributes object

field string Required

Source event field used to override the default severity.

operator string Required

Value is equals.

severity string 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 are low, medium, high, or critical.

value string Required

tags array[string] Required

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.

threat array[object] Required

Currently, only threats described using the MITRE ATT&CK™ framework are supported.

Hide threat attributes Show threat attributes object

framework string Required

Relevant attack framework

tactic object Required

Object containing information on the attack type

Hide tactic attributes Show tactic attributes object

id string Required

Tactic ID

name string Required

Tactic name

reference string Required

Tactic reference

technique array[object]

Array containing information on the attack techniques (optional)

Hide technique attributes Show technique attributes object

id string Required

Technique ID

name string Required

Technique name

reference string Required

Technique reference

subtechnique array[object]

Array containing more specific information on the attack technique.

Hide subtechnique attributes Show subtechnique attributes object

id string Required

Subtechnique ID

name string Required

Subtechnique name

reference string Required

Subtechnique reference

throttle string | null

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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 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.

It is not incremented on each update. Compare this to the revision field.

Minimum value is 1.

created_at string(date-time) Required

created_by string Required

execution_summary object

Summary of the last execution of a rule.

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

Hide execution_summary attribute Show execution_summary attribute object

last_execution object Required

Hide last_execution attributes Show last_execution attributes object

date string(date-time) Required

Date of the last execution

message string Required

metrics object Required

Hide metrics attributes Show metrics attributes object

execution_gap_duration_s integer

Duration in seconds of execution gap

Minimum value is 0.

frozen_indices_queried_count integer

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

Minimum value is 0.

gap_range object

Range of the execution gap

Hide gap_range attributes Show gap_range attributes object

gte string Required

Start date of the execution gap

lte string Required

End date of the execution gap

total_enrichment_duration_ms integer

Total time spent enriching documents during current rule execution cycle

Minimum value is 0.

total_indexing_duration_ms integer

Total time spent indexing documents during current rule execution cycle

Minimum value is 0.

total_search_duration_ms integer

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

Minimum value is 0.

status string Required

Status of the last execution

Values are going to run, running, partial failure, failed, or succeeded.

status_order integer Required

id string(uuid) Required

A dynamic unique identifier for the rule object. It is randomly generated when a rule is created and cannot be changed after that. It is always a UUID. It is unique within a given Kibana space. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have different object ids.

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

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.

Minimum value is 0.

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 object 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:
Security_Detections_API_ExternalRuleSource object Security_Detections_API_InternalRuleSource object

Type of rule source for externally sourced rules, i.e. rules that have an external source, such as the Elastic Prebuilt rules repo.

Hide attributes Show attributes

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

type string Required Discriminator

Value is external.

updated_at string(date-time) Required

updated_by string Required

language string Required

Query language to use

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

type string Required Discriminator

Rule type

Value is eql.

alert_suppression object

Defines alert suppression configuration.

Hide alert_suppression attributes Show alert_suppression attributes object

duration object

Hide duration attributes Show duration attributes object

unit string Required

Time unit

Values are s, m, or h.

value integer Required

Minimum value is 1.

group_by array[string] Required

At least 1 but not more than 3 elements.

missing_fields_strategy string

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 are doNotSuppress or suppress.

data_view_id string

event_category_override string

filters array

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

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.
Hide attributes Show attributes

actions array[object] Required

Array defining the automated actions (notifications) taken when alerts are generated.

Hide actions attributes Show actions attributes object

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.

Additional properties are allowed.

frequency object

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

Hide frequency attributes Show frequency attributes object

notifyWhen string Required

Defines how often rules run actions.

Values are onActiveAlert, onThrottleInterval, or 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 string | null Required

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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.

Additional properties are allowed.

uuid string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

alias_purpose string

Values are savedObjectConversion or savedObjectImport.

alias_target_id string

author array[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 Required

The rule’s description.

Minimum length is 1.

enabled boolean Required

Determines whether the rule is enabled. Defaults to true.

exceptions_list array[object] Required

Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.

Hide exceptions_list attributes Show exceptions_list attributes object

id string(nonempty) Required

ID of the exception container

Minimum length is 1.

list_id string(nonempty) Required

List ID of the exception container

Minimum length is 1.

namespace_type string Required

Determines the exceptions validity in rule's Kibana space

Values are agnostic or single.

type string Required

The exception type

Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.

false_positives array[string] Required

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.

from string(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.

Hide investigation_fields attribute Show investigation_fields attribute object

field_names array[string(nonempty)] Required

A string that does not contain only whitespace characters

At least 1 element. Minimum length of each is 1.

license string

The rule's license.

max_signals integer Required

Maximum number of alerts the rule can create during a single run (the rule’s Max alerts per run advanced setting value).

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.

Minimum value is 1. Default value is 100.

meta object

Placeholder for metadata about the rule.

This field is overwritten when you save changes to the rule’s settings.

Additional properties are allowed.

name string Required

A human-readable name for the rule.

Minimum length is 1.

namespace string

Has no effect.

note string

Notes to help investigate alerts produced by the rule.

outcome string

Values are exactMatch, aliasMatch, or conflict.

output_index string Deprecated

(deprecated) Has no effect.

references array[string] Required

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.

related_integrations array[object] Required

Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:

package: name of the package (required, unique id)

version: version of the package (required, semver-compatible)

integration: name of the integration of this package (optional, id within the package)

There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.

Hide related_integrations attributes Show related_integrations attributes object

integration string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

package string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

version string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

required_fields array[object] Required

Elasticsearch fields and their types that need to be present for the rule to function.

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.

Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.

Hide required_fields attributes Show required_fields attributes object

name string(nonempty) Required

Name of an Elasticsearch field

Minimum length is 1.

type string(nonempty) Required

Type of the Elasticsearch field

Minimum length is 1.

response_actions array[object]

One of:
Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object

Hide attributes Show attributes

action_type_id string Required

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

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

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[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.

Hide attributes Show attributes

action_type_id string Required

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object

Hide attributes Show attributes

command string Required

Value is isolate.

comment string

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.

risk_score integer 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

Minimum value is 0, maximum value is 100.

risk_score_mapping array[object] Required

Overrides generated alerts' risk_score with a value from the source event

Hide risk_score_mapping attributes Show risk_score_mapping attributes object

field string Required

Source event field used to override the default risk_score.

operator string Required

Value is equals.

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

Minimum value is 0, maximum value is 100.

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 string 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 are low, medium, high, or critical.

severity_mapping array[object] Required

Overrides generated alerts' severity with values from the source event

Hide severity_mapping attributes Show severity_mapping attributes object

field string Required

Source event field used to override the default severity.

operator string Required

Value is equals.

severity string 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 are low, medium, high, or critical.

value string Required

tags array[string] Required

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.

threat array[object] Required

Currently, only threats described using the MITRE ATT&CK™ framework are supported.

Hide threat attributes Show threat attributes object

framework string Required

Relevant attack framework

tactic object Required

Object containing information on the attack type

Hide tactic attributes Show tactic attributes object

id string Required

Tactic ID

name string Required

Tactic name

reference string Required

Tactic reference

technique array[object]

Array containing information on the attack techniques (optional)

Hide technique attributes Show technique attributes object

id string Required

Technique ID

name string Required

Technique name

reference string Required

Technique reference

subtechnique array[object]

Array containing more specific information on the attack technique.

Hide subtechnique attributes Show subtechnique attributes object

id string Required

Subtechnique ID

name string Required

Subtechnique name

reference string Required

Subtechnique reference

throttle string | null

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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 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.

It is not incremented on each update. Compare this to the revision field.

Minimum value is 1.

created_at string(date-time) Required

created_by string Required

execution_summary object

Summary of the last execution of a rule.

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

Hide execution_summary attribute Show execution_summary attribute object

last_execution object Required

Hide last_execution attributes Show last_execution attributes object

date string(date-time) Required

Date of the last execution

message string Required

metrics object Required

Hide metrics attributes Show metrics attributes object

execution_gap_duration_s integer

Duration in seconds of execution gap

Minimum value is 0.

frozen_indices_queried_count integer

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

Minimum value is 0.

gap_range object

Range of the execution gap

Hide gap_range attributes Show gap_range attributes object

gte string Required

Start date of the execution gap

lte string Required

End date of the execution gap

total_enrichment_duration_ms integer

Total time spent enriching documents during current rule execution cycle

Minimum value is 0.

total_indexing_duration_ms integer

Total time spent indexing documents during current rule execution cycle

Minimum value is 0.

total_search_duration_ms integer

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

Minimum value is 0.

status string Required

Status of the last execution

Values are going to run, running, partial failure, failed, or succeeded.

status_order integer Required

id string(uuid) Required

A dynamic unique identifier for the rule object. It is randomly generated when a rule is created and cannot be changed after that. It is always a UUID. It is unique within a given Kibana space. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have different object ids.

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

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.

Minimum value is 0.

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 object 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:
Security_Detections_API_ExternalRuleSource object Security_Detections_API_InternalRuleSource object

Type of rule source for externally sourced rules, i.e. rules that have an external source, such as the Elastic Prebuilt rules repo.

Hide attributes Show attributes

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

type string Required Discriminator

Value is external.

updated_at string(date-time) Required

updated_by string Required

type string Required Discriminator

Rule type

Value is query.

alert_suppression object

Defines alert suppression configuration.

Hide alert_suppression attributes Show alert_suppression attributes object

duration object

Hide duration attributes Show duration attributes object

unit string Required

Time unit

Values are s, m, or h.

value integer Required

Minimum value is 1.

group_by array[string] Required

At least 1 but not more than 3 elements.

missing_fields_strategy string

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 are doNotSuppress or suppress.

data_view_id string

filters array

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

saved_id string

Kibana saved search used by the rule to create alerts.

language string Required

Values are kuery or lucene.

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.
Hide attributes Show attributes

actions array[object] Required

Array defining the automated actions (notifications) taken when alerts are generated.

Hide actions attributes Show actions attributes object

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.

Additional properties are allowed.

frequency object

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

Hide frequency attributes Show frequency attributes object

notifyWhen string Required

Defines how often rules run actions.

Values are onActiveAlert, onThrottleInterval, or 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 string | null Required

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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.

Additional properties are allowed.

uuid string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

alias_purpose string

Values are savedObjectConversion or savedObjectImport.

alias_target_id string

author array[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 Required

The rule’s description.

Minimum length is 1.

enabled boolean Required

Determines whether the rule is enabled. Defaults to true.

exceptions_list array[object] Required

Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.

Hide exceptions_list attributes Show exceptions_list attributes object

id string(nonempty) Required

ID of the exception container

Minimum length is 1.

list_id string(nonempty) Required

List ID of the exception container

Minimum length is 1.

namespace_type string Required

Determines the exceptions validity in rule's Kibana space

Values are agnostic or single.

type string Required

The exception type

Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.

false_positives array[string] Required

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.

from string(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.

Hide investigation_fields attribute Show investigation_fields attribute object

field_names array[string(nonempty)] Required

A string that does not contain only whitespace characters

At least 1 element. Minimum length of each is 1.

license string

The rule's license.

max_signals integer Required

Maximum number of alerts the rule can create during a single run (the rule’s Max alerts per run advanced setting value).

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.

Minimum value is 1. Default value is 100.

meta object

Placeholder for metadata about the rule.

This field is overwritten when you save changes to the rule’s settings.

Additional properties are allowed.

name string Required

A human-readable name for the rule.

Minimum length is 1.

namespace string

Has no effect.

note string

Notes to help investigate alerts produced by the rule.

outcome string

Values are exactMatch, aliasMatch, or conflict.

output_index string Deprecated

(deprecated) Has no effect.

references array[string] Required

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.

related_integrations array[object] Required

Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:

package: name of the package (required, unique id)

version: version of the package (required, semver-compatible)

integration: name of the integration of this package (optional, id within the package)

There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.

Hide related_integrations attributes Show related_integrations attributes object

integration string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

package string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

version string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

required_fields array[object] Required

Elasticsearch fields and their types that need to be present for the rule to function.

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.

Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.

Hide required_fields attributes Show required_fields attributes object

name string(nonempty) Required

Name of an Elasticsearch field

Minimum length is 1.

type string(nonempty) Required

Type of the Elasticsearch field

Minimum length is 1.

response_actions array[object]

One of:
Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object

Hide attributes Show attributes

action_type_id string Required

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

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

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[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.

Hide attributes Show attributes

action_type_id string Required

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object

Hide attributes Show attributes

command string Required

Value is isolate.

comment string

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.

risk_score integer 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

Minimum value is 0, maximum value is 100.

risk_score_mapping array[object] Required

Overrides generated alerts' risk_score with a value from the source event

Hide risk_score_mapping attributes Show risk_score_mapping attributes object

field string Required

Source event field used to override the default risk_score.

operator string Required

Value is equals.

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

Minimum value is 0, maximum value is 100.

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 string 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 are low, medium, high, or critical.

severity_mapping array[object] Required

Overrides generated alerts' severity with values from the source event

Hide severity_mapping attributes Show severity_mapping attributes object

field string Required

Source event field used to override the default severity.

operator string Required

Value is equals.

severity string 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 are low, medium, high, or critical.

value string Required

tags array[string] Required

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.

threat array[object] Required

Currently, only threats described using the MITRE ATT&CK™ framework are supported.

Hide threat attributes Show threat attributes object

framework string Required

Relevant attack framework

tactic object Required

Object containing information on the attack type

Hide tactic attributes Show tactic attributes object

id string Required

Tactic ID

name string Required

Tactic name

reference string Required

Tactic reference

technique array[object]

Array containing information on the attack techniques (optional)

Hide technique attributes Show technique attributes object

id string Required

Technique ID

name string Required

Technique name

reference string Required

Technique reference

subtechnique array[object]

Array containing more specific information on the attack technique.

Hide subtechnique attributes Show subtechnique attributes object

id string Required

Subtechnique ID

name string Required

Subtechnique name

reference string Required

Subtechnique reference

throttle string | null

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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 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.

It is not incremented on each update. Compare this to the revision field.

Minimum value is 1.

created_at string(date-time) Required

created_by string Required

execution_summary object

Summary of the last execution of a rule.

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

Hide execution_summary attribute Show execution_summary attribute object

last_execution object Required

Hide last_execution attributes Show last_execution attributes object

date string(date-time) Required

Date of the last execution

message string Required

metrics object Required

Hide metrics attributes Show metrics attributes object

execution_gap_duration_s integer

Duration in seconds of execution gap

Minimum value is 0.

frozen_indices_queried_count integer

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

Minimum value is 0.

gap_range object

Range of the execution gap

Hide gap_range attributes Show gap_range attributes object

gte string Required

Start date of the execution gap

lte string Required

End date of the execution gap

total_enrichment_duration_ms integer

Total time spent enriching documents during current rule execution cycle

Minimum value is 0.

total_indexing_duration_ms integer

Total time spent indexing documents during current rule execution cycle

Minimum value is 0.

total_search_duration_ms integer

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

Minimum value is 0.

status string Required

Status of the last execution

Values are going to run, running, partial failure, failed, or succeeded.

status_order integer Required

id string(uuid) Required

A dynamic unique identifier for the rule object. It is randomly generated when a rule is created and cannot be changed after that. It is always a UUID. It is unique within a given Kibana space. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have different object ids.

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

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.

Minimum value is 0.

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 object 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:
Security_Detections_API_ExternalRuleSource object Security_Detections_API_InternalRuleSource object

Type of rule source for externally sourced rules, i.e. rules that have an external source, such as the Elastic Prebuilt rules repo.

Hide attributes Show attributes

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

type string Required Discriminator

Value is external.

updated_at string(date-time) Required

updated_by string Required

saved_id string Required

Kibana saved search used by the rule to create alerts.

type string Required Discriminator

Rule type

Value is saved_query.

alert_suppression object

Defines alert suppression configuration.

Hide alert_suppression attributes Show alert_suppression attributes object

duration object

Hide duration attributes Show duration attributes object

unit string Required

Time unit

Values are s, m, or h.

value integer Required

Minimum value is 1.

group_by array[string] Required

At least 1 but not more than 3 elements.

missing_fields_strategy string

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 are doNotSuppress or suppress.

data_view_id string

filters array

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

query string

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.

language string Required

Values are kuery or lucene.
Hide attributes Show attributes

actions array[object] Required

Array defining the automated actions (notifications) taken when alerts are generated.

Hide actions attributes Show actions attributes object

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.

Additional properties are allowed.

frequency object

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

Hide frequency attributes Show frequency attributes object

notifyWhen string Required

Defines how often rules run actions.

Values are onActiveAlert, onThrottleInterval, or 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 string | null Required

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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.

Additional properties are allowed.

uuid string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

alias_purpose string

Values are savedObjectConversion or savedObjectImport.

alias_target_id string

author array[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 Required

The rule’s description.

Minimum length is 1.

enabled boolean Required

Determines whether the rule is enabled. Defaults to true.

exceptions_list array[object] Required

Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.

Hide exceptions_list attributes Show exceptions_list attributes object

id string(nonempty) Required

ID of the exception container

Minimum length is 1.

list_id string(nonempty) Required

List ID of the exception container

Minimum length is 1.

namespace_type string Required

Determines the exceptions validity in rule's Kibana space

Values are agnostic or single.

type string Required

The exception type

Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.

false_positives array[string] Required

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.

from string(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.

Hide investigation_fields attribute Show investigation_fields attribute object

field_names array[string(nonempty)] Required

A string that does not contain only whitespace characters

At least 1 element. Minimum length of each is 1.

license string

The rule's license.

max_signals integer Required

Maximum number of alerts the rule can create during a single run (the rule’s Max alerts per run advanced setting value).

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.

Minimum value is 1. Default value is 100.

meta object

Placeholder for metadata about the rule.

This field is overwritten when you save changes to the rule’s settings.

Additional properties are allowed.

name string Required

A human-readable name for the rule.

Minimum length is 1.

namespace string

Has no effect.

note string

Notes to help investigate alerts produced by the rule.

outcome string

Values are exactMatch, aliasMatch, or conflict.

output_index string Deprecated

(deprecated) Has no effect.

references array[string] Required

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.

related_integrations array[object] Required

Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:

package: name of the package (required, unique id)

version: version of the package (required, semver-compatible)

integration: name of the integration of this package (optional, id within the package)

There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.

Hide related_integrations attributes Show related_integrations attributes object

integration string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

package string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

version string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

required_fields array[object] Required

Elasticsearch fields and their types that need to be present for the rule to function.

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.

Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.

Hide required_fields attributes Show required_fields attributes object

name string(nonempty) Required

Name of an Elasticsearch field

Minimum length is 1.

type string(nonempty) Required

Type of the Elasticsearch field

Minimum length is 1.

response_actions array[object]

One of:
Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object

Hide attributes Show attributes

action_type_id string Required

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

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

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[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.

Hide attributes Show attributes

action_type_id string Required

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object

Hide attributes Show attributes

command string Required

Value is isolate.

comment string

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.

risk_score integer 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

Minimum value is 0, maximum value is 100.

risk_score_mapping array[object] Required

Overrides generated alerts' risk_score with a value from the source event

Hide risk_score_mapping attributes Show risk_score_mapping attributes object

field string Required

Source event field used to override the default risk_score.

operator string Required

Value is equals.

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

Minimum value is 0, maximum value is 100.

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 string 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 are low, medium, high, or critical.

severity_mapping array[object] Required

Overrides generated alerts' severity with values from the source event

Hide severity_mapping attributes Show severity_mapping attributes object

field string Required

Source event field used to override the default severity.

operator string Required

Value is equals.

severity string 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 are low, medium, high, or critical.

value string Required

tags array[string] Required

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.

threat array[object] Required

Currently, only threats described using the MITRE ATT&CK™ framework are supported.

Hide threat attributes Show threat attributes object

framework string Required

Relevant attack framework

tactic object Required

Object containing information on the attack type

Hide tactic attributes Show tactic attributes object

id string Required

Tactic ID

name string Required

Tactic name

reference string Required

Tactic reference

technique array[object]

Array containing information on the attack techniques (optional)

Hide technique attributes Show technique attributes object

id string Required

Technique ID

name string Required

Technique name

reference string Required

Technique reference

subtechnique array[object]

Array containing more specific information on the attack technique.

Hide subtechnique attributes Show subtechnique attributes object

id string Required

Subtechnique ID

name string Required

Subtechnique name

reference string Required

Subtechnique reference

throttle string | null

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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 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.

It is not incremented on each update. Compare this to the revision field.

Minimum value is 1.

created_at string(date-time) Required

created_by string Required

execution_summary object

Summary of the last execution of a rule.

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

Hide execution_summary attribute Show execution_summary attribute object

last_execution object Required

Hide last_execution attributes Show last_execution attributes object

date string(date-time) Required

Date of the last execution

message string Required

metrics object Required

Hide metrics attributes Show metrics attributes object

execution_gap_duration_s integer

Duration in seconds of execution gap

Minimum value is 0.

frozen_indices_queried_count integer

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

Minimum value is 0.

gap_range object

Range of the execution gap

Hide gap_range attributes Show gap_range attributes object

gte string Required

Start date of the execution gap

lte string Required

End date of the execution gap

total_enrichment_duration_ms integer

Total time spent enriching documents during current rule execution cycle

Minimum value is 0.

total_indexing_duration_ms integer

Total time spent indexing documents during current rule execution cycle

Minimum value is 0.

total_search_duration_ms integer

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

Minimum value is 0.

status string Required

Status of the last execution

Values are going to run, running, partial failure, failed, or succeeded.

status_order integer Required

id string(uuid) Required

A dynamic unique identifier for the rule object. It is randomly generated when a rule is created and cannot be changed after that. It is always a UUID. It is unique within a given Kibana space. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have different object ids.

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

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.

Minimum value is 0.

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 object 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:
Security_Detections_API_ExternalRuleSource object Security_Detections_API_InternalRuleSource object

Type of rule source for externally sourced rules, i.e. rules that have an external source, such as the Elastic Prebuilt rules repo.

Hide attributes Show attributes

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

type string Required Discriminator

Value is external.

updated_at string(date-time) Required

updated_by string Required

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.

threshold object Required

Hide threshold attributes Show threshold attributes object

cardinality array[object]

The field on which the cardinality is applied.

Hide cardinality attributes Show cardinality attributes object

field string Required

The field on which to calculate and compare the cardinality.

value integer Required

The threshold value from which an alert is generated based on unique number of values of cardinality.field.

Minimum value is 0.

field string | array[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.

One of:
string-1 string array-2 array[string]

value integer Required

The threshold value from which an alert is generated.

Minimum value is 1.

type string Required Discriminator

Rule type

Value is threshold.

alert_suppression object

Defines alert suppression configuration.

Hide alert_suppression attribute Show alert_suppression attribute object

duration object Required

Hide duration attributes Show duration attributes object

unit string Required

Time unit

Values are s, m, or h.

value integer Required

Minimum value is 1.

data_view_id string

filters array

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

saved_id string

Kibana saved search used by the rule to create alerts.

language string Required

Values are kuery or lucene.
Hide attributes Show attributes

actions array[object] Required

Array defining the automated actions (notifications) taken when alerts are generated.

Hide actions attributes Show actions attributes object

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.

Additional properties are allowed.

frequency object

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

Hide frequency attributes Show frequency attributes object

notifyWhen string Required

Defines how often rules run actions.

Values are onActiveAlert, onThrottleInterval, or 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 string | null Required

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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.

Additional properties are allowed.

uuid string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

alias_purpose string

Values are savedObjectConversion or savedObjectImport.

alias_target_id string

author array[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 Required

The rule’s description.

Minimum length is 1.

enabled boolean Required

Determines whether the rule is enabled. Defaults to true.

exceptions_list array[object] Required

Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.

Hide exceptions_list attributes Show exceptions_list attributes object

id string(nonempty) Required

ID of the exception container

Minimum length is 1.

list_id string(nonempty) Required

List ID of the exception container

Minimum length is 1.

namespace_type string Required

Determines the exceptions validity in rule's Kibana space

Values are agnostic or single.

type string Required

The exception type

Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.

false_positives array[string] Required

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.

from string(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.

Hide investigation_fields attribute Show investigation_fields attribute object

field_names array[string(nonempty)] Required

A string that does not contain only whitespace characters

At least 1 element. Minimum length of each is 1.

license string

The rule's license.

max_signals integer Required

Maximum number of alerts the rule can create during a single run (the rule’s Max alerts per run advanced setting value).

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.

Minimum value is 1. Default value is 100.

meta object

Placeholder for metadata about the rule.

This field is overwritten when you save changes to the rule’s settings.

Additional properties are allowed.

name string Required

A human-readable name for the rule.

Minimum length is 1.

namespace string

Has no effect.

note string

Notes to help investigate alerts produced by the rule.

outcome string

Values are exactMatch, aliasMatch, or conflict.

output_index string Deprecated

(deprecated) Has no effect.

references array[string] Required

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.

related_integrations array[object] Required

Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:

package: name of the package (required, unique id)

version: version of the package (required, semver-compatible)

integration: name of the integration of this package (optional, id within the package)

There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.

Hide related_integrations attributes Show related_integrations attributes object

integration string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

package string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

version string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

required_fields array[object] Required

Elasticsearch fields and their types that need to be present for the rule to function.

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.

Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.

Hide required_fields attributes Show required_fields attributes object

name string(nonempty) Required

Name of an Elasticsearch field

Minimum length is 1.

type string(nonempty) Required

Type of the Elasticsearch field

Minimum length is 1.

response_actions array[object]

One of:
Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object

Hide attributes Show attributes

action_type_id string Required

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

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

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[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.

Hide attributes Show attributes

action_type_id string Required

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object

Hide attributes Show attributes

command string Required

Value is isolate.

comment string

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.

risk_score integer 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

Minimum value is 0, maximum value is 100.

risk_score_mapping array[object] Required

Overrides generated alerts' risk_score with a value from the source event

Hide risk_score_mapping attributes Show risk_score_mapping attributes object

field string Required

Source event field used to override the default risk_score.

operator string Required

Value is equals.

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

Minimum value is 0, maximum value is 100.

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 string 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 are low, medium, high, or critical.

severity_mapping array[object] Required

Overrides generated alerts' severity with values from the source event

Hide severity_mapping attributes Show severity_mapping attributes object

field string Required

Source event field used to override the default severity.

operator string Required

Value is equals.

severity string 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 are low, medium, high, or critical.

value string Required

tags array[string] Required

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.

threat array[object] Required

Currently, only threats described using the MITRE ATT&CK™ framework are supported.

Hide threat attributes Show threat attributes object

framework string Required

Relevant attack framework

tactic object Required

Object containing information on the attack type

Hide tactic attributes Show tactic attributes object

id string Required

Tactic ID

name string Required

Tactic name

reference string Required

Tactic reference

technique array[object]

Array containing information on the attack techniques (optional)

Hide technique attributes Show technique attributes object

id string Required

Technique ID

name string Required

Technique name

reference string Required

Technique reference

subtechnique array[object]

Array containing more specific information on the attack technique.

Hide subtechnique attributes Show subtechnique attributes object

id string Required

Subtechnique ID

name string Required

Subtechnique name

reference string Required

Subtechnique reference

throttle string | null

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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 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.

It is not incremented on each update. Compare this to the revision field.

Minimum value is 1.

created_at string(date-time) Required

created_by string Required

execution_summary object

Summary of the last execution of a rule.

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

Hide execution_summary attribute Show execution_summary attribute object

last_execution object Required

Hide last_execution attributes Show last_execution attributes object

date string(date-time) Required

Date of the last execution

message string Required

metrics object Required

Hide metrics attributes Show metrics attributes object

execution_gap_duration_s integer

Duration in seconds of execution gap

Minimum value is 0.

frozen_indices_queried_count integer

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

Minimum value is 0.

gap_range object

Range of the execution gap

Hide gap_range attributes Show gap_range attributes object

gte string Required

Start date of the execution gap

lte string Required

End date of the execution gap

total_enrichment_duration_ms integer

Total time spent enriching documents during current rule execution cycle

Minimum value is 0.

total_indexing_duration_ms integer

Total time spent indexing documents during current rule execution cycle

Minimum value is 0.

total_search_duration_ms integer

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

Minimum value is 0.

status string Required

Status of the last execution

Values are going to run, running, partial failure, failed, or succeeded.

status_order integer Required

id string(uuid) Required

A dynamic unique identifier for the rule object. It is randomly generated when a rule is created and cannot be changed after that. It is always a UUID. It is unique within a given Kibana space. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have different object ids.

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

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.

Minimum value is 0.

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 object 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:
Security_Detections_API_ExternalRuleSource object Security_Detections_API_InternalRuleSource object

Type of rule source for externally sourced rules, i.e. rules that have an external source, such as the Elastic Prebuilt rules repo.

Hide attributes Show attributes

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

type string Required Discriminator

Value is external.

updated_at string(date-time) Required

updated_by string Required

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.

threat_index array[string] Required

Elasticsearch indices used to check which field values generate alerts.

threat_mapping array[object] Required

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 Example of Threat Match rule which uses both and and or logic.

At least 1 element.

Hide threat_mapping attribute Show threat_mapping attribute object

entries array[object] Required

Hide entries attributes Show entries attributes object

field string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

type string Required

Value is mapping.

value string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

threat_query string Required

Query used to determine which fields in the Elasticsearch index are used for generating alerts.

type string Required Discriminator

Rule type

Value is threat_match.

alert_suppression object

Defines alert suppression configuration.

Hide alert_suppression attributes Show alert_suppression attributes object

duration object

Hide duration attributes Show duration attributes object

unit string Required

Time unit

Values are s, m, or h.

value integer Required

Minimum value is 1.

group_by array[string] Required

At least 1 but not more than 3 elements.

missing_fields_strategy string

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 are doNotSuppress or suppress.

concurrent_searches integer

Minimum value is 1.

data_view_id string

filters array

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

items_per_search integer

Minimum value is 1.

saved_id string

Kibana saved search used by the rule to create alerts.

threat_filters array

Query and filter context array used to filter documents from the Elasticsearch index containing the threat values

threat_indicator_path string

Defines the path to the threat indicator in the indicator documents (optional)

threat_language string

Values are kuery or lucene.

language string Required

Values are kuery or lucene.
Hide attributes Show attributes

actions array[object] Required

Array defining the automated actions (notifications) taken when alerts are generated.

Hide actions attributes Show actions attributes object

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.

Additional properties are allowed.

frequency object

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

Hide frequency attributes Show frequency attributes object

notifyWhen string Required

Defines how often rules run actions.

Values are onActiveAlert, onThrottleInterval, or 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 string | null Required

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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.

Additional properties are allowed.

uuid string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

alias_purpose string

Values are savedObjectConversion or savedObjectImport.

alias_target_id string

author array[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 Required

The rule’s description.

Minimum length is 1.

enabled boolean Required

Determines whether the rule is enabled. Defaults to true.

exceptions_list array[object] Required

Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.

Hide exceptions_list attributes Show exceptions_list attributes object

id string(nonempty) Required

ID of the exception container

Minimum length is 1.

list_id string(nonempty) Required

List ID of the exception container

Minimum length is 1.

namespace_type string Required

Determines the exceptions validity in rule's Kibana space

Values are agnostic or single.

type string Required

The exception type

Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.

false_positives array[string] Required

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.

from string(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.

Hide investigation_fields attribute Show investigation_fields attribute object

field_names array[string(nonempty)] Required

A string that does not contain only whitespace characters

At least 1 element. Minimum length of each is 1.

license string

The rule's license.

max_signals integer Required

Maximum number of alerts the rule can create during a single run (the rule’s Max alerts per run advanced setting value).

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.

Minimum value is 1. Default value is 100.

meta object

Placeholder for metadata about the rule.

This field is overwritten when you save changes to the rule’s settings.

Additional properties are allowed.

name string Required

A human-readable name for the rule.

Minimum length is 1.

namespace string

Has no effect.

note string

Notes to help investigate alerts produced by the rule.

outcome string

Values are exactMatch, aliasMatch, or conflict.

output_index string Deprecated

(deprecated) Has no effect.

references array[string] Required

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.

related_integrations array[object] Required

Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:

package: name of the package (required, unique id)

version: version of the package (required, semver-compatible)

integration: name of the integration of this package (optional, id within the package)

There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.

Hide related_integrations attributes Show related_integrations attributes object

integration string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

package string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

version string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

required_fields array[object] Required

Elasticsearch fields and their types that need to be present for the rule to function.

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.

Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.

Hide required_fields attributes Show required_fields attributes object

name string(nonempty) Required

Name of an Elasticsearch field

Minimum length is 1.

type string(nonempty) Required

Type of the Elasticsearch field

Minimum length is 1.

response_actions array[object]

One of:
Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object

Hide attributes Show attributes

action_type_id string Required

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

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

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[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.

Hide attributes Show attributes

action_type_id string Required

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object

Hide attributes Show attributes

command string Required

Value is isolate.

comment string

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.

risk_score integer 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

Minimum value is 0, maximum value is 100.

risk_score_mapping array[object] Required

Overrides generated alerts' risk_score with a value from the source event

Hide risk_score_mapping attributes Show risk_score_mapping attributes object

field string Required

Source event field used to override the default risk_score.

operator string Required

Value is equals.

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

Minimum value is 0, maximum value is 100.

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 string 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 are low, medium, high, or critical.

severity_mapping array[object] Required

Overrides generated alerts' severity with values from the source event

Hide severity_mapping attributes Show severity_mapping attributes object

field string Required

Source event field used to override the default severity.

operator string Required

Value is equals.

severity string 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 are low, medium, high, or critical.

value string Required

tags array[string] Required

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.

threat array[object] Required

Currently, only threats described using the MITRE ATT&CK™ framework are supported.

Hide threat attributes Show threat attributes object

framework string Required

Relevant attack framework

tactic object Required

Object containing information on the attack type

Hide tactic attributes Show tactic attributes object

id string Required

Tactic ID

name string Required

Tactic name

reference string Required

Tactic reference

technique array[object]

Array containing information on the attack techniques (optional)

Hide technique attributes Show technique attributes object

id string Required

Technique ID

name string Required

Technique name

reference string Required

Technique reference

subtechnique array[object]

Array containing more specific information on the attack technique.

Hide subtechnique attributes Show subtechnique attributes object

id string Required

Subtechnique ID

name string Required

Subtechnique name

reference string Required

Subtechnique reference

throttle string | null

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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 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.

It is not incremented on each update. Compare this to the revision field.

Minimum value is 1.

created_at string(date-time) Required

created_by string Required

execution_summary object

Summary of the last execution of a rule.

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

Hide execution_summary attribute Show execution_summary attribute object

last_execution object Required

Hide last_execution attributes Show last_execution attributes object

date string(date-time) Required

Date of the last execution

message string Required

metrics object Required

Hide metrics attributes Show metrics attributes object

execution_gap_duration_s integer

Duration in seconds of execution gap

Minimum value is 0.

frozen_indices_queried_count integer

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

Minimum value is 0.

gap_range object

Range of the execution gap

Hide gap_range attributes Show gap_range attributes object

gte string Required

Start date of the execution gap

lte string Required

End date of the execution gap

total_enrichment_duration_ms integer

Total time spent enriching documents during current rule execution cycle

Minimum value is 0.

total_indexing_duration_ms integer

Total time spent indexing documents during current rule execution cycle

Minimum value is 0.

total_search_duration_ms integer

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

Minimum value is 0.

status string Required

Status of the last execution

Values are going to run, running, partial failure, failed, or succeeded.

status_order integer Required

id string(uuid) Required

A dynamic unique identifier for the rule object. It is randomly generated when a rule is created and cannot be changed after that. It is always a UUID. It is unique within a given Kibana space. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have different object ids.

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

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.

Minimum value is 0.

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 object 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:
Security_Detections_API_ExternalRuleSource object Security_Detections_API_InternalRuleSource object

Type of rule source for externally sourced rules, i.e. rules that have an external source, such as the Elastic Prebuilt rules repo.

Hide attributes Show attributes

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

type string Required Discriminator

Value is external.

updated_at string(date-time) Required

updated_by string Required

anomaly_threshold integer Required

Anomaly score threshold above which the rule creates an alert. Valid values are from 0 to 100.

Minimum value is 0.

machine_learning_job_id string | array[string] Required

Machine learning job ID(s) the rule monitors for anomaly scores.

One of:
string-1 string array-2 array[string]

type string Required Discriminator

Rule type

Value is machine_learning.

alert_suppression object

Defines alert suppression configuration.

Hide alert_suppression attributes Show alert_suppression attributes object

duration object

Hide duration attributes Show duration attributes object

unit string Required

Time unit

Values are s, m, or h.

value integer Required

Minimum value is 1.

group_by array[string] Required

At least 1 but not more than 3 elements.

missing_fields_strategy string

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 are doNotSuppress or suppress.
Hide attributes Show attributes

actions array[object] Required

Array defining the automated actions (notifications) taken when alerts are generated.

Hide actions attributes Show actions attributes object

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.

Additional properties are allowed.

frequency object

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

Hide frequency attributes Show frequency attributes object

notifyWhen string Required

Defines how often rules run actions.

Values are onActiveAlert, onThrottleInterval, or 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 string | null Required

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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.

Additional properties are allowed.

uuid string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

alias_purpose string

Values are savedObjectConversion or savedObjectImport.

alias_target_id string

author array[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 Required

The rule’s description.

Minimum length is 1.

enabled boolean Required

Determines whether the rule is enabled. Defaults to true.

exceptions_list array[object] Required

Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.

Hide exceptions_list attributes Show exceptions_list attributes object

id string(nonempty) Required

ID of the exception container

Minimum length is 1.

list_id string(nonempty) Required

List ID of the exception container

Minimum length is 1.

namespace_type string Required

Determines the exceptions validity in rule's Kibana space

Values are agnostic or single.

type string Required

The exception type

Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.

false_positives array[string] Required

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.

from string(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.

Hide investigation_fields attribute Show investigation_fields attribute object

field_names array[string(nonempty)] Required

A string that does not contain only whitespace characters

At least 1 element. Minimum length of each is 1.

license string

The rule's license.

max_signals integer Required

Maximum number of alerts the rule can create during a single run (the rule’s Max alerts per run advanced setting value).

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.

Minimum value is 1. Default value is 100.

meta object

Placeholder for metadata about the rule.

This field is overwritten when you save changes to the rule’s settings.

Additional properties are allowed.

name string Required

A human-readable name for the rule.

Minimum length is 1.

namespace string

Has no effect.

note string

Notes to help investigate alerts produced by the rule.

outcome string

Values are exactMatch, aliasMatch, or conflict.

output_index string Deprecated

(deprecated) Has no effect.

references array[string] Required

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.

related_integrations array[object] Required

Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:

package: name of the package (required, unique id)

version: version of the package (required, semver-compatible)

integration: name of the integration of this package (optional, id within the package)

There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.

Hide related_integrations attributes Show related_integrations attributes object

integration string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

package string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

version string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

required_fields array[object] Required

Elasticsearch fields and their types that need to be present for the rule to function.

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.

Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.

Hide required_fields attributes Show required_fields attributes object

name string(nonempty) Required

Name of an Elasticsearch field

Minimum length is 1.

type string(nonempty) Required

Type of the Elasticsearch field

Minimum length is 1.

response_actions array[object]

One of:
Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object

Hide attributes Show attributes

action_type_id string Required

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

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

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[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.

Hide attributes Show attributes

action_type_id string Required

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object

Hide attributes Show attributes

command string Required

Value is isolate.

comment string

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.

risk_score integer 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

Minimum value is 0, maximum value is 100.

risk_score_mapping array[object] Required

Overrides generated alerts' risk_score with a value from the source event

Hide risk_score_mapping attributes Show risk_score_mapping attributes object

field string Required

Source event field used to override the default risk_score.

operator string Required

Value is equals.

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

Minimum value is 0, maximum value is 100.

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 string 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 are low, medium, high, or critical.

severity_mapping array[object] Required

Overrides generated alerts' severity with values from the source event

Hide severity_mapping attributes Show severity_mapping attributes object

field string Required

Source event field used to override the default severity.

operator string Required

Value is equals.

severity string 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 are low, medium, high, or critical.

value string Required

tags array[string] Required

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.

threat array[object] Required

Currently, only threats described using the MITRE ATT&CK™ framework are supported.

Hide threat attributes Show threat attributes object

framework string Required

Relevant attack framework

tactic object Required

Object containing information on the attack type

Hide tactic attributes Show tactic attributes object

id string Required

Tactic ID

name string Required

Tactic name

reference string Required

Tactic reference

technique array[object]

Array containing information on the attack techniques (optional)

Hide technique attributes Show technique attributes object

id string Required

Technique ID

name string Required

Technique name

reference string Required

Technique reference

subtechnique array[object]

Array containing more specific information on the attack technique.

Hide subtechnique attributes Show subtechnique attributes object

id string Required

Subtechnique ID

name string Required

Subtechnique name

reference string Required

Subtechnique reference

throttle string | null

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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 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.

It is not incremented on each update. Compare this to the revision field.

Minimum value is 1.

created_at string(date-time) Required

created_by string Required

execution_summary object

Summary of the last execution of a rule.

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

Hide execution_summary attribute Show execution_summary attribute object

last_execution object Required

Hide last_execution attributes Show last_execution attributes object

date string(date-time) Required

Date of the last execution

message string Required

metrics object Required

Hide metrics attributes Show metrics attributes object

execution_gap_duration_s integer

Duration in seconds of execution gap

Minimum value is 0.

frozen_indices_queried_count integer

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

Minimum value is 0.

gap_range object

Range of the execution gap

Hide gap_range attributes Show gap_range attributes object

gte string Required

Start date of the execution gap

lte string Required

End date of the execution gap

total_enrichment_duration_ms integer

Total time spent enriching documents during current rule execution cycle

Minimum value is 0.

total_indexing_duration_ms integer

Total time spent indexing documents during current rule execution cycle

Minimum value is 0.

total_search_duration_ms integer

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

Minimum value is 0.

status string Required

Status of the last execution

Values are going to run, running, partial failure, failed, or succeeded.

status_order integer Required

id string(uuid) Required

A dynamic unique identifier for the rule object. It is randomly generated when a rule is created and cannot be changed after that. It is always a UUID. It is unique within a given Kibana space. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have different object ids.

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

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.

Minimum value is 0.

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 object 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:
Security_Detections_API_ExternalRuleSource object Security_Detections_API_InternalRuleSource object

Type of rule source for externally sourced rules, i.e. rules that have an external source, such as the Elastic Prebuilt rules repo.

Hide attributes Show attributes

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

type string Required Discriminator

Value is external.

updated_at string(date-time) Required

updated_by string Required

history_window_start string(nonempty) Required

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.

Minimum length is 1.

new_terms_fields array[string] Required

Fields to monitor for new values.

At least 1 but not more than 3 elements.

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.

type string Required Discriminator

Rule type

Value is new_terms.

alert_suppression object

Defines alert suppression configuration.

Hide alert_suppression attributes Show alert_suppression attributes object

duration object

Hide duration attributes Show duration attributes object

unit string Required

Time unit

Values are s, m, or h.

value integer Required

Minimum value is 1.

group_by array[string] Required

At least 1 but not more than 3 elements.

missing_fields_strategy string

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 are doNotSuppress or suppress.

data_view_id string

filters array

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

language string Required

Values are kuery or lucene.
Hide attributes Show attributes

actions array[object] Required

Array defining the automated actions (notifications) taken when alerts are generated.

Hide actions attributes Show actions attributes object

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.

Additional properties are allowed.

frequency object

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

Hide frequency attributes Show frequency attributes object

notifyWhen string Required

Defines how often rules run actions.

Values are onActiveAlert, onThrottleInterval, or 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 string | null Required

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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.

Additional properties are allowed.

uuid string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

alias_purpose string

Values are savedObjectConversion or savedObjectImport.

alias_target_id string

author array[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 Required

The rule’s description.

Minimum length is 1.

enabled boolean Required

Determines whether the rule is enabled. Defaults to true.

exceptions_list array[object] Required

Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.

Hide exceptions_list attributes Show exceptions_list attributes object

id string(nonempty) Required

ID of the exception container

Minimum length is 1.

list_id string(nonempty) Required

List ID of the exception container

Minimum length is 1.

namespace_type string Required

Determines the exceptions validity in rule's Kibana space

Values are agnostic or single.

type string Required

The exception type

Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.

false_positives array[string] Required

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.

from string(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.

Hide investigation_fields attribute Show investigation_fields attribute object

field_names array[string(nonempty)] Required

A string that does not contain only whitespace characters

At least 1 element. Minimum length of each is 1.

license string

The rule's license.

max_signals integer Required

Maximum number of alerts the rule can create during a single run (the rule’s Max alerts per run advanced setting value).

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.

Minimum value is 1. Default value is 100.

meta object

Placeholder for metadata about the rule.

This field is overwritten when you save changes to the rule’s settings.

Additional properties are allowed.

name string Required

A human-readable name for the rule.

Minimum length is 1.

namespace string

Has no effect.

note string

Notes to help investigate alerts produced by the rule.

outcome string

Values are exactMatch, aliasMatch, or conflict.

output_index string Deprecated

(deprecated) Has no effect.

references array[string] Required

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.

related_integrations array[object] Required

Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:

package: name of the package (required, unique id)

version: version of the package (required, semver-compatible)

integration: name of the integration of this package (optional, id within the package)

There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.

Hide related_integrations attributes Show related_integrations attributes object

integration string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

package string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

version string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

required_fields array[object] Required

Elasticsearch fields and their types that need to be present for the rule to function.

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.

Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.

Hide required_fields attributes Show required_fields attributes object

name string(nonempty) Required

Name of an Elasticsearch field

Minimum length is 1.

type string(nonempty) Required

Type of the Elasticsearch field

Minimum length is 1.

response_actions array[object]

One of:
Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object

Hide attributes Show attributes

action_type_id string Required

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

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

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[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.

Hide attributes Show attributes

action_type_id string Required

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object

Hide attributes Show attributes

command string Required

Value is isolate.

comment string

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.

risk_score integer 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

Minimum value is 0, maximum value is 100.

risk_score_mapping array[object] Required

Overrides generated alerts' risk_score with a value from the source event

Hide risk_score_mapping attributes Show risk_score_mapping attributes object

field string Required

Source event field used to override the default risk_score.

operator string Required

Value is equals.

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

Minimum value is 0, maximum value is 100.

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 string 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 are low, medium, high, or critical.

severity_mapping array[object] Required

Overrides generated alerts' severity with values from the source event

Hide severity_mapping attributes Show severity_mapping attributes object

field string Required

Source event field used to override the default severity.

operator string Required

Value is equals.

severity string 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 are low, medium, high, or critical.

value string Required

tags array[string] Required

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.

threat array[object] Required

Currently, only threats described using the MITRE ATT&CK™ framework are supported.

Hide threat attributes Show threat attributes object

framework string Required

Relevant attack framework

tactic object Required

Object containing information on the attack type

Hide tactic attributes Show tactic attributes object

id string Required

Tactic ID

name string Required

Tactic name

reference string Required

Tactic reference

technique array[object]

Array containing information on the attack techniques (optional)

Hide technique attributes Show technique attributes object

id string Required

Technique ID

name string Required

Technique name

reference string Required

Technique reference

subtechnique array[object]

Array containing more specific information on the attack technique.

Hide subtechnique attributes Show subtechnique attributes object

id string Required

Subtechnique ID

name string Required

Subtechnique name

reference string Required

Subtechnique reference

throttle string | null

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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 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.

It is not incremented on each update. Compare this to the revision field.

Minimum value is 1.

created_at string(date-time) Required

created_by string Required

execution_summary object

Summary of the last execution of a rule.

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

Hide execution_summary attribute Show execution_summary attribute object

last_execution object Required

Hide last_execution attributes Show last_execution attributes object

date string(date-time) Required

Date of the last execution

message string Required

metrics object Required

Hide metrics attributes Show metrics attributes object

execution_gap_duration_s integer

Duration in seconds of execution gap

Minimum value is 0.

frozen_indices_queried_count integer

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

Minimum value is 0.

gap_range object

Range of the execution gap

Hide gap_range attributes Show gap_range attributes object

gte string Required

Start date of the execution gap

lte string Required

End date of the execution gap

total_enrichment_duration_ms integer

Total time spent enriching documents during current rule execution cycle

Minimum value is 0.

total_indexing_duration_ms integer

Total time spent indexing documents during current rule execution cycle

Minimum value is 0.

total_search_duration_ms integer

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

Minimum value is 0.

status string Required

Status of the last execution

Values are going to run, running, partial failure, failed, or succeeded.

status_order integer Required

id string(uuid) Required

A dynamic unique identifier for the rule object. It is randomly generated when a rule is created and cannot be changed after that. It is always a UUID. It is unique within a given Kibana space. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have different object ids.

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

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.

Minimum value is 0.

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 object 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:
Security_Detections_API_ExternalRuleSource object Security_Detections_API_InternalRuleSource object

Type of rule source for externally sourced rules, i.e. rules that have an external source, such as the Elastic Prebuilt rules repo.

Hide attributes Show attributes

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

type string Required Discriminator

Value is external.

updated_at string(date-time) Required

updated_by string Required

alert_suppression object

Defines alert suppression configuration.

Hide alert_suppression attributes Show alert_suppression attributes object

duration object

Hide duration attributes Show duration attributes object

unit string Required

Time unit

Values are s, m, or h.

value integer Required

Minimum value is 1.

group_by array[string] Required

At least 1 but not more than 3 elements.

missing_fields_strategy string

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 are doNotSuppress or suppress.

language string Required

Value is esql.

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.

type string Required Discriminator

Rule type

Value is esql.

PUT /api/detection_engine/rules

curl \
 --request PUT 'https://<KIBANA_URL>/api/detection_engine/rules' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"id":"14b7b513-3d8d-4b22-b7da-a7ae632f7e76","name":"A new name for the rule","type":"query","severity":"medium","risk_score":22,"description":"A new description"}'

Request examples

{
  "id": "14b7b513-3d8d-4b22-b7da-a7ae632f7e76",
  "name": "A new name for the rule",
  "type": "query",
  "severity": "medium",
  "risk_score": 22,
  "description": "A new description"
}

{
  "id": "9b684efb-acf9-4323-9bff-8335b3867d14",
  "name": "New name for EQL rule",
  "type": "eql",
  "index": [
    "apm-*-transaction*"
  ],
  "query": "process where process.name == \"regsvr32.exe\"",
  "language": "eql",
  "severity": "low",
  "risk_score": 21,
  "description": "eql rule test"
}

{
  "id": "005d2c4f-51ca-493d-a2bd-20ef076339b1",
  "name": "New name for threat rule",
  "tags": [
    "new_tag"
  ],
  "type": "threshold",
  "query": "agent.version : * and agent.id : \"243d9b4f-ca01-4311-8e5c-9abbee91afd8\"",
  "language": "kuery",
  "severity": "low",
  "threshold": {
    "field": [],
    "value": 400,
    "cardinality": []
  },
  "risk_score": 21,
  "description": "Description of threat rule test"
}

{
  "id": "569aac91-40dc-4807-a8ae-a2c8698089c4",
  "name": "New terms rule name",
  "type": "new_terms",
  "query": "agent.version : \"9.1.0\"",
  "interval": "5m",
  "severity": "low",
  "risk_score": 21,
  "description": "New description",
  "new_terms_fields": [
    "Endpoint.policy.applied.artifacts.global.identifiers.name"
  ],
  "history_window_start": "now-7d"
}

{
  "id": "0b15e8a2-49b6-47e0-a8e6-d63a6cc335bd",
  "name": "New name for esql rule",
  "type": "esql",
  "query": "FROM logs*\n| STATS count = COUNT(*), min_timestamp = MIN(@timestamp) /* MIN(dateField) finds the earliest timestamp in the dataset. */\n| EVAL event_rate = count / DATE_DIFF(\"seconds\", min_timestamp, NOW()) /* Calculates the event rate by dividing the total count of events by the time difference (in seconds) between the earliest event and the current time. */\n| KEEP event_rate\n",
  "language": "esql",
  "severity": "low",
  "risk_score": 21,
  "description": "New description for esql rule"
}

{
  "id": "462f1986-10fe-40a3-a22c-2b1c9c4c48fd",
  "name": "New name for Indicator Match rule",
  "type": "threat_match",
  "query": "source.ip:* or destination.ip:*\\n",
  "severity": "critical",
  "risk_score": 99,
  "description": "New description",
  "threat_index": [
    "filebeat-*",
    "logs-ti_*"
  ],
  "threat_query": "@timestamp >= \"now-30d/d\" and event.module:(threatintel or ti_*) and threat.indicator.ip:* and not labels.is_ioc_transform_source:\"true\"",
  "threat_mapping": [
    {
      "entries": [
        {
          "type": "mapping",
          "field": "source.ip",
          "value": "threat.indicator.ip"
        }
      ]
    },
    {
      "entries": [
        {
          "type": "mapping",
          "field": "destination.ip",
          "value": "threat.indicator.ip"
        }
      ]
    }
  ]
}

{
  "id": "60b13926-289b-41b1-a537-197ef1fa5059",
  "name": "New name of ml rule",
  "type": "machine_learning",
  "severity": "low",
  "risk_score": 21,
  "description": "New description of ml rule",
  "anomaly_threshold": 50,
  "machine_learning_job_id": [
    "auth_high_count_logon_events"
  ]
}

Response examples (200)

{
  "id": "6541b99a-dee9-4f6d-a86d-dbd1869d73b1",
  "to": "now",
  "from": "now-70m",
  "name": "Updated Rule Name",
  "tags": [
    "child process",
    "ms office"
  ],
  "type": "query",
  "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",
  "setup": "",
  "threat": [],
  "actions": [],
  "enabled": false,
  "filters": [
    {
      "query": null
    }
  ],
  "rule_id": "process_started_by_ms_office_program",
  "version": 2,
  "interval": "1h",
  "language": "kuery",
  "severity": "low",
  "immutable": false,
  "created_at": "2020-04-07T14:51:09.755Z",
  "created_by": "elastic",
  "references": [],
  "risk_score": 50,
  "updated_at": "2020-04-07T14:51:09.970Z",
  "updated_by": "elastic",
  "description": "Updated description for the rule.",
  "max_signals": 100,
  "false_positives": [],
  "required_fields": [
    {
      "name": "process.parent.name"
    }
  ],
  "related_integrations": [
    {
      "package": "o365"
    }
  ]
}

Create a detection rule

POST /api/detection_engine/rules

Create a new detection rule.

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.

You can create the following types of rules:

Custom query: Searches the defined indices and creates an alert when a document matches the rule's KQL query.
Event correlation: Searches the defined indices and creates an alert when results match an Event Query Language (EQL) query.
Threshold: Searches the defined indices and creates an alert when the number of times the specified field's value meets the threshold during a single execution. When there are multiple values that meet the threshold, an alert is generated for each value. For example, if the threshold field is source.ip and its value is 10, an alert is generated for every source IP address that appears in at least 10 of the rule's search results. If you're interested, see Terms Aggregation for more information.
Indicator match: Creates an alert when fields match values defined in the specified Elasticsearch index. For example, you can create an index for IP addresses and use this index to create an alert whenever an event's destination.ip equals a value in the index. The index's field mappings should be ECS-compliant.
New terms: Generates an alert for each new term detected in source documents within a specified time range.
ES|QL: Uses Elasticsearch Query Language (ES|QL) to find events and aggregate search results.
Machine learning rules: Creates an alert when a machine learning job discovers an anomaly above the defined threshold.

To create machine learning rules, you must have the appropriate license or use a cloud deployment. Additionally, for the machine learning rule to function correctly, the associated machine learning job must be running.

To retrieve machine learning job IDs, which are required to create machine learning jobs, call the Elasticsearch Get jobs API. Machine learning jobs that contain siem in the groups field can be used to create rules:

...
"job_id": "linux_anomalous_network_activity_ecs",
"job_type": "anomaly_detector",
"job_version": "7.7.0",
"groups": [
  "auditbeat",
  "process",
  "siem"
],
...

Additionally, you can set up notifications for when rules create alerts. The notifications use the Alerting and Actions framework. Each action type requires a connector. Connectors store the information required to send notifications via external systems. The following connector types are supported for rule notifications:

Slack
Email
PagerDuty
Webhook
Microsoft Teams
IBM Resilient
Jira
ServiceNow ITSM

For more information on PagerDuty fields, see Send a v2 Event.

To retrieve connector IDs, which are required to configure rule notifications, call the Find objects API with "type": "action" in the request payload.

For detailed information on Kibana actions and alerting, and additional API calls, see:

application/json

Body object Required

actions array[object]

Array defining the automated actions (notifications) taken when alerts are generated.
Hide actions attributes Show actions attributes object
- 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.
  Additional properties are allowed.
- frequency object
  
  The action frequency defines when the action runs (for example, only on rule execution or at specific time intervals).
  Hide frequency attributes Show frequency attributes object
  
  notifyWhen string Required
  
  Defines how often rules run actions.
  
  Values are onActiveAlert, onThrottleInterval, or 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 string | null Required
  
  Defines how often rule actions are taken.
  
  One of:
  string-1 string | null string-2 string | null
  
  Values are no_actions or 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.
  Additional properties are allowed.
- uuid string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
alias_purpose string

Values are savedObjectConversion or savedObjectImport.
alias_target_id string
author array[string]

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 Required

The rule’s description.

Minimum length is 1.
enabled boolean

Determines whether the rule is enabled. Defaults to true.
exceptions_list array[object]

Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.
Hide exceptions_list attributes Show exceptions_list attributes object
- id string(nonempty) Required
  
  ID of the exception container
  
  Minimum length is 1.
- list_id string(nonempty) Required
  
  List ID of the exception container
  
  Minimum length is 1.
- namespace_type string Required
  
  Determines the exceptions validity in rule's Kibana space
  
  Values are agnostic or single.
- type string Required
  
  The exception type
  
  Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.
false_positives array[string]

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.
from string(date-math)

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

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.
Hide investigation_fields attribute Show investigation_fields attribute object
- field_names array[string(nonempty)] Required
  
  A string that does not contain only whitespace characters
  
  At least 1 element. Minimum length of each is 1.
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).

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.

Minimum value is 1. Default value is 100.
meta object

Placeholder for metadata about the rule.

This field is overwritten when you save changes to the rule’s settings.

Additional properties are allowed.
name string Required

A human-readable name for the rule.

Minimum length is 1.
namespace string

Has no effect.
note string

Notes to help investigate alerts produced by the rule.
outcome string

Values are exactMatch, aliasMatch, or conflict.
output_index string Deprecated

(deprecated) Has no effect.
references array[string]

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.
related_integrations array[object]
Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:
- package: name of the package (required, unique id)
- version: version of the package (required, semver-compatible)
- integration: name of the integration of this package (optional, id within the package)
There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.
Hide related_integrations attributes Show related_integrations attributes object
- integration string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- package string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- version string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
required_fields array[object]

Elasticsearch fields and their types that need to be present for the rule to function.

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.

Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.
Hide required_fields attributes Show required_fields attributes object
- name string(nonempty) Required
  
  Name of an Elasticsearch field
  
  Minimum length is 1.
- type string(nonempty) Required
  
  Type of the Elasticsearch field
  
  Minimum length is 1.
response_actions array[object]
One of:
Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object
Hide attributes Show attributes

action_type_id string Required

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

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

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[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.
Hide attributes Show attributes

action_type_id string Required

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object

Hide attributes Show attributes

command string Required

Value is isolate.

comment string

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.
risk_score integer 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
Minimum value is 0, maximum value is 100.
risk_score_mapping array[object]

Overrides generated alerts' risk_score with a value from the source event
Hide risk_score_mapping attributes Show risk_score_mapping attributes object
- field string Required
  
  Source event field used to override the default risk_score.
- operator string Required
  
  Value is equals.
- 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
  Minimum value is 0, maximum value is 100.
- value string Required
rule_id string

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

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 string 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 are low, medium, high, or critical.
severity_mapping array[object]

Overrides generated alerts' severity with values from the source event
Hide severity_mapping attributes Show severity_mapping attributes object
- field string Required
  
  Source event field used to override the default severity.
- operator string Required
  
  Value is equals.
- severity string 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 are low, medium, high, or critical.
- value string Required
tags array[string]

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.
threat array[object]

Currently, only threats described using the MITRE ATT&CK™ framework are supported.
Hide threat attributes Show threat attributes object
- framework string Required
  
  Relevant attack framework
- tactic object Required
  
  Object containing information on the attack type
  Hide tactic attributes Show tactic attributes object
  
  id string Required
  
  Tactic ID
  
  name string Required
  
  Tactic name
  
  reference string Required
  
  Tactic reference
- technique array[object]
  
  Array containing information on the attack techniques (optional)
  Hide technique attributes Show technique attributes object
  
  id string Required
  
  Technique ID
  
  name string Required
  
  Technique name
  
  reference string Required
  
  Technique reference
  
  subtechnique array[object]
  
  Array containing more specific information on the attack technique.
  
  Hide subtechnique attributes Show subtechnique attributes object
  
  id string Required
  
  Subtechnique ID
  
  name string Required
  
  Subtechnique name
  
  reference string Required
  
  Subtechnique reference
throttle string | null

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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
version integer
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.
It is not incremented on each update. Compare this to the revision field.
Minimum value is 1.
language string Required

Query language to use

Value is 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.
type string Required Discriminator

Rule type

Value is eql.
alert_suppression object

Defines alert suppression configuration.
Hide alert_suppression attributes Show alert_suppression attributes object
- duration object
  Hide duration attributes Show duration attributes object
  
  unit string Required
  
  Time unit
  
  Values are s, m, or h.
  
  value integer Required
  
  Minimum value is 1.
- group_by array[string] Required
  
  At least 1 but not more than 3 elements.
- missing_fields_strategy string
  
  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 are doNotSuppress or suppress.
data_view_id string
event_category_override string
filters array

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

actions array[object]

Array defining the automated actions (notifications) taken when alerts are generated.
Hide actions attributes Show actions attributes object
- 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.
  Additional properties are allowed.
- frequency object
  
  The action frequency defines when the action runs (for example, only on rule execution or at specific time intervals).
  Hide frequency attributes Show frequency attributes object
  
  notifyWhen string Required
  
  Defines how often rules run actions.
  
  Values are onActiveAlert, onThrottleInterval, or 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 string | null Required
  
  Defines how often rule actions are taken.
  
  One of:
  string-1 string | null string-2 string | null
  
  Values are no_actions or 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.
  Additional properties are allowed.
- uuid string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
alias_purpose string

Values are savedObjectConversion or savedObjectImport.
alias_target_id string
author array[string]

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 Required

The rule’s description.

Minimum length is 1.
enabled boolean

Determines whether the rule is enabled. Defaults to true.
exceptions_list array[object]

Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.
Hide exceptions_list attributes Show exceptions_list attributes object
- id string(nonempty) Required
  
  ID of the exception container
  
  Minimum length is 1.
- list_id string(nonempty) Required
  
  List ID of the exception container
  
  Minimum length is 1.
- namespace_type string Required
  
  Determines the exceptions validity in rule's Kibana space
  
  Values are agnostic or single.
- type string Required
  
  The exception type
  
  Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.
false_positives array[string]

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.
from string(date-math)

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

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.
Hide investigation_fields attribute Show investigation_fields attribute object
- field_names array[string(nonempty)] Required
  
  A string that does not contain only whitespace characters
  
  At least 1 element. Minimum length of each is 1.
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).

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.

Minimum value is 1. Default value is 100.
meta object

Placeholder for metadata about the rule.

This field is overwritten when you save changes to the rule’s settings.

Additional properties are allowed.
name string Required

A human-readable name for the rule.

Minimum length is 1.
namespace string

Has no effect.
note string

Notes to help investigate alerts produced by the rule.
outcome string

Values are exactMatch, aliasMatch, or conflict.
output_index string Deprecated

(deprecated) Has no effect.
references array[string]

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.
related_integrations array[object]
Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:
- package: name of the package (required, unique id)
- version: version of the package (required, semver-compatible)
- integration: name of the integration of this package (optional, id within the package)
There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.
Hide related_integrations attributes Show related_integrations attributes object
- integration string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- package string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- version string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
required_fields array[object]

Elasticsearch fields and their types that need to be present for the rule to function.

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.

Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.
Hide required_fields attributes Show required_fields attributes object
- name string(nonempty) Required
  
  Name of an Elasticsearch field
  
  Minimum length is 1.
- type string(nonempty) Required
  
  Type of the Elasticsearch field
  
  Minimum length is 1.
response_actions array[object]
One of:
Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object
Hide attributes Show attributes

action_type_id string Required

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

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

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[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.
Hide attributes Show attributes

action_type_id string Required

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object

Hide attributes Show attributes

command string Required

Value is isolate.

comment string

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.
risk_score integer 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
Minimum value is 0, maximum value is 100.
risk_score_mapping array[object]

Overrides generated alerts' risk_score with a value from the source event
Hide risk_score_mapping attributes Show risk_score_mapping attributes object
- field string Required
  
  Source event field used to override the default risk_score.
- operator string Required
  
  Value is equals.
- 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
  Minimum value is 0, maximum value is 100.
- value string Required
rule_id string

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

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 string 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 are low, medium, high, or critical.
severity_mapping array[object]

Overrides generated alerts' severity with values from the source event
Hide severity_mapping attributes Show severity_mapping attributes object
- field string Required
  
  Source event field used to override the default severity.
- operator string Required
  
  Value is equals.
- severity string 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 are low, medium, high, or critical.
- value string Required
tags array[string]

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.
threat array[object]

Currently, only threats described using the MITRE ATT&CK™ framework are supported.
Hide threat attributes Show threat attributes object
- framework string Required
  
  Relevant attack framework
- tactic object Required
  
  Object containing information on the attack type
  Hide tactic attributes Show tactic attributes object
  
  id string Required
  
  Tactic ID
  
  name string Required
  
  Tactic name
  
  reference string Required
  
  Tactic reference
- technique array[object]
  
  Array containing information on the attack techniques (optional)
  Hide technique attributes Show technique attributes object
  
  id string Required
  
  Technique ID
  
  name string Required
  
  Technique name
  
  reference string Required
  
  Technique reference
  
  subtechnique array[object]
  
  Array containing more specific information on the attack technique.
  
  Hide subtechnique attributes Show subtechnique attributes object
  
  id string Required
  
  Subtechnique ID
  
  name string Required
  
  Subtechnique name
  
  reference string Required
  
  Subtechnique reference
throttle string | null

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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
version integer
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.
It is not incremented on each update. Compare this to the revision field.
Minimum value is 1.
type string Required Discriminator

Rule type

Value is query.
alert_suppression object

Defines alert suppression configuration.
Hide alert_suppression attributes Show alert_suppression attributes object
- duration object
  Hide duration attributes Show duration attributes object
  
  unit string Required
  
  Time unit
  
  Values are s, m, or h.
  
  value integer Required
  
  Minimum value is 1.
- group_by array[string] Required
  
  At least 1 but not more than 3 elements.
- missing_fields_strategy string
  
  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 are doNotSuppress or suppress.
data_view_id string
filters array

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 array[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.
saved_id string

Kibana saved search used by the rule to create alerts.
language string

Values are kuery or lucene.
query string
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.

actions array[object]

Array defining the automated actions (notifications) taken when alerts are generated.
Hide actions attributes Show actions attributes object
- 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.
  Additional properties are allowed.
- frequency object
  
  The action frequency defines when the action runs (for example, only on rule execution or at specific time intervals).
  Hide frequency attributes Show frequency attributes object
  
  notifyWhen string Required
  
  Defines how often rules run actions.
  
  Values are onActiveAlert, onThrottleInterval, or 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 string | null Required
  
  Defines how often rule actions are taken.
  
  One of:
  string-1 string | null string-2 string | null
  
  Values are no_actions or 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.
  Additional properties are allowed.
- uuid string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
alias_purpose string

Values are savedObjectConversion or savedObjectImport.
alias_target_id string
author array[string]

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 Required

The rule’s description.

Minimum length is 1.
enabled boolean

Determines whether the rule is enabled. Defaults to true.
exceptions_list array[object]

Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.
Hide exceptions_list attributes Show exceptions_list attributes object
- id string(nonempty) Required
  
  ID of the exception container
  
  Minimum length is 1.
- list_id string(nonempty) Required
  
  List ID of the exception container
  
  Minimum length is 1.
- namespace_type string Required
  
  Determines the exceptions validity in rule's Kibana space
  
  Values are agnostic or single.
- type string Required
  
  The exception type
  
  Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.
false_positives array[string]

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.
from string(date-math)

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

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.
Hide investigation_fields attribute Show investigation_fields attribute object
- field_names array[string(nonempty)] Required
  
  A string that does not contain only whitespace characters
  
  At least 1 element. Minimum length of each is 1.
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).

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.

Minimum value is 1. Default value is 100.
meta object

Placeholder for metadata about the rule.

This field is overwritten when you save changes to the rule’s settings.

Additional properties are allowed.
name string Required

A human-readable name for the rule.

Minimum length is 1.
namespace string

Has no effect.
note string

Notes to help investigate alerts produced by the rule.
outcome string

Values are exactMatch, aliasMatch, or conflict.
output_index string Deprecated

(deprecated) Has no effect.
references array[string]

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.
related_integrations array[object]
Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:
- package: name of the package (required, unique id)
- version: version of the package (required, semver-compatible)
- integration: name of the integration of this package (optional, id within the package)
There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.
Hide related_integrations attributes Show related_integrations attributes object
- integration string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- package string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- version string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
required_fields array[object]

Elasticsearch fields and their types that need to be present for the rule to function.

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.

Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.
Hide required_fields attributes Show required_fields attributes object
- name string(nonempty) Required
  
  Name of an Elasticsearch field
  
  Minimum length is 1.
- type string(nonempty) Required
  
  Type of the Elasticsearch field
  
  Minimum length is 1.
response_actions array[object]
One of:
Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object
Hide attributes Show attributes

action_type_id string Required

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

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

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[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.
Hide attributes Show attributes

action_type_id string Required

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object

Hide attributes Show attributes

command string Required

Value is isolate.

comment string

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.
risk_score integer 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
Minimum value is 0, maximum value is 100.
risk_score_mapping array[object]

Overrides generated alerts' risk_score with a value from the source event
Hide risk_score_mapping attributes Show risk_score_mapping attributes object
- field string Required
  
  Source event field used to override the default risk_score.
- operator string Required
  
  Value is equals.
- 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
  Minimum value is 0, maximum value is 100.
- value string Required
rule_id string

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

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 string 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 are low, medium, high, or critical.
severity_mapping array[object]

Overrides generated alerts' severity with values from the source event
Hide severity_mapping attributes Show severity_mapping attributes object
- field string Required
  
  Source event field used to override the default severity.
- operator string Required
  
  Value is equals.
- severity string 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 are low, medium, high, or critical.
- value string Required
tags array[string]

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.
threat array[object]

Currently, only threats described using the MITRE ATT&CK™ framework are supported.
Hide threat attributes Show threat attributes object
- framework string Required
  
  Relevant attack framework
- tactic object Required
  
  Object containing information on the attack type
  Hide tactic attributes Show tactic attributes object
  
  id string Required
  
  Tactic ID
  
  name string Required
  
  Tactic name
  
  reference string Required
  
  Tactic reference
- technique array[object]
  
  Array containing information on the attack techniques (optional)
  Hide technique attributes Show technique attributes object
  
  id string Required
  
  Technique ID
  
  name string Required
  
  Technique name
  
  reference string Required
  
  Technique reference
  
  subtechnique array[object]
  
  Array containing more specific information on the attack technique.
  
  Hide subtechnique attributes Show subtechnique attributes object
  
  id string Required
  
  Subtechnique ID
  
  name string Required
  
  Subtechnique name
  
  reference string Required
  
  Subtechnique reference
throttle string | null

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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
version integer
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.
It is not incremented on each update. Compare this to the revision field.
Minimum value is 1.
saved_id string Required

Kibana saved search used by the rule to create alerts.
type string Required Discriminator

Rule type

Value is saved_query.
alert_suppression object

Defines alert suppression configuration.
Hide alert_suppression attributes Show alert_suppression attributes object
- duration object
  Hide duration attributes Show duration attributes object
  
  unit string Required
  
  Time unit
  
  Values are s, m, or h.
  
  value integer Required
  
  Minimum value is 1.
- group_by array[string] Required
  
  At least 1 but not more than 3 elements.
- missing_fields_strategy string
  
  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 are doNotSuppress or suppress.
data_view_id string
filters array

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 array[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.
query string
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.
language string

Values are kuery or lucene.

actions array[object]

Array defining the automated actions (notifications) taken when alerts are generated.
Hide actions attributes Show actions attributes object
- 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.
  Additional properties are allowed.
- frequency object
  
  The action frequency defines when the action runs (for example, only on rule execution or at specific time intervals).
  Hide frequency attributes Show frequency attributes object
  
  notifyWhen string Required
  
  Defines how often rules run actions.
  
  Values are onActiveAlert, onThrottleInterval, or 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 string | null Required
  
  Defines how often rule actions are taken.
  
  One of:
  string-1 string | null string-2 string | null
  
  Values are no_actions or 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.
  Additional properties are allowed.
- uuid string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
alias_purpose string

Values are savedObjectConversion or savedObjectImport.
alias_target_id string
author array[string]

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 Required

The rule’s description.

Minimum length is 1.
enabled boolean

Determines whether the rule is enabled. Defaults to true.
exceptions_list array[object]

Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.
Hide exceptions_list attributes Show exceptions_list attributes object
- id string(nonempty) Required
  
  ID of the exception container
  
  Minimum length is 1.
- list_id string(nonempty) Required
  
  List ID of the exception container
  
  Minimum length is 1.
- namespace_type string Required
  
  Determines the exceptions validity in rule's Kibana space
  
  Values are agnostic or single.
- type string Required
  
  The exception type
  
  Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.
false_positives array[string]

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.
from string(date-math)

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

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.
Hide investigation_fields attribute Show investigation_fields attribute object
- field_names array[string(nonempty)] Required
  
  A string that does not contain only whitespace characters
  
  At least 1 element. Minimum length of each is 1.
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).

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.

Minimum value is 1. Default value is 100.
meta object

Placeholder for metadata about the rule.

This field is overwritten when you save changes to the rule’s settings.

Additional properties are allowed.
name string Required

A human-readable name for the rule.

Minimum length is 1.
namespace string

Has no effect.
note string

Notes to help investigate alerts produced by the rule.
outcome string

Values are exactMatch, aliasMatch, or conflict.
output_index string Deprecated

(deprecated) Has no effect.
references array[string]

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.
related_integrations array[object]
Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:
- package: name of the package (required, unique id)
- version: version of the package (required, semver-compatible)
- integration: name of the integration of this package (optional, id within the package)
There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.
Hide related_integrations attributes Show related_integrations attributes object
- integration string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- package string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- version string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
required_fields array[object]

Elasticsearch fields and their types that need to be present for the rule to function.

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.

Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.
Hide required_fields attributes Show required_fields attributes object
- name string(nonempty) Required
  
  Name of an Elasticsearch field
  
  Minimum length is 1.
- type string(nonempty) Required
  
  Type of the Elasticsearch field
  
  Minimum length is 1.
response_actions array[object]
One of:
Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object
Hide attributes Show attributes

action_type_id string Required

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

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

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[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.
Hide attributes Show attributes

action_type_id string Required

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object

Hide attributes Show attributes

command string Required

Value is isolate.

comment string

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.
risk_score integer 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
Minimum value is 0, maximum value is 100.
risk_score_mapping array[object]

Overrides generated alerts' risk_score with a value from the source event
Hide risk_score_mapping attributes Show risk_score_mapping attributes object
- field string Required
  
  Source event field used to override the default risk_score.
- operator string Required
  
  Value is equals.
- 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
  Minimum value is 0, maximum value is 100.
- value string Required
rule_id string

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

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 string 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 are low, medium, high, or critical.
severity_mapping array[object]

Overrides generated alerts' severity with values from the source event
Hide severity_mapping attributes Show severity_mapping attributes object
- field string Required
  
  Source event field used to override the default severity.
- operator string Required
  
  Value is equals.
- severity string 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 are low, medium, high, or critical.
- value string Required
tags array[string]

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.
threat array[object]

Currently, only threats described using the MITRE ATT&CK™ framework are supported.
Hide threat attributes Show threat attributes object
- framework string Required
  
  Relevant attack framework
- tactic object Required
  
  Object containing information on the attack type
  Hide tactic attributes Show tactic attributes object
  
  id string Required
  
  Tactic ID
  
  name string Required
  
  Tactic name
  
  reference string Required
  
  Tactic reference
- technique array[object]
  
  Array containing information on the attack techniques (optional)
  Hide technique attributes Show technique attributes object
  
  id string Required
  
  Technique ID
  
  name string Required
  
  Technique name
  
  reference string Required
  
  Technique reference
  
  subtechnique array[object]
  
  Array containing more specific information on the attack technique.
  
  Hide subtechnique attributes Show subtechnique attributes object
  
  id string Required
  
  Subtechnique ID
  
  name string Required
  
  Subtechnique name
  
  reference string Required
  
  Subtechnique reference
throttle string | null

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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
version integer
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.
It is not incremented on each update. Compare this to the revision field.
Minimum value is 1.
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.
threshold object Required
Hide threshold attributes Show threshold attributes object
- cardinality array[object]
  
  The field on which the cardinality is applied.
  Hide cardinality attributes Show cardinality attributes object
  
  field string Required
  
  The field on which to calculate and compare the cardinality.
  
  value integer Required
  
  The threshold value from which an alert is generated based on unique number of values of cardinality.field.
  
  Minimum value is 0.
- field string | array[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.
  
  One of:
  string-1 string array-2 array[string]
- value integer Required
  
  The threshold value from which an alert is generated.
  
  Minimum value is 1.
type string Required Discriminator

Rule type

Value is threshold.
alert_suppression object

Defines alert suppression configuration.
Hide alert_suppression attribute Show alert_suppression attribute object
- duration object Required
  Hide duration attributes Show duration attributes object
  
  unit string Required
  
  Time unit
  
  Values are s, m, or h.
  
  value integer Required
  
  Minimum value is 1.
data_view_id string
filters array

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 array[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.
saved_id string

Kibana saved search used by the rule to create alerts.
language string

Values are kuery or lucene.

actions array[object]

Array defining the automated actions (notifications) taken when alerts are generated.
Hide actions attributes Show actions attributes object
- 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.
  Additional properties are allowed.
- frequency object
  
  The action frequency defines when the action runs (for example, only on rule execution or at specific time intervals).
  Hide frequency attributes Show frequency attributes object
  
  notifyWhen string Required
  
  Defines how often rules run actions.
  
  Values are onActiveAlert, onThrottleInterval, or 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 string | null Required
  
  Defines how often rule actions are taken.
  
  One of:
  string-1 string | null string-2 string | null
  
  Values are no_actions or 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.
  Additional properties are allowed.
- uuid string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
alias_purpose string

Values are savedObjectConversion or savedObjectImport.
alias_target_id string
author array[string]

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 Required

The rule’s description.

Minimum length is 1.
enabled boolean

Determines whether the rule is enabled. Defaults to true.
exceptions_list array[object]

Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.
Hide exceptions_list attributes Show exceptions_list attributes object
- id string(nonempty) Required
  
  ID of the exception container
  
  Minimum length is 1.
- list_id string(nonempty) Required
  
  List ID of the exception container
  
  Minimum length is 1.
- namespace_type string Required
  
  Determines the exceptions validity in rule's Kibana space
  
  Values are agnostic or single.
- type string Required
  
  The exception type
  
  Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.
false_positives array[string]

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.
from string(date-math)

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

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.
Hide investigation_fields attribute Show investigation_fields attribute object
- field_names array[string(nonempty)] Required
  
  A string that does not contain only whitespace characters
  
  At least 1 element. Minimum length of each is 1.
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).

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.

Minimum value is 1. Default value is 100.
meta object

Placeholder for metadata about the rule.

This field is overwritten when you save changes to the rule’s settings.

Additional properties are allowed.
name string Required

A human-readable name for the rule.

Minimum length is 1.
namespace string

Has no effect.
note string

Notes to help investigate alerts produced by the rule.
outcome string

Values are exactMatch, aliasMatch, or conflict.
output_index string Deprecated

(deprecated) Has no effect.
references array[string]

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.
related_integrations array[object]
Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:
- package: name of the package (required, unique id)
- version: version of the package (required, semver-compatible)
- integration: name of the integration of this package (optional, id within the package)
There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.
Hide related_integrations attributes Show related_integrations attributes object
- integration string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- package string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- version string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
required_fields array[object]

Elasticsearch fields and their types that need to be present for the rule to function.

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.

Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.
Hide required_fields attributes Show required_fields attributes object
- name string(nonempty) Required
  
  Name of an Elasticsearch field
  
  Minimum length is 1.
- type string(nonempty) Required
  
  Type of the Elasticsearch field
  
  Minimum length is 1.
response_actions array[object]
One of:
Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object
Hide attributes Show attributes

action_type_id string Required

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

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

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[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.
Hide attributes Show attributes

action_type_id string Required

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object

Hide attributes Show attributes

command string Required

Value is isolate.

comment string

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.
risk_score integer 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
Minimum value is 0, maximum value is 100.
risk_score_mapping array[object]

Overrides generated alerts' risk_score with a value from the source event
Hide risk_score_mapping attributes Show risk_score_mapping attributes object
- field string Required
  
  Source event field used to override the default risk_score.
- operator string Required
  
  Value is equals.
- 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
  Minimum value is 0, maximum value is 100.
- value string Required
rule_id string

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

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 string 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 are low, medium, high, or critical.
severity_mapping array[object]

Overrides generated alerts' severity with values from the source event
Hide severity_mapping attributes Show severity_mapping attributes object
- field string Required
  
  Source event field used to override the default severity.
- operator string Required
  
  Value is equals.
- severity string 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 are low, medium, high, or critical.
- value string Required
tags array[string]

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.
threat array[object]

Currently, only threats described using the MITRE ATT&CK™ framework are supported.
Hide threat attributes Show threat attributes object
- framework string Required
  
  Relevant attack framework
- tactic object Required
  
  Object containing information on the attack type
  Hide tactic attributes Show tactic attributes object
  
  id string Required
  
  Tactic ID
  
  name string Required
  
  Tactic name
  
  reference string Required
  
  Tactic reference
- technique array[object]
  
  Array containing information on the attack techniques (optional)
  Hide technique attributes Show technique attributes object
  
  id string Required
  
  Technique ID
  
  name string Required
  
  Technique name
  
  reference string Required
  
  Technique reference
  
  subtechnique array[object]
  
  Array containing more specific information on the attack technique.
  
  Hide subtechnique attributes Show subtechnique attributes object
  
  id string Required
  
  Subtechnique ID
  
  name string Required
  
  Subtechnique name
  
  reference string Required
  
  Subtechnique reference
throttle string | null

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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
version integer
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.
It is not incremented on each update. Compare this to the revision field.
Minimum value is 1.
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.
threat_index array[string] Required

Elasticsearch indices used to check which field values generate alerts.
threat_mapping array[object] Required
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 Example of Threat Match rule which uses both and and or logic.
At least 1 element.
Hide threat_mapping attribute Show threat_mapping attribute object
- entries array[object] Required
  Hide entries attributes Show entries attributes object
  
  field string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  type string Required
  
  Value is mapping.
  
  value string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
threat_query string Required

Query used to determine which fields in the Elasticsearch index are used for generating alerts.
type string Required Discriminator

Rule type

Value is threat_match.
alert_suppression object

Defines alert suppression configuration.
Hide alert_suppression attributes Show alert_suppression attributes object
- duration object
  Hide duration attributes Show duration attributes object
  
  unit string Required
  
  Time unit
  
  Values are s, m, or h.
  
  value integer Required
  
  Minimum value is 1.
- group_by array[string] Required
  
  At least 1 but not more than 3 elements.
- missing_fields_strategy string
  
  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 are doNotSuppress or suppress.
concurrent_searches integer

Minimum value is 1.
data_view_id string
filters array

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 array[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.
items_per_search integer

Minimum value is 1.
saved_id string

Kibana saved search used by the rule to create alerts.
threat_filters array

Query and filter context array used to filter documents from the Elasticsearch index containing the threat values
threat_indicator_path string

Defines the path to the threat indicator in the indicator documents (optional)
threat_language string

Values are kuery or lucene.
language string

Values are kuery or lucene.

actions array[object]

Array defining the automated actions (notifications) taken when alerts are generated.
Hide actions attributes Show actions attributes object
- 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.
  Additional properties are allowed.
- frequency object
  
  The action frequency defines when the action runs (for example, only on rule execution or at specific time intervals).
  Hide frequency attributes Show frequency attributes object
  
  notifyWhen string Required
  
  Defines how often rules run actions.
  
  Values are onActiveAlert, onThrottleInterval, or 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 string | null Required
  
  Defines how often rule actions are taken.
  
  One of:
  string-1 string | null string-2 string | null
  
  Values are no_actions or 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.
  Additional properties are allowed.
- uuid string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
alias_purpose string

Values are savedObjectConversion or savedObjectImport.
alias_target_id string
author array[string]

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 Required

The rule’s description.

Minimum length is 1.
enabled boolean

Determines whether the rule is enabled. Defaults to true.
exceptions_list array[object]

Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.
Hide exceptions_list attributes Show exceptions_list attributes object
- id string(nonempty) Required
  
  ID of the exception container
  
  Minimum length is 1.
- list_id string(nonempty) Required
  
  List ID of the exception container
  
  Minimum length is 1.
- namespace_type string Required
  
  Determines the exceptions validity in rule's Kibana space
  
  Values are agnostic or single.
- type string Required
  
  The exception type
  
  Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.
false_positives array[string]

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.
from string(date-math)

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

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.
Hide investigation_fields attribute Show investigation_fields attribute object
- field_names array[string(nonempty)] Required
  
  A string that does not contain only whitespace characters
  
  At least 1 element. Minimum length of each is 1.
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).

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.

Minimum value is 1. Default value is 100.
meta object

Placeholder for metadata about the rule.

This field is overwritten when you save changes to the rule’s settings.

Additional properties are allowed.
name string Required

A human-readable name for the rule.

Minimum length is 1.
namespace string

Has no effect.
note string

Notes to help investigate alerts produced by the rule.
outcome string

Values are exactMatch, aliasMatch, or conflict.
output_index string Deprecated

(deprecated) Has no effect.
references array[string]

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.
related_integrations array[object]
Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:
- package: name of the package (required, unique id)
- version: version of the package (required, semver-compatible)
- integration: name of the integration of this package (optional, id within the package)
There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.
Hide related_integrations attributes Show related_integrations attributes object
- integration string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- package string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- version string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
required_fields array[object]

Elasticsearch fields and their types that need to be present for the rule to function.

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.

Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.
Hide required_fields attributes Show required_fields attributes object
- name string(nonempty) Required
  
  Name of an Elasticsearch field
  
  Minimum length is 1.
- type string(nonempty) Required
  
  Type of the Elasticsearch field
  
  Minimum length is 1.
response_actions array[object]
One of:
Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object
Hide attributes Show attributes

action_type_id string Required

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

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

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[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.
Hide attributes Show attributes

action_type_id string Required

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object

Hide attributes Show attributes

command string Required

Value is isolate.

comment string

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.
risk_score integer 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
Minimum value is 0, maximum value is 100.
risk_score_mapping array[object]

Overrides generated alerts' risk_score with a value from the source event
Hide risk_score_mapping attributes Show risk_score_mapping attributes object
- field string Required
  
  Source event field used to override the default risk_score.
- operator string Required
  
  Value is equals.
- 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
  Minimum value is 0, maximum value is 100.
- value string Required
rule_id string

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

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 string 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 are low, medium, high, or critical.
severity_mapping array[object]

Overrides generated alerts' severity with values from the source event
Hide severity_mapping attributes Show severity_mapping attributes object
- field string Required
  
  Source event field used to override the default severity.
- operator string Required
  
  Value is equals.
- severity string 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 are low, medium, high, or critical.
- value string Required
tags array[string]

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.
threat array[object]

Currently, only threats described using the MITRE ATT&CK™ framework are supported.
Hide threat attributes Show threat attributes object
- framework string Required
  
  Relevant attack framework
- tactic object Required
  
  Object containing information on the attack type
  Hide tactic attributes Show tactic attributes object
  
  id string Required
  
  Tactic ID
  
  name string Required
  
  Tactic name
  
  reference string Required
  
  Tactic reference
- technique array[object]
  
  Array containing information on the attack techniques (optional)
  Hide technique attributes Show technique attributes object
  
  id string Required
  
  Technique ID
  
  name string Required
  
  Technique name
  
  reference string Required
  
  Technique reference
  
  subtechnique array[object]
  
  Array containing more specific information on the attack technique.
  
  Hide subtechnique attributes Show subtechnique attributes object
  
  id string Required
  
  Subtechnique ID
  
  name string Required
  
  Subtechnique name
  
  reference string Required
  
  Subtechnique reference
throttle string | null

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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
version integer
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.
It is not incremented on each update. Compare this to the revision field.
Minimum value is 1.
anomaly_threshold integer Required

Anomaly score threshold above which the rule creates an alert. Valid values are from 0 to 100.

Minimum value is 0.
machine_learning_job_id string | array[string] Required

Machine learning job ID(s) the rule monitors for anomaly scores.

One of:
string-1 string array-2 array[string]
type string Required Discriminator

Rule type

Value is machine_learning.
alert_suppression object

Defines alert suppression configuration.
Hide alert_suppression attributes Show alert_suppression attributes object
- duration object
  Hide duration attributes Show duration attributes object
  
  unit string Required
  
  Time unit
  
  Values are s, m, or h.
  
  value integer Required
  
  Minimum value is 1.
- group_by array[string] Required
  
  At least 1 but not more than 3 elements.
- missing_fields_strategy string
  
  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 are doNotSuppress or suppress.

actions array[object]

Array defining the automated actions (notifications) taken when alerts are generated.
Hide actions attributes Show actions attributes object
- 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.
  Additional properties are allowed.
- frequency object
  
  The action frequency defines when the action runs (for example, only on rule execution or at specific time intervals).
  Hide frequency attributes Show frequency attributes object
  
  notifyWhen string Required
  
  Defines how often rules run actions.
  
  Values are onActiveAlert, onThrottleInterval, or 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 string | null Required
  
  Defines how often rule actions are taken.
  
  One of:
  string-1 string | null string-2 string | null
  
  Values are no_actions or 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.
  Additional properties are allowed.
- uuid string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
alias_purpose string

Values are savedObjectConversion or savedObjectImport.
alias_target_id string
author array[string]

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 Required

The rule’s description.

Minimum length is 1.
enabled boolean

Determines whether the rule is enabled. Defaults to true.
exceptions_list array[object]

Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.
Hide exceptions_list attributes Show exceptions_list attributes object
- id string(nonempty) Required
  
  ID of the exception container
  
  Minimum length is 1.
- list_id string(nonempty) Required
  
  List ID of the exception container
  
  Minimum length is 1.
- namespace_type string Required
  
  Determines the exceptions validity in rule's Kibana space
  
  Values are agnostic or single.
- type string Required
  
  The exception type
  
  Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.
false_positives array[string]

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.
from string(date-math)

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

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.
Hide investigation_fields attribute Show investigation_fields attribute object
- field_names array[string(nonempty)] Required
  
  A string that does not contain only whitespace characters
  
  At least 1 element. Minimum length of each is 1.
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).

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.

Minimum value is 1. Default value is 100.
meta object

Placeholder for metadata about the rule.

This field is overwritten when you save changes to the rule’s settings.

Additional properties are allowed.
name string Required

A human-readable name for the rule.

Minimum length is 1.
namespace string

Has no effect.
note string

Notes to help investigate alerts produced by the rule.
outcome string

Values are exactMatch, aliasMatch, or conflict.
output_index string Deprecated

(deprecated) Has no effect.
references array[string]

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.
related_integrations array[object]
Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:
- package: name of the package (required, unique id)
- version: version of the package (required, semver-compatible)
- integration: name of the integration of this package (optional, id within the package)
There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.
Hide related_integrations attributes Show related_integrations attributes object
- integration string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- package string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- version string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
required_fields array[object]

Elasticsearch fields and their types that need to be present for the rule to function.

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.

Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.
Hide required_fields attributes Show required_fields attributes object
- name string(nonempty) Required
  
  Name of an Elasticsearch field
  
  Minimum length is 1.
- type string(nonempty) Required
  
  Type of the Elasticsearch field
  
  Minimum length is 1.
response_actions array[object]
One of:
Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object
Hide attributes Show attributes

action_type_id string Required

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

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

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[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.
Hide attributes Show attributes

action_type_id string Required

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object

Hide attributes Show attributes

command string Required

Value is isolate.

comment string

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.
risk_score integer 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
Minimum value is 0, maximum value is 100.
risk_score_mapping array[object]

Overrides generated alerts' risk_score with a value from the source event
Hide risk_score_mapping attributes Show risk_score_mapping attributes object
- field string Required
  
  Source event field used to override the default risk_score.
- operator string Required
  
  Value is equals.
- 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
  Minimum value is 0, maximum value is 100.
- value string Required
rule_id string

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

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 string 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 are low, medium, high, or critical.
severity_mapping array[object]

Overrides generated alerts' severity with values from the source event
Hide severity_mapping attributes Show severity_mapping attributes object
- field string Required
  
  Source event field used to override the default severity.
- operator string Required
  
  Value is equals.
- severity string 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 are low, medium, high, or critical.
- value string Required
tags array[string]

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.
threat array[object]

Currently, only threats described using the MITRE ATT&CK™ framework are supported.
Hide threat attributes Show threat attributes object
- framework string Required
  
  Relevant attack framework
- tactic object Required
  
  Object containing information on the attack type
  Hide tactic attributes Show tactic attributes object
  
  id string Required
  
  Tactic ID
  
  name string Required
  
  Tactic name
  
  reference string Required
  
  Tactic reference
- technique array[object]
  
  Array containing information on the attack techniques (optional)
  Hide technique attributes Show technique attributes object
  
  id string Required
  
  Technique ID
  
  name string Required
  
  Technique name
  
  reference string Required
  
  Technique reference
  
  subtechnique array[object]
  
  Array containing more specific information on the attack technique.
  
  Hide subtechnique attributes Show subtechnique attributes object
  
  id string Required
  
  Subtechnique ID
  
  name string Required
  
  Subtechnique name
  
  reference string Required
  
  Subtechnique reference
throttle string | null

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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
version integer
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.
It is not incremented on each update. Compare this to the revision field.
Minimum value is 1.
history_window_start string(nonempty) Required

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.

Minimum length is 1.
new_terms_fields array[string] Required

Fields to monitor for new values.

At least 1 but not more than 3 elements.
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.
type string Required Discriminator

Rule type

Value is new_terms.
alert_suppression object

Defines alert suppression configuration.
Hide alert_suppression attributes Show alert_suppression attributes object
- duration object
  Hide duration attributes Show duration attributes object
  
  unit string Required
  
  Time unit
  
  Values are s, m, or h.
  
  value integer Required
  
  Minimum value is 1.
- group_by array[string] Required
  
  At least 1 but not more than 3 elements.
- missing_fields_strategy string
  
  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 are doNotSuppress or suppress.
data_view_id string
filters array

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 array[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.
language string

Values are kuery or lucene.

actions array[object]

Array defining the automated actions (notifications) taken when alerts are generated.
Hide actions attributes Show actions attributes object
- 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.
  Additional properties are allowed.
- frequency object
  
  The action frequency defines when the action runs (for example, only on rule execution or at specific time intervals).
  Hide frequency attributes Show frequency attributes object
  
  notifyWhen string Required
  
  Defines how often rules run actions.
  
  Values are onActiveAlert, onThrottleInterval, or 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 string | null Required
  
  Defines how often rule actions are taken.
  
  One of:
  string-1 string | null string-2 string | null
  
  Values are no_actions or 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.
  Additional properties are allowed.
- uuid string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
alias_purpose string

Values are savedObjectConversion or savedObjectImport.
alias_target_id string
author array[string]

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 Required

The rule’s description.

Minimum length is 1.
enabled boolean

Determines whether the rule is enabled. Defaults to true.
exceptions_list array[object]

Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.
Hide exceptions_list attributes Show exceptions_list attributes object
- id string(nonempty) Required
  
  ID of the exception container
  
  Minimum length is 1.
- list_id string(nonempty) Required
  
  List ID of the exception container
  
  Minimum length is 1.
- namespace_type string Required
  
  Determines the exceptions validity in rule's Kibana space
  
  Values are agnostic or single.
- type string Required
  
  The exception type
  
  Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.
false_positives array[string]

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.
from string(date-math)

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

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.
Hide investigation_fields attribute Show investigation_fields attribute object
- field_names array[string(nonempty)] Required
  
  A string that does not contain only whitespace characters
  
  At least 1 element. Minimum length of each is 1.
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).

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.

Minimum value is 1. Default value is 100.
meta object

Placeholder for metadata about the rule.

This field is overwritten when you save changes to the rule’s settings.

Additional properties are allowed.
name string Required

A human-readable name for the rule.

Minimum length is 1.
namespace string

Has no effect.
note string

Notes to help investigate alerts produced by the rule.
outcome string

Values are exactMatch, aliasMatch, or conflict.
output_index string Deprecated

(deprecated) Has no effect.
references array[string]

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.
related_integrations array[object]
Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:
- package: name of the package (required, unique id)
- version: version of the package (required, semver-compatible)
- integration: name of the integration of this package (optional, id within the package)
There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.
Hide related_integrations attributes Show related_integrations attributes object
- integration string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- package string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- version string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
required_fields array[object]

Elasticsearch fields and their types that need to be present for the rule to function.

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.

Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.
Hide required_fields attributes Show required_fields attributes object
- name string(nonempty) Required
  
  Name of an Elasticsearch field
  
  Minimum length is 1.
- type string(nonempty) Required
  
  Type of the Elasticsearch field
  
  Minimum length is 1.
response_actions array[object]
One of:
Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object
Hide attributes Show attributes

action_type_id string Required

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

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

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[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.
Hide attributes Show attributes

action_type_id string Required

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object

Hide attributes Show attributes

command string Required

Value is isolate.

comment string

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.
risk_score integer 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
Minimum value is 0, maximum value is 100.
risk_score_mapping array[object]

Overrides generated alerts' risk_score with a value from the source event
Hide risk_score_mapping attributes Show risk_score_mapping attributes object
- field string Required
  
  Source event field used to override the default risk_score.
- operator string Required
  
  Value is equals.
- 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
  Minimum value is 0, maximum value is 100.
- value string Required
rule_id string

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

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 string 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 are low, medium, high, or critical.
severity_mapping array[object]

Overrides generated alerts' severity with values from the source event
Hide severity_mapping attributes Show severity_mapping attributes object
- field string Required
  
  Source event field used to override the default severity.
- operator string Required
  
  Value is equals.
- severity string 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 are low, medium, high, or critical.
- value string Required
tags array[string]

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.
threat array[object]

Currently, only threats described using the MITRE ATT&CK™ framework are supported.
Hide threat attributes Show threat attributes object
- framework string Required
  
  Relevant attack framework
- tactic object Required
  
  Object containing information on the attack type
  Hide tactic attributes Show tactic attributes object
  
  id string Required
  
  Tactic ID
  
  name string Required
  
  Tactic name
  
  reference string Required
  
  Tactic reference
- technique array[object]
  
  Array containing information on the attack techniques (optional)
  Hide technique attributes Show technique attributes object
  
  id string Required
  
  Technique ID
  
  name string Required
  
  Technique name
  
  reference string Required
  
  Technique reference
  
  subtechnique array[object]
  
  Array containing more specific information on the attack technique.
  
  Hide subtechnique attributes Show subtechnique attributes object
  
  id string Required
  
  Subtechnique ID
  
  name string Required
  
  Subtechnique name
  
  reference string Required
  
  Subtechnique reference
throttle string | null

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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
version integer
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.
It is not incremented on each update. Compare this to the revision field.
Minimum value is 1.
alert_suppression object

Defines alert suppression configuration.
Hide alert_suppression attributes Show alert_suppression attributes object
- duration object
  Hide duration attributes Show duration attributes object
  
  unit string Required
  
  Time unit
  
  Values are s, m, or h.
  
  value integer Required
  
  Minimum value is 1.
- group_by array[string] Required
  
  At least 1 but not more than 3 elements.
- missing_fields_strategy string
  
  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 are doNotSuppress or suppress.
language string Required

Value is esql.
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.
type string Required Discriminator

Rule type

Value is esql.

Responses

200 application/json

Indicates a successful call.
Any of:
Security_Detections_API_EqlRuleResponseFields object Security_Detections_API_QueryRuleResponseFields object Security_Detections_API_SavedQueryRuleResponseFields object Security_Detections_API_ThresholdRuleResponseFields object Security_Detections_API_ThreatMatchRuleResponseFields object Security_Detections_API_MachineLearningRuleResponseFields object Security_Detections_API_NewTermsRuleResponseFields object Security_Detections_API_EsqlRuleResponseFields object
Hide attributes Show attributes

actions array[object] Required

Array defining the automated actions (notifications) taken when alerts are generated.

Hide actions attributes Show actions attributes object

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.

Additional properties are allowed.

frequency object

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

Hide frequency attributes Show frequency attributes object

notifyWhen string Required

Defines how often rules run actions.

Values are onActiveAlert, onThrottleInterval, or 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 string | null Required

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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.

Additional properties are allowed.

uuid string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

alias_purpose string

Values are savedObjectConversion or savedObjectImport.

alias_target_id string

author array[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 Required

The rule’s description.

Minimum length is 1.

enabled boolean Required

Determines whether the rule is enabled. Defaults to true.

exceptions_list array[object] Required

Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.

Hide exceptions_list attributes Show exceptions_list attributes object

id string(nonempty) Required

ID of the exception container

Minimum length is 1.

list_id string(nonempty) Required

List ID of the exception container

Minimum length is 1.

namespace_type string Required

Determines the exceptions validity in rule's Kibana space

Values are agnostic or single.

type string Required

The exception type

Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.

false_positives array[string] Required

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.

from string(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.

Hide investigation_fields attribute Show investigation_fields attribute object

field_names array[string(nonempty)] Required

A string that does not contain only whitespace characters

At least 1 element. Minimum length of each is 1.

license string

The rule's license.

max_signals integer Required

Maximum number of alerts the rule can create during a single run (the rule’s Max alerts per run advanced setting value).

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.

Minimum value is 1. Default value is 100.

meta object

Placeholder for metadata about the rule.

This field is overwritten when you save changes to the rule’s settings.

Additional properties are allowed.

name string Required

A human-readable name for the rule.

Minimum length is 1.

namespace string

Has no effect.

note string

Notes to help investigate alerts produced by the rule.

outcome string

Values are exactMatch, aliasMatch, or conflict.

output_index string Deprecated

(deprecated) Has no effect.

references array[string] Required

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.

related_integrations array[object] Required

Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:

package: name of the package (required, unique id)

version: version of the package (required, semver-compatible)

integration: name of the integration of this package (optional, id within the package)

There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.

Hide related_integrations attributes Show related_integrations attributes object

integration string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

package string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

version string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

required_fields array[object] Required

Elasticsearch fields and their types that need to be present for the rule to function.

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.

Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.

Hide required_fields attributes Show required_fields attributes object

name string(nonempty) Required

Name of an Elasticsearch field

Minimum length is 1.

type string(nonempty) Required

Type of the Elasticsearch field

Minimum length is 1.

response_actions array[object]

One of:
Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object

Hide attributes Show attributes

action_type_id string Required

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

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

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[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.

Hide attributes Show attributes

action_type_id string Required

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object

Hide attributes Show attributes

command string Required

Value is isolate.

comment string

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.

risk_score integer 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

Minimum value is 0, maximum value is 100.

risk_score_mapping array[object] Required

Overrides generated alerts' risk_score with a value from the source event

Hide risk_score_mapping attributes Show risk_score_mapping attributes object

field string Required

Source event field used to override the default risk_score.

operator string Required

Value is equals.

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

Minimum value is 0, maximum value is 100.

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 string 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 are low, medium, high, or critical.

severity_mapping array[object] Required

Overrides generated alerts' severity with values from the source event

Hide severity_mapping attributes Show severity_mapping attributes object

field string Required

Source event field used to override the default severity.

operator string Required

Value is equals.

severity string 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 are low, medium, high, or critical.

value string Required

tags array[string] Required

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.

threat array[object] Required

Currently, only threats described using the MITRE ATT&CK™ framework are supported.

Hide threat attributes Show threat attributes object

framework string Required

Relevant attack framework

tactic object Required

Object containing information on the attack type

Hide tactic attributes Show tactic attributes object

id string Required

Tactic ID

name string Required

Tactic name

reference string Required

Tactic reference

technique array[object]

Array containing information on the attack techniques (optional)

Hide technique attributes Show technique attributes object

id string Required

Technique ID

name string Required

Technique name

reference string Required

Technique reference

subtechnique array[object]

Array containing more specific information on the attack technique.

Hide subtechnique attributes Show subtechnique attributes object

id string Required

Subtechnique ID

name string Required

Subtechnique name

reference string Required

Subtechnique reference

throttle string | null

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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 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.

It is not incremented on each update. Compare this to the revision field.

Minimum value is 1.

created_at string(date-time) Required

created_by string Required

execution_summary object

Summary of the last execution of a rule.

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

Hide execution_summary attribute Show execution_summary attribute object

last_execution object Required

Hide last_execution attributes Show last_execution attributes object

date string(date-time) Required

Date of the last execution

message string Required

metrics object Required

Hide metrics attributes Show metrics attributes object

execution_gap_duration_s integer

Duration in seconds of execution gap

Minimum value is 0.

frozen_indices_queried_count integer

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

Minimum value is 0.

gap_range object

Range of the execution gap

Hide gap_range attributes Show gap_range attributes object

gte string Required

Start date of the execution gap

lte string Required

End date of the execution gap

total_enrichment_duration_ms integer

Total time spent enriching documents during current rule execution cycle

Minimum value is 0.

total_indexing_duration_ms integer

Total time spent indexing documents during current rule execution cycle

Minimum value is 0.

total_search_duration_ms integer

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

Minimum value is 0.

status string Required

Status of the last execution

Values are going to run, running, partial failure, failed, or succeeded.

status_order integer Required

id string(uuid) Required

A dynamic unique identifier for the rule object. It is randomly generated when a rule is created and cannot be changed after that. It is always a UUID. It is unique within a given Kibana space. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have different object ids.

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

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.

Minimum value is 0.

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 object 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:
Security_Detections_API_ExternalRuleSource object Security_Detections_API_InternalRuleSource object

Type of rule source for externally sourced rules, i.e. rules that have an external source, such as the Elastic Prebuilt rules repo.

Hide attributes Show attributes

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

type string Required Discriminator

Value is external.

updated_at string(date-time) Required

updated_by string Required

language string Required

Query language to use

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

type string Required Discriminator

Rule type

Value is eql.

alert_suppression object

Defines alert suppression configuration.

Hide alert_suppression attributes Show alert_suppression attributes object

duration object

Hide duration attributes Show duration attributes object

unit string Required

Time unit

Values are s, m, or h.

value integer Required

Minimum value is 1.

group_by array[string] Required

At least 1 but not more than 3 elements.

missing_fields_strategy string

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 are doNotSuppress or suppress.

data_view_id string

event_category_override string

filters array

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

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.
Hide attributes Show attributes

actions array[object] Required

Array defining the automated actions (notifications) taken when alerts are generated.

Hide actions attributes Show actions attributes object

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.

Additional properties are allowed.

frequency object

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

Hide frequency attributes Show frequency attributes object

notifyWhen string Required

Defines how often rules run actions.

Values are onActiveAlert, onThrottleInterval, or 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 string | null Required

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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.

Additional properties are allowed.

uuid string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

alias_purpose string

Values are savedObjectConversion or savedObjectImport.

alias_target_id string

author array[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 Required

The rule’s description.

Minimum length is 1.

enabled boolean Required

Determines whether the rule is enabled. Defaults to true.

exceptions_list array[object] Required

Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.

Hide exceptions_list attributes Show exceptions_list attributes object

id string(nonempty) Required

ID of the exception container

Minimum length is 1.

list_id string(nonempty) Required

List ID of the exception container

Minimum length is 1.

namespace_type string Required

Determines the exceptions validity in rule's Kibana space

Values are agnostic or single.

type string Required

The exception type

Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.

false_positives array[string] Required

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.

from string(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.

Hide investigation_fields attribute Show investigation_fields attribute object

field_names array[string(nonempty)] Required

A string that does not contain only whitespace characters

At least 1 element. Minimum length of each is 1.

license string

The rule's license.

max_signals integer Required

Maximum number of alerts the rule can create during a single run (the rule’s Max alerts per run advanced setting value).

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.

Minimum value is 1. Default value is 100.

meta object

Placeholder for metadata about the rule.

This field is overwritten when you save changes to the rule’s settings.

Additional properties are allowed.

name string Required

A human-readable name for the rule.

Minimum length is 1.

namespace string

Has no effect.

note string

Notes to help investigate alerts produced by the rule.

outcome string

Values are exactMatch, aliasMatch, or conflict.

output_index string Deprecated

(deprecated) Has no effect.

references array[string] Required

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.

related_integrations array[object] Required

Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:

package: name of the package (required, unique id)

version: version of the package (required, semver-compatible)

integration: name of the integration of this package (optional, id within the package)

There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.

Hide related_integrations attributes Show related_integrations attributes object

integration string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

package string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

version string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

required_fields array[object] Required

Elasticsearch fields and their types that need to be present for the rule to function.

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.

Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.

Hide required_fields attributes Show required_fields attributes object

name string(nonempty) Required

Name of an Elasticsearch field

Minimum length is 1.

type string(nonempty) Required

Type of the Elasticsearch field

Minimum length is 1.

response_actions array[object]

One of:
Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object

Hide attributes Show attributes

action_type_id string Required

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

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

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[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.

Hide attributes Show attributes

action_type_id string Required

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object

Hide attributes Show attributes

command string Required

Value is isolate.

comment string

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.

risk_score integer 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

Minimum value is 0, maximum value is 100.

risk_score_mapping array[object] Required

Overrides generated alerts' risk_score with a value from the source event

Hide risk_score_mapping attributes Show risk_score_mapping attributes object

field string Required

Source event field used to override the default risk_score.

operator string Required

Value is equals.

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

Minimum value is 0, maximum value is 100.

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 string 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 are low, medium, high, or critical.

severity_mapping array[object] Required

Overrides generated alerts' severity with values from the source event

Hide severity_mapping attributes Show severity_mapping attributes object

field string Required

Source event field used to override the default severity.

operator string Required

Value is equals.

severity string 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 are low, medium, high, or critical.

value string Required

tags array[string] Required

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.

threat array[object] Required

Currently, only threats described using the MITRE ATT&CK™ framework are supported.

Hide threat attributes Show threat attributes object

framework string Required

Relevant attack framework

tactic object Required

Object containing information on the attack type

Hide tactic attributes Show tactic attributes object

id string Required

Tactic ID

name string Required

Tactic name

reference string Required

Tactic reference

technique array[object]

Array containing information on the attack techniques (optional)

Hide technique attributes Show technique attributes object

id string Required

Technique ID

name string Required

Technique name

reference string Required

Technique reference

subtechnique array[object]

Array containing more specific information on the attack technique.

Hide subtechnique attributes Show subtechnique attributes object

id string Required

Subtechnique ID

name string Required

Subtechnique name

reference string Required

Subtechnique reference

throttle string | null

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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 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.

It is not incremented on each update. Compare this to the revision field.

Minimum value is 1.

created_at string(date-time) Required

created_by string Required

execution_summary object

Summary of the last execution of a rule.

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

Hide execution_summary attribute Show execution_summary attribute object

last_execution object Required

Hide last_execution attributes Show last_execution attributes object

date string(date-time) Required

Date of the last execution

message string Required

metrics object Required

Hide metrics attributes Show metrics attributes object

execution_gap_duration_s integer

Duration in seconds of execution gap

Minimum value is 0.

frozen_indices_queried_count integer

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

Minimum value is 0.

gap_range object

Range of the execution gap

Hide gap_range attributes Show gap_range attributes object

gte string Required

Start date of the execution gap

lte string Required

End date of the execution gap

total_enrichment_duration_ms integer

Total time spent enriching documents during current rule execution cycle

Minimum value is 0.

total_indexing_duration_ms integer

Total time spent indexing documents during current rule execution cycle

Minimum value is 0.

total_search_duration_ms integer

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

Minimum value is 0.

status string Required

Status of the last execution

Values are going to run, running, partial failure, failed, or succeeded.

status_order integer Required

id string(uuid) Required

A dynamic unique identifier for the rule object. It is randomly generated when a rule is created and cannot be changed after that. It is always a UUID. It is unique within a given Kibana space. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have different object ids.

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

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.

Minimum value is 0.

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 object 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:
Security_Detections_API_ExternalRuleSource object Security_Detections_API_InternalRuleSource object

Type of rule source for externally sourced rules, i.e. rules that have an external source, such as the Elastic Prebuilt rules repo.

Hide attributes Show attributes

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

type string Required Discriminator

Value is external.

updated_at string(date-time) Required

updated_by string Required

type string Required Discriminator

Rule type

Value is query.

alert_suppression object

Defines alert suppression configuration.

Hide alert_suppression attributes Show alert_suppression attributes object

duration object

Hide duration attributes Show duration attributes object

unit string Required

Time unit

Values are s, m, or h.

value integer Required

Minimum value is 1.

group_by array[string] Required

At least 1 but not more than 3 elements.

missing_fields_strategy string

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 are doNotSuppress or suppress.

data_view_id string

filters array

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

saved_id string

Kibana saved search used by the rule to create alerts.

language string Required

Values are kuery or lucene.

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.
Hide attributes Show attributes

actions array[object] Required

Array defining the automated actions (notifications) taken when alerts are generated.

Hide actions attributes Show actions attributes object

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.

Additional properties are allowed.

frequency object

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

Hide frequency attributes Show frequency attributes object

notifyWhen string Required

Defines how often rules run actions.

Values are onActiveAlert, onThrottleInterval, or 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 string | null Required

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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.

Additional properties are allowed.

uuid string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

alias_purpose string

Values are savedObjectConversion or savedObjectImport.

alias_target_id string

author array[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 Required

The rule’s description.

Minimum length is 1.

enabled boolean Required

Determines whether the rule is enabled. Defaults to true.

exceptions_list array[object] Required

Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.

Hide exceptions_list attributes Show exceptions_list attributes object

id string(nonempty) Required

ID of the exception container

Minimum length is 1.

list_id string(nonempty) Required

List ID of the exception container

Minimum length is 1.

namespace_type string Required

Determines the exceptions validity in rule's Kibana space

Values are agnostic or single.

type string Required

The exception type

Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.

false_positives array[string] Required

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.

from string(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.

Hide investigation_fields attribute Show investigation_fields attribute object

field_names array[string(nonempty)] Required

A string that does not contain only whitespace characters

At least 1 element. Minimum length of each is 1.

license string

The rule's license.

max_signals integer Required

Maximum number of alerts the rule can create during a single run (the rule’s Max alerts per run advanced setting value).

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.

Minimum value is 1. Default value is 100.

meta object

Placeholder for metadata about the rule.

This field is overwritten when you save changes to the rule’s settings.

Additional properties are allowed.

name string Required

A human-readable name for the rule.

Minimum length is 1.

namespace string

Has no effect.

note string

Notes to help investigate alerts produced by the rule.

outcome string

Values are exactMatch, aliasMatch, or conflict.

output_index string Deprecated

(deprecated) Has no effect.

references array[string] Required

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.

related_integrations array[object] Required

Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:

package: name of the package (required, unique id)

version: version of the package (required, semver-compatible)

integration: name of the integration of this package (optional, id within the package)

There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.

Hide related_integrations attributes Show related_integrations attributes object

integration string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

package string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

version string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

required_fields array[object] Required

Elasticsearch fields and their types that need to be present for the rule to function.

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.

Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.

Hide required_fields attributes Show required_fields attributes object

name string(nonempty) Required

Name of an Elasticsearch field

Minimum length is 1.

type string(nonempty) Required

Type of the Elasticsearch field

Minimum length is 1.

response_actions array[object]

One of:
Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object

Hide attributes Show attributes

action_type_id string Required

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

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

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[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.

Hide attributes Show attributes

action_type_id string Required

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object

Hide attributes Show attributes

command string Required

Value is isolate.

comment string

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.

risk_score integer 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

Minimum value is 0, maximum value is 100.

risk_score_mapping array[object] Required

Overrides generated alerts' risk_score with a value from the source event

Hide risk_score_mapping attributes Show risk_score_mapping attributes object

field string Required

Source event field used to override the default risk_score.

operator string Required

Value is equals.

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

Minimum value is 0, maximum value is 100.

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 string 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 are low, medium, high, or critical.

severity_mapping array[object] Required

Overrides generated alerts' severity with values from the source event

Hide severity_mapping attributes Show severity_mapping attributes object

field string Required

Source event field used to override the default severity.

operator string Required

Value is equals.

severity string 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 are low, medium, high, or critical.

value string Required

tags array[string] Required

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.

threat array[object] Required

Currently, only threats described using the MITRE ATT&CK™ framework are supported.

Hide threat attributes Show threat attributes object

framework string Required

Relevant attack framework

tactic object Required

Object containing information on the attack type

Hide tactic attributes Show tactic attributes object

id string Required

Tactic ID

name string Required

Tactic name

reference string Required

Tactic reference

technique array[object]

Array containing information on the attack techniques (optional)

Hide technique attributes Show technique attributes object

id string Required

Technique ID

name string Required

Technique name

reference string Required

Technique reference

subtechnique array[object]

Array containing more specific information on the attack technique.

Hide subtechnique attributes Show subtechnique attributes object

id string Required

Subtechnique ID

name string Required

Subtechnique name

reference string Required

Subtechnique reference

throttle string | null

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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 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.

It is not incremented on each update. Compare this to the revision field.

Minimum value is 1.

created_at string(date-time) Required

created_by string Required

execution_summary object

Summary of the last execution of a rule.

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

Hide execution_summary attribute Show execution_summary attribute object

last_execution object Required

Hide last_execution attributes Show last_execution attributes object

date string(date-time) Required

Date of the last execution

message string Required

metrics object Required

Hide metrics attributes Show metrics attributes object

execution_gap_duration_s integer

Duration in seconds of execution gap

Minimum value is 0.

frozen_indices_queried_count integer

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

Minimum value is 0.

gap_range object

Range of the execution gap

Hide gap_range attributes Show gap_range attributes object

gte string Required

Start date of the execution gap

lte string Required

End date of the execution gap

total_enrichment_duration_ms integer

Total time spent enriching documents during current rule execution cycle

Minimum value is 0.

total_indexing_duration_ms integer

Total time spent indexing documents during current rule execution cycle

Minimum value is 0.

total_search_duration_ms integer

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

Minimum value is 0.

status string Required

Status of the last execution

Values are going to run, running, partial failure, failed, or succeeded.

status_order integer Required

id string(uuid) Required

A dynamic unique identifier for the rule object. It is randomly generated when a rule is created and cannot be changed after that. It is always a UUID. It is unique within a given Kibana space. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have different object ids.

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

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.

Minimum value is 0.

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 object 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:
Security_Detections_API_ExternalRuleSource object Security_Detections_API_InternalRuleSource object

Type of rule source for externally sourced rules, i.e. rules that have an external source, such as the Elastic Prebuilt rules repo.

Hide attributes Show attributes

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

type string Required Discriminator

Value is external.

updated_at string(date-time) Required

updated_by string Required

saved_id string Required

Kibana saved search used by the rule to create alerts.

type string Required Discriminator

Rule type

Value is saved_query.

alert_suppression object

Defines alert suppression configuration.

Hide alert_suppression attributes Show alert_suppression attributes object

duration object

Hide duration attributes Show duration attributes object

unit string Required

Time unit

Values are s, m, or h.

value integer Required

Minimum value is 1.

group_by array[string] Required

At least 1 but not more than 3 elements.

missing_fields_strategy string

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 are doNotSuppress or suppress.

data_view_id string

filters array

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

query string

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.

language string Required

Values are kuery or lucene.
Hide attributes Show attributes

actions array[object] Required

Array defining the automated actions (notifications) taken when alerts are generated.

Hide actions attributes Show actions attributes object

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.

Additional properties are allowed.

frequency object

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

Hide frequency attributes Show frequency attributes object

notifyWhen string Required

Defines how often rules run actions.

Values are onActiveAlert, onThrottleInterval, or 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 string | null Required

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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.

Additional properties are allowed.

uuid string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

alias_purpose string

Values are savedObjectConversion or savedObjectImport.

alias_target_id string

author array[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 Required

The rule’s description.

Minimum length is 1.

enabled boolean Required

Determines whether the rule is enabled. Defaults to true.

exceptions_list array[object] Required

Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.

Hide exceptions_list attributes Show exceptions_list attributes object

id string(nonempty) Required

ID of the exception container

Minimum length is 1.

list_id string(nonempty) Required

List ID of the exception container

Minimum length is 1.

namespace_type string Required

Determines the exceptions validity in rule's Kibana space

Values are agnostic or single.

type string Required

The exception type

Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.

false_positives array[string] Required

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.

from string(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.

Hide investigation_fields attribute Show investigation_fields attribute object

field_names array[string(nonempty)] Required

A string that does not contain only whitespace characters

At least 1 element. Minimum length of each is 1.

license string

The rule's license.

max_signals integer Required

Maximum number of alerts the rule can create during a single run (the rule’s Max alerts per run advanced setting value).

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.

Minimum value is 1. Default value is 100.

meta object

Placeholder for metadata about the rule.

This field is overwritten when you save changes to the rule’s settings.

Additional properties are allowed.

name string Required

A human-readable name for the rule.

Minimum length is 1.

namespace string

Has no effect.

note string

Notes to help investigate alerts produced by the rule.

outcome string

Values are exactMatch, aliasMatch, or conflict.

output_index string Deprecated

(deprecated) Has no effect.

references array[string] Required

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.

related_integrations array[object] Required

Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:

package: name of the package (required, unique id)

version: version of the package (required, semver-compatible)

integration: name of the integration of this package (optional, id within the package)

There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.

Hide related_integrations attributes Show related_integrations attributes object

integration string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

package string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

version string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

required_fields array[object] Required

Elasticsearch fields and their types that need to be present for the rule to function.

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.

Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.

Hide required_fields attributes Show required_fields attributes object

name string(nonempty) Required

Name of an Elasticsearch field

Minimum length is 1.

type string(nonempty) Required

Type of the Elasticsearch field

Minimum length is 1.

response_actions array[object]

One of:
Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object

Hide attributes Show attributes

action_type_id string Required

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

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

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[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.

Hide attributes Show attributes

action_type_id string Required

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object

Hide attributes Show attributes

command string Required

Value is isolate.

comment string

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.

risk_score integer 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

Minimum value is 0, maximum value is 100.

risk_score_mapping array[object] Required

Overrides generated alerts' risk_score with a value from the source event

Hide risk_score_mapping attributes Show risk_score_mapping attributes object

field string Required

Source event field used to override the default risk_score.

operator string Required

Value is equals.

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

Minimum value is 0, maximum value is 100.

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 string 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 are low, medium, high, or critical.

severity_mapping array[object] Required

Overrides generated alerts' severity with values from the source event

Hide severity_mapping attributes Show severity_mapping attributes object

field string Required

Source event field used to override the default severity.

operator string Required

Value is equals.

severity string 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 are low, medium, high, or critical.

value string Required

tags array[string] Required

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.

threat array[object] Required

Currently, only threats described using the MITRE ATT&CK™ framework are supported.

Hide threat attributes Show threat attributes object

framework string Required

Relevant attack framework

tactic object Required

Object containing information on the attack type

Hide tactic attributes Show tactic attributes object

id string Required

Tactic ID

name string Required

Tactic name

reference string Required

Tactic reference

technique array[object]

Array containing information on the attack techniques (optional)

Hide technique attributes Show technique attributes object

id string Required

Technique ID

name string Required

Technique name

reference string Required

Technique reference

subtechnique array[object]

Array containing more specific information on the attack technique.

Hide subtechnique attributes Show subtechnique attributes object

id string Required

Subtechnique ID

name string Required

Subtechnique name

reference string Required

Subtechnique reference

throttle string | null

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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 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.

It is not incremented on each update. Compare this to the revision field.

Minimum value is 1.

created_at string(date-time) Required

created_by string Required

execution_summary object

Summary of the last execution of a rule.

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

Hide execution_summary attribute Show execution_summary attribute object

last_execution object Required

Hide last_execution attributes Show last_execution attributes object

date string(date-time) Required

Date of the last execution

message string Required

metrics object Required

Hide metrics attributes Show metrics attributes object

execution_gap_duration_s integer

Duration in seconds of execution gap

Minimum value is 0.

frozen_indices_queried_count integer

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

Minimum value is 0.

gap_range object

Range of the execution gap

Hide gap_range attributes Show gap_range attributes object

gte string Required

Start date of the execution gap

lte string Required

End date of the execution gap

total_enrichment_duration_ms integer

Total time spent enriching documents during current rule execution cycle

Minimum value is 0.

total_indexing_duration_ms integer

Total time spent indexing documents during current rule execution cycle

Minimum value is 0.

total_search_duration_ms integer

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

Minimum value is 0.

status string Required

Status of the last execution

Values are going to run, running, partial failure, failed, or succeeded.

status_order integer Required

id string(uuid) Required

A dynamic unique identifier for the rule object. It is randomly generated when a rule is created and cannot be changed after that. It is always a UUID. It is unique within a given Kibana space. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have different object ids.

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

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.

Minimum value is 0.

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 object 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:
Security_Detections_API_ExternalRuleSource object Security_Detections_API_InternalRuleSource object

Type of rule source for externally sourced rules, i.e. rules that have an external source, such as the Elastic Prebuilt rules repo.

Hide attributes Show attributes

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

type string Required Discriminator

Value is external.

updated_at string(date-time) Required

updated_by string Required

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.

threshold object Required

Hide threshold attributes Show threshold attributes object

cardinality array[object]

The field on which the cardinality is applied.

Hide cardinality attributes Show cardinality attributes object

field string Required

The field on which to calculate and compare the cardinality.

value integer Required

The threshold value from which an alert is generated based on unique number of values of cardinality.field.

Minimum value is 0.

field string | array[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.

One of:
string-1 string array-2 array[string]

value integer Required

The threshold value from which an alert is generated.

Minimum value is 1.

type string Required Discriminator

Rule type

Value is threshold.

alert_suppression object

Defines alert suppression configuration.

Hide alert_suppression attribute Show alert_suppression attribute object

duration object Required

Hide duration attributes Show duration attributes object

unit string Required

Time unit

Values are s, m, or h.

value integer Required

Minimum value is 1.

data_view_id string

filters array

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

saved_id string

Kibana saved search used by the rule to create alerts.

language string Required

Values are kuery or lucene.
Hide attributes Show attributes

actions array[object] Required

Array defining the automated actions (notifications) taken when alerts are generated.

Hide actions attributes Show actions attributes object

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.

Additional properties are allowed.

frequency object

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

Hide frequency attributes Show frequency attributes object

notifyWhen string Required

Defines how often rules run actions.

Values are onActiveAlert, onThrottleInterval, or 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 string | null Required

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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.

Additional properties are allowed.

uuid string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

alias_purpose string

Values are savedObjectConversion or savedObjectImport.

alias_target_id string

author array[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 Required

The rule’s description.

Minimum length is 1.

enabled boolean Required

Determines whether the rule is enabled. Defaults to true.

exceptions_list array[object] Required

Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.

Hide exceptions_list attributes Show exceptions_list attributes object

id string(nonempty) Required

ID of the exception container

Minimum length is 1.

list_id string(nonempty) Required

List ID of the exception container

Minimum length is 1.

namespace_type string Required

Determines the exceptions validity in rule's Kibana space

Values are agnostic or single.

type string Required

The exception type

Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.

false_positives array[string] Required

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.

from string(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.

Hide investigation_fields attribute Show investigation_fields attribute object

field_names array[string(nonempty)] Required

A string that does not contain only whitespace characters

At least 1 element. Minimum length of each is 1.

license string

The rule's license.

max_signals integer Required

Maximum number of alerts the rule can create during a single run (the rule’s Max alerts per run advanced setting value).

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.

Minimum value is 1. Default value is 100.

meta object

Placeholder for metadata about the rule.

This field is overwritten when you save changes to the rule’s settings.

Additional properties are allowed.

name string Required

A human-readable name for the rule.

Minimum length is 1.

namespace string

Has no effect.

note string

Notes to help investigate alerts produced by the rule.

outcome string

Values are exactMatch, aliasMatch, or conflict.

output_index string Deprecated

(deprecated) Has no effect.

references array[string] Required

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.

related_integrations array[object] Required

Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:

package: name of the package (required, unique id)

version: version of the package (required, semver-compatible)

integration: name of the integration of this package (optional, id within the package)

There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.

Hide related_integrations attributes Show related_integrations attributes object

integration string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

package string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

version string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

required_fields array[object] Required

Elasticsearch fields and their types that need to be present for the rule to function.

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.

Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.

Hide required_fields attributes Show required_fields attributes object

name string(nonempty) Required

Name of an Elasticsearch field

Minimum length is 1.

type string(nonempty) Required

Type of the Elasticsearch field

Minimum length is 1.

response_actions array[object]

One of:
Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object

Hide attributes Show attributes

action_type_id string Required

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

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

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[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.

Hide attributes Show attributes

action_type_id string Required

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object

Hide attributes Show attributes

command string Required

Value is isolate.

comment string

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.

risk_score integer 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

Minimum value is 0, maximum value is 100.

risk_score_mapping array[object] Required

Overrides generated alerts' risk_score with a value from the source event

Hide risk_score_mapping attributes Show risk_score_mapping attributes object

field string Required

Source event field used to override the default risk_score.

operator string Required

Value is equals.

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

Minimum value is 0, maximum value is 100.

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 string 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 are low, medium, high, or critical.

severity_mapping array[object] Required

Overrides generated alerts' severity with values from the source event

Hide severity_mapping attributes Show severity_mapping attributes object

field string Required

Source event field used to override the default severity.

operator string Required

Value is equals.

severity string 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 are low, medium, high, or critical.

value string Required

tags array[string] Required

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.

threat array[object] Required

Currently, only threats described using the MITRE ATT&CK™ framework are supported.

Hide threat attributes Show threat attributes object

framework string Required

Relevant attack framework

tactic object Required

Object containing information on the attack type

Hide tactic attributes Show tactic attributes object

id string Required

Tactic ID

name string Required

Tactic name

reference string Required

Tactic reference

technique array[object]

Array containing information on the attack techniques (optional)

Hide technique attributes Show technique attributes object

id string Required

Technique ID

name string Required

Technique name

reference string Required

Technique reference

subtechnique array[object]

Array containing more specific information on the attack technique.

Hide subtechnique attributes Show subtechnique attributes object

id string Required

Subtechnique ID

name string Required

Subtechnique name

reference string Required

Subtechnique reference

throttle string | null

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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 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.

It is not incremented on each update. Compare this to the revision field.

Minimum value is 1.

created_at string(date-time) Required

created_by string Required

execution_summary object

Summary of the last execution of a rule.

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

Hide execution_summary attribute Show execution_summary attribute object

last_execution object Required

Hide last_execution attributes Show last_execution attributes object

date string(date-time) Required

Date of the last execution

message string Required

metrics object Required

Hide metrics attributes Show metrics attributes object

execution_gap_duration_s integer

Duration in seconds of execution gap

Minimum value is 0.

frozen_indices_queried_count integer

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

Minimum value is 0.

gap_range object

Range of the execution gap

Hide gap_range attributes Show gap_range attributes object

gte string Required

Start date of the execution gap

lte string Required

End date of the execution gap

total_enrichment_duration_ms integer

Total time spent enriching documents during current rule execution cycle

Minimum value is 0.

total_indexing_duration_ms integer

Total time spent indexing documents during current rule execution cycle

Minimum value is 0.

total_search_duration_ms integer

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

Minimum value is 0.

status string Required

Status of the last execution

Values are going to run, running, partial failure, failed, or succeeded.

status_order integer Required

id string(uuid) Required

A dynamic unique identifier for the rule object. It is randomly generated when a rule is created and cannot be changed after that. It is always a UUID. It is unique within a given Kibana space. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have different object ids.

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

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.

Minimum value is 0.

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 object 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:
Security_Detections_API_ExternalRuleSource object Security_Detections_API_InternalRuleSource object

Type of rule source for externally sourced rules, i.e. rules that have an external source, such as the Elastic Prebuilt rules repo.

Hide attributes Show attributes

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

type string Required Discriminator

Value is external.

updated_at string(date-time) Required

updated_by string Required

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.

threat_index array[string] Required

Elasticsearch indices used to check which field values generate alerts.

threat_mapping array[object] Required

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 Example of Threat Match rule which uses both and and or logic.

At least 1 element.

Hide threat_mapping attribute Show threat_mapping attribute object

entries array[object] Required

Hide entries attributes Show entries attributes object

field string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

type string Required

Value is mapping.

value string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

threat_query string Required

Query used to determine which fields in the Elasticsearch index are used for generating alerts.

type string Required Discriminator

Rule type

Value is threat_match.

alert_suppression object

Defines alert suppression configuration.

Hide alert_suppression attributes Show alert_suppression attributes object

duration object

Hide duration attributes Show duration attributes object

unit string Required

Time unit

Values are s, m, or h.

value integer Required

Minimum value is 1.

group_by array[string] Required

At least 1 but not more than 3 elements.

missing_fields_strategy string

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 are doNotSuppress or suppress.

concurrent_searches integer

Minimum value is 1.

data_view_id string

filters array

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

items_per_search integer

Minimum value is 1.

saved_id string

Kibana saved search used by the rule to create alerts.

threat_filters array

Query and filter context array used to filter documents from the Elasticsearch index containing the threat values

threat_indicator_path string

Defines the path to the threat indicator in the indicator documents (optional)

threat_language string

Values are kuery or lucene.

language string Required

Values are kuery or lucene.
Hide attributes Show attributes

actions array[object] Required

Array defining the automated actions (notifications) taken when alerts are generated.

Hide actions attributes Show actions attributes object

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.

Additional properties are allowed.

frequency object

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

Hide frequency attributes Show frequency attributes object

notifyWhen string Required

Defines how often rules run actions.

Values are onActiveAlert, onThrottleInterval, or 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 string | null Required

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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.

Additional properties are allowed.

uuid string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

alias_purpose string

Values are savedObjectConversion or savedObjectImport.

alias_target_id string

author array[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 Required

The rule’s description.

Minimum length is 1.

enabled boolean Required

Determines whether the rule is enabled. Defaults to true.

exceptions_list array[object] Required

Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.

Hide exceptions_list attributes Show exceptions_list attributes object

id string(nonempty) Required

ID of the exception container

Minimum length is 1.

list_id string(nonempty) Required

List ID of the exception container

Minimum length is 1.

namespace_type string Required

Determines the exceptions validity in rule's Kibana space

Values are agnostic or single.

type string Required

The exception type

Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.

false_positives array[string] Required

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.

from string(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.

Hide investigation_fields attribute Show investigation_fields attribute object

field_names array[string(nonempty)] Required

A string that does not contain only whitespace characters

At least 1 element. Minimum length of each is 1.

license string

The rule's license.

max_signals integer Required

Maximum number of alerts the rule can create during a single run (the rule’s Max alerts per run advanced setting value).

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.

Minimum value is 1. Default value is 100.

meta object

Placeholder for metadata about the rule.

This field is overwritten when you save changes to the rule’s settings.

Additional properties are allowed.

name string Required

A human-readable name for the rule.

Minimum length is 1.

namespace string

Has no effect.

note string

Notes to help investigate alerts produced by the rule.

outcome string

Values are exactMatch, aliasMatch, or conflict.

output_index string Deprecated

(deprecated) Has no effect.

references array[string] Required

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.

related_integrations array[object] Required

Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:

package: name of the package (required, unique id)

version: version of the package (required, semver-compatible)

integration: name of the integration of this package (optional, id within the package)

There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.

Hide related_integrations attributes Show related_integrations attributes object

integration string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

package string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

version string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

required_fields array[object] Required

Elasticsearch fields and their types that need to be present for the rule to function.

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.

Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.

Hide required_fields attributes Show required_fields attributes object

name string(nonempty) Required

Name of an Elasticsearch field

Minimum length is 1.

type string(nonempty) Required

Type of the Elasticsearch field

Minimum length is 1.

response_actions array[object]

One of:
Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object

Hide attributes Show attributes

action_type_id string Required

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

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

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[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.

Hide attributes Show attributes

action_type_id string Required

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object

Hide attributes Show attributes

command string Required

Value is isolate.

comment string

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.

risk_score integer 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

Minimum value is 0, maximum value is 100.

risk_score_mapping array[object] Required

Overrides generated alerts' risk_score with a value from the source event

Hide risk_score_mapping attributes Show risk_score_mapping attributes object

field string Required

Source event field used to override the default risk_score.

operator string Required

Value is equals.

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

Minimum value is 0, maximum value is 100.

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 string 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 are low, medium, high, or critical.

severity_mapping array[object] Required

Overrides generated alerts' severity with values from the source event

Hide severity_mapping attributes Show severity_mapping attributes object

field string Required

Source event field used to override the default severity.

operator string Required

Value is equals.

severity string 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 are low, medium, high, or critical.

value string Required

tags array[string] Required

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.

threat array[object] Required

Currently, only threats described using the MITRE ATT&CK™ framework are supported.

Hide threat attributes Show threat attributes object

framework string Required

Relevant attack framework

tactic object Required

Object containing information on the attack type

Hide tactic attributes Show tactic attributes object

id string Required

Tactic ID

name string Required

Tactic name

reference string Required

Tactic reference

technique array[object]

Array containing information on the attack techniques (optional)

Hide technique attributes Show technique attributes object

id string Required

Technique ID

name string Required

Technique name

reference string Required

Technique reference

subtechnique array[object]

Array containing more specific information on the attack technique.

Hide subtechnique attributes Show subtechnique attributes object

id string Required

Subtechnique ID

name string Required

Subtechnique name

reference string Required

Subtechnique reference

throttle string | null

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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 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.

It is not incremented on each update. Compare this to the revision field.

Minimum value is 1.

created_at string(date-time) Required

created_by string Required

execution_summary object

Summary of the last execution of a rule.

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

Hide execution_summary attribute Show execution_summary attribute object

last_execution object Required

Hide last_execution attributes Show last_execution attributes object

date string(date-time) Required

Date of the last execution

message string Required

metrics object Required

Hide metrics attributes Show metrics attributes object

execution_gap_duration_s integer

Duration in seconds of execution gap

Minimum value is 0.

frozen_indices_queried_count integer

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

Minimum value is 0.

gap_range object

Range of the execution gap

Hide gap_range attributes Show gap_range attributes object

gte string Required

Start date of the execution gap

lte string Required

End date of the execution gap

total_enrichment_duration_ms integer

Total time spent enriching documents during current rule execution cycle

Minimum value is 0.

total_indexing_duration_ms integer

Total time spent indexing documents during current rule execution cycle

Minimum value is 0.

total_search_duration_ms integer

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

Minimum value is 0.

status string Required

Status of the last execution

Values are going to run, running, partial failure, failed, or succeeded.

status_order integer Required

id string(uuid) Required

A dynamic unique identifier for the rule object. It is randomly generated when a rule is created and cannot be changed after that. It is always a UUID. It is unique within a given Kibana space. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have different object ids.

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

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.

Minimum value is 0.

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 object 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:
Security_Detections_API_ExternalRuleSource object Security_Detections_API_InternalRuleSource object

Type of rule source for externally sourced rules, i.e. rules that have an external source, such as the Elastic Prebuilt rules repo.

Hide attributes Show attributes

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

type string Required Discriminator

Value is external.

updated_at string(date-time) Required

updated_by string Required

anomaly_threshold integer Required

Anomaly score threshold above which the rule creates an alert. Valid values are from 0 to 100.

Minimum value is 0.

machine_learning_job_id string | array[string] Required

Machine learning job ID(s) the rule monitors for anomaly scores.

One of:
string-1 string array-2 array[string]

type string Required Discriminator

Rule type

Value is machine_learning.

alert_suppression object

Defines alert suppression configuration.

Hide alert_suppression attributes Show alert_suppression attributes object

duration object

Hide duration attributes Show duration attributes object

unit string Required

Time unit

Values are s, m, or h.

value integer Required

Minimum value is 1.

group_by array[string] Required

At least 1 but not more than 3 elements.

missing_fields_strategy string

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 are doNotSuppress or suppress.
Hide attributes Show attributes

actions array[object] Required

Array defining the automated actions (notifications) taken when alerts are generated.

Hide actions attributes Show actions attributes object

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.

Additional properties are allowed.

frequency object

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

Hide frequency attributes Show frequency attributes object

notifyWhen string Required

Defines how often rules run actions.

Values are onActiveAlert, onThrottleInterval, or 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 string | null Required

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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.

Additional properties are allowed.

uuid string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

alias_purpose string

Values are savedObjectConversion or savedObjectImport.

alias_target_id string

author array[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 Required

The rule’s description.

Minimum length is 1.

enabled boolean Required

Determines whether the rule is enabled. Defaults to true.

exceptions_list array[object] Required

Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.

Hide exceptions_list attributes Show exceptions_list attributes object

id string(nonempty) Required

ID of the exception container

Minimum length is 1.

list_id string(nonempty) Required

List ID of the exception container

Minimum length is 1.

namespace_type string Required

Determines the exceptions validity in rule's Kibana space

Values are agnostic or single.

type string Required

The exception type

Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.

false_positives array[string] Required

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.

from string(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.

Hide investigation_fields attribute Show investigation_fields attribute object

field_names array[string(nonempty)] Required

A string that does not contain only whitespace characters

At least 1 element. Minimum length of each is 1.

license string

The rule's license.

max_signals integer Required

Maximum number of alerts the rule can create during a single run (the rule’s Max alerts per run advanced setting value).

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.

Minimum value is 1. Default value is 100.

meta object

Placeholder for metadata about the rule.

This field is overwritten when you save changes to the rule’s settings.

Additional properties are allowed.

name string Required

A human-readable name for the rule.

Minimum length is 1.

namespace string

Has no effect.

note string

Notes to help investigate alerts produced by the rule.

outcome string

Values are exactMatch, aliasMatch, or conflict.

output_index string Deprecated

(deprecated) Has no effect.

references array[string] Required

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.

related_integrations array[object] Required

Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:

package: name of the package (required, unique id)

version: version of the package (required, semver-compatible)

integration: name of the integration of this package (optional, id within the package)

There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.

Hide related_integrations attributes Show related_integrations attributes object

integration string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

package string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

version string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

required_fields array[object] Required

Elasticsearch fields and their types that need to be present for the rule to function.

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.

Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.

Hide required_fields attributes Show required_fields attributes object

name string(nonempty) Required

Name of an Elasticsearch field

Minimum length is 1.

type string(nonempty) Required

Type of the Elasticsearch field

Minimum length is 1.

response_actions array[object]

One of:
Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object

Hide attributes Show attributes

action_type_id string Required

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

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

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[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.

Hide attributes Show attributes

action_type_id string Required

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object

Hide attributes Show attributes

command string Required

Value is isolate.

comment string

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.

risk_score integer 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

Minimum value is 0, maximum value is 100.

risk_score_mapping array[object] Required

Overrides generated alerts' risk_score with a value from the source event

Hide risk_score_mapping attributes Show risk_score_mapping attributes object

field string Required

Source event field used to override the default risk_score.

operator string Required

Value is equals.

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

Minimum value is 0, maximum value is 100.

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 string 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 are low, medium, high, or critical.

severity_mapping array[object] Required

Overrides generated alerts' severity with values from the source event

Hide severity_mapping attributes Show severity_mapping attributes object

field string Required

Source event field used to override the default severity.

operator string Required

Value is equals.

severity string 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 are low, medium, high, or critical.

value string Required

tags array[string] Required

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.

threat array[object] Required

Currently, only threats described using the MITRE ATT&CK™ framework are supported.

Hide threat attributes Show threat attributes object

framework string Required

Relevant attack framework

tactic object Required

Object containing information on the attack type

Hide tactic attributes Show tactic attributes object

id string Required

Tactic ID

name string Required

Tactic name

reference string Required

Tactic reference

technique array[object]

Array containing information on the attack techniques (optional)

Hide technique attributes Show technique attributes object

id string Required

Technique ID

name string Required

Technique name

reference string Required

Technique reference

subtechnique array[object]

Array containing more specific information on the attack technique.

Hide subtechnique attributes Show subtechnique attributes object

id string Required

Subtechnique ID

name string Required

Subtechnique name

reference string Required

Subtechnique reference

throttle string | null

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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 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.

It is not incremented on each update. Compare this to the revision field.

Minimum value is 1.

created_at string(date-time) Required

created_by string Required

execution_summary object

Summary of the last execution of a rule.

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

Hide execution_summary attribute Show execution_summary attribute object

last_execution object Required

Hide last_execution attributes Show last_execution attributes object

date string(date-time) Required

Date of the last execution

message string Required

metrics object Required

Hide metrics attributes Show metrics attributes object

execution_gap_duration_s integer

Duration in seconds of execution gap

Minimum value is 0.

frozen_indices_queried_count integer

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

Minimum value is 0.

gap_range object

Range of the execution gap

Hide gap_range attributes Show gap_range attributes object

gte string Required

Start date of the execution gap

lte string Required

End date of the execution gap

total_enrichment_duration_ms integer

Total time spent enriching documents during current rule execution cycle

Minimum value is 0.

total_indexing_duration_ms integer

Total time spent indexing documents during current rule execution cycle

Minimum value is 0.

total_search_duration_ms integer

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

Minimum value is 0.

status string Required

Status of the last execution

Values are going to run, running, partial failure, failed, or succeeded.

status_order integer Required

id string(uuid) Required

A dynamic unique identifier for the rule object. It is randomly generated when a rule is created and cannot be changed after that. It is always a UUID. It is unique within a given Kibana space. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have different object ids.

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

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.

Minimum value is 0.

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 object 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:
Security_Detections_API_ExternalRuleSource object Security_Detections_API_InternalRuleSource object

Type of rule source for externally sourced rules, i.e. rules that have an external source, such as the Elastic Prebuilt rules repo.

Hide attributes Show attributes

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

type string Required Discriminator

Value is external.

updated_at string(date-time) Required

updated_by string Required

history_window_start string(nonempty) Required

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.

Minimum length is 1.

new_terms_fields array[string] Required

Fields to monitor for new values.

At least 1 but not more than 3 elements.

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.

type string Required Discriminator

Rule type

Value is new_terms.

alert_suppression object

Defines alert suppression configuration.

Hide alert_suppression attributes Show alert_suppression attributes object

duration object

Hide duration attributes Show duration attributes object

unit string Required

Time unit

Values are s, m, or h.

value integer Required

Minimum value is 1.

group_by array[string] Required

At least 1 but not more than 3 elements.

missing_fields_strategy string

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 are doNotSuppress or suppress.

data_view_id string

filters array

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

language string Required

Values are kuery or lucene.
Hide attributes Show attributes

actions array[object] Required

Array defining the automated actions (notifications) taken when alerts are generated.

Hide actions attributes Show actions attributes object

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.

Additional properties are allowed.

frequency object

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

Hide frequency attributes Show frequency attributes object

notifyWhen string Required

Defines how often rules run actions.

Values are onActiveAlert, onThrottleInterval, or 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 string | null Required

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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.

Additional properties are allowed.

uuid string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

alias_purpose string

Values are savedObjectConversion or savedObjectImport.

alias_target_id string

author array[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 Required

The rule’s description.

Minimum length is 1.

enabled boolean Required

Determines whether the rule is enabled. Defaults to true.

exceptions_list array[object] Required

Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.

Hide exceptions_list attributes Show exceptions_list attributes object

id string(nonempty) Required

ID of the exception container

Minimum length is 1.

list_id string(nonempty) Required

List ID of the exception container

Minimum length is 1.

namespace_type string Required

Determines the exceptions validity in rule's Kibana space

Values are agnostic or single.

type string Required

The exception type

Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.

false_positives array[string] Required

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.

from string(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.

Hide investigation_fields attribute Show investigation_fields attribute object

field_names array[string(nonempty)] Required

A string that does not contain only whitespace characters

At least 1 element. Minimum length of each is 1.

license string

The rule's license.

max_signals integer Required

Maximum number of alerts the rule can create during a single run (the rule’s Max alerts per run advanced setting value).

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.

Minimum value is 1. Default value is 100.

meta object

Placeholder for metadata about the rule.

This field is overwritten when you save changes to the rule’s settings.

Additional properties are allowed.

name string Required

A human-readable name for the rule.

Minimum length is 1.

namespace string

Has no effect.

note string

Notes to help investigate alerts produced by the rule.

outcome string

Values are exactMatch, aliasMatch, or conflict.

output_index string Deprecated

(deprecated) Has no effect.

references array[string] Required

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.

related_integrations array[object] Required

Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:

package: name of the package (required, unique id)

version: version of the package (required, semver-compatible)

integration: name of the integration of this package (optional, id within the package)

There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.

Hide related_integrations attributes Show related_integrations attributes object

integration string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

package string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

version string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

required_fields array[object] Required

Elasticsearch fields and their types that need to be present for the rule to function.

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.

Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.

Hide required_fields attributes Show required_fields attributes object

name string(nonempty) Required

Name of an Elasticsearch field

Minimum length is 1.

type string(nonempty) Required

Type of the Elasticsearch field

Minimum length is 1.

response_actions array[object]

One of:
Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object

Hide attributes Show attributes

action_type_id string Required

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

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

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[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.

Hide attributes Show attributes

action_type_id string Required

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object

Hide attributes Show attributes

command string Required

Value is isolate.

comment string

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.

risk_score integer 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

Minimum value is 0, maximum value is 100.

risk_score_mapping array[object] Required

Overrides generated alerts' risk_score with a value from the source event

Hide risk_score_mapping attributes Show risk_score_mapping attributes object

field string Required

Source event field used to override the default risk_score.

operator string Required

Value is equals.

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

Minimum value is 0, maximum value is 100.

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 string 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 are low, medium, high, or critical.

severity_mapping array[object] Required

Overrides generated alerts' severity with values from the source event

Hide severity_mapping attributes Show severity_mapping attributes object

field string Required

Source event field used to override the default severity.

operator string Required

Value is equals.

severity string 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 are low, medium, high, or critical.

value string Required

tags array[string] Required

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.

threat array[object] Required

Currently, only threats described using the MITRE ATT&CK™ framework are supported.

Hide threat attributes Show threat attributes object

framework string Required

Relevant attack framework

tactic object Required

Object containing information on the attack type

Hide tactic attributes Show tactic attributes object

id string Required

Tactic ID

name string Required

Tactic name

reference string Required

Tactic reference

technique array[object]

Array containing information on the attack techniques (optional)

Hide technique attributes Show technique attributes object

id string Required

Technique ID

name string Required

Technique name

reference string Required

Technique reference

subtechnique array[object]

Array containing more specific information on the attack technique.

Hide subtechnique attributes Show subtechnique attributes object

id string Required

Subtechnique ID

name string Required

Subtechnique name

reference string Required

Subtechnique reference

throttle string | null

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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 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.

It is not incremented on each update. Compare this to the revision field.

Minimum value is 1.

created_at string(date-time) Required

created_by string Required

execution_summary object

Summary of the last execution of a rule.

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

Hide execution_summary attribute Show execution_summary attribute object

last_execution object Required

Hide last_execution attributes Show last_execution attributes object

date string(date-time) Required

Date of the last execution

message string Required

metrics object Required

Hide metrics attributes Show metrics attributes object

execution_gap_duration_s integer

Duration in seconds of execution gap

Minimum value is 0.

frozen_indices_queried_count integer

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

Minimum value is 0.

gap_range object

Range of the execution gap

Hide gap_range attributes Show gap_range attributes object

gte string Required

Start date of the execution gap

lte string Required

End date of the execution gap

total_enrichment_duration_ms integer

Total time spent enriching documents during current rule execution cycle

Minimum value is 0.

total_indexing_duration_ms integer

Total time spent indexing documents during current rule execution cycle

Minimum value is 0.

total_search_duration_ms integer

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

Minimum value is 0.

status string Required

Status of the last execution

Values are going to run, running, partial failure, failed, or succeeded.

status_order integer Required

id string(uuid) Required

A dynamic unique identifier for the rule object. It is randomly generated when a rule is created and cannot be changed after that. It is always a UUID. It is unique within a given Kibana space. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have different object ids.

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

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.

Minimum value is 0.

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 object 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:
Security_Detections_API_ExternalRuleSource object Security_Detections_API_InternalRuleSource object

Type of rule source for externally sourced rules, i.e. rules that have an external source, such as the Elastic Prebuilt rules repo.

Hide attributes Show attributes

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

type string Required Discriminator

Value is external.

updated_at string(date-time) Required

updated_by string Required

alert_suppression object

Defines alert suppression configuration.

Hide alert_suppression attributes Show alert_suppression attributes object

duration object

Hide duration attributes Show duration attributes object

unit string Required

Time unit

Values are s, m, or h.

value integer Required

Minimum value is 1.

group_by array[string] Required

At least 1 but not more than 3 elements.

missing_fields_strategy string

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 are doNotSuppress or suppress.

language string Required

Value is esql.

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.

type string Required Discriminator

Rule type

Value is esql.

POST /api/detection_engine/rules

curl \
 --request POST 'https://<KIBANA_URL>/api/detection_engine/rules' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"from":"now-70m","name":"MS Office child process","tags":["child process","ms office"],"type":"query","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","enabled":false,"filters":[{"query":{"match":{"event.action":{"type":"phrase","query":"Process Create (rule: ProcessCreate)"}}}}],"rule_id":"process_started_by_ms_office_program","interval":"1h","language":"kuery","severity":"low","risk_score":50,"description":"Process started by MS Office program - possible payload","required_fields":[{"name":"process.parent.name","type":"keyword"}],"related_integrations":[{"package":"o365","version":"^2.3.2"}]}'

Request examples

Query rule that searches for processes started by MS Office

{
  "from": "now-70m",
  "name": "MS Office child process",
  "tags": [
    "child process",
    "ms office"
  ],
  "type": "query",
  "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",
  "enabled": false,
  "filters": [
    {
      "query": {
        "match": {
          "event.action": {
            "type": "phrase",
            "query": "Process Create (rule: ProcessCreate)"
          }
        }
      }
    }
  ],
  "rule_id": "process_started_by_ms_office_program",
  "interval": "1h",
  "language": "kuery",
  "severity": "low",
  "risk_score": 50,
  "description": "Process started by MS Office program - possible payload",
  "required_fields": [
    {
      "name": "process.parent.name",
      "type": "keyword"
    }
  ],
  "related_integrations": [
    {
      "package": "o365",
      "version": "^2.3.2"
    }
  ]
}

Threshold rule that detects multiple failed login attempts to a Windows host from the same external source IP address

{
  "from": "now-180s",
  "name": "Windows server prml-19",
  "tags": [
    "Brute force"
  ],
  "type": "threshold",
  "index": [
    "winlogbeat-*"
  ],
  "query": "host.name:prml-19 and event.category:authentication and event.outcome:failure",
  "enabled": true,
  "rule_id": "liv-win-ser-logins",
  "interval": "2m",
  "severity": "low",
  "threshold": {
    "field": "source.ip",
    "value": 20
  },
  "risk_score": 30,
  "description": "Detects when there are 20 or more failed login attempts from the same IP address with a 2 minute time frame.",
  "exceptions_list": [
    {
      "id": "int-ips",
      "type": "detection",
      "namespace_type": "single"
    }
  ],
  "required_fields": [
    {
      "name": "source.ip",
      "type": "ip"
    }
  ],
  "severity_mapping": [
    {
      "field": "source.geo.city_name",
      "value": "Manchester",
      "operator": "equals",
      "severity": "low"
    },
    {
      "field": "source.geo.city_name",
      "value": "London",
      "operator": "equals",
      "severity": "medium"
    },
    {
      "field": "source.geo.city_name",
      "value": "Birmingham",
      "operator": "equals",
      "severity": "high"
    },
    {
      "field": "source.geo.city_name",
      "value": "Wallingford",
      "operator": "equals",
      "severity": "critical"
    }
  ]
}

Machine learning rule that creates alerts, and sends Slack notifications, when the linux_anomalous_network_activity_ecs machine learning job discovers anomalies with a threshold of 70 or above.

{
  "from": "now-6m",
  "name": "Anomalous Linux network activity",
  "note": "Shut down the internet.",
  "tags": [
    "machine learning",
    "Linux"
  ],
  "type": "machine_learning",
  "setup": "This rule requires data coming in from Elastic Defend.",
  "actions": [
    {
      "id": "5ad22cd5-5e6e-4c6c-a81a-54b626a4cec5",
      "group": "default",
      "params": {
        "message": "Urgent: {{context.rule.description}}"
      },
      "action_type_id": ".slack"
    }
  ],
  "enabled": true,
  "rule_id": "ml_linux_network_high_threshold",
  "interval": "5m",
  "severity": "high",
  "risk_score": 70,
  "description": "Generates alerts when the job discovers anomalies over 70",
  "anomaly_threshold": 70,
  "machine_learning_job_id": "linux_anomalous_network_activity_ecs"
}

Event correlation rule that creates alerts when the Windows rundll32.exe process makes unusual network connections

{
  "name": "rundll32.exe network connection",
  "tags": [
    "EQL",
    "Windows",
    "rundll32.exe"
  ],
  "type": "eql",
  "query": "sequence by process.entity_id with maxspan=2h [process where event.type in (\"start\", \"process_started\") and (process.name == \"rundll32.exe\" or process.pe.original_file_name == \"rundll32.exe\") and ((process.args == \"rundll32.exe\" and process.args_count == 1) or (process.args != \"rundll32.exe\" and process.args_count == 0))] [network where event.type == \"connection\" and (process.name == \"rundll32.exe\" or process.pe.original_file_name == \"rundll32.exe\")]",
  "rule_id": "eql-outbound-rundll32-connections",
  "language": "eql",
  "severity": "low",
  "risk_score": 21,
  "description": "Unusual rundll32.exe network connection",
  "required_fields": [
    {
      "name": "event.type",
      "type": "keyword"
    },
    {
      "name": "process.args",
      "type": "keyword"
    },
    {
      "name": "process.args_count",
      "type": "long"
    },
    {
      "name": "process.entity_id",
      "type": "keyword"
    },
    {
      "name": "process.name",
      "type": "keyword"
    },
    {
      "name": "process.pe.original_file_name",
      "type": "keyword"
    }
  ]
}

Indicator match rule that creates an alert when one of the following is true: The event's destination IP address and port number matches destination IP and port values in the threat_index index; The event's source IP address matches a host IP address value in the threat_index index.

{
  "name": "Bad IP threat match",
  "type": "threat_match",
  "index": [
    "packetbeat-*"
  ],
  "query": "destination.ip:* or host.ip:*",
  "actions": [],
  "severity": "medium",
  "risk_score": 50,
  "description": "Checks for bad IP addresses listed in the ip-threat-list index",
  "threat_index": [
    "ip-threat-list"
  ],
  "threat_query": "*:*",
  "threat_mapping": [
    {
      "entries": [
        {
          "type": "mapping",
          "field": "destination.ip",
          "value": "destination.ip"
        },
        {
          "type": "mapping",
          "field": "destination.port",
          "value": "destination.port"
        }
      ]
    },
    {
      "entries": [
        {
          "type": "mapping",
          "field": "source.ip",
          "value": "host.ip"
        }
      ]
    }
  ],
  "required_fields": [
    {
      "name": "destination.ip",
      "type": "ip"
    },
    {
      "name": "destination.port",
      "type": "long"
    },
    {
      "name": "host.ip",
      "type": "ip"
    }
  ]
}

New terms rule that creates alerts a new IP address is detected for a user

{
  "name": "New User IP Detected",
  "type": "new_terms",
  "index": [
    "auditbeat*"
  ],
  "query": "*",
  "language": "kuery",
  "severity": "medium",
  "risk_score": 21,
  "description": "Detects a user associated with a new IP address",
  "required_fields": [
    {
      "name": "user.id",
      "type": "keyword"
    },
    {
      "name": "source.ip",
      "type": "ip"
    }
  ],
  "new_terms_fields": [
    "user.id",
    "source.ip"
  ],
  "history_window_start": "now-30d"
}

esql rule that creates alerts from events that match an Excel parent process

{
  "to": "now",
  "from": "now-360s",
  "name": "Find Excel events",
  "tags": [],
  "type": "esql",
  "query": "from auditbeat-8.10.2 METADATA _id, _version, _index | where process.parent.name == \"EXCEL.EXE\"",
  "enabled": false,
  "interval": "5m",
  "language": "esql",
  "severity": "low",
  "risk_score": 21,
  "description": "Find Excel events",
  "required_fields": [
    {
      "name": "process.parent.name",
      "type": "keyword"
    }
  ]
}

Query rule that searches for processes started by MS Office and suppresses alerts by the process.parent.name field within a 5-hour time period

{
  "from": "now-70m",
  "name": "MS Office child process",
  "tags": [
    "child process",
    "ms office"
  ],
  "type": "query",
  "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",
  "enabled": false,
  "filters": [
    {
      "query": {
        "match": {
          "event.action": {
            "type": "phrase",
            "query": "Process Create (rule: ProcessCreate)"
          }
        }
      }
    }
  ],
  "rule_id": "process_started_by_ms_office_program",
  "interval": "1h",
  "language": "kuery",
  "severity": "low",
  "risk_score": 50,
  "description": "Process started by MS Office program - possible payload",
  "alert_suppression": {
    "duration": {
      "unit": "h",
      "value": 5
    },
    "group_by": [
      "process.parent.name"
    ],
    "missing_fields_strategy": "suppress"
  }
}

Response examples (200)

Example response for a query rule

{
  "id": "6541b99a-dee9-4f6d-a86d-dbd1869d73b1",
  "to": "now",
  "from": "now-70m",
  "name": "MS Office child process",
  "tags": [
    "child process",
    "ms office"
  ],
  "type": "query",
  "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",
  "setup": "",
  "threat": [],
  "actions": [],
  "enabled": false,
  "filters": [
    {
      "query": {
        "match": {
          "event.action": {
            "type": "phrase",
            "query": "Process Create (rule: ProcessCreate)"
          }
        }
      }
    }
  ],
  "rule_id": "process_started_by_ms_office_program",
  "version": 1,
  "interval": "1h",
  "language": "kuery",
  "severity": "low",
  "immutable": false,
  "created_at": "2020-04-07T14:51:09.755Z",
  "created_by": "elastic",
  "references": [],
  "risk_score": 50,
  "updated_at": "2020-04-07T14:51:09.970Z",
  "updated_by": "elastic",
  "description": "Process started by MS Office program - possible payload",
  "max_signals": 100,
  "false_positives": [],
  "required_fields": [
    {
      "ecs": true,
      "name": "process.parent.name",
      "type": "keyword"
    }
  ],
  "related_integrations": [
    {
      "package": "o365",
      "version": "^2.3.2"
    },
    {
      "package": "azure",
      "version": "^1.11.4",
      "integration": "graphactivitylogs"
    }
  ]
}

Example response for a machine learning job rule

{
  "id": "83876f66-3a57-4a99-bf37-416494c80f3b",
  "to": "now",
  "from": "now-6m",
  "name": "Anomalous Linux network activity",
  "note": "Shut down the internet.",
  "tags": [
    "machine learning",
    "Linux"
  ],
  "type": "machine_learning",
  "setup": "",
  "status": "going to run",
  "threat": [],
  "actions": [
    {
      "id": "5ad22cd5-5e6e-4c6c-a81a-54b626a4cec5",
      "group": "default",
      "params": {
        "message": "Urgent: {{context.rule.description}}"
      },
      "frequency": {
        "summary": true,
        "throttle": null,
        "notifyWhen": "onActiveAlert"
      },
      "action_type_id": ".slack"
    }
  ],
  "enabled": true,
  "rule_id": "ml_linux_network_high_threshold",
  "version": 1,
  "interval": "5m",
  "severity": "high",
  "immutable": false,
  "created_at": "2020-04-07T14:45:15.679Z",
  "created_by": "elastic",
  "references": [],
  "risk_score": 70,
  "updated_at": "2020-04-07T14:45:15.892Z",
  "updated_by": "elastic",
  "description": "Generates alerts when the job discovers anomalies over 70",
  "max_signals": 100,
  "status_date": "2020-04-07T14:45:21.685Z",
  "false_positives": [],
  "required_fields": [],
  "anomaly_threshold": 70,
  "related_integrations": [],
  "machine_learning_job_id": "linux_anomalous_network_activity_ecs"
}

Example response for a threshold rule

{
  "id": "15dbde26-b627-4d74-bb1f-a5e0ed9e4993",
  "to": "now",
  "from": "now-180s",
  "name": "Windows server prml-19",
  "tags": [
    "Brute force"
  ],
  "type": "threshold",
  "index": [
    "winlogbeat-*"
  ],
  "query": "host.name:prml-19 and event.category:authentication and event.outcome:failure",
  "setup": "",
  "author": [],
  "threat": [],
  "actions": [],
  "enabled": true,
  "rule_id": "liv-win-ser-logins",
  "version": 1,
  "interval": "2m",
  "language": "kuery",
  "severity": "low",
  "immutable": false,
  "threshold": {
    "field": "source.ip",
    "value": 20
  },
  "created_at": "2020-07-22T10:27:23.486Z",
  "created_by": "elastic",
  "references": [],
  "risk_score": 30,
  "updated_at": "2020-07-22T10:27:23.673Z",
  "updated_by": "elastic",
  "description": "Detects when there are 20 or more failed login attempts from the same IP address with a 2 minute time frame.",
  "max_signals": 100,
  "exceptions_list": [
    {
      "id": "int-ips",
      "type": "detection",
      "namespace_type": "single"
    }
  ],
  "false_positives": [],
  "required_fields": [
    {
      "ecs": true,
      "name": "source.ip",
      "type": "ip"
    }
  ],
  "severity_mapping": [
    {
      "field": "source.geo.city_name",
      "value": "Manchester",
      "operator": "equals",
      "severity": "low"
    },
    {
      "field": "source.geo.city_name",
      "value": "London",
      "operator": "equals",
      "severity": "medium"
    },
    {
      "field": "source.geo.city_name",
      "value": "Birmingham",
      "operator": "equals",
      "severity": "high"
    },
    {
      "field": "source.geo.city_name",
      "value": "Wallingford",
      "operator": "equals",
      "severity": "critical"
    }
  ],
  "risk_score_mapping": [],
  "related_integrations": [
    {
      "package": "o365",
      "version": "^2.3.2"
    }
  ]
}

Example response for an EQL rule

{
  "id": "93808cae-b05b-4dc9-8479-73574b50f8b1",
  "to": "now",
  "from": "now-6m",
  "name": "rundll32.exe network connection",
  "tags": [
    "EQL",
    "Windows",
    "rundll32.exe"
  ],
  "type": "eql",
  "query": "sequence by process.entity_id with maxspan=2h [process where event.type in (\"start\", \"process_started\") and (process.name == \"rundll32.exe\" or process.pe.original_file_name == \"rundll32.exe\") and ((process.args == \"rundll32.exe\" and process.args_count == 1) or (process.args != \"rundll32.exe\" and process.args_count == 0))] [network where event.type == \"connection\" and (process.name == \"rundll32.exe\" or process.pe.original_file_name == \"rundll32.exe\")]",
  "setup": "",
  "author": [],
  "threat": [],
  "enabled": true,
  "rule_id": "eql-outbound-rundll32-connections",
  "version": 1,
  "interval": "5m",
  "language": "eql",
  "severity": "low",
  "throttle": "no_actions",
  "immutable": false,
  "created_at": "2020-10-05T09:06:16.392Z",
  "created_by": "elastic",
  "references": [],
  "risk_score": 21,
  "updated_at": "2020-10-05T09:06:16.403Z",
  "updated_by": "elastic",
  "description": "Unusual rundll32.exe network connection",
  "max_signals": 100,
  "exceptions_list": [],
  "false_positives": [],
  "required_fields": [
    {
      "ecs": true,
      "name": "event.type",
      "type": "keyword"
    },
    {
      "ecs": true,
      "name": "process.args",
      "type": "keyword"
    },
    {
      "ecs": true,
      "name": "process.args_count",
      "type": "long"
    },
    {
      "ecs": true,
      "name": "process.entity_id",
      "type": "keyword"
    },
    {
      "ecs": true,
      "name": "process.name",
      "type": "keyword"
    },
    {
      "ecs": true,
      "name": "process.pe.original_file_name",
      "type": "keyword"
    }
  ],
  "severity_mapping": [],
  "risk_score_mapping": [],
  "related_integrations": [
    {
      "package": "o365",
      "version": "^2.3.2"
    }
  ]
}

Example response for an indicator match rule

{
  "id": "d5daa13f-81fb-4b13-be2f-31011e1d9ae1",
  "to": "now",
  "from": "now-6m",
  "name": "Bad IP threat match",
  "tags": [],
  "type": "threat_match",
  "index": [
    "packetbeat-*"
  ],
  "query": "destination.ip:* or host.ip:*",
  "setup": "",
  "author": [],
  "threat": [],
  "enabled": true,
  "rule_id": "608501e4-c768-4f64-9326-cec55b5d439b",
  "version": 1,
  "interval": "5m",
  "language": "kuery",
  "severity": "medium",
  "immutable": false,
  "created_at": "2020-10-06T07:07:58.227Z",
  "created_by": "elastic",
  "references": [],
  "risk_score": 50,
  "updated_at": "2020-10-06T07:07:58.237Z",
  "updated_by": "elastic",
  "description": "Checks for bad IP addresses listed in the ip-threat-list index",
  "max_signals": 100,
  "threat_index": [
    "ip-threat-list"
  ],
  "threat_query": "*:*",
  "threat_mapping": [
    {
      "entries": [
        {
          "type": "mapping",
          "field": "destination.ip",
          "value": "destination.ip"
        },
        {
          "type": "mapping",
          "field": "destination.port",
          "value": "destination.port"
        }
      ]
    },
    {
      "entries": [
        {
          "type": "mapping",
          "field": "source.ip",
          "value": "host.ip"
        }
      ]
    }
  ],
  "exceptions_list": [],
  "false_positives": [],
  "required_fields": [
    {
      "ecs": true,
      "name": "destination.ip",
      "type": "ip"
    },
    {
      "ecs": true,
      "name": "destination.port",
      "type": "long"
    },
    {
      "ecs": true,
      "name": "host.ip",
      "type": "ip"
    }
  ],
  "severity_mapping": [],
  "risk_score_mapping": [],
  "related_integrations": [
    {
      "package": "o365",
      "version": "^2.3.2"
    }
  ]
}

Example response for a new terms rule

{
  "id": "eb7225c0-566b-11ee-8b4f-bbf3afdeb9f4",
  "to": "now",
  "from": "now-6m",
  "name": "New User IP Detected",
  "tags": [],
  "type": "new_terms",
  "index": [
    "auditbeat*"
  ],
  "query": "*",
  "setup": "",
  "author": [],
  "threat": [],
  "enabled": true,
  "rule_id": "c6f5d0bc-7be9-47d4-b2f3-073d22641e30",
  "version": 1,
  "interval": "5m",
  "language": "kuery",
  "severity": "medium",
  "immutable": false,
  "created_at": "2020-10-06T07:07:58.227Z",
  "created_by": "elastic",
  "references": [],
  "risk_score": 21,
  "updated_at": "2020-10-06T07:07:58.237Z",
  "updated_by": "elastic",
  "description": "Detects a user associated with a new IP address",
  "max_signals": 100,
  "exceptions_list": [],
  "false_positives": [],
  "required_fields": [
    {
      "ecs": true,
      "name": "user.id",
      "type": "keyword"
    },
    {
      "ecs": true,
      "name": "source.ip",
      "type": "ip"
    }
  ],
  "new_terms_fields": [
    "user.id",
    "source.ip"
  ],
  "severity_mapping": [],
  "risk_score_mapping": [],
  "history_window_start": "now-30d",
  "related_integrations": [
    {
      "package": "o365",
      "version": "^2.3.2"
    }
  ]
}

Example response for an Esql rule

{
  "id": "d0f20490-6da4-11ee-b85e-09e9b661f2e2",
  "to": "now",
  "from": "now-360s",
  "name": "Find Excel events",
  "tags": [],
  "type": "esql",
  "query": "from auditbeat-8.10.2 METADATA _id | where process.parent.name == \"EXCEL.EXE\"",
  "setup": "",
  "author": [],
  "threat": [],
  "actions": [],
  "enabled": false,
  "rule_id": "e4b53a89-debd-4a0d-a3e3-20606952e589",
  "version": 1,
  "interval": "5m",
  "language": "esql",
  "revision": 0,
  "severity": "low",
  "immutable": false,
  "created_at": "2023-10-18T10:55:14.269Z",
  "created_by": "elastic",
  "references": [],
  "risk_score": 21,
  "updated_at": "2023-10-18T10:55:14.269Z",
  "updated_by": "elastic",
  "description": "Find Excel events",
  "max_signals": 100,
  "output_index": "",
  "exceptions_list": [],
  "false_positives": [],
  "required_fields": [
    {
      "ecs": true,
      "name": "process.parent.name",
      "type": "keyword"
    }
  ],
  "severity_mapping": [],
  "risk_score_mapping": [],
  "related_integrations": [
    {
      "package": "o365",
      "version": "^2.3.2"
    }
  ]
}

Delete a detection rule

DELETE /api/detection_engine/rules

Delete a detection rule using the rule_id or id field.

The URL query must include one of the following:

id - DELETE /api/detection_engine/rules?id=<id>
rule_id- DELETE /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.

Query parameters

id string(uuid)

The rule's id value.
rule_id string

The rule's rule_id value.

Responses

200 application/json

Indicates a successful call.
Any of:
Security_Detections_API_EqlRuleResponseFields object Security_Detections_API_QueryRuleResponseFields object Security_Detections_API_SavedQueryRuleResponseFields object Security_Detections_API_ThresholdRuleResponseFields object Security_Detections_API_ThreatMatchRuleResponseFields object Security_Detections_API_MachineLearningRuleResponseFields object Security_Detections_API_NewTermsRuleResponseFields object Security_Detections_API_EsqlRuleResponseFields object
Hide attributes Show attributes

actions array[object] Required

Array defining the automated actions (notifications) taken when alerts are generated.

Hide actions attributes Show actions attributes object

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.

Additional properties are allowed.

frequency object

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

Hide frequency attributes Show frequency attributes object

notifyWhen string Required

Defines how often rules run actions.

Values are onActiveAlert, onThrottleInterval, or 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 string | null Required

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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.

Additional properties are allowed.

uuid string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

alias_purpose string

Values are savedObjectConversion or savedObjectImport.

alias_target_id string

author array[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 Required

The rule’s description.

Minimum length is 1.

enabled boolean Required

Determines whether the rule is enabled. Defaults to true.

exceptions_list array[object] Required

Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.

Hide exceptions_list attributes Show exceptions_list attributes object

id string(nonempty) Required

ID of the exception container

Minimum length is 1.

list_id string(nonempty) Required

List ID of the exception container

Minimum length is 1.

namespace_type string Required

Determines the exceptions validity in rule's Kibana space

Values are agnostic or single.

type string Required

The exception type

Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.

false_positives array[string] Required

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.

from string(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.

Hide investigation_fields attribute Show investigation_fields attribute object

field_names array[string(nonempty)] Required

A string that does not contain only whitespace characters

At least 1 element. Minimum length of each is 1.

license string

The rule's license.

max_signals integer Required

Maximum number of alerts the rule can create during a single run (the rule’s Max alerts per run advanced setting value).

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.

Minimum value is 1. Default value is 100.

meta object

Placeholder for metadata about the rule.

This field is overwritten when you save changes to the rule’s settings.

Additional properties are allowed.

name string Required

A human-readable name for the rule.

Minimum length is 1.

namespace string

Has no effect.

note string

Notes to help investigate alerts produced by the rule.

outcome string

Values are exactMatch, aliasMatch, or conflict.

output_index string Deprecated

(deprecated) Has no effect.

references array[string] Required

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.

related_integrations array[object] Required

Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:

package: name of the package (required, unique id)

version: version of the package (required, semver-compatible)

integration: name of the integration of this package (optional, id within the package)

There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.

Hide related_integrations attributes Show related_integrations attributes object

integration string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

package string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

version string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

required_fields array[object] Required

Elasticsearch fields and their types that need to be present for the rule to function.

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.

Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.

Hide required_fields attributes Show required_fields attributes object

name string(nonempty) Required

Name of an Elasticsearch field

Minimum length is 1.

type string(nonempty) Required

Type of the Elasticsearch field

Minimum length is 1.

response_actions array[object]

One of:
Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object

Hide attributes Show attributes

action_type_id string Required

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

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

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[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.

Hide attributes Show attributes

action_type_id string Required

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object

Hide attributes Show attributes

command string Required

Value is isolate.

comment string

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.

risk_score integer 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

Minimum value is 0, maximum value is 100.

risk_score_mapping array[object] Required

Overrides generated alerts' risk_score with a value from the source event

Hide risk_score_mapping attributes Show risk_score_mapping attributes object

field string Required

Source event field used to override the default risk_score.

operator string Required

Value is equals.

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

Minimum value is 0, maximum value is 100.

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 string 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 are low, medium, high, or critical.

severity_mapping array[object] Required

Overrides generated alerts' severity with values from the source event

Hide severity_mapping attributes Show severity_mapping attributes object

field string Required

Source event field used to override the default severity.

operator string Required

Value is equals.

severity string 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 are low, medium, high, or critical.

value string Required

tags array[string] Required

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.

threat array[object] Required

Currently, only threats described using the MITRE ATT&CK™ framework are supported.

Hide threat attributes Show threat attributes object

framework string Required

Relevant attack framework

tactic object Required

Object containing information on the attack type

Hide tactic attributes Show tactic attributes object

id string Required

Tactic ID

name string Required

Tactic name

reference string Required

Tactic reference

technique array[object]

Array containing information on the attack techniques (optional)

Hide technique attributes Show technique attributes object

id string Required

Technique ID

name string Required

Technique name

reference string Required

Technique reference

subtechnique array[object]

Array containing more specific information on the attack technique.

Hide subtechnique attributes Show subtechnique attributes object

id string Required

Subtechnique ID

name string Required

Subtechnique name

reference string Required

Subtechnique reference

throttle string | null

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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 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.

It is not incremented on each update. Compare this to the revision field.

Minimum value is 1.

created_at string(date-time) Required

created_by string Required

execution_summary object

Summary of the last execution of a rule.

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

Hide execution_summary attribute Show execution_summary attribute object

last_execution object Required

Hide last_execution attributes Show last_execution attributes object

date string(date-time) Required

Date of the last execution

message string Required

metrics object Required

Hide metrics attributes Show metrics attributes object

execution_gap_duration_s integer

Duration in seconds of execution gap

Minimum value is 0.

frozen_indices_queried_count integer

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

Minimum value is 0.

gap_range object

Range of the execution gap

Hide gap_range attributes Show gap_range attributes object

gte string Required

Start date of the execution gap

lte string Required

End date of the execution gap

total_enrichment_duration_ms integer

Total time spent enriching documents during current rule execution cycle

Minimum value is 0.

total_indexing_duration_ms integer

Total time spent indexing documents during current rule execution cycle

Minimum value is 0.

total_search_duration_ms integer

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

Minimum value is 0.

status string Required

Status of the last execution

Values are going to run, running, partial failure, failed, or succeeded.

status_order integer Required

id string(uuid) Required

A dynamic unique identifier for the rule object. It is randomly generated when a rule is created and cannot be changed after that. It is always a UUID. It is unique within a given Kibana space. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have different object ids.

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

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.

Minimum value is 0.

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 object 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:
Security_Detections_API_ExternalRuleSource object Security_Detections_API_InternalRuleSource object

Type of rule source for externally sourced rules, i.e. rules that have an external source, such as the Elastic Prebuilt rules repo.

Hide attributes Show attributes

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

type string Required Discriminator

Value is external.

updated_at string(date-time) Required

updated_by string Required

language string Required

Query language to use

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

type string Required Discriminator

Rule type

Value is eql.

alert_suppression object

Defines alert suppression configuration.

Hide alert_suppression attributes Show alert_suppression attributes object

duration object

Hide duration attributes Show duration attributes object

unit string Required

Time unit

Values are s, m, or h.

value integer Required

Minimum value is 1.

group_by array[string] Required

At least 1 but not more than 3 elements.

missing_fields_strategy string

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 are doNotSuppress or suppress.

data_view_id string

event_category_override string

filters array

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

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.
Hide attributes Show attributes

actions array[object] Required

Array defining the automated actions (notifications) taken when alerts are generated.

Hide actions attributes Show actions attributes object

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.

Additional properties are allowed.

frequency object

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

Hide frequency attributes Show frequency attributes object

notifyWhen string Required

Defines how often rules run actions.

Values are onActiveAlert, onThrottleInterval, or 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 string | null Required

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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.

Additional properties are allowed.

uuid string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

alias_purpose string

Values are savedObjectConversion or savedObjectImport.

alias_target_id string

author array[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 Required

The rule’s description.

Minimum length is 1.

enabled boolean Required

Determines whether the rule is enabled. Defaults to true.

exceptions_list array[object] Required

Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.

Hide exceptions_list attributes Show exceptions_list attributes object

id string(nonempty) Required

ID of the exception container

Minimum length is 1.

list_id string(nonempty) Required

List ID of the exception container

Minimum length is 1.

namespace_type string Required

Determines the exceptions validity in rule's Kibana space

Values are agnostic or single.

type string Required

The exception type

Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.

false_positives array[string] Required

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.

from string(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.

Hide investigation_fields attribute Show investigation_fields attribute object

field_names array[string(nonempty)] Required

A string that does not contain only whitespace characters

At least 1 element. Minimum length of each is 1.

license string

The rule's license.

max_signals integer Required

Maximum number of alerts the rule can create during a single run (the rule’s Max alerts per run advanced setting value).

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.

Minimum value is 1. Default value is 100.

meta object

Placeholder for metadata about the rule.

This field is overwritten when you save changes to the rule’s settings.

Additional properties are allowed.

name string Required

A human-readable name for the rule.

Minimum length is 1.

namespace string

Has no effect.

note string

Notes to help investigate alerts produced by the rule.

outcome string

Values are exactMatch, aliasMatch, or conflict.

output_index string Deprecated

(deprecated) Has no effect.

references array[string] Required

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.

related_integrations array[object] Required

Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:

package: name of the package (required, unique id)

version: version of the package (required, semver-compatible)

integration: name of the integration of this package (optional, id within the package)

There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.

Hide related_integrations attributes Show related_integrations attributes object

integration string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

package string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

version string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

required_fields array[object] Required

Elasticsearch fields and their types that need to be present for the rule to function.

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.

Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.

Hide required_fields attributes Show required_fields attributes object

name string(nonempty) Required

Name of an Elasticsearch field

Minimum length is 1.

type string(nonempty) Required

Type of the Elasticsearch field

Minimum length is 1.

response_actions array[object]

One of:
Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object

Hide attributes Show attributes

action_type_id string Required

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

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

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[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.

Hide attributes Show attributes

action_type_id string Required

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object

Hide attributes Show attributes

command string Required

Value is isolate.

comment string

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.

risk_score integer 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

Minimum value is 0, maximum value is 100.

risk_score_mapping array[object] Required

Overrides generated alerts' risk_score with a value from the source event

Hide risk_score_mapping attributes Show risk_score_mapping attributes object

field string Required

Source event field used to override the default risk_score.

operator string Required

Value is equals.

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

Minimum value is 0, maximum value is 100.

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 string 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 are low, medium, high, or critical.

severity_mapping array[object] Required

Overrides generated alerts' severity with values from the source event

Hide severity_mapping attributes Show severity_mapping attributes object

field string Required

Source event field used to override the default severity.

operator string Required

Value is equals.

severity string 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 are low, medium, high, or critical.

value string Required

tags array[string] Required

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.

threat array[object] Required

Currently, only threats described using the MITRE ATT&CK™ framework are supported.

Hide threat attributes Show threat attributes object

framework string Required

Relevant attack framework

tactic object Required

Object containing information on the attack type

Hide tactic attributes Show tactic attributes object

id string Required

Tactic ID

name string Required

Tactic name

reference string Required

Tactic reference

technique array[object]

Array containing information on the attack techniques (optional)

Hide technique attributes Show technique attributes object

id string Required

Technique ID

name string Required

Technique name

reference string Required

Technique reference

subtechnique array[object]

Array containing more specific information on the attack technique.

Hide subtechnique attributes Show subtechnique attributes object

id string Required

Subtechnique ID

name string Required

Subtechnique name

reference string Required

Subtechnique reference

throttle string | null

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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 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.

It is not incremented on each update. Compare this to the revision field.

Minimum value is 1.

created_at string(date-time) Required

created_by string Required

execution_summary object

Summary of the last execution of a rule.

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

Hide execution_summary attribute Show execution_summary attribute object

last_execution object Required

Hide last_execution attributes Show last_execution attributes object

date string(date-time) Required

Date of the last execution

message string Required

metrics object Required

Hide metrics attributes Show metrics attributes object

execution_gap_duration_s integer

Duration in seconds of execution gap

Minimum value is 0.

frozen_indices_queried_count integer

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

Minimum value is 0.

gap_range object

Range of the execution gap

Hide gap_range attributes Show gap_range attributes object

gte string Required

Start date of the execution gap

lte string Required

End date of the execution gap

total_enrichment_duration_ms integer

Total time spent enriching documents during current rule execution cycle

Minimum value is 0.

total_indexing_duration_ms integer

Total time spent indexing documents during current rule execution cycle

Minimum value is 0.

total_search_duration_ms integer

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

Minimum value is 0.

status string Required

Status of the last execution

Values are going to run, running, partial failure, failed, or succeeded.

status_order integer Required

id string(uuid) Required

A dynamic unique identifier for the rule object. It is randomly generated when a rule is created and cannot be changed after that. It is always a UUID. It is unique within a given Kibana space. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have different object ids.

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

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.

Minimum value is 0.

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 object 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:
Security_Detections_API_ExternalRuleSource object Security_Detections_API_InternalRuleSource object

Type of rule source for externally sourced rules, i.e. rules that have an external source, such as the Elastic Prebuilt rules repo.

Hide attributes Show attributes

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

type string Required Discriminator

Value is external.

updated_at string(date-time) Required

updated_by string Required

type string Required Discriminator

Rule type

Value is query.

alert_suppression object

Defines alert suppression configuration.

Hide alert_suppression attributes Show alert_suppression attributes object

duration object

Hide duration attributes Show duration attributes object

unit string Required

Time unit

Values are s, m, or h.

value integer Required

Minimum value is 1.

group_by array[string] Required

At least 1 but not more than 3 elements.

missing_fields_strategy string

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 are doNotSuppress or suppress.

data_view_id string

filters array

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

saved_id string

Kibana saved search used by the rule to create alerts.

language string Required

Values are kuery or lucene.

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.
Hide attributes Show attributes

actions array[object] Required

Array defining the automated actions (notifications) taken when alerts are generated.

Hide actions attributes Show actions attributes object

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.

Additional properties are allowed.

frequency object

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

Hide frequency attributes Show frequency attributes object

notifyWhen string Required

Defines how often rules run actions.

Values are onActiveAlert, onThrottleInterval, or 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 string | null Required

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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.

Additional properties are allowed.

uuid string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

alias_purpose string

Values are savedObjectConversion or savedObjectImport.

alias_target_id string

author array[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 Required

The rule’s description.

Minimum length is 1.

enabled boolean Required

Determines whether the rule is enabled. Defaults to true.

exceptions_list array[object] Required

Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.

Hide exceptions_list attributes Show exceptions_list attributes object

id string(nonempty) Required

ID of the exception container

Minimum length is 1.

list_id string(nonempty) Required

List ID of the exception container

Minimum length is 1.

namespace_type string Required

Determines the exceptions validity in rule's Kibana space

Values are agnostic or single.

type string Required

The exception type

Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.

false_positives array[string] Required

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.

from string(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.

Hide investigation_fields attribute Show investigation_fields attribute object

field_names array[string(nonempty)] Required

A string that does not contain only whitespace characters

At least 1 element. Minimum length of each is 1.

license string

The rule's license.

max_signals integer Required

Maximum number of alerts the rule can create during a single run (the rule’s Max alerts per run advanced setting value).

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.

Minimum value is 1. Default value is 100.

meta object

Placeholder for metadata about the rule.

This field is overwritten when you save changes to the rule’s settings.

Additional properties are allowed.

name string Required

A human-readable name for the rule.

Minimum length is 1.

namespace string

Has no effect.

note string

Notes to help investigate alerts produced by the rule.

outcome string

Values are exactMatch, aliasMatch, or conflict.

output_index string Deprecated

(deprecated) Has no effect.

references array[string] Required

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.

related_integrations array[object] Required

Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:

package: name of the package (required, unique id)

version: version of the package (required, semver-compatible)

integration: name of the integration of this package (optional, id within the package)

There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.

Hide related_integrations attributes Show related_integrations attributes object

integration string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

package string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

version string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

required_fields array[object] Required

Elasticsearch fields and their types that need to be present for the rule to function.

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.

Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.

Hide required_fields attributes Show required_fields attributes object

name string(nonempty) Required

Name of an Elasticsearch field

Minimum length is 1.

type string(nonempty) Required

Type of the Elasticsearch field

Minimum length is 1.

response_actions array[object]

One of:
Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object

Hide attributes Show attributes

action_type_id string Required

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

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

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[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.

Hide attributes Show attributes

action_type_id string Required

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object

Hide attributes Show attributes

command string Required

Value is isolate.

comment string

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.

risk_score integer 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

Minimum value is 0, maximum value is 100.

risk_score_mapping array[object] Required

Overrides generated alerts' risk_score with a value from the source event

Hide risk_score_mapping attributes Show risk_score_mapping attributes object

field string Required

Source event field used to override the default risk_score.

operator string Required

Value is equals.

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

Minimum value is 0, maximum value is 100.

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 string 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 are low, medium, high, or critical.

severity_mapping array[object] Required

Overrides generated alerts' severity with values from the source event

Hide severity_mapping attributes Show severity_mapping attributes object

field string Required

Source event field used to override the default severity.

operator string Required

Value is equals.

severity string 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 are low, medium, high, or critical.

value string Required

tags array[string] Required

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.

threat array[object] Required

Currently, only threats described using the MITRE ATT&CK™ framework are supported.

Hide threat attributes Show threat attributes object

framework string Required

Relevant attack framework

tactic object Required

Object containing information on the attack type

Hide tactic attributes Show tactic attributes object

id string Required

Tactic ID

name string Required

Tactic name

reference string Required

Tactic reference

technique array[object]

Array containing information on the attack techniques (optional)

Hide technique attributes Show technique attributes object

id string Required

Technique ID

name string Required

Technique name

reference string Required

Technique reference

subtechnique array[object]

Array containing more specific information on the attack technique.

Hide subtechnique attributes Show subtechnique attributes object

id string Required

Subtechnique ID

name string Required

Subtechnique name

reference string Required

Subtechnique reference

throttle string | null

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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 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.

It is not incremented on each update. Compare this to the revision field.

Minimum value is 1.

created_at string(date-time) Required

created_by string Required

execution_summary object

Summary of the last execution of a rule.

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

Hide execution_summary attribute Show execution_summary attribute object

last_execution object Required

Hide last_execution attributes Show last_execution attributes object

date string(date-time) Required

Date of the last execution

message string Required

metrics object Required

Hide metrics attributes Show metrics attributes object

execution_gap_duration_s integer

Duration in seconds of execution gap

Minimum value is 0.

frozen_indices_queried_count integer

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

Minimum value is 0.

gap_range object

Range of the execution gap

Hide gap_range attributes Show gap_range attributes object

gte string Required

Start date of the execution gap

lte string Required

End date of the execution gap

total_enrichment_duration_ms integer

Total time spent enriching documents during current rule execution cycle

Minimum value is 0.

total_indexing_duration_ms integer

Total time spent indexing documents during current rule execution cycle

Minimum value is 0.

total_search_duration_ms integer

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

Minimum value is 0.

status string Required

Status of the last execution

Values are going to run, running, partial failure, failed, or succeeded.

status_order integer Required

id string(uuid) Required

A dynamic unique identifier for the rule object. It is randomly generated when a rule is created and cannot be changed after that. It is always a UUID. It is unique within a given Kibana space. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have different object ids.

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

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.

Minimum value is 0.

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 object 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:
Security_Detections_API_ExternalRuleSource object Security_Detections_API_InternalRuleSource object

Type of rule source for externally sourced rules, i.e. rules that have an external source, such as the Elastic Prebuilt rules repo.

Hide attributes Show attributes

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

type string Required Discriminator

Value is external.

updated_at string(date-time) Required

updated_by string Required

saved_id string Required

Kibana saved search used by the rule to create alerts.

type string Required Discriminator

Rule type

Value is saved_query.

alert_suppression object

Defines alert suppression configuration.

Hide alert_suppression attributes Show alert_suppression attributes object

duration object

Hide duration attributes Show duration attributes object

unit string Required

Time unit

Values are s, m, or h.

value integer Required

Minimum value is 1.

group_by array[string] Required

At least 1 but not more than 3 elements.

missing_fields_strategy string

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 are doNotSuppress or suppress.

data_view_id string

filters array

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

query string

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.

language string Required

Values are kuery or lucene.
Hide attributes Show attributes

actions array[object] Required

Array defining the automated actions (notifications) taken when alerts are generated.

Hide actions attributes Show actions attributes object

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.

Additional properties are allowed.

frequency object

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

Hide frequency attributes Show frequency attributes object

notifyWhen string Required

Defines how often rules run actions.

Values are onActiveAlert, onThrottleInterval, or 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 string | null Required

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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.

Additional properties are allowed.

uuid string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

alias_purpose string

Values are savedObjectConversion or savedObjectImport.

alias_target_id string

author array[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 Required

The rule’s description.

Minimum length is 1.

enabled boolean Required

Determines whether the rule is enabled. Defaults to true.

exceptions_list array[object] Required

Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.

Hide exceptions_list attributes Show exceptions_list attributes object

id string(nonempty) Required

ID of the exception container

Minimum length is 1.

list_id string(nonempty) Required

List ID of the exception container

Minimum length is 1.

namespace_type string Required

Determines the exceptions validity in rule's Kibana space

Values are agnostic or single.

type string Required

The exception type

Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.

false_positives array[string] Required

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.

from string(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.

Hide investigation_fields attribute Show investigation_fields attribute object

field_names array[string(nonempty)] Required

A string that does not contain only whitespace characters

At least 1 element. Minimum length of each is 1.

license string

The rule's license.

max_signals integer Required

Maximum number of alerts the rule can create during a single run (the rule’s Max alerts per run advanced setting value).

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.

Minimum value is 1. Default value is 100.

meta object

Placeholder for metadata about the rule.

This field is overwritten when you save changes to the rule’s settings.

Additional properties are allowed.

name string Required

A human-readable name for the rule.

Minimum length is 1.

namespace string

Has no effect.

note string

Notes to help investigate alerts produced by the rule.

outcome string

Values are exactMatch, aliasMatch, or conflict.

output_index string Deprecated

(deprecated) Has no effect.

references array[string] Required

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.

related_integrations array[object] Required

Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:

package: name of the package (required, unique id)

version: version of the package (required, semver-compatible)

integration: name of the integration of this package (optional, id within the package)

There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.

Hide related_integrations attributes Show related_integrations attributes object

integration string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

package string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

version string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

required_fields array[object] Required

Elasticsearch fields and their types that need to be present for the rule to function.

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.

Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.

Hide required_fields attributes Show required_fields attributes object

name string(nonempty) Required

Name of an Elasticsearch field

Minimum length is 1.

type string(nonempty) Required

Type of the Elasticsearch field

Minimum length is 1.

response_actions array[object]

One of:
Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object

Hide attributes Show attributes

action_type_id string Required

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

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

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[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.

Hide attributes Show attributes

action_type_id string Required

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object

Hide attributes Show attributes

command string Required

Value is isolate.

comment string

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.

risk_score integer 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

Minimum value is 0, maximum value is 100.

risk_score_mapping array[object] Required

Overrides generated alerts' risk_score with a value from the source event

Hide risk_score_mapping attributes Show risk_score_mapping attributes object

field string Required

Source event field used to override the default risk_score.

operator string Required

Value is equals.

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

Minimum value is 0, maximum value is 100.

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 string 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 are low, medium, high, or critical.

severity_mapping array[object] Required

Overrides generated alerts' severity with values from the source event

Hide severity_mapping attributes Show severity_mapping attributes object

field string Required

Source event field used to override the default severity.

operator string Required

Value is equals.

severity string 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 are low, medium, high, or critical.

value string Required

tags array[string] Required

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.

threat array[object] Required

Currently, only threats described using the MITRE ATT&CK™ framework are supported.

Hide threat attributes Show threat attributes object

framework string Required

Relevant attack framework

tactic object Required

Object containing information on the attack type

Hide tactic attributes Show tactic attributes object

id string Required

Tactic ID

name string Required

Tactic name

reference string Required

Tactic reference

technique array[object]

Array containing information on the attack techniques (optional)

Hide technique attributes Show technique attributes object

id string Required

Technique ID

name string Required

Technique name

reference string Required

Technique reference

subtechnique array[object]

Array containing more specific information on the attack technique.

Hide subtechnique attributes Show subtechnique attributes object

id string Required

Subtechnique ID

name string Required

Subtechnique name

reference string Required

Subtechnique reference

throttle string | null

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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 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.

It is not incremented on each update. Compare this to the revision field.

Minimum value is 1.

created_at string(date-time) Required

created_by string Required

execution_summary object

Summary of the last execution of a rule.

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

Hide execution_summary attribute Show execution_summary attribute object

last_execution object Required

Hide last_execution attributes Show last_execution attributes object

date string(date-time) Required

Date of the last execution

message string Required

metrics object Required

Hide metrics attributes Show metrics attributes object

execution_gap_duration_s integer

Duration in seconds of execution gap

Minimum value is 0.

frozen_indices_queried_count integer

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

Minimum value is 0.

gap_range object

Range of the execution gap

Hide gap_range attributes Show gap_range attributes object

gte string Required

Start date of the execution gap

lte string Required

End date of the execution gap

total_enrichment_duration_ms integer

Total time spent enriching documents during current rule execution cycle

Minimum value is 0.

total_indexing_duration_ms integer

Total time spent indexing documents during current rule execution cycle

Minimum value is 0.

total_search_duration_ms integer

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

Minimum value is 0.

status string Required

Status of the last execution

Values are going to run, running, partial failure, failed, or succeeded.

status_order integer Required

id string(uuid) Required

A dynamic unique identifier for the rule object. It is randomly generated when a rule is created and cannot be changed after that. It is always a UUID. It is unique within a given Kibana space. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have different object ids.

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

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.

Minimum value is 0.

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 object 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:
Security_Detections_API_ExternalRuleSource object Security_Detections_API_InternalRuleSource object

Type of rule source for externally sourced rules, i.e. rules that have an external source, such as the Elastic Prebuilt rules repo.

Hide attributes Show attributes

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

type string Required Discriminator

Value is external.

updated_at string(date-time) Required

updated_by string Required

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.

threshold object Required

Hide threshold attributes Show threshold attributes object

cardinality array[object]

The field on which the cardinality is applied.

Hide cardinality attributes Show cardinality attributes object

field string Required

The field on which to calculate and compare the cardinality.

value integer Required

The threshold value from which an alert is generated based on unique number of values of cardinality.field.

Minimum value is 0.

field string | array[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.

One of:
string-1 string array-2 array[string]

value integer Required

The threshold value from which an alert is generated.

Minimum value is 1.

type string Required Discriminator

Rule type

Value is threshold.

alert_suppression object

Defines alert suppression configuration.

Hide alert_suppression attribute Show alert_suppression attribute object

duration object Required

Hide duration attributes Show duration attributes object

unit string Required

Time unit

Values are s, m, or h.

value integer Required

Minimum value is 1.

data_view_id string

filters array

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

saved_id string

Kibana saved search used by the rule to create alerts.

language string Required

Values are kuery or lucene.
Hide attributes Show attributes

actions array[object] Required

Array defining the automated actions (notifications) taken when alerts are generated.

Hide actions attributes Show actions attributes object

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.

Additional properties are allowed.

frequency object

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

Hide frequency attributes Show frequency attributes object

notifyWhen string Required

Defines how often rules run actions.

Values are onActiveAlert, onThrottleInterval, or 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 string | null Required

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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.

Additional properties are allowed.

uuid string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

alias_purpose string

Values are savedObjectConversion or savedObjectImport.

alias_target_id string

author array[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 Required

The rule’s description.

Minimum length is 1.

enabled boolean Required

Determines whether the rule is enabled. Defaults to true.

exceptions_list array[object] Required

Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.

Hide exceptions_list attributes Show exceptions_list attributes object

id string(nonempty) Required

ID of the exception container

Minimum length is 1.

list_id string(nonempty) Required

List ID of the exception container

Minimum length is 1.

namespace_type string Required

Determines the exceptions validity in rule's Kibana space

Values are agnostic or single.

type string Required

The exception type

Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.

false_positives array[string] Required

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.

from string(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.

Hide investigation_fields attribute Show investigation_fields attribute object

field_names array[string(nonempty)] Required

A string that does not contain only whitespace characters

At least 1 element. Minimum length of each is 1.

license string

The rule's license.

max_signals integer Required

Maximum number of alerts the rule can create during a single run (the rule’s Max alerts per run advanced setting value).

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.

Minimum value is 1. Default value is 100.

meta object

Placeholder for metadata about the rule.

This field is overwritten when you save changes to the rule’s settings.

Additional properties are allowed.

name string Required

A human-readable name for the rule.

Minimum length is 1.

namespace string

Has no effect.

note string

Notes to help investigate alerts produced by the rule.

outcome string

Values are exactMatch, aliasMatch, or conflict.

output_index string Deprecated

(deprecated) Has no effect.

references array[string] Required

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.

related_integrations array[object] Required

Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:

package: name of the package (required, unique id)

version: version of the package (required, semver-compatible)

integration: name of the integration of this package (optional, id within the package)

There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.

Hide related_integrations attributes Show related_integrations attributes object

integration string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

package string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

version string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

required_fields array[object] Required

Elasticsearch fields and their types that need to be present for the rule to function.

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.

Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.

Hide required_fields attributes Show required_fields attributes object

name string(nonempty) Required

Name of an Elasticsearch field

Minimum length is 1.

type string(nonempty) Required

Type of the Elasticsearch field

Minimum length is 1.

response_actions array[object]

One of:
Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object

Hide attributes Show attributes

action_type_id string Required

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

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

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[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.

Hide attributes Show attributes

action_type_id string Required

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object

Hide attributes Show attributes

command string Required

Value is isolate.

comment string

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.

risk_score integer 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

Minimum value is 0, maximum value is 100.

risk_score_mapping array[object] Required

Overrides generated alerts' risk_score with a value from the source event

Hide risk_score_mapping attributes Show risk_score_mapping attributes object

field string Required

Source event field used to override the default risk_score.

operator string Required

Value is equals.

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

Minimum value is 0, maximum value is 100.

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 string 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 are low, medium, high, or critical.

severity_mapping array[object] Required

Overrides generated alerts' severity with values from the source event

Hide severity_mapping attributes Show severity_mapping attributes object

field string Required

Source event field used to override the default severity.

operator string Required

Value is equals.

severity string 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 are low, medium, high, or critical.

value string Required

tags array[string] Required

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.

threat array[object] Required

Currently, only threats described using the MITRE ATT&CK™ framework are supported.

Hide threat attributes Show threat attributes object

framework string Required

Relevant attack framework

tactic object Required

Object containing information on the attack type

Hide tactic attributes Show tactic attributes object

id string Required

Tactic ID

name string Required

Tactic name

reference string Required

Tactic reference

technique array[object]

Array containing information on the attack techniques (optional)

Hide technique attributes Show technique attributes object

id string Required

Technique ID

name string Required

Technique name

reference string Required

Technique reference

subtechnique array[object]

Array containing more specific information on the attack technique.

Hide subtechnique attributes Show subtechnique attributes object

id string Required

Subtechnique ID

name string Required

Subtechnique name

reference string Required

Subtechnique reference

throttle string | null

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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 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.

It is not incremented on each update. Compare this to the revision field.

Minimum value is 1.

created_at string(date-time) Required

created_by string Required

execution_summary object

Summary of the last execution of a rule.

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

Hide execution_summary attribute Show execution_summary attribute object

last_execution object Required

Hide last_execution attributes Show last_execution attributes object

date string(date-time) Required

Date of the last execution

message string Required

metrics object Required

Hide metrics attributes Show metrics attributes object

execution_gap_duration_s integer

Duration in seconds of execution gap

Minimum value is 0.

frozen_indices_queried_count integer

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

Minimum value is 0.

gap_range object

Range of the execution gap

Hide gap_range attributes Show gap_range attributes object

gte string Required

Start date of the execution gap

lte string Required

End date of the execution gap

total_enrichment_duration_ms integer

Total time spent enriching documents during current rule execution cycle

Minimum value is 0.

total_indexing_duration_ms integer

Total time spent indexing documents during current rule execution cycle

Minimum value is 0.

total_search_duration_ms integer

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

Minimum value is 0.

status string Required

Status of the last execution

Values are going to run, running, partial failure, failed, or succeeded.

status_order integer Required

id string(uuid) Required

A dynamic unique identifier for the rule object. It is randomly generated when a rule is created and cannot be changed after that. It is always a UUID. It is unique within a given Kibana space. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have different object ids.

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

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.

Minimum value is 0.

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 object 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:
Security_Detections_API_ExternalRuleSource object Security_Detections_API_InternalRuleSource object

Type of rule source for externally sourced rules, i.e. rules that have an external source, such as the Elastic Prebuilt rules repo.

Hide attributes Show attributes

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

type string Required Discriminator

Value is external.

updated_at string(date-time) Required

updated_by string Required

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.

threat_index array[string] Required

Elasticsearch indices used to check which field values generate alerts.

threat_mapping array[object] Required

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 Example of Threat Match rule which uses both and and or logic.

At least 1 element.

Hide threat_mapping attribute Show threat_mapping attribute object

entries array[object] Required

Hide entries attributes Show entries attributes object

field string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

type string Required

Value is mapping.

value string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

threat_query string Required

Query used to determine which fields in the Elasticsearch index are used for generating alerts.

type string Required Discriminator

Rule type

Value is threat_match.

alert_suppression object

Defines alert suppression configuration.

Hide alert_suppression attributes Show alert_suppression attributes object

duration object

Hide duration attributes Show duration attributes object

unit string Required

Time unit

Values are s, m, or h.

value integer Required

Minimum value is 1.

group_by array[string] Required

At least 1 but not more than 3 elements.

missing_fields_strategy string

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 are doNotSuppress or suppress.

concurrent_searches integer

Minimum value is 1.

data_view_id string

filters array

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

items_per_search integer

Minimum value is 1.

saved_id string

Kibana saved search used by the rule to create alerts.

threat_filters array

Query and filter context array used to filter documents from the Elasticsearch index containing the threat values

threat_indicator_path string

Defines the path to the threat indicator in the indicator documents (optional)

threat_language string

Values are kuery or lucene.

language string Required

Values are kuery or lucene.
Hide attributes Show attributes

actions array[object] Required

Array defining the automated actions (notifications) taken when alerts are generated.

Hide actions attributes Show actions attributes object

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.

Additional properties are allowed.

frequency object

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

Hide frequency attributes Show frequency attributes object

notifyWhen string Required

Defines how often rules run actions.

Values are onActiveAlert, onThrottleInterval, or 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 string | null Required

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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.

Additional properties are allowed.

uuid string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

alias_purpose string

Values are savedObjectConversion or savedObjectImport.

alias_target_id string

author array[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 Required

The rule’s description.

Minimum length is 1.

enabled boolean Required

Determines whether the rule is enabled. Defaults to true.

exceptions_list array[object] Required

Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.

Hide exceptions_list attributes Show exceptions_list attributes object

id string(nonempty) Required

ID of the exception container

Minimum length is 1.

list_id string(nonempty) Required

List ID of the exception container

Minimum length is 1.

namespace_type string Required

Determines the exceptions validity in rule's Kibana space

Values are agnostic or single.

type string Required

The exception type

Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.

false_positives array[string] Required

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.

from string(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.

Hide investigation_fields attribute Show investigation_fields attribute object

field_names array[string(nonempty)] Required

A string that does not contain only whitespace characters

At least 1 element. Minimum length of each is 1.

license string

The rule's license.

max_signals integer Required

Maximum number of alerts the rule can create during a single run (the rule’s Max alerts per run advanced setting value).

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.

Minimum value is 1. Default value is 100.

meta object

Placeholder for metadata about the rule.

This field is overwritten when you save changes to the rule’s settings.

Additional properties are allowed.

name string Required

A human-readable name for the rule.

Minimum length is 1.

namespace string

Has no effect.

note string

Notes to help investigate alerts produced by the rule.

outcome string

Values are exactMatch, aliasMatch, or conflict.

output_index string Deprecated

(deprecated) Has no effect.

references array[string] Required

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.

related_integrations array[object] Required

Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:

package: name of the package (required, unique id)

version: version of the package (required, semver-compatible)

integration: name of the integration of this package (optional, id within the package)

There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.

Hide related_integrations attributes Show related_integrations attributes object

integration string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

package string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

version string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

required_fields array[object] Required

Elasticsearch fields and their types that need to be present for the rule to function.

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.

Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.

Hide required_fields attributes Show required_fields attributes object

name string(nonempty) Required

Name of an Elasticsearch field

Minimum length is 1.

type string(nonempty) Required

Type of the Elasticsearch field

Minimum length is 1.

response_actions array[object]

One of:
Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object

Hide attributes Show attributes

action_type_id string Required

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

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

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[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.

Hide attributes Show attributes

action_type_id string Required

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object

Hide attributes Show attributes

command string Required

Value is isolate.

comment string

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.

risk_score integer 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

Minimum value is 0, maximum value is 100.

risk_score_mapping array[object] Required

Overrides generated alerts' risk_score with a value from the source event

Hide risk_score_mapping attributes Show risk_score_mapping attributes object

field string Required

Source event field used to override the default risk_score.

operator string Required

Value is equals.

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

Minimum value is 0, maximum value is 100.

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 string 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 are low, medium, high, or critical.

severity_mapping array[object] Required

Overrides generated alerts' severity with values from the source event

Hide severity_mapping attributes Show severity_mapping attributes object

field string Required

Source event field used to override the default severity.

operator string Required

Value is equals.

severity string 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 are low, medium, high, or critical.

value string Required

tags array[string] Required

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.

threat array[object] Required

Currently, only threats described using the MITRE ATT&CK™ framework are supported.

Hide threat attributes Show threat attributes object

framework string Required

Relevant attack framework

tactic object Required

Object containing information on the attack type

Hide tactic attributes Show tactic attributes object

id string Required

Tactic ID

name string Required

Tactic name

reference string Required

Tactic reference

technique array[object]

Array containing information on the attack techniques (optional)

Hide technique attributes Show technique attributes object

id string Required

Technique ID

name string Required

Technique name

reference string Required

Technique reference

subtechnique array[object]

Array containing more specific information on the attack technique.

Hide subtechnique attributes Show subtechnique attributes object

id string Required

Subtechnique ID

name string Required

Subtechnique name

reference string Required

Subtechnique reference

throttle string | null

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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 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.

It is not incremented on each update. Compare this to the revision field.

Minimum value is 1.

created_at string(date-time) Required

created_by string Required

execution_summary object

Summary of the last execution of a rule.

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

Hide execution_summary attribute Show execution_summary attribute object

last_execution object Required

Hide last_execution attributes Show last_execution attributes object

date string(date-time) Required

Date of the last execution

message string Required

metrics object Required

Hide metrics attributes Show metrics attributes object

execution_gap_duration_s integer

Duration in seconds of execution gap

Minimum value is 0.

frozen_indices_queried_count integer

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

Minimum value is 0.

gap_range object

Range of the execution gap

Hide gap_range attributes Show gap_range attributes object

gte string Required

Start date of the execution gap

lte string Required

End date of the execution gap

total_enrichment_duration_ms integer

Total time spent enriching documents during current rule execution cycle

Minimum value is 0.

total_indexing_duration_ms integer

Total time spent indexing documents during current rule execution cycle

Minimum value is 0.

total_search_duration_ms integer

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

Minimum value is 0.

status string Required

Status of the last execution

Values are going to run, running, partial failure, failed, or succeeded.

status_order integer Required

id string(uuid) Required

A dynamic unique identifier for the rule object. It is randomly generated when a rule is created and cannot be changed after that. It is always a UUID. It is unique within a given Kibana space. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have different object ids.

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

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.

Minimum value is 0.

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 object 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:
Security_Detections_API_ExternalRuleSource object Security_Detections_API_InternalRuleSource object

Type of rule source for externally sourced rules, i.e. rules that have an external source, such as the Elastic Prebuilt rules repo.

Hide attributes Show attributes

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

type string Required Discriminator

Value is external.

updated_at string(date-time) Required

updated_by string Required

anomaly_threshold integer Required

Anomaly score threshold above which the rule creates an alert. Valid values are from 0 to 100.

Minimum value is 0.

machine_learning_job_id string | array[string] Required

Machine learning job ID(s) the rule monitors for anomaly scores.

One of:
string-1 string array-2 array[string]

type string Required Discriminator

Rule type

Value is machine_learning.

alert_suppression object

Defines alert suppression configuration.

Hide alert_suppression attributes Show alert_suppression attributes object

duration object

Hide duration attributes Show duration attributes object

unit string Required

Time unit

Values are s, m, or h.

value integer Required

Minimum value is 1.

group_by array[string] Required

At least 1 but not more than 3 elements.

missing_fields_strategy string

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 are doNotSuppress or suppress.
Hide attributes Show attributes

actions array[object] Required

Array defining the automated actions (notifications) taken when alerts are generated.

Hide actions attributes Show actions attributes object

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.

Additional properties are allowed.

frequency object

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

Hide frequency attributes Show frequency attributes object

notifyWhen string Required

Defines how often rules run actions.

Values are onActiveAlert, onThrottleInterval, or 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 string | null Required

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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.

Additional properties are allowed.

uuid string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

alias_purpose string

Values are savedObjectConversion or savedObjectImport.

alias_target_id string

author array[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 Required

The rule’s description.

Minimum length is 1.

enabled boolean Required

Determines whether the rule is enabled. Defaults to true.

exceptions_list array[object] Required

Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.

Hide exceptions_list attributes Show exceptions_list attributes object

id string(nonempty) Required

ID of the exception container

Minimum length is 1.

list_id string(nonempty) Required

List ID of the exception container

Minimum length is 1.

namespace_type string Required

Determines the exceptions validity in rule's Kibana space

Values are agnostic or single.

type string Required

The exception type

Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.

false_positives array[string] Required

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.

from string(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.

Hide investigation_fields attribute Show investigation_fields attribute object

field_names array[string(nonempty)] Required

A string that does not contain only whitespace characters

At least 1 element. Minimum length of each is 1.

license string

The rule's license.

max_signals integer Required

Maximum number of alerts the rule can create during a single run (the rule’s Max alerts per run advanced setting value).

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.

Minimum value is 1. Default value is 100.

meta object

Placeholder for metadata about the rule.

This field is overwritten when you save changes to the rule’s settings.

Additional properties are allowed.

name string Required

A human-readable name for the rule.

Minimum length is 1.

namespace string

Has no effect.

note string

Notes to help investigate alerts produced by the rule.

outcome string

Values are exactMatch, aliasMatch, or conflict.

output_index string Deprecated

(deprecated) Has no effect.

references array[string] Required

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.

related_integrations array[object] Required

Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:

package: name of the package (required, unique id)

version: version of the package (required, semver-compatible)

integration: name of the integration of this package (optional, id within the package)

There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.

Hide related_integrations attributes Show related_integrations attributes object

integration string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

package string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

version string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

required_fields array[object] Required

Elasticsearch fields and their types that need to be present for the rule to function.

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.

Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.

Hide required_fields attributes Show required_fields attributes object

name string(nonempty) Required

Name of an Elasticsearch field

Minimum length is 1.

type string(nonempty) Required

Type of the Elasticsearch field

Minimum length is 1.

response_actions array[object]

One of:
Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object

Hide attributes Show attributes

action_type_id string Required

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

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

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[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.

Hide attributes Show attributes

action_type_id string Required

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object

Hide attributes Show attributes

command string Required

Value is isolate.

comment string

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.

risk_score integer 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

Minimum value is 0, maximum value is 100.

risk_score_mapping array[object] Required

Overrides generated alerts' risk_score with a value from the source event

Hide risk_score_mapping attributes Show risk_score_mapping attributes object

field string Required

Source event field used to override the default risk_score.

operator string Required

Value is equals.

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

Minimum value is 0, maximum value is 100.

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 string 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 are low, medium, high, or critical.

severity_mapping array[object] Required

Overrides generated alerts' severity with values from the source event

Hide severity_mapping attributes Show severity_mapping attributes object

field string Required

Source event field used to override the default severity.

operator string Required

Value is equals.

severity string 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 are low, medium, high, or critical.

value string Required

tags array[string] Required

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.

threat array[object] Required

Currently, only threats described using the MITRE ATT&CK™ framework are supported.

Hide threat attributes Show threat attributes object

framework string Required

Relevant attack framework

tactic object Required

Object containing information on the attack type

Hide tactic attributes Show tactic attributes object

id string Required

Tactic ID

name string Required

Tactic name

reference string Required

Tactic reference

technique array[object]

Array containing information on the attack techniques (optional)

Hide technique attributes Show technique attributes object

id string Required

Technique ID

name string Required

Technique name

reference string Required

Technique reference

subtechnique array[object]

Array containing more specific information on the attack technique.

Hide subtechnique attributes Show subtechnique attributes object

id string Required

Subtechnique ID

name string Required

Subtechnique name

reference string Required

Subtechnique reference

throttle string | null

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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 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.

It is not incremented on each update. Compare this to the revision field.

Minimum value is 1.

created_at string(date-time) Required

created_by string Required

execution_summary object

Summary of the last execution of a rule.

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

Hide execution_summary attribute Show execution_summary attribute object

last_execution object Required

Hide last_execution attributes Show last_execution attributes object

date string(date-time) Required

Date of the last execution

message string Required

metrics object Required

Hide metrics attributes Show metrics attributes object

execution_gap_duration_s integer

Duration in seconds of execution gap

Minimum value is 0.

frozen_indices_queried_count integer

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

Minimum value is 0.

gap_range object

Range of the execution gap

Hide gap_range attributes Show gap_range attributes object

gte string Required

Start date of the execution gap

lte string Required

End date of the execution gap

total_enrichment_duration_ms integer

Total time spent enriching documents during current rule execution cycle

Minimum value is 0.

total_indexing_duration_ms integer

Total time spent indexing documents during current rule execution cycle

Minimum value is 0.

total_search_duration_ms integer

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

Minimum value is 0.

status string Required

Status of the last execution

Values are going to run, running, partial failure, failed, or succeeded.

status_order integer Required

id string(uuid) Required

A dynamic unique identifier for the rule object. It is randomly generated when a rule is created and cannot be changed after that. It is always a UUID. It is unique within a given Kibana space. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have different object ids.

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

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.

Minimum value is 0.

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 object 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:
Security_Detections_API_ExternalRuleSource object Security_Detections_API_InternalRuleSource object

Type of rule source for externally sourced rules, i.e. rules that have an external source, such as the Elastic Prebuilt rules repo.

Hide attributes Show attributes

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

type string Required Discriminator

Value is external.

updated_at string(date-time) Required

updated_by string Required

history_window_start string(nonempty) Required

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.

Minimum length is 1.

new_terms_fields array[string] Required

Fields to monitor for new values.

At least 1 but not more than 3 elements.

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.

type string Required Discriminator

Rule type

Value is new_terms.

alert_suppression object

Defines alert suppression configuration.

Hide alert_suppression attributes Show alert_suppression attributes object

duration object

Hide duration attributes Show duration attributes object

unit string Required

Time unit

Values are s, m, or h.

value integer Required

Minimum value is 1.

group_by array[string] Required

At least 1 but not more than 3 elements.

missing_fields_strategy string

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 are doNotSuppress or suppress.

data_view_id string

filters array

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

language string Required

Values are kuery or lucene.
Hide attributes Show attributes

actions array[object] Required

Array defining the automated actions (notifications) taken when alerts are generated.

Hide actions attributes Show actions attributes object

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.

Additional properties are allowed.

frequency object

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

Hide frequency attributes Show frequency attributes object

notifyWhen string Required

Defines how often rules run actions.

Values are onActiveAlert, onThrottleInterval, or 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 string | null Required

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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.

Additional properties are allowed.

uuid string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

alias_purpose string

Values are savedObjectConversion or savedObjectImport.

alias_target_id string

author array[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 Required

The rule’s description.

Minimum length is 1.

enabled boolean Required

Determines whether the rule is enabled. Defaults to true.

exceptions_list array[object] Required

Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.

Hide exceptions_list attributes Show exceptions_list attributes object

id string(nonempty) Required

ID of the exception container

Minimum length is 1.

list_id string(nonempty) Required

List ID of the exception container

Minimum length is 1.

namespace_type string Required

Determines the exceptions validity in rule's Kibana space

Values are agnostic or single.

type string Required

The exception type

Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.

false_positives array[string] Required

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.

from string(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.

Hide investigation_fields attribute Show investigation_fields attribute object

field_names array[string(nonempty)] Required

A string that does not contain only whitespace characters

At least 1 element. Minimum length of each is 1.

license string

The rule's license.

max_signals integer Required

Maximum number of alerts the rule can create during a single run (the rule’s Max alerts per run advanced setting value).

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.

Minimum value is 1. Default value is 100.

meta object

Placeholder for metadata about the rule.

This field is overwritten when you save changes to the rule’s settings.

Additional properties are allowed.

name string Required

A human-readable name for the rule.

Minimum length is 1.

namespace string

Has no effect.

note string

Notes to help investigate alerts produced by the rule.

outcome string

Values are exactMatch, aliasMatch, or conflict.

output_index string Deprecated

(deprecated) Has no effect.

references array[string] Required

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.

related_integrations array[object] Required

Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:

package: name of the package (required, unique id)

version: version of the package (required, semver-compatible)

integration: name of the integration of this package (optional, id within the package)

There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.

Hide related_integrations attributes Show related_integrations attributes object

integration string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

package string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

version string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

required_fields array[object] Required

Elasticsearch fields and their types that need to be present for the rule to function.

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.

Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.

Hide required_fields attributes Show required_fields attributes object

name string(nonempty) Required

Name of an Elasticsearch field

Minimum length is 1.

type string(nonempty) Required

Type of the Elasticsearch field

Minimum length is 1.

response_actions array[object]

One of:
Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object

Hide attributes Show attributes

action_type_id string Required

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

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

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[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.

Hide attributes Show attributes

action_type_id string Required

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object

Hide attributes Show attributes

command string Required

Value is isolate.

comment string

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.

risk_score integer 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

Minimum value is 0, maximum value is 100.

risk_score_mapping array[object] Required

Overrides generated alerts' risk_score with a value from the source event

Hide risk_score_mapping attributes Show risk_score_mapping attributes object

field string Required

Source event field used to override the default risk_score.

operator string Required

Value is equals.

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

Minimum value is 0, maximum value is 100.

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 string 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 are low, medium, high, or critical.

severity_mapping array[object] Required

Overrides generated alerts' severity with values from the source event

Hide severity_mapping attributes Show severity_mapping attributes object

field string Required

Source event field used to override the default severity.

operator string Required

Value is equals.

severity string 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 are low, medium, high, or critical.

value string Required

tags array[string] Required

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.

threat array[object] Required

Currently, only threats described using the MITRE ATT&CK™ framework are supported.

Hide threat attributes Show threat attributes object

framework string Required

Relevant attack framework

tactic object Required

Object containing information on the attack type

Hide tactic attributes Show tactic attributes object

id string Required

Tactic ID

name string Required

Tactic name

reference string Required

Tactic reference

technique array[object]

Array containing information on the attack techniques (optional)

Hide technique attributes Show technique attributes object

id string Required

Technique ID

name string Required

Technique name

reference string Required

Technique reference

subtechnique array[object]

Array containing more specific information on the attack technique.

Hide subtechnique attributes Show subtechnique attributes object

id string Required

Subtechnique ID

name string Required

Subtechnique name

reference string Required

Subtechnique reference

throttle string | null

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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 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.

It is not incremented on each update. Compare this to the revision field.

Minimum value is 1.

created_at string(date-time) Required

created_by string Required

execution_summary object

Summary of the last execution of a rule.

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

Hide execution_summary attribute Show execution_summary attribute object

last_execution object Required

Hide last_execution attributes Show last_execution attributes object

date string(date-time) Required

Date of the last execution

message string Required

metrics object Required

Hide metrics attributes Show metrics attributes object

execution_gap_duration_s integer

Duration in seconds of execution gap

Minimum value is 0.

frozen_indices_queried_count integer

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

Minimum value is 0.

gap_range object

Range of the execution gap

Hide gap_range attributes Show gap_range attributes object

gte string Required

Start date of the execution gap

lte string Required

End date of the execution gap

total_enrichment_duration_ms integer

Total time spent enriching documents during current rule execution cycle

Minimum value is 0.

total_indexing_duration_ms integer

Total time spent indexing documents during current rule execution cycle

Minimum value is 0.

total_search_duration_ms integer

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

Minimum value is 0.

status string Required

Status of the last execution

Values are going to run, running, partial failure, failed, or succeeded.

status_order integer Required

id string(uuid) Required

A dynamic unique identifier for the rule object. It is randomly generated when a rule is created and cannot be changed after that. It is always a UUID. It is unique within a given Kibana space. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have different object ids.

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

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.

Minimum value is 0.

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 object 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:
Security_Detections_API_ExternalRuleSource object Security_Detections_API_InternalRuleSource object

Type of rule source for externally sourced rules, i.e. rules that have an external source, such as the Elastic Prebuilt rules repo.

Hide attributes Show attributes

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

type string Required Discriminator

Value is external.

updated_at string(date-time) Required

updated_by string Required

alert_suppression object

Defines alert suppression configuration.

Hide alert_suppression attributes Show alert_suppression attributes object

duration object

Hide duration attributes Show duration attributes object

unit string Required

Time unit

Values are s, m, or h.

value integer Required

Minimum value is 1.

group_by array[string] Required

At least 1 but not more than 3 elements.

missing_fields_strategy string

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 are doNotSuppress or suppress.

language string Required

Value is esql.

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.

type string Required Discriminator

Rule type

Value is esql.

DELETE /api/detection_engine/rules

curl \
  --request DELETE https://localhost:5601/api/detection_engine/rules?rule_id=bfeaf89b-a2a7-48a3-817f-e41829dc61ee \
  --header "Content-Type: application/json; Elastic-Api-Version=2023-10-31"

Patch a detection rule

PATCH /api/detection_engine/rules

Update specific fields of an existing detection rule using the rule_id or id field.

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.

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.

application/json

Body object Required

You cannot modify the id or rule_id values.

actions array[object]

Array defining the automated actions (notifications) taken when alerts are generated.
Hide actions attributes Show actions attributes object
- 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.
  Additional properties are allowed.
- frequency object
  
  The action frequency defines when the action runs (for example, only on rule execution or at specific time intervals).
  Hide frequency attributes Show frequency attributes object
  
  notifyWhen string Required
  
  Defines how often rules run actions.
  
  Values are onActiveAlert, onThrottleInterval, or 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 string | null Required
  
  Defines how often rule actions are taken.
  
  One of:
  string-1 string | null string-2 string | null
  
  Values are no_actions or 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.
  Additional properties are allowed.
- uuid string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
alias_purpose string

Values are savedObjectConversion or savedObjectImport.
alias_target_id string
author array[string]

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

The rule’s description.

Minimum length is 1.
enabled boolean

Determines whether the rule is enabled. Defaults to true.
exceptions_list array[object]

Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.
Hide exceptions_list attributes Show exceptions_list attributes object
- id string(nonempty) Required
  
  ID of the exception container
  
  Minimum length is 1.
- list_id string(nonempty) Required
  
  List ID of the exception container
  
  Minimum length is 1.
- namespace_type string Required
  
  Determines the exceptions validity in rule's Kibana space
  
  Values are agnostic or single.
- type string Required
  
  The exception type
  
  Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.
false_positives array[string]

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.
from string(date-math)

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).
id string(uuid)

A dynamic unique identifier for the rule object. It is randomly generated when a rule is created and cannot be changed after that. It is always a UUID. It is unique within a given Kibana space. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have different object ids.
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).
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.
Hide investigation_fields attribute Show investigation_fields attribute object
- field_names array[string(nonempty)] Required
  
  A string that does not contain only whitespace characters
  
  At least 1 element. Minimum length of each is 1.
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).

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.

Minimum value is 1. Default value is 100.
meta object

Placeholder for metadata about the rule.

This field is overwritten when you save changes to the rule’s settings.

Additional properties are allowed.
name string

A human-readable name for the rule.

Minimum length is 1.
namespace string

Has no effect.
note string

Notes to help investigate alerts produced by the rule.
outcome string

Values are exactMatch, aliasMatch, or conflict.
output_index string Deprecated

(deprecated) Has no effect.
references array[string]

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.
related_integrations array[object]
Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:
- package: name of the package (required, unique id)
- version: version of the package (required, semver-compatible)
- integration: name of the integration of this package (optional, id within the package)
There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.
Hide related_integrations attributes Show related_integrations attributes object
- integration string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- package string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- version string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
required_fields array[object]

Elasticsearch fields and their types that need to be present for the rule to function.

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.

Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.
Hide required_fields attributes Show required_fields attributes object
- name string(nonempty) Required
  
  Name of an Elasticsearch field
  
  Minimum length is 1.
- type string(nonempty) Required
  
  Type of the Elasticsearch field
  
  Minimum length is 1.
response_actions array[object]
One of:
Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object
Hide attributes Show attributes

action_type_id string Required

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

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

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[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.
Hide attributes Show attributes

action_type_id string Required

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object

Hide attributes Show attributes

command string Required

Value is isolate.

comment string

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.
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
Minimum value is 0, maximum value is 100.
risk_score_mapping array[object]

Overrides generated alerts' risk_score with a value from the source event
Hide risk_score_mapping attributes Show risk_score_mapping attributes object
- field string Required
  
  Source event field used to override the default risk_score.
- operator string Required
  
  Value is equals.
- 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
  Minimum value is 0, maximum value is 100.
- value string Required
rule_id string

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

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 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
Values are low, medium, high, or critical.
severity_mapping array[object]

Overrides generated alerts' severity with values from the source event
Hide severity_mapping attributes Show severity_mapping attributes object
- field string Required
  
  Source event field used to override the default severity.
- operator string Required
  
  Value is equals.
- severity string 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 are low, medium, high, or critical.
- value string Required
tags array[string]

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.
threat array[object]

Currently, only threats described using the MITRE ATT&CK™ framework are supported.
Hide threat attributes Show threat attributes object
- framework string Required
  
  Relevant attack framework
- tactic object Required
  
  Object containing information on the attack type
  Hide tactic attributes Show tactic attributes object
  
  id string Required
  
  Tactic ID
  
  name string Required
  
  Tactic name
  
  reference string Required
  
  Tactic reference
- technique array[object]
  
  Array containing information on the attack techniques (optional)
  Hide technique attributes Show technique attributes object
  
  id string Required
  
  Technique ID
  
  name string Required
  
  Technique name
  
  reference string Required
  
  Technique reference
  
  subtechnique array[object]
  
  Array containing more specific information on the attack technique.
  
  Hide subtechnique attributes Show subtechnique attributes object
  
  id string Required
  
  Subtechnique ID
  
  name string Required
  
  Subtechnique name
  
  reference string Required
  
  Subtechnique reference
throttle string | null

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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
version integer
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.
It is not incremented on each update. Compare this to the revision field.
Minimum value is 1.
language string

Query language to use

Value is eql.
query string
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.
type string

Rule type

Value is eql.
alert_suppression object

Defines alert suppression configuration.
Hide alert_suppression attributes Show alert_suppression attributes object
- duration object
  Hide duration attributes Show duration attributes object
  
  unit string Required
  
  Time unit
  
  Values are s, m, or h.
  
  value integer Required
  
  Minimum value is 1.
- group_by array[string] Required
  
  At least 1 but not more than 3 elements.
- missing_fields_strategy string
  
  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 are doNotSuppress or suppress.
data_view_id string
event_category_override string
filters array

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

actions array[object]

Array defining the automated actions (notifications) taken when alerts are generated.
Hide actions attributes Show actions attributes object
- 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.
  Additional properties are allowed.
- frequency object
  
  The action frequency defines when the action runs (for example, only on rule execution or at specific time intervals).
  Hide frequency attributes Show frequency attributes object
  
  notifyWhen string Required
  
  Defines how often rules run actions.
  
  Values are onActiveAlert, onThrottleInterval, or 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 string | null Required
  
  Defines how often rule actions are taken.
  
  One of:
  string-1 string | null string-2 string | null
  
  Values are no_actions or 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.
  Additional properties are allowed.
- uuid string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
alias_purpose string

Values are savedObjectConversion or savedObjectImport.
alias_target_id string
author array[string]

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

The rule’s description.

Minimum length is 1.
enabled boolean

Determines whether the rule is enabled. Defaults to true.
exceptions_list array[object]

Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.
Hide exceptions_list attributes Show exceptions_list attributes object
- id string(nonempty) Required
  
  ID of the exception container
  
  Minimum length is 1.
- list_id string(nonempty) Required
  
  List ID of the exception container
  
  Minimum length is 1.
- namespace_type string Required
  
  Determines the exceptions validity in rule's Kibana space
  
  Values are agnostic or single.
- type string Required
  
  The exception type
  
  Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.
false_positives array[string]

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.
from string(date-math)

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).
id string(uuid)

A dynamic unique identifier for the rule object. It is randomly generated when a rule is created and cannot be changed after that. It is always a UUID. It is unique within a given Kibana space. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have different object ids.
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).
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.
Hide investigation_fields attribute Show investigation_fields attribute object
- field_names array[string(nonempty)] Required
  
  A string that does not contain only whitespace characters
  
  At least 1 element. Minimum length of each is 1.
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).

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.

Minimum value is 1. Default value is 100.
meta object

Placeholder for metadata about the rule.

This field is overwritten when you save changes to the rule’s settings.

Additional properties are allowed.
name string

A human-readable name for the rule.

Minimum length is 1.
namespace string

Has no effect.
note string

Notes to help investigate alerts produced by the rule.
outcome string

Values are exactMatch, aliasMatch, or conflict.
output_index string Deprecated

(deprecated) Has no effect.
references array[string]

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.
related_integrations array[object]
Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:
- package: name of the package (required, unique id)
- version: version of the package (required, semver-compatible)
- integration: name of the integration of this package (optional, id within the package)
There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.
Hide related_integrations attributes Show related_integrations attributes object
- integration string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- package string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- version string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
required_fields array[object]

Elasticsearch fields and their types that need to be present for the rule to function.

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.

Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.
Hide required_fields attributes Show required_fields attributes object
- name string(nonempty) Required
  
  Name of an Elasticsearch field
  
  Minimum length is 1.
- type string(nonempty) Required
  
  Type of the Elasticsearch field
  
  Minimum length is 1.
response_actions array[object]
One of:
Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object
Hide attributes Show attributes

action_type_id string Required

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

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

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[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.
Hide attributes Show attributes

action_type_id string Required

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object

Hide attributes Show attributes

command string Required

Value is isolate.

comment string

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.
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
Minimum value is 0, maximum value is 100.
risk_score_mapping array[object]

Overrides generated alerts' risk_score with a value from the source event
Hide risk_score_mapping attributes Show risk_score_mapping attributes object
- field string Required
  
  Source event field used to override the default risk_score.
- operator string Required
  
  Value is equals.
- 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
  Minimum value is 0, maximum value is 100.
- value string Required
rule_id string

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

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 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
Values are low, medium, high, or critical.
severity_mapping array[object]

Overrides generated alerts' severity with values from the source event
Hide severity_mapping attributes Show severity_mapping attributes object
- field string Required
  
  Source event field used to override the default severity.
- operator string Required
  
  Value is equals.
- severity string 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 are low, medium, high, or critical.
- value string Required
tags array[string]

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.
threat array[object]

Currently, only threats described using the MITRE ATT&CK™ framework are supported.
Hide threat attributes Show threat attributes object
- framework string Required
  
  Relevant attack framework
- tactic object Required
  
  Object containing information on the attack type
  Hide tactic attributes Show tactic attributes object
  
  id string Required
  
  Tactic ID
  
  name string Required
  
  Tactic name
  
  reference string Required
  
  Tactic reference
- technique array[object]
  
  Array containing information on the attack techniques (optional)
  Hide technique attributes Show technique attributes object
  
  id string Required
  
  Technique ID
  
  name string Required
  
  Technique name
  
  reference string Required
  
  Technique reference
  
  subtechnique array[object]
  
  Array containing more specific information on the attack technique.
  
  Hide subtechnique attributes Show subtechnique attributes object
  
  id string Required
  
  Subtechnique ID
  
  name string Required
  
  Subtechnique name
  
  reference string Required
  
  Subtechnique reference
throttle string | null

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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
version integer
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.
It is not incremented on each update. Compare this to the revision field.
Minimum value is 1.
type string

Rule type

Value is query.
alert_suppression object

Defines alert suppression configuration.
Hide alert_suppression attributes Show alert_suppression attributes object
- duration object
  Hide duration attributes Show duration attributes object
  
  unit string Required
  
  Time unit
  
  Values are s, m, or h.
  
  value integer Required
  
  Minimum value is 1.
- group_by array[string] Required
  
  At least 1 but not more than 3 elements.
- missing_fields_strategy string
  
  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 are doNotSuppress or suppress.
data_view_id string
filters array

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 array[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.
saved_id string

Kibana saved search used by the rule to create alerts.
language string

Values are kuery or lucene.
query string
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.

actions array[object]

Array defining the automated actions (notifications) taken when alerts are generated.
Hide actions attributes Show actions attributes object
- 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.
  Additional properties are allowed.
- frequency object
  
  The action frequency defines when the action runs (for example, only on rule execution or at specific time intervals).
  Hide frequency attributes Show frequency attributes object
  
  notifyWhen string Required
  
  Defines how often rules run actions.
  
  Values are onActiveAlert, onThrottleInterval, or 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 string | null Required
  
  Defines how often rule actions are taken.
  
  One of:
  string-1 string | null string-2 string | null
  
  Values are no_actions or 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.
  Additional properties are allowed.
- uuid string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
alias_purpose string

Values are savedObjectConversion or savedObjectImport.
alias_target_id string
author array[string]

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

The rule’s description.

Minimum length is 1.
enabled boolean

Determines whether the rule is enabled. Defaults to true.
exceptions_list array[object]

Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.
Hide exceptions_list attributes Show exceptions_list attributes object
- id string(nonempty) Required
  
  ID of the exception container
  
  Minimum length is 1.
- list_id string(nonempty) Required
  
  List ID of the exception container
  
  Minimum length is 1.
- namespace_type string Required
  
  Determines the exceptions validity in rule's Kibana space
  
  Values are agnostic or single.
- type string Required
  
  The exception type
  
  Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.
false_positives array[string]

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.
from string(date-math)

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).
id string(uuid)

A dynamic unique identifier for the rule object. It is randomly generated when a rule is created and cannot be changed after that. It is always a UUID. It is unique within a given Kibana space. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have different object ids.
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).
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.
Hide investigation_fields attribute Show investigation_fields attribute object
- field_names array[string(nonempty)] Required
  
  A string that does not contain only whitespace characters
  
  At least 1 element. Minimum length of each is 1.
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).

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.

Minimum value is 1. Default value is 100.
meta object

Placeholder for metadata about the rule.

This field is overwritten when you save changes to the rule’s settings.

Additional properties are allowed.
name string

A human-readable name for the rule.

Minimum length is 1.
namespace string

Has no effect.
note string

Notes to help investigate alerts produced by the rule.
outcome string

Values are exactMatch, aliasMatch, or conflict.
output_index string Deprecated

(deprecated) Has no effect.
references array[string]

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.
related_integrations array[object]
Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:
- package: name of the package (required, unique id)
- version: version of the package (required, semver-compatible)
- integration: name of the integration of this package (optional, id within the package)
There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.
Hide related_integrations attributes Show related_integrations attributes object
- integration string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- package string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- version string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
required_fields array[object]

Elasticsearch fields and their types that need to be present for the rule to function.

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.

Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.
Hide required_fields attributes Show required_fields attributes object
- name string(nonempty) Required
  
  Name of an Elasticsearch field
  
  Minimum length is 1.
- type string(nonempty) Required
  
  Type of the Elasticsearch field
  
  Minimum length is 1.
response_actions array[object]
One of:
Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object
Hide attributes Show attributes

action_type_id string Required

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

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

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[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.
Hide attributes Show attributes

action_type_id string Required

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object

Hide attributes Show attributes

command string Required

Value is isolate.

comment string

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.
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
Minimum value is 0, maximum value is 100.
risk_score_mapping array[object]

Overrides generated alerts' risk_score with a value from the source event
Hide risk_score_mapping attributes Show risk_score_mapping attributes object
- field string Required
  
  Source event field used to override the default risk_score.
- operator string Required
  
  Value is equals.
- 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
  Minimum value is 0, maximum value is 100.
- value string Required
rule_id string

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

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 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
Values are low, medium, high, or critical.
severity_mapping array[object]

Overrides generated alerts' severity with values from the source event
Hide severity_mapping attributes Show severity_mapping attributes object
- field string Required
  
  Source event field used to override the default severity.
- operator string Required
  
  Value is equals.
- severity string 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 are low, medium, high, or critical.
- value string Required
tags array[string]

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.
threat array[object]

Currently, only threats described using the MITRE ATT&CK™ framework are supported.
Hide threat attributes Show threat attributes object
- framework string Required
  
  Relevant attack framework
- tactic object Required
  
  Object containing information on the attack type
  Hide tactic attributes Show tactic attributes object
  
  id string Required
  
  Tactic ID
  
  name string Required
  
  Tactic name
  
  reference string Required
  
  Tactic reference
- technique array[object]
  
  Array containing information on the attack techniques (optional)
  Hide technique attributes Show technique attributes object
  
  id string Required
  
  Technique ID
  
  name string Required
  
  Technique name
  
  reference string Required
  
  Technique reference
  
  subtechnique array[object]
  
  Array containing more specific information on the attack technique.
  
  Hide subtechnique attributes Show subtechnique attributes object
  
  id string Required
  
  Subtechnique ID
  
  name string Required
  
  Subtechnique name
  
  reference string Required
  
  Subtechnique reference
throttle string | null

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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
version integer
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.
It is not incremented on each update. Compare this to the revision field.
Minimum value is 1.
saved_id string

Kibana saved search used by the rule to create alerts.
type string

Rule type

Value is saved_query.
alert_suppression object

Defines alert suppression configuration.
Hide alert_suppression attributes Show alert_suppression attributes object
- duration object
  Hide duration attributes Show duration attributes object
  
  unit string Required
  
  Time unit
  
  Values are s, m, or h.
  
  value integer Required
  
  Minimum value is 1.
- group_by array[string] Required
  
  At least 1 but not more than 3 elements.
- missing_fields_strategy string
  
  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 are doNotSuppress or suppress.
data_view_id string
filters array

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 array[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.
query string
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.
language string

Values are kuery or lucene.

actions array[object]

Array defining the automated actions (notifications) taken when alerts are generated.
Hide actions attributes Show actions attributes object
- 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.
  Additional properties are allowed.
- frequency object
  
  The action frequency defines when the action runs (for example, only on rule execution or at specific time intervals).
  Hide frequency attributes Show frequency attributes object
  
  notifyWhen string Required
  
  Defines how often rules run actions.
  
  Values are onActiveAlert, onThrottleInterval, or 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 string | null Required
  
  Defines how often rule actions are taken.
  
  One of:
  string-1 string | null string-2 string | null
  
  Values are no_actions or 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.
  Additional properties are allowed.
- uuid string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
alias_purpose string

Values are savedObjectConversion or savedObjectImport.
alias_target_id string
author array[string]

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

The rule’s description.

Minimum length is 1.
enabled boolean

Determines whether the rule is enabled. Defaults to true.
exceptions_list array[object]

Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.
Hide exceptions_list attributes Show exceptions_list attributes object
- id string(nonempty) Required
  
  ID of the exception container
  
  Minimum length is 1.
- list_id string(nonempty) Required
  
  List ID of the exception container
  
  Minimum length is 1.
- namespace_type string Required
  
  Determines the exceptions validity in rule's Kibana space
  
  Values are agnostic or single.
- type string Required
  
  The exception type
  
  Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.
false_positives array[string]

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.
from string(date-math)

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).
id string(uuid)

A dynamic unique identifier for the rule object. It is randomly generated when a rule is created and cannot be changed after that. It is always a UUID. It is unique within a given Kibana space. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have different object ids.
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).
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.
Hide investigation_fields attribute Show investigation_fields attribute object
- field_names array[string(nonempty)] Required
  
  A string that does not contain only whitespace characters
  
  At least 1 element. Minimum length of each is 1.
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).

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.

Minimum value is 1. Default value is 100.
meta object

Placeholder for metadata about the rule.

This field is overwritten when you save changes to the rule’s settings.

Additional properties are allowed.
name string

A human-readable name for the rule.

Minimum length is 1.
namespace string

Has no effect.
note string

Notes to help investigate alerts produced by the rule.
outcome string

Values are exactMatch, aliasMatch, or conflict.
output_index string Deprecated

(deprecated) Has no effect.
references array[string]

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.
related_integrations array[object]
Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:
- package: name of the package (required, unique id)
- version: version of the package (required, semver-compatible)
- integration: name of the integration of this package (optional, id within the package)
There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.
Hide related_integrations attributes Show related_integrations attributes object
- integration string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- package string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- version string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
required_fields array[object]

Elasticsearch fields and their types that need to be present for the rule to function.

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.

Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.
Hide required_fields attributes Show required_fields attributes object
- name string(nonempty) Required
  
  Name of an Elasticsearch field
  
  Minimum length is 1.
- type string(nonempty) Required
  
  Type of the Elasticsearch field
  
  Minimum length is 1.
response_actions array[object]
One of:
Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object
Hide attributes Show attributes

action_type_id string Required

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

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

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[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.
Hide attributes Show attributes

action_type_id string Required

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object

Hide attributes Show attributes

command string Required

Value is isolate.

comment string

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.
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
Minimum value is 0, maximum value is 100.
risk_score_mapping array[object]

Overrides generated alerts' risk_score with a value from the source event
Hide risk_score_mapping attributes Show risk_score_mapping attributes object
- field string Required
  
  Source event field used to override the default risk_score.
- operator string Required
  
  Value is equals.
- 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
  Minimum value is 0, maximum value is 100.
- value string Required
rule_id string

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

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 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
Values are low, medium, high, or critical.
severity_mapping array[object]

Overrides generated alerts' severity with values from the source event
Hide severity_mapping attributes Show severity_mapping attributes object
- field string Required
  
  Source event field used to override the default severity.
- operator string Required
  
  Value is equals.
- severity string 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 are low, medium, high, or critical.
- value string Required
tags array[string]

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.
threat array[object]

Currently, only threats described using the MITRE ATT&CK™ framework are supported.
Hide threat attributes Show threat attributes object
- framework string Required
  
  Relevant attack framework
- tactic object Required
  
  Object containing information on the attack type
  Hide tactic attributes Show tactic attributes object
  
  id string Required
  
  Tactic ID
  
  name string Required
  
  Tactic name
  
  reference string Required
  
  Tactic reference
- technique array[object]
  
  Array containing information on the attack techniques (optional)
  Hide technique attributes Show technique attributes object
  
  id string Required
  
  Technique ID
  
  name string Required
  
  Technique name
  
  reference string Required
  
  Technique reference
  
  subtechnique array[object]
  
  Array containing more specific information on the attack technique.
  
  Hide subtechnique attributes Show subtechnique attributes object
  
  id string Required
  
  Subtechnique ID
  
  name string Required
  
  Subtechnique name
  
  reference string Required
  
  Subtechnique reference
throttle string | null

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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
version integer
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.
It is not incremented on each update. Compare this to the revision field.
Minimum value is 1.
query string
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.
threshold object
Hide threshold attributes Show threshold attributes object
- cardinality array[object]
  
  The field on which the cardinality is applied.
  Hide cardinality attributes Show cardinality attributes object
  
  field string Required
  
  The field on which to calculate and compare the cardinality.
  
  value integer Required
  
  The threshold value from which an alert is generated based on unique number of values of cardinality.field.
  
  Minimum value is 0.
- field string | array[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.
  
  One of:
  string-1 string array-2 array[string]
- value integer Required
  
  The threshold value from which an alert is generated.
  
  Minimum value is 1.
type string

Rule type

Value is threshold.
alert_suppression object

Defines alert suppression configuration.
Hide alert_suppression attribute Show alert_suppression attribute object
- duration object Required
  Hide duration attributes Show duration attributes object
  
  unit string Required
  
  Time unit
  
  Values are s, m, or h.
  
  value integer Required
  
  Minimum value is 1.
data_view_id string
filters array

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 array[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.
saved_id string

Kibana saved search used by the rule to create alerts.
language string

Values are kuery or lucene.

actions array[object]

Array defining the automated actions (notifications) taken when alerts are generated.
Hide actions attributes Show actions attributes object
- 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.
  Additional properties are allowed.
- frequency object
  
  The action frequency defines when the action runs (for example, only on rule execution or at specific time intervals).
  Hide frequency attributes Show frequency attributes object
  
  notifyWhen string Required
  
  Defines how often rules run actions.
  
  Values are onActiveAlert, onThrottleInterval, or 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 string | null Required
  
  Defines how often rule actions are taken.
  
  One of:
  string-1 string | null string-2 string | null
  
  Values are no_actions or 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.
  Additional properties are allowed.
- uuid string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
alias_purpose string

Values are savedObjectConversion or savedObjectImport.
alias_target_id string
author array[string]

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

The rule’s description.

Minimum length is 1.
enabled boolean

Determines whether the rule is enabled. Defaults to true.
exceptions_list array[object]

Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.
Hide exceptions_list attributes Show exceptions_list attributes object
- id string(nonempty) Required
  
  ID of the exception container
  
  Minimum length is 1.
- list_id string(nonempty) Required
  
  List ID of the exception container
  
  Minimum length is 1.
- namespace_type string Required
  
  Determines the exceptions validity in rule's Kibana space
  
  Values are agnostic or single.
- type string Required
  
  The exception type
  
  Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.
false_positives array[string]

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.
from string(date-math)

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).
id string(uuid)

A dynamic unique identifier for the rule object. It is randomly generated when a rule is created and cannot be changed after that. It is always a UUID. It is unique within a given Kibana space. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have different object ids.
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).
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.
Hide investigation_fields attribute Show investigation_fields attribute object
- field_names array[string(nonempty)] Required
  
  A string that does not contain only whitespace characters
  
  At least 1 element. Minimum length of each is 1.
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).

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.

Minimum value is 1. Default value is 100.
meta object

Placeholder for metadata about the rule.

This field is overwritten when you save changes to the rule’s settings.

Additional properties are allowed.
name string

A human-readable name for the rule.

Minimum length is 1.
namespace string

Has no effect.
note string

Notes to help investigate alerts produced by the rule.
outcome string

Values are exactMatch, aliasMatch, or conflict.
output_index string Deprecated

(deprecated) Has no effect.
references array[string]

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.
related_integrations array[object]
Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:
- package: name of the package (required, unique id)
- version: version of the package (required, semver-compatible)
- integration: name of the integration of this package (optional, id within the package)
There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.
Hide related_integrations attributes Show related_integrations attributes object
- integration string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- package string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- version string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
required_fields array[object]

Elasticsearch fields and their types that need to be present for the rule to function.

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.

Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.
Hide required_fields attributes Show required_fields attributes object
- name string(nonempty) Required
  
  Name of an Elasticsearch field
  
  Minimum length is 1.
- type string(nonempty) Required
  
  Type of the Elasticsearch field
  
  Minimum length is 1.
response_actions array[object]
One of:
Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object
Hide attributes Show attributes

action_type_id string Required

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

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

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[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.
Hide attributes Show attributes

action_type_id string Required

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object

Hide attributes Show attributes

command string Required

Value is isolate.

comment string

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.
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
Minimum value is 0, maximum value is 100.
risk_score_mapping array[object]

Overrides generated alerts' risk_score with a value from the source event
Hide risk_score_mapping attributes Show risk_score_mapping attributes object
- field string Required
  
  Source event field used to override the default risk_score.
- operator string Required
  
  Value is equals.
- 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
  Minimum value is 0, maximum value is 100.
- value string Required
rule_id string

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

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 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
Values are low, medium, high, or critical.
severity_mapping array[object]

Overrides generated alerts' severity with values from the source event
Hide severity_mapping attributes Show severity_mapping attributes object
- field string Required
  
  Source event field used to override the default severity.
- operator string Required
  
  Value is equals.
- severity string 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 are low, medium, high, or critical.
- value string Required
tags array[string]

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.
threat array[object]

Currently, only threats described using the MITRE ATT&CK™ framework are supported.
Hide threat attributes Show threat attributes object
- framework string Required
  
  Relevant attack framework
- tactic object Required
  
  Object containing information on the attack type
  Hide tactic attributes Show tactic attributes object
  
  id string Required
  
  Tactic ID
  
  name string Required
  
  Tactic name
  
  reference string Required
  
  Tactic reference
- technique array[object]
  
  Array containing information on the attack techniques (optional)
  Hide technique attributes Show technique attributes object
  
  id string Required
  
  Technique ID
  
  name string Required
  
  Technique name
  
  reference string Required
  
  Technique reference
  
  subtechnique array[object]
  
  Array containing more specific information on the attack technique.
  
  Hide subtechnique attributes Show subtechnique attributes object
  
  id string Required
  
  Subtechnique ID
  
  name string Required
  
  Subtechnique name
  
  reference string Required
  
  Subtechnique reference
throttle string | null

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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
version integer
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.
It is not incremented on each update. Compare this to the revision field.
Minimum value is 1.
query string
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.
threat_index array[string]

Elasticsearch indices used to check which field values generate alerts.
threat_mapping array[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 Example of Threat Match rule which uses both and and or logic.
At least 1 element.
Hide threat_mapping attribute Show threat_mapping attribute object
- entries array[object] Required
  Hide entries attributes Show entries attributes object
  
  field string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  type string Required
  
  Value is mapping.
  
  value string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
threat_query string

Query used to determine which fields in the Elasticsearch index are used for generating alerts.
type string

Rule type

Value is threat_match.
alert_suppression object

Defines alert suppression configuration.
Hide alert_suppression attributes Show alert_suppression attributes object
- duration object
  Hide duration attributes Show duration attributes object
  
  unit string Required
  
  Time unit
  
  Values are s, m, or h.
  
  value integer Required
  
  Minimum value is 1.
- group_by array[string] Required
  
  At least 1 but not more than 3 elements.
- missing_fields_strategy string
  
  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 are doNotSuppress or suppress.
concurrent_searches integer

Minimum value is 1.
data_view_id string
filters array

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 array[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.
items_per_search integer

Minimum value is 1.
saved_id string

Kibana saved search used by the rule to create alerts.
threat_filters array

Query and filter context array used to filter documents from the Elasticsearch index containing the threat values
threat_indicator_path string

Defines the path to the threat indicator in the indicator documents (optional)
threat_language string

Values are kuery or lucene.
language string

Values are kuery or lucene.

actions array[object]

Array defining the automated actions (notifications) taken when alerts are generated.
Hide actions attributes Show actions attributes object
- 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.
  Additional properties are allowed.
- frequency object
  
  The action frequency defines when the action runs (for example, only on rule execution or at specific time intervals).
  Hide frequency attributes Show frequency attributes object
  
  notifyWhen string Required
  
  Defines how often rules run actions.
  
  Values are onActiveAlert, onThrottleInterval, or 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 string | null Required
  
  Defines how often rule actions are taken.
  
  One of:
  string-1 string | null string-2 string | null
  
  Values are no_actions or 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.
  Additional properties are allowed.
- uuid string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
alias_purpose string

Values are savedObjectConversion or savedObjectImport.
alias_target_id string
author array[string]

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

The rule’s description.

Minimum length is 1.
enabled boolean

Determines whether the rule is enabled. Defaults to true.
exceptions_list array[object]

Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.
Hide exceptions_list attributes Show exceptions_list attributes object
- id string(nonempty) Required
  
  ID of the exception container
  
  Minimum length is 1.
- list_id string(nonempty) Required
  
  List ID of the exception container
  
  Minimum length is 1.
- namespace_type string Required
  
  Determines the exceptions validity in rule's Kibana space
  
  Values are agnostic or single.
- type string Required
  
  The exception type
  
  Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.
false_positives array[string]

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.
from string(date-math)

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).
id string(uuid)

A dynamic unique identifier for the rule object. It is randomly generated when a rule is created and cannot be changed after that. It is always a UUID. It is unique within a given Kibana space. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have different object ids.
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).
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.
Hide investigation_fields attribute Show investigation_fields attribute object
- field_names array[string(nonempty)] Required
  
  A string that does not contain only whitespace characters
  
  At least 1 element. Minimum length of each is 1.
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).

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.

Minimum value is 1. Default value is 100.
meta object

Placeholder for metadata about the rule.

This field is overwritten when you save changes to the rule’s settings.

Additional properties are allowed.
name string

A human-readable name for the rule.

Minimum length is 1.
namespace string

Has no effect.
note string

Notes to help investigate alerts produced by the rule.
outcome string

Values are exactMatch, aliasMatch, or conflict.
output_index string Deprecated

(deprecated) Has no effect.
references array[string]

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.
related_integrations array[object]
Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:
- package: name of the package (required, unique id)
- version: version of the package (required, semver-compatible)
- integration: name of the integration of this package (optional, id within the package)
There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.
Hide related_integrations attributes Show related_integrations attributes object
- integration string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- package string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- version string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
required_fields array[object]

Elasticsearch fields and their types that need to be present for the rule to function.

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.

Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.
Hide required_fields attributes Show required_fields attributes object
- name string(nonempty) Required
  
  Name of an Elasticsearch field
  
  Minimum length is 1.
- type string(nonempty) Required
  
  Type of the Elasticsearch field
  
  Minimum length is 1.
response_actions array[object]
One of:
Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object
Hide attributes Show attributes

action_type_id string Required

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

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

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[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.
Hide attributes Show attributes

action_type_id string Required

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object

Hide attributes Show attributes

command string Required

Value is isolate.

comment string

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.
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
Minimum value is 0, maximum value is 100.
risk_score_mapping array[object]

Overrides generated alerts' risk_score with a value from the source event
Hide risk_score_mapping attributes Show risk_score_mapping attributes object
- field string Required
  
  Source event field used to override the default risk_score.
- operator string Required
  
  Value is equals.
- 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
  Minimum value is 0, maximum value is 100.
- value string Required
rule_id string

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

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 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
Values are low, medium, high, or critical.
severity_mapping array[object]

Overrides generated alerts' severity with values from the source event
Hide severity_mapping attributes Show severity_mapping attributes object
- field string Required
  
  Source event field used to override the default severity.
- operator string Required
  
  Value is equals.
- severity string 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 are low, medium, high, or critical.
- value string Required
tags array[string]

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.
threat array[object]

Currently, only threats described using the MITRE ATT&CK™ framework are supported.
Hide threat attributes Show threat attributes object
- framework string Required
  
  Relevant attack framework
- tactic object Required
  
  Object containing information on the attack type
  Hide tactic attributes Show tactic attributes object
  
  id string Required
  
  Tactic ID
  
  name string Required
  
  Tactic name
  
  reference string Required
  
  Tactic reference
- technique array[object]
  
  Array containing information on the attack techniques (optional)
  Hide technique attributes Show technique attributes object
  
  id string Required
  
  Technique ID
  
  name string Required
  
  Technique name
  
  reference string Required
  
  Technique reference
  
  subtechnique array[object]
  
  Array containing more specific information on the attack technique.
  
  Hide subtechnique attributes Show subtechnique attributes object
  
  id string Required
  
  Subtechnique ID
  
  name string Required
  
  Subtechnique name
  
  reference string Required
  
  Subtechnique reference
throttle string | null

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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
version integer
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.
It is not incremented on each update. Compare this to the revision field.
Minimum value is 1.
anomaly_threshold integer

Anomaly score threshold above which the rule creates an alert. Valid values are from 0 to 100.

Minimum value is 0.
machine_learning_job_id string | array[string]

Machine learning job ID(s) the rule monitors for anomaly scores.

One of:
string-1 string array-2 array[string]
type string

Rule type

Value is machine_learning.
alert_suppression object

Defines alert suppression configuration.
Hide alert_suppression attributes Show alert_suppression attributes object
- duration object
  Hide duration attributes Show duration attributes object
  
  unit string Required
  
  Time unit
  
  Values are s, m, or h.
  
  value integer Required
  
  Minimum value is 1.
- group_by array[string] Required
  
  At least 1 but not more than 3 elements.
- missing_fields_strategy string
  
  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 are doNotSuppress or suppress.

actions array[object]

Array defining the automated actions (notifications) taken when alerts are generated.
Hide actions attributes Show actions attributes object
- 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.
  Additional properties are allowed.
- frequency object
  
  The action frequency defines when the action runs (for example, only on rule execution or at specific time intervals).
  Hide frequency attributes Show frequency attributes object
  
  notifyWhen string Required
  
  Defines how often rules run actions.
  
  Values are onActiveAlert, onThrottleInterval, or 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 string | null Required
  
  Defines how often rule actions are taken.
  
  One of:
  string-1 string | null string-2 string | null
  
  Values are no_actions or 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.
  Additional properties are allowed.
- uuid string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
alias_purpose string

Values are savedObjectConversion or savedObjectImport.
alias_target_id string
author array[string]

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

The rule’s description.

Minimum length is 1.
enabled boolean

Determines whether the rule is enabled. Defaults to true.
exceptions_list array[object]

Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.
Hide exceptions_list attributes Show exceptions_list attributes object
- id string(nonempty) Required
  
  ID of the exception container
  
  Minimum length is 1.
- list_id string(nonempty) Required
  
  List ID of the exception container
  
  Minimum length is 1.
- namespace_type string Required
  
  Determines the exceptions validity in rule's Kibana space
  
  Values are agnostic or single.
- type string Required
  
  The exception type
  
  Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.
false_positives array[string]

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.
from string(date-math)

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).
id string(uuid)

A dynamic unique identifier for the rule object. It is randomly generated when a rule is created and cannot be changed after that. It is always a UUID. It is unique within a given Kibana space. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have different object ids.
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).
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.
Hide investigation_fields attribute Show investigation_fields attribute object
- field_names array[string(nonempty)] Required
  
  A string that does not contain only whitespace characters
  
  At least 1 element. Minimum length of each is 1.
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).

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.

Minimum value is 1. Default value is 100.
meta object

Placeholder for metadata about the rule.

This field is overwritten when you save changes to the rule’s settings.

Additional properties are allowed.
name string

A human-readable name for the rule.

Minimum length is 1.
namespace string

Has no effect.
note string

Notes to help investigate alerts produced by the rule.
outcome string

Values are exactMatch, aliasMatch, or conflict.
output_index string Deprecated

(deprecated) Has no effect.
references array[string]

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.
related_integrations array[object]
Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:
- package: name of the package (required, unique id)
- version: version of the package (required, semver-compatible)
- integration: name of the integration of this package (optional, id within the package)
There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.
Hide related_integrations attributes Show related_integrations attributes object
- integration string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- package string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- version string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
required_fields array[object]

Elasticsearch fields and their types that need to be present for the rule to function.

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.

Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.
Hide required_fields attributes Show required_fields attributes object
- name string(nonempty) Required
  
  Name of an Elasticsearch field
  
  Minimum length is 1.
- type string(nonempty) Required
  
  Type of the Elasticsearch field
  
  Minimum length is 1.
response_actions array[object]
One of:
Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object
Hide attributes Show attributes

action_type_id string Required

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

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

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[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.
Hide attributes Show attributes

action_type_id string Required

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object

Hide attributes Show attributes

command string Required

Value is isolate.

comment string

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.
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
Minimum value is 0, maximum value is 100.
risk_score_mapping array[object]

Overrides generated alerts' risk_score with a value from the source event
Hide risk_score_mapping attributes Show risk_score_mapping attributes object
- field string Required
  
  Source event field used to override the default risk_score.
- operator string Required
  
  Value is equals.
- 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
  Minimum value is 0, maximum value is 100.
- value string Required
rule_id string

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

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 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
Values are low, medium, high, or critical.
severity_mapping array[object]

Overrides generated alerts' severity with values from the source event
Hide severity_mapping attributes Show severity_mapping attributes object
- field string Required
  
  Source event field used to override the default severity.
- operator string Required
  
  Value is equals.
- severity string 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 are low, medium, high, or critical.
- value string Required
tags array[string]

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.
threat array[object]

Currently, only threats described using the MITRE ATT&CK™ framework are supported.
Hide threat attributes Show threat attributes object
- framework string Required
  
  Relevant attack framework
- tactic object Required
  
  Object containing information on the attack type
  Hide tactic attributes Show tactic attributes object
  
  id string Required
  
  Tactic ID
  
  name string Required
  
  Tactic name
  
  reference string Required
  
  Tactic reference
- technique array[object]
  
  Array containing information on the attack techniques (optional)
  Hide technique attributes Show technique attributes object
  
  id string Required
  
  Technique ID
  
  name string Required
  
  Technique name
  
  reference string Required
  
  Technique reference
  
  subtechnique array[object]
  
  Array containing more specific information on the attack technique.
  
  Hide subtechnique attributes Show subtechnique attributes object
  
  id string Required
  
  Subtechnique ID
  
  name string Required
  
  Subtechnique name
  
  reference string Required
  
  Subtechnique reference
throttle string | null

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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
version integer
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.
It is not incremented on each update. Compare this to the revision field.
Minimum value is 1.
history_window_start string(nonempty)

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.

Minimum length is 1.
new_terms_fields array[string]

Fields to monitor for new values.

At least 1 but not more than 3 elements.
query string
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.
type string

Rule type

Value is new_terms.
alert_suppression object

Defines alert suppression configuration.
Hide alert_suppression attributes Show alert_suppression attributes object
- duration object
  Hide duration attributes Show duration attributes object
  
  unit string Required
  
  Time unit
  
  Values are s, m, or h.
  
  value integer Required
  
  Minimum value is 1.
- group_by array[string] Required
  
  At least 1 but not more than 3 elements.
- missing_fields_strategy string
  
  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 are doNotSuppress or suppress.
data_view_id string
filters array

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 array[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.
language string

Values are kuery or lucene.

actions array[object]

Array defining the automated actions (notifications) taken when alerts are generated.
Hide actions attributes Show actions attributes object
- 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.
  Additional properties are allowed.
- frequency object
  
  The action frequency defines when the action runs (for example, only on rule execution or at specific time intervals).
  Hide frequency attributes Show frequency attributes object
  
  notifyWhen string Required
  
  Defines how often rules run actions.
  
  Values are onActiveAlert, onThrottleInterval, or 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 string | null Required
  
  Defines how often rule actions are taken.
  
  One of:
  string-1 string | null string-2 string | null
  
  Values are no_actions or 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.
  Additional properties are allowed.
- uuid string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
alias_purpose string

Values are savedObjectConversion or savedObjectImport.
alias_target_id string
author array[string]

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

The rule’s description.

Minimum length is 1.
enabled boolean

Determines whether the rule is enabled. Defaults to true.
exceptions_list array[object]

Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.
Hide exceptions_list attributes Show exceptions_list attributes object
- id string(nonempty) Required
  
  ID of the exception container
  
  Minimum length is 1.
- list_id string(nonempty) Required
  
  List ID of the exception container
  
  Minimum length is 1.
- namespace_type string Required
  
  Determines the exceptions validity in rule's Kibana space
  
  Values are agnostic or single.
- type string Required
  
  The exception type
  
  Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.
false_positives array[string]

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.
from string(date-math)

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).
id string(uuid)

A dynamic unique identifier for the rule object. It is randomly generated when a rule is created and cannot be changed after that. It is always a UUID. It is unique within a given Kibana space. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have different object ids.
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).
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.
Hide investigation_fields attribute Show investigation_fields attribute object
- field_names array[string(nonempty)] Required
  
  A string that does not contain only whitespace characters
  
  At least 1 element. Minimum length of each is 1.
language string

Value is esql.
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).

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.

Minimum value is 1. Default value is 100.
meta object

Placeholder for metadata about the rule.

This field is overwritten when you save changes to the rule’s settings.

Additional properties are allowed.
name string

A human-readable name for the rule.

Minimum length is 1.
namespace string

Has no effect.
note string

Notes to help investigate alerts produced by the rule.
outcome string

Values are exactMatch, aliasMatch, or conflict.
output_index string Deprecated

(deprecated) Has no effect.
query string
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.
references array[string]

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.
related_integrations array[object]
Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:
- package: name of the package (required, unique id)
- version: version of the package (required, semver-compatible)
- integration: name of the integration of this package (optional, id within the package)
There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.
Hide related_integrations attributes Show related_integrations attributes object
- integration string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- package string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- version string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
required_fields array[object]

Elasticsearch fields and their types that need to be present for the rule to function.

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.

Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.
Hide required_fields attributes Show required_fields attributes object
- name string(nonempty) Required
  
  Name of an Elasticsearch field
  
  Minimum length is 1.
- type string(nonempty) Required
  
  Type of the Elasticsearch field
  
  Minimum length is 1.
response_actions array[object]
One of:
Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object
Hide attributes Show attributes

action_type_id string Required

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

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

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[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.
Hide attributes Show attributes

action_type_id string Required

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object

Hide attributes Show attributes

command string Required

Value is isolate.

comment string

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.
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
Minimum value is 0, maximum value is 100.
risk_score_mapping array[object]

Overrides generated alerts' risk_score with a value from the source event
Hide risk_score_mapping attributes Show risk_score_mapping attributes object
- field string Required
  
  Source event field used to override the default risk_score.
- operator string Required
  
  Value is equals.
- 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
  Minimum value is 0, maximum value is 100.
- value string Required
rule_id string

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

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 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
Values are low, medium, high, or critical.
severity_mapping array[object]

Overrides generated alerts' severity with values from the source event
Hide severity_mapping attributes Show severity_mapping attributes object
- field string Required
  
  Source event field used to override the default severity.
- operator string Required
  
  Value is equals.
- severity string 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 are low, medium, high, or critical.
- value string Required
tags array[string]

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.
threat array[object]

Currently, only threats described using the MITRE ATT&CK™ framework are supported.
Hide threat attributes Show threat attributes object
- framework string Required
  
  Relevant attack framework
- tactic object Required
  
  Object containing information on the attack type
  Hide tactic attributes Show tactic attributes object
  
  id string Required
  
  Tactic ID
  
  name string Required
  
  Tactic name
  
  reference string Required
  
  Tactic reference
- technique array[object]
  
  Array containing information on the attack techniques (optional)
  Hide technique attributes Show technique attributes object
  
  id string Required
  
  Technique ID
  
  name string Required
  
  Technique name
  
  reference string Required
  
  Technique reference
  
  subtechnique array[object]
  
  Array containing more specific information on the attack technique.
  
  Hide subtechnique attributes Show subtechnique attributes object
  
  id string Required
  
  Subtechnique ID
  
  name string Required
  
  Subtechnique name
  
  reference string Required
  
  Subtechnique reference
throttle string | null

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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
type string

Rule type

Value is esql.
version integer
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.
It is not incremented on each update. Compare this to the revision field.
Minimum value is 1.
alert_suppression object

Defines alert suppression configuration.
Hide alert_suppression attributes Show alert_suppression attributes object
- duration object
  Hide duration attributes Show duration attributes object
  
  unit string Required
  
  Time unit
  
  Values are s, m, or h.
  
  value integer Required
  
  Minimum value is 1.
- group_by array[string] Required
  
  At least 1 but not more than 3 elements.
- missing_fields_strategy string
  
  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 are doNotSuppress or suppress.

Responses

200 application/json

Indicates a successful call.
Any of:
Security_Detections_API_EqlRuleResponseFields object Security_Detections_API_QueryRuleResponseFields object Security_Detections_API_SavedQueryRuleResponseFields object Security_Detections_API_ThresholdRuleResponseFields object Security_Detections_API_ThreatMatchRuleResponseFields object Security_Detections_API_MachineLearningRuleResponseFields object Security_Detections_API_NewTermsRuleResponseFields object Security_Detections_API_EsqlRuleResponseFields object
Hide attributes Show attributes

actions array[object] Required

Array defining the automated actions (notifications) taken when alerts are generated.

Hide actions attributes Show actions attributes object

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.

Additional properties are allowed.

frequency object

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

Hide frequency attributes Show frequency attributes object

notifyWhen string Required

Defines how often rules run actions.

Values are onActiveAlert, onThrottleInterval, or 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 string | null Required

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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.

Additional properties are allowed.

uuid string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

alias_purpose string

Values are savedObjectConversion or savedObjectImport.

alias_target_id string

author array[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 Required

The rule’s description.

Minimum length is 1.

enabled boolean Required

Determines whether the rule is enabled. Defaults to true.

exceptions_list array[object] Required

Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.

Hide exceptions_list attributes Show exceptions_list attributes object

id string(nonempty) Required

ID of the exception container

Minimum length is 1.

list_id string(nonempty) Required

List ID of the exception container

Minimum length is 1.

namespace_type string Required

Determines the exceptions validity in rule's Kibana space

Values are agnostic or single.

type string Required

The exception type

Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.

false_positives array[string] Required

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.

from string(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.

Hide investigation_fields attribute Show investigation_fields attribute object

field_names array[string(nonempty)] Required

A string that does not contain only whitespace characters

At least 1 element. Minimum length of each is 1.

license string

The rule's license.

max_signals integer Required

Maximum number of alerts the rule can create during a single run (the rule’s Max alerts per run advanced setting value).

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.

Minimum value is 1. Default value is 100.

meta object

Placeholder for metadata about the rule.

This field is overwritten when you save changes to the rule’s settings.

Additional properties are allowed.

name string Required

A human-readable name for the rule.

Minimum length is 1.

namespace string

Has no effect.

note string

Notes to help investigate alerts produced by the rule.

outcome string

Values are exactMatch, aliasMatch, or conflict.

output_index string Deprecated

(deprecated) Has no effect.

references array[string] Required

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.

related_integrations array[object] Required

Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:

package: name of the package (required, unique id)

version: version of the package (required, semver-compatible)

integration: name of the integration of this package (optional, id within the package)

There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.

Hide related_integrations attributes Show related_integrations attributes object

integration string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

package string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

version string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

required_fields array[object] Required

Elasticsearch fields and their types that need to be present for the rule to function.

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.

Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.

Hide required_fields attributes Show required_fields attributes object

name string(nonempty) Required

Name of an Elasticsearch field

Minimum length is 1.

type string(nonempty) Required

Type of the Elasticsearch field

Minimum length is 1.

response_actions array[object]

One of:
Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object

Hide attributes Show attributes

action_type_id string Required

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

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

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[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.

Hide attributes Show attributes

action_type_id string Required

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object

Hide attributes Show attributes

command string Required

Value is isolate.

comment string

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.

risk_score integer 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

Minimum value is 0, maximum value is 100.

risk_score_mapping array[object] Required

Overrides generated alerts' risk_score with a value from the source event

Hide risk_score_mapping attributes Show risk_score_mapping attributes object

field string Required

Source event field used to override the default risk_score.

operator string Required

Value is equals.

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

Minimum value is 0, maximum value is 100.

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 string 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 are low, medium, high, or critical.

severity_mapping array[object] Required

Overrides generated alerts' severity with values from the source event

Hide severity_mapping attributes Show severity_mapping attributes object

field string Required

Source event field used to override the default severity.

operator string Required

Value is equals.

severity string 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 are low, medium, high, or critical.

value string Required

tags array[string] Required

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.

threat array[object] Required

Currently, only threats described using the MITRE ATT&CK™ framework are supported.

Hide threat attributes Show threat attributes object

framework string Required

Relevant attack framework

tactic object Required

Object containing information on the attack type

Hide tactic attributes Show tactic attributes object

id string Required

Tactic ID

name string Required

Tactic name

reference string Required

Tactic reference

technique array[object]

Array containing information on the attack techniques (optional)

Hide technique attributes Show technique attributes object

id string Required

Technique ID

name string Required

Technique name

reference string Required

Technique reference

subtechnique array[object]

Array containing more specific information on the attack technique.

Hide subtechnique attributes Show subtechnique attributes object

id string Required

Subtechnique ID

name string Required

Subtechnique name

reference string Required

Subtechnique reference

throttle string | null

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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 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.

It is not incremented on each update. Compare this to the revision field.

Minimum value is 1.

created_at string(date-time) Required

created_by string Required

execution_summary object

Summary of the last execution of a rule.

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

Hide execution_summary attribute Show execution_summary attribute object

last_execution object Required

Hide last_execution attributes Show last_execution attributes object

date string(date-time) Required

Date of the last execution

message string Required

metrics object Required

Hide metrics attributes Show metrics attributes object

execution_gap_duration_s integer

Duration in seconds of execution gap

Minimum value is 0.

frozen_indices_queried_count integer

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

Minimum value is 0.

gap_range object

Range of the execution gap

Hide gap_range attributes Show gap_range attributes object

gte string Required

Start date of the execution gap

lte string Required

End date of the execution gap

total_enrichment_duration_ms integer

Total time spent enriching documents during current rule execution cycle

Minimum value is 0.

total_indexing_duration_ms integer

Total time spent indexing documents during current rule execution cycle

Minimum value is 0.

total_search_duration_ms integer

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

Minimum value is 0.

status string Required

Status of the last execution

Values are going to run, running, partial failure, failed, or succeeded.

status_order integer Required

id string(uuid) Required

A dynamic unique identifier for the rule object. It is randomly generated when a rule is created and cannot be changed after that. It is always a UUID. It is unique within a given Kibana space. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have different object ids.

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

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.

Minimum value is 0.

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 object 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:
Security_Detections_API_ExternalRuleSource object Security_Detections_API_InternalRuleSource object

Type of rule source for externally sourced rules, i.e. rules that have an external source, such as the Elastic Prebuilt rules repo.

Hide attributes Show attributes

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

type string Required Discriminator

Value is external.

updated_at string(date-time) Required

updated_by string Required

language string Required

Query language to use

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

type string Required Discriminator

Rule type

Value is eql.

alert_suppression object

Defines alert suppression configuration.

Hide alert_suppression attributes Show alert_suppression attributes object

duration object

Hide duration attributes Show duration attributes object

unit string Required

Time unit

Values are s, m, or h.

value integer Required

Minimum value is 1.

group_by array[string] Required

At least 1 but not more than 3 elements.

missing_fields_strategy string

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 are doNotSuppress or suppress.

data_view_id string

event_category_override string

filters array

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

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.
Hide attributes Show attributes

actions array[object] Required

Array defining the automated actions (notifications) taken when alerts are generated.

Hide actions attributes Show actions attributes object

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.

Additional properties are allowed.

frequency object

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

Hide frequency attributes Show frequency attributes object

notifyWhen string Required

Defines how often rules run actions.

Values are onActiveAlert, onThrottleInterval, or 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 string | null Required

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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.

Additional properties are allowed.

uuid string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

alias_purpose string

Values are savedObjectConversion or savedObjectImport.

alias_target_id string

author array[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 Required

The rule’s description.

Minimum length is 1.

enabled boolean Required

Determines whether the rule is enabled. Defaults to true.

exceptions_list array[object] Required

Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.

Hide exceptions_list attributes Show exceptions_list attributes object

id string(nonempty) Required

ID of the exception container

Minimum length is 1.

list_id string(nonempty) Required

List ID of the exception container

Minimum length is 1.

namespace_type string Required

Determines the exceptions validity in rule's Kibana space

Values are agnostic or single.

type string Required

The exception type

Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.

false_positives array[string] Required

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.

from string(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.

Hide investigation_fields attribute Show investigation_fields attribute object

field_names array[string(nonempty)] Required

A string that does not contain only whitespace characters

At least 1 element. Minimum length of each is 1.

license string

The rule's license.

max_signals integer Required

Maximum number of alerts the rule can create during a single run (the rule’s Max alerts per run advanced setting value).

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.

Minimum value is 1. Default value is 100.

meta object

Placeholder for metadata about the rule.

This field is overwritten when you save changes to the rule’s settings.

Additional properties are allowed.

name string Required

A human-readable name for the rule.

Minimum length is 1.

namespace string

Has no effect.

note string

Notes to help investigate alerts produced by the rule.

outcome string

Values are exactMatch, aliasMatch, or conflict.

output_index string Deprecated

(deprecated) Has no effect.

references array[string] Required

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.

related_integrations array[object] Required

Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:

package: name of the package (required, unique id)

version: version of the package (required, semver-compatible)

integration: name of the integration of this package (optional, id within the package)

There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.

Hide related_integrations attributes Show related_integrations attributes object

integration string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

package string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

version string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

required_fields array[object] Required

Elasticsearch fields and their types that need to be present for the rule to function.

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.

Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.

Hide required_fields attributes Show required_fields attributes object

name string(nonempty) Required

Name of an Elasticsearch field

Minimum length is 1.

type string(nonempty) Required

Type of the Elasticsearch field

Minimum length is 1.

response_actions array[object]

One of:
Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object

Hide attributes Show attributes

action_type_id string Required

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

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

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[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.

Hide attributes Show attributes

action_type_id string Required

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object

Hide attributes Show attributes

command string Required

Value is isolate.

comment string

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.

risk_score integer 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

Minimum value is 0, maximum value is 100.

risk_score_mapping array[object] Required

Overrides generated alerts' risk_score with a value from the source event

Hide risk_score_mapping attributes Show risk_score_mapping attributes object

field string Required

Source event field used to override the default risk_score.

operator string Required

Value is equals.

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

Minimum value is 0, maximum value is 100.

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 string 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 are low, medium, high, or critical.

severity_mapping array[object] Required

Overrides generated alerts' severity with values from the source event

Hide severity_mapping attributes Show severity_mapping attributes object

field string Required

Source event field used to override the default severity.

operator string Required

Value is equals.

severity string 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 are low, medium, high, or critical.

value string Required

tags array[string] Required

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.

threat array[object] Required

Currently, only threats described using the MITRE ATT&CK™ framework are supported.

Hide threat attributes Show threat attributes object

framework string Required

Relevant attack framework

tactic object Required

Object containing information on the attack type

Hide tactic attributes Show tactic attributes object

id string Required

Tactic ID

name string Required

Tactic name

reference string Required

Tactic reference

technique array[object]

Array containing information on the attack techniques (optional)

Hide technique attributes Show technique attributes object

id string Required

Technique ID

name string Required

Technique name

reference string Required

Technique reference

subtechnique array[object]

Array containing more specific information on the attack technique.

Hide subtechnique attributes Show subtechnique attributes object

id string Required

Subtechnique ID

name string Required

Subtechnique name

reference string Required

Subtechnique reference

throttle string | null

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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 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.

It is not incremented on each update. Compare this to the revision field.

Minimum value is 1.

created_at string(date-time) Required

created_by string Required

execution_summary object

Summary of the last execution of a rule.

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

Hide execution_summary attribute Show execution_summary attribute object

last_execution object Required

Hide last_execution attributes Show last_execution attributes object

date string(date-time) Required

Date of the last execution

message string Required

metrics object Required

Hide metrics attributes Show metrics attributes object

execution_gap_duration_s integer

Duration in seconds of execution gap

Minimum value is 0.

frozen_indices_queried_count integer

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

Minimum value is 0.

gap_range object

Range of the execution gap

Hide gap_range attributes Show gap_range attributes object

gte string Required

Start date of the execution gap

lte string Required

End date of the execution gap

total_enrichment_duration_ms integer

Total time spent enriching documents during current rule execution cycle

Minimum value is 0.

total_indexing_duration_ms integer

Total time spent indexing documents during current rule execution cycle

Minimum value is 0.

total_search_duration_ms integer

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

Minimum value is 0.

status string Required

Status of the last execution

Values are going to run, running, partial failure, failed, or succeeded.

status_order integer Required

id string(uuid) Required

A dynamic unique identifier for the rule object. It is randomly generated when a rule is created and cannot be changed after that. It is always a UUID. It is unique within a given Kibana space. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have different object ids.

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

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.

Minimum value is 0.

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 object 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:
Security_Detections_API_ExternalRuleSource object Security_Detections_API_InternalRuleSource object

Type of rule source for externally sourced rules, i.e. rules that have an external source, such as the Elastic Prebuilt rules repo.

Hide attributes Show attributes

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

type string Required Discriminator

Value is external.

updated_at string(date-time) Required

updated_by string Required

type string Required Discriminator

Rule type

Value is query.

alert_suppression object

Defines alert suppression configuration.

Hide alert_suppression attributes Show alert_suppression attributes object

duration object

Hide duration attributes Show duration attributes object

unit string Required

Time unit

Values are s, m, or h.

value integer Required

Minimum value is 1.

group_by array[string] Required

At least 1 but not more than 3 elements.

missing_fields_strategy string

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 are doNotSuppress or suppress.

data_view_id string

filters array

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

saved_id string

Kibana saved search used by the rule to create alerts.

language string Required

Values are kuery or lucene.

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.
Hide attributes Show attributes

actions array[object] Required

Array defining the automated actions (notifications) taken when alerts are generated.

Hide actions attributes Show actions attributes object

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.

Additional properties are allowed.

frequency object

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

Hide frequency attributes Show frequency attributes object

notifyWhen string Required

Defines how often rules run actions.

Values are onActiveAlert, onThrottleInterval, or 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 string | null Required

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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.

Additional properties are allowed.

uuid string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

alias_purpose string

Values are savedObjectConversion or savedObjectImport.

alias_target_id string

author array[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 Required

The rule’s description.

Minimum length is 1.

enabled boolean Required

Determines whether the rule is enabled. Defaults to true.

exceptions_list array[object] Required

Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.

Hide exceptions_list attributes Show exceptions_list attributes object

id string(nonempty) Required

ID of the exception container

Minimum length is 1.

list_id string(nonempty) Required

List ID of the exception container

Minimum length is 1.

namespace_type string Required

Determines the exceptions validity in rule's Kibana space

Values are agnostic or single.

type string Required

The exception type

Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.

false_positives array[string] Required

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.

from string(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.

Hide investigation_fields attribute Show investigation_fields attribute object

field_names array[string(nonempty)] Required

A string that does not contain only whitespace characters

At least 1 element. Minimum length of each is 1.

license string

The rule's license.

max_signals integer Required

Maximum number of alerts the rule can create during a single run (the rule’s Max alerts per run advanced setting value).

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.

Minimum value is 1. Default value is 100.

meta object

Placeholder for metadata about the rule.

This field is overwritten when you save changes to the rule’s settings.

Additional properties are allowed.

name string Required

A human-readable name for the rule.

Minimum length is 1.

namespace string

Has no effect.

note string

Notes to help investigate alerts produced by the rule.

outcome string

Values are exactMatch, aliasMatch, or conflict.

output_index string Deprecated

(deprecated) Has no effect.

references array[string] Required

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.

related_integrations array[object] Required

Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:

package: name of the package (required, unique id)

version: version of the package (required, semver-compatible)

integration: name of the integration of this package (optional, id within the package)

There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.

Hide related_integrations attributes Show related_integrations attributes object

integration string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

package string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

version string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

required_fields array[object] Required

Elasticsearch fields and their types that need to be present for the rule to function.

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.

Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.

Hide required_fields attributes Show required_fields attributes object

name string(nonempty) Required

Name of an Elasticsearch field

Minimum length is 1.

type string(nonempty) Required

Type of the Elasticsearch field

Minimum length is 1.

response_actions array[object]

One of:
Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object

Hide attributes Show attributes

action_type_id string Required

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

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

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[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.

Hide attributes Show attributes

action_type_id string Required

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object

Hide attributes Show attributes

command string Required

Value is isolate.

comment string

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.

risk_score integer 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

Minimum value is 0, maximum value is 100.

risk_score_mapping array[object] Required

Overrides generated alerts' risk_score with a value from the source event

Hide risk_score_mapping attributes Show risk_score_mapping attributes object

field string Required

Source event field used to override the default risk_score.

operator string Required

Value is equals.

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

Minimum value is 0, maximum value is 100.

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 string 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 are low, medium, high, or critical.

severity_mapping array[object] Required

Overrides generated alerts' severity with values from the source event

Hide severity_mapping attributes Show severity_mapping attributes object

field string Required

Source event field used to override the default severity.

operator string Required

Value is equals.

severity string 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 are low, medium, high, or critical.

value string Required

tags array[string] Required

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.

threat array[object] Required

Currently, only threats described using the MITRE ATT&CK™ framework are supported.

Hide threat attributes Show threat attributes object

framework string Required

Relevant attack framework

tactic object Required

Object containing information on the attack type

Hide tactic attributes Show tactic attributes object

id string Required

Tactic ID

name string Required

Tactic name

reference string Required

Tactic reference

technique array[object]

Array containing information on the attack techniques (optional)

Hide technique attributes Show technique attributes object

id string Required

Technique ID

name string Required

Technique name

reference string Required

Technique reference

subtechnique array[object]

Array containing more specific information on the attack technique.

Hide subtechnique attributes Show subtechnique attributes object

id string Required

Subtechnique ID

name string Required

Subtechnique name

reference string Required

Subtechnique reference

throttle string | null

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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 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.

It is not incremented on each update. Compare this to the revision field.

Minimum value is 1.

created_at string(date-time) Required

created_by string Required

execution_summary object

Summary of the last execution of a rule.

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

Hide execution_summary attribute Show execution_summary attribute object

last_execution object Required

Hide last_execution attributes Show last_execution attributes object

date string(date-time) Required

Date of the last execution

message string Required

metrics object Required

Hide metrics attributes Show metrics attributes object

execution_gap_duration_s integer

Duration in seconds of execution gap

Minimum value is 0.

frozen_indices_queried_count integer

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

Minimum value is 0.

gap_range object

Range of the execution gap

Hide gap_range attributes Show gap_range attributes object

gte string Required

Start date of the execution gap

lte string Required

End date of the execution gap

total_enrichment_duration_ms integer

Total time spent enriching documents during current rule execution cycle

Minimum value is 0.

total_indexing_duration_ms integer

Total time spent indexing documents during current rule execution cycle

Minimum value is 0.

total_search_duration_ms integer

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

Minimum value is 0.

status string Required

Status of the last execution

Values are going to run, running, partial failure, failed, or succeeded.

status_order integer Required

id string(uuid) Required

A dynamic unique identifier for the rule object. It is randomly generated when a rule is created and cannot be changed after that. It is always a UUID. It is unique within a given Kibana space. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have different object ids.

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

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.

Minimum value is 0.

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 object 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:
Security_Detections_API_ExternalRuleSource object Security_Detections_API_InternalRuleSource object

Type of rule source for externally sourced rules, i.e. rules that have an external source, such as the Elastic Prebuilt rules repo.

Hide attributes Show attributes

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

type string Required Discriminator

Value is external.

updated_at string(date-time) Required

updated_by string Required

saved_id string Required

Kibana saved search used by the rule to create alerts.

type string Required Discriminator

Rule type

Value is saved_query.

alert_suppression object

Defines alert suppression configuration.

Hide alert_suppression attributes Show alert_suppression attributes object

duration object

Hide duration attributes Show duration attributes object

unit string Required

Time unit

Values are s, m, or h.

value integer Required

Minimum value is 1.

group_by array[string] Required

At least 1 but not more than 3 elements.

missing_fields_strategy string

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 are doNotSuppress or suppress.

data_view_id string

filters array

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

query string

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.

language string Required

Values are kuery or lucene.
Hide attributes Show attributes

actions array[object] Required

Array defining the automated actions (notifications) taken when alerts are generated.

Hide actions attributes Show actions attributes object

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.

Additional properties are allowed.

frequency object

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

Hide frequency attributes Show frequency attributes object

notifyWhen string Required

Defines how often rules run actions.

Values are onActiveAlert, onThrottleInterval, or 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 string | null Required

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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.

Additional properties are allowed.

uuid string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

alias_purpose string

Values are savedObjectConversion or savedObjectImport.

alias_target_id string

author array[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 Required

The rule’s description.

Minimum length is 1.

enabled boolean Required

Determines whether the rule is enabled. Defaults to true.

exceptions_list array[object] Required

Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.

Hide exceptions_list attributes Show exceptions_list attributes object

id string(nonempty) Required

ID of the exception container

Minimum length is 1.

list_id string(nonempty) Required

List ID of the exception container

Minimum length is 1.

namespace_type string Required

Determines the exceptions validity in rule's Kibana space

Values are agnostic or single.

type string Required

The exception type

Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.

false_positives array[string] Required

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.

from string(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.

Hide investigation_fields attribute Show investigation_fields attribute object

field_names array[string(nonempty)] Required

A string that does not contain only whitespace characters

At least 1 element. Minimum length of each is 1.

license string

The rule's license.

max_signals integer Required

Maximum number of alerts the rule can create during a single run (the rule’s Max alerts per run advanced setting value).

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.

Minimum value is 1. Default value is 100.

meta object

Placeholder for metadata about the rule.

This field is overwritten when you save changes to the rule’s settings.

Additional properties are allowed.

name string Required

A human-readable name for the rule.

Minimum length is 1.

namespace string

Has no effect.

note string

Notes to help investigate alerts produced by the rule.

outcome string

Values are exactMatch, aliasMatch, or conflict.

output_index string Deprecated

(deprecated) Has no effect.

references array[string] Required

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.

related_integrations array[object] Required

Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:

package: name of the package (required, unique id)

version: version of the package (required, semver-compatible)

integration: name of the integration of this package (optional, id within the package)

There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.

Hide related_integrations attributes Show related_integrations attributes object

integration string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

package string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

version string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

required_fields array[object] Required

Elasticsearch fields and their types that need to be present for the rule to function.

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.

Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.

Hide required_fields attributes Show required_fields attributes object

name string(nonempty) Required

Name of an Elasticsearch field

Minimum length is 1.

type string(nonempty) Required

Type of the Elasticsearch field

Minimum length is 1.

response_actions array[object]

One of:
Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object

Hide attributes Show attributes

action_type_id string Required

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

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

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[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.

Hide attributes Show attributes

action_type_id string Required

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object

Hide attributes Show attributes

command string Required

Value is isolate.

comment string

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.

risk_score integer 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

Minimum value is 0, maximum value is 100.

risk_score_mapping array[object] Required

Overrides generated alerts' risk_score with a value from the source event

Hide risk_score_mapping attributes Show risk_score_mapping attributes object

field string Required

Source event field used to override the default risk_score.

operator string Required

Value is equals.

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

Minimum value is 0, maximum value is 100.

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 string 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 are low, medium, high, or critical.

severity_mapping array[object] Required

Overrides generated alerts' severity with values from the source event

Hide severity_mapping attributes Show severity_mapping attributes object

field string Required

Source event field used to override the default severity.

operator string Required

Value is equals.

severity string 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 are low, medium, high, or critical.

value string Required

tags array[string] Required

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.

threat array[object] Required

Currently, only threats described using the MITRE ATT&CK™ framework are supported.

Hide threat attributes Show threat attributes object

framework string Required

Relevant attack framework

tactic object Required

Object containing information on the attack type

Hide tactic attributes Show tactic attributes object

id string Required

Tactic ID

name string Required

Tactic name

reference string Required

Tactic reference

technique array[object]

Array containing information on the attack techniques (optional)

Hide technique attributes Show technique attributes object

id string Required

Technique ID

name string Required

Technique name

reference string Required

Technique reference

subtechnique array[object]

Array containing more specific information on the attack technique.

Hide subtechnique attributes Show subtechnique attributes object

id string Required

Subtechnique ID

name string Required

Subtechnique name

reference string Required

Subtechnique reference

throttle string | null

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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 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.

It is not incremented on each update. Compare this to the revision field.

Minimum value is 1.

created_at string(date-time) Required

created_by string Required

execution_summary object

Summary of the last execution of a rule.

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

Hide execution_summary attribute Show execution_summary attribute object

last_execution object Required

Hide last_execution attributes Show last_execution attributes object

date string(date-time) Required

Date of the last execution

message string Required

metrics object Required

Hide metrics attributes Show metrics attributes object

execution_gap_duration_s integer

Duration in seconds of execution gap

Minimum value is 0.

frozen_indices_queried_count integer

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

Minimum value is 0.

gap_range object

Range of the execution gap

Hide gap_range attributes Show gap_range attributes object

gte string Required

Start date of the execution gap

lte string Required

End date of the execution gap

total_enrichment_duration_ms integer

Total time spent enriching documents during current rule execution cycle

Minimum value is 0.

total_indexing_duration_ms integer

Total time spent indexing documents during current rule execution cycle

Minimum value is 0.

total_search_duration_ms integer

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

Minimum value is 0.

status string Required

Status of the last execution

Values are going to run, running, partial failure, failed, or succeeded.

status_order integer Required

id string(uuid) Required

A dynamic unique identifier for the rule object. It is randomly generated when a rule is created and cannot be changed after that. It is always a UUID. It is unique within a given Kibana space. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have different object ids.

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

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.

Minimum value is 0.

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 object 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:
Security_Detections_API_ExternalRuleSource object Security_Detections_API_InternalRuleSource object

Type of rule source for externally sourced rules, i.e. rules that have an external source, such as the Elastic Prebuilt rules repo.

Hide attributes Show attributes

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

type string Required Discriminator

Value is external.

updated_at string(date-time) Required

updated_by string Required

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.

threshold object Required

Hide threshold attributes Show threshold attributes object

cardinality array[object]

The field on which the cardinality is applied.

Hide cardinality attributes Show cardinality attributes object

field string Required

The field on which to calculate and compare the cardinality.

value integer Required

The threshold value from which an alert is generated based on unique number of values of cardinality.field.

Minimum value is 0.

field string | array[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.

One of:
string-1 string array-2 array[string]

value integer Required

The threshold value from which an alert is generated.

Minimum value is 1.

type string Required Discriminator

Rule type

Value is threshold.

alert_suppression object

Defines alert suppression configuration.

Hide alert_suppression attribute Show alert_suppression attribute object

duration object Required

Hide duration attributes Show duration attributes object

unit string Required

Time unit

Values are s, m, or h.

value integer Required

Minimum value is 1.

data_view_id string

filters array

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

saved_id string

Kibana saved search used by the rule to create alerts.

language string Required

Values are kuery or lucene.
Hide attributes Show attributes

actions array[object] Required

Array defining the automated actions (notifications) taken when alerts are generated.

Hide actions attributes Show actions attributes object

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.

Additional properties are allowed.

frequency object

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

Hide frequency attributes Show frequency attributes object

notifyWhen string Required

Defines how often rules run actions.

Values are onActiveAlert, onThrottleInterval, or 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 string | null Required

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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.

Additional properties are allowed.

uuid string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

alias_purpose string

Values are savedObjectConversion or savedObjectImport.

alias_target_id string

author array[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 Required

The rule’s description.

Minimum length is 1.

enabled boolean Required

Determines whether the rule is enabled. Defaults to true.

exceptions_list array[object] Required

Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.

Hide exceptions_list attributes Show exceptions_list attributes object

id string(nonempty) Required

ID of the exception container

Minimum length is 1.

list_id string(nonempty) Required

List ID of the exception container

Minimum length is 1.

namespace_type string Required

Determines the exceptions validity in rule's Kibana space

Values are agnostic or single.

type string Required

The exception type

Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.

false_positives array[string] Required

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.

from string(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.

Hide investigation_fields attribute Show investigation_fields attribute object

field_names array[string(nonempty)] Required

A string that does not contain only whitespace characters

At least 1 element. Minimum length of each is 1.

license string

The rule's license.

max_signals integer Required

Maximum number of alerts the rule can create during a single run (the rule’s Max alerts per run advanced setting value).

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.

Minimum value is 1. Default value is 100.

meta object

Placeholder for metadata about the rule.

This field is overwritten when you save changes to the rule’s settings.

Additional properties are allowed.

name string Required

A human-readable name for the rule.

Minimum length is 1.

namespace string

Has no effect.

note string

Notes to help investigate alerts produced by the rule.

outcome string

Values are exactMatch, aliasMatch, or conflict.

output_index string Deprecated

(deprecated) Has no effect.

references array[string] Required

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.

related_integrations array[object] Required

Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:

package: name of the package (required, unique id)

version: version of the package (required, semver-compatible)

integration: name of the integration of this package (optional, id within the package)

There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.

Hide related_integrations attributes Show related_integrations attributes object

integration string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

package string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

version string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

required_fields array[object] Required

Elasticsearch fields and their types that need to be present for the rule to function.

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.

Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.

Hide required_fields attributes Show required_fields attributes object

name string(nonempty) Required

Name of an Elasticsearch field

Minimum length is 1.

type string(nonempty) Required

Type of the Elasticsearch field

Minimum length is 1.

response_actions array[object]

One of:
Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object

Hide attributes Show attributes

action_type_id string Required

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

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

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[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.

Hide attributes Show attributes

action_type_id string Required

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object

Hide attributes Show attributes

command string Required

Value is isolate.

comment string

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.

risk_score integer 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

Minimum value is 0, maximum value is 100.

risk_score_mapping array[object] Required

Overrides generated alerts' risk_score with a value from the source event

Hide risk_score_mapping attributes Show risk_score_mapping attributes object

field string Required

Source event field used to override the default risk_score.

operator string Required

Value is equals.

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

Minimum value is 0, maximum value is 100.

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 string 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 are low, medium, high, or critical.

severity_mapping array[object] Required

Overrides generated alerts' severity with values from the source event

Hide severity_mapping attributes Show severity_mapping attributes object

field string Required

Source event field used to override the default severity.

operator string Required

Value is equals.

severity string 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 are low, medium, high, or critical.

value string Required

tags array[string] Required

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.

threat array[object] Required

Currently, only threats described using the MITRE ATT&CK™ framework are supported.

Hide threat attributes Show threat attributes object

framework string Required

Relevant attack framework

tactic object Required

Object containing information on the attack type

Hide tactic attributes Show tactic attributes object

id string Required

Tactic ID

name string Required

Tactic name

reference string Required

Tactic reference

technique array[object]

Array containing information on the attack techniques (optional)

Hide technique attributes Show technique attributes object

id string Required

Technique ID

name string Required

Technique name

reference string Required

Technique reference

subtechnique array[object]

Array containing more specific information on the attack technique.

Hide subtechnique attributes Show subtechnique attributes object

id string Required

Subtechnique ID

name string Required

Subtechnique name

reference string Required

Subtechnique reference

throttle string | null

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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 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.

It is not incremented on each update. Compare this to the revision field.

Minimum value is 1.

created_at string(date-time) Required

created_by string Required

execution_summary object

Summary of the last execution of a rule.

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

Hide execution_summary attribute Show execution_summary attribute object

last_execution object Required

Hide last_execution attributes Show last_execution attributes object

date string(date-time) Required

Date of the last execution

message string Required

metrics object Required

Hide metrics attributes Show metrics attributes object

execution_gap_duration_s integer

Duration in seconds of execution gap

Minimum value is 0.

frozen_indices_queried_count integer

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

Minimum value is 0.

gap_range object

Range of the execution gap

Hide gap_range attributes Show gap_range attributes object

gte string Required

Start date of the execution gap

lte string Required

End date of the execution gap

total_enrichment_duration_ms integer

Total time spent enriching documents during current rule execution cycle

Minimum value is 0.

total_indexing_duration_ms integer

Total time spent indexing documents during current rule execution cycle

Minimum value is 0.

total_search_duration_ms integer

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

Minimum value is 0.

status string Required

Status of the last execution

Values are going to run, running, partial failure, failed, or succeeded.

status_order integer Required

id string(uuid) Required

A dynamic unique identifier for the rule object. It is randomly generated when a rule is created and cannot be changed after that. It is always a UUID. It is unique within a given Kibana space. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have different object ids.

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

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.

Minimum value is 0.

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 object 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:
Security_Detections_API_ExternalRuleSource object Security_Detections_API_InternalRuleSource object

Type of rule source for externally sourced rules, i.e. rules that have an external source, such as the Elastic Prebuilt rules repo.

Hide attributes Show attributes

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

type string Required Discriminator

Value is external.

updated_at string(date-time) Required

updated_by string Required

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.

threat_index array[string] Required

Elasticsearch indices used to check which field values generate alerts.

threat_mapping array[object] Required

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 Example of Threat Match rule which uses both and and or logic.

At least 1 element.

Hide threat_mapping attribute Show threat_mapping attribute object

entries array[object] Required

Hide entries attributes Show entries attributes object

field string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

type string Required

Value is mapping.

value string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

threat_query string Required

Query used to determine which fields in the Elasticsearch index are used for generating alerts.

type string Required Discriminator

Rule type

Value is threat_match.

alert_suppression object

Defines alert suppression configuration.

Hide alert_suppression attributes Show alert_suppression attributes object

duration object

Hide duration attributes Show duration attributes object

unit string Required

Time unit

Values are s, m, or h.

value integer Required

Minimum value is 1.

group_by array[string] Required

At least 1 but not more than 3 elements.

missing_fields_strategy string

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 are doNotSuppress or suppress.

concurrent_searches integer

Minimum value is 1.

data_view_id string

filters array

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

items_per_search integer

Minimum value is 1.

saved_id string

Kibana saved search used by the rule to create alerts.

threat_filters array

Query and filter context array used to filter documents from the Elasticsearch index containing the threat values

threat_indicator_path string

Defines the path to the threat indicator in the indicator documents (optional)

threat_language string

Values are kuery or lucene.

language string Required

Values are kuery or lucene.
Hide attributes Show attributes

actions array[object] Required

Array defining the automated actions (notifications) taken when alerts are generated.

Hide actions attributes Show actions attributes object

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.

Additional properties are allowed.

frequency object

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

Hide frequency attributes Show frequency attributes object

notifyWhen string Required

Defines how often rules run actions.

Values are onActiveAlert, onThrottleInterval, or 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 string | null Required

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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.

Additional properties are allowed.

uuid string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

alias_purpose string

Values are savedObjectConversion or savedObjectImport.

alias_target_id string

author array[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 Required

The rule’s description.

Minimum length is 1.

enabled boolean Required

Determines whether the rule is enabled. Defaults to true.

exceptions_list array[object] Required

Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.

Hide exceptions_list attributes Show exceptions_list attributes object

id string(nonempty) Required

ID of the exception container

Minimum length is 1.

list_id string(nonempty) Required

List ID of the exception container

Minimum length is 1.

namespace_type string Required

Determines the exceptions validity in rule's Kibana space

Values are agnostic or single.

type string Required

The exception type

Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.

false_positives array[string] Required

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.

from string(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.

Hide investigation_fields attribute Show investigation_fields attribute object

field_names array[string(nonempty)] Required

A string that does not contain only whitespace characters

At least 1 element. Minimum length of each is 1.

license string

The rule's license.

max_signals integer Required

Maximum number of alerts the rule can create during a single run (the rule’s Max alerts per run advanced setting value).

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.

Minimum value is 1. Default value is 100.

meta object

Placeholder for metadata about the rule.

This field is overwritten when you save changes to the rule’s settings.

Additional properties are allowed.

name string Required

A human-readable name for the rule.

Minimum length is 1.

namespace string

Has no effect.

note string

Notes to help investigate alerts produced by the rule.

outcome string

Values are exactMatch, aliasMatch, or conflict.

output_index string Deprecated

(deprecated) Has no effect.

references array[string] Required

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.

related_integrations array[object] Required

Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:

package: name of the package (required, unique id)

version: version of the package (required, semver-compatible)

integration: name of the integration of this package (optional, id within the package)

There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.

Hide related_integrations attributes Show related_integrations attributes object

integration string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

package string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

version string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

required_fields array[object] Required

Elasticsearch fields and their types that need to be present for the rule to function.

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.

Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.

Hide required_fields attributes Show required_fields attributes object

name string(nonempty) Required

Name of an Elasticsearch field

Minimum length is 1.

type string(nonempty) Required

Type of the Elasticsearch field

Minimum length is 1.

response_actions array[object]

One of:
Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object

Hide attributes Show attributes

action_type_id string Required

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

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

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[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.

Hide attributes Show attributes

action_type_id string Required

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object

Hide attributes Show attributes

command string Required

Value is isolate.

comment string

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.

risk_score integer 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

Minimum value is 0, maximum value is 100.

risk_score_mapping array[object] Required

Overrides generated alerts' risk_score with a value from the source event

Hide risk_score_mapping attributes Show risk_score_mapping attributes object

field string Required

Source event field used to override the default risk_score.

operator string Required

Value is equals.

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

Minimum value is 0, maximum value is 100.

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 string 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 are low, medium, high, or critical.

severity_mapping array[object] Required

Overrides generated alerts' severity with values from the source event

Hide severity_mapping attributes Show severity_mapping attributes object

field string Required

Source event field used to override the default severity.

operator string Required

Value is equals.

severity string 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 are low, medium, high, or critical.

value string Required

tags array[string] Required

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.

threat array[object] Required

Currently, only threats described using the MITRE ATT&CK™ framework are supported.

Hide threat attributes Show threat attributes object

framework string Required

Relevant attack framework

tactic object Required

Object containing information on the attack type

Hide tactic attributes Show tactic attributes object

id string Required

Tactic ID

name string Required

Tactic name

reference string Required

Tactic reference

technique array[object]

Array containing information on the attack techniques (optional)

Hide technique attributes Show technique attributes object

id string Required

Technique ID

name string Required

Technique name

reference string Required

Technique reference

subtechnique array[object]

Array containing more specific information on the attack technique.

Hide subtechnique attributes Show subtechnique attributes object

id string Required

Subtechnique ID

name string Required

Subtechnique name

reference string Required

Subtechnique reference

throttle string | null

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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 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.

It is not incremented on each update. Compare this to the revision field.

Minimum value is 1.

created_at string(date-time) Required

created_by string Required

execution_summary object

Summary of the last execution of a rule.

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

Hide execution_summary attribute Show execution_summary attribute object

last_execution object Required

Hide last_execution attributes Show last_execution attributes object

date string(date-time) Required

Date of the last execution

message string Required

metrics object Required

Hide metrics attributes Show metrics attributes object

execution_gap_duration_s integer

Duration in seconds of execution gap

Minimum value is 0.

frozen_indices_queried_count integer

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

Minimum value is 0.

gap_range object

Range of the execution gap

Hide gap_range attributes Show gap_range attributes object

gte string Required

Start date of the execution gap

lte string Required

End date of the execution gap

total_enrichment_duration_ms integer

Total time spent enriching documents during current rule execution cycle

Minimum value is 0.

total_indexing_duration_ms integer

Total time spent indexing documents during current rule execution cycle

Minimum value is 0.

total_search_duration_ms integer

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

Minimum value is 0.

status string Required

Status of the last execution

Values are going to run, running, partial failure, failed, or succeeded.

status_order integer Required

id string(uuid) Required

A dynamic unique identifier for the rule object. It is randomly generated when a rule is created and cannot be changed after that. It is always a UUID. It is unique within a given Kibana space. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have different object ids.

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

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.

Minimum value is 0.

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 object 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:
Security_Detections_API_ExternalRuleSource object Security_Detections_API_InternalRuleSource object

Type of rule source for externally sourced rules, i.e. rules that have an external source, such as the Elastic Prebuilt rules repo.

Hide attributes Show attributes

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

type string Required Discriminator

Value is external.

updated_at string(date-time) Required

updated_by string Required

anomaly_threshold integer Required

Anomaly score threshold above which the rule creates an alert. Valid values are from 0 to 100.

Minimum value is 0.

machine_learning_job_id string | array[string] Required

Machine learning job ID(s) the rule monitors for anomaly scores.

One of:
string-1 string array-2 array[string]

type string Required Discriminator

Rule type

Value is machine_learning.

alert_suppression object

Defines alert suppression configuration.

Hide alert_suppression attributes Show alert_suppression attributes object

duration object

Hide duration attributes Show duration attributes object

unit string Required

Time unit

Values are s, m, or h.

value integer Required

Minimum value is 1.

group_by array[string] Required

At least 1 but not more than 3 elements.

missing_fields_strategy string

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 are doNotSuppress or suppress.
Hide attributes Show attributes

actions array[object] Required

Array defining the automated actions (notifications) taken when alerts are generated.

Hide actions attributes Show actions attributes object

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.

Additional properties are allowed.

frequency object

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

Hide frequency attributes Show frequency attributes object

notifyWhen string Required

Defines how often rules run actions.

Values are onActiveAlert, onThrottleInterval, or 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 string | null Required

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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.

Additional properties are allowed.

uuid string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

alias_purpose string

Values are savedObjectConversion or savedObjectImport.

alias_target_id string

author array[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 Required

The rule’s description.

Minimum length is 1.

enabled boolean Required

Determines whether the rule is enabled. Defaults to true.

exceptions_list array[object] Required

Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.

Hide exceptions_list attributes Show exceptions_list attributes object

id string(nonempty) Required

ID of the exception container

Minimum length is 1.

list_id string(nonempty) Required

List ID of the exception container

Minimum length is 1.

namespace_type string Required

Determines the exceptions validity in rule's Kibana space

Values are agnostic or single.

type string Required

The exception type

Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.

false_positives array[string] Required

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.

from string(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.

Hide investigation_fields attribute Show investigation_fields attribute object

field_names array[string(nonempty)] Required

A string that does not contain only whitespace characters

At least 1 element. Minimum length of each is 1.

license string

The rule's license.

max_signals integer Required

Maximum number of alerts the rule can create during a single run (the rule’s Max alerts per run advanced setting value).

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.

Minimum value is 1. Default value is 100.

meta object

Placeholder for metadata about the rule.

This field is overwritten when you save changes to the rule’s settings.

Additional properties are allowed.

name string Required

A human-readable name for the rule.

Minimum length is 1.

namespace string

Has no effect.

note string

Notes to help investigate alerts produced by the rule.

outcome string

Values are exactMatch, aliasMatch, or conflict.

output_index string Deprecated

(deprecated) Has no effect.

references array[string] Required

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.

related_integrations array[object] Required

Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:

package: name of the package (required, unique id)

version: version of the package (required, semver-compatible)

integration: name of the integration of this package (optional, id within the package)

There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.

Hide related_integrations attributes Show related_integrations attributes object

integration string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

package string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

version string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

required_fields array[object] Required

Elasticsearch fields and their types that need to be present for the rule to function.

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.

Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.

Hide required_fields attributes Show required_fields attributes object

name string(nonempty) Required

Name of an Elasticsearch field

Minimum length is 1.

type string(nonempty) Required

Type of the Elasticsearch field

Minimum length is 1.

response_actions array[object]

One of:
Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object

Hide attributes Show attributes

action_type_id string Required

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

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

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[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.

Hide attributes Show attributes

action_type_id string Required

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object

Hide attributes Show attributes

command string Required

Value is isolate.

comment string

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.

risk_score integer 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

Minimum value is 0, maximum value is 100.

risk_score_mapping array[object] Required

Overrides generated alerts' risk_score with a value from the source event

Hide risk_score_mapping attributes Show risk_score_mapping attributes object

field string Required

Source event field used to override the default risk_score.

operator string Required

Value is equals.

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

Minimum value is 0, maximum value is 100.

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 string 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 are low, medium, high, or critical.

severity_mapping array[object] Required

Overrides generated alerts' severity with values from the source event

Hide severity_mapping attributes Show severity_mapping attributes object

field string Required

Source event field used to override the default severity.

operator string Required

Value is equals.

severity string 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 are low, medium, high, or critical.

value string Required

tags array[string] Required

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.

threat array[object] Required

Currently, only threats described using the MITRE ATT&CK™ framework are supported.

Hide threat attributes Show threat attributes object

framework string Required

Relevant attack framework

tactic object Required

Object containing information on the attack type

Hide tactic attributes Show tactic attributes object

id string Required

Tactic ID

name string Required

Tactic name

reference string Required

Tactic reference

technique array[object]

Array containing information on the attack techniques (optional)

Hide technique attributes Show technique attributes object

id string Required

Technique ID

name string Required

Technique name

reference string Required

Technique reference

subtechnique array[object]

Array containing more specific information on the attack technique.

Hide subtechnique attributes Show subtechnique attributes object

id string Required

Subtechnique ID

name string Required

Subtechnique name

reference string Required

Subtechnique reference

throttle string | null

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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 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.

It is not incremented on each update. Compare this to the revision field.

Minimum value is 1.

created_at string(date-time) Required

created_by string Required

execution_summary object

Summary of the last execution of a rule.

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

Hide execution_summary attribute Show execution_summary attribute object

last_execution object Required

Hide last_execution attributes Show last_execution attributes object

date string(date-time) Required

Date of the last execution

message string Required

metrics object Required

Hide metrics attributes Show metrics attributes object

execution_gap_duration_s integer

Duration in seconds of execution gap

Minimum value is 0.

frozen_indices_queried_count integer

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

Minimum value is 0.

gap_range object

Range of the execution gap

Hide gap_range attributes Show gap_range attributes object

gte string Required

Start date of the execution gap

lte string Required

End date of the execution gap

total_enrichment_duration_ms integer

Total time spent enriching documents during current rule execution cycle

Minimum value is 0.

total_indexing_duration_ms integer

Total time spent indexing documents during current rule execution cycle

Minimum value is 0.

total_search_duration_ms integer

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

Minimum value is 0.

status string Required

Status of the last execution

Values are going to run, running, partial failure, failed, or succeeded.

status_order integer Required

id string(uuid) Required

A dynamic unique identifier for the rule object. It is randomly generated when a rule is created and cannot be changed after that. It is always a UUID. It is unique within a given Kibana space. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have different object ids.

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

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.

Minimum value is 0.

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 object 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:
Security_Detections_API_ExternalRuleSource object Security_Detections_API_InternalRuleSource object

Type of rule source for externally sourced rules, i.e. rules that have an external source, such as the Elastic Prebuilt rules repo.

Hide attributes Show attributes

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

type string Required Discriminator

Value is external.

updated_at string(date-time) Required

updated_by string Required

history_window_start string(nonempty) Required

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.

Minimum length is 1.

new_terms_fields array[string] Required

Fields to monitor for new values.

At least 1 but not more than 3 elements.

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.

type string Required Discriminator

Rule type

Value is new_terms.

alert_suppression object

Defines alert suppression configuration.

Hide alert_suppression attributes Show alert_suppression attributes object

duration object

Hide duration attributes Show duration attributes object

unit string Required

Time unit

Values are s, m, or h.

value integer Required

Minimum value is 1.

group_by array[string] Required

At least 1 but not more than 3 elements.

missing_fields_strategy string

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 are doNotSuppress or suppress.

data_view_id string

filters array

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

language string Required

Values are kuery or lucene.
Hide attributes Show attributes

actions array[object] Required

Array defining the automated actions (notifications) taken when alerts are generated.

Hide actions attributes Show actions attributes object

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.

Additional properties are allowed.

frequency object

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

Hide frequency attributes Show frequency attributes object

notifyWhen string Required

Defines how often rules run actions.

Values are onActiveAlert, onThrottleInterval, or 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 string | null Required

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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.

Additional properties are allowed.

uuid string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

alias_purpose string

Values are savedObjectConversion or savedObjectImport.

alias_target_id string

author array[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 Required

The rule’s description.

Minimum length is 1.

enabled boolean Required

Determines whether the rule is enabled. Defaults to true.

exceptions_list array[object] Required

Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.

Hide exceptions_list attributes Show exceptions_list attributes object

id string(nonempty) Required

ID of the exception container

Minimum length is 1.

list_id string(nonempty) Required

List ID of the exception container

Minimum length is 1.

namespace_type string Required

Determines the exceptions validity in rule's Kibana space

Values are agnostic or single.

type string Required

The exception type

Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.

false_positives array[string] Required

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.

from string(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.

Hide investigation_fields attribute Show investigation_fields attribute object

field_names array[string(nonempty)] Required

A string that does not contain only whitespace characters

At least 1 element. Minimum length of each is 1.

license string

The rule's license.

max_signals integer Required

Maximum number of alerts the rule can create during a single run (the rule’s Max alerts per run advanced setting value).

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.

Minimum value is 1. Default value is 100.

meta object

Placeholder for metadata about the rule.

This field is overwritten when you save changes to the rule’s settings.

Additional properties are allowed.

name string Required

A human-readable name for the rule.

Minimum length is 1.

namespace string

Has no effect.

note string

Notes to help investigate alerts produced by the rule.

outcome string

Values are exactMatch, aliasMatch, or conflict.

output_index string Deprecated

(deprecated) Has no effect.

references array[string] Required

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.

related_integrations array[object] Required

Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:

package: name of the package (required, unique id)

version: version of the package (required, semver-compatible)

integration: name of the integration of this package (optional, id within the package)

There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.

Hide related_integrations attributes Show related_integrations attributes object

integration string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

package string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

version string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

required_fields array[object] Required

Elasticsearch fields and their types that need to be present for the rule to function.

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.

Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.

Hide required_fields attributes Show required_fields attributes object

name string(nonempty) Required

Name of an Elasticsearch field

Minimum length is 1.

type string(nonempty) Required

Type of the Elasticsearch field

Minimum length is 1.

response_actions array[object]

One of:
Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object

Hide attributes Show attributes

action_type_id string Required

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

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

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[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.

Hide attributes Show attributes

action_type_id string Required

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object

Hide attributes Show attributes

command string Required

Value is isolate.

comment string

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.

risk_score integer 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

Minimum value is 0, maximum value is 100.

risk_score_mapping array[object] Required

Overrides generated alerts' risk_score with a value from the source event

Hide risk_score_mapping attributes Show risk_score_mapping attributes object

field string Required

Source event field used to override the default risk_score.

operator string Required

Value is equals.

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

Minimum value is 0, maximum value is 100.

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 string 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 are low, medium, high, or critical.

severity_mapping array[object] Required

Overrides generated alerts' severity with values from the source event

Hide severity_mapping attributes Show severity_mapping attributes object

field string Required

Source event field used to override the default severity.

operator string Required

Value is equals.

severity string 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 are low, medium, high, or critical.

value string Required

tags array[string] Required

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.

threat array[object] Required

Currently, only threats described using the MITRE ATT&CK™ framework are supported.

Hide threat attributes Show threat attributes object

framework string Required

Relevant attack framework

tactic object Required

Object containing information on the attack type

Hide tactic attributes Show tactic attributes object

id string Required

Tactic ID

name string Required

Tactic name

reference string Required

Tactic reference

technique array[object]

Array containing information on the attack techniques (optional)

Hide technique attributes Show technique attributes object

id string Required

Technique ID

name string Required

Technique name

reference string Required

Technique reference

subtechnique array[object]

Array containing more specific information on the attack technique.

Hide subtechnique attributes Show subtechnique attributes object

id string Required

Subtechnique ID

name string Required

Subtechnique name

reference string Required

Subtechnique reference

throttle string | null

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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 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.

It is not incremented on each update. Compare this to the revision field.

Minimum value is 1.

created_at string(date-time) Required

created_by string Required

execution_summary object

Summary of the last execution of a rule.

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

Hide execution_summary attribute Show execution_summary attribute object

last_execution object Required

Hide last_execution attributes Show last_execution attributes object

date string(date-time) Required

Date of the last execution

message string Required

metrics object Required

Hide metrics attributes Show metrics attributes object

execution_gap_duration_s integer

Duration in seconds of execution gap

Minimum value is 0.

frozen_indices_queried_count integer

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

Minimum value is 0.

gap_range object

Range of the execution gap

Hide gap_range attributes Show gap_range attributes object

gte string Required

Start date of the execution gap

lte string Required

End date of the execution gap

total_enrichment_duration_ms integer

Total time spent enriching documents during current rule execution cycle

Minimum value is 0.

total_indexing_duration_ms integer

Total time spent indexing documents during current rule execution cycle

Minimum value is 0.

total_search_duration_ms integer

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

Minimum value is 0.

status string Required

Status of the last execution

Values are going to run, running, partial failure, failed, or succeeded.

status_order integer Required

id string(uuid) Required

A dynamic unique identifier for the rule object. It is randomly generated when a rule is created and cannot be changed after that. It is always a UUID. It is unique within a given Kibana space. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have different object ids.

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

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.

Minimum value is 0.

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 object 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:
Security_Detections_API_ExternalRuleSource object Security_Detections_API_InternalRuleSource object

Type of rule source for externally sourced rules, i.e. rules that have an external source, such as the Elastic Prebuilt rules repo.

Hide attributes Show attributes

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

type string Required Discriminator

Value is external.

updated_at string(date-time) Required

updated_by string Required

alert_suppression object

Defines alert suppression configuration.

Hide alert_suppression attributes Show alert_suppression attributes object

duration object

Hide duration attributes Show duration attributes object

unit string Required

Time unit

Values are s, m, or h.

value integer Required

Minimum value is 1.

group_by array[string] Required

At least 1 but not more than 3 elements.

missing_fields_strategy string

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 are doNotSuppress or suppress.

language string Required

Value is esql.

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.

type string Required Discriminator

Rule type

Value is esql.

PATCH /api/detection_engine/rules

curl \
 --request PATCH 'https://<KIBANA_URL>/api/detection_engine/rules' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"id":"14b7b513-3d8d-4b22-b7da-a7ae632f7e76","name":"New name"}'

Request examples

{
  "id": "14b7b513-3d8d-4b22-b7da-a7ae632f7e76",
  "name": "New name"
}

{
  "threat": [
    {
      "tactic": {
        "id": "TA0001",
        "name": "Initial Access",
        "reference": "https://attack.mitre.org/tactics/TA0001"
      },
      "framework": "MITRE ATT&CK",
      "technique": [
        {
          "id": "T1193",
          "name": "Spearphishing Attachment",
          "reference": "https://attack.mitre.org/techniques/T1193"
        }
      ]
    }
  ],
  "rule_id": "process_started_by_ms_office_program_possible_payload"
}

{
  "id": "005d2c4f-51ca-493d-a2bd-20ef076339b1",
  "query": "agent.version : * and agent.id : \"243d9b4f-ca01-4311-8e5c-9abbee91afd8\"",
  "threshold": {
    "field": [],
    "value": 600,
    "cardinality": []
  }
}

{
  "id": "569aac91-40dc-4807-a8ae-a2c8698089c4",
  "new_terms_fields": [
    "Endpoint.policy.applied.artifacts.global.identifiers.name"
  ],
  "history_window_start": "now-3d"
}

{
  "id": "0b15e8a2-49b6-47e0-a8e6-d63a6cc335bd",
  "query": "FROM logs-abc*\n| STATS count = COUNT(*), min_timestamp = MIN(@timestamp)\n| EVAL event_rate = count / DATE_DIFF(\"seconds\", min_timestamp, NOW()) \n| KEEP event_rate\n"
}

{
  "id": "462f1986-10fe-40a3-a22c-2b1c9c4c48fd",
  "threat_query": "@timestamp >= \"now-30d/d\" and event.module:(threatintel or ti_*) and threat.indicator.ip:* and not labels.is_ioc_transform_source:\"false\""
}

{
  "id": "60b13926-289b-41b1-a537-197ef1fa5059",
  "anomaly_threshold": 50,
  "machine_learning_job_id": [
    "auth_high_count_logon_events"
  ]
}

Response examples (200)

{
  "id": "6541b99a-dee9-4f6d-a86d-dbd1869d73b1",
  "to": "now",
  "from": "now-70m",
  "name": "Updated Rule Name",
  "tags": [
    "child process",
    "ms office"
  ],
  "type": "query",
  "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",
  "setup": "",
  "threat": [],
  "actions": [],
  "enabled": false,
  "filters": [
    {
      "query": null
    }
  ],
  "rule_id": "process_started_by_ms_office_program",
  "version": 2,
  "interval": "1h",
  "language": "kuery",
  "severity": "low",
  "immutable": false,
  "created_at": "2020-04-07T14:51:09.755Z",
  "created_by": "elastic",
  "references": [],
  "risk_score": 50,
  "updated_at": "2020-04-07T14:51:09.970Z",
  "updated_by": "elastic",
  "description": "Updated description for the rule.",
  "max_signals": 100,
  "false_positives": [],
  "required_fields": [
    {
      "name": "process.parent.name"
    }
  ],
  "related_integrations": [
    {
      "package": "o365"
    }
  ]
}

Apply a bulk action to detection rules

POST /api/detection_engine/rules/_bulk_action

Apply a bulk action, such as bulk edit, duplicate, or delete, to multiple detection rules. The bulk action is applied to all rules that match the query or to the rules listed by their IDs.

The edit action allows you to add, delete, or set tags, index patterns, investigation fields, rule actions and schedules for multiple rules at once. The edit action is idempotent, meaning that if you add a tag to a rule that already has that tag, no changes are made. The same is true for other edit actions, for example removing an index pattern that is not specified in a rule will not result in any changes. The only exception is the add_rule_actions and set_rule_actions action, which is non-idempotent. This means that if you add or set a rule action to a rule that already has that action, a new action is created with a new unique ID.

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.

Query parameters

dry_run boolean

Enables dry run mode for the request call.

Enable dry run mode to verify that bulk actions can be applied to specified rules. Certain rules, such as prebuilt Elastic rules on a Basic subscription, can’t be edited and will return errors in the request response. Error details will contain an explanation, the rule name and/or ID, and additional troubleshooting information.

To enable dry run mode on a request, add the query parameter dry_run=true to the end of the request URL. Rules specified in the request will be temporarily updated. These updates won’t be written to Elasticsearch.

Dry run mode is not supported for the export bulk action. A 400 error will be returned in the request response.

application/json

Body object

action string Required

Value is delete.
ids array[string]

Array of rule IDs. Array of rule IDs to which a bulk action will be applied. Only valid when query property is undefined.

At least 1 element.
query string

Query to filter rules.

action string Required

Value is disable.
ids array[string]

Array of rule IDs. Array of rule IDs to which a bulk action will be applied. Only valid when query property is undefined.

At least 1 element.
query string

Query to filter rules.

action string Required

Value is enable.
ids array[string]

Array of rule IDs. Array of rule IDs to which a bulk action will be applied. Only valid when query property is undefined.

At least 1 element.
query string

Query to filter rules.

action string Required

Value is export.
ids array[string]

Array of rule IDs. Array of rule IDs to which a bulk action will be applied. Only valid when query property is undefined.

At least 1 element.
query string

Query to filter rules.

action string Required

Value is duplicate.
duplicate object

Duplicate object that describes applying an update action.
Hide duplicate attributes Show duplicate attributes object
- include_exceptions boolean Required
  
  Whether to copy exceptions from the original rule
- include_expired_exceptions boolean Required
  
  Whether to copy expired exceptions from the original rule
ids array[string]

Array of rule IDs. Array of rule IDs to which a bulk action will be applied. Only valid when query property is undefined.

At least 1 element.
query string

Query to filter rules.

action string Required

Value is run.
ids array[string]

Array of rule IDs. Array of rule IDs to which a bulk action will be applied. Only valid when query property is undefined.

At least 1 element.
query string

Query to filter rules.
run object Required

Object that describes applying a manual rule run action.
Hide run attributes Show run attributes object
- end_date string Required
  
  End date of the manual rule run
- start_date string Required
  
  Start date of the manual rule run

action string Required

Value is edit.
edit array[object] Required

Array of objects containing the edit operations

At least 1 element.
Any of:
Security_Detections_API_BulkActionEditPayloadTags object Security_Detections_API_BulkActionEditPayloadIndexPatterns object Security_Detections_API_BulkActionEditPayloadInvestigationFields object Security_Detections_API_BulkActionEditPayloadTimeline object Security_Detections_API_BulkActionEditPayloadRuleActions object Security_Detections_API_BulkActionEditPayloadSchedule object
Edits tags of rules.

add_tags adds tags to rules. If a tag already exists for a rule, no changes are made.

delete_tags removes tags from rules. If a tag does not exist for a rule, no changes are made.

set_tags sets tags for rules, overwriting any existing tags. If the set of tags is the same as the existing tags, no changes are made.
Hide attributes Show attributes

type string Required

Values are add_tags, delete_tags, or set_tags.

value array[string] Required

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.
Edits index patterns of rulesClient.

add_index_patterns adds index patterns to rules. If an index pattern already exists for a rule, no changes are made.

delete_index_patterns removes index patterns from rules. If an index pattern does not exist for a rule, no changes are made.

set_index_patterns sets index patterns for rules, overwriting any existing index patterns. If the set of index patterns is the same as the existing index patterns, no changes are made.
Hide attributes Show attributes

overwrite_data_views boolean

Resets the data view for the rule.

type string Required

Values are add_index_patterns, delete_index_patterns, or set_index_patterns.

value array[string] Required

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.
Edits investigation fields of rules.

add_investigation_fields adds investigation fields to rules. If an investigation field already exists for a rule, no changes are made.

delete_investigation_fields removes investigation fields from rules. If an investigation field does not exist for a rule, no changes are made.

set_investigation_fields sets investigation fields for rules. If the set of investigation fields is the same as the existing investigation fields, no changes are made.
Hide attributes Show attributes

type string Required

Values are add_investigation_fields, delete_investigation_fields, or set_investigation_fields.

value object Required

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.

Hide value attribute Show value attribute object

field_names array[string(nonempty)] Required

A string that does not contain only whitespace characters

At least 1 element. Minimum length of each is 1.
Edits timeline of rules.

set_timeline sets a timeline for rules. If the same timeline already exists for a rule, no changes are made.
Hide attributes Show attributes

type string Required

Value is set_timeline.

value object Required

Hide value attributes Show value attributes object

timeline_id string Required

Timeline template ID

timeline_title string Required

Timeline template title
Edits rule actions of rules.

add_rule_actions adds rule actions to rules. This action is non-idempotent, meaning that even if the same rule action already exists for a rule, it will be added again with a new unique ID.

set_rule_actions sets rule actions for rules. This action is non-idempotent, meaning that even if the same set of rule actions already exists for a rule, it will be set again and the actions will receive new unique IDs.
Hide attributes Show attributes

type string Required

Values are add_rule_actions or set_rule_actions.

value object Required

Hide value attributes Show value attributes object

actions array[object] Required

Hide actions attributes Show actions attributes object

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.

Additional properties are allowed.

frequency object

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

Hide frequency attributes Show frequency attributes object

notifyWhen string Required

Defines how often rules run actions.

Values are onActiveAlert, onThrottleInterval, or 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 string | null Required

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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.

Additional properties are allowed.

throttle string

Defines the maximum interval in which a rule’s actions are executed.

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.

Values are rule, 1h, 1d, or 7d.
Overwrites schedule of rules.

set_schedule sets a schedule for rules. If the same schedule already exists for a rule, no changes are made.

Both interval and lookback have a format of "{integer}{time_unit}", where accepted time units are s for seconds, m for minutes, and h for hours. The integer must be positive and larger than 0. Examples: "45s", "30m", "6h"
Hide attributes Show attributes

type string Required

Value is set_schedule.

value object Required

Hide value attributes Show value attributes object

interval string Required

Interval in which the rule runs. For example, "1h" means the rule runs every hour.

Format should match the following pattern: ^[1-9]\d*[smh]$.

lookback string Required

Lookback time for the rules.

Additional look-back time that the rule analyzes. For example, "10m" means the rule analyzes the last 10 minutes of data in addition to the frequency interval.

Format should match the following pattern: ^[1-9]\d*[smh]$.
ids array[string]

Array of rule IDs. Array of rule IDs to which a bulk action will be applied. Only valid when query property is undefined.

At least 1 element.
query string

Query to filter rules.

Responses

200 application/json

OK
One of:
Security_Detections_API_BulkEditActionResponse object Security_Detections_API_BulkExportActionResponse string
Hide attributes Show attributes

attributes object Required

Hide attributes attributes Show attributes attributes object

errors array[object]

Hide errors attributes Show errors attributes object

err_code string

Values are IMMUTABLE, PREBUILT_CUSTOMIZATION_LICENSE, MACHINE_LEARNING_AUTH, MACHINE_LEARNING_INDEX_PATTERN, ESQL_INDEX_PATTERN, MANUAL_RULE_RUN_FEATURE, or MANUAL_RULE_RUN_DISABLED_RULE.

message string Required

rules array[object] Required

Hide rules attributes Show rules attributes object

id string Required

name string

status_code integer Required

results object Required

Hide results attributes Show results attributes object

created array[object] Required

Any of:
Security_Detections_API_EqlRuleResponseFields object Security_Detections_API_QueryRuleResponseFields object Security_Detections_API_SavedQueryRuleResponseFields object Security_Detections_API_ThresholdRuleResponseFields object Security_Detections_API_ThreatMatchRuleResponseFields object Security_Detections_API_MachineLearningRuleResponseFields object Security_Detections_API_NewTermsRuleResponseFields object Security_Detections_API_EsqlRuleResponseFields object

Hide attributes Show attributes

actions array[object] Required

Array defining the automated actions (notifications) taken when alerts are generated.

Hide actions attributes Show actions attributes object

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.

Additional properties are allowed.

frequency object

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

Hide frequency attributes Show frequency attributes object

notifyWhen string Required

Defines how often rules run actions.

Values are onActiveAlert, onThrottleInterval, or 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 string | null Required

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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.

Additional properties are allowed.

uuid string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

alias_purpose string

Values are savedObjectConversion or savedObjectImport.

alias_target_id string

author array[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 Required

The rule’s description.

Minimum length is 1.

enabled boolean Required

Determines whether the rule is enabled. Defaults to true.

exceptions_list array[object] Required

Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.

Hide exceptions_list attributes Show exceptions_list attributes object

id string(nonempty) Required

ID of the exception container

Minimum length is 1.

list_id string(nonempty) Required

List ID of the exception container

Minimum length is 1.

namespace_type string Required

Determines the exceptions validity in rule's Kibana space

Values are agnostic or single.

type string Required

The exception type

Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.

false_positives array[string] Required

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.

from string(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.

Hide investigation_fields attribute Show investigation_fields attribute object

field_names array[string(nonempty)] Required

A string that does not contain only whitespace characters

At least 1 element. Minimum length of each is 1.

license string

The rule's license.

max_signals integer Required

Maximum number of alerts the rule can create during a single run (the rule’s Max alerts per run advanced setting value).

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.

Minimum value is 1. Default value is 100.

meta object

Placeholder for metadata about the rule.

This field is overwritten when you save changes to the rule’s settings.

Additional properties are allowed.

name string Required

A human-readable name for the rule.

Minimum length is 1.

namespace string

Has no effect.

note string

Notes to help investigate alerts produced by the rule.

outcome string

Values are exactMatch, aliasMatch, or conflict.

output_index string Deprecated

(deprecated) Has no effect.

references array[string] Required

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.

related_integrations array[object] Required

Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:

package: name of the package (required, unique id)

version: version of the package (required, semver-compatible)

integration: name of the integration of this package (optional, id within the package)

There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.

Hide related_integrations attributes Show related_integrations attributes object

integration string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

package string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

version string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

required_fields array[object] Required

Elasticsearch fields and their types that need to be present for the rule to function.

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.

Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.

Hide required_fields attributes Show required_fields attributes object

name string(nonempty) Required

Name of an Elasticsearch field

Minimum length is 1.

type string(nonempty) Required

Type of the Elasticsearch field

Minimum length is 1.

response_actions array[object]

One of:
Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object

Hide attributes Show attributes

action_type_id string Required

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

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

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[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.

Hide attributes Show attributes

action_type_id string Required

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object

Hide attributes Show attributes

command string Required

Value is isolate.

comment string

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.

risk_score integer 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

Minimum value is 0, maximum value is 100.

risk_score_mapping array[object] Required

Overrides generated alerts' risk_score with a value from the source event

Hide risk_score_mapping attributes Show risk_score_mapping attributes object

field string Required

Source event field used to override the default risk_score.

operator string Required

Value is equals.

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

Minimum value is 0, maximum value is 100.

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 string 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 are low, medium, high, or critical.

severity_mapping array[object] Required

Overrides generated alerts' severity with values from the source event

Hide severity_mapping attributes Show severity_mapping attributes object

field string Required

Source event field used to override the default severity.

operator string Required

Value is equals.

severity string 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 are low, medium, high, or critical.

value string Required

tags array[string] Required

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.

threat array[object] Required

Currently, only threats described using the MITRE ATT&CK™ framework are supported.

Hide threat attributes Show threat attributes object

framework string Required

Relevant attack framework

tactic object Required

Object containing information on the attack type

Hide tactic attributes Show tactic attributes object

id string Required

Tactic ID

name string Required

Tactic name

reference string Required

Tactic reference

technique array[object]

Array containing information on the attack techniques (optional)

Hide technique attributes Show technique attributes object

id string Required

Technique ID

name string Required

Technique name

reference string Required

Technique reference

subtechnique array[object]

Array containing more specific information on the attack technique.

Hide subtechnique attributes Show subtechnique attributes object

id string Required

Subtechnique ID

name string Required

Subtechnique name

reference string Required

Subtechnique reference

throttle string | null

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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 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.

It is not incremented on each update. Compare this to the revision field.

Minimum value is 1.

created_at string(date-time) Required

created_by string Required

execution_summary object

Summary of the last execution of a rule.

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

Hide execution_summary attribute Show execution_summary attribute object

last_execution object Required

Hide last_execution attributes Show last_execution attributes object

date string(date-time) Required

Date of the last execution

message string Required

metrics object Required

Hide metrics attributes Show metrics attributes object

execution_gap_duration_s integer

Duration in seconds of execution gap

Minimum value is 0.

frozen_indices_queried_count integer

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

Minimum value is 0.

gap_range object

Range of the execution gap

Hide gap_range attributes Show gap_range attributes object

gte string Required

Start date of the execution gap

lte string Required

End date of the execution gap

total_enrichment_duration_ms integer

Total time spent enriching documents during current rule execution cycle

Minimum value is 0.

total_indexing_duration_ms integer

Total time spent indexing documents during current rule execution cycle

Minimum value is 0.

total_search_duration_ms integer

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

Minimum value is 0.

status string Required

Status of the last execution

Values are going to run, running, partial failure, failed, or succeeded.

status_order integer Required

id string(uuid) Required

A dynamic unique identifier for the rule object. It is randomly generated when a rule is created and cannot be changed after that. It is always a UUID. It is unique within a given Kibana space. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have different object ids.

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

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.

Minimum value is 0.

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 object 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:
Security_Detections_API_ExternalRuleSource object Security_Detections_API_InternalRuleSource object

Type of rule source for externally sourced rules, i.e. rules that have an external source, such as the Elastic Prebuilt rules repo.

Hide attributes Show attributes

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

type string Required Discriminator

Value is external.

updated_at string(date-time) Required

updated_by string Required

language string Required

Query language to use

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

type string Required Discriminator

Rule type

Value is eql.

alert_suppression object

Defines alert suppression configuration.

Hide alert_suppression attributes Show alert_suppression attributes object

duration object

Hide duration attributes Show duration attributes object

unit string Required

Time unit

Values are s, m, or h.

value integer Required

Minimum value is 1.

group_by array[string] Required

At least 1 but not more than 3 elements.

missing_fields_strategy string

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 are doNotSuppress or suppress.

data_view_id string

event_category_override string

filters array

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

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.

Hide attributes Show attributes

actions array[object] Required

Array defining the automated actions (notifications) taken when alerts are generated.

Hide actions attributes Show actions attributes object

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.

Additional properties are allowed.

frequency object

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

Hide frequency attributes Show frequency attributes object

notifyWhen string Required

Defines how often rules run actions.

Values are onActiveAlert, onThrottleInterval, or 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 string | null Required

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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.

Additional properties are allowed.

uuid string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

alias_purpose string

Values are savedObjectConversion or savedObjectImport.

alias_target_id string

author array[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 Required

The rule’s description.

Minimum length is 1.

enabled boolean Required

Determines whether the rule is enabled. Defaults to true.

exceptions_list array[object] Required

Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.

Hide exceptions_list attributes Show exceptions_list attributes object

id string(nonempty) Required

ID of the exception container

Minimum length is 1.

list_id string(nonempty) Required

List ID of the exception container

Minimum length is 1.

namespace_type string Required

Determines the exceptions validity in rule's Kibana space

Values are agnostic or single.

type string Required

The exception type

Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.

false_positives array[string] Required

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.

from string(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.

Hide investigation_fields attribute Show investigation_fields attribute object

field_names array[string(nonempty)] Required

A string that does not contain only whitespace characters

At least 1 element. Minimum length of each is 1.

license string

The rule's license.

max_signals integer Required

Maximum number of alerts the rule can create during a single run (the rule’s Max alerts per run advanced setting value).

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.

Minimum value is 1. Default value is 100.

meta object

Placeholder for metadata about the rule.

This field is overwritten when you save changes to the rule’s settings.

Additional properties are allowed.

name string Required

A human-readable name for the rule.

Minimum length is 1.

namespace string

Has no effect.

note string

Notes to help investigate alerts produced by the rule.

outcome string

Values are exactMatch, aliasMatch, or conflict.

output_index string Deprecated

(deprecated) Has no effect.

references array[string] Required

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.

related_integrations array[object] Required

Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:

package: name of the package (required, unique id)

version: version of the package (required, semver-compatible)

integration: name of the integration of this package (optional, id within the package)

There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.

Hide related_integrations attributes Show related_integrations attributes object

integration string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

package string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

version string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

required_fields array[object] Required

Elasticsearch fields and their types that need to be present for the rule to function.

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.

Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.

Hide required_fields attributes Show required_fields attributes object

name string(nonempty) Required

Name of an Elasticsearch field

Minimum length is 1.

type string(nonempty) Required

Type of the Elasticsearch field

Minimum length is 1.

response_actions array[object]

One of:
Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object

Hide attributes Show attributes

action_type_id string Required

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

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

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[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.

Hide attributes Show attributes

action_type_id string Required

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object

Hide attributes Show attributes

command string Required

Value is isolate.

comment string

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.

risk_score integer 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

Minimum value is 0, maximum value is 100.

risk_score_mapping array[object] Required

Overrides generated alerts' risk_score with a value from the source event

Hide risk_score_mapping attributes Show risk_score_mapping attributes object

field string Required

Source event field used to override the default risk_score.

operator string Required

Value is equals.

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

Minimum value is 0, maximum value is 100.

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 string 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 are low, medium, high, or critical.

severity_mapping array[object] Required

Overrides generated alerts' severity with values from the source event

Hide severity_mapping attributes Show severity_mapping attributes object

field string Required

Source event field used to override the default severity.

operator string Required

Value is equals.

severity string 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 are low, medium, high, or critical.

value string Required

tags array[string] Required

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.

threat array[object] Required

Currently, only threats described using the MITRE ATT&CK™ framework are supported.

Hide threat attributes Show threat attributes object

framework string Required

Relevant attack framework

tactic object Required

Object containing information on the attack type

Hide tactic attributes Show tactic attributes object

id string Required

Tactic ID

name string Required

Tactic name

reference string Required

Tactic reference

technique array[object]

Array containing information on the attack techniques (optional)

Hide technique attributes Show technique attributes object

id string Required

Technique ID

name string Required

Technique name

reference string Required

Technique reference

subtechnique array[object]

Array containing more specific information on the attack technique.

Hide subtechnique attributes Show subtechnique attributes object

id string Required

Subtechnique ID

name string Required

Subtechnique name

reference string Required

Subtechnique reference

throttle string | null

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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 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.

It is not incremented on each update. Compare this to the revision field.

Minimum value is 1.

created_at string(date-time) Required

created_by string Required

execution_summary object

Summary of the last execution of a rule.

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

Hide execution_summary attribute Show execution_summary attribute object

last_execution object Required

Hide last_execution attributes Show last_execution attributes object

date string(date-time) Required

Date of the last execution

message string Required

metrics object Required

Hide metrics attributes Show metrics attributes object

execution_gap_duration_s integer

Duration in seconds of execution gap

Minimum value is 0.

frozen_indices_queried_count integer

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

Minimum value is 0.

gap_range object

Range of the execution gap

Hide gap_range attributes Show gap_range attributes object

gte string Required

Start date of the execution gap

lte string Required

End date of the execution gap

total_enrichment_duration_ms integer

Total time spent enriching documents during current rule execution cycle

Minimum value is 0.

total_indexing_duration_ms integer

Total time spent indexing documents during current rule execution cycle

Minimum value is 0.

total_search_duration_ms integer

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

Minimum value is 0.

status string Required

Status of the last execution

Values are going to run, running, partial failure, failed, or succeeded.

status_order integer Required

id string(uuid) Required

A dynamic unique identifier for the rule object. It is randomly generated when a rule is created and cannot be changed after that. It is always a UUID. It is unique within a given Kibana space. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have different object ids.

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

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.

Minimum value is 0.

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 object 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:
Security_Detections_API_ExternalRuleSource object Security_Detections_API_InternalRuleSource object

Type of rule source for externally sourced rules, i.e. rules that have an external source, such as the Elastic Prebuilt rules repo.

Hide attributes Show attributes

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

type string Required Discriminator

Value is external.

updated_at string(date-time) Required

updated_by string Required

type string Required Discriminator

Rule type

Value is query.

alert_suppression object

Defines alert suppression configuration.

Hide alert_suppression attributes Show alert_suppression attributes object

duration object

Hide duration attributes Show duration attributes object

unit string Required

Time unit

Values are s, m, or h.

value integer Required

Minimum value is 1.

group_by array[string] Required

At least 1 but not more than 3 elements.

missing_fields_strategy string

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 are doNotSuppress or suppress.

data_view_id string

filters array

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

saved_id string

Kibana saved search used by the rule to create alerts.

language string Required

Values are kuery or lucene.

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.

Hide attributes Show attributes

actions array[object] Required

Array defining the automated actions (notifications) taken when alerts are generated.

Hide actions attributes Show actions attributes object

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.

Additional properties are allowed.

frequency object

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

Hide frequency attributes Show frequency attributes object

notifyWhen string Required

Defines how often rules run actions.

Values are onActiveAlert, onThrottleInterval, or 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 string | null Required

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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.

Additional properties are allowed.

uuid string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

alias_purpose string

Values are savedObjectConversion or savedObjectImport.

alias_target_id string

author array[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 Required

The rule’s description.

Minimum length is 1.

enabled boolean Required

Determines whether the rule is enabled. Defaults to true.

exceptions_list array[object] Required

Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.

Hide exceptions_list attributes Show exceptions_list attributes object

id string(nonempty) Required

ID of the exception container

Minimum length is 1.

list_id string(nonempty) Required

List ID of the exception container

Minimum length is 1.

namespace_type string Required

Determines the exceptions validity in rule's Kibana space

Values are agnostic or single.

type string Required

The exception type

Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.

false_positives array[string] Required

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.

from string(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.

Hide investigation_fields attribute Show investigation_fields attribute object

field_names array[string(nonempty)] Required

A string that does not contain only whitespace characters

At least 1 element. Minimum length of each is 1.

license string

The rule's license.

max_signals integer Required

Maximum number of alerts the rule can create during a single run (the rule’s Max alerts per run advanced setting value).

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.

Minimum value is 1. Default value is 100.

meta object

Placeholder for metadata about the rule.

This field is overwritten when you save changes to the rule’s settings.

Additional properties are allowed.

name string Required

A human-readable name for the rule.

Minimum length is 1.

namespace string

Has no effect.

note string

Notes to help investigate alerts produced by the rule.

outcome string

Values are exactMatch, aliasMatch, or conflict.

output_index string Deprecated

(deprecated) Has no effect.

references array[string] Required

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.

related_integrations array[object] Required

Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:

package: name of the package (required, unique id)

version: version of the package (required, semver-compatible)

integration: name of the integration of this package (optional, id within the package)

There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.

Hide related_integrations attributes Show related_integrations attributes object

integration string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

package string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

version string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

required_fields array[object] Required

Elasticsearch fields and their types that need to be present for the rule to function.

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.

Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.

Hide required_fields attributes Show required_fields attributes object

name string(nonempty) Required

Name of an Elasticsearch field

Minimum length is 1.

type string(nonempty) Required

Type of the Elasticsearch field

Minimum length is 1.

response_actions array[object]

One of:
Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object

Hide attributes Show attributes

action_type_id string Required

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

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

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[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.

Hide attributes Show attributes

action_type_id string Required

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object

Hide attributes Show attributes

command string Required

Value is isolate.

comment string

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.

risk_score integer 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

Minimum value is 0, maximum value is 100.

risk_score_mapping array[object] Required

Overrides generated alerts' risk_score with a value from the source event

Hide risk_score_mapping attributes Show risk_score_mapping attributes object

field string Required

Source event field used to override the default risk_score.

operator string Required

Value is equals.

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

Minimum value is 0, maximum value is 100.

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 string 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 are low, medium, high, or critical.

severity_mapping array[object] Required

Overrides generated alerts' severity with values from the source event

Hide severity_mapping attributes Show severity_mapping attributes object

field string Required

Source event field used to override the default severity.

operator string Required

Value is equals.

severity string 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 are low, medium, high, or critical.

value string Required

tags array[string] Required

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.

threat array[object] Required

Currently, only threats described using the MITRE ATT&CK™ framework are supported.

Hide threat attributes Show threat attributes object

framework string Required

Relevant attack framework

tactic object Required

Object containing information on the attack type

Hide tactic attributes Show tactic attributes object

id string Required

Tactic ID

name string Required

Tactic name

reference string Required

Tactic reference

technique array[object]

Array containing information on the attack techniques (optional)

Hide technique attributes Show technique attributes object

id string Required

Technique ID

name string Required

Technique name

reference string Required

Technique reference

subtechnique array[object]

Array containing more specific information on the attack technique.

Hide subtechnique attributes Show subtechnique attributes object

id string Required

Subtechnique ID

name string Required

Subtechnique name

reference string Required

Subtechnique reference

throttle string | null

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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 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.

It is not incremented on each update. Compare this to the revision field.

Minimum value is 1.

created_at string(date-time) Required

created_by string Required

execution_summary object

Summary of the last execution of a rule.

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

Hide execution_summary attribute Show execution_summary attribute object

last_execution object Required

Hide last_execution attributes Show last_execution attributes object

date string(date-time) Required

Date of the last execution

message string Required

metrics object Required

Hide metrics attributes Show metrics attributes object

execution_gap_duration_s integer

Duration in seconds of execution gap

Minimum value is 0.

frozen_indices_queried_count integer

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

Minimum value is 0.

gap_range object

Range of the execution gap

Hide gap_range attributes Show gap_range attributes object

gte string Required

Start date of the execution gap

lte string Required

End date of the execution gap

total_enrichment_duration_ms integer

Total time spent enriching documents during current rule execution cycle

Minimum value is 0.

total_indexing_duration_ms integer

Total time spent indexing documents during current rule execution cycle

Minimum value is 0.

total_search_duration_ms integer

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

Minimum value is 0.

status string Required

Status of the last execution

Values are going to run, running, partial failure, failed, or succeeded.

status_order integer Required

id string(uuid) Required

A dynamic unique identifier for the rule object. It is randomly generated when a rule is created and cannot be changed after that. It is always a UUID. It is unique within a given Kibana space. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have different object ids.

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

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.

Minimum value is 0.

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 object 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:
Security_Detections_API_ExternalRuleSource object Security_Detections_API_InternalRuleSource object

Type of rule source for externally sourced rules, i.e. rules that have an external source, such as the Elastic Prebuilt rules repo.

Hide attributes Show attributes

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

type string Required Discriminator

Value is external.

updated_at string(date-time) Required

updated_by string Required

saved_id string Required

Kibana saved search used by the rule to create alerts.

type string Required Discriminator

Rule type

Value is saved_query.

alert_suppression object

Defines alert suppression configuration.

Hide alert_suppression attributes Show alert_suppression attributes object

duration object

Hide duration attributes Show duration attributes object

unit string Required

Time unit

Values are s, m, or h.

value integer Required

Minimum value is 1.

group_by array[string] Required

At least 1 but not more than 3 elements.

missing_fields_strategy string

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 are doNotSuppress or suppress.

data_view_id string

filters array

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

query string

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.

language string Required

Values are kuery or lucene.

Hide attributes Show attributes

actions array[object] Required

Array defining the automated actions (notifications) taken when alerts are generated.

Hide actions attributes Show actions attributes object

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.

Additional properties are allowed.

frequency object

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

Hide frequency attributes Show frequency attributes object

notifyWhen string Required

Defines how often rules run actions.

Values are onActiveAlert, onThrottleInterval, or 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 string | null Required

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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.

Additional properties are allowed.

uuid string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

alias_purpose string

Values are savedObjectConversion or savedObjectImport.

alias_target_id string

author array[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 Required

The rule’s description.

Minimum length is 1.

enabled boolean Required

Determines whether the rule is enabled. Defaults to true.

exceptions_list array[object] Required

Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.

Hide exceptions_list attributes Show exceptions_list attributes object

id string(nonempty) Required

ID of the exception container

Minimum length is 1.

list_id string(nonempty) Required

List ID of the exception container

Minimum length is 1.

namespace_type string Required

Determines the exceptions validity in rule's Kibana space

Values are agnostic or single.

type string Required

The exception type

Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.

false_positives array[string] Required

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.

from string(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.

Hide investigation_fields attribute Show investigation_fields attribute object

field_names array[string(nonempty)] Required

A string that does not contain only whitespace characters

At least 1 element. Minimum length of each is 1.

license string

The rule's license.

max_signals integer Required

Maximum number of alerts the rule can create during a single run (the rule’s Max alerts per run advanced setting value).

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.

Minimum value is 1. Default value is 100.

meta object

Placeholder for metadata about the rule.

This field is overwritten when you save changes to the rule’s settings.

Additional properties are allowed.

name string Required

A human-readable name for the rule.

Minimum length is 1.

namespace string

Has no effect.

note string

Notes to help investigate alerts produced by the rule.

outcome string

Values are exactMatch, aliasMatch, or conflict.

output_index string Deprecated

(deprecated) Has no effect.

references array[string] Required

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.

related_integrations array[object] Required

Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:

package: name of the package (required, unique id)

version: version of the package (required, semver-compatible)

integration: name of the integration of this package (optional, id within the package)

There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.

Hide related_integrations attributes Show related_integrations attributes object

integration string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

package string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

version string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

required_fields array[object] Required

Elasticsearch fields and their types that need to be present for the rule to function.

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.

Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.

Hide required_fields attributes Show required_fields attributes object

name string(nonempty) Required

Name of an Elasticsearch field

Minimum length is 1.

type string(nonempty) Required

Type of the Elasticsearch field

Minimum length is 1.

response_actions array[object]

One of:
Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object

Hide attributes Show attributes

action_type_id string Required

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

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

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[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.

Hide attributes Show attributes

action_type_id string Required

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object

Hide attributes Show attributes

command string Required

Value is isolate.

comment string

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.

risk_score integer 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

Minimum value is 0, maximum value is 100.

risk_score_mapping array[object] Required

Overrides generated alerts' risk_score with a value from the source event

Hide risk_score_mapping attributes Show risk_score_mapping attributes object

field string Required

Source event field used to override the default risk_score.

operator string Required

Value is equals.

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

Minimum value is 0, maximum value is 100.

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 string 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 are low, medium, high, or critical.

severity_mapping array[object] Required

Overrides generated alerts' severity with values from the source event

Hide severity_mapping attributes Show severity_mapping attributes object

field string Required

Source event field used to override the default severity.

operator string Required

Value is equals.

severity string 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 are low, medium, high, or critical.

value string Required

tags array[string] Required

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.

threat array[object] Required

Currently, only threats described using the MITRE ATT&CK™ framework are supported.

Hide threat attributes Show threat attributes object

framework string Required

Relevant attack framework

tactic object Required

Object containing information on the attack type

Hide tactic attributes Show tactic attributes object

id string Required

Tactic ID

name string Required

Tactic name

reference string Required

Tactic reference

technique array[object]

Array containing information on the attack techniques (optional)

Hide technique attributes Show technique attributes object

id string Required

Technique ID

name string Required

Technique name

reference string Required

Technique reference

subtechnique array[object]

Array containing more specific information on the attack technique.

Hide subtechnique attributes Show subtechnique attributes object

id string Required

Subtechnique ID

name string Required

Subtechnique name

reference string Required

Subtechnique reference

throttle string | null

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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 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.

It is not incremented on each update. Compare this to the revision field.

Minimum value is 1.

created_at string(date-time) Required

created_by string Required

execution_summary object

Summary of the last execution of a rule.

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

Hide execution_summary attribute Show execution_summary attribute object

last_execution object Required

Hide last_execution attributes Show last_execution attributes object

date string(date-time) Required

Date of the last execution

message string Required

metrics object Required

Hide metrics attributes Show metrics attributes object

execution_gap_duration_s integer

Duration in seconds of execution gap

Minimum value is 0.

frozen_indices_queried_count integer

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

Minimum value is 0.

gap_range object

Range of the execution gap

Hide gap_range attributes Show gap_range attributes object

gte string Required

Start date of the execution gap

lte string Required

End date of the execution gap

total_enrichment_duration_ms integer

Total time spent enriching documents during current rule execution cycle

Minimum value is 0.

total_indexing_duration_ms integer

Total time spent indexing documents during current rule execution cycle

Minimum value is 0.

total_search_duration_ms integer

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

Minimum value is 0.

status string Required

Status of the last execution

Values are going to run, running, partial failure, failed, or succeeded.

status_order integer Required

id string(uuid) Required

A dynamic unique identifier for the rule object. It is randomly generated when a rule is created and cannot be changed after that. It is always a UUID. It is unique within a given Kibana space. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have different object ids.

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

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.

Minimum value is 0.

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 object 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:
Security_Detections_API_ExternalRuleSource object Security_Detections_API_InternalRuleSource object

Type of rule source for externally sourced rules, i.e. rules that have an external source, such as the Elastic Prebuilt rules repo.

Hide attributes Show attributes

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

type string Required Discriminator

Value is external.

updated_at string(date-time) Required

updated_by string Required

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.

threshold object Required

Hide threshold attributes Show threshold attributes object

cardinality array[object]

The field on which the cardinality is applied.

Hide cardinality attributes Show cardinality attributes object

field string Required

The field on which to calculate and compare the cardinality.

value integer Required

The threshold value from which an alert is generated based on unique number of values of cardinality.field.

Minimum value is 0.

field string | array[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.

One of:
string-1 string array-2 array[string]

value integer Required

The threshold value from which an alert is generated.

Minimum value is 1.

type string Required Discriminator

Rule type

Value is threshold.

alert_suppression object

Defines alert suppression configuration.

Hide alert_suppression attribute Show alert_suppression attribute object

duration object Required

Hide duration attributes Show duration attributes object

unit string Required

Time unit

Values are s, m, or h.

value integer Required

Minimum value is 1.

data_view_id string

filters array

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

saved_id string

Kibana saved search used by the rule to create alerts.

language string Required

Values are kuery or lucene.

Hide attributes Show attributes

actions array[object] Required

Array defining the automated actions (notifications) taken when alerts are generated.

Hide actions attributes Show actions attributes object

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.

Additional properties are allowed.

frequency object

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

Hide frequency attributes Show frequency attributes object

notifyWhen string Required

Defines how often rules run actions.

Values are onActiveAlert, onThrottleInterval, or 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 string | null Required

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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.

Additional properties are allowed.

uuid string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

alias_purpose string

Values are savedObjectConversion or savedObjectImport.

alias_target_id string

author array[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 Required

The rule’s description.

Minimum length is 1.

enabled boolean Required

Determines whether the rule is enabled. Defaults to true.

exceptions_list array[object] Required

Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.

Hide exceptions_list attributes Show exceptions_list attributes object

id string(nonempty) Required

ID of the exception container

Minimum length is 1.

list_id string(nonempty) Required

List ID of the exception container

Minimum length is 1.

namespace_type string Required

Determines the exceptions validity in rule's Kibana space

Values are agnostic or single.

type string Required

The exception type

Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.

false_positives array[string] Required

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.

from string(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.

Hide investigation_fields attribute Show investigation_fields attribute object

field_names array[string(nonempty)] Required

A string that does not contain only whitespace characters

At least 1 element. Minimum length of each is 1.

license string

The rule's license.

max_signals integer Required

Maximum number of alerts the rule can create during a single run (the rule’s Max alerts per run advanced setting value).

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.

Minimum value is 1. Default value is 100.

meta object

Placeholder for metadata about the rule.

This field is overwritten when you save changes to the rule’s settings.

Additional properties are allowed.

name string Required

A human-readable name for the rule.

Minimum length is 1.

namespace string

Has no effect.

note string

Notes to help investigate alerts produced by the rule.

outcome string

Values are exactMatch, aliasMatch, or conflict.

output_index string Deprecated

(deprecated) Has no effect.

references array[string] Required

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.

related_integrations array[object] Required

Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:

package: name of the package (required, unique id)

version: version of the package (required, semver-compatible)

integration: name of the integration of this package (optional, id within the package)

There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.

Hide related_integrations attributes Show related_integrations attributes object

integration string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

package string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

version string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

required_fields array[object] Required

Elasticsearch fields and their types that need to be present for the rule to function.

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.

Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.

Hide required_fields attributes Show required_fields attributes object

name string(nonempty) Required

Name of an Elasticsearch field

Minimum length is 1.

type string(nonempty) Required

Type of the Elasticsearch field

Minimum length is 1.

response_actions array[object]

One of:
Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object

Hide attributes Show attributes

action_type_id string Required

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

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

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[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.

Hide attributes Show attributes

action_type_id string Required

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object

Hide attributes Show attributes

command string Required

Value is isolate.

comment string

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.

risk_score integer 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

Minimum value is 0, maximum value is 100.

risk_score_mapping array[object] Required

Overrides generated alerts' risk_score with a value from the source event

Hide risk_score_mapping attributes Show risk_score_mapping attributes object

field string Required

Source event field used to override the default risk_score.

operator string Required

Value is equals.

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

Minimum value is 0, maximum value is 100.

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 string 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 are low, medium, high, or critical.

severity_mapping array[object] Required

Overrides generated alerts' severity with values from the source event

Hide severity_mapping attributes Show severity_mapping attributes object

field string Required

Source event field used to override the default severity.

operator string Required

Value is equals.

severity string 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 are low, medium, high, or critical.

value string Required

tags array[string] Required

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.

threat array[object] Required

Currently, only threats described using the MITRE ATT&CK™ framework are supported.

Hide threat attributes Show threat attributes object

framework string Required

Relevant attack framework

tactic object Required

Object containing information on the attack type

Hide tactic attributes Show tactic attributes object

id string Required

Tactic ID

name string Required

Tactic name

reference string Required

Tactic reference

technique array[object]

Array containing information on the attack techniques (optional)

Hide technique attributes Show technique attributes object

id string Required

Technique ID

name string Required

Technique name

reference string Required

Technique reference

subtechnique array[object]

Array containing more specific information on the attack technique.

Hide subtechnique attributes Show subtechnique attributes object

id string Required

Subtechnique ID

name string Required

Subtechnique name

reference string Required

Subtechnique reference

throttle string | null

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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 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.

It is not incremented on each update. Compare this to the revision field.

Minimum value is 1.

created_at string(date-time) Required

created_by string Required

execution_summary object

Summary of the last execution of a rule.

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

Hide execution_summary attribute Show execution_summary attribute object

last_execution object Required

Hide last_execution attributes Show last_execution attributes object

date string(date-time) Required

Date of the last execution

message string Required

metrics object Required

Hide metrics attributes Show metrics attributes object

execution_gap_duration_s integer

Duration in seconds of execution gap

Minimum value is 0.

frozen_indices_queried_count integer

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

Minimum value is 0.

gap_range object

Range of the execution gap

Hide gap_range attributes Show gap_range attributes object

gte string Required

Start date of the execution gap

lte string Required

End date of the execution gap

total_enrichment_duration_ms integer

Total time spent enriching documents during current rule execution cycle

Minimum value is 0.

total_indexing_duration_ms integer

Total time spent indexing documents during current rule execution cycle

Minimum value is 0.

total_search_duration_ms integer

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

Minimum value is 0.

status string Required

Status of the last execution

Values are going to run, running, partial failure, failed, or succeeded.

status_order integer Required

id string(uuid) Required

A dynamic unique identifier for the rule object. It is randomly generated when a rule is created and cannot be changed after that. It is always a UUID. It is unique within a given Kibana space. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have different object ids.

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

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.

Minimum value is 0.

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 object 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:
Security_Detections_API_ExternalRuleSource object Security_Detections_API_InternalRuleSource object

Type of rule source for externally sourced rules, i.e. rules that have an external source, such as the Elastic Prebuilt rules repo.

Hide attributes Show attributes

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

type string Required Discriminator

Value is external.

updated_at string(date-time) Required

updated_by string Required

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.

threat_index array[string] Required

Elasticsearch indices used to check which field values generate alerts.

threat_mapping array[object] Required

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 Example of Threat Match rule which uses both and and or logic.

At least 1 element.

Hide threat_mapping attribute Show threat_mapping attribute object

entries array[object] Required

Hide entries attributes Show entries attributes object

field string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

type string Required

Value is mapping.

value string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

threat_query string Required

Query used to determine which fields in the Elasticsearch index are used for generating alerts.

type string Required Discriminator

Rule type

Value is threat_match.

alert_suppression object

Defines alert suppression configuration.

Hide alert_suppression attributes Show alert_suppression attributes object

duration object

Hide duration attributes Show duration attributes object

unit string Required

Time unit

Values are s, m, or h.

value integer Required

Minimum value is 1.

group_by array[string] Required

At least 1 but not more than 3 elements.

missing_fields_strategy string

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 are doNotSuppress or suppress.

concurrent_searches integer

Minimum value is 1.

data_view_id string

filters array

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

items_per_search integer

Minimum value is 1.

saved_id string

Kibana saved search used by the rule to create alerts.

threat_filters array

Query and filter context array used to filter documents from the Elasticsearch index containing the threat values

threat_indicator_path string

Defines the path to the threat indicator in the indicator documents (optional)

threat_language string

Values are kuery or lucene.

language string Required

Values are kuery or lucene.

Hide attributes Show attributes

actions array[object] Required

Array defining the automated actions (notifications) taken when alerts are generated.

Hide actions attributes Show actions attributes object

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.

Additional properties are allowed.

frequency object

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

Hide frequency attributes Show frequency attributes object

notifyWhen string Required

Defines how often rules run actions.

Values are onActiveAlert, onThrottleInterval, or 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 string | null Required

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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.

Additional properties are allowed.

uuid string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

alias_purpose string

Values are savedObjectConversion or savedObjectImport.

alias_target_id string

author array[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 Required

The rule’s description.

Minimum length is 1.

enabled boolean Required

Determines whether the rule is enabled. Defaults to true.

exceptions_list array[object] Required

Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.

Hide exceptions_list attributes Show exceptions_list attributes object

id string(nonempty) Required

ID of the exception container

Minimum length is 1.

list_id string(nonempty) Required

List ID of the exception container

Minimum length is 1.

namespace_type string Required

Determines the exceptions validity in rule's Kibana space

Values are agnostic or single.

type string Required

The exception type

Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.

false_positives array[string] Required

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.

from string(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.

Hide investigation_fields attribute Show investigation_fields attribute object

field_names array[string(nonempty)] Required

A string that does not contain only whitespace characters

At least 1 element. Minimum length of each is 1.

license string

The rule's license.

max_signals integer Required

Maximum number of alerts the rule can create during a single run (the rule’s Max alerts per run advanced setting value).

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.

Minimum value is 1. Default value is 100.

meta object

Placeholder for metadata about the rule.

This field is overwritten when you save changes to the rule’s settings.

Additional properties are allowed.

name string Required

A human-readable name for the rule.

Minimum length is 1.

namespace string

Has no effect.

note string

Notes to help investigate alerts produced by the rule.

outcome string

Values are exactMatch, aliasMatch, or conflict.

output_index string Deprecated

(deprecated) Has no effect.

references array[string] Required

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.

related_integrations array[object] Required

Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:

package: name of the package (required, unique id)

version: version of the package (required, semver-compatible)

integration: name of the integration of this package (optional, id within the package)

There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.

Hide related_integrations attributes Show related_integrations attributes object

integration string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

package string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

version string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

required_fields array[object] Required

Elasticsearch fields and their types that need to be present for the rule to function.

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.

Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.

Hide required_fields attributes Show required_fields attributes object

name string(nonempty) Required

Name of an Elasticsearch field

Minimum length is 1.

type string(nonempty) Required

Type of the Elasticsearch field

Minimum length is 1.

response_actions array[object]

One of:
Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object

Hide attributes Show attributes

action_type_id string Required

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

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

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[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.

Hide attributes Show attributes

action_type_id string Required

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object

Hide attributes Show attributes

command string Required

Value is isolate.

comment string

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.

risk_score integer 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

Minimum value is 0, maximum value is 100.

risk_score_mapping array[object] Required

Overrides generated alerts' risk_score with a value from the source event

Hide risk_score_mapping attributes Show risk_score_mapping attributes object

field string Required

Source event field used to override the default risk_score.

operator string Required

Value is equals.

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

Minimum value is 0, maximum value is 100.

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 string 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 are low, medium, high, or critical.

severity_mapping array[object] Required

Overrides generated alerts' severity with values from the source event

Hide severity_mapping attributes Show severity_mapping attributes object

field string Required

Source event field used to override the default severity.

operator string Required

Value is equals.

severity string 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 are low, medium, high, or critical.

value string Required

tags array[string] Required

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.

threat array[object] Required

Currently, only threats described using the MITRE ATT&CK™ framework are supported.

Hide threat attributes Show threat attributes object

framework string Required

Relevant attack framework

tactic object Required

Object containing information on the attack type

Hide tactic attributes Show tactic attributes object

id string Required

Tactic ID

name string Required

Tactic name

reference string Required

Tactic reference

technique array[object]

Array containing information on the attack techniques (optional)

Hide technique attributes Show technique attributes object

id string Required

Technique ID

name string Required

Technique name

reference string Required

Technique reference

subtechnique array[object]

Array containing more specific information on the attack technique.

Hide subtechnique attributes Show subtechnique attributes object

id string Required

Subtechnique ID

name string Required

Subtechnique name

reference string Required

Subtechnique reference

throttle string | null

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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 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.

It is not incremented on each update. Compare this to the revision field.

Minimum value is 1.

created_at string(date-time) Required

created_by string Required

execution_summary object

Summary of the last execution of a rule.

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

Hide execution_summary attribute Show execution_summary attribute object

last_execution object Required

Hide last_execution attributes Show last_execution attributes object

date string(date-time) Required

Date of the last execution

message string Required

metrics object Required

Hide metrics attributes Show metrics attributes object

execution_gap_duration_s integer

Duration in seconds of execution gap

Minimum value is 0.

frozen_indices_queried_count integer

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

Minimum value is 0.

gap_range object

Range of the execution gap

Hide gap_range attributes Show gap_range attributes object

gte string Required

Start date of the execution gap

lte string Required

End date of the execution gap

total_enrichment_duration_ms integer

Total time spent enriching documents during current rule execution cycle

Minimum value is 0.

total_indexing_duration_ms integer

Total time spent indexing documents during current rule execution cycle

Minimum value is 0.

total_search_duration_ms integer

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

Minimum value is 0.

status string Required

Status of the last execution

Values are going to run, running, partial failure, failed, or succeeded.

status_order integer Required

id string(uuid) Required

A dynamic unique identifier for the rule object. It is randomly generated when a rule is created and cannot be changed after that. It is always a UUID. It is unique within a given Kibana space. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have different object ids.

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

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.

Minimum value is 0.

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 object 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:
Security_Detections_API_ExternalRuleSource object Security_Detections_API_InternalRuleSource object

Type of rule source for externally sourced rules, i.e. rules that have an external source, such as the Elastic Prebuilt rules repo.

Hide attributes Show attributes

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

type string Required Discriminator

Value is external.

updated_at string(date-time) Required

updated_by string Required

anomaly_threshold integer Required

Anomaly score threshold above which the rule creates an alert. Valid values are from 0 to 100.

Minimum value is 0.

machine_learning_job_id string | array[string] Required

Machine learning job ID(s) the rule monitors for anomaly scores.

One of:
string-1 string array-2 array[string]

type string Required Discriminator

Rule type

Value is machine_learning.

alert_suppression object

Defines alert suppression configuration.

Hide alert_suppression attributes Show alert_suppression attributes object

duration object

Hide duration attributes Show duration attributes object

unit string Required

Time unit

Values are s, m, or h.

value integer Required

Minimum value is 1.

group_by array[string] Required

At least 1 but not more than 3 elements.

missing_fields_strategy string

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 are doNotSuppress or suppress.

Hide attributes Show attributes

actions array[object] Required

Array defining the automated actions (notifications) taken when alerts are generated.

Hide actions attributes Show actions attributes object

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.

Additional properties are allowed.

frequency object

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

Hide frequency attributes Show frequency attributes object

notifyWhen string Required

Defines how often rules run actions.

Values are onActiveAlert, onThrottleInterval, or 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 string | null Required

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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.

Additional properties are allowed.

uuid string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

alias_purpose string

Values are savedObjectConversion or savedObjectImport.

alias_target_id string

author array[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 Required

The rule’s description.

Minimum length is 1.

enabled boolean Required

Determines whether the rule is enabled. Defaults to true.

exceptions_list array[object] Required

Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.

Hide exceptions_list attributes Show exceptions_list attributes object

id string(nonempty) Required

ID of the exception container

Minimum length is 1.

list_id string(nonempty) Required

List ID of the exception container

Minimum length is 1.

namespace_type string Required

Determines the exceptions validity in rule's Kibana space

Values are agnostic or single.

type string Required

The exception type

Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.

false_positives array[string] Required

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.

from string(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.

Hide investigation_fields attribute Show investigation_fields attribute object

field_names array[string(nonempty)] Required

A string that does not contain only whitespace characters

At least 1 element. Minimum length of each is 1.

license string

The rule's license.

max_signals integer Required

Maximum number of alerts the rule can create during a single run (the rule’s Max alerts per run advanced setting value).

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.

Minimum value is 1. Default value is 100.

meta object

Placeholder for metadata about the rule.

This field is overwritten when you save changes to the rule’s settings.

Additional properties are allowed.

name string Required

A human-readable name for the rule.

Minimum length is 1.

namespace string

Has no effect.

note string

Notes to help investigate alerts produced by the rule.

outcome string

Values are exactMatch, aliasMatch, or conflict.

output_index string Deprecated

(deprecated) Has no effect.

references array[string] Required

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.

related_integrations array[object] Required

Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:

package: name of the package (required, unique id)

version: version of the package (required, semver-compatible)

integration: name of the integration of this package (optional, id within the package)

There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.

Hide related_integrations attributes Show related_integrations attributes object

integration string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

package string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

version string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

required_fields array[object] Required

Elasticsearch fields and their types that need to be present for the rule to function.

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.

Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.

Hide required_fields attributes Show required_fields attributes object

name string(nonempty) Required

Name of an Elasticsearch field

Minimum length is 1.

type string(nonempty) Required

Type of the Elasticsearch field

Minimum length is 1.

response_actions array[object]

One of:
Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object

Hide attributes Show attributes

action_type_id string Required

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

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

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[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.

Hide attributes Show attributes

action_type_id string Required

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object

Hide attributes Show attributes

command string Required

Value is isolate.

comment string

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.

risk_score integer 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

Minimum value is 0, maximum value is 100.

risk_score_mapping array[object] Required

Overrides generated alerts' risk_score with a value from the source event

Hide risk_score_mapping attributes Show risk_score_mapping attributes object

field string Required

Source event field used to override the default risk_score.

operator string Required

Value is equals.

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

Minimum value is 0, maximum value is 100.

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 string 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 are low, medium, high, or critical.

severity_mapping array[object] Required

Overrides generated alerts' severity with values from the source event

Hide severity_mapping attributes Show severity_mapping attributes object

field string Required

Source event field used to override the default severity.

operator string Required

Value is equals.

severity string 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 are low, medium, high, or critical.

value string Required

tags array[string] Required

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.

threat array[object] Required

Currently, only threats described using the MITRE ATT&CK™ framework are supported.

Hide threat attributes Show threat attributes object

framework string Required

Relevant attack framework

tactic object Required

Object containing information on the attack type

Hide tactic attributes Show tactic attributes object

id string Required

Tactic ID

name string Required

Tactic name

reference string Required

Tactic reference

technique array[object]

Array containing information on the attack techniques (optional)

Hide technique attributes Show technique attributes object

id string Required

Technique ID

name string Required

Technique name

reference string Required

Technique reference

subtechnique array[object]

Array containing more specific information on the attack technique.

Hide subtechnique attributes Show subtechnique attributes object

id string Required

Subtechnique ID

name string Required

Subtechnique name

reference string Required

Subtechnique reference

throttle string | null

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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 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.

It is not incremented on each update. Compare this to the revision field.

Minimum value is 1.

created_at string(date-time) Required

created_by string Required

execution_summary object

Summary of the last execution of a rule.

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

Hide execution_summary attribute Show execution_summary attribute object

last_execution object Required

Hide last_execution attributes Show last_execution attributes object

date string(date-time) Required

Date of the last execution

message string Required

metrics object Required

Hide metrics attributes Show metrics attributes object

execution_gap_duration_s integer

Duration in seconds of execution gap

Minimum value is 0.

frozen_indices_queried_count integer

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

Minimum value is 0.

gap_range object

Range of the execution gap

Hide gap_range attributes Show gap_range attributes object

gte string Required

Start date of the execution gap

lte string Required

End date of the execution gap

total_enrichment_duration_ms integer

Total time spent enriching documents during current rule execution cycle

Minimum value is 0.

total_indexing_duration_ms integer

Total time spent indexing documents during current rule execution cycle

Minimum value is 0.

total_search_duration_ms integer

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

Minimum value is 0.

status string Required

Status of the last execution

Values are going to run, running, partial failure, failed, or succeeded.

status_order integer Required

id string(uuid) Required

A dynamic unique identifier for the rule object. It is randomly generated when a rule is created and cannot be changed after that. It is always a UUID. It is unique within a given Kibana space. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have different object ids.

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

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.

Minimum value is 0.

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 object 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:
Security_Detections_API_ExternalRuleSource object Security_Detections_API_InternalRuleSource object

Type of rule source for externally sourced rules, i.e. rules that have an external source, such as the Elastic Prebuilt rules repo.

Hide attributes Show attributes

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

type string Required Discriminator

Value is external.

updated_at string(date-time) Required

updated_by string Required

history_window_start string(nonempty) Required

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.

Minimum length is 1.

new_terms_fields array[string] Required

Fields to monitor for new values.

At least 1 but not more than 3 elements.

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.

type string Required Discriminator

Rule type

Value is new_terms.

alert_suppression object

Defines alert suppression configuration.

Hide alert_suppression attributes Show alert_suppression attributes object

duration object

Hide duration attributes Show duration attributes object

unit string Required

Time unit

Values are s, m, or h.

value integer Required

Minimum value is 1.

group_by array[string] Required

At least 1 but not more than 3 elements.

missing_fields_strategy string

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 are doNotSuppress or suppress.

data_view_id string

filters array

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

language string Required

Values are kuery or lucene.

Hide attributes Show attributes

actions array[object] Required

Array defining the automated actions (notifications) taken when alerts are generated.

Hide actions attributes Show actions attributes object

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.

Additional properties are allowed.

frequency object

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

Hide frequency attributes Show frequency attributes object

notifyWhen string Required

Defines how often rules run actions.

Values are onActiveAlert, onThrottleInterval, or 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 string | null Required

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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.

Additional properties are allowed.

uuid string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

alias_purpose string

Values are savedObjectConversion or savedObjectImport.

alias_target_id string

author array[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 Required

The rule’s description.

Minimum length is 1.

enabled boolean Required

Determines whether the rule is enabled. Defaults to true.

exceptions_list array[object] Required

Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.

Hide exceptions_list attributes Show exceptions_list attributes object

id string(nonempty) Required

ID of the exception container

Minimum length is 1.

list_id string(nonempty) Required

List ID of the exception container

Minimum length is 1.

namespace_type string Required

Determines the exceptions validity in rule's Kibana space

Values are agnostic or single.

type string Required

The exception type

Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.

false_positives array[string] Required

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.

from string(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.

Hide investigation_fields attribute Show investigation_fields attribute object

field_names array[string(nonempty)] Required

A string that does not contain only whitespace characters

At least 1 element. Minimum length of each is 1.

license string

The rule's license.

max_signals integer Required

Maximum number of alerts the rule can create during a single run (the rule’s Max alerts per run advanced setting value).

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.

Minimum value is 1. Default value is 100.

meta object

Placeholder for metadata about the rule.

This field is overwritten when you save changes to the rule’s settings.

Additional properties are allowed.

name string Required

A human-readable name for the rule.

Minimum length is 1.

namespace string

Has no effect.

note string

Notes to help investigate alerts produced by the rule.

outcome string

Values are exactMatch, aliasMatch, or conflict.

output_index string Deprecated

(deprecated) Has no effect.

references array[string] Required

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.

related_integrations array[object] Required

Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:

package: name of the package (required, unique id)

version: version of the package (required, semver-compatible)

integration: name of the integration of this package (optional, id within the package)

There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.

Hide related_integrations attributes Show related_integrations attributes object

integration string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

package string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

version string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

required_fields array[object] Required

Elasticsearch fields and their types that need to be present for the rule to function.

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.

Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.

Hide required_fields attributes Show required_fields attributes object

name string(nonempty) Required

Name of an Elasticsearch field

Minimum length is 1.

type string(nonempty) Required

Type of the Elasticsearch field

Minimum length is 1.

response_actions array[object]

One of:
Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object

Hide attributes Show attributes

action_type_id string Required

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

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

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[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.

Hide attributes Show attributes

action_type_id string Required

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object

Hide attributes Show attributes

command string Required

Value is isolate.

comment string

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.

risk_score integer 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

Minimum value is 0, maximum value is 100.

risk_score_mapping array[object] Required

Overrides generated alerts' risk_score with a value from the source event

Hide risk_score_mapping attributes Show risk_score_mapping attributes object

field string Required

Source event field used to override the default risk_score.

operator string Required

Value is equals.

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

Minimum value is 0, maximum value is 100.

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 string 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 are low, medium, high, or critical.

severity_mapping array[object] Required

Overrides generated alerts' severity with values from the source event

Hide severity_mapping attributes Show severity_mapping attributes object

field string Required

Source event field used to override the default severity.

operator string Required

Value is equals.

severity string 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 are low, medium, high, or critical.

value string Required

tags array[string] Required

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.

threat array[object] Required

Currently, only threats described using the MITRE ATT&CK™ framework are supported.

Hide threat attributes Show threat attributes object

framework string Required

Relevant attack framework

tactic object Required

Object containing information on the attack type

Hide tactic attributes Show tactic attributes object

id string Required

Tactic ID

name string Required

Tactic name

reference string Required

Tactic reference

technique array[object]

Array containing information on the attack techniques (optional)

Hide technique attributes Show technique attributes object

id string Required

Technique ID

name string Required

Technique name

reference string Required

Technique reference

subtechnique array[object]

Array containing more specific information on the attack technique.

Hide subtechnique attributes Show subtechnique attributes object

id string Required

Subtechnique ID

name string Required

Subtechnique name

reference string Required

Subtechnique reference

throttle string | null

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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 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.

It is not incremented on each update. Compare this to the revision field.

Minimum value is 1.

created_at string(date-time) Required

created_by string Required

execution_summary object

Summary of the last execution of a rule.

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

Hide execution_summary attribute Show execution_summary attribute object

last_execution object Required

Hide last_execution attributes Show last_execution attributes object

date string(date-time) Required

Date of the last execution

message string Required

metrics object Required

Hide metrics attributes Show metrics attributes object

execution_gap_duration_s integer

Duration in seconds of execution gap

Minimum value is 0.

frozen_indices_queried_count integer

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

Minimum value is 0.

gap_range object

Range of the execution gap

Hide gap_range attributes Show gap_range attributes object

gte string Required

Start date of the execution gap

lte string Required

End date of the execution gap

total_enrichment_duration_ms integer

Total time spent enriching documents during current rule execution cycle

Minimum value is 0.

total_indexing_duration_ms integer

Total time spent indexing documents during current rule execution cycle

Minimum value is 0.

total_search_duration_ms integer

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

Minimum value is 0.

status string Required

Status of the last execution

Values are going to run, running, partial failure, failed, or succeeded.

status_order integer Required

id string(uuid) Required

A dynamic unique identifier for the rule object. It is randomly generated when a rule is created and cannot be changed after that. It is always a UUID. It is unique within a given Kibana space. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have different object ids.

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

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.

Minimum value is 0.

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 object 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:
Security_Detections_API_ExternalRuleSource object Security_Detections_API_InternalRuleSource object

Type of rule source for externally sourced rules, i.e. rules that have an external source, such as the Elastic Prebuilt rules repo.

Hide attributes Show attributes

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

type string Required Discriminator

Value is external.

updated_at string(date-time) Required

updated_by string Required

alert_suppression object

Defines alert suppression configuration.

Hide alert_suppression attributes Show alert_suppression attributes object

duration object

Hide duration attributes Show duration attributes object

unit string Required

Time unit

Values are s, m, or h.

value integer Required

Minimum value is 1.

group_by array[string] Required

At least 1 but not more than 3 elements.

missing_fields_strategy string

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 are doNotSuppress or suppress.

language string Required

Value is esql.

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.

type string Required Discriminator

Rule type

Value is esql.

deleted array[object] Required

Any of:
Security_Detections_API_EqlRuleResponseFields object Security_Detections_API_QueryRuleResponseFields object Security_Detections_API_SavedQueryRuleResponseFields object Security_Detections_API_ThresholdRuleResponseFields object Security_Detections_API_ThreatMatchRuleResponseFields object Security_Detections_API_MachineLearningRuleResponseFields object Security_Detections_API_NewTermsRuleResponseFields object Security_Detections_API_EsqlRuleResponseFields object

Hide attributes Show attributes

actions array[object] Required

Array defining the automated actions (notifications) taken when alerts are generated.

Hide actions attributes Show actions attributes object

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.

Additional properties are allowed.

frequency object

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

Hide frequency attributes Show frequency attributes object

notifyWhen string Required

Defines how often rules run actions.

Values are onActiveAlert, onThrottleInterval, or 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 string | null Required

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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.

Additional properties are allowed.

uuid string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

alias_purpose string

Values are savedObjectConversion or savedObjectImport.

alias_target_id string

author array[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 Required

The rule’s description.

Minimum length is 1.

enabled boolean Required

Determines whether the rule is enabled. Defaults to true.

exceptions_list array[object] Required

Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.

Hide exceptions_list attributes Show exceptions_list attributes object

id string(nonempty) Required

ID of the exception container

Minimum length is 1.

list_id string(nonempty) Required

List ID of the exception container

Minimum length is 1.

namespace_type string Required

Determines the exceptions validity in rule's Kibana space

Values are agnostic or single.

type string Required

The exception type

Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.

false_positives array[string] Required

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.

from string(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.

Hide investigation_fields attribute Show investigation_fields attribute object

field_names array[string(nonempty)] Required

A string that does not contain only whitespace characters

At least 1 element. Minimum length of each is 1.

license string

The rule's license.

max_signals integer Required

Maximum number of alerts the rule can create during a single run (the rule’s Max alerts per run advanced setting value).

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.

Minimum value is 1. Default value is 100.

meta object

Placeholder for metadata about the rule.

This field is overwritten when you save changes to the rule’s settings.

Additional properties are allowed.

name string Required

A human-readable name for the rule.

Minimum length is 1.

namespace string

Has no effect.

note string

Notes to help investigate alerts produced by the rule.

outcome string

Values are exactMatch, aliasMatch, or conflict.

output_index string Deprecated

(deprecated) Has no effect.

references array[string] Required

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.

related_integrations array[object] Required

Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:

package: name of the package (required, unique id)

version: version of the package (required, semver-compatible)

integration: name of the integration of this package (optional, id within the package)

There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.

Hide related_integrations attributes Show related_integrations attributes object

integration string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

package string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

version string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

required_fields array[object] Required

Elasticsearch fields and their types that need to be present for the rule to function.

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.

Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.

Hide required_fields attributes Show required_fields attributes object

name string(nonempty) Required

Name of an Elasticsearch field

Minimum length is 1.

type string(nonempty) Required

Type of the Elasticsearch field

Minimum length is 1.

response_actions array[object]

One of:
Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object

Hide attributes Show attributes

action_type_id string Required

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

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

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[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.

Hide attributes Show attributes

action_type_id string Required

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object

Hide attributes Show attributes

command string Required

Value is isolate.

comment string

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.

risk_score integer 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

Minimum value is 0, maximum value is 100.

risk_score_mapping array[object] Required

Overrides generated alerts' risk_score with a value from the source event

Hide risk_score_mapping attributes Show risk_score_mapping attributes object

field string Required

Source event field used to override the default risk_score.

operator string Required

Value is equals.

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

Minimum value is 0, maximum value is 100.

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 string 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 are low, medium, high, or critical.

severity_mapping array[object] Required

Overrides generated alerts' severity with values from the source event

Hide severity_mapping attributes Show severity_mapping attributes object

field string Required

Source event field used to override the default severity.

operator string Required

Value is equals.

severity string 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 are low, medium, high, or critical.

value string Required

tags array[string] Required

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.

threat array[object] Required

Currently, only threats described using the MITRE ATT&CK™ framework are supported.

Hide threat attributes Show threat attributes object

framework string Required

Relevant attack framework

tactic object Required

Object containing information on the attack type

Hide tactic attributes Show tactic attributes object

id string Required

Tactic ID

name string Required

Tactic name

reference string Required

Tactic reference

technique array[object]

Array containing information on the attack techniques (optional)

Hide technique attributes Show technique attributes object

id string Required

Technique ID

name string Required

Technique name

reference string Required

Technique reference

subtechnique array[object]

Array containing more specific information on the attack technique.

Hide subtechnique attributes Show subtechnique attributes object

id string Required

Subtechnique ID

name string Required

Subtechnique name

reference string Required

Subtechnique reference

throttle string | null

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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 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.

It is not incremented on each update. Compare this to the revision field.

Minimum value is 1.

created_at string(date-time) Required

created_by string Required

execution_summary object

Summary of the last execution of a rule.

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

Hide execution_summary attribute Show execution_summary attribute object

last_execution object Required

Hide last_execution attributes Show last_execution attributes object

date string(date-time) Required

Date of the last execution

message string Required

metrics object Required

Hide metrics attributes Show metrics attributes object

execution_gap_duration_s integer

Duration in seconds of execution gap

Minimum value is 0.

frozen_indices_queried_count integer

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

Minimum value is 0.

gap_range object

Range of the execution gap

Hide gap_range attributes Show gap_range attributes object

gte string Required

Start date of the execution gap

lte string Required

End date of the execution gap

total_enrichment_duration_ms integer

Total time spent enriching documents during current rule execution cycle

Minimum value is 0.

total_indexing_duration_ms integer

Total time spent indexing documents during current rule execution cycle

Minimum value is 0.

total_search_duration_ms integer

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

Minimum value is 0.

status string Required

Status of the last execution

Values are going to run, running, partial failure, failed, or succeeded.

status_order integer Required

id string(uuid) Required

A dynamic unique identifier for the rule object. It is randomly generated when a rule is created and cannot be changed after that. It is always a UUID. It is unique within a given Kibana space. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have different object ids.

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

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.

Minimum value is 0.

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 object 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:
Security_Detections_API_ExternalRuleSource object Security_Detections_API_InternalRuleSource object

Type of rule source for externally sourced rules, i.e. rules that have an external source, such as the Elastic Prebuilt rules repo.

Hide attributes Show attributes

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

type string Required Discriminator

Value is external.

updated_at string(date-time) Required

updated_by string Required

language string Required

Query language to use

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

type string Required Discriminator

Rule type

Value is eql.

alert_suppression object

Defines alert suppression configuration.

Hide alert_suppression attributes Show alert_suppression attributes object

duration object

Hide duration attributes Show duration attributes object

unit string Required

Time unit

Values are s, m, or h.

value integer Required

Minimum value is 1.

group_by array[string] Required

At least 1 but not more than 3 elements.

missing_fields_strategy string

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 are doNotSuppress or suppress.

data_view_id string

event_category_override string

filters array

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

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.

Hide attributes Show attributes

actions array[object] Required

Array defining the automated actions (notifications) taken when alerts are generated.

Hide actions attributes Show actions attributes object

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.

Additional properties are allowed.

frequency object

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

Hide frequency attributes Show frequency attributes object

notifyWhen string Required

Defines how often rules run actions.

Values are onActiveAlert, onThrottleInterval, or 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 string | null Required

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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.

Additional properties are allowed.

uuid string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

alias_purpose string

Values are savedObjectConversion or savedObjectImport.

alias_target_id string

author array[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 Required

The rule’s description.

Minimum length is 1.

enabled boolean Required

Determines whether the rule is enabled. Defaults to true.

exceptions_list array[object] Required

Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.

Hide exceptions_list attributes Show exceptions_list attributes object

id string(nonempty) Required

ID of the exception container

Minimum length is 1.

list_id string(nonempty) Required

List ID of the exception container

Minimum length is 1.

namespace_type string Required

Determines the exceptions validity in rule's Kibana space

Values are agnostic or single.

type string Required

The exception type

Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.

false_positives array[string] Required

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.

from string(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.

Hide investigation_fields attribute Show investigation_fields attribute object

field_names array[string(nonempty)] Required

A string that does not contain only whitespace characters

At least 1 element. Minimum length of each is 1.

license string

The rule's license.

max_signals integer Required

Maximum number of alerts the rule can create during a single run (the rule’s Max alerts per run advanced setting value).

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.

Minimum value is 1. Default value is 100.

meta object

Placeholder for metadata about the rule.

This field is overwritten when you save changes to the rule’s settings.

Additional properties are allowed.

name string Required

A human-readable name for the rule.

Minimum length is 1.

namespace string

Has no effect.

note string

Notes to help investigate alerts produced by the rule.

outcome string

Values are exactMatch, aliasMatch, or conflict.

output_index string Deprecated

(deprecated) Has no effect.

references array[string] Required

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.

related_integrations array[object] Required

Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:

package: name of the package (required, unique id)

version: version of the package (required, semver-compatible)

integration: name of the integration of this package (optional, id within the package)

There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.

Hide related_integrations attributes Show related_integrations attributes object

integration string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

package string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

version string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

required_fields array[object] Required

Elasticsearch fields and their types that need to be present for the rule to function.

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.

Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.

Hide required_fields attributes Show required_fields attributes object

name string(nonempty) Required

Name of an Elasticsearch field

Minimum length is 1.

type string(nonempty) Required

Type of the Elasticsearch field

Minimum length is 1.

response_actions array[object]

One of:
Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object

Hide attributes Show attributes

action_type_id string Required

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

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

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[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.

Hide attributes Show attributes

action_type_id string Required

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object

Hide attributes Show attributes

command string Required

Value is isolate.

comment string

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.

risk_score integer 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

Minimum value is 0, maximum value is 100.

risk_score_mapping array[object] Required

Overrides generated alerts' risk_score with a value from the source event

Hide risk_score_mapping attributes Show risk_score_mapping attributes object

field string Required

Source event field used to override the default risk_score.

operator string Required

Value is equals.

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

Minimum value is 0, maximum value is 100.

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 string 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 are low, medium, high, or critical.

severity_mapping array[object] Required

Overrides generated alerts' severity with values from the source event

Hide severity_mapping attributes Show severity_mapping attributes object

field string Required

Source event field used to override the default severity.

operator string Required

Value is equals.

severity string 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 are low, medium, high, or critical.

value string Required

tags array[string] Required

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.

threat array[object] Required

Currently, only threats described using the MITRE ATT&CK™ framework are supported.

Hide threat attributes Show threat attributes object

framework string Required

Relevant attack framework

tactic object Required

Object containing information on the attack type

Hide tactic attributes Show tactic attributes object

id string Required

Tactic ID

name string Required

Tactic name

reference string Required

Tactic reference

technique array[object]

Array containing information on the attack techniques (optional)

Hide technique attributes Show technique attributes object

id string Required

Technique ID

name string Required

Technique name

reference string Required

Technique reference

subtechnique array[object]

Array containing more specific information on the attack technique.

Hide subtechnique attributes Show subtechnique attributes object

id string Required

Subtechnique ID

name string Required

Subtechnique name

reference string Required

Subtechnique reference

throttle string | null

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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 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.

It is not incremented on each update. Compare this to the revision field.

Minimum value is 1.

created_at string(date-time) Required

created_by string Required

execution_summary object

Summary of the last execution of a rule.

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

Hide execution_summary attribute Show execution_summary attribute object

last_execution object Required

Hide last_execution attributes Show last_execution attributes object

date string(date-time) Required

Date of the last execution

message string Required

metrics object Required

Hide metrics attributes Show metrics attributes object

execution_gap_duration_s integer

Duration in seconds of execution gap

Minimum value is 0.

frozen_indices_queried_count integer

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

Minimum value is 0.

gap_range object

Range of the execution gap

Hide gap_range attributes Show gap_range attributes object

gte string Required

Start date of the execution gap

lte string Required

End date of the execution gap

total_enrichment_duration_ms integer

Total time spent enriching documents during current rule execution cycle

Minimum value is 0.

total_indexing_duration_ms integer

Total time spent indexing documents during current rule execution cycle

Minimum value is 0.

total_search_duration_ms integer

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

Minimum value is 0.

status string Required

Status of the last execution

Values are going to run, running, partial failure, failed, or succeeded.

status_order integer Required

id string(uuid) Required

A dynamic unique identifier for the rule object. It is randomly generated when a rule is created and cannot be changed after that. It is always a UUID. It is unique within a given Kibana space. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have different object ids.

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

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.

Minimum value is 0.

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 object 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:
Security_Detections_API_ExternalRuleSource object Security_Detections_API_InternalRuleSource object

Type of rule source for externally sourced rules, i.e. rules that have an external source, such as the Elastic Prebuilt rules repo.

Hide attributes Show attributes

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

type string Required Discriminator

Value is external.

updated_at string(date-time) Required

updated_by string Required

type string Required Discriminator

Rule type

Value is query.

alert_suppression object

Defines alert suppression configuration.

Hide alert_suppression attributes Show alert_suppression attributes object

duration object

Hide duration attributes Show duration attributes object

unit string Required

Time unit

Values are s, m, or h.

value integer Required

Minimum value is 1.

group_by array[string] Required

At least 1 but not more than 3 elements.

missing_fields_strategy string

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 are doNotSuppress or suppress.

data_view_id string

filters array

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

saved_id string

Kibana saved search used by the rule to create alerts.

language string Required

Values are kuery or lucene.

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.

Hide attributes Show attributes

actions array[object] Required

Array defining the automated actions (notifications) taken when alerts are generated.

Hide actions attributes Show actions attributes object

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.

Additional properties are allowed.

frequency object

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

Hide frequency attributes Show frequency attributes object

notifyWhen string Required

Defines how often rules run actions.

Values are onActiveAlert, onThrottleInterval, or 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 string | null Required

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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.

Additional properties are allowed.

uuid string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

alias_purpose string

Values are savedObjectConversion or savedObjectImport.

alias_target_id string

author array[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 Required

The rule’s description.

Minimum length is 1.

enabled boolean Required

Determines whether the rule is enabled. Defaults to true.

exceptions_list array[object] Required

Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.

Hide exceptions_list attributes Show exceptions_list attributes object

id string(nonempty) Required

ID of the exception container

Minimum length is 1.

list_id string(nonempty) Required

List ID of the exception container

Minimum length is 1.

namespace_type string Required

Determines the exceptions validity in rule's Kibana space

Values are agnostic or single.

type string Required

The exception type

Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.

false_positives array[string] Required

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.

from string(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.

Hide investigation_fields attribute Show investigation_fields attribute object

field_names array[string(nonempty)] Required

A string that does not contain only whitespace characters

At least 1 element. Minimum length of each is 1.

license string

The rule's license.

max_signals integer Required

Maximum number of alerts the rule can create during a single run (the rule’s Max alerts per run advanced setting value).

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.

Minimum value is 1. Default value is 100.

meta object

Placeholder for metadata about the rule.

This field is overwritten when you save changes to the rule’s settings.

Additional properties are allowed.

name string Required

A human-readable name for the rule.

Minimum length is 1.

namespace string

Has no effect.

note string

Notes to help investigate alerts produced by the rule.

outcome string

Values are exactMatch, aliasMatch, or conflict.

output_index string Deprecated

(deprecated) Has no effect.

references array[string] Required

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.

related_integrations array[object] Required

Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:

package: name of the package (required, unique id)

version: version of the package (required, semver-compatible)

integration: name of the integration of this package (optional, id within the package)

There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.

Hide related_integrations attributes Show related_integrations attributes object

integration string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

package string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

version string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

required_fields array[object] Required

Elasticsearch fields and their types that need to be present for the rule to function.

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.

Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.

Hide required_fields attributes Show required_fields attributes object

name string(nonempty) Required

Name of an Elasticsearch field

Minimum length is 1.

type string(nonempty) Required

Type of the Elasticsearch field

Minimum length is 1.

response_actions array[object]

One of:
Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object

Hide attributes Show attributes

action_type_id string Required

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

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

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[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.

Hide attributes Show attributes

action_type_id string Required

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object

Hide attributes Show attributes

command string Required

Value is isolate.

comment string

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.

risk_score integer 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

Minimum value is 0, maximum value is 100.

risk_score_mapping array[object] Required

Overrides generated alerts' risk_score with a value from the source event

Hide risk_score_mapping attributes Show risk_score_mapping attributes object

field string Required

Source event field used to override the default risk_score.

operator string Required

Value is equals.

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

Minimum value is 0, maximum value is 100.

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 string 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 are low, medium, high, or critical.

severity_mapping array[object] Required

Overrides generated alerts' severity with values from the source event

Hide severity_mapping attributes Show severity_mapping attributes object

field string Required

Source event field used to override the default severity.

operator string Required

Value is equals.

severity string 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 are low, medium, high, or critical.

value string Required

tags array[string] Required

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.

threat array[object] Required

Currently, only threats described using the MITRE ATT&CK™ framework are supported.

Hide threat attributes Show threat attributes object

framework string Required

Relevant attack framework

tactic object Required

Object containing information on the attack type

Hide tactic attributes Show tactic attributes object

id string Required

Tactic ID

name string Required

Tactic name

reference string Required

Tactic reference

technique array[object]

Array containing information on the attack techniques (optional)

Hide technique attributes Show technique attributes object

id string Required

Technique ID

name string Required

Technique name

reference string Required

Technique reference

subtechnique array[object]

Array containing more specific information on the attack technique.

Hide subtechnique attributes Show subtechnique attributes object

id string Required

Subtechnique ID

name string Required

Subtechnique name

reference string Required

Subtechnique reference

throttle string | null

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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 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.

It is not incremented on each update. Compare this to the revision field.

Minimum value is 1.

created_at string(date-time) Required

created_by string Required

execution_summary object

Summary of the last execution of a rule.

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

Hide execution_summary attribute Show execution_summary attribute object

last_execution object Required

Hide last_execution attributes Show last_execution attributes object

date string(date-time) Required

Date of the last execution

message string Required

metrics object Required

Hide metrics attributes Show metrics attributes object

execution_gap_duration_s integer

Duration in seconds of execution gap

Minimum value is 0.

frozen_indices_queried_count integer

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

Minimum value is 0.

gap_range object

Range of the execution gap

Hide gap_range attributes Show gap_range attributes object

gte string Required

Start date of the execution gap

lte string Required

End date of the execution gap

total_enrichment_duration_ms integer

Total time spent enriching documents during current rule execution cycle

Minimum value is 0.

total_indexing_duration_ms integer

Total time spent indexing documents during current rule execution cycle

Minimum value is 0.

total_search_duration_ms integer

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

Minimum value is 0.

status string Required

Status of the last execution

Values are going to run, running, partial failure, failed, or succeeded.

status_order integer Required

id string(uuid) Required

A dynamic unique identifier for the rule object. It is randomly generated when a rule is created and cannot be changed after that. It is always a UUID. It is unique within a given Kibana space. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have different object ids.

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

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.

Minimum value is 0.

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 object 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:
Security_Detections_API_ExternalRuleSource object Security_Detections_API_InternalRuleSource object

Type of rule source for externally sourced rules, i.e. rules that have an external source, such as the Elastic Prebuilt rules repo.

Hide attributes Show attributes

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

type string Required Discriminator

Value is external.

updated_at string(date-time) Required

updated_by string Required

saved_id string Required

Kibana saved search used by the rule to create alerts.

type string Required Discriminator

Rule type

Value is saved_query.

alert_suppression object

Defines alert suppression configuration.

Hide alert_suppression attributes Show alert_suppression attributes object

duration object

Hide duration attributes Show duration attributes object

unit string Required

Time unit

Values are s, m, or h.

value integer Required

Minimum value is 1.

group_by array[string] Required

At least 1 but not more than 3 elements.

missing_fields_strategy string

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 are doNotSuppress or suppress.

data_view_id string

filters array

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

query string

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.

language string Required

Values are kuery or lucene.

Hide attributes Show attributes

actions array[object] Required

Array defining the automated actions (notifications) taken when alerts are generated.

Hide actions attributes Show actions attributes object

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.

Additional properties are allowed.

frequency object

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

Hide frequency attributes Show frequency attributes object

notifyWhen string Required

Defines how often rules run actions.

Values are onActiveAlert, onThrottleInterval, or 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 string | null Required

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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.

Additional properties are allowed.

uuid string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

alias_purpose string

Values are savedObjectConversion or savedObjectImport.

alias_target_id string

author array[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 Required

The rule’s description.

Minimum length is 1.

enabled boolean Required

Determines whether the rule is enabled. Defaults to true.

exceptions_list array[object] Required

Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.

Hide exceptions_list attributes Show exceptions_list attributes object

id string(nonempty) Required

ID of the exception container

Minimum length is 1.

list_id string(nonempty) Required

List ID of the exception container

Minimum length is 1.

namespace_type string Required

Determines the exceptions validity in rule's Kibana space

Values are agnostic or single.

type string Required

The exception type

Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.

false_positives array[string] Required

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.

from string(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.

Hide investigation_fields attribute Show investigation_fields attribute object

field_names array[string(nonempty)] Required

A string that does not contain only whitespace characters

At least 1 element. Minimum length of each is 1.

license string

The rule's license.

max_signals integer Required

Maximum number of alerts the rule can create during a single run (the rule’s Max alerts per run advanced setting value).

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.

Minimum value is 1. Default value is 100.

meta object

Placeholder for metadata about the rule.

This field is overwritten when you save changes to the rule’s settings.

Additional properties are allowed.

name string Required

A human-readable name for the rule.

Minimum length is 1.

namespace string

Has no effect.

note string

Notes to help investigate alerts produced by the rule.

outcome string

Values are exactMatch, aliasMatch, or conflict.

output_index string Deprecated

(deprecated) Has no effect.

references array[string] Required

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.

related_integrations array[object] Required

Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:

package: name of the package (required, unique id)

version: version of the package (required, semver-compatible)

integration: name of the integration of this package (optional, id within the package)

There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.

Hide related_integrations attributes Show related_integrations attributes object

integration string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

package string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

version string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

required_fields array[object] Required

Elasticsearch fields and their types that need to be present for the rule to function.

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.

Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.

Hide required_fields attributes Show required_fields attributes object

name string(nonempty) Required

Name of an Elasticsearch field

Minimum length is 1.

type string(nonempty) Required

Type of the Elasticsearch field

Minimum length is 1.

response_actions array[object]

One of:
Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object

Hide attributes Show attributes

action_type_id string Required

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

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

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[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.

Hide attributes Show attributes

action_type_id string Required

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object

Hide attributes Show attributes

command string Required

Value is isolate.

comment string

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.

risk_score integer 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

Minimum value is 0, maximum value is 100.

risk_score_mapping array[object] Required

Overrides generated alerts' risk_score with a value from the source event

Hide risk_score_mapping attributes Show risk_score_mapping attributes object

field string Required

Source event field used to override the default risk_score.

operator string Required

Value is equals.

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

Minimum value is 0, maximum value is 100.

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 string 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 are low, medium, high, or critical.

severity_mapping array[object] Required

Overrides generated alerts' severity with values from the source event

Hide severity_mapping attributes Show severity_mapping attributes object

field string Required

Source event field used to override the default severity.

operator string Required

Value is equals.

severity string 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 are low, medium, high, or critical.

value string Required

tags array[string] Required

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.

threat array[object] Required

Currently, only threats described using the MITRE ATT&CK™ framework are supported.

Hide threat attributes Show threat attributes object

framework string Required

Relevant attack framework

tactic object Required

Object containing information on the attack type

Hide tactic attributes Show tactic attributes object

id string Required

Tactic ID

name string Required

Tactic name

reference string Required

Tactic reference

technique array[object]

Array containing information on the attack techniques (optional)

Hide technique attributes Show technique attributes object

id string Required

Technique ID

name string Required

Technique name

reference string Required

Technique reference

subtechnique array[object]

Array containing more specific information on the attack technique.

Hide subtechnique attributes Show subtechnique attributes object

id string Required

Subtechnique ID

name string Required

Subtechnique name

reference string Required

Subtechnique reference

throttle string | null

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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 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.

It is not incremented on each update. Compare this to the revision field.

Minimum value is 1.

created_at string(date-time) Required

created_by string Required

execution_summary object

Summary of the last execution of a rule.

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

Hide execution_summary attribute Show execution_summary attribute object

last_execution object Required

Hide last_execution attributes Show last_execution attributes object

date string(date-time) Required

Date of the last execution

message string Required

metrics object Required

Hide metrics attributes Show metrics attributes object

execution_gap_duration_s integer

Duration in seconds of execution gap

Minimum value is 0.

frozen_indices_queried_count integer

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

Minimum value is 0.

gap_range object

Range of the execution gap

Hide gap_range attributes Show gap_range attributes object

gte string Required

Start date of the execution gap

lte string Required

End date of the execution gap

total_enrichment_duration_ms integer

Total time spent enriching documents during current rule execution cycle

Minimum value is 0.

total_indexing_duration_ms integer

Total time spent indexing documents during current rule execution cycle

Minimum value is 0.

total_search_duration_ms integer

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

Minimum value is 0.

status string Required

Status of the last execution

Values are going to run, running, partial failure, failed, or succeeded.

status_order integer Required

id string(uuid) Required

A dynamic unique identifier for the rule object. It is randomly generated when a rule is created and cannot be changed after that. It is always a UUID. It is unique within a given Kibana space. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have different object ids.

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

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.

Minimum value is 0.

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 object 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:
Security_Detections_API_ExternalRuleSource object Security_Detections_API_InternalRuleSource object

Type of rule source for externally sourced rules, i.e. rules that have an external source, such as the Elastic Prebuilt rules repo.

Hide attributes Show attributes

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

type string Required Discriminator

Value is external.

updated_at string(date-time) Required

updated_by string Required

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.

threshold object Required

Hide threshold attributes Show threshold attributes object

cardinality array[object]

The field on which the cardinality is applied.

Hide cardinality attributes Show cardinality attributes object

field string Required

The field on which to calculate and compare the cardinality.

value integer Required

The threshold value from which an alert is generated based on unique number of values of cardinality.field.

Minimum value is 0.

field string | array[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.

One of:
string-1 string array-2 array[string]

value integer Required

The threshold value from which an alert is generated.

Minimum value is 1.

type string Required Discriminator

Rule type

Value is threshold.

alert_suppression object

Defines alert suppression configuration.

Hide alert_suppression attribute Show alert_suppression attribute object

duration object Required

Hide duration attributes Show duration attributes object

unit string Required

Time unit

Values are s, m, or h.

value integer Required

Minimum value is 1.

data_view_id string

filters array

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

saved_id string

Kibana saved search used by the rule to create alerts.

language string Required

Values are kuery or lucene.

Hide attributes Show attributes

actions array[object] Required

Array defining the automated actions (notifications) taken when alerts are generated.

Hide actions attributes Show actions attributes object

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.

Additional properties are allowed.

frequency object

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

Hide frequency attributes Show frequency attributes object

notifyWhen string Required

Defines how often rules run actions.

Values are onActiveAlert, onThrottleInterval, or 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 string | null Required

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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.

Additional properties are allowed.

uuid string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

alias_purpose string

Values are savedObjectConversion or savedObjectImport.

alias_target_id string

author array[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 Required

The rule’s description.

Minimum length is 1.

enabled boolean Required

Determines whether the rule is enabled. Defaults to true.

exceptions_list array[object] Required

Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.

Hide exceptions_list attributes Show exceptions_list attributes object

id string(nonempty) Required

ID of the exception container

Minimum length is 1.

list_id string(nonempty) Required

List ID of the exception container

Minimum length is 1.

namespace_type string Required

Determines the exceptions validity in rule's Kibana space

Values are agnostic or single.

type string Required

The exception type

Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.

false_positives array[string] Required

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.

from string(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.

Hide investigation_fields attribute Show investigation_fields attribute object

field_names array[string(nonempty)] Required

A string that does not contain only whitespace characters

At least 1 element. Minimum length of each is 1.

license string

The rule's license.

max_signals integer Required

Maximum number of alerts the rule can create during a single run (the rule’s Max alerts per run advanced setting value).

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.

Minimum value is 1. Default value is 100.

meta object

Placeholder for metadata about the rule.

This field is overwritten when you save changes to the rule’s settings.

Additional properties are allowed.

name string Required

A human-readable name for the rule.

Minimum length is 1.

namespace string

Has no effect.

note string

Notes to help investigate alerts produced by the rule.

outcome string

Values are exactMatch, aliasMatch, or conflict.

output_index string Deprecated

(deprecated) Has no effect.

references array[string] Required

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.

related_integrations array[object] Required

Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:

package: name of the package (required, unique id)

version: version of the package (required, semver-compatible)

integration: name of the integration of this package (optional, id within the package)

There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.

Hide related_integrations attributes Show related_integrations attributes object

integration string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

package string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

version string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

required_fields array[object] Required

Elasticsearch fields and their types that need to be present for the rule to function.

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.

Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.

Hide required_fields attributes Show required_fields attributes object

name string(nonempty) Required

Name of an Elasticsearch field

Minimum length is 1.

type string(nonempty) Required

Type of the Elasticsearch field

Minimum length is 1.

response_actions array[object]

One of:
Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object

Hide attributes Show attributes

action_type_id string Required

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

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

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[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.

Hide attributes Show attributes

action_type_id string Required

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object

Hide attributes Show attributes

command string Required

Value is isolate.

comment string

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.

risk_score integer 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

Minimum value is 0, maximum value is 100.

risk_score_mapping array[object] Required

Overrides generated alerts' risk_score with a value from the source event

Hide risk_score_mapping attributes Show risk_score_mapping attributes object

field string Required

Source event field used to override the default risk_score.

operator string Required

Value is equals.

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

Minimum value is 0, maximum value is 100.

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 string 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 are low, medium, high, or critical.

severity_mapping array[object] Required

Overrides generated alerts' severity with values from the source event

Hide severity_mapping attributes Show severity_mapping attributes object

field string Required

Source event field used to override the default severity.

operator string Required

Value is equals.

severity string 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 are low, medium, high, or critical.

value string Required

tags array[string] Required

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.

threat array[object] Required

Currently, only threats described using the MITRE ATT&CK™ framework are supported.

Hide threat attributes Show threat attributes object

framework string Required

Relevant attack framework

tactic object Required

Object containing information on the attack type

Hide tactic attributes Show tactic attributes object

id string Required

Tactic ID

name string Required

Tactic name

reference string Required

Tactic reference

technique array[object]

Array containing information on the attack techniques (optional)

Hide technique attributes Show technique attributes object

id string Required

Technique ID

name string Required

Technique name

reference string Required

Technique reference

subtechnique array[object]

Array containing more specific information on the attack technique.

Hide subtechnique attributes Show subtechnique attributes object

id string Required

Subtechnique ID

name string Required

Subtechnique name

reference string Required

Subtechnique reference

throttle string | null

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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 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.

It is not incremented on each update. Compare this to the revision field.

Minimum value is 1.

created_at string(date-time) Required

created_by string Required

execution_summary object

Summary of the last execution of a rule.

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

Hide execution_summary attribute Show execution_summary attribute object

last_execution object Required

Hide last_execution attributes Show last_execution attributes object

date string(date-time) Required

Date of the last execution

message string Required

metrics object Required

Hide metrics attributes Show metrics attributes object

execution_gap_duration_s integer

Duration in seconds of execution gap

Minimum value is 0.

frozen_indices_queried_count integer

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

Minimum value is 0.

gap_range object

Range of the execution gap

Hide gap_range attributes Show gap_range attributes object

gte string Required

Start date of the execution gap

lte string Required

End date of the execution gap

total_enrichment_duration_ms integer

Total time spent enriching documents during current rule execution cycle

Minimum value is 0.

total_indexing_duration_ms integer

Total time spent indexing documents during current rule execution cycle

Minimum value is 0.

total_search_duration_ms integer

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

Minimum value is 0.

status string Required

Status of the last execution

Values are going to run, running, partial failure, failed, or succeeded.

status_order integer Required

id string(uuid) Required

A dynamic unique identifier for the rule object. It is randomly generated when a rule is created and cannot be changed after that. It is always a UUID. It is unique within a given Kibana space. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have different object ids.

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

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.

Minimum value is 0.

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 object 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:
Security_Detections_API_ExternalRuleSource object Security_Detections_API_InternalRuleSource object

Type of rule source for externally sourced rules, i.e. rules that have an external source, such as the Elastic Prebuilt rules repo.

Hide attributes Show attributes

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

type string Required Discriminator

Value is external.

updated_at string(date-time) Required

updated_by string Required

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.

threat_index array[string] Required

Elasticsearch indices used to check which field values generate alerts.

threat_mapping array[object] Required

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 Example of Threat Match rule which uses both and and or logic.

At least 1 element.

Hide threat_mapping attribute Show threat_mapping attribute object

entries array[object] Required

Hide entries attributes Show entries attributes object

field string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

type string Required

Value is mapping.

value string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

threat_query string Required

Query used to determine which fields in the Elasticsearch index are used for generating alerts.

type string Required Discriminator

Rule type

Value is threat_match.

alert_suppression object

Defines alert suppression configuration.

Hide alert_suppression attributes Show alert_suppression attributes object

duration object

Hide duration attributes Show duration attributes object

unit string Required

Time unit

Values are s, m, or h.

value integer Required

Minimum value is 1.

group_by array[string] Required

At least 1 but not more than 3 elements.

missing_fields_strategy string

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 are doNotSuppress or suppress.

concurrent_searches integer

Minimum value is 1.

data_view_id string

filters array

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

items_per_search integer

Minimum value is 1.

saved_id string

Kibana saved search used by the rule to create alerts.

threat_filters array

Query and filter context array used to filter documents from the Elasticsearch index containing the threat values

threat_indicator_path string

Defines the path to the threat indicator in the indicator documents (optional)

threat_language string

Values are kuery or lucene.

language string Required

Values are kuery or lucene.

Hide attributes Show attributes

actions array[object] Required

Array defining the automated actions (notifications) taken when alerts are generated.

Hide actions attributes Show actions attributes object

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.

Additional properties are allowed.

frequency object

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

Hide frequency attributes Show frequency attributes object

notifyWhen string Required

Defines how often rules run actions.

Values are onActiveAlert, onThrottleInterval, or 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 string | null Required

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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.

Additional properties are allowed.

uuid string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

alias_purpose string

Values are savedObjectConversion or savedObjectImport.

alias_target_id string

author array[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 Required

The rule’s description.

Minimum length is 1.

enabled boolean Required

Determines whether the rule is enabled. Defaults to true.

exceptions_list array[object] Required

Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.

Hide exceptions_list attributes Show exceptions_list attributes object

id string(nonempty) Required

ID of the exception container

Minimum length is 1.

list_id string(nonempty) Required

List ID of the exception container

Minimum length is 1.

namespace_type string Required

Determines the exceptions validity in rule's Kibana space

Values are agnostic or single.

type string Required

The exception type

Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.

false_positives array[string] Required

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.

from string(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.

Hide investigation_fields attribute Show investigation_fields attribute object

field_names array[string(nonempty)] Required

A string that does not contain only whitespace characters

At least 1 element. Minimum length of each is 1.

license string

The rule's license.

max_signals integer Required

Maximum number of alerts the rule can create during a single run (the rule’s Max alerts per run advanced setting value).

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.

Minimum value is 1. Default value is 100.

meta object

Placeholder for metadata about the rule.

This field is overwritten when you save changes to the rule’s settings.

Additional properties are allowed.

name string Required

A human-readable name for the rule.

Minimum length is 1.

namespace string

Has no effect.

note string

Notes to help investigate alerts produced by the rule.

outcome string

Values are exactMatch, aliasMatch, or conflict.

output_index string Deprecated

(deprecated) Has no effect.

references array[string] Required

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.

related_integrations array[object] Required

Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:

package: name of the package (required, unique id)

version: version of the package (required, semver-compatible)

integration: name of the integration of this package (optional, id within the package)

There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.

Hide related_integrations attributes Show related_integrations attributes object

integration string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

package string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

version string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

required_fields array[object] Required

Elasticsearch fields and their types that need to be present for the rule to function.

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.

Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.

Hide required_fields attributes Show required_fields attributes object

name string(nonempty) Required

Name of an Elasticsearch field

Minimum length is 1.

type string(nonempty) Required

Type of the Elasticsearch field

Minimum length is 1.

response_actions array[object]

One of:
Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object

Hide attributes Show attributes

action_type_id string Required

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

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

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[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.

Hide attributes Show attributes

action_type_id string Required

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object

Hide attributes Show attributes

command string Required

Value is isolate.

comment string

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.

risk_score integer 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

Minimum value is 0, maximum value is 100.

risk_score_mapping array[object] Required

Overrides generated alerts' risk_score with a value from the source event

Hide risk_score_mapping attributes Show risk_score_mapping attributes object

field string Required

Source event field used to override the default risk_score.

operator string Required

Value is equals.

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

Minimum value is 0, maximum value is 100.

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 string 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 are low, medium, high, or critical.

severity_mapping array[object] Required

Overrides generated alerts' severity with values from the source event

Hide severity_mapping attributes Show severity_mapping attributes object

field string Required

Source event field used to override the default severity.

operator string Required

Value is equals.

severity string 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 are low, medium, high, or critical.

value string Required

tags array[string] Required

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.

threat array[object] Required

Currently, only threats described using the MITRE ATT&CK™ framework are supported.

Hide threat attributes Show threat attributes object

framework string Required

Relevant attack framework

tactic object Required

Object containing information on the attack type

Hide tactic attributes Show tactic attributes object

id string Required

Tactic ID

name string Required

Tactic name

reference string Required

Tactic reference

technique array[object]

Array containing information on the attack techniques (optional)

Hide technique attributes Show technique attributes object

id string Required

Technique ID

name string Required

Technique name

reference string Required

Technique reference

subtechnique array[object]

Array containing more specific information on the attack technique.

Hide subtechnique attributes Show subtechnique attributes object

id string Required

Subtechnique ID

name string Required

Subtechnique name

reference string Required

Subtechnique reference

throttle string | null

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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 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.

It is not incremented on each update. Compare this to the revision field.

Minimum value is 1.

created_at string(date-time) Required

created_by string Required

execution_summary object

Summary of the last execution of a rule.

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

Hide execution_summary attribute Show execution_summary attribute object

last_execution object Required

Hide last_execution attributes Show last_execution attributes object

date string(date-time) Required

Date of the last execution

message string Required

metrics object Required

Hide metrics attributes Show metrics attributes object

execution_gap_duration_s integer

Duration in seconds of execution gap

Minimum value is 0.

frozen_indices_queried_count integer

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

Minimum value is 0.

gap_range object

Range of the execution gap

Hide gap_range attributes Show gap_range attributes object

gte string Required

Start date of the execution gap

lte string Required

End date of the execution gap

total_enrichment_duration_ms integer

Total time spent enriching documents during current rule execution cycle

Minimum value is 0.

total_indexing_duration_ms integer

Total time spent indexing documents during current rule execution cycle

Minimum value is 0.

total_search_duration_ms integer

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

Minimum value is 0.

status string Required

Status of the last execution

Values are going to run, running, partial failure, failed, or succeeded.

status_order integer Required

id string(uuid) Required

A dynamic unique identifier for the rule object. It is randomly generated when a rule is created and cannot be changed after that. It is always a UUID. It is unique within a given Kibana space. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have different object ids.

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

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.

Minimum value is 0.

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 object 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:
Security_Detections_API_ExternalRuleSource object Security_Detections_API_InternalRuleSource object

Type of rule source for externally sourced rules, i.e. rules that have an external source, such as the Elastic Prebuilt rules repo.

Hide attributes Show attributes

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

type string Required Discriminator

Value is external.

updated_at string(date-time) Required

updated_by string Required

anomaly_threshold integer Required

Anomaly score threshold above which the rule creates an alert. Valid values are from 0 to 100.

Minimum value is 0.

machine_learning_job_id string | array[string] Required

Machine learning job ID(s) the rule monitors for anomaly scores.

One of:
string-1 string array-2 array[string]

type string Required Discriminator

Rule type

Value is machine_learning.

alert_suppression object

Defines alert suppression configuration.

Hide alert_suppression attributes Show alert_suppression attributes object

duration object

Hide duration attributes Show duration attributes object

unit string Required

Time unit

Values are s, m, or h.

value integer Required

Minimum value is 1.

group_by array[string] Required

At least 1 but not more than 3 elements.

missing_fields_strategy string

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 are doNotSuppress or suppress.

Hide attributes Show attributes

actions array[object] Required

Array defining the automated actions (notifications) taken when alerts are generated.

Hide actions attributes Show actions attributes object

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.

Additional properties are allowed.

frequency object

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

Hide frequency attributes Show frequency attributes object

notifyWhen string Required

Defines how often rules run actions.

Values are onActiveAlert, onThrottleInterval, or 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 string | null Required

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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.

Additional properties are allowed.

uuid string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

alias_purpose string

Values are savedObjectConversion or savedObjectImport.

alias_target_id string

author array[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 Required

The rule’s description.

Minimum length is 1.

enabled boolean Required

Determines whether the rule is enabled. Defaults to true.

exceptions_list array[object] Required

Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.

Hide exceptions_list attributes Show exceptions_list attributes object

id string(nonempty) Required

ID of the exception container

Minimum length is 1.

list_id string(nonempty) Required

List ID of the exception container

Minimum length is 1.

namespace_type string Required

Determines the exceptions validity in rule's Kibana space

Values are agnostic or single.

type string Required

The exception type

Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.

false_positives array[string] Required

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.

from string(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.

Hide investigation_fields attribute Show investigation_fields attribute object

field_names array[string(nonempty)] Required

A string that does not contain only whitespace characters

At least 1 element. Minimum length of each is 1.

license string

The rule's license.

max_signals integer Required

Maximum number of alerts the rule can create during a single run (the rule’s Max alerts per run advanced setting value).

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.

Minimum value is 1. Default value is 100.

meta object

Placeholder for metadata about the rule.

This field is overwritten when you save changes to the rule’s settings.

Additional properties are allowed.

name string Required

A human-readable name for the rule.

Minimum length is 1.

namespace string

Has no effect.

note string

Notes to help investigate alerts produced by the rule.

outcome string

Values are exactMatch, aliasMatch, or conflict.

output_index string Deprecated

(deprecated) Has no effect.

references array[string] Required

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.

related_integrations array[object] Required

Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:

package: name of the package (required, unique id)

version: version of the package (required, semver-compatible)

integration: name of the integration of this package (optional, id within the package)

There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.

Hide related_integrations attributes Show related_integrations attributes object

integration string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

package string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

version string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

required_fields array[object] Required

Elasticsearch fields and their types that need to be present for the rule to function.

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.

Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.

Hide required_fields attributes Show required_fields attributes object

name string(nonempty) Required

Name of an Elasticsearch field

Minimum length is 1.

type string(nonempty) Required

Type of the Elasticsearch field

Minimum length is 1.

response_actions array[object]

One of:
Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object

Hide attributes Show attributes

action_type_id string Required

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

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

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[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.

Hide attributes Show attributes

action_type_id string Required

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object

Hide attributes Show attributes

command string Required

Value is isolate.

comment string

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.

risk_score integer 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

Minimum value is 0, maximum value is 100.

risk_score_mapping array[object] Required

Overrides generated alerts' risk_score with a value from the source event

Hide risk_score_mapping attributes Show risk_score_mapping attributes object

field string Required

Source event field used to override the default risk_score.

operator string Required

Value is equals.

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

Minimum value is 0, maximum value is 100.

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 string 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 are low, medium, high, or critical.

severity_mapping array[object] Required

Overrides generated alerts' severity with values from the source event

Hide severity_mapping attributes Show severity_mapping attributes object

field string Required

Source event field used to override the default severity.

operator string Required

Value is equals.

severity string 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 are low, medium, high, or critical.

value string Required

tags array[string] Required

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.

threat array[object] Required

Currently, only threats described using the MITRE ATT&CK™ framework are supported.

Hide threat attributes Show threat attributes object

framework string Required

Relevant attack framework

tactic object Required

Object containing information on the attack type

Hide tactic attributes Show tactic attributes object

id string Required

Tactic ID

name string Required

Tactic name

reference string Required

Tactic reference

technique array[object]

Array containing information on the attack techniques (optional)

Hide technique attributes Show technique attributes object

id string Required

Technique ID

name string Required

Technique name

reference string Required

Technique reference

subtechnique array[object]

Array containing more specific information on the attack technique.

Hide subtechnique attributes Show subtechnique attributes object

id string Required

Subtechnique ID

name string Required

Subtechnique name

reference string Required

Subtechnique reference

throttle string | null

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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 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.

It is not incremented on each update. Compare this to the revision field.

Minimum value is 1.

created_at string(date-time) Required

created_by string Required

execution_summary object

Summary of the last execution of a rule.

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

Hide execution_summary attribute Show execution_summary attribute object

last_execution object Required

Hide last_execution attributes Show last_execution attributes object

date string(date-time) Required

Date of the last execution

message string Required

metrics object Required

Hide metrics attributes Show metrics attributes object

execution_gap_duration_s integer

Duration in seconds of execution gap

Minimum value is 0.

frozen_indices_queried_count integer

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

Minimum value is 0.

gap_range object

Range of the execution gap

Hide gap_range attributes Show gap_range attributes object

gte string Required

Start date of the execution gap

lte string Required

End date of the execution gap

total_enrichment_duration_ms integer

Total time spent enriching documents during current rule execution cycle

Minimum value is 0.

total_indexing_duration_ms integer

Total time spent indexing documents during current rule execution cycle

Minimum value is 0.

total_search_duration_ms integer

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

Minimum value is 0.

status string Required

Status of the last execution

Values are going to run, running, partial failure, failed, or succeeded.

status_order integer Required

id string(uuid) Required

A dynamic unique identifier for the rule object. It is randomly generated when a rule is created and cannot be changed after that. It is always a UUID. It is unique within a given Kibana space. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have different object ids.

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

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.

Minimum value is 0.

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 object 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:
Security_Detections_API_ExternalRuleSource object Security_Detections_API_InternalRuleSource object

Type of rule source for externally sourced rules, i.e. rules that have an external source, such as the Elastic Prebuilt rules repo.

Hide attributes Show attributes

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

type string Required Discriminator

Value is external.

updated_at string(date-time) Required

updated_by string Required

history_window_start string(nonempty) Required

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.

Minimum length is 1.

new_terms_fields array[string] Required

Fields to monitor for new values.

At least 1 but not more than 3 elements.

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.

type string Required Discriminator

Rule type

Value is new_terms.

alert_suppression object

Defines alert suppression configuration.

Hide alert_suppression attributes Show alert_suppression attributes object

duration object

Hide duration attributes Show duration attributes object

unit string Required

Time unit

Values are s, m, or h.

value integer Required

Minimum value is 1.

group_by array[string] Required

At least 1 but not more than 3 elements.

missing_fields_strategy string

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 are doNotSuppress or suppress.

data_view_id string

filters array

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

language string Required

Values are kuery or lucene.

Hide attributes Show attributes

actions array[object] Required

Array defining the automated actions (notifications) taken when alerts are generated.

Hide actions attributes Show actions attributes object

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.

Additional properties are allowed.

frequency object

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

Hide frequency attributes Show frequency attributes object

notifyWhen string Required

Defines how often rules run actions.

Values are onActiveAlert, onThrottleInterval, or 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 string | null Required

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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.

Additional properties are allowed.

uuid string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

alias_purpose string

Values are savedObjectConversion or savedObjectImport.

alias_target_id string

author array[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 Required

The rule’s description.

Minimum length is 1.

enabled boolean Required

Determines whether the rule is enabled. Defaults to true.

exceptions_list array[object] Required

Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.

Hide exceptions_list attributes Show exceptions_list attributes object

id string(nonempty) Required

ID of the exception container

Minimum length is 1.

list_id string(nonempty) Required

List ID of the exception container

Minimum length is 1.

namespace_type string Required

Determines the exceptions validity in rule's Kibana space

Values are agnostic or single.

type string Required

The exception type

Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.

false_positives array[string] Required

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.

from string(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.

Hide investigation_fields attribute Show investigation_fields attribute object

field_names array[string(nonempty)] Required

A string that does not contain only whitespace characters

At least 1 element. Minimum length of each is 1.

license string

The rule's license.

max_signals integer Required

Maximum number of alerts the rule can create during a single run (the rule’s Max alerts per run advanced setting value).

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.

Minimum value is 1. Default value is 100.

meta object

Placeholder for metadata about the rule.

This field is overwritten when you save changes to the rule’s settings.

Additional properties are allowed.

name string Required

A human-readable name for the rule.

Minimum length is 1.

namespace string

Has no effect.

note string

Notes to help investigate alerts produced by the rule.

outcome string

Values are exactMatch, aliasMatch, or conflict.

output_index string Deprecated

(deprecated) Has no effect.

references array[string] Required

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.

related_integrations array[object] Required

Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:

package: name of the package (required, unique id)

version: version of the package (required, semver-compatible)

integration: name of the integration of this package (optional, id within the package)

There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.

Hide related_integrations attributes Show related_integrations attributes object

integration string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

package string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

version string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

required_fields array[object] Required

Elasticsearch fields and their types that need to be present for the rule to function.

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.

Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.

Hide required_fields attributes Show required_fields attributes object

name string(nonempty) Required

Name of an Elasticsearch field

Minimum length is 1.

type string(nonempty) Required

Type of the Elasticsearch field

Minimum length is 1.

response_actions array[object]

One of:
Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object

Hide attributes Show attributes

action_type_id string Required

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

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

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[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.

Hide attributes Show attributes

action_type_id string Required

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object

Hide attributes Show attributes

command string Required

Value is isolate.

comment string

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.

risk_score integer 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

Minimum value is 0, maximum value is 100.

risk_score_mapping array[object] Required

Overrides generated alerts' risk_score with a value from the source event

Hide risk_score_mapping attributes Show risk_score_mapping attributes object

field string Required

Source event field used to override the default risk_score.

operator string Required

Value is equals.

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

Minimum value is 0, maximum value is 100.

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 string 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 are low, medium, high, or critical.

severity_mapping array[object] Required

Overrides generated alerts' severity with values from the source event

Hide severity_mapping attributes Show severity_mapping attributes object

field string Required

Source event field used to override the default severity.

operator string Required

Value is equals.

severity string 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 are low, medium, high, or critical.

value string Required

tags array[string] Required

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.

threat array[object] Required

Currently, only threats described using the MITRE ATT&CK™ framework are supported.

Hide threat attributes Show threat attributes object

framework string Required

Relevant attack framework

tactic object Required

Object containing information on the attack type

Hide tactic attributes Show tactic attributes object

id string Required

Tactic ID

name string Required

Tactic name

reference string Required

Tactic reference

technique array[object]

Array containing information on the attack techniques (optional)

Hide technique attributes Show technique attributes object

id string Required

Technique ID

name string Required

Technique name

reference string Required

Technique reference

subtechnique array[object]

Array containing more specific information on the attack technique.

Hide subtechnique attributes Show subtechnique attributes object

id string Required

Subtechnique ID

name string Required

Subtechnique name

reference string Required

Subtechnique reference

throttle string | null

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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 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.

It is not incremented on each update. Compare this to the revision field.

Minimum value is 1.

created_at string(date-time) Required

created_by string Required

execution_summary object

Summary of the last execution of a rule.

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

Hide execution_summary attribute Show execution_summary attribute object

last_execution object Required

Hide last_execution attributes Show last_execution attributes object

date string(date-time) Required

Date of the last execution

message string Required

metrics object Required

Hide metrics attributes Show metrics attributes object

execution_gap_duration_s integer

Duration in seconds of execution gap

Minimum value is 0.

frozen_indices_queried_count integer

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

Minimum value is 0.

gap_range object

Range of the execution gap

Hide gap_range attributes Show gap_range attributes object

gte string Required

Start date of the execution gap

lte string Required

End date of the execution gap

total_enrichment_duration_ms integer

Total time spent enriching documents during current rule execution cycle

Minimum value is 0.

total_indexing_duration_ms integer

Total time spent indexing documents during current rule execution cycle

Minimum value is 0.

total_search_duration_ms integer

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

Minimum value is 0.

status string Required

Status of the last execution

Values are going to run, running, partial failure, failed, or succeeded.

status_order integer Required

id string(uuid) Required

A dynamic unique identifier for the rule object. It is randomly generated when a rule is created and cannot be changed after that. It is always a UUID. It is unique within a given Kibana space. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have different object ids.

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

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.

Minimum value is 0.

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 object 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:
Security_Detections_API_ExternalRuleSource object Security_Detections_API_InternalRuleSource object

Type of rule source for externally sourced rules, i.e. rules that have an external source, such as the Elastic Prebuilt rules repo.

Hide attributes Show attributes

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

type string Required Discriminator

Value is external.

updated_at string(date-time) Required

updated_by string Required

alert_suppression object

Defines alert suppression configuration.

Hide alert_suppression attributes Show alert_suppression attributes object

duration object

Hide duration attributes Show duration attributes object

unit string Required

Time unit

Values are s, m, or h.

value integer Required

Minimum value is 1.

group_by array[string] Required

At least 1 but not more than 3 elements.

missing_fields_strategy string

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 are doNotSuppress or suppress.

language string Required

Value is esql.

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.

type string Required Discriminator

Rule type

Value is esql.

skipped array[object] Required

Hide skipped attributes Show skipped attributes object

id string Required

name string

skip_reason string Required

Value is RULE_NOT_MODIFIED.

updated array[object] Required

Any of:
Security_Detections_API_EqlRuleResponseFields object Security_Detections_API_QueryRuleResponseFields object Security_Detections_API_SavedQueryRuleResponseFields object Security_Detections_API_ThresholdRuleResponseFields object Security_Detections_API_ThreatMatchRuleResponseFields object Security_Detections_API_MachineLearningRuleResponseFields object Security_Detections_API_NewTermsRuleResponseFields object Security_Detections_API_EsqlRuleResponseFields object

Hide attributes Show attributes

actions array[object] Required

Array defining the automated actions (notifications) taken when alerts are generated.

Hide actions attributes Show actions attributes object

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.

Additional properties are allowed.

frequency object

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

Hide frequency attributes Show frequency attributes object

notifyWhen string Required

Defines how often rules run actions.

Values are onActiveAlert, onThrottleInterval, or 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 string | null Required

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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.

Additional properties are allowed.

uuid string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

alias_purpose string

Values are savedObjectConversion or savedObjectImport.

alias_target_id string

author array[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 Required

The rule’s description.

Minimum length is 1.

enabled boolean Required

Determines whether the rule is enabled. Defaults to true.

exceptions_list array[object] Required

Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.

Hide exceptions_list attributes Show exceptions_list attributes object

id string(nonempty) Required

ID of the exception container

Minimum length is 1.

list_id string(nonempty) Required

List ID of the exception container

Minimum length is 1.

namespace_type string Required

Determines the exceptions validity in rule's Kibana space

Values are agnostic or single.

type string Required

The exception type

Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.

false_positives array[string] Required

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.

from string(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.

Hide investigation_fields attribute Show investigation_fields attribute object

field_names array[string(nonempty)] Required

A string that does not contain only whitespace characters

At least 1 element. Minimum length of each is 1.

license string

The rule's license.

max_signals integer Required

Maximum number of alerts the rule can create during a single run (the rule’s Max alerts per run advanced setting value).

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.

Minimum value is 1. Default value is 100.

meta object

Placeholder for metadata about the rule.

This field is overwritten when you save changes to the rule’s settings.

Additional properties are allowed.

name string Required

A human-readable name for the rule.

Minimum length is 1.

namespace string

Has no effect.

note string

Notes to help investigate alerts produced by the rule.

outcome string

Values are exactMatch, aliasMatch, or conflict.

output_index string Deprecated

(deprecated) Has no effect.

references array[string] Required

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.

related_integrations array[object] Required

Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:

package: name of the package (required, unique id)

version: version of the package (required, semver-compatible)

integration: name of the integration of this package (optional, id within the package)

There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.

Hide related_integrations attributes Show related_integrations attributes object

integration string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

package string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

version string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

required_fields array[object] Required

Elasticsearch fields and their types that need to be present for the rule to function.

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.

Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.

Hide required_fields attributes Show required_fields attributes object

name string(nonempty) Required

Name of an Elasticsearch field

Minimum length is 1.

type string(nonempty) Required

Type of the Elasticsearch field

Minimum length is 1.

response_actions array[object]

One of:
Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object

Hide attributes Show attributes

action_type_id string Required

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

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

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[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.

Hide attributes Show attributes

action_type_id string Required

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object

Hide attributes Show attributes

command string Required

Value is isolate.

comment string

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.

risk_score integer 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

Minimum value is 0, maximum value is 100.

risk_score_mapping array[object] Required

Overrides generated alerts' risk_score with a value from the source event

Hide risk_score_mapping attributes Show risk_score_mapping attributes object

field string Required

Source event field used to override the default risk_score.

operator string Required

Value is equals.

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

Minimum value is 0, maximum value is 100.

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 string 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 are low, medium, high, or critical.

severity_mapping array[object] Required

Overrides generated alerts' severity with values from the source event

Hide severity_mapping attributes Show severity_mapping attributes object

field string Required

Source event field used to override the default severity.

operator string Required

Value is equals.

severity string 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 are low, medium, high, or critical.

value string Required

tags array[string] Required

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.

threat array[object] Required

Currently, only threats described using the MITRE ATT&CK™ framework are supported.

Hide threat attributes Show threat attributes object

framework string Required

Relevant attack framework

tactic object Required

Object containing information on the attack type

Hide tactic attributes Show tactic attributes object

id string Required

Tactic ID

name string Required

Tactic name

reference string Required

Tactic reference

technique array[object]

Array containing information on the attack techniques (optional)

Hide technique attributes Show technique attributes object

id string Required

Technique ID

name string Required

Technique name

reference string Required

Technique reference

subtechnique array[object]

Array containing more specific information on the attack technique.

Hide subtechnique attributes Show subtechnique attributes object

id string Required

Subtechnique ID

name string Required

Subtechnique name

reference string Required

Subtechnique reference

throttle string | null

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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 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.

It is not incremented on each update. Compare this to the revision field.

Minimum value is 1.

created_at string(date-time) Required

created_by string Required

execution_summary object

Summary of the last execution of a rule.

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

Hide execution_summary attribute Show execution_summary attribute object

last_execution object Required

Hide last_execution attributes Show last_execution attributes object

date string(date-time) Required

Date of the last execution

message string Required

metrics object Required

Hide metrics attributes Show metrics attributes object

execution_gap_duration_s integer

Duration in seconds of execution gap

Minimum value is 0.

frozen_indices_queried_count integer

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

Minimum value is 0.

gap_range object

Range of the execution gap

Hide gap_range attributes Show gap_range attributes object

gte string Required

Start date of the execution gap

lte string Required

End date of the execution gap

total_enrichment_duration_ms integer

Total time spent enriching documents during current rule execution cycle

Minimum value is 0.

total_indexing_duration_ms integer

Total time spent indexing documents during current rule execution cycle

Minimum value is 0.

total_search_duration_ms integer

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

Minimum value is 0.

status string Required

Status of the last execution

Values are going to run, running, partial failure, failed, or succeeded.

status_order integer Required

id string(uuid) Required

A dynamic unique identifier for the rule object. It is randomly generated when a rule is created and cannot be changed after that. It is always a UUID. It is unique within a given Kibana space. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have different object ids.

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

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.

Minimum value is 0.

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 object 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:
Security_Detections_API_ExternalRuleSource object Security_Detections_API_InternalRuleSource object

Type of rule source for externally sourced rules, i.e. rules that have an external source, such as the Elastic Prebuilt rules repo.

Hide attributes Show attributes

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

type string Required Discriminator

Value is external.

updated_at string(date-time) Required

updated_by string Required

language string Required

Query language to use

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

type string Required Discriminator

Rule type

Value is eql.

alert_suppression object

Defines alert suppression configuration.

Hide alert_suppression attributes Show alert_suppression attributes object

duration object

Hide duration attributes Show duration attributes object

unit string Required

Time unit

Values are s, m, or h.

value integer Required

Minimum value is 1.

group_by array[string] Required

At least 1 but not more than 3 elements.

missing_fields_strategy string

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 are doNotSuppress or suppress.

data_view_id string

event_category_override string

filters array

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

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.

Hide attributes Show attributes

actions array[object] Required

Array defining the automated actions (notifications) taken when alerts are generated.

Hide actions attributes Show actions attributes object

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.

Additional properties are allowed.

frequency object

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

Hide frequency attributes Show frequency attributes object

notifyWhen string Required

Defines how often rules run actions.

Values are onActiveAlert, onThrottleInterval, or 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 string | null Required

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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.

Additional properties are allowed.

uuid string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

alias_purpose string

Values are savedObjectConversion or savedObjectImport.

alias_target_id string

author array[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 Required

The rule’s description.

Minimum length is 1.

enabled boolean Required

Determines whether the rule is enabled. Defaults to true.

exceptions_list array[object] Required

Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.

Hide exceptions_list attributes Show exceptions_list attributes object

id string(nonempty) Required

ID of the exception container

Minimum length is 1.

list_id string(nonempty) Required

List ID of the exception container

Minimum length is 1.

namespace_type string Required

Determines the exceptions validity in rule's Kibana space

Values are agnostic or single.

type string Required

The exception type

Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.

false_positives array[string] Required

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.

from string(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.

Hide investigation_fields attribute Show investigation_fields attribute object

field_names array[string(nonempty)] Required

A string that does not contain only whitespace characters

At least 1 element. Minimum length of each is 1.

license string

The rule's license.

max_signals integer Required

Maximum number of alerts the rule can create during a single run (the rule’s Max alerts per run advanced setting value).

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.

Minimum value is 1. Default value is 100.

meta object

Placeholder for metadata about the rule.

This field is overwritten when you save changes to the rule’s settings.

Additional properties are allowed.

name string Required

A human-readable name for the rule.

Minimum length is 1.

namespace string

Has no effect.

note string

Notes to help investigate alerts produced by the rule.

outcome string

Values are exactMatch, aliasMatch, or conflict.

output_index string Deprecated

(deprecated) Has no effect.

references array[string] Required

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.

related_integrations array[object] Required

Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:

package: name of the package (required, unique id)

version: version of the package (required, semver-compatible)

integration: name of the integration of this package (optional, id within the package)

There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.

Hide related_integrations attributes Show related_integrations attributes object

integration string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

package string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

version string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

required_fields array[object] Required

Elasticsearch fields and their types that need to be present for the rule to function.

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.

Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.

Hide required_fields attributes Show required_fields attributes object

name string(nonempty) Required

Name of an Elasticsearch field

Minimum length is 1.

type string(nonempty) Required

Type of the Elasticsearch field

Minimum length is 1.

response_actions array[object]

One of:
Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object

Hide attributes Show attributes

action_type_id string Required

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

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

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[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.

Hide attributes Show attributes

action_type_id string Required

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object

Hide attributes Show attributes

command string Required

Value is isolate.

comment string

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.

risk_score integer 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

Minimum value is 0, maximum value is 100.

risk_score_mapping array[object] Required

Overrides generated alerts' risk_score with a value from the source event

Hide risk_score_mapping attributes Show risk_score_mapping attributes object

field string Required

Source event field used to override the default risk_score.

operator string Required

Value is equals.

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

Minimum value is 0, maximum value is 100.

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 string 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 are low, medium, high, or critical.

severity_mapping array[object] Required

Overrides generated alerts' severity with values from the source event

Hide severity_mapping attributes Show severity_mapping attributes object

field string Required

Source event field used to override the default severity.

operator string Required

Value is equals.

severity string 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 are low, medium, high, or critical.

value string Required

tags array[string] Required

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.

threat array[object] Required

Currently, only threats described using the MITRE ATT&CK™ framework are supported.

Hide threat attributes Show threat attributes object

framework string Required

Relevant attack framework

tactic object Required

Object containing information on the attack type

Hide tactic attributes Show tactic attributes object

id string Required

Tactic ID

name string Required

Tactic name

reference string Required

Tactic reference

technique array[object]

Array containing information on the attack techniques (optional)

Hide technique attributes Show technique attributes object

id string Required

Technique ID

name string Required

Technique name

reference string Required

Technique reference

subtechnique array[object]

Array containing more specific information on the attack technique.

Hide subtechnique attributes Show subtechnique attributes object

id string Required

Subtechnique ID

name string Required

Subtechnique name

reference string Required

Subtechnique reference

throttle string | null

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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 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.

It is not incremented on each update. Compare this to the revision field.

Minimum value is 1.

created_at string(date-time) Required

created_by string Required

execution_summary object

Summary of the last execution of a rule.

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

Hide execution_summary attribute Show execution_summary attribute object

last_execution object Required

Hide last_execution attributes Show last_execution attributes object

date string(date-time) Required

Date of the last execution

message string Required

metrics object Required

Hide metrics attributes Show metrics attributes object

execution_gap_duration_s integer

Duration in seconds of execution gap

Minimum value is 0.

frozen_indices_queried_count integer

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

Minimum value is 0.

gap_range object

Range of the execution gap

Hide gap_range attributes Show gap_range attributes object

gte string Required

Start date of the execution gap

lte string Required

End date of the execution gap

total_enrichment_duration_ms integer

Total time spent enriching documents during current rule execution cycle

Minimum value is 0.

total_indexing_duration_ms integer

Total time spent indexing documents during current rule execution cycle

Minimum value is 0.

total_search_duration_ms integer

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

Minimum value is 0.

status string Required

Status of the last execution

Values are going to run, running, partial failure, failed, or succeeded.

status_order integer Required

id string(uuid) Required

A dynamic unique identifier for the rule object. It is randomly generated when a rule is created and cannot be changed after that. It is always a UUID. It is unique within a given Kibana space. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have different object ids.

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

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.

Minimum value is 0.

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 object 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:
Security_Detections_API_ExternalRuleSource object Security_Detections_API_InternalRuleSource object

Type of rule source for externally sourced rules, i.e. rules that have an external source, such as the Elastic Prebuilt rules repo.

Hide attributes Show attributes

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

type string Required Discriminator

Value is external.

updated_at string(date-time) Required

updated_by string Required

type string Required Discriminator

Rule type

Value is query.

alert_suppression object

Defines alert suppression configuration.

Hide alert_suppression attributes Show alert_suppression attributes object

duration object

Hide duration attributes Show duration attributes object

unit string Required

Time unit

Values are s, m, or h.

value integer Required

Minimum value is 1.

group_by array[string] Required

At least 1 but not more than 3 elements.

missing_fields_strategy string

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 are doNotSuppress or suppress.

data_view_id string

filters array

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

saved_id string

Kibana saved search used by the rule to create alerts.

language string Required

Values are kuery or lucene.

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.

Hide attributes Show attributes

actions array[object] Required

Array defining the automated actions (notifications) taken when alerts are generated.

Hide actions attributes Show actions attributes object

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.

Additional properties are allowed.

frequency object

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

Hide frequency attributes Show frequency attributes object

notifyWhen string Required

Defines how often rules run actions.

Values are onActiveAlert, onThrottleInterval, or 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 string | null Required

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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.

Additional properties are allowed.

uuid string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

alias_purpose string

Values are savedObjectConversion or savedObjectImport.

alias_target_id string

author array[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 Required

The rule’s description.

Minimum length is 1.

enabled boolean Required

Determines whether the rule is enabled. Defaults to true.

exceptions_list array[object] Required

Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.

Hide exceptions_list attributes Show exceptions_list attributes object

id string(nonempty) Required

ID of the exception container

Minimum length is 1.

list_id string(nonempty) Required

List ID of the exception container

Minimum length is 1.

namespace_type string Required

Determines the exceptions validity in rule's Kibana space

Values are agnostic or single.

type string Required

The exception type

Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.

false_positives array[string] Required

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.

from string(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.

Hide investigation_fields attribute Show investigation_fields attribute object

field_names array[string(nonempty)] Required

A string that does not contain only whitespace characters

At least 1 element. Minimum length of each is 1.

license string

The rule's license.

max_signals integer Required

Maximum number of alerts the rule can create during a single run (the rule’s Max alerts per run advanced setting value).

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.

Minimum value is 1. Default value is 100.

meta object

Placeholder for metadata about the rule.

This field is overwritten when you save changes to the rule’s settings.

Additional properties are allowed.

name string Required

A human-readable name for the rule.

Minimum length is 1.

namespace string

Has no effect.

note string

Notes to help investigate alerts produced by the rule.

outcome string

Values are exactMatch, aliasMatch, or conflict.

output_index string Deprecated

(deprecated) Has no effect.

references array[string] Required

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.

related_integrations array[object] Required

Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:

package: name of the package (required, unique id)

version: version of the package (required, semver-compatible)

integration: name of the integration of this package (optional, id within the package)

There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.

Hide related_integrations attributes Show related_integrations attributes object

integration string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

package string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

version string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

required_fields array[object] Required

Elasticsearch fields and their types that need to be present for the rule to function.

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.

Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.

Hide required_fields attributes Show required_fields attributes object

name string(nonempty) Required

Name of an Elasticsearch field

Minimum length is 1.

type string(nonempty) Required

Type of the Elasticsearch field

Minimum length is 1.

response_actions array[object]

One of:
Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object

Hide attributes Show attributes

action_type_id string Required

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

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

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[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.

Hide attributes Show attributes

action_type_id string Required

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object

Hide attributes Show attributes

command string Required

Value is isolate.

comment string

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.

risk_score integer 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

Minimum value is 0, maximum value is 100.

risk_score_mapping array[object] Required

Overrides generated alerts' risk_score with a value from the source event

Hide risk_score_mapping attributes Show risk_score_mapping attributes object

field string Required

Source event field used to override the default risk_score.

operator string Required

Value is equals.

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

Minimum value is 0, maximum value is 100.

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 string 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 are low, medium, high, or critical.

severity_mapping array[object] Required

Overrides generated alerts' severity with values from the source event

Hide severity_mapping attributes Show severity_mapping attributes object

field string Required

Source event field used to override the default severity.

operator string Required

Value is equals.

severity string 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 are low, medium, high, or critical.

value string Required

tags array[string] Required

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.

threat array[object] Required

Currently, only threats described using the MITRE ATT&CK™ framework are supported.

Hide threat attributes Show threat attributes object

framework string Required

Relevant attack framework

tactic object Required

Object containing information on the attack type

Hide tactic attributes Show tactic attributes object

id string Required

Tactic ID

name string Required

Tactic name

reference string Required

Tactic reference

technique array[object]

Array containing information on the attack techniques (optional)

Hide technique attributes Show technique attributes object

id string Required

Technique ID

name string Required

Technique name

reference string Required

Technique reference

subtechnique array[object]

Array containing more specific information on the attack technique.

Hide subtechnique attributes Show subtechnique attributes object

id string Required

Subtechnique ID

name string Required

Subtechnique name

reference string Required

Subtechnique reference

throttle string | null

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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 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.

It is not incremented on each update. Compare this to the revision field.

Minimum value is 1.

created_at string(date-time) Required

created_by string Required

execution_summary object

Summary of the last execution of a rule.

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

Hide execution_summary attribute Show execution_summary attribute object

last_execution object Required

Hide last_execution attributes Show last_execution attributes object

date string(date-time) Required

Date of the last execution

message string Required

metrics object Required

Hide metrics attributes Show metrics attributes object

execution_gap_duration_s integer

Duration in seconds of execution gap

Minimum value is 0.

frozen_indices_queried_count integer

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

Minimum value is 0.

gap_range object

Range of the execution gap

Hide gap_range attributes Show gap_range attributes object

gte string Required

Start date of the execution gap

lte string Required

End date of the execution gap

total_enrichment_duration_ms integer

Total time spent enriching documents during current rule execution cycle

Minimum value is 0.

total_indexing_duration_ms integer

Total time spent indexing documents during current rule execution cycle

Minimum value is 0.

total_search_duration_ms integer

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

Minimum value is 0.

status string Required

Status of the last execution

Values are going to run, running, partial failure, failed, or succeeded.

status_order integer Required

id string(uuid) Required

A dynamic unique identifier for the rule object. It is randomly generated when a rule is created and cannot be changed after that. It is always a UUID. It is unique within a given Kibana space. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have different object ids.

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

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.

Minimum value is 0.

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 object 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:
Security_Detections_API_ExternalRuleSource object Security_Detections_API_InternalRuleSource object

Type of rule source for externally sourced rules, i.e. rules that have an external source, such as the Elastic Prebuilt rules repo.

Hide attributes Show attributes

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

type string Required Discriminator

Value is external.

updated_at string(date-time) Required

updated_by string Required

saved_id string Required

Kibana saved search used by the rule to create alerts.

type string Required Discriminator

Rule type

Value is saved_query.

alert_suppression object

Defines alert suppression configuration.

Hide alert_suppression attributes Show alert_suppression attributes object

duration object

Hide duration attributes Show duration attributes object

unit string Required

Time unit

Values are s, m, or h.

value integer Required

Minimum value is 1.

group_by array[string] Required

At least 1 but not more than 3 elements.

missing_fields_strategy string

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 are doNotSuppress or suppress.

data_view_id string

filters array

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

query string

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.

language string Required

Values are kuery or lucene.

Hide attributes Show attributes

actions array[object] Required

Array defining the automated actions (notifications) taken when alerts are generated.

Hide actions attributes Show actions attributes object

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.

Additional properties are allowed.

frequency object

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

Hide frequency attributes Show frequency attributes object

notifyWhen string Required

Defines how often rules run actions.

Values are onActiveAlert, onThrottleInterval, or 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 string | null Required

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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.

Additional properties are allowed.

uuid string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

alias_purpose string

Values are savedObjectConversion or savedObjectImport.

alias_target_id string

author array[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 Required

The rule’s description.

Minimum length is 1.

enabled boolean Required

Determines whether the rule is enabled. Defaults to true.

exceptions_list array[object] Required

Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.

Hide exceptions_list attributes Show exceptions_list attributes object

id string(nonempty) Required

ID of the exception container

Minimum length is 1.

list_id string(nonempty) Required

List ID of the exception container

Minimum length is 1.

namespace_type string Required

Determines the exceptions validity in rule's Kibana space

Values are agnostic or single.

type string Required

The exception type

Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.

false_positives array[string] Required

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.

from string(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.

Hide investigation_fields attribute Show investigation_fields attribute object

field_names array[string(nonempty)] Required

A string that does not contain only whitespace characters

At least 1 element. Minimum length of each is 1.

license string

The rule's license.

max_signals integer Required

Maximum number of alerts the rule can create during a single run (the rule’s Max alerts per run advanced setting value).

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.

Minimum value is 1. Default value is 100.

meta object

Placeholder for metadata about the rule.

This field is overwritten when you save changes to the rule’s settings.

Additional properties are allowed.

name string Required

A human-readable name for the rule.

Minimum length is 1.

namespace string

Has no effect.

note string

Notes to help investigate alerts produced by the rule.

outcome string

Values are exactMatch, aliasMatch, or conflict.

output_index string Deprecated

(deprecated) Has no effect.

references array[string] Required

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.

related_integrations array[object] Required

Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:

package: name of the package (required, unique id)

version: version of the package (required, semver-compatible)

integration: name of the integration of this package (optional, id within the package)

There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.

Hide related_integrations attributes Show related_integrations attributes object

integration string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

package string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

version string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

required_fields array[object] Required

Elasticsearch fields and their types that need to be present for the rule to function.

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.

Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.

Hide required_fields attributes Show required_fields attributes object

name string(nonempty) Required

Name of an Elasticsearch field

Minimum length is 1.

type string(nonempty) Required

Type of the Elasticsearch field

Minimum length is 1.

response_actions array[object]

One of:
Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object

Hide attributes Show attributes

action_type_id string Required

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

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

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[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.

Hide attributes Show attributes

action_type_id string Required

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object

Hide attributes Show attributes

command string Required

Value is isolate.

comment string

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.

risk_score integer 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

Minimum value is 0, maximum value is 100.

risk_score_mapping array[object] Required

Overrides generated alerts' risk_score with a value from the source event

Hide risk_score_mapping attributes Show risk_score_mapping attributes object

field string Required

Source event field used to override the default risk_score.

operator string Required

Value is equals.

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

Minimum value is 0, maximum value is 100.

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 string 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 are low, medium, high, or critical.

severity_mapping array[object] Required

Overrides generated alerts' severity with values from the source event

Hide severity_mapping attributes Show severity_mapping attributes object

field string Required

Source event field used to override the default severity.

operator string Required

Value is equals.

severity string 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 are low, medium, high, or critical.

value string Required

tags array[string] Required

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.

threat array[object] Required

Currently, only threats described using the MITRE ATT&CK™ framework are supported.

Hide threat attributes Show threat attributes object

framework string Required

Relevant attack framework

tactic object Required

Object containing information on the attack type

Hide tactic attributes Show tactic attributes object

id string Required

Tactic ID

name string Required

Tactic name

reference string Required

Tactic reference

technique array[object]

Array containing information on the attack techniques (optional)

Hide technique attributes Show technique attributes object

id string Required

Technique ID

name string Required

Technique name

reference string Required

Technique reference

subtechnique array[object]

Array containing more specific information on the attack technique.

Hide subtechnique attributes Show subtechnique attributes object

id string Required

Subtechnique ID

name string Required

Subtechnique name

reference string Required

Subtechnique reference

throttle string | null

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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 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.

It is not incremented on each update. Compare this to the revision field.

Minimum value is 1.

created_at string(date-time) Required

created_by string Required

execution_summary object

Summary of the last execution of a rule.

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

Hide execution_summary attribute Show execution_summary attribute object

last_execution object Required

Hide last_execution attributes Show last_execution attributes object

date string(date-time) Required

Date of the last execution

message string Required

metrics object Required

Hide metrics attributes Show metrics attributes object

execution_gap_duration_s integer

Duration in seconds of execution gap

Minimum value is 0.

frozen_indices_queried_count integer

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

Minimum value is 0.

gap_range object

Range of the execution gap

Hide gap_range attributes Show gap_range attributes object

gte string Required

Start date of the execution gap

lte string Required

End date of the execution gap

total_enrichment_duration_ms integer

Total time spent enriching documents during current rule execution cycle

Minimum value is 0.

total_indexing_duration_ms integer

Total time spent indexing documents during current rule execution cycle

Minimum value is 0.

total_search_duration_ms integer

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

Minimum value is 0.

status string Required

Status of the last execution

Values are going to run, running, partial failure, failed, or succeeded.

status_order integer Required

id string(uuid) Required

A dynamic unique identifier for the rule object. It is randomly generated when a rule is created and cannot be changed after that. It is always a UUID. It is unique within a given Kibana space. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have different object ids.

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

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.

Minimum value is 0.

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 object 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:
Security_Detections_API_ExternalRuleSource object Security_Detections_API_InternalRuleSource object

Type of rule source for externally sourced rules, i.e. rules that have an external source, such as the Elastic Prebuilt rules repo.

Hide attributes Show attributes

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

type string Required Discriminator

Value is external.

updated_at string(date-time) Required

updated_by string Required

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.

threshold object Required

Hide threshold attributes Show threshold attributes object

cardinality array[object]

The field on which the cardinality is applied.

Hide cardinality attributes Show cardinality attributes object

field string Required

The field on which to calculate and compare the cardinality.

value integer Required

The threshold value from which an alert is generated based on unique number of values of cardinality.field.

Minimum value is 0.

field string | array[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.

One of:
string-1 string array-2 array[string]

value integer Required

The threshold value from which an alert is generated.

Minimum value is 1.

type string Required Discriminator

Rule type

Value is threshold.

alert_suppression object

Defines alert suppression configuration.

Hide alert_suppression attribute Show alert_suppression attribute object

duration object Required

Hide duration attributes Show duration attributes object

unit string Required

Time unit

Values are s, m, or h.

value integer Required

Minimum value is 1.

data_view_id string

filters array

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

saved_id string

Kibana saved search used by the rule to create alerts.

language string Required

Values are kuery or lucene.

Hide attributes Show attributes

actions array[object] Required

Array defining the automated actions (notifications) taken when alerts are generated.

Hide actions attributes Show actions attributes object

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.

Additional properties are allowed.

frequency object

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

Hide frequency attributes Show frequency attributes object

notifyWhen string Required

Defines how often rules run actions.

Values are onActiveAlert, onThrottleInterval, or 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 string | null Required

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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.

Additional properties are allowed.

uuid string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

alias_purpose string

Values are savedObjectConversion or savedObjectImport.

alias_target_id string

author array[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 Required

The rule’s description.

Minimum length is 1.

enabled boolean Required

Determines whether the rule is enabled. Defaults to true.

exceptions_list array[object] Required

Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.

Hide exceptions_list attributes Show exceptions_list attributes object

id string(nonempty) Required

ID of the exception container

Minimum length is 1.

list_id string(nonempty) Required

List ID of the exception container

Minimum length is 1.

namespace_type string Required

Determines the exceptions validity in rule's Kibana space

Values are agnostic or single.

type string Required

The exception type

Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.

false_positives array[string] Required

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.

from string(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.

Hide investigation_fields attribute Show investigation_fields attribute object

field_names array[string(nonempty)] Required

A string that does not contain only whitespace characters

At least 1 element. Minimum length of each is 1.

license string

The rule's license.

max_signals integer Required

Maximum number of alerts the rule can create during a single run (the rule’s Max alerts per run advanced setting value).

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.

Minimum value is 1. Default value is 100.

meta object

Placeholder for metadata about the rule.

This field is overwritten when you save changes to the rule’s settings.

Additional properties are allowed.

name string Required

A human-readable name for the rule.

Minimum length is 1.

namespace string

Has no effect.

note string

Notes to help investigate alerts produced by the rule.

outcome string

Values are exactMatch, aliasMatch, or conflict.

output_index string Deprecated

(deprecated) Has no effect.

references array[string] Required

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.

related_integrations array[object] Required

Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:

package: name of the package (required, unique id)

version: version of the package (required, semver-compatible)

integration: name of the integration of this package (optional, id within the package)

There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.

Hide related_integrations attributes Show related_integrations attributes object

integration string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

package string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

version string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

required_fields array[object] Required

Elasticsearch fields and their types that need to be present for the rule to function.

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.

Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.

Hide required_fields attributes Show required_fields attributes object

name string(nonempty) Required

Name of an Elasticsearch field

Minimum length is 1.

type string(nonempty) Required

Type of the Elasticsearch field

Minimum length is 1.

response_actions array[object]

One of:
Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object

Hide attributes Show attributes

action_type_id string Required

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

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

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[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.

Hide attributes Show attributes

action_type_id string Required

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object

Hide attributes Show attributes

command string Required

Value is isolate.

comment string

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.

risk_score integer 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

Minimum value is 0, maximum value is 100.

risk_score_mapping array[object] Required

Overrides generated alerts' risk_score with a value from the source event

Hide risk_score_mapping attributes Show risk_score_mapping attributes object

field string Required

Source event field used to override the default risk_score.

operator string Required

Value is equals.

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

Minimum value is 0, maximum value is 100.

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 string 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 are low, medium, high, or critical.

severity_mapping array[object] Required

Overrides generated alerts' severity with values from the source event

Hide severity_mapping attributes Show severity_mapping attributes object

field string Required

Source event field used to override the default severity.

operator string Required

Value is equals.

severity string 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 are low, medium, high, or critical.

value string Required

tags array[string] Required

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.

threat array[object] Required

Currently, only threats described using the MITRE ATT&CK™ framework are supported.

Hide threat attributes Show threat attributes object

framework string Required

Relevant attack framework

tactic object Required

Object containing information on the attack type

Hide tactic attributes Show tactic attributes object

id string Required

Tactic ID

name string Required

Tactic name

reference string Required

Tactic reference

technique array[object]

Array containing information on the attack techniques (optional)

Hide technique attributes Show technique attributes object

id string Required

Technique ID

name string Required

Technique name

reference string Required

Technique reference

subtechnique array[object]

Array containing more specific information on the attack technique.

Hide subtechnique attributes Show subtechnique attributes object

id string Required

Subtechnique ID

name string Required

Subtechnique name

reference string Required

Subtechnique reference

throttle string | null

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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 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.

It is not incremented on each update. Compare this to the revision field.

Minimum value is 1.

created_at string(date-time) Required

created_by string Required

execution_summary object

Summary of the last execution of a rule.

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

Hide execution_summary attribute Show execution_summary attribute object

last_execution object Required

Hide last_execution attributes Show last_execution attributes object

date string(date-time) Required

Date of the last execution

message string Required

metrics object Required

Hide metrics attributes Show metrics attributes object

execution_gap_duration_s integer

Duration in seconds of execution gap

Minimum value is 0.

frozen_indices_queried_count integer

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

Minimum value is 0.

gap_range object

Range of the execution gap

Hide gap_range attributes Show gap_range attributes object

gte string Required

Start date of the execution gap

lte string Required

End date of the execution gap

total_enrichment_duration_ms integer

Total time spent enriching documents during current rule execution cycle

Minimum value is 0.

total_indexing_duration_ms integer

Total time spent indexing documents during current rule execution cycle

Minimum value is 0.

total_search_duration_ms integer

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

Minimum value is 0.

status string Required

Status of the last execution

Values are going to run, running, partial failure, failed, or succeeded.

status_order integer Required

id string(uuid) Required

A dynamic unique identifier for the rule object. It is randomly generated when a rule is created and cannot be changed after that. It is always a UUID. It is unique within a given Kibana space. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have different object ids.

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

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.

Minimum value is 0.

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 object 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:
Security_Detections_API_ExternalRuleSource object Security_Detections_API_InternalRuleSource object

Type of rule source for externally sourced rules, i.e. rules that have an external source, such as the Elastic Prebuilt rules repo.

Hide attributes Show attributes

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

type string Required Discriminator

Value is external.

updated_at string(date-time) Required

updated_by string Required

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.

threat_index array[string] Required

Elasticsearch indices used to check which field values generate alerts.

threat_mapping array[object] Required

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 Example of Threat Match rule which uses both and and or logic.

At least 1 element.

Hide threat_mapping attribute Show threat_mapping attribute object

entries array[object] Required

Hide entries attributes Show entries attributes object

field string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

type string Required

Value is mapping.

value string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

threat_query string Required

Query used to determine which fields in the Elasticsearch index are used for generating alerts.

type string Required Discriminator

Rule type

Value is threat_match.

alert_suppression object

Defines alert suppression configuration.

Hide alert_suppression attributes Show alert_suppression attributes object

duration object

Hide duration attributes Show duration attributes object

unit string Required

Time unit

Values are s, m, or h.

value integer Required

Minimum value is 1.

group_by array[string] Required

At least 1 but not more than 3 elements.

missing_fields_strategy string

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 are doNotSuppress or suppress.

concurrent_searches integer

Minimum value is 1.

data_view_id string

filters array

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

items_per_search integer

Minimum value is 1.

saved_id string

Kibana saved search used by the rule to create alerts.

threat_filters array

Query and filter context array used to filter documents from the Elasticsearch index containing the threat values

threat_indicator_path string

Defines the path to the threat indicator in the indicator documents (optional)

threat_language string

Values are kuery or lucene.

language string Required

Values are kuery or lucene.

Hide attributes Show attributes

actions array[object] Required

Array defining the automated actions (notifications) taken when alerts are generated.

Hide actions attributes Show actions attributes object

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.

Additional properties are allowed.

frequency object

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

Hide frequency attributes Show frequency attributes object

notifyWhen string Required

Defines how often rules run actions.

Values are onActiveAlert, onThrottleInterval, or 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 string | null Required

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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.

Additional properties are allowed.

uuid string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

alias_purpose string

Values are savedObjectConversion or savedObjectImport.

alias_target_id string

author array[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 Required

The rule’s description.

Minimum length is 1.

enabled boolean Required

Determines whether the rule is enabled. Defaults to true.

exceptions_list array[object] Required

Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.

Hide exceptions_list attributes Show exceptions_list attributes object

id string(nonempty) Required

ID of the exception container

Minimum length is 1.

list_id string(nonempty) Required

List ID of the exception container

Minimum length is 1.

namespace_type string Required

Determines the exceptions validity in rule's Kibana space

Values are agnostic or single.

type string Required

The exception type

Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.

false_positives array[string] Required

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.

from string(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.

Hide investigation_fields attribute Show investigation_fields attribute object

field_names array[string(nonempty)] Required

A string that does not contain only whitespace characters

At least 1 element. Minimum length of each is 1.

license string

The rule's license.

max_signals integer Required

Maximum number of alerts the rule can create during a single run (the rule’s Max alerts per run advanced setting value).

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.

Minimum value is 1. Default value is 100.

meta object

Placeholder for metadata about the rule.

This field is overwritten when you save changes to the rule’s settings.

Additional properties are allowed.

name string Required

A human-readable name for the rule.

Minimum length is 1.

namespace string

Has no effect.

note string

Notes to help investigate alerts produced by the rule.

outcome string

Values are exactMatch, aliasMatch, or conflict.

output_index string Deprecated

(deprecated) Has no effect.

references array[string] Required

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.

related_integrations array[object] Required

Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:

package: name of the package (required, unique id)

version: version of the package (required, semver-compatible)

integration: name of the integration of this package (optional, id within the package)

There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.

Hide related_integrations attributes Show related_integrations attributes object

integration string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

package string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

version string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

required_fields array[object] Required

Elasticsearch fields and their types that need to be present for the rule to function.

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.

Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.

Hide required_fields attributes Show required_fields attributes object

name string(nonempty) Required

Name of an Elasticsearch field

Minimum length is 1.

type string(nonempty) Required

Type of the Elasticsearch field

Minimum length is 1.

response_actions array[object]

One of:
Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object

Hide attributes Show attributes

action_type_id string Required

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

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

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[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.

Hide attributes Show attributes

action_type_id string Required

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object

Hide attributes Show attributes

command string Required

Value is isolate.

comment string

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.

risk_score integer 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

Minimum value is 0, maximum value is 100.

risk_score_mapping array[object] Required

Overrides generated alerts' risk_score with a value from the source event

Hide risk_score_mapping attributes Show risk_score_mapping attributes object

field string Required

Source event field used to override the default risk_score.

operator string Required

Value is equals.

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

Minimum value is 0, maximum value is 100.

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 string 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 are low, medium, high, or critical.

severity_mapping array[object] Required

Overrides generated alerts' severity with values from the source event

Hide severity_mapping attributes Show severity_mapping attributes object

field string Required

Source event field used to override the default severity.

operator string Required

Value is equals.

severity string 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 are low, medium, high, or critical.

value string Required

tags array[string] Required

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.

threat array[object] Required

Currently, only threats described using the MITRE ATT&CK™ framework are supported.

Hide threat attributes Show threat attributes object

framework string Required

Relevant attack framework

tactic object Required

Object containing information on the attack type

Hide tactic attributes Show tactic attributes object

id string Required

Tactic ID

name string Required

Tactic name

reference string Required

Tactic reference

technique array[object]

Array containing information on the attack techniques (optional)

Hide technique attributes Show technique attributes object

id string Required

Technique ID

name string Required

Technique name

reference string Required

Technique reference

subtechnique array[object]

Array containing more specific information on the attack technique.

Hide subtechnique attributes Show subtechnique attributes object

id string Required

Subtechnique ID

name string Required

Subtechnique name

reference string Required

Subtechnique reference

throttle string | null

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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 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.

It is not incremented on each update. Compare this to the revision field.

Minimum value is 1.

created_at string(date-time) Required

created_by string Required

execution_summary object

Summary of the last execution of a rule.

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

Hide execution_summary attribute Show execution_summary attribute object

last_execution object Required

Hide last_execution attributes Show last_execution attributes object

date string(date-time) Required

Date of the last execution

message string Required

metrics object Required

Hide metrics attributes Show metrics attributes object

execution_gap_duration_s integer

Duration in seconds of execution gap

Minimum value is 0.

frozen_indices_queried_count integer

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

Minimum value is 0.

gap_range object

Range of the execution gap

Hide gap_range attributes Show gap_range attributes object

gte string Required

Start date of the execution gap

lte string Required

End date of the execution gap

total_enrichment_duration_ms integer

Total time spent enriching documents during current rule execution cycle

Minimum value is 0.

total_indexing_duration_ms integer

Total time spent indexing documents during current rule execution cycle

Minimum value is 0.

total_search_duration_ms integer

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

Minimum value is 0.

status string Required

Status of the last execution

Values are going to run, running, partial failure, failed, or succeeded.

status_order integer Required

id string(uuid) Required

A dynamic unique identifier for the rule object. It is randomly generated when a rule is created and cannot be changed after that. It is always a UUID. It is unique within a given Kibana space. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have different object ids.

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

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.

Minimum value is 0.

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 object 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:
Security_Detections_API_ExternalRuleSource object Security_Detections_API_InternalRuleSource object

Type of rule source for externally sourced rules, i.e. rules that have an external source, such as the Elastic Prebuilt rules repo.

Hide attributes Show attributes

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

type string Required Discriminator

Value is external.

updated_at string(date-time) Required

updated_by string Required

anomaly_threshold integer Required

Anomaly score threshold above which the rule creates an alert. Valid values are from 0 to 100.

Minimum value is 0.

machine_learning_job_id string | array[string] Required

Machine learning job ID(s) the rule monitors for anomaly scores.

One of:
string-1 string array-2 array[string]

type string Required Discriminator

Rule type

Value is machine_learning.

alert_suppression object

Defines alert suppression configuration.

Hide alert_suppression attributes Show alert_suppression attributes object

duration object

Hide duration attributes Show duration attributes object

unit string Required

Time unit

Values are s, m, or h.

value integer Required

Minimum value is 1.

group_by array[string] Required

At least 1 but not more than 3 elements.

missing_fields_strategy string

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 are doNotSuppress or suppress.

Hide attributes Show attributes

actions array[object] Required

Array defining the automated actions (notifications) taken when alerts are generated.

Hide actions attributes Show actions attributes object

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.

Additional properties are allowed.

frequency object

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

Hide frequency attributes Show frequency attributes object

notifyWhen string Required

Defines how often rules run actions.

Values are onActiveAlert, onThrottleInterval, or 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 string | null Required

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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.

Additional properties are allowed.

uuid string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

alias_purpose string

Values are savedObjectConversion or savedObjectImport.

alias_target_id string

author array[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 Required

The rule’s description.

Minimum length is 1.

enabled boolean Required

Determines whether the rule is enabled. Defaults to true.

exceptions_list array[object] Required

Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.

Hide exceptions_list attributes Show exceptions_list attributes object

id string(nonempty) Required

ID of the exception container

Minimum length is 1.

list_id string(nonempty) Required

List ID of the exception container

Minimum length is 1.

namespace_type string Required

Determines the exceptions validity in rule's Kibana space

Values are agnostic or single.

type string Required

The exception type

Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.

false_positives array[string] Required

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.

from string(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.

Hide investigation_fields attribute Show investigation_fields attribute object

field_names array[string(nonempty)] Required

A string that does not contain only whitespace characters

At least 1 element. Minimum length of each is 1.

license string

The rule's license.

max_signals integer Required

Maximum number of alerts the rule can create during a single run (the rule’s Max alerts per run advanced setting value).

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.

Minimum value is 1. Default value is 100.

meta object

Placeholder for metadata about the rule.

This field is overwritten when you save changes to the rule’s settings.

Additional properties are allowed.

name string Required

A human-readable name for the rule.

Minimum length is 1.

namespace string

Has no effect.

note string

Notes to help investigate alerts produced by the rule.

outcome string

Values are exactMatch, aliasMatch, or conflict.

output_index string Deprecated

(deprecated) Has no effect.

references array[string] Required

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.

related_integrations array[object] Required

Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:

package: name of the package (required, unique id)

version: version of the package (required, semver-compatible)

integration: name of the integration of this package (optional, id within the package)

There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.

Hide related_integrations attributes Show related_integrations attributes object

integration string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

package string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

version string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

required_fields array[object] Required

Elasticsearch fields and their types that need to be present for the rule to function.

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.

Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.

Hide required_fields attributes Show required_fields attributes object

name string(nonempty) Required

Name of an Elasticsearch field

Minimum length is 1.

type string(nonempty) Required

Type of the Elasticsearch field

Minimum length is 1.

response_actions array[object]

One of:
Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object

Hide attributes Show attributes

action_type_id string Required

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

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

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[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.

Hide attributes Show attributes

action_type_id string Required

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object

Hide attributes Show attributes

command string Required

Value is isolate.

comment string

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.

risk_score integer 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

Minimum value is 0, maximum value is 100.

risk_score_mapping array[object] Required

Overrides generated alerts' risk_score with a value from the source event

Hide risk_score_mapping attributes Show risk_score_mapping attributes object

field string Required

Source event field used to override the default risk_score.

operator string Required

Value is equals.

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

Minimum value is 0, maximum value is 100.

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 string 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 are low, medium, high, or critical.

severity_mapping array[object] Required

Overrides generated alerts' severity with values from the source event

Hide severity_mapping attributes Show severity_mapping attributes object

field string Required

Source event field used to override the default severity.

operator string Required

Value is equals.

severity string 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 are low, medium, high, or critical.

value string Required

tags array[string] Required

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.

threat array[object] Required

Currently, only threats described using the MITRE ATT&CK™ framework are supported.

Hide threat attributes Show threat attributes object

framework string Required

Relevant attack framework

tactic object Required

Object containing information on the attack type

Hide tactic attributes Show tactic attributes object

id string Required

Tactic ID

name string Required

Tactic name

reference string Required

Tactic reference

technique array[object]

Array containing information on the attack techniques (optional)

Hide technique attributes Show technique attributes object

id string Required

Technique ID

name string Required

Technique name

reference string Required

Technique reference

subtechnique array[object]

Array containing more specific information on the attack technique.

Hide subtechnique attributes Show subtechnique attributes object

id string Required

Subtechnique ID

name string Required

Subtechnique name

reference string Required

Subtechnique reference

throttle string | null

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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 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.

It is not incremented on each update. Compare this to the revision field.

Minimum value is 1.

created_at string(date-time) Required

created_by string Required

execution_summary object

Summary of the last execution of a rule.

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

Hide execution_summary attribute Show execution_summary attribute object

last_execution object Required

Hide last_execution attributes Show last_execution attributes object

date string(date-time) Required

Date of the last execution

message string Required

metrics object Required

Hide metrics attributes Show metrics attributes object

execution_gap_duration_s integer

Duration in seconds of execution gap

Minimum value is 0.

frozen_indices_queried_count integer

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

Minimum value is 0.

gap_range object

Range of the execution gap

Hide gap_range attributes Show gap_range attributes object

gte string Required

Start date of the execution gap

lte string Required

End date of the execution gap

total_enrichment_duration_ms integer

Total time spent enriching documents during current rule execution cycle

Minimum value is 0.

total_indexing_duration_ms integer

Total time spent indexing documents during current rule execution cycle

Minimum value is 0.

total_search_duration_ms integer

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

Minimum value is 0.

status string Required

Status of the last execution

Values are going to run, running, partial failure, failed, or succeeded.

status_order integer Required

id string(uuid) Required

A dynamic unique identifier for the rule object. It is randomly generated when a rule is created and cannot be changed after that. It is always a UUID. It is unique within a given Kibana space. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have different object ids.

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

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.

Minimum value is 0.

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 object 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:
Security_Detections_API_ExternalRuleSource object Security_Detections_API_InternalRuleSource object

Type of rule source for externally sourced rules, i.e. rules that have an external source, such as the Elastic Prebuilt rules repo.

Hide attributes Show attributes

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

type string Required Discriminator

Value is external.

updated_at string(date-time) Required

updated_by string Required

history_window_start string(nonempty) Required

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.

Minimum length is 1.

new_terms_fields array[string] Required

Fields to monitor for new values.

At least 1 but not more than 3 elements.

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.

type string Required Discriminator

Rule type

Value is new_terms.

alert_suppression object

Defines alert suppression configuration.

Hide alert_suppression attributes Show alert_suppression attributes object

duration object

Hide duration attributes Show duration attributes object

unit string Required

Time unit

Values are s, m, or h.

value integer Required

Minimum value is 1.

group_by array[string] Required

At least 1 but not more than 3 elements.

missing_fields_strategy string

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 are doNotSuppress or suppress.

data_view_id string

filters array

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

language string Required

Values are kuery or lucene.

Hide attributes Show attributes

actions array[object] Required

Array defining the automated actions (notifications) taken when alerts are generated.

Hide actions attributes Show actions attributes object

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.

Additional properties are allowed.

frequency object

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

Hide frequency attributes Show frequency attributes object

notifyWhen string Required

Defines how often rules run actions.

Values are onActiveAlert, onThrottleInterval, or 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 string | null Required

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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.

Additional properties are allowed.

uuid string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

alias_purpose string

Values are savedObjectConversion or savedObjectImport.

alias_target_id string

author array[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 Required

The rule’s description.

Minimum length is 1.

enabled boolean Required

Determines whether the rule is enabled. Defaults to true.

exceptions_list array[object] Required

Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.

Hide exceptions_list attributes Show exceptions_list attributes object

id string(nonempty) Required

ID of the exception container

Minimum length is 1.

list_id string(nonempty) Required

List ID of the exception container

Minimum length is 1.

namespace_type string Required

Determines the exceptions validity in rule's Kibana space

Values are agnostic or single.

type string Required

The exception type

Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.

false_positives array[string] Required

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.

from string(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.

Hide investigation_fields attribute Show investigation_fields attribute object

field_names array[string(nonempty)] Required

A string that does not contain only whitespace characters

At least 1 element. Minimum length of each is 1.

license string

The rule's license.

max_signals integer Required

Maximum number of alerts the rule can create during a single run (the rule’s Max alerts per run advanced setting value).

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.

Minimum value is 1. Default value is 100.

meta object

Placeholder for metadata about the rule.

This field is overwritten when you save changes to the rule’s settings.

Additional properties are allowed.

name string Required

A human-readable name for the rule.

Minimum length is 1.

namespace string

Has no effect.

note string

Notes to help investigate alerts produced by the rule.

outcome string

Values are exactMatch, aliasMatch, or conflict.

output_index string Deprecated

(deprecated) Has no effect.

references array[string] Required

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.

related_integrations array[object] Required

Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:

package: name of the package (required, unique id)

version: version of the package (required, semver-compatible)

integration: name of the integration of this package (optional, id within the package)

There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.

Hide related_integrations attributes Show related_integrations attributes object

integration string(nonempty)

A string that does not contain only whitespace characters

Minimum length is 1.

package string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

version string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

required_fields array[object] Required

Elasticsearch fields and their types that need to be present for the rule to function.

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.

Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.

Hide required_fields attributes Show required_fields attributes object

name string(nonempty) Required

Name of an Elasticsearch field

Minimum length is 1.

type string(nonempty) Required

Type of the Elasticsearch field

Minimum length is 1.

response_actions array[object]

One of:
Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object

Hide attributes Show attributes

action_type_id string Required

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

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

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[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.

Hide attributes Show attributes

action_type_id string Required

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object

Hide attributes Show attributes

command string Required

Value is isolate.

comment string

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.

risk_score integer 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

Minimum value is 0, maximum value is 100.

risk_score_mapping array[object] Required

Overrides generated alerts' risk_score with a value from the source event

Hide risk_score_mapping attributes Show risk_score_mapping attributes object

field string Required

Source event field used to override the default risk_score.

operator string Required

Value is equals.

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

Minimum value is 0, maximum value is 100.

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 string 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 are low, medium, high, or critical.

severity_mapping array[object] Required

Overrides generated alerts' severity with values from the source event

Hide severity_mapping attributes Show severity_mapping attributes object

field string Required

Source event field used to override the default severity.

operator string Required

Value is equals.

severity string 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 are low, medium, high, or critical.

value string Required

tags array[string] Required

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.

threat array[object] Required

Currently, only threats described using the MITRE ATT&CK™ framework are supported.

Hide threat attributes Show threat attributes object

framework string Required

Relevant attack framework

tactic object Required

Object containing information on the attack type

Hide tactic attributes Show tactic attributes object

id string Required

Tactic ID

name string Required

Tactic name

reference string Required

Tactic reference

technique array[object]

Array containing information on the attack techniques (optional)

Hide technique attributes Show technique attributes object

id string Required

Technique ID

name string Required

Technique name

reference string Required

Technique reference

subtechnique array[object]

Array containing more specific information on the attack technique.

Hide subtechnique attributes Show subtechnique attributes object

id string Required

Subtechnique ID

name string Required

Subtechnique name

reference string Required

Subtechnique reference

throttle string | null

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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 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.

It is not incremented on each update. Compare this to the revision field.

Minimum value is 1.

created_at string(date-time) Required

created_by string Required

execution_summary object

Summary of the last execution of a rule.

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

Hide execution_summary attribute Show execution_summary attribute object

last_execution object Required

Hide last_execution attributes Show last_execution attributes object

date string(date-time) Required

Date of the last execution

message string Required

metrics object Required

Hide metrics attributes Show metrics attributes object

execution_gap_duration_s integer

Duration in seconds of execution gap

Minimum value is 0.

frozen_indices_queried_count integer

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

Minimum value is 0.

gap_range object

Range of the execution gap

Hide gap_range attributes Show gap_range attributes object

gte string Required

Start date of the execution gap

lte string Required

End date of the execution gap

total_enrichment_duration_ms integer

Total time spent enriching documents during current rule execution cycle

Minimum value is 0.

total_indexing_duration_ms integer

Total time spent indexing documents during current rule execution cycle

Minimum value is 0.

total_search_duration_ms integer

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

Minimum value is 0.

status string Required

Status of the last execution

Values are going to run, running, partial failure, failed, or succeeded.

status_order integer Required

id string(uuid) Required

A dynamic unique identifier for the rule object. It is randomly generated when a rule is created and cannot be changed after that. It is always a UUID. It is unique within a given Kibana space. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have different object ids.

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

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.

Minimum value is 0.

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 object 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:
Security_Detections_API_ExternalRuleSource object Security_Detections_API_InternalRuleSource object

Type of rule source for externally sourced rules, i.e. rules that have an external source, such as the Elastic Prebuilt rules repo.

Hide attributes Show attributes

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

type string Required Discriminator

Value is external.

updated_at string(date-time) Required

updated_by string Required

alert_suppression object

Defines alert suppression configuration.

Hide alert_suppression attributes Show alert_suppression attributes object

duration object

Hide duration attributes Show duration attributes object

unit string Required

Time unit

Values are s, m, or h.

value integer Required

Minimum value is 1.

group_by array[string] Required

At least 1 but not more than 3 elements.

missing_fields_strategy string

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 are doNotSuppress or suppress.

language string Required

Value is esql.

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.

type string Required Discriminator

Rule type

Value is esql.

summary object Required

A rule can only be skipped when the bulk action to be performed on it results in nothing being done. For example, if the edit action is used to add a tag to a rule that already has that tag, or to delete an index pattern that is not specified in a rule. Objects returned in attributes.results.skipped will only include rules' id, name, and skip_reason.

Hide summary attributes Show summary attributes object

failed integer Required

skipped integer Required

succeeded integer Required

total integer Required

message string

rules_count integer

status_code integer

success boolean

POST /api/detection_engine/rules/_bulk_action

curl \
 --request POST 'https://<KIBANA_URL>/api/detection_engine/rules/_bulk_action' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"query":"alert.attributes.tags: \"test\"","action":"enable"}'

Request examples

The following request activates all rules with the test tag.

{
  "query": "alert.attributes.tags: \"test\"",
  "action": "enable"
}

The following request enables the rule with the specified ID.

{
  "ids": [
    "748694f0-6977-4ea5-8384-cd2e39730779"
  ],
  "action": "enable"
}

The following request disables the rule with the specified ID.

{
  "ids": [
    "748694f0-6977-4ea5-8384-cd2e39730779"
  ],
  "action": "disable"
}

The following request duplicates rules with the specified IDs, including exceptions but not expired exceptions.

{
  "ids": [
    "748694f0-6977-4ea5-8384-cd2e39730779",
    "461a4c22-416e-4009-a9a7-cf79656454bf"
  ],
  "action": "duplicate",
  "duplicate": {
    "include_exceptions": true,
    "include_expired_exceptions": false
  }
}

The following request deletes the rule with the specified ID.

{
  "ids": [
    "cf4abfd1-7c37-4519-ab0f-5ea5c75fac60"
  ],
  "action": "delete"
}

The following request runs the rule with the specified ID within the given date range.

{
  "ids": [
    "748694f0-6977-4ea5-8384-cd2e39730779"
  ],
  "run": {
    "end_date": "2025-03-10T23:59:59.999Z",
    "start_date": "2025-03-01T00:00:00.000Z"
  },
  "action": "run"
}

The following request exports the rules with the specified IDs.

{
  "ids": [
    "748694f0-6977-4ea5-8384-cd2e39730779"
  ],
  "action": "export"
}

The following request will validate that the add_index_patterns bulk action can be successfully applied to three rules. The dry_run parameter is specified in query parameters, e.g. POST api/detection_engine/rules/_bulk_action?dry_run=true

{
  "ids": [
    "81aa0480-06af-11ed-94fb-dd1a0597d8d2",
    "dc015d10-0831-11ed-ac8b-05a222bd8d4a",
    "de8f5af0-0831-11ed-ac8b-05a222bd8d4a"
  ],
  "edit": [
    {
      "type": "add_index_patterns",
      "value": [
        "test-*"
      ]
    }
  ],
  "action": "edit"
}

The following request adds the tag "tag-1" to the rules with the specified IDs. If the tag already exists for a rule, no changes are made.

{
  "ids": [
    "8bc7dad0-9320-11ec-9265-8b772383a08d",
    "8e5c1a40-9320-11ec-9265-8b772383a08d"
  ],
  "edit": [
    {
      "type": "add_tags",
      "value": [
        "tag-1"
      ]
    }
  ],
  "action": "edit"
}

The following request adds two tags at the same time, tag-1 and tag-2, to the rules that have the IDs sent in the payload. If the tags already exist for a rule, no changes are made.

{
  "ids": [
    "8bc7dad0-9320-11ec-9265-8b772383a08d",
    "8e5c1a40-9320-11ec-9265-8b772383a08d"
  ],
  "edit": [
    {
      "type": "add_tags",
      "value": [
        "tag-1",
        "tag-2"
      ]
    }
  ],
  "action": "edit"
}

The following request removes the tag "tag-1" from the rules with the specified IDs. If the tag does not exist for a rule, no changes are made.

{
  "ids": [
    "8bc7dad0-9320-11ec-9265-8b772383a08d",
    "8e5c1a40-9320-11ec-9265-8b772383a08d"
  ],
  "edit": [
    {
      "type": "delete_tags",
      "value": [
        "tag-1"
      ]
    }
  ],
  "action": "edit"
}

The following request sets the tags "tag-1" and "tag-2" for the rules with the specified IDs, overwriting any existing tags. If the set of tags is the same as the existing tags, no changes are made.

{
  "ids": [
    "8bc7dad0-9320-11ec-9265-8b772383a08d",
    "8e5c1a40-9320-11ec-9265-8b772383a08d"
  ],
  "edit": [
    {
      "type": "set_tags",
      "value": [
        "tag-1",
        "tag-2"
      ]
    }
  ],
  "action": "edit"
}

The following request adds the index pattern "test-*" to the rules with the specified IDs. If the index pattern already exists for a rule, no changes are made.

{
  "ids": [
    "81aa0480-06af-11ed-94fb-dd1a0597d8d2",
    "dc015d10-0831-11ed-ac8b-05a222bd8d4a"
  ],
  "edit": [
    {
      "type": "add_index_patterns",
      "value": [
        "test-*"
      ]
    }
  ],
  "action": "edit"
}

The following request removes the index pattern "test-*" from the rules with the specified IDs. If the index pattern does not exist for a rule, no changes are made.

{
  "ids": [
    "81aa0480-06af-11ed-94fb-dd1a0597d8d2",
    "dc015d10-0831-11ed-ac8b-05a222bd8d4a"
  ],
  "edit": [
    {
      "type": "delete_index_patterns",
      "value": [
        "test-*"
      ]
    }
  ],
  "action": "edit"
}

The following request sets the index patterns "test-*" and "prod-*" for the rules with the specified IDs, overwriting any existing index patterns. If the set of index patterns is the same as the existing index patterns, no changes are made.

{
  "ids": [
    "81aa0480-06af-11ed-94fb-dd1a0597d8d2",
    "dc015d10-0831-11ed-ac8b-05a222bd8d4a"
  ],
  "edit": [
    {
      "type": "set_index_patterns",
      "value": [
        "test-*"
      ]
    }
  ],
  "action": "edit"
}

The following request adds investigation field to the rules with the specified IDs.

{
  "ids": [
    "12345678-1234-1234-1234-1234567890ab",
    "87654321-4321-4321-4321-0987654321ba"
  ],
  "edit": [
    {
      "type": "add_investigation_fields",
      "value": {
        "field_names": [
          "alert.status"
        ]
      }
    }
  ],
  "action": "edit"
}

The following request deletes investigation fields from the rules with the specified IDs. If the field does not exist for a rule, no changes are made.

{
  "ids": [
    "12345678-1234-1234-1234-1234567890ab",
    "87654321-4321-4321-4321-0987654321ba"
  ],
  "edit": [
    {
      "type": "delete_investigation_fields"
    }
  ],
  "value": [
    "field1",
    "field2"
  ],
  "action": "edit"
}

The following request sets investigation fields for the rules with the specified IDs, overwriting any existing investigation fields. If the set of investigation fields is the same as the existing investigation fields, no changes are made.

{
  "ids": [
    "12345678-1234-1234-1234-1234567890ab",
    "87654321-4321-4321-4321-0987654321ba"
  ],
  "edit": [
    {
      "type": "set_investigation_fields",
      "value": [
        "field1",
        "field2"
      ]
    }
  ],
  "action": "edit"
}

The following request sets a timeline template for the rules with the specified IDs. If the same timeline template is already set for a rule, no changes are made.

{
  "ids": [
    "eacdfc95-e007-41c9-986e-4b2cbdfdc71b"
  ],
  "edit": [
    {
      "type": "set_timeline",
      "value": {
        "timeline_id": "3e827bab-838a-469f-bd1e-5e19a2bff2fd",
        "timeline_title": "Alerts Involving a Single User Timeline"
      }
    }
  ],
  "action": "edit"
}

The following request sets a schedule for the rules with the specified IDs. If the same schedule is already set for a rule, no changes are made.

{
  "ids": [
    "99887766-5544-3322-1100-aabbccddeeff"
  ],
  "edit": [
    {
      "type": "set_schedule",
      "value": {
        "interval": "1h",
        "lookback": "30m"
      }
    }
  ],
  "action": "edit"
}

The following request adds rule actions to the rules with the specified IDs. Each new action receives its own unique ID.

{
  "ids": [
    "9e946bfc-3118-4c77-bb25-67d781191928"
  ],
  "edit": [
    {
      "type": "add_rule_actions",
      "value": {
        "actions": [
          {
            "id": "20fbf986-a270-460e-80f3-7b83c08b430f",
            "group": "default",
            "params": {
              "body": "The message body"
            }
          }
        ]
      }
    }
  ],
  "action": "edit"
}

The following request sets rule actions for the rules with the specified IDs. Each action receives its own unique ID.

{
  "ids": [
    "9e946bfc-3118-4c77-bb25-67d781191928"
  ],
  "edit": [
    {
      "type": "set_rule_actions",
      "value": {
        "actions": [
          {
            "id": "20fbf986-a270-460e-80f3-7b83c08b430f",
            "group": "default",
            "params": {
              "body": "The message body"
            }
          }
        ]
      }
    }
  ],
  "action": "edit"
}

The following request adds rule actions to the rules with the specified IDs. Each new action receives its own unique ID.

{
  "ids": [
    "9e946bfc-3118-4c77-bb25-67d781191921"
  ],
  "edit": [
    {
      "type": "add_rule_actions",
      "value": {
        "actions": [
          {
            "id": "20fbf986-a270-460e-80f3-7b83c08b430f",
            "group": "default3",
            "params": {
              "body": "The message body"
            }
          }
        ]
      }
    }
  ],
  "action": "edit"
}

The following request adds rule actions to the rules with the specified IDs. Each new action receives its own unique ID.

{
  "ids": [
    "9e946bfc-3118-4c77-bb25-67d781191921"
  ],
  "edit": [
    {
      "type": "add_rule_actions",
      "value": {
        "actions": [
          {
            "id": "20fbf986-a270-460e-80f3-7b83c08b430f",
            "group": "default3",
            "params": {
              "to": "address@domain.com",
              "message": "The message body",
              "subject": "Subject"
            }
          }
        ]
      }
    }
  ],
  "action": "edit"
}

The following request adds rule actions to the rules with the specified IDs. Each new action receives its own unique ID.

{
  "ids": [
    "9e946bfc-3118-4c77-bb25-67d781191921"
  ],
  "edit": [
    {
      "type": "add_rule_actions",
      "value": {
        "actions": [
          {
            "id": "20fbf986-a270-460e-80f3-7b83c08b430f",
            "group": "default3",
            "params": {
              "message": "The content of the message"
            }
          }
        ]
      }
    }
  ],
  "action": "edit"
}

The following request adds rule actions to the rules with the specified IDs. Each new action receives its own unique ID.

{
  "ids": [
    "9e946bfc-3118-4c77-bb25-67d781191921"
  ],
  "edit": [
    {
      "type": "add_rule_actions",
      "value": {
        "actions": [
          {
            "id": "20fbf986-a270-460e-80f3-7b83c08b430f",
            "group": "default3",
            "params": {
              "summary": "The message body",
              "severity": "critical",
              "timestamp": "2023-10-31T00:00:00.000Z",
              "eventAction": "trigger"
            }
          }
        ]
      }
    }
  ],
  "action": "edit"
}

Response examples (200)

In this response one rule was updated and one was skipped. Objects returned in attributes.results.skipped will only include rules' id, name, and skip_reason.

{
  "success": true,
  "attributes": {
    "results": {
      "created": [],
      "deleted": [],
      "skipped": [
        {
          "id": "51658332-a15e-4c9e-912a-67214e2e2359",
          "name": "Skipped rule",
          "skip_reason": "RULE_NOT_MODIFIED"
        }
      ],
      "updated": [
        {
          "id": "8bc7dad0-9320-11ec-9265-8b772383a08d",
          "to": "now",
          "from": "now-45m",
          "name": "DNS Tunneling [Duplicate]",
          "tags": [
            "Elastic",
            "Network",
            "Threat Detection",
            "ML"
          ],
          "type": "machine_learning",
          "setup": "",
          "author": [
            "Elastic"
          ],
          "threat": [],
          "enabled": true,
          "license": "Elastic License v2",
          "rule_id": "7289bf08-4e91-4c70-bf01-e04c4c5d7756",
          "version": 6,
          "interval": "15m",
          "severity": "low",
          "immutable": false,
          "created_at": "2022-02-21T14:14:13.801Z",
          "created_by": "elastic",
          "references": [
            "https://www.elastic.co/guide/en/security/current/prebuilt-ml-jobs.html"
          ],
          "risk_score": 21,
          "updated_at": "2022-02-21T17:05:50.883Z",
          "updated_by": "elastic",
          "description": "A machine learning job detected unusually large numbers of DNS queries for a single top-level DNS domain, which is often used for DNS tunneling. DNS tunneling can be used for command-and-control, persistence, or data exfiltration activity. For example, dnscat tends to generate many DNS questions for a top-level domain as it uses the DNS protocol to tunnel data.",
          "max_signals": 100,
          "exceptions_list": [],
          "false_positives": [
            "DNS domains that use large numbers of child domains, such as software or content distribution networks, can trigger this alert and such parent domains can be excluded."
          ],
          "required_fields": [],
          "severity_mapping": [],
          "anomaly_threshold": 50,
          "execution_summary": {
            "last_execution": {
              "date": "2022-03-23T16:06:12.787Z",
              "status": "partial failure",
              "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": {
                "execution_gap_duration_s": 0,
                "total_search_duration_ms": 135,
                "total_indexing_duration_ms": 15
              },
              "status_order": 20
            }
          },
          "risk_score_mapping": [],
          "related_integrations": [],
          "machine_learning_job_id": [
            "packetbeat_dns_tunneling"
          ]
        }
      ]
    },
    "summary": {
      "total": 2,
      "failed": 0,
      "skipped": 1,
      "succeeded": 1
    }
  },
  "rules_count": 1
}

If processing of any rule fails, a partial error outputs the ID and/or name of the affected rule and the corresponding error, as well as successfully processed rules (in the same format as a successful 200 request).

{
  "value": {
    "message": "Bulk edit partially failed",
    "success": false,
    "attributes": {
      "errors": [
        {
          "rules": [
            {
              "id": "8bc7dad0-9320-11ec-9265-8b772383a08d",
              "name": "DNS Tunneling [Duplicate]"
            }
          ],
          "message": "Index patterns can't be added. Machine learning rule doesn't have index patterns property",
          "status_code": 500
        }
      ],
      "results": {
        "created": [],
        "deleted": [],
        "skipped": [],
        "updated": [
          {
            "id": "8e5c1a40-9320-11ec-9265-8b772383a08d",
            "to": "now",
            "from": "now-6m",
            "name": "External Alerts [Duplicate]",
            "tags": [
              "Elastic",
              "Network",
              "Windows",
              "APM",
              "macOS",
              "Linux"
            ],
            "type": "query",
            "index": [
              "apm-*-transaction*",
              "traces-apm*",
              "auditbeat-*",
              "filebeat-*",
              "logs-*",
              "packetbeat-*",
              "winlogbeat-*",
              "added-by-id-*"
            ],
            "query": "event.kind:alert and not event.module:(endgame or endpoint)\n",
            "setup": "",
            "author": [
              "Elastic"
            ],
            "threat": [],
            "actions": [],
            "enabled": true,
            "license": "Elastic License v2",
            "rule_id": "941faf98-0cdc-4569-b16d-4af962914d61",
            "version": 5,
            "interval": "5m",
            "language": "kuery",
            "severity": "medium",
            "immutable": false,
            "created_at": "2022-02-21T14:14:17.883Z",
            "created_by": "elastic",
            "references": [],
            "risk_score": 47,
            "updated_at": "2022-02-21T16:56:22.818Z",
            "updated_by": "elastic",
            "description": "Generates a detection alert for each external alert written to the configured indices. Enabling this rule allows you to immediately begin investigating external alerts in the app.",
            "max_signals": 10000,
            "exceptions_list": [],
            "false_positives": [],
            "required_fields": [],
            "severity_mapping": [
              {
                "field": "event.severity",
                "value": "21",
                "operator": "equals",
                "severity": "low"
              },
              {
                "field": "event.severity",
                "value": "47",
                "operator": "equals",
                "severity": "medium"
              },
              {
                "field": "event.severity",
                "value": "73",
                "operator": "equals",
                "severity": "high"
              },
              {
                "field": "event.severity",
                "value": "99",
                "operator": "equals",
                "severity": "critical"
              }
            ],
            "execution_summary": {
              "last_execution": {
                "date": "2022-03-23T16:06:12.787Z",
                "status": "partial failure",
                "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": {
                  "execution_gap_duration_s": 0,
                  "total_search_duration_ms": 135,
                  "total_indexing_duration_ms": 15
                },
                "status_order": 20
              }
            },
            "risk_score_mapping": [
              {
                "field": "event.risk_score",
                "value": "",
                "operator": "equals"
              }
            ],
            "rule_name_override": "message",
            "timestamp_override": "event.ingested",
            "related_integrations": []
          }
        ]
      },
      "summary": {
        "total": 2,
        "failed": 1,
        "skipped": 0,
        "succeeded": 1
      }
    },
    "rules_count": 2,
    "status_code": 500
  }
}

The attributes.errors section of the response shows that two rules failed to update and one succeeded. The same results would be returned if you ran the request without dry run mode enabled. Notice that there are no arrays in attributes.results. In dry run mode, rule updates are not applied and saved to Elasticsearch, so the endpoint wouldn’t return results for rules that have been updated, created, or deleted.

{
  "message": "Bulk edit partially failed",
  "attributes": {
    "errors": [
      {
        "rules": [
          {
            "id": "81aa0480-06af-11ed-94fb-dd1a0597d8d2",
            "name": "Unusual AWS Command for a User"
          }
        ],
        "message": "Elastic rule can't be edited",
        "err_code": "IMMUTABLE",
        "status_code": 500
      },
      {
        "rules": [
          {
            "id": "dc015d10-0831-11ed-ac8b-05a222bd8d4a",
            "name": "Suspicious Powershell Script [Duplicate]"
          }
        ],
        "message": "Machine learning rule doesn't have index patterns",
        "err_code": "MACHINE_LEARNING_INDEX_PATTERN",
        "status_code": 500
      }
    ],
    "results": {
      "created": [],
      "deleted": [],
      "skipped": [],
      "updated": []
    },
    "summary": {
      "total": 3,
      "failed": 2,
      "skipped": 0,
      "succeeded": 1
    }
  },
  "status_code": 500
}

This example presents the successful setting of tags for 2 rules. There was a difference between the set of tags that were being added and the tags that were already set in the rules, that's why the rules were updated.

{
  "success": true,
  "attributes": {
    "results": {
      "created": [],
      "deleted": [],
      "skipped": [],
      "updated": [
        {
          "id": "738112cd-6cfa-414a-8457-2a658845d6ba",
          "to": "now",
          "from": "now-6m",
          "meta": {
            "kibana_siem_app_url": "http://localhost:5601/kbn/app/security"
          },
          "name": "Rule 1",
          "tags": [
            "tag-1",
            "tag-2"
          ],
          "type": "query",
          "index": [
            "apm-*-transaction*",
            "auditbeat-*",
            "endgame-*",
            "filebeat-*",
            "logs-*",
            "packetbeat-*",
            "traces-apm*",
            "winlogbeat-*",
            "-*elastic-cloud-logs-*"
          ],
          "query": "*",
          "setup": "",
          "author": [],
          "threat": [],
          "actions": [],
          "enabled": false,
          "filters": [],
          "license": "",
          "rule_id": "6fb746a0-dfe5-40fa-b03f-5cbb84f3e32e",
          "version": 2,
          "interval": "5m",
          "language": "kuery",
          "revision": 1,
          "severity": "low",
          "immutable": false,
          "created_at": "2025-03-25T11:46:41.899Z",
          "created_by": "elastic",
          "references": [],
          "risk_score": 21,
          "updated_at": "2025-03-25T11:47:11.350Z",
          "updated_by": "elastic",
          "description": "test",
          "max_signals": 100,
          "rule_source": {
            "type": "internal"
          },
          "output_index": "",
          "exceptions_list": [],
          "false_positives": [],
          "required_fields": [],
          "severity_mapping": [],
          "risk_score_mapping": [],
          "related_integrations": []
        },
        {
          "id": "eacdfc95-e007-41c9-986e-4b2cbdfdc71b",
          "to": "now",
          "from": "now-360s",
          "meta": {
            "from": "3m",
            "kibana_siem_app_url": "http://localhost:5601/kbn/app/security"
          },
          "name": "Rule 2",
          "tags": [
            "tag-1",
            "tag-2"
          ],
          "type": "query",
          "index": [
            "apm-*-transaction*",
            "auditbeat-*",
            "endgame-*",
            "filebeat-*",
            "logs-*",
            "packetbeat-*",
            "traces-apm*",
            "winlogbeat-*",
            "-*elastic-cloud-logs-*"
          ],
          "query": "*",
          "setup": "",
          "author": [],
          "threat": [],
          "actions": [
            {
              "id": "20fbf986-a270-460e-80f3-7b83c08b430f",
              "uuid": "580e2e16-5e91-411c-999b-7b75a11ed441",
              "group": "default",
              "params": {
                "body": "Hello"
              },
              "frequency": {
                "summary": true,
                "throttle": null,
                "notifyWhen": "onActiveAlert"
              },
              "action_type_id": ".webhook"
            }
          ],
          "enabled": false,
          "filters": [],
          "license": "",
          "rule_id": "43250a55-53a3-4ddd-96cb-82a1bd720180",
          "version": 24,
          "interval": "3m",
          "language": "kuery",
          "revision": 33,
          "severity": "low",
          "immutable": false,
          "created_at": "2025-03-25T09:49:08.343Z",
          "created_by": "elastic",
          "references": [],
          "risk_score": 21,
          "updated_at": "2025-03-25T11:47:11.357Z",
          "updated_by": "elastic",
          "description": "test",
          "max_signals": 100,
          "rule_source": {
            "type": "internal"
          },
          "timeline_id": "3e827bab-838a-469f-bd1e-5e19a2bff2fd",
          "output_index": "",
          "timeline_title": "Alerts Involving a Single User Timeline",
          "exceptions_list": [],
          "false_positives": [],
          "required_fields": [],
          "severity_mapping": [],
          "risk_score_mapping": [],
          "investigation_fields": {
            "field_names": [
              "alert.status",
              "Endpoint.policy.applied.artifacts.global.channel"
            ]
          },
          "related_integrations": []
        }
      ]
    },
    "summary": {
      "total": 2,
      "failed": 0,
      "skipped": 0,
      "succeeded": 2
    }
  },
  "rules_count": 2
}

This example presents the idempotent behavior of the edit action with set_tags request. Both rules already had exactly the same tags that were being added, so no changes were made in any of them.

{
  "success": true,
  "attributes": {
    "results": {
      "created": [],
      "deleted": [],
      "skipped": [
        {
          "id": "eacdfc95-e007-41c9-986e-4b2cbdfdc71b",
          "name": "Rule 1",
          "skip_reason": "RULE_NOT_MODIFIED"
        },
        {
          "id": "738112cd-6cfa-414a-8457-2a658845d6ba",
          "name": "Rule 2",
          "skip_reason": "RULE_NOT_MODIFIED"
        }
      ],
      "updated": []
    },
    "summary": {
      "total": 2,
      "failed": 0,
      "skipped": 2,
      "succeeded": 0
    }
  },
  "rules_count": 2
}

This example presents the idempotent behavior of the edit action with add_tags request. One rule was updated and one was skipped. The rule that was skipped already had all the tags that were being added.

{
  "success": true,
  "attributes": {
    "results": {
      "created": [],
      "deleted": [],
      "skipped": [
        {
          "id": "738112cd-6cfa-414a-8457-2a658845d6ba",
          "name": "Test Rule 2",
          "skip_reason": "RULE_NOT_MODIFIED"
        }
      ],
      "updated": [
        {
          "id": "eacdfc95-e007-41c9-986e-4b2cbdfdc71b",
          "to": "now",
          "from": "now-360s",
          "meta": {
            "from": "3m",
            "kibana_siem_app_url": "http://localhost:5601/kbn/app/security"
          },
          "name": "Test rule",
          "tags": [
            "tag-1",
            "tag-2",
            "tag-4"
          ],
          "type": "query",
          "index": [
            "apm-*-transaction*",
            "auditbeat-*",
            "endgame-*",
            "filebeat-*",
            "logs-*",
            "packetbeat-*",
            "traces-apm*",
            "winlogbeat-*",
            "-*elastic-cloud-logs-*"
          ],
          "query": "*",
          "setup": "",
          "author": [],
          "threat": [],
          "actions": [
            {
              "id": "20fbf986-a270-460e-80f3-7b83c08b430f",
              "uuid": "580e2e16-5e91-411c-999b-7b75a11ed441",
              "group": "default",
              "params": {
                "body": "Hello"
              },
              "frequency": {
                "summary": true,
                "throttle": null,
                "notifyWhen": "onActiveAlert"
              },
              "action_type_id": ".webhook"
            }
          ],
          "enabled": false,
          "filters": [],
          "license": "",
          "rule_id": "43250a55-53a3-4ddd-96cb-82a1bd720180",
          "version": 25,
          "interval": "3m",
          "language": "kuery",
          "revision": 34,
          "severity": "low",
          "immutable": false,
          "created_at": "2025-03-25T09:49:08.343Z",
          "created_by": "elastic",
          "references": [],
          "risk_score": 21,
          "updated_at": "2025-03-25T11:55:12.752Z",
          "updated_by": "elastic",
          "description": "test",
          "max_signals": 100,
          "rule_source": {
            "type": "internal"
          },
          "timeline_id": "3e827bab-838a-469f-bd1e-5e19a2bff2fd",
          "output_index": "",
          "timeline_title": "Alerts Involving a Single User Timeline",
          "exceptions_list": [],
          "false_positives": [],
          "required_fields": [],
          "severity_mapping": [],
          "risk_score_mapping": [],
          "investigation_fields": {
            "field_names": [
              "alert.status",
              "Endpoint.policy.applied.artifacts.global.channel"
            ]
          },
          "related_integrations": []
        }
      ]
    },
    "summary": {
      "total": 2,
      "failed": 0,
      "skipped": 1,
      "succeeded": 1
    }
  },
  "rules_count": 2
}

This example shows a non-idempotent nature of the set_rule_actions requests. Regardless if the actions are the same as the existing actions for a rule, the actions are always set in the rule and receive a new unique ID.

{
  "success": true,
  "attributes": {
    "results": {
      "created": [],
      "deleted": [],
      "skipped": [],
      "updated": [
        {
          "id": "eacdfc95-e007-41c9-986e-4b2cbdfdc71b",
          "to": "now",
          "from": "now-360s",
          "meta": {
            "from": "3m",
            "kibana_siem_app_url": "http://localhost:5601/kbn/app/security"
          },
          "name": "Test rule",
          "tags": [
            "tag-1",
            "tag-2",
            "tag-4"
          ],
          "type": "query",
          "index": [
            "apm-*-transaction*",
            "auditbeat-*",
            "endgame-*",
            "filebeat-*",
            "logs-*",
            "packetbeat-*",
            "traces-apm*",
            "winlogbeat-*",
            "-*elastic-cloud-logs-*"
          ],
          "query": "*",
          "setup": "",
          "author": [],
          "threat": [],
          "actions": [
            {
              "id": "20fbf986-a270-460e-80f3-7b83c08b430f",
              "uuid": "e48428e5-efac-4856-b8ad-b271c14eaa91",
              "group": "default",
              "params": {
                "body": "Hello"
              },
              "frequency": {
                "summary": true,
                "throttle": null,
                "notifyWhen": "onActiveAlert"
              },
              "action_type_id": ".webhook"
            }
          ],
          "enabled": false,
          "filters": [],
          "license": "",
          "rule_id": "43250a55-53a3-4ddd-96cb-82a1bd720180",
          "version": 30,
          "interval": "3m",
          "language": "kuery",
          "revision": 39,
          "severity": "low",
          "immutable": false,
          "created_at": "2025-03-25T09:49:08.343Z",
          "created_by": "elastic",
          "references": [],
          "risk_score": 21,
          "updated_at": "2025-03-25T12:17:40.528Z",
          "updated_by": "elastic",
          "description": "test",
          "max_signals": 100,
          "rule_source": {
            "type": "internal"
          },
          "timeline_id": "3e827bab-838a-469f-bd1e-5e19a2bff2fd",
          "output_index": "",
          "timeline_title": "Alerts Involving a Single User Timeline",
          "exceptions_list": [],
          "false_positives": [],
          "required_fields": [],
          "severity_mapping": [],
          "risk_score_mapping": [],
          "investigation_fields": {
            "field_names": [
              "alert.status",
              "Endpoint.policy.applied.artifacts.global.channel"
            ]
          },
          "related_integrations": []
        }
      ]
    },
    "summary": {
      "total": 1,
      "failed": 0,
      "skipped": 0,
      "succeeded": 1
    }
  },
  "rules_count": 1
}

This example shows a non-idempotent nature of the add_rule_actions requests. Regardless if the added action is the same as another existing action for a rule, the new action is added to the rule and receives a new unique ID.

{
  "success": true,
  "attributes": {
    "results": {
      "created": [],
      "deleted": [],
      "skipped": [],
      "updated": [
        {
          "id": "0d3eb0cd-88c4-4651-ac87-6d9f0cb87217",
          "to": "now",
          "from": "now-6m",
          "meta": {
            "kibana_siem_app_url": "http://localhost:5601/kbn/app/security"
          },
          "name": "Jacek test rule",
          "tags": [],
          "type": "query",
          "index": [
            "apm-*-transaction*",
            "auditbeat-*",
            "endgame-*",
            "filebeat-*",
            "logs-*",
            "packetbeat-*",
            "traces-apm*",
            "winlogbeat-*",
            "-*elastic-cloud-logs-*"
          ],
          "query": "*",
          "setup": "",
          "author": [],
          "threat": [],
          "actions": [
            {
              "id": "76af173d-38d8-4a9a-b2cc-a3c695b845b4",
              "uuid": "0309347e-3954-429c-9168-5da2663389af",
              "group": "default",
              "params": {
                "body": "Message body"
              },
              "frequency": {
                "summary": true,
                "throttle": null,
                "notifyWhen": "onActiveAlert"
              },
              "action_type_id": ".webhook"
            },
            {
              "id": "76af173d-38d8-4a9a-b2cc-a3c695b845b4",
              "uuid": "49ddaa94-d63d-410e-90dc-8c1bad9552bd",
              "group": "default",
              "params": {
                "body": "Message body"
              },
              "frequency": {
                "summary": true,
                "throttle": null,
                "notifyWhen": "onActiveAlert"
              },
              "action_type_id": ".webhook"
            }
          ],
          "enabled": false,
          "filters": [],
          "license": "",
          "rule_id": "2684c020-1370-4719-ac27-eafe6428fe10",
          "version": 2,
          "interval": "5m",
          "language": "kuery",
          "revision": 2,
          "severity": "low",
          "immutable": false,
          "created_at": "2025-04-02T12:42:03.400Z",
          "created_by": "elastic",
          "references": [],
          "risk_score": 21,
          "updated_at": "2025-04-02T12:51:40.215Z",
          "updated_by": "elastic",
          "description": "test",
          "max_signals": 100,
          "rule_source": {
            "type": "internal"
          },
          "output_index": "",
          "exceptions_list": [],
          "false_positives": [],
          "required_fields": [],
          "severity_mapping": [],
          "risk_score_mapping": [],
          "related_integrations": []
        }
      ]
    },
    "summary": {
      "total": 1,
      "failed": 0,
      "skipped": 0,
      "succeeded": 1
    }
  },
  "rules_count": 1
}

Export detection rules

POST /api/detection_engine/rules/_export

Export detection rules to an .ndjson file. The following configuration items are also included in the .ndjson file:

Actions
Exception lists

Rule actions and connectors are included in the exported file, but sensitive information about the connector (such as authentication credentials) is not included. You must re-add missing connector details after importing detection rules.

You can use Kibana’s Saved Objects UI (Stack Management → Kibana → Saved Objects) or the Saved Objects APIs (experimental) to export and import any necessary connectors before importing detection rules.

Similarly, any value lists used for rule exceptions are not included in rule exports or imports. Use the Manage value lists UI (Rules → Detection rules (SIEM) → Manage value lists) to export and import value lists separately.

Query parameters

exclude_export_details boolean

Determines whether a summary of the exported rules is returned.

Default value is false.
file_name string

File name for saving the exported rules.

When using cURL to export rules to a file, use the -O and -J options to save the rules to the file name specified in the URL.

Default value is export.ndjson.

application/json

Body

objects array[object] Required

Array of rule_id fields. Exports all rules when unspecified.
Hide objects attribute Show objects attribute object
- 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.

Responses

200 application/ndjson

Indicates a successful call.

An .ndjson file containing the returned rules.

Each line in the file represents an object (a rule, exception list parent container, or exception list item), and the last line includes a summary of what was exported.

POST /api/detection_engine/rules/_export

curl -X POST "localhost:5601/api/detection_engine/rules/_export?exclude_export_details=true&file_name=exported_rules.ndjson" -H 'kbn-xsrf: true' -H 'Content-Type: application/json' -d'
{
  "objects": [
    {
      "rule_id":"343580b5-c811-447c-8d2d-2ccf052c6900"
    },
    {
      "rule_id":"2938c9fa-53eb-4c04-b79c-33cbf041b18d"
    }
  ]
}

List all detection rules

GET /api/detection_engine/rules/_find

Retrieve a paginated list of detection rules. By default, the first page is returned, with 20 results per page.

Query parameters

fields array[string]
filter string
Search query

Filters the returned results according to the value of the specified field, using the alert.attributes.: syntax, where can be:
- name
- enabled
- tags
- createdBy
- interval
- updatedBy
Even though the JSON rule object uses created_by and updated_by fields, you must use createdBy and updatedBy fields in the filter.
sort_field string

Field to sort by

Values are created_at, createdAt, enabled, execution_summary.last_execution.date, execution_summary.last_execution.metrics.execution_gap_duration_s, execution_summary.last_execution.metrics.total_indexing_duration_ms, execution_summary.last_execution.metrics.total_search_duration_ms, execution_summary.last_execution.status, name, risk_score, riskScore, severity, updated_at, or updatedAt.
sort_order string

Sort order

Values are asc or desc.
page integer

Page number

Minimum value is 1. Default value is 1.
per_page integer

Rules per page

Minimum value is 0. Default value is 20.
gaps_range_start string

Gaps range start
gaps_range_end string

Gaps range end

Responses

200 application/json

Successful response

These fields are under development and their usage or schema may change: execution_summary.
Hide response attributes Show response attributes object
- data array[object] Required
  
  Any of:
  Security_Detections_API_EqlRuleResponseFields object Security_Detections_API_QueryRuleResponseFields object Security_Detections_API_SavedQueryRuleResponseFields object Security_Detections_API_ThresholdRuleResponseFields object Security_Detections_API_ThreatMatchRuleResponseFields object Security_Detections_API_MachineLearningRuleResponseFields object Security_Detections_API_NewTermsRuleResponseFields object Security_Detections_API_EsqlRuleResponseFields object
  
  Hide attributes Show attributes
  
  actions array[object] Required
  
  Array defining the automated actions (notifications) taken when alerts are generated.
  
  Hide actions attributes Show actions attributes object
  
  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.
  
  Additional properties are allowed.
  
  frequency object
  
  The action frequency defines when the action runs (for example, only on rule execution or at specific time intervals).
  
  Hide frequency attributes Show frequency attributes object
  
  notifyWhen string Required
  
  Defines how often rules run actions.
  
  Values are onActiveAlert, onThrottleInterval, or 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 string | null Required
  
  Defines how often rule actions are taken.
  
  One of:
  string-1 string | null string-2 string | null
  
  Values are no_actions or 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.
  
  Additional properties are allowed.
  
  uuid string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  alias_purpose string
  
  Values are savedObjectConversion or savedObjectImport.
  
  alias_target_id string
  
  author array[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 Required
  
  The rule’s description.
  
  Minimum length is 1.
  
  enabled boolean Required
  
  Determines whether the rule is enabled. Defaults to true.
  
  exceptions_list array[object] Required
  
  Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.
  
  Hide exceptions_list attributes Show exceptions_list attributes object
  
  id string(nonempty) Required
  
  ID of the exception container
  
  Minimum length is 1.
  
  list_id string(nonempty) Required
  
  List ID of the exception container
  
  Minimum length is 1.
  
  namespace_type string Required
  
  Determines the exceptions validity in rule's Kibana space
  
  Values are agnostic or single.
  
  type string Required
  
  The exception type
  
  Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.
  
  false_positives array[string] Required
  
  String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.
  
  from string(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.
  
  Hide investigation_fields attribute Show investigation_fields attribute object
  
  field_names array[string(nonempty)] Required
  
  A string that does not contain only whitespace characters
  
  At least 1 element. Minimum length of each is 1.
  
  license string
  
  The rule's license.
  
  max_signals integer Required
  
  Maximum number of alerts the rule can create during a single run (the rule’s Max alerts per run advanced setting value).
  
  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.
  
  Minimum value is 1. Default value is 100.
  
  meta object
  
  Placeholder for metadata about the rule.
  
  This field is overwritten when you save changes to the rule’s settings.
  
  Additional properties are allowed.
  
  name string Required
  
  A human-readable name for the rule.
  
  Minimum length is 1.
  
  namespace string
  
  Has no effect.
  
  note string
  
  Notes to help investigate alerts produced by the rule.
  
  outcome string
  
  Values are exactMatch, aliasMatch, or conflict.
  
  output_index string Deprecated
  
  (deprecated) Has no effect.
  
  references array[string] Required
  
  Array containing notes about or references to relevant information about the rule. Defaults to an empty array.
  
  related_integrations array[object] Required
  
  Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.
  
  NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.
  
  Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:
  
  package: name of the package (required, unique id)
  
  version: version of the package (required, semver-compatible)
  
  integration: name of the integration of this package (optional, id within the package)
  
  There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.
  
  Hide related_integrations attributes Show related_integrations attributes object
  
  integration string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  package string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  version string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  required_fields array[object] Required
  
  Elasticsearch fields and their types that need to be present for the rule to function.
  
  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.
  
  Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.
  
  Hide required_fields attributes Show required_fields attributes object
  
  name string(nonempty) Required
  
  Name of an Elasticsearch field
  
  Minimum length is 1.
  
  type string(nonempty) Required
  
  Type of the Elasticsearch field
  
  Minimum length is 1.
  
  response_actions array[object]
  
  One of:
  Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object
  
  Hide attributes Show attributes
  
  action_type_id string Required
  
  Value is .osquery.
  
  params object Required
  
  Hide params attributes Show params attributes object
  
  ecs_mapping object
  
  Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}
  
  Hide ecs_mapping attribute Show ecs_mapping attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  field string
  
  value string | array[string]
  
  One of:
  string-1 string array-2 array[string]
  
  pack_id string
  
  To specify a query pack, use the packId field. Example: "packId": "processes_elastic"
  
  queries array[object]
  
  Hide queries attributes Show queries attributes object
  
  ecs_mapping object
  
  Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}
  
  Hide ecs_mapping attribute Show ecs_mapping attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  field string
  
  value string | array[string]
  
  One of:
  string-1 string array-2 array[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.
  
  Hide attributes Show attributes
  
  action_type_id string Required
  
  Value is .endpoint.
  
  params object Required
  
  One of:
  Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object
  
  Hide attributes Show attributes
  
  command string Required
  
  Value is isolate.
  
  comment string
  
  Hide attributes Show attributes
  
  command string Required
  
  To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"
  
  Values are kill-process or suspend-process.
  
  comment string
  
  Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"
  
  config object Required
  
  Hide config attributes Show config attributes object
  
  field string Required
  
  Field to use instead of process.pid
  
  overwrite boolean
  
  Whether to overwrite field with process.pid
  
  Default value is true.
  
  risk_score integer 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
  
  Minimum value is 0, maximum value is 100.
  
  risk_score_mapping array[object] Required
  
  Overrides generated alerts' risk_score with a value from the source event
  
  Hide risk_score_mapping attributes Show risk_score_mapping attributes object
  
  field string Required
  
  Source event field used to override the default risk_score.
  
  operator string Required
  
  Value is equals.
  
  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
  
  Minimum value is 0, maximum value is 100.
  
  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 string 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 are low, medium, high, or critical.
  
  severity_mapping array[object] Required
  
  Overrides generated alerts' severity with values from the source event
  
  Hide severity_mapping attributes Show severity_mapping attributes object
  
  field string Required
  
  Source event field used to override the default severity.
  
  operator string Required
  
  Value is equals.
  
  severity string 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 are low, medium, high, or critical.
  
  value string Required
  
  tags array[string] Required
  
  String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.
  
  threat array[object] Required
  
  Currently, only threats described using the MITRE ATT&CK™ framework are supported.
  
  Hide threat attributes Show threat attributes object
  
  framework string Required
  
  Relevant attack framework
  
  tactic object Required
  
  Object containing information on the attack type
  
  Hide tactic attributes Show tactic attributes object
  
  id string Required
  
  Tactic ID
  
  name string Required
  
  Tactic name
  
  reference string Required
  
  Tactic reference
  
  technique array[object]
  
  Array containing information on the attack techniques (optional)
  
  Hide technique attributes Show technique attributes object
  
  id string Required
  
  Technique ID
  
  name string Required
  
  Technique name
  
  reference string Required
  
  Technique reference
  
  subtechnique array[object]
  
  Array containing more specific information on the attack technique.
  
  Hide subtechnique attributes Show subtechnique attributes object
  
  id string Required
  
  Subtechnique ID
  
  name string Required
  
  Subtechnique name
  
  reference string Required
  
  Subtechnique reference
  
  throttle string | null
  
  Defines how often rule actions are taken.
  
  One of:
  string-1 string | null string-2 string | null
  
  Values are no_actions or 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 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.
  
  It is not incremented on each update. Compare this to the revision field.
  
  Minimum value is 1.
  
  created_at string(date-time) Required
  
  created_by string Required
  
  execution_summary object
  
  Summary of the last execution of a rule.
  
  This field is under development and its usage or schema may change
  
  Hide execution_summary attribute Show execution_summary attribute object
  
  last_execution object Required
  
  Hide last_execution attributes Show last_execution attributes object
  
  date string(date-time) Required
  
  Date of the last execution
  
  message string Required
  
  metrics object Required
  
  Hide metrics attributes Show metrics attributes object
  
  execution_gap_duration_s integer
  
  Duration in seconds of execution gap
  
  Minimum value is 0.
  
  frozen_indices_queried_count integer
  
  Count of frozen indices queried during the rule execution. These indices could not be entirely excluded after applying the time range filter.
  
  Minimum value is 0.
  
  gap_range object
  
  Range of the execution gap
  
  Hide gap_range attributes Show gap_range attributes object
  
  gte string Required
  
  Start date of the execution gap
  
  lte string Required
  
  End date of the execution gap
  
  total_enrichment_duration_ms integer
  
  Total time spent enriching documents during current rule execution cycle
  
  Minimum value is 0.
  
  total_indexing_duration_ms integer
  
  Total time spent indexing documents during current rule execution cycle
  
  Minimum value is 0.
  
  total_search_duration_ms integer
  
  Total time spent performing ES searches as measured by Kibana; includes network latency and time spent serializing/deserializing request/response
  
  Minimum value is 0.
  
  status string Required
  
  Status of the last execution
  
  Values are going to run, running, partial failure, failed, or succeeded.
  
  status_order integer Required
  
  id string(uuid) Required
  
  A dynamic unique identifier for the rule object. It is randomly generated when a rule is created and cannot be changed after that. It is always a UUID. It is unique within a given Kibana space. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have different object ids.
  
  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 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.
  
  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.
  
  Minimum value is 0.
  
  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 object 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:
  Security_Detections_API_ExternalRuleSource object Security_Detections_API_InternalRuleSource object
  
  Type of rule source for externally sourced rules, i.e. rules that have an external source, such as the Elastic Prebuilt rules repo.
  
  Hide attributes Show attributes
  
  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).
  
  type string Required Discriminator
  
  Value is external.
  
  updated_at string(date-time) Required
  
  updated_by string Required
  
  language string Required
  
  Query language to use
  
  Value is 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.
  
  type string Required Discriminator
  
  Rule type
  
  Value is eql.
  
  alert_suppression object
  
  Defines alert suppression configuration.
  
  Hide alert_suppression attributes Show alert_suppression attributes object
  
  duration object
  
  Hide duration attributes Show duration attributes object
  
  unit string Required
  
  Time unit
  
  Values are s, m, or h.
  
  value integer Required
  
  Minimum value is 1.
  
  group_by array[string] Required
  
  At least 1 but not more than 3 elements.
  
  missing_fields_strategy string
  
  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 are doNotSuppress or suppress.
  
  data_view_id string
  
  event_category_override string
  
  filters array
  
  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 array[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.
  
  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.
  
  Hide attributes Show attributes
  
  actions array[object] Required
  
  Array defining the automated actions (notifications) taken when alerts are generated.
  
  Hide actions attributes Show actions attributes object
  
  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.
  
  Additional properties are allowed.
  
  frequency object
  
  The action frequency defines when the action runs (for example, only on rule execution or at specific time intervals).
  
  Hide frequency attributes Show frequency attributes object
  
  notifyWhen string Required
  
  Defines how often rules run actions.
  
  Values are onActiveAlert, onThrottleInterval, or 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 string | null Required
  
  Defines how often rule actions are taken.
  
  One of:
  string-1 string | null string-2 string | null
  
  Values are no_actions or 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.
  
  Additional properties are allowed.
  
  uuid string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  alias_purpose string
  
  Values are savedObjectConversion or savedObjectImport.
  
  alias_target_id string
  
  author array[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 Required
  
  The rule’s description.
  
  Minimum length is 1.
  
  enabled boolean Required
  
  Determines whether the rule is enabled. Defaults to true.
  
  exceptions_list array[object] Required
  
  Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.
  
  Hide exceptions_list attributes Show exceptions_list attributes object
  
  id string(nonempty) Required
  
  ID of the exception container
  
  Minimum length is 1.
  
  list_id string(nonempty) Required
  
  List ID of the exception container
  
  Minimum length is 1.
  
  namespace_type string Required
  
  Determines the exceptions validity in rule's Kibana space
  
  Values are agnostic or single.
  
  type string Required
  
  The exception type
  
  Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.
  
  false_positives array[string] Required
  
  String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.
  
  from string(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.
  
  Hide investigation_fields attribute Show investigation_fields attribute object
  
  field_names array[string(nonempty)] Required
  
  A string that does not contain only whitespace characters
  
  At least 1 element. Minimum length of each is 1.
  
  license string
  
  The rule's license.
  
  max_signals integer Required
  
  Maximum number of alerts the rule can create during a single run (the rule’s Max alerts per run advanced setting value).
  
  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.
  
  Minimum value is 1. Default value is 100.
  
  meta object
  
  Placeholder for metadata about the rule.
  
  This field is overwritten when you save changes to the rule’s settings.
  
  Additional properties are allowed.
  
  name string Required
  
  A human-readable name for the rule.
  
  Minimum length is 1.
  
  namespace string
  
  Has no effect.
  
  note string
  
  Notes to help investigate alerts produced by the rule.
  
  outcome string
  
  Values are exactMatch, aliasMatch, or conflict.
  
  output_index string Deprecated
  
  (deprecated) Has no effect.
  
  references array[string] Required
  
  Array containing notes about or references to relevant information about the rule. Defaults to an empty array.
  
  related_integrations array[object] Required
  
  Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.
  
  NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.
  
  Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:
  
  package: name of the package (required, unique id)
  
  version: version of the package (required, semver-compatible)
  
  integration: name of the integration of this package (optional, id within the package)
  
  There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.
  
  Hide related_integrations attributes Show related_integrations attributes object
  
  integration string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  package string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  version string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  required_fields array[object] Required
  
  Elasticsearch fields and their types that need to be present for the rule to function.
  
  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.
  
  Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.
  
  Hide required_fields attributes Show required_fields attributes object
  
  name string(nonempty) Required
  
  Name of an Elasticsearch field
  
  Minimum length is 1.
  
  type string(nonempty) Required
  
  Type of the Elasticsearch field
  
  Minimum length is 1.
  
  response_actions array[object]
  
  One of:
  Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object
  
  Hide attributes Show attributes
  
  action_type_id string Required
  
  Value is .osquery.
  
  params object Required
  
  Hide params attributes Show params attributes object
  
  ecs_mapping object
  
  Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}
  
  Hide ecs_mapping attribute Show ecs_mapping attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  field string
  
  value string | array[string]
  
  One of:
  string-1 string array-2 array[string]
  
  pack_id string
  
  To specify a query pack, use the packId field. Example: "packId": "processes_elastic"
  
  queries array[object]
  
  Hide queries attributes Show queries attributes object
  
  ecs_mapping object
  
  Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}
  
  Hide ecs_mapping attribute Show ecs_mapping attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  field string
  
  value string | array[string]
  
  One of:
  string-1 string array-2 array[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.
  
  Hide attributes Show attributes
  
  action_type_id string Required
  
  Value is .endpoint.
  
  params object Required
  
  One of:
  Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object
  
  Hide attributes Show attributes
  
  command string Required
  
  Value is isolate.
  
  comment string
  
  Hide attributes Show attributes
  
  command string Required
  
  To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"
  
  Values are kill-process or suspend-process.
  
  comment string
  
  Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"
  
  config object Required
  
  Hide config attributes Show config attributes object
  
  field string Required
  
  Field to use instead of process.pid
  
  overwrite boolean
  
  Whether to overwrite field with process.pid
  
  Default value is true.
  
  risk_score integer 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
  
  Minimum value is 0, maximum value is 100.
  
  risk_score_mapping array[object] Required
  
  Overrides generated alerts' risk_score with a value from the source event
  
  Hide risk_score_mapping attributes Show risk_score_mapping attributes object
  
  field string Required
  
  Source event field used to override the default risk_score.
  
  operator string Required
  
  Value is equals.
  
  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
  
  Minimum value is 0, maximum value is 100.
  
  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 string 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 are low, medium, high, or critical.
  
  severity_mapping array[object] Required
  
  Overrides generated alerts' severity with values from the source event
  
  Hide severity_mapping attributes Show severity_mapping attributes object
  
  field string Required
  
  Source event field used to override the default severity.
  
  operator string Required
  
  Value is equals.
  
  severity string 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 are low, medium, high, or critical.
  
  value string Required
  
  tags array[string] Required
  
  String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.
  
  threat array[object] Required
  
  Currently, only threats described using the MITRE ATT&CK™ framework are supported.
  
  Hide threat attributes Show threat attributes object
  
  framework string Required
  
  Relevant attack framework
  
  tactic object Required
  
  Object containing information on the attack type
  
  Hide tactic attributes Show tactic attributes object
  
  id string Required
  
  Tactic ID
  
  name string Required
  
  Tactic name
  
  reference string Required
  
  Tactic reference
  
  technique array[object]
  
  Array containing information on the attack techniques (optional)
  
  Hide technique attributes Show technique attributes object
  
  id string Required
  
  Technique ID
  
  name string Required
  
  Technique name
  
  reference string Required
  
  Technique reference
  
  subtechnique array[object]
  
  Array containing more specific information on the attack technique.
  
  Hide subtechnique attributes Show subtechnique attributes object
  
  id string Required
  
  Subtechnique ID
  
  name string Required
  
  Subtechnique name
  
  reference string Required
  
  Subtechnique reference
  
  throttle string | null
  
  Defines how often rule actions are taken.
  
  One of:
  string-1 string | null string-2 string | null
  
  Values are no_actions or 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 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.
  
  It is not incremented on each update. Compare this to the revision field.
  
  Minimum value is 1.
  
  created_at string(date-time) Required
  
  created_by string Required
  
  execution_summary object
  
  Summary of the last execution of a rule.
  
  This field is under development and its usage or schema may change
  
  Hide execution_summary attribute Show execution_summary attribute object
  
  last_execution object Required
  
  Hide last_execution attributes Show last_execution attributes object
  
  date string(date-time) Required
  
  Date of the last execution
  
  message string Required
  
  metrics object Required
  
  Hide metrics attributes Show metrics attributes object
  
  execution_gap_duration_s integer
  
  Duration in seconds of execution gap
  
  Minimum value is 0.
  
  frozen_indices_queried_count integer
  
  Count of frozen indices queried during the rule execution. These indices could not be entirely excluded after applying the time range filter.
  
  Minimum value is 0.
  
  gap_range object
  
  Range of the execution gap
  
  Hide gap_range attributes Show gap_range attributes object
  
  gte string Required
  
  Start date of the execution gap
  
  lte string Required
  
  End date of the execution gap
  
  total_enrichment_duration_ms integer
  
  Total time spent enriching documents during current rule execution cycle
  
  Minimum value is 0.
  
  total_indexing_duration_ms integer
  
  Total time spent indexing documents during current rule execution cycle
  
  Minimum value is 0.
  
  total_search_duration_ms integer
  
  Total time spent performing ES searches as measured by Kibana; includes network latency and time spent serializing/deserializing request/response
  
  Minimum value is 0.
  
  status string Required
  
  Status of the last execution
  
  Values are going to run, running, partial failure, failed, or succeeded.
  
  status_order integer Required
  
  id string(uuid) Required
  
  A dynamic unique identifier for the rule object. It is randomly generated when a rule is created and cannot be changed after that. It is always a UUID. It is unique within a given Kibana space. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have different object ids.
  
  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 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.
  
  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.
  
  Minimum value is 0.
  
  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 object 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:
  Security_Detections_API_ExternalRuleSource object Security_Detections_API_InternalRuleSource object
  
  Type of rule source for externally sourced rules, i.e. rules that have an external source, such as the Elastic Prebuilt rules repo.
  
  Hide attributes Show attributes
  
  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).
  
  type string Required Discriminator
  
  Value is external.
  
  updated_at string(date-time) Required
  
  updated_by string Required
  
  type string Required Discriminator
  
  Rule type
  
  Value is query.
  
  alert_suppression object
  
  Defines alert suppression configuration.
  
  Hide alert_suppression attributes Show alert_suppression attributes object
  
  duration object
  
  Hide duration attributes Show duration attributes object
  
  unit string Required
  
  Time unit
  
  Values are s, m, or h.
  
  value integer Required
  
  Minimum value is 1.
  
  group_by array[string] Required
  
  At least 1 but not more than 3 elements.
  
  missing_fields_strategy string
  
  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 are doNotSuppress or suppress.
  
  data_view_id string
  
  filters array
  
  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 array[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.
  
  saved_id string
  
  Kibana saved search used by the rule to create alerts.
  
  language string Required
  
  Values are kuery or lucene.
  
  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.
  
  Hide attributes Show attributes
  
  actions array[object] Required
  
  Array defining the automated actions (notifications) taken when alerts are generated.
  
  Hide actions attributes Show actions attributes object
  
  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.
  
  Additional properties are allowed.
  
  frequency object
  
  The action frequency defines when the action runs (for example, only on rule execution or at specific time intervals).
  
  Hide frequency attributes Show frequency attributes object
  
  notifyWhen string Required
  
  Defines how often rules run actions.
  
  Values are onActiveAlert, onThrottleInterval, or 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 string | null Required
  
  Defines how often rule actions are taken.
  
  One of:
  string-1 string | null string-2 string | null
  
  Values are no_actions or 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.
  
  Additional properties are allowed.
  
  uuid string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  alias_purpose string
  
  Values are savedObjectConversion or savedObjectImport.
  
  alias_target_id string
  
  author array[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 Required
  
  The rule’s description.
  
  Minimum length is 1.
  
  enabled boolean Required
  
  Determines whether the rule is enabled. Defaults to true.
  
  exceptions_list array[object] Required
  
  Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.
  
  Hide exceptions_list attributes Show exceptions_list attributes object
  
  id string(nonempty) Required
  
  ID of the exception container
  
  Minimum length is 1.
  
  list_id string(nonempty) Required
  
  List ID of the exception container
  
  Minimum length is 1.
  
  namespace_type string Required
  
  Determines the exceptions validity in rule's Kibana space
  
  Values are agnostic or single.
  
  type string Required
  
  The exception type
  
  Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.
  
  false_positives array[string] Required
  
  String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.
  
  from string(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.
  
  Hide investigation_fields attribute Show investigation_fields attribute object
  
  field_names array[string(nonempty)] Required
  
  A string that does not contain only whitespace characters
  
  At least 1 element. Minimum length of each is 1.
  
  license string
  
  The rule's license.
  
  max_signals integer Required
  
  Maximum number of alerts the rule can create during a single run (the rule’s Max alerts per run advanced setting value).
  
  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.
  
  Minimum value is 1. Default value is 100.
  
  meta object
  
  Placeholder for metadata about the rule.
  
  This field is overwritten when you save changes to the rule’s settings.
  
  Additional properties are allowed.
  
  name string Required
  
  A human-readable name for the rule.
  
  Minimum length is 1.
  
  namespace string
  
  Has no effect.
  
  note string
  
  Notes to help investigate alerts produced by the rule.
  
  outcome string
  
  Values are exactMatch, aliasMatch, or conflict.
  
  output_index string Deprecated
  
  (deprecated) Has no effect.
  
  references array[string] Required
  
  Array containing notes about or references to relevant information about the rule. Defaults to an empty array.
  
  related_integrations array[object] Required
  
  Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.
  
  NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.
  
  Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:
  
  package: name of the package (required, unique id)
  
  version: version of the package (required, semver-compatible)
  
  integration: name of the integration of this package (optional, id within the package)
  
  There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.
  
  Hide related_integrations attributes Show related_integrations attributes object
  
  integration string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  package string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  version string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  required_fields array[object] Required
  
  Elasticsearch fields and their types that need to be present for the rule to function.
  
  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.
  
  Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.
  
  Hide required_fields attributes Show required_fields attributes object
  
  name string(nonempty) Required
  
  Name of an Elasticsearch field
  
  Minimum length is 1.
  
  type string(nonempty) Required
  
  Type of the Elasticsearch field
  
  Minimum length is 1.
  
  response_actions array[object]
  
  One of:
  Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object
  
  Hide attributes Show attributes
  
  action_type_id string Required
  
  Value is .osquery.
  
  params object Required
  
  Hide params attributes Show params attributes object
  
  ecs_mapping object
  
  Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}
  
  Hide ecs_mapping attribute Show ecs_mapping attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  field string
  
  value string | array[string]
  
  One of:
  string-1 string array-2 array[string]
  
  pack_id string
  
  To specify a query pack, use the packId field. Example: "packId": "processes_elastic"
  
  queries array[object]
  
  Hide queries attributes Show queries attributes object
  
  ecs_mapping object
  
  Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}
  
  Hide ecs_mapping attribute Show ecs_mapping attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  field string
  
  value string | array[string]
  
  One of:
  string-1 string array-2 array[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.
  
  Hide attributes Show attributes
  
  action_type_id string Required
  
  Value is .endpoint.
  
  params object Required
  
  One of:
  Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object
  
  Hide attributes Show attributes
  
  command string Required
  
  Value is isolate.
  
  comment string
  
  Hide attributes Show attributes
  
  command string Required
  
  To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"
  
  Values are kill-process or suspend-process.
  
  comment string
  
  Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"
  
  config object Required
  
  Hide config attributes Show config attributes object
  
  field string Required
  
  Field to use instead of process.pid
  
  overwrite boolean
  
  Whether to overwrite field with process.pid
  
  Default value is true.
  
  risk_score integer 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
  
  Minimum value is 0, maximum value is 100.
  
  risk_score_mapping array[object] Required
  
  Overrides generated alerts' risk_score with a value from the source event
  
  Hide risk_score_mapping attributes Show risk_score_mapping attributes object
  
  field string Required
  
  Source event field used to override the default risk_score.
  
  operator string Required
  
  Value is equals.
  
  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
  
  Minimum value is 0, maximum value is 100.
  
  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 string 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 are low, medium, high, or critical.
  
  severity_mapping array[object] Required
  
  Overrides generated alerts' severity with values from the source event
  
  Hide severity_mapping attributes Show severity_mapping attributes object
  
  field string Required
  
  Source event field used to override the default severity.
  
  operator string Required
  
  Value is equals.
  
  severity string 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 are low, medium, high, or critical.
  
  value string Required
  
  tags array[string] Required
  
  String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.
  
  threat array[object] Required
  
  Currently, only threats described using the MITRE ATT&CK™ framework are supported.
  
  Hide threat attributes Show threat attributes object
  
  framework string Required
  
  Relevant attack framework
  
  tactic object Required
  
  Object containing information on the attack type
  
  Hide tactic attributes Show tactic attributes object
  
  id string Required
  
  Tactic ID
  
  name string Required
  
  Tactic name
  
  reference string Required
  
  Tactic reference
  
  technique array[object]
  
  Array containing information on the attack techniques (optional)
  
  Hide technique attributes Show technique attributes object
  
  id string Required
  
  Technique ID
  
  name string Required
  
  Technique name
  
  reference string Required
  
  Technique reference
  
  subtechnique array[object]
  
  Array containing more specific information on the attack technique.
  
  Hide subtechnique attributes Show subtechnique attributes object
  
  id string Required
  
  Subtechnique ID
  
  name string Required
  
  Subtechnique name
  
  reference string Required
  
  Subtechnique reference
  
  throttle string | null
  
  Defines how often rule actions are taken.
  
  One of:
  string-1 string | null string-2 string | null
  
  Values are no_actions or 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 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.
  
  It is not incremented on each update. Compare this to the revision field.
  
  Minimum value is 1.
  
  created_at string(date-time) Required
  
  created_by string Required
  
  execution_summary object
  
  Summary of the last execution of a rule.
  
  This field is under development and its usage or schema may change
  
  Hide execution_summary attribute Show execution_summary attribute object
  
  last_execution object Required
  
  Hide last_execution attributes Show last_execution attributes object
  
  date string(date-time) Required
  
  Date of the last execution
  
  message string Required
  
  metrics object Required
  
  Hide metrics attributes Show metrics attributes object
  
  execution_gap_duration_s integer
  
  Duration in seconds of execution gap
  
  Minimum value is 0.
  
  frozen_indices_queried_count integer
  
  Count of frozen indices queried during the rule execution. These indices could not be entirely excluded after applying the time range filter.
  
  Minimum value is 0.
  
  gap_range object
  
  Range of the execution gap
  
  Hide gap_range attributes Show gap_range attributes object
  
  gte string Required
  
  Start date of the execution gap
  
  lte string Required
  
  End date of the execution gap
  
  total_enrichment_duration_ms integer
  
  Total time spent enriching documents during current rule execution cycle
  
  Minimum value is 0.
  
  total_indexing_duration_ms integer
  
  Total time spent indexing documents during current rule execution cycle
  
  Minimum value is 0.
  
  total_search_duration_ms integer
  
  Total time spent performing ES searches as measured by Kibana; includes network latency and time spent serializing/deserializing request/response
  
  Minimum value is 0.
  
  status string Required
  
  Status of the last execution
  
  Values are going to run, running, partial failure, failed, or succeeded.
  
  status_order integer Required
  
  id string(uuid) Required
  
  A dynamic unique identifier for the rule object. It is randomly generated when a rule is created and cannot be changed after that. It is always a UUID. It is unique within a given Kibana space. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have different object ids.
  
  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 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.
  
  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.
  
  Minimum value is 0.
  
  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 object 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:
  Security_Detections_API_ExternalRuleSource object Security_Detections_API_InternalRuleSource object
  
  Type of rule source for externally sourced rules, i.e. rules that have an external source, such as the Elastic Prebuilt rules repo.
  
  Hide attributes Show attributes
  
  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).
  
  type string Required Discriminator
  
  Value is external.
  
  updated_at string(date-time) Required
  
  updated_by string Required
  
  saved_id string Required
  
  Kibana saved search used by the rule to create alerts.
  
  type string Required Discriminator
  
  Rule type
  
  Value is saved_query.
  
  alert_suppression object
  
  Defines alert suppression configuration.
  
  Hide alert_suppression attributes Show alert_suppression attributes object
  
  duration object
  
  Hide duration attributes Show duration attributes object
  
  unit string Required
  
  Time unit
  
  Values are s, m, or h.
  
  value integer Required
  
  Minimum value is 1.
  
  group_by array[string] Required
  
  At least 1 but not more than 3 elements.
  
  missing_fields_strategy string
  
  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 are doNotSuppress or suppress.
  
  data_view_id string
  
  filters array
  
  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 array[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.
  
  query string
  
  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.
  
  language string Required
  
  Values are kuery or lucene.
  
  Hide attributes Show attributes
  
  actions array[object] Required
  
  Array defining the automated actions (notifications) taken when alerts are generated.
  
  Hide actions attributes Show actions attributes object
  
  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.
  
  Additional properties are allowed.
  
  frequency object
  
  The action frequency defines when the action runs (for example, only on rule execution or at specific time intervals).
  
  Hide frequency attributes Show frequency attributes object
  
  notifyWhen string Required
  
  Defines how often rules run actions.
  
  Values are onActiveAlert, onThrottleInterval, or 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 string | null Required
  
  Defines how often rule actions are taken.
  
  One of:
  string-1 string | null string-2 string | null
  
  Values are no_actions or 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.
  
  Additional properties are allowed.
  
  uuid string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  alias_purpose string
  
  Values are savedObjectConversion or savedObjectImport.
  
  alias_target_id string
  
  author array[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 Required
  
  The rule’s description.
  
  Minimum length is 1.
  
  enabled boolean Required
  
  Determines whether the rule is enabled. Defaults to true.
  
  exceptions_list array[object] Required
  
  Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.
  
  Hide exceptions_list attributes Show exceptions_list attributes object
  
  id string(nonempty) Required
  
  ID of the exception container
  
  Minimum length is 1.
  
  list_id string(nonempty) Required
  
  List ID of the exception container
  
  Minimum length is 1.
  
  namespace_type string Required
  
  Determines the exceptions validity in rule's Kibana space
  
  Values are agnostic or single.
  
  type string Required
  
  The exception type
  
  Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.
  
  false_positives array[string] Required
  
  String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.
  
  from string(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.
  
  Hide investigation_fields attribute Show investigation_fields attribute object
  
  field_names array[string(nonempty)] Required
  
  A string that does not contain only whitespace characters
  
  At least 1 element. Minimum length of each is 1.
  
  license string
  
  The rule's license.
  
  max_signals integer Required
  
  Maximum number of alerts the rule can create during a single run (the rule’s Max alerts per run advanced setting value).
  
  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.
  
  Minimum value is 1. Default value is 100.
  
  meta object
  
  Placeholder for metadata about the rule.
  
  This field is overwritten when you save changes to the rule’s settings.
  
  Additional properties are allowed.
  
  name string Required
  
  A human-readable name for the rule.
  
  Minimum length is 1.
  
  namespace string
  
  Has no effect.
  
  note string
  
  Notes to help investigate alerts produced by the rule.
  
  outcome string
  
  Values are exactMatch, aliasMatch, or conflict.
  
  output_index string Deprecated
  
  (deprecated) Has no effect.
  
  references array[string] Required
  
  Array containing notes about or references to relevant information about the rule. Defaults to an empty array.
  
  related_integrations array[object] Required
  
  Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.
  
  NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.
  
  Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:
  
  package: name of the package (required, unique id)
  
  version: version of the package (required, semver-compatible)
  
  integration: name of the integration of this package (optional, id within the package)
  
  There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.
  
  Hide related_integrations attributes Show related_integrations attributes object
  
  integration string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  package string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  version string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  required_fields array[object] Required
  
  Elasticsearch fields and their types that need to be present for the rule to function.
  
  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.
  
  Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.
  
  Hide required_fields attributes Show required_fields attributes object
  
  name string(nonempty) Required
  
  Name of an Elasticsearch field
  
  Minimum length is 1.
  
  type string(nonempty) Required
  
  Type of the Elasticsearch field
  
  Minimum length is 1.
  
  response_actions array[object]
  
  One of:
  Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object
  
  Hide attributes Show attributes
  
  action_type_id string Required
  
  Value is .osquery.
  
  params object Required
  
  Hide params attributes Show params attributes object
  
  ecs_mapping object
  
  Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}
  
  Hide ecs_mapping attribute Show ecs_mapping attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  field string
  
  value string | array[string]
  
  One of:
  string-1 string array-2 array[string]
  
  pack_id string
  
  To specify a query pack, use the packId field. Example: "packId": "processes_elastic"
  
  queries array[object]
  
  Hide queries attributes Show queries attributes object
  
  ecs_mapping object
  
  Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}
  
  Hide ecs_mapping attribute Show ecs_mapping attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  field string
  
  value string | array[string]
  
  One of:
  string-1 string array-2 array[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.
  
  Hide attributes Show attributes
  
  action_type_id string Required
  
  Value is .endpoint.
  
  params object Required
  
  One of:
  Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object
  
  Hide attributes Show attributes
  
  command string Required
  
  Value is isolate.
  
  comment string
  
  Hide attributes Show attributes
  
  command string Required
  
  To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"
  
  Values are kill-process or suspend-process.
  
  comment string
  
  Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"
  
  config object Required
  
  Hide config attributes Show config attributes object
  
  field string Required
  
  Field to use instead of process.pid
  
  overwrite boolean
  
  Whether to overwrite field with process.pid
  
  Default value is true.
  
  risk_score integer 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
  
  Minimum value is 0, maximum value is 100.
  
  risk_score_mapping array[object] Required
  
  Overrides generated alerts' risk_score with a value from the source event
  
  Hide risk_score_mapping attributes Show risk_score_mapping attributes object
  
  field string Required
  
  Source event field used to override the default risk_score.
  
  operator string Required
  
  Value is equals.
  
  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
  
  Minimum value is 0, maximum value is 100.
  
  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 string 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 are low, medium, high, or critical.
  
  severity_mapping array[object] Required
  
  Overrides generated alerts' severity with values from the source event
  
  Hide severity_mapping attributes Show severity_mapping attributes object
  
  field string Required
  
  Source event field used to override the default severity.
  
  operator string Required
  
  Value is equals.
  
  severity string 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 are low, medium, high, or critical.
  
  value string Required
  
  tags array[string] Required
  
  String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.
  
  threat array[object] Required
  
  Currently, only threats described using the MITRE ATT&CK™ framework are supported.
  
  Hide threat attributes Show threat attributes object
  
  framework string Required
  
  Relevant attack framework
  
  tactic object Required
  
  Object containing information on the attack type
  
  Hide tactic attributes Show tactic attributes object
  
  id string Required
  
  Tactic ID
  
  name string Required
  
  Tactic name
  
  reference string Required
  
  Tactic reference
  
  technique array[object]
  
  Array containing information on the attack techniques (optional)
  
  Hide technique attributes Show technique attributes object
  
  id string Required
  
  Technique ID
  
  name string Required
  
  Technique name
  
  reference string Required
  
  Technique reference
  
  subtechnique array[object]
  
  Array containing more specific information on the attack technique.
  
  Hide subtechnique attributes Show subtechnique attributes object
  
  id string Required
  
  Subtechnique ID
  
  name string Required
  
  Subtechnique name
  
  reference string Required
  
  Subtechnique reference
  
  throttle string | null
  
  Defines how often rule actions are taken.
  
  One of:
  string-1 string | null string-2 string | null
  
  Values are no_actions or 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 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.
  
  It is not incremented on each update. Compare this to the revision field.
  
  Minimum value is 1.
  
  created_at string(date-time) Required
  
  created_by string Required
  
  execution_summary object
  
  Summary of the last execution of a rule.
  
  This field is under development and its usage or schema may change
  
  Hide execution_summary attribute Show execution_summary attribute object
  
  last_execution object Required
  
  Hide last_execution attributes Show last_execution attributes object
  
  date string(date-time) Required
  
  Date of the last execution
  
  message string Required
  
  metrics object Required
  
  Hide metrics attributes Show metrics attributes object
  
  execution_gap_duration_s integer
  
  Duration in seconds of execution gap
  
  Minimum value is 0.
  
  frozen_indices_queried_count integer
  
  Count of frozen indices queried during the rule execution. These indices could not be entirely excluded after applying the time range filter.
  
  Minimum value is 0.
  
  gap_range object
  
  Range of the execution gap
  
  Hide gap_range attributes Show gap_range attributes object
  
  gte string Required
  
  Start date of the execution gap
  
  lte string Required
  
  End date of the execution gap
  
  total_enrichment_duration_ms integer
  
  Total time spent enriching documents during current rule execution cycle
  
  Minimum value is 0.
  
  total_indexing_duration_ms integer
  
  Total time spent indexing documents during current rule execution cycle
  
  Minimum value is 0.
  
  total_search_duration_ms integer
  
  Total time spent performing ES searches as measured by Kibana; includes network latency and time spent serializing/deserializing request/response
  
  Minimum value is 0.
  
  status string Required
  
  Status of the last execution
  
  Values are going to run, running, partial failure, failed, or succeeded.
  
  status_order integer Required
  
  id string(uuid) Required
  
  A dynamic unique identifier for the rule object. It is randomly generated when a rule is created and cannot be changed after that. It is always a UUID. It is unique within a given Kibana space. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have different object ids.
  
  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 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.
  
  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.
  
  Minimum value is 0.
  
  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 object 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:
  Security_Detections_API_ExternalRuleSource object Security_Detections_API_InternalRuleSource object
  
  Type of rule source for externally sourced rules, i.e. rules that have an external source, such as the Elastic Prebuilt rules repo.
  
  Hide attributes Show attributes
  
  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).
  
  type string Required Discriminator
  
  Value is external.
  
  updated_at string(date-time) Required
  
  updated_by string Required
  
  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.
  
  threshold object Required
  
  Hide threshold attributes Show threshold attributes object
  
  cardinality array[object]
  
  The field on which the cardinality is applied.
  
  Hide cardinality attributes Show cardinality attributes object
  
  field string Required
  
  The field on which to calculate and compare the cardinality.
  
  value integer Required
  
  The threshold value from which an alert is generated based on unique number of values of cardinality.field.
  
  Minimum value is 0.
  
  field string | array[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.
  
  One of:
  string-1 string array-2 array[string]
  
  value integer Required
  
  The threshold value from which an alert is generated.
  
  Minimum value is 1.
  
  type string Required Discriminator
  
  Rule type
  
  Value is threshold.
  
  alert_suppression object
  
  Defines alert suppression configuration.
  
  Hide alert_suppression attribute Show alert_suppression attribute object
  
  duration object Required
  
  Hide duration attributes Show duration attributes object
  
  unit string Required
  
  Time unit
  
  Values are s, m, or h.
  
  value integer Required
  
  Minimum value is 1.
  
  data_view_id string
  
  filters array
  
  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 array[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.
  
  saved_id string
  
  Kibana saved search used by the rule to create alerts.
  
  language string Required
  
  Values are kuery or lucene.
  
  Hide attributes Show attributes
  
  actions array[object] Required
  
  Array defining the automated actions (notifications) taken when alerts are generated.
  
  Hide actions attributes Show actions attributes object
  
  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.
  
  Additional properties are allowed.
  
  frequency object
  
  The action frequency defines when the action runs (for example, only on rule execution or at specific time intervals).
  
  Hide frequency attributes Show frequency attributes object
  
  notifyWhen string Required
  
  Defines how often rules run actions.
  
  Values are onActiveAlert, onThrottleInterval, or 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 string | null Required
  
  Defines how often rule actions are taken.
  
  One of:
  string-1 string | null string-2 string | null
  
  Values are no_actions or 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.
  
  Additional properties are allowed.
  
  uuid string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  alias_purpose string
  
  Values are savedObjectConversion or savedObjectImport.
  
  alias_target_id string
  
  author array[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 Required
  
  The rule’s description.
  
  Minimum length is 1.
  
  enabled boolean Required
  
  Determines whether the rule is enabled. Defaults to true.
  
  exceptions_list array[object] Required
  
  Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.
  
  Hide exceptions_list attributes Show exceptions_list attributes object
  
  id string(nonempty) Required
  
  ID of the exception container
  
  Minimum length is 1.
  
  list_id string(nonempty) Required
  
  List ID of the exception container
  
  Minimum length is 1.
  
  namespace_type string Required
  
  Determines the exceptions validity in rule's Kibana space
  
  Values are agnostic or single.
  
  type string Required
  
  The exception type
  
  Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.
  
  false_positives array[string] Required
  
  String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.
  
  from string(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.
  
  Hide investigation_fields attribute Show investigation_fields attribute object
  
  field_names array[string(nonempty)] Required
  
  A string that does not contain only whitespace characters
  
  At least 1 element. Minimum length of each is 1.
  
  license string
  
  The rule's license.
  
  max_signals integer Required
  
  Maximum number of alerts the rule can create during a single run (the rule’s Max alerts per run advanced setting value).
  
  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.
  
  Minimum value is 1. Default value is 100.
  
  meta object
  
  Placeholder for metadata about the rule.
  
  This field is overwritten when you save changes to the rule’s settings.
  
  Additional properties are allowed.
  
  name string Required
  
  A human-readable name for the rule.
  
  Minimum length is 1.
  
  namespace string
  
  Has no effect.
  
  note string
  
  Notes to help investigate alerts produced by the rule.
  
  outcome string
  
  Values are exactMatch, aliasMatch, or conflict.
  
  output_index string Deprecated
  
  (deprecated) Has no effect.
  
  references array[string] Required
  
  Array containing notes about or references to relevant information about the rule. Defaults to an empty array.
  
  related_integrations array[object] Required
  
  Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.
  
  NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.
  
  Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:
  
  package: name of the package (required, unique id)
  
  version: version of the package (required, semver-compatible)
  
  integration: name of the integration of this package (optional, id within the package)
  
  There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.
  
  Hide related_integrations attributes Show related_integrations attributes object
  
  integration string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  package string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  version string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  required_fields array[object] Required
  
  Elasticsearch fields and their types that need to be present for the rule to function.
  
  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.
  
  Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.
  
  Hide required_fields attributes Show required_fields attributes object
  
  name string(nonempty) Required
  
  Name of an Elasticsearch field
  
  Minimum length is 1.
  
  type string(nonempty) Required
  
  Type of the Elasticsearch field
  
  Minimum length is 1.
  
  response_actions array[object]
  
  One of:
  Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object
  
  Hide attributes Show attributes
  
  action_type_id string Required
  
  Value is .osquery.
  
  params object Required
  
  Hide params attributes Show params attributes object
  
  ecs_mapping object
  
  Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}
  
  Hide ecs_mapping attribute Show ecs_mapping attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  field string
  
  value string | array[string]
  
  One of:
  string-1 string array-2 array[string]
  
  pack_id string
  
  To specify a query pack, use the packId field. Example: "packId": "processes_elastic"
  
  queries array[object]
  
  Hide queries attributes Show queries attributes object
  
  ecs_mapping object
  
  Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}
  
  Hide ecs_mapping attribute Show ecs_mapping attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  field string
  
  value string | array[string]
  
  One of:
  string-1 string array-2 array[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.
  
  Hide attributes Show attributes
  
  action_type_id string Required
  
  Value is .endpoint.
  
  params object Required
  
  One of:
  Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object
  
  Hide attributes Show attributes
  
  command string Required
  
  Value is isolate.
  
  comment string
  
  Hide attributes Show attributes
  
  command string Required
  
  To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"
  
  Values are kill-process or suspend-process.
  
  comment string
  
  Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"
  
  config object Required
  
  Hide config attributes Show config attributes object
  
  field string Required
  
  Field to use instead of process.pid
  
  overwrite boolean
  
  Whether to overwrite field with process.pid
  
  Default value is true.
  
  risk_score integer 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
  
  Minimum value is 0, maximum value is 100.
  
  risk_score_mapping array[object] Required
  
  Overrides generated alerts' risk_score with a value from the source event
  
  Hide risk_score_mapping attributes Show risk_score_mapping attributes object
  
  field string Required
  
  Source event field used to override the default risk_score.
  
  operator string Required
  
  Value is equals.
  
  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
  
  Minimum value is 0, maximum value is 100.
  
  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 string 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 are low, medium, high, or critical.
  
  severity_mapping array[object] Required
  
  Overrides generated alerts' severity with values from the source event
  
  Hide severity_mapping attributes Show severity_mapping attributes object
  
  field string Required
  
  Source event field used to override the default severity.
  
  operator string Required
  
  Value is equals.
  
  severity string 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 are low, medium, high, or critical.
  
  value string Required
  
  tags array[string] Required
  
  String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.
  
  threat array[object] Required
  
  Currently, only threats described using the MITRE ATT&CK™ framework are supported.
  
  Hide threat attributes Show threat attributes object
  
  framework string Required
  
  Relevant attack framework
  
  tactic object Required
  
  Object containing information on the attack type
  
  Hide tactic attributes Show tactic attributes object
  
  id string Required
  
  Tactic ID
  
  name string Required
  
  Tactic name
  
  reference string Required
  
  Tactic reference
  
  technique array[object]
  
  Array containing information on the attack techniques (optional)
  
  Hide technique attributes Show technique attributes object
  
  id string Required
  
  Technique ID
  
  name string Required
  
  Technique name
  
  reference string Required
  
  Technique reference
  
  subtechnique array[object]
  
  Array containing more specific information on the attack technique.
  
  Hide subtechnique attributes Show subtechnique attributes object
  
  id string Required
  
  Subtechnique ID
  
  name string Required
  
  Subtechnique name
  
  reference string Required
  
  Subtechnique reference
  
  throttle string | null
  
  Defines how often rule actions are taken.
  
  One of:
  string-1 string | null string-2 string | null
  
  Values are no_actions or 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 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.
  
  It is not incremented on each update. Compare this to the revision field.
  
  Minimum value is 1.
  
  created_at string(date-time) Required
  
  created_by string Required
  
  execution_summary object
  
  Summary of the last execution of a rule.
  
  This field is under development and its usage or schema may change
  
  Hide execution_summary attribute Show execution_summary attribute object
  
  last_execution object Required
  
  Hide last_execution attributes Show last_execution attributes object
  
  date string(date-time) Required
  
  Date of the last execution
  
  message string Required
  
  metrics object Required
  
  Hide metrics attributes Show metrics attributes object
  
  execution_gap_duration_s integer
  
  Duration in seconds of execution gap
  
  Minimum value is 0.
  
  frozen_indices_queried_count integer
  
  Count of frozen indices queried during the rule execution. These indices could not be entirely excluded after applying the time range filter.
  
  Minimum value is 0.
  
  gap_range object
  
  Range of the execution gap
  
  Hide gap_range attributes Show gap_range attributes object
  
  gte string Required
  
  Start date of the execution gap
  
  lte string Required
  
  End date of the execution gap
  
  total_enrichment_duration_ms integer
  
  Total time spent enriching documents during current rule execution cycle
  
  Minimum value is 0.
  
  total_indexing_duration_ms integer
  
  Total time spent indexing documents during current rule execution cycle
  
  Minimum value is 0.
  
  total_search_duration_ms integer
  
  Total time spent performing ES searches as measured by Kibana; includes network latency and time spent serializing/deserializing request/response
  
  Minimum value is 0.
  
  status string Required
  
  Status of the last execution
  
  Values are going to run, running, partial failure, failed, or succeeded.
  
  status_order integer Required
  
  id string(uuid) Required
  
  A dynamic unique identifier for the rule object. It is randomly generated when a rule is created and cannot be changed after that. It is always a UUID. It is unique within a given Kibana space. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have different object ids.
  
  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 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.
  
  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.
  
  Minimum value is 0.
  
  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 object 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:
  Security_Detections_API_ExternalRuleSource object Security_Detections_API_InternalRuleSource object
  
  Type of rule source for externally sourced rules, i.e. rules that have an external source, such as the Elastic Prebuilt rules repo.
  
  Hide attributes Show attributes
  
  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).
  
  type string Required Discriminator
  
  Value is external.
  
  updated_at string(date-time) Required
  
  updated_by string Required
  
  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.
  
  threat_index array[string] Required
  
  Elasticsearch indices used to check which field values generate alerts.
  
  threat_mapping array[object] Required
  
  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 Example of Threat Match rule which uses both and and or logic.
  
  At least 1 element.
  
  Hide threat_mapping attribute Show threat_mapping attribute object
  
  entries array[object] Required
  
  Hide entries attributes Show entries attributes object
  
  field string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  type string Required
  
  Value is mapping.
  
  value string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  threat_query string Required
  
  Query used to determine which fields in the Elasticsearch index are used for generating alerts.
  
  type string Required Discriminator
  
  Rule type
  
  Value is threat_match.
  
  alert_suppression object
  
  Defines alert suppression configuration.
  
  Hide alert_suppression attributes Show alert_suppression attributes object
  
  duration object
  
  Hide duration attributes Show duration attributes object
  
  unit string Required
  
  Time unit
  
  Values are s, m, or h.
  
  value integer Required
  
  Minimum value is 1.
  
  group_by array[string] Required
  
  At least 1 but not more than 3 elements.
  
  missing_fields_strategy string
  
  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 are doNotSuppress or suppress.
  
  concurrent_searches integer
  
  Minimum value is 1.
  
  data_view_id string
  
  filters array
  
  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 array[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.
  
  items_per_search integer
  
  Minimum value is 1.
  
  saved_id string
  
  Kibana saved search used by the rule to create alerts.
  
  threat_filters array
  
  Query and filter context array used to filter documents from the Elasticsearch index containing the threat values
  
  threat_indicator_path string
  
  Defines the path to the threat indicator in the indicator documents (optional)
  
  threat_language string
  
  Values are kuery or lucene.
  
  language string Required
  
  Values are kuery or lucene.
  
  Hide attributes Show attributes
  
  actions array[object] Required
  
  Array defining the automated actions (notifications) taken when alerts are generated.
  
  Hide actions attributes Show actions attributes object
  
  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.
  
  Additional properties are allowed.
  
  frequency object
  
  The action frequency defines when the action runs (for example, only on rule execution or at specific time intervals).
  
  Hide frequency attributes Show frequency attributes object
  
  notifyWhen string Required
  
  Defines how often rules run actions.
  
  Values are onActiveAlert, onThrottleInterval, or 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 string | null Required
  
  Defines how often rule actions are taken.
  
  One of:
  string-1 string | null string-2 string | null
  
  Values are no_actions or 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.
  
  Additional properties are allowed.
  
  uuid string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  alias_purpose string
  
  Values are savedObjectConversion or savedObjectImport.
  
  alias_target_id string
  
  author array[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 Required
  
  The rule’s description.
  
  Minimum length is 1.
  
  enabled boolean Required
  
  Determines whether the rule is enabled. Defaults to true.
  
  exceptions_list array[object] Required
  
  Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.
  
  Hide exceptions_list attributes Show exceptions_list attributes object
  
  id string(nonempty) Required
  
  ID of the exception container
  
  Minimum length is 1.
  
  list_id string(nonempty) Required
  
  List ID of the exception container
  
  Minimum length is 1.
  
  namespace_type string Required
  
  Determines the exceptions validity in rule's Kibana space
  
  Values are agnostic or single.
  
  type string Required
  
  The exception type
  
  Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.
  
  false_positives array[string] Required
  
  String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.
  
  from string(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.
  
  Hide investigation_fields attribute Show investigation_fields attribute object
  
  field_names array[string(nonempty)] Required
  
  A string that does not contain only whitespace characters
  
  At least 1 element. Minimum length of each is 1.
  
  license string
  
  The rule's license.
  
  max_signals integer Required
  
  Maximum number of alerts the rule can create during a single run (the rule’s Max alerts per run advanced setting value).
  
  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.
  
  Minimum value is 1. Default value is 100.
  
  meta object
  
  Placeholder for metadata about the rule.
  
  This field is overwritten when you save changes to the rule’s settings.
  
  Additional properties are allowed.
  
  name string Required
  
  A human-readable name for the rule.
  
  Minimum length is 1.
  
  namespace string
  
  Has no effect.
  
  note string
  
  Notes to help investigate alerts produced by the rule.
  
  outcome string
  
  Values are exactMatch, aliasMatch, or conflict.
  
  output_index string Deprecated
  
  (deprecated) Has no effect.
  
  references array[string] Required
  
  Array containing notes about or references to relevant information about the rule. Defaults to an empty array.
  
  related_integrations array[object] Required
  
  Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.
  
  NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.
  
  Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:
  
  package: name of the package (required, unique id)
  
  version: version of the package (required, semver-compatible)
  
  integration: name of the integration of this package (optional, id within the package)
  
  There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.
  
  Hide related_integrations attributes Show related_integrations attributes object
  
  integration string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  package string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  version string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  required_fields array[object] Required
  
  Elasticsearch fields and their types that need to be present for the rule to function.
  
  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.
  
  Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.
  
  Hide required_fields attributes Show required_fields attributes object
  
  name string(nonempty) Required
  
  Name of an Elasticsearch field
  
  Minimum length is 1.
  
  type string(nonempty) Required
  
  Type of the Elasticsearch field
  
  Minimum length is 1.
  
  response_actions array[object]
  
  One of:
  Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object
  
  Hide attributes Show attributes
  
  action_type_id string Required
  
  Value is .osquery.
  
  params object Required
  
  Hide params attributes Show params attributes object
  
  ecs_mapping object
  
  Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}
  
  Hide ecs_mapping attribute Show ecs_mapping attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  field string
  
  value string | array[string]
  
  One of:
  string-1 string array-2 array[string]
  
  pack_id string
  
  To specify a query pack, use the packId field. Example: "packId": "processes_elastic"
  
  queries array[object]
  
  Hide queries attributes Show queries attributes object
  
  ecs_mapping object
  
  Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}
  
  Hide ecs_mapping attribute Show ecs_mapping attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  field string
  
  value string | array[string]
  
  One of:
  string-1 string array-2 array[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.
  
  Hide attributes Show attributes
  
  action_type_id string Required
  
  Value is .endpoint.
  
  params object Required
  
  One of:
  Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object
  
  Hide attributes Show attributes
  
  command string Required
  
  Value is isolate.
  
  comment string
  
  Hide attributes Show attributes
  
  command string Required
  
  To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"
  
  Values are kill-process or suspend-process.
  
  comment string
  
  Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"
  
  config object Required
  
  Hide config attributes Show config attributes object
  
  field string Required
  
  Field to use instead of process.pid
  
  overwrite boolean
  
  Whether to overwrite field with process.pid
  
  Default value is true.
  
  risk_score integer 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
  
  Minimum value is 0, maximum value is 100.
  
  risk_score_mapping array[object] Required
  
  Overrides generated alerts' risk_score with a value from the source event
  
  Hide risk_score_mapping attributes Show risk_score_mapping attributes object
  
  field string Required
  
  Source event field used to override the default risk_score.
  
  operator string Required
  
  Value is equals.
  
  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
  
  Minimum value is 0, maximum value is 100.
  
  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 string 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 are low, medium, high, or critical.
  
  severity_mapping array[object] Required
  
  Overrides generated alerts' severity with values from the source event
  
  Hide severity_mapping attributes Show severity_mapping attributes object
  
  field string Required
  
  Source event field used to override the default severity.
  
  operator string Required
  
  Value is equals.
  
  severity string 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 are low, medium, high, or critical.
  
  value string Required
  
  tags array[string] Required
  
  String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.
  
  threat array[object] Required
  
  Currently, only threats described using the MITRE ATT&CK™ framework are supported.
  
  Hide threat attributes Show threat attributes object
  
  framework string Required
  
  Relevant attack framework
  
  tactic object Required
  
  Object containing information on the attack type
  
  Hide tactic attributes Show tactic attributes object
  
  id string Required
  
  Tactic ID
  
  name string Required
  
  Tactic name
  
  reference string Required
  
  Tactic reference
  
  technique array[object]
  
  Array containing information on the attack techniques (optional)
  
  Hide technique attributes Show technique attributes object
  
  id string Required
  
  Technique ID
  
  name string Required
  
  Technique name
  
  reference string Required
  
  Technique reference
  
  subtechnique array[object]
  
  Array containing more specific information on the attack technique.
  
  Hide subtechnique attributes Show subtechnique attributes object
  
  id string Required
  
  Subtechnique ID
  
  name string Required
  
  Subtechnique name
  
  reference string Required
  
  Subtechnique reference
  
  throttle string | null
  
  Defines how often rule actions are taken.
  
  One of:
  string-1 string | null string-2 string | null
  
  Values are no_actions or 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 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.
  
  It is not incremented on each update. Compare this to the revision field.
  
  Minimum value is 1.
  
  created_at string(date-time) Required
  
  created_by string Required
  
  execution_summary object
  
  Summary of the last execution of a rule.
  
  This field is under development and its usage or schema may change
  
  Hide execution_summary attribute Show execution_summary attribute object
  
  last_execution object Required
  
  Hide last_execution attributes Show last_execution attributes object
  
  date string(date-time) Required
  
  Date of the last execution
  
  message string Required
  
  metrics object Required
  
  Hide metrics attributes Show metrics attributes object
  
  execution_gap_duration_s integer
  
  Duration in seconds of execution gap
  
  Minimum value is 0.
  
  frozen_indices_queried_count integer
  
  Count of frozen indices queried during the rule execution. These indices could not be entirely excluded after applying the time range filter.
  
  Minimum value is 0.
  
  gap_range object
  
  Range of the execution gap
  
  Hide gap_range attributes Show gap_range attributes object
  
  gte string Required
  
  Start date of the execution gap
  
  lte string Required
  
  End date of the execution gap
  
  total_enrichment_duration_ms integer
  
  Total time spent enriching documents during current rule execution cycle
  
  Minimum value is 0.
  
  total_indexing_duration_ms integer
  
  Total time spent indexing documents during current rule execution cycle
  
  Minimum value is 0.
  
  total_search_duration_ms integer
  
  Total time spent performing ES searches as measured by Kibana; includes network latency and time spent serializing/deserializing request/response
  
  Minimum value is 0.
  
  status string Required
  
  Status of the last execution
  
  Values are going to run, running, partial failure, failed, or succeeded.
  
  status_order integer Required
  
  id string(uuid) Required
  
  A dynamic unique identifier for the rule object. It is randomly generated when a rule is created and cannot be changed after that. It is always a UUID. It is unique within a given Kibana space. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have different object ids.
  
  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 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.
  
  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.
  
  Minimum value is 0.
  
  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 object 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:
  Security_Detections_API_ExternalRuleSource object Security_Detections_API_InternalRuleSource object
  
  Type of rule source for externally sourced rules, i.e. rules that have an external source, such as the Elastic Prebuilt rules repo.
  
  Hide attributes Show attributes
  
  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).
  
  type string Required Discriminator
  
  Value is external.
  
  updated_at string(date-time) Required
  
  updated_by string Required
  
  anomaly_threshold integer Required
  
  Anomaly score threshold above which the rule creates an alert. Valid values are from 0 to 100.
  
  Minimum value is 0.
  
  machine_learning_job_id string | array[string] Required
  
  Machine learning job ID(s) the rule monitors for anomaly scores.
  
  One of:
  string-1 string array-2 array[string]
  
  type string Required Discriminator
  
  Rule type
  
  Value is machine_learning.
  
  alert_suppression object
  
  Defines alert suppression configuration.
  
  Hide alert_suppression attributes Show alert_suppression attributes object
  
  duration object
  
  Hide duration attributes Show duration attributes object
  
  unit string Required
  
  Time unit
  
  Values are s, m, or h.
  
  value integer Required
  
  Minimum value is 1.
  
  group_by array[string] Required
  
  At least 1 but not more than 3 elements.
  
  missing_fields_strategy string
  
  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 are doNotSuppress or suppress.
  
  Hide attributes Show attributes
  
  actions array[object] Required
  
  Array defining the automated actions (notifications) taken when alerts are generated.
  
  Hide actions attributes Show actions attributes object
  
  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.
  
  Additional properties are allowed.
  
  frequency object
  
  The action frequency defines when the action runs (for example, only on rule execution or at specific time intervals).
  
  Hide frequency attributes Show frequency attributes object
  
  notifyWhen string Required
  
  Defines how often rules run actions.
  
  Values are onActiveAlert, onThrottleInterval, or 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 string | null Required
  
  Defines how often rule actions are taken.
  
  One of:
  string-1 string | null string-2 string | null
  
  Values are no_actions or 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.
  
  Additional properties are allowed.
  
  uuid string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  alias_purpose string
  
  Values are savedObjectConversion or savedObjectImport.
  
  alias_target_id string
  
  author array[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 Required
  
  The rule’s description.
  
  Minimum length is 1.
  
  enabled boolean Required
  
  Determines whether the rule is enabled. Defaults to true.
  
  exceptions_list array[object] Required
  
  Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.
  
  Hide exceptions_list attributes Show exceptions_list attributes object
  
  id string(nonempty) Required
  
  ID of the exception container
  
  Minimum length is 1.
  
  list_id string(nonempty) Required
  
  List ID of the exception container
  
  Minimum length is 1.
  
  namespace_type string Required
  
  Determines the exceptions validity in rule's Kibana space
  
  Values are agnostic or single.
  
  type string Required
  
  The exception type
  
  Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.
  
  false_positives array[string] Required
  
  String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.
  
  from string(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.
  
  Hide investigation_fields attribute Show investigation_fields attribute object
  
  field_names array[string(nonempty)] Required
  
  A string that does not contain only whitespace characters
  
  At least 1 element. Minimum length of each is 1.
  
  license string
  
  The rule's license.
  
  max_signals integer Required
  
  Maximum number of alerts the rule can create during a single run (the rule’s Max alerts per run advanced setting value).
  
  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.
  
  Minimum value is 1. Default value is 100.
  
  meta object
  
  Placeholder for metadata about the rule.
  
  This field is overwritten when you save changes to the rule’s settings.
  
  Additional properties are allowed.
  
  name string Required
  
  A human-readable name for the rule.
  
  Minimum length is 1.
  
  namespace string
  
  Has no effect.
  
  note string
  
  Notes to help investigate alerts produced by the rule.
  
  outcome string
  
  Values are exactMatch, aliasMatch, or conflict.
  
  output_index string Deprecated
  
  (deprecated) Has no effect.
  
  references array[string] Required
  
  Array containing notes about or references to relevant information about the rule. Defaults to an empty array.
  
  related_integrations array[object] Required
  
  Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.
  
  NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.
  
  Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:
  
  package: name of the package (required, unique id)
  
  version: version of the package (required, semver-compatible)
  
  integration: name of the integration of this package (optional, id within the package)
  
  There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.
  
  Hide related_integrations attributes Show related_integrations attributes object
  
  integration string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  package string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  version string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  required_fields array[object] Required
  
  Elasticsearch fields and their types that need to be present for the rule to function.
  
  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.
  
  Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.
  
  Hide required_fields attributes Show required_fields attributes object
  
  name string(nonempty) Required
  
  Name of an Elasticsearch field
  
  Minimum length is 1.
  
  type string(nonempty) Required
  
  Type of the Elasticsearch field
  
  Minimum length is 1.
  
  response_actions array[object]
  
  One of:
  Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object
  
  Hide attributes Show attributes
  
  action_type_id string Required
  
  Value is .osquery.
  
  params object Required
  
  Hide params attributes Show params attributes object
  
  ecs_mapping object
  
  Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}
  
  Hide ecs_mapping attribute Show ecs_mapping attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  field string
  
  value string | array[string]
  
  One of:
  string-1 string array-2 array[string]
  
  pack_id string
  
  To specify a query pack, use the packId field. Example: "packId": "processes_elastic"
  
  queries array[object]
  
  Hide queries attributes Show queries attributes object
  
  ecs_mapping object
  
  Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}
  
  Hide ecs_mapping attribute Show ecs_mapping attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  field string
  
  value string | array[string]
  
  One of:
  string-1 string array-2 array[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.
  
  Hide attributes Show attributes
  
  action_type_id string Required
  
  Value is .endpoint.
  
  params object Required
  
  One of:
  Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object
  
  Hide attributes Show attributes
  
  command string Required
  
  Value is isolate.
  
  comment string
  
  Hide attributes Show attributes
  
  command string Required
  
  To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"
  
  Values are kill-process or suspend-process.
  
  comment string
  
  Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"
  
  config object Required
  
  Hide config attributes Show config attributes object
  
  field string Required
  
  Field to use instead of process.pid
  
  overwrite boolean
  
  Whether to overwrite field with process.pid
  
  Default value is true.
  
  risk_score integer 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
  
  Minimum value is 0, maximum value is 100.
  
  risk_score_mapping array[object] Required
  
  Overrides generated alerts' risk_score with a value from the source event
  
  Hide risk_score_mapping attributes Show risk_score_mapping attributes object
  
  field string Required
  
  Source event field used to override the default risk_score.
  
  operator string Required
  
  Value is equals.
  
  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
  
  Minimum value is 0, maximum value is 100.
  
  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 string 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 are low, medium, high, or critical.
  
  severity_mapping array[object] Required
  
  Overrides generated alerts' severity with values from the source event
  
  Hide severity_mapping attributes Show severity_mapping attributes object
  
  field string Required
  
  Source event field used to override the default severity.
  
  operator string Required
  
  Value is equals.
  
  severity string 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 are low, medium, high, or critical.
  
  value string Required
  
  tags array[string] Required
  
  String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.
  
  threat array[object] Required
  
  Currently, only threats described using the MITRE ATT&CK™ framework are supported.
  
  Hide threat attributes Show threat attributes object
  
  framework string Required
  
  Relevant attack framework
  
  tactic object Required
  
  Object containing information on the attack type
  
  Hide tactic attributes Show tactic attributes object
  
  id string Required
  
  Tactic ID
  
  name string Required
  
  Tactic name
  
  reference string Required
  
  Tactic reference
  
  technique array[object]
  
  Array containing information on the attack techniques (optional)
  
  Hide technique attributes Show technique attributes object
  
  id string Required
  
  Technique ID
  
  name string Required
  
  Technique name
  
  reference string Required
  
  Technique reference
  
  subtechnique array[object]
  
  Array containing more specific information on the attack technique.
  
  Hide subtechnique attributes Show subtechnique attributes object
  
  id string Required
  
  Subtechnique ID
  
  name string Required
  
  Subtechnique name
  
  reference string Required
  
  Subtechnique reference
  
  throttle string | null
  
  Defines how often rule actions are taken.
  
  One of:
  string-1 string | null string-2 string | null
  
  Values are no_actions or 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 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.
  
  It is not incremented on each update. Compare this to the revision field.
  
  Minimum value is 1.
  
  created_at string(date-time) Required
  
  created_by string Required
  
  execution_summary object
  
  Summary of the last execution of a rule.
  
  This field is under development and its usage or schema may change
  
  Hide execution_summary attribute Show execution_summary attribute object
  
  last_execution object Required
  
  Hide last_execution attributes Show last_execution attributes object
  
  date string(date-time) Required
  
  Date of the last execution
  
  message string Required
  
  metrics object Required
  
  Hide metrics attributes Show metrics attributes object
  
  execution_gap_duration_s integer
  
  Duration in seconds of execution gap
  
  Minimum value is 0.
  
  frozen_indices_queried_count integer
  
  Count of frozen indices queried during the rule execution. These indices could not be entirely excluded after applying the time range filter.
  
  Minimum value is 0.
  
  gap_range object
  
  Range of the execution gap
  
  Hide gap_range attributes Show gap_range attributes object
  
  gte string Required
  
  Start date of the execution gap
  
  lte string Required
  
  End date of the execution gap
  
  total_enrichment_duration_ms integer
  
  Total time spent enriching documents during current rule execution cycle
  
  Minimum value is 0.
  
  total_indexing_duration_ms integer
  
  Total time spent indexing documents during current rule execution cycle
  
  Minimum value is 0.
  
  total_search_duration_ms integer
  
  Total time spent performing ES searches as measured by Kibana; includes network latency and time spent serializing/deserializing request/response
  
  Minimum value is 0.
  
  status string Required
  
  Status of the last execution
  
  Values are going to run, running, partial failure, failed, or succeeded.
  
  status_order integer Required
  
  id string(uuid) Required
  
  A dynamic unique identifier for the rule object. It is randomly generated when a rule is created and cannot be changed after that. It is always a UUID. It is unique within a given Kibana space. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have different object ids.
  
  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 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.
  
  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.
  
  Minimum value is 0.
  
  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 object 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:
  Security_Detections_API_ExternalRuleSource object Security_Detections_API_InternalRuleSource object
  
  Type of rule source for externally sourced rules, i.e. rules that have an external source, such as the Elastic Prebuilt rules repo.
  
  Hide attributes Show attributes
  
  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).
  
  type string Required Discriminator
  
  Value is external.
  
  updated_at string(date-time) Required
  
  updated_by string Required
  
  history_window_start string(nonempty) Required
  
  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.
  
  Minimum length is 1.
  
  new_terms_fields array[string] Required
  
  Fields to monitor for new values.
  
  At least 1 but not more than 3 elements.
  
  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.
  
  type string Required Discriminator
  
  Rule type
  
  Value is new_terms.
  
  alert_suppression object
  
  Defines alert suppression configuration.
  
  Hide alert_suppression attributes Show alert_suppression attributes object
  
  duration object
  
  Hide duration attributes Show duration attributes object
  
  unit string Required
  
  Time unit
  
  Values are s, m, or h.
  
  value integer Required
  
  Minimum value is 1.
  
  group_by array[string] Required
  
  At least 1 but not more than 3 elements.
  
  missing_fields_strategy string
  
  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 are doNotSuppress or suppress.
  
  data_view_id string
  
  filters array
  
  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 array[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.
  
  language string Required
  
  Values are kuery or lucene.
  
  Hide attributes Show attributes
  
  actions array[object] Required
  
  Array defining the automated actions (notifications) taken when alerts are generated.
  
  Hide actions attributes Show actions attributes object
  
  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.
  
  Additional properties are allowed.
  
  frequency object
  
  The action frequency defines when the action runs (for example, only on rule execution or at specific time intervals).
  
  Hide frequency attributes Show frequency attributes object
  
  notifyWhen string Required
  
  Defines how often rules run actions.
  
  Values are onActiveAlert, onThrottleInterval, or 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 string | null Required
  
  Defines how often rule actions are taken.
  
  One of:
  string-1 string | null string-2 string | null
  
  Values are no_actions or 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.
  
  Additional properties are allowed.
  
  uuid string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  alias_purpose string
  
  Values are savedObjectConversion or savedObjectImport.
  
  alias_target_id string
  
  author array[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 Required
  
  The rule’s description.
  
  Minimum length is 1.
  
  enabled boolean Required
  
  Determines whether the rule is enabled. Defaults to true.
  
  exceptions_list array[object] Required
  
  Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.
  
  Hide exceptions_list attributes Show exceptions_list attributes object
  
  id string(nonempty) Required
  
  ID of the exception container
  
  Minimum length is 1.
  
  list_id string(nonempty) Required
  
  List ID of the exception container
  
  Minimum length is 1.
  
  namespace_type string Required
  
  Determines the exceptions validity in rule's Kibana space
  
  Values are agnostic or single.
  
  type string Required
  
  The exception type
  
  Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.
  
  false_positives array[string] Required
  
  String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.
  
  from string(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.
  
  Hide investigation_fields attribute Show investigation_fields attribute object
  
  field_names array[string(nonempty)] Required
  
  A string that does not contain only whitespace characters
  
  At least 1 element. Minimum length of each is 1.
  
  license string
  
  The rule's license.
  
  max_signals integer Required
  
  Maximum number of alerts the rule can create during a single run (the rule’s Max alerts per run advanced setting value).
  
  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.
  
  Minimum value is 1. Default value is 100.
  
  meta object
  
  Placeholder for metadata about the rule.
  
  This field is overwritten when you save changes to the rule’s settings.
  
  Additional properties are allowed.
  
  name string Required
  
  A human-readable name for the rule.
  
  Minimum length is 1.
  
  namespace string
  
  Has no effect.
  
  note string
  
  Notes to help investigate alerts produced by the rule.
  
  outcome string
  
  Values are exactMatch, aliasMatch, or conflict.
  
  output_index string Deprecated
  
  (deprecated) Has no effect.
  
  references array[string] Required
  
  Array containing notes about or references to relevant information about the rule. Defaults to an empty array.
  
  related_integrations array[object] Required
  
  Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.
  
  NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.
  
  Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:
  
  package: name of the package (required, unique id)
  
  version: version of the package (required, semver-compatible)
  
  integration: name of the integration of this package (optional, id within the package)
  
  There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.
  
  Hide related_integrations attributes Show related_integrations attributes object
  
  integration string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  package string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  version string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  required_fields array[object] Required
  
  Elasticsearch fields and their types that need to be present for the rule to function.
  
  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.
  
  Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.
  
  Hide required_fields attributes Show required_fields attributes object
  
  name string(nonempty) Required
  
  Name of an Elasticsearch field
  
  Minimum length is 1.
  
  type string(nonempty) Required
  
  Type of the Elasticsearch field
  
  Minimum length is 1.
  
  response_actions array[object]
  
  One of:
  Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object
  
  Hide attributes Show attributes
  
  action_type_id string Required
  
  Value is .osquery.
  
  params object Required
  
  Hide params attributes Show params attributes object
  
  ecs_mapping object
  
  Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}
  
  Hide ecs_mapping attribute Show ecs_mapping attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  field string
  
  value string | array[string]
  
  One of:
  string-1 string array-2 array[string]
  
  pack_id string
  
  To specify a query pack, use the packId field. Example: "packId": "processes_elastic"
  
  queries array[object]
  
  Hide queries attributes Show queries attributes object
  
  ecs_mapping object
  
  Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}
  
  Hide ecs_mapping attribute Show ecs_mapping attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  field string
  
  value string | array[string]
  
  One of:
  string-1 string array-2 array[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.
  
  Hide attributes Show attributes
  
  action_type_id string Required
  
  Value is .endpoint.
  
  params object Required
  
  One of:
  Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object
  
  Hide attributes Show attributes
  
  command string Required
  
  Value is isolate.
  
  comment string
  
  Hide attributes Show attributes
  
  command string Required
  
  To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"
  
  Values are kill-process or suspend-process.
  
  comment string
  
  Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"
  
  config object Required
  
  Hide config attributes Show config attributes object
  
  field string Required
  
  Field to use instead of process.pid
  
  overwrite boolean
  
  Whether to overwrite field with process.pid
  
  Default value is true.
  
  risk_score integer 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
  
  Minimum value is 0, maximum value is 100.
  
  risk_score_mapping array[object] Required
  
  Overrides generated alerts' risk_score with a value from the source event
  
  Hide risk_score_mapping attributes Show risk_score_mapping attributes object
  
  field string Required
  
  Source event field used to override the default risk_score.
  
  operator string Required
  
  Value is equals.
  
  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
  
  Minimum value is 0, maximum value is 100.
  
  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 string 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 are low, medium, high, or critical.
  
  severity_mapping array[object] Required
  
  Overrides generated alerts' severity with values from the source event
  
  Hide severity_mapping attributes Show severity_mapping attributes object
  
  field string Required
  
  Source event field used to override the default severity.
  
  operator string Required
  
  Value is equals.
  
  severity string 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 are low, medium, high, or critical.
  
  value string Required
  
  tags array[string] Required
  
  String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.
  
  threat array[object] Required
  
  Currently, only threats described using the MITRE ATT&CK™ framework are supported.
  
  Hide threat attributes Show threat attributes object
  
  framework string Required
  
  Relevant attack framework
  
  tactic object Required
  
  Object containing information on the attack type
  
  Hide tactic attributes Show tactic attributes object
  
  id string Required
  
  Tactic ID
  
  name string Required
  
  Tactic name
  
  reference string Required
  
  Tactic reference
  
  technique array[object]
  
  Array containing information on the attack techniques (optional)
  
  Hide technique attributes Show technique attributes object
  
  id string Required
  
  Technique ID
  
  name string Required
  
  Technique name
  
  reference string Required
  
  Technique reference
  
  subtechnique array[object]
  
  Array containing more specific information on the attack technique.
  
  Hide subtechnique attributes Show subtechnique attributes object
  
  id string Required
  
  Subtechnique ID
  
  name string Required
  
  Subtechnique name
  
  reference string Required
  
  Subtechnique reference
  
  throttle string | null
  
  Defines how often rule actions are taken.
  
  One of:
  string-1 string | null string-2 string | null
  
  Values are no_actions or 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 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.
  
  It is not incremented on each update. Compare this to the revision field.
  
  Minimum value is 1.
  
  created_at string(date-time) Required
  
  created_by string Required
  
  execution_summary object
  
  Summary of the last execution of a rule.
  
  This field is under development and its usage or schema may change
  
  Hide execution_summary attribute Show execution_summary attribute object
  
  last_execution object Required
  
  Hide last_execution attributes Show last_execution attributes object
  
  date string(date-time) Required
  
  Date of the last execution
  
  message string Required
  
  metrics object Required
  
  Hide metrics attributes Show metrics attributes object
  
  execution_gap_duration_s integer
  
  Duration in seconds of execution gap
  
  Minimum value is 0.
  
  frozen_indices_queried_count integer
  
  Count of frozen indices queried during the rule execution. These indices could not be entirely excluded after applying the time range filter.
  
  Minimum value is 0.
  
  gap_range object
  
  Range of the execution gap
  
  Hide gap_range attributes Show gap_range attributes object
  
  gte string Required
  
  Start date of the execution gap
  
  lte string Required
  
  End date of the execution gap
  
  total_enrichment_duration_ms integer
  
  Total time spent enriching documents during current rule execution cycle
  
  Minimum value is 0.
  
  total_indexing_duration_ms integer
  
  Total time spent indexing documents during current rule execution cycle
  
  Minimum value is 0.
  
  total_search_duration_ms integer
  
  Total time spent performing ES searches as measured by Kibana; includes network latency and time spent serializing/deserializing request/response
  
  Minimum value is 0.
  
  status string Required
  
  Status of the last execution
  
  Values are going to run, running, partial failure, failed, or succeeded.
  
  status_order integer Required
  
  id string(uuid) Required
  
  A dynamic unique identifier for the rule object. It is randomly generated when a rule is created and cannot be changed after that. It is always a UUID. It is unique within a given Kibana space. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have different object ids.
  
  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 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.
  
  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.
  
  Minimum value is 0.
  
  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 object 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:
  Security_Detections_API_ExternalRuleSource object Security_Detections_API_InternalRuleSource object
  
  Type of rule source for externally sourced rules, i.e. rules that have an external source, such as the Elastic Prebuilt rules repo.
  
  Hide attributes Show attributes
  
  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).
  
  type string Required Discriminator
  
  Value is external.
  
  updated_at string(date-time) Required
  
  updated_by string Required
  
  alert_suppression object
  
  Defines alert suppression configuration.
  
  Hide alert_suppression attributes Show alert_suppression attributes object
  
  duration object
  
  Hide duration attributes Show duration attributes object
  
  unit string Required
  
  Time unit
  
  Values are s, m, or h.
  
  value integer Required
  
  Minimum value is 1.
  
  group_by array[string] Required
  
  At least 1 but not more than 3 elements.
  
  missing_fields_strategy string
  
  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 are doNotSuppress or suppress.
  
  language string Required
  
  Value is esql.
  
  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.
  
  type string Required Discriminator
  
  Rule type
  
  Value is esql.
- page integer Required
- perPage integer Required
- total integer Required

GET /api/detection_engine/rules/_find

curl -X GET "localhost:5601/api/detection_engine/rules/_find?page=1&per_page=5&sort_field=enabled&sort_order=asc&filter=alert.attributes.name:windows" -H 'kbn-xsrf: true'

Response examples (200)

{
  "data": [
    {
      "id": "89761517-fdb0-4223-b67b-7621acc48f9e",
      "to": "now",
      "from": "now-6m",
      "name": "Windows Script Executing PowerShell",
      "tags": [
        "Elastic",
        "Windows"
      ],
      "type": "query",
      "index": [
        "winlogbeat-*"
      ],
      "query": "event.action:\"Process Create (rule: ProcessCreate)\" and process.parent.name:(\"wscript.exe\" or \"cscript.exe\") and process.name:\"powershell.exe\"",
      "setup": "",
      "threat": [
        {
          "tactic": {
            "id": "TA0002",
            "name": "Execution",
            "reference": "https://attack.mitre.org/tactics/TA0002/"
          },
          "framework": "MITRE ATT&CK",
          "technique": [
            {
              "id": "T1193",
              "name": "Spearphishing Attachment",
              "reference": "https://attack.mitre.org/techniques/T1193/"
            }
          ]
        }
      ],
      "enabled": false,
      "rule_id": "f545ff26-3c94-4fd0-bd33-3c7f95a3a0fc",
      "interval": "5m",
      "language": "kuery",
      "severity": "low",
      "immutable": true,
      "created_at": "2020-02-02T10:05:19.613Z",
      "created_by": "elastic",
      "references": [],
      "risk_score": 21,
      "updated_at": "2020-02-02T10:05:19.830Z",
      "updated_by": "elastic",
      "description": "Identifies a PowerShell process launched by either cscript.exe or wscript.exe. Observing Windows scripting processes executing a PowerShell script, may be indicative of malicious activity.",
      "max_signals": 33,
      "false_positives": [],
      "required_fields": [
        {
          "ecs": true,
          "name": "event.action",
          "type": "keyword"
        },
        {
          "ecs": true,
          "name": "process.name",
          "type": "keyword"
        },
        {
          "ecs": true,
          "name": "process.parent.name",
          "type": "keyword"
        }
      ],
      "execution_summary": {
        "last_execution": {
          "date": "2022-03-23T16:06:12.787Z",
          "status": "partial failure",
          "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": {
            "execution_gap_duration_s": 0,
            "total_search_duration_ms": 135,
            "total_indexing_duration_ms": 15
          },
          "status_order": 20
        }
      },
      "related_integrations": [
        {
          "package": "o365",
          "version": "^2.3.2"
        }
      ]
    }
  ],
  "page": 1,
  "total": 4,
  "perPage": 5
}

Import detection rules

POST /api/detection_engine/rules/_import

Import detection rules from an .ndjson file, including actions and exception lists. The request must include:

The Content-Type: multipart/form-data HTTP header.
A link to the .ndjson file containing the rules.

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.

info To import rules with actions, you need at least Read privileges for the Action and Connectors feature. To overwrite or add new connectors, you need All privileges for the Actions and Connectors feature. To import rules without actions, you don’t need Actions and Connectors privileges. Refer to Enable and access detections for more information.

Rule actions and connectors are included in the exported file, but sensitive information about the connector (such as authentication credentials) is not included. You must re-add missing connector details after importing detection rules.

You can use Kibana’s Saved Objects UI (Stack Management → Kibana → Saved Objects) or the Saved Objects APIs (experimental) to export and import any necessary connectors before importing detection rules.

Similarly, any value lists used for rule exceptions are not included in rule exports or imports. Use the Manage value lists UI (Rules → Detection rules (SIEM) → Manage value lists) to export and import value lists separately.

Query parameters

overwrite boolean

Determines whether existing rules with the same rule_id are overwritten.

Default value is false.
overwrite_exceptions boolean

Determines whether existing exception lists with the same list_id are overwritten. Both the exception list container and its items are overwritten.

Default value is false.
overwrite_action_connectors boolean

Determines whether existing actions with the same kibana.alert.rule.actions.id are overwritten.

Default value is false.
as_new_list boolean

Generates a new list ID for each imported exception list.

Default value is false.

multipart/form-data

Body Required

file string(binary)

The .ndjson file containing the rules.

Responses

200 application/json

Indicates a successful call.
Hide response attributes Show response attributes object
- action_connectors_errors array[object] Required
  
  Hide action_connectors_errors attributes Show action_connectors_errors attributes object
  
  error object Required
  
  Hide error attributes Show error attributes object
  
  message string Required
  
  status_code integer Required
  
  Minimum value is 400.
  
  id string
  
  item_id string
  
  Minimum length is 1.
  
  list_id string
  
  Minimum length is 1.
  
  rule_id string
  
  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.
- action_connectors_success boolean Required
- action_connectors_success_count integer Required
  
  Minimum value is 0.
- action_connectors_warnings array[object] Required
  
  Hide action_connectors_warnings attributes Show action_connectors_warnings attributes object
  
  actionPath string Required
  
  buttonLabel string
  
  message string Required
  
  type string Required
- errors array[object] Required
  
  Hide errors attributes Show errors attributes object
  
  error object Required
  
  Hide error attributes Show error attributes object
  
  message string Required
  
  status_code integer Required
  
  Minimum value is 400.
  
  id string
  
  item_id string
  
  Minimum length is 1.
  
  list_id string
  
  Minimum length is 1.
  
  rule_id string
  
  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.
- exceptions_errors array[object] Required
  
  Hide exceptions_errors attributes Show exceptions_errors attributes object
  
  error object Required
  
  Hide error attributes Show error attributes object
  
  message string Required
  
  status_code integer Required
  
  Minimum value is 400.
  
  id string
  
  item_id string
  
  Minimum length is 1.
  
  list_id string
  
  Minimum length is 1.
  
  rule_id string
  
  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.
- exceptions_success boolean Required
- exceptions_success_count integer Required
  
  Minimum value is 0.
- rules_count integer Required
  
  Minimum value is 0.
- success boolean Required
- success_count integer Required
  
  Minimum value is 0.

POST /api/detection_engine/rules/_import

curl -X POST "<KibanaURL>/api/detection_engine/rules/_import"
-u <username>:<password> -H 'kbn-xsrf: true'
-H 'Content-Type: multipart/form-data'
--form "file=@<link to file>"

Response examples (200)

{
  "errors": [],
  "success": true,
  "rules_count": 1,
  "success_count": 1,
  "exceptions_errors": [],
  "exceptions_success": true,
  "exceptions_success_count": 0
}

Preview rule alerts generated on specified time range

POST /api/detection_engine/rules/preview

Query parameters

enable_logged_requests boolean

Enables logging and returning in response ES queries, performed during rule execution

application/json

Body object Required

An object containing tags to add or remove and alert ids the changes will be applied

actions array[object]

Array defining the automated actions (notifications) taken when alerts are generated.
Hide actions attributes Show actions attributes object
- 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.
  Additional properties are allowed.
- frequency object
  
  The action frequency defines when the action runs (for example, only on rule execution or at specific time intervals).
  Hide frequency attributes Show frequency attributes object
  
  notifyWhen string Required
  
  Defines how often rules run actions.
  
  Values are onActiveAlert, onThrottleInterval, or 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 string | null Required
  
  Defines how often rule actions are taken.
  
  One of:
  string-1 string | null string-2 string | null
  
  Values are no_actions or 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.
  Additional properties are allowed.
- uuid string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
alias_purpose string

Values are savedObjectConversion or savedObjectImport.
alias_target_id string
author array[string]

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 Required

The rule’s description.

Minimum length is 1.
enabled boolean

Determines whether the rule is enabled. Defaults to true.
exceptions_list array[object]

Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.
Hide exceptions_list attributes Show exceptions_list attributes object
- id string(nonempty) Required
  
  ID of the exception container
  
  Minimum length is 1.
- list_id string(nonempty) Required
  
  List ID of the exception container
  
  Minimum length is 1.
- namespace_type string Required
  
  Determines the exceptions validity in rule's Kibana space
  
  Values are agnostic or single.
- type string Required
  
  The exception type
  
  Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.
false_positives array[string]

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.
from string(date-math)

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

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.
Hide investigation_fields attribute Show investigation_fields attribute object
- field_names array[string(nonempty)] Required
  
  A string that does not contain only whitespace characters
  
  At least 1 element. Minimum length of each is 1.
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).

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.

Minimum value is 1. Default value is 100.
meta object

Placeholder for metadata about the rule.

This field is overwritten when you save changes to the rule’s settings.

Additional properties are allowed.
name string Required

A human-readable name for the rule.

Minimum length is 1.
namespace string

Has no effect.
note string

Notes to help investigate alerts produced by the rule.
outcome string

Values are exactMatch, aliasMatch, or conflict.
output_index string Deprecated

(deprecated) Has no effect.
references array[string]

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.
related_integrations array[object]
Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:
- package: name of the package (required, unique id)
- version: version of the package (required, semver-compatible)
- integration: name of the integration of this package (optional, id within the package)
There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.
Hide related_integrations attributes Show related_integrations attributes object
- integration string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- package string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- version string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
required_fields array[object]

Elasticsearch fields and their types that need to be present for the rule to function.

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.

Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.
Hide required_fields attributes Show required_fields attributes object
- name string(nonempty) Required
  
  Name of an Elasticsearch field
  
  Minimum length is 1.
- type string(nonempty) Required
  
  Type of the Elasticsearch field
  
  Minimum length is 1.
response_actions array[object]
One of:
Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object
Hide attributes Show attributes

action_type_id string Required

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

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

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[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.
Hide attributes Show attributes

action_type_id string Required

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object

Hide attributes Show attributes

command string Required

Value is isolate.

comment string

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.
risk_score integer 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
Minimum value is 0, maximum value is 100.
risk_score_mapping array[object]

Overrides generated alerts' risk_score with a value from the source event
Hide risk_score_mapping attributes Show risk_score_mapping attributes object
- field string Required
  
  Source event field used to override the default risk_score.
- operator string Required
  
  Value is equals.
- 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
  Minimum value is 0, maximum value is 100.
- value string Required
rule_id string

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

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 string 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 are low, medium, high, or critical.
severity_mapping array[object]

Overrides generated alerts' severity with values from the source event
Hide severity_mapping attributes Show severity_mapping attributes object
- field string Required
  
  Source event field used to override the default severity.
- operator string Required
  
  Value is equals.
- severity string 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 are low, medium, high, or critical.
- value string Required
tags array[string]

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.
threat array[object]

Currently, only threats described using the MITRE ATT&CK™ framework are supported.
Hide threat attributes Show threat attributes object
- framework string Required
  
  Relevant attack framework
- tactic object Required
  
  Object containing information on the attack type
  Hide tactic attributes Show tactic attributes object
  
  id string Required
  
  Tactic ID
  
  name string Required
  
  Tactic name
  
  reference string Required
  
  Tactic reference
- technique array[object]
  
  Array containing information on the attack techniques (optional)
  Hide technique attributes Show technique attributes object
  
  id string Required
  
  Technique ID
  
  name string Required
  
  Technique name
  
  reference string Required
  
  Technique reference
  
  subtechnique array[object]
  
  Array containing more specific information on the attack technique.
  
  Hide subtechnique attributes Show subtechnique attributes object
  
  id string Required
  
  Subtechnique ID
  
  name string Required
  
  Subtechnique name
  
  reference string Required
  
  Subtechnique reference
throttle string | null

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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
version integer
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.
It is not incremented on each update. Compare this to the revision field.
Minimum value is 1.
language string Required

Query language to use

Value is 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.
type string Required Discriminator

Rule type

Value is eql.
alert_suppression object

Defines alert suppression configuration.
Hide alert_suppression attributes Show alert_suppression attributes object
- duration object
  Hide duration attributes Show duration attributes object
  
  unit string Required
  
  Time unit
  
  Values are s, m, or h.
  
  value integer Required
  
  Minimum value is 1.
- group_by array[string] Required
  
  At least 1 but not more than 3 elements.
- missing_fields_strategy string
  
  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 are doNotSuppress or suppress.
data_view_id string
event_category_override string
filters array

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 array[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.
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.
invocationCount integer Required
timeframeEnd string(date-time) Required

actions array[object]

Array defining the automated actions (notifications) taken when alerts are generated.
Hide actions attributes Show actions attributes object
- 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.
  Additional properties are allowed.
- frequency object
  
  The action frequency defines when the action runs (for example, only on rule execution or at specific time intervals).
  Hide frequency attributes Show frequency attributes object
  
  notifyWhen string Required
  
  Defines how often rules run actions.
  
  Values are onActiveAlert, onThrottleInterval, or 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 string | null Required
  
  Defines how often rule actions are taken.
  
  One of:
  string-1 string | null string-2 string | null
  
  Values are no_actions or 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.
  Additional properties are allowed.
- uuid string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
alias_purpose string

Values are savedObjectConversion or savedObjectImport.
alias_target_id string
author array[string]

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 Required

The rule’s description.

Minimum length is 1.
enabled boolean

Determines whether the rule is enabled. Defaults to true.
exceptions_list array[object]

Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.
Hide exceptions_list attributes Show exceptions_list attributes object
- id string(nonempty) Required
  
  ID of the exception container
  
  Minimum length is 1.
- list_id string(nonempty) Required
  
  List ID of the exception container
  
  Minimum length is 1.
- namespace_type string Required
  
  Determines the exceptions validity in rule's Kibana space
  
  Values are agnostic or single.
- type string Required
  
  The exception type
  
  Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.
false_positives array[string]

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.
from string(date-math)

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

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.
Hide investigation_fields attribute Show investigation_fields attribute object
- field_names array[string(nonempty)] Required
  
  A string that does not contain only whitespace characters
  
  At least 1 element. Minimum length of each is 1.
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).

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.

Minimum value is 1. Default value is 100.
meta object

Placeholder for metadata about the rule.

This field is overwritten when you save changes to the rule’s settings.

Additional properties are allowed.
name string Required

A human-readable name for the rule.

Minimum length is 1.
namespace string

Has no effect.
note string

Notes to help investigate alerts produced by the rule.
outcome string

Values are exactMatch, aliasMatch, or conflict.
output_index string Deprecated

(deprecated) Has no effect.
references array[string]

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.
related_integrations array[object]
Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:
- package: name of the package (required, unique id)
- version: version of the package (required, semver-compatible)
- integration: name of the integration of this package (optional, id within the package)
There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.
Hide related_integrations attributes Show related_integrations attributes object
- integration string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- package string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- version string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
required_fields array[object]

Elasticsearch fields and their types that need to be present for the rule to function.

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.

Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.
Hide required_fields attributes Show required_fields attributes object
- name string(nonempty) Required
  
  Name of an Elasticsearch field
  
  Minimum length is 1.
- type string(nonempty) Required
  
  Type of the Elasticsearch field
  
  Minimum length is 1.
response_actions array[object]
One of:
Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object
Hide attributes Show attributes

action_type_id string Required

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

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

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[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.
Hide attributes Show attributes

action_type_id string Required

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object

Hide attributes Show attributes

command string Required

Value is isolate.

comment string

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.
risk_score integer 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
Minimum value is 0, maximum value is 100.
risk_score_mapping array[object]

Overrides generated alerts' risk_score with a value from the source event
Hide risk_score_mapping attributes Show risk_score_mapping attributes object
- field string Required
  
  Source event field used to override the default risk_score.
- operator string Required
  
  Value is equals.
- 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
  Minimum value is 0, maximum value is 100.
- value string Required
rule_id string

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

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 string 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 are low, medium, high, or critical.
severity_mapping array[object]

Overrides generated alerts' severity with values from the source event
Hide severity_mapping attributes Show severity_mapping attributes object
- field string Required
  
  Source event field used to override the default severity.
- operator string Required
  
  Value is equals.
- severity string 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 are low, medium, high, or critical.
- value string Required
tags array[string]

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.
threat array[object]

Currently, only threats described using the MITRE ATT&CK™ framework are supported.
Hide threat attributes Show threat attributes object
- framework string Required
  
  Relevant attack framework
- tactic object Required
  
  Object containing information on the attack type
  Hide tactic attributes Show tactic attributes object
  
  id string Required
  
  Tactic ID
  
  name string Required
  
  Tactic name
  
  reference string Required
  
  Tactic reference
- technique array[object]
  
  Array containing information on the attack techniques (optional)
  Hide technique attributes Show technique attributes object
  
  id string Required
  
  Technique ID
  
  name string Required
  
  Technique name
  
  reference string Required
  
  Technique reference
  
  subtechnique array[object]
  
  Array containing more specific information on the attack technique.
  
  Hide subtechnique attributes Show subtechnique attributes object
  
  id string Required
  
  Subtechnique ID
  
  name string Required
  
  Subtechnique name
  
  reference string Required
  
  Subtechnique reference
throttle string | null

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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
version integer
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.
It is not incremented on each update. Compare this to the revision field.
Minimum value is 1.
type string Required Discriminator

Rule type

Value is query.
alert_suppression object

Defines alert suppression configuration.
Hide alert_suppression attributes Show alert_suppression attributes object
- duration object
  Hide duration attributes Show duration attributes object
  
  unit string Required
  
  Time unit
  
  Values are s, m, or h.
  
  value integer Required
  
  Minimum value is 1.
- group_by array[string] Required
  
  At least 1 but not more than 3 elements.
- missing_fields_strategy string
  
  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 are doNotSuppress or suppress.
data_view_id string
filters array

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 array[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.
saved_id string

Kibana saved search used by the rule to create alerts.
language string

Values are kuery or lucene.
query string
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.
invocationCount integer Required
timeframeEnd string(date-time) Required

actions array[object]

Array defining the automated actions (notifications) taken when alerts are generated.
Hide actions attributes Show actions attributes object
- 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.
  Additional properties are allowed.
- frequency object
  
  The action frequency defines when the action runs (for example, only on rule execution or at specific time intervals).
  Hide frequency attributes Show frequency attributes object
  
  notifyWhen string Required
  
  Defines how often rules run actions.
  
  Values are onActiveAlert, onThrottleInterval, or 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 string | null Required
  
  Defines how often rule actions are taken.
  
  One of:
  string-1 string | null string-2 string | null
  
  Values are no_actions or 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.
  Additional properties are allowed.
- uuid string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
alias_purpose string

Values are savedObjectConversion or savedObjectImport.
alias_target_id string
author array[string]

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 Required

The rule’s description.

Minimum length is 1.
enabled boolean

Determines whether the rule is enabled. Defaults to true.
exceptions_list array[object]

Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.
Hide exceptions_list attributes Show exceptions_list attributes object
- id string(nonempty) Required
  
  ID of the exception container
  
  Minimum length is 1.
- list_id string(nonempty) Required
  
  List ID of the exception container
  
  Minimum length is 1.
- namespace_type string Required
  
  Determines the exceptions validity in rule's Kibana space
  
  Values are agnostic or single.
- type string Required
  
  The exception type
  
  Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.
false_positives array[string]

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.
from string(date-math)

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

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.
Hide investigation_fields attribute Show investigation_fields attribute object
- field_names array[string(nonempty)] Required
  
  A string that does not contain only whitespace characters
  
  At least 1 element. Minimum length of each is 1.
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).

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.

Minimum value is 1. Default value is 100.
meta object

Placeholder for metadata about the rule.

This field is overwritten when you save changes to the rule’s settings.

Additional properties are allowed.
name string Required

A human-readable name for the rule.

Minimum length is 1.
namespace string

Has no effect.
note string

Notes to help investigate alerts produced by the rule.
outcome string

Values are exactMatch, aliasMatch, or conflict.
output_index string Deprecated

(deprecated) Has no effect.
references array[string]

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.
related_integrations array[object]
Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:
- package: name of the package (required, unique id)
- version: version of the package (required, semver-compatible)
- integration: name of the integration of this package (optional, id within the package)
There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.
Hide related_integrations attributes Show related_integrations attributes object
- integration string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- package string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- version string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
required_fields array[object]

Elasticsearch fields and their types that need to be present for the rule to function.

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.

Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.
Hide required_fields attributes Show required_fields attributes object
- name string(nonempty) Required
  
  Name of an Elasticsearch field
  
  Minimum length is 1.
- type string(nonempty) Required
  
  Type of the Elasticsearch field
  
  Minimum length is 1.
response_actions array[object]
One of:
Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object
Hide attributes Show attributes

action_type_id string Required

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

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

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[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.
Hide attributes Show attributes

action_type_id string Required

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object

Hide attributes Show attributes

command string Required

Value is isolate.

comment string

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.
risk_score integer 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
Minimum value is 0, maximum value is 100.
risk_score_mapping array[object]

Overrides generated alerts' risk_score with a value from the source event
Hide risk_score_mapping attributes Show risk_score_mapping attributes object
- field string Required
  
  Source event field used to override the default risk_score.
- operator string Required
  
  Value is equals.
- 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
  Minimum value is 0, maximum value is 100.
- value string Required
rule_id string

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

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 string 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 are low, medium, high, or critical.
severity_mapping array[object]

Overrides generated alerts' severity with values from the source event
Hide severity_mapping attributes Show severity_mapping attributes object
- field string Required
  
  Source event field used to override the default severity.
- operator string Required
  
  Value is equals.
- severity string 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 are low, medium, high, or critical.
- value string Required
tags array[string]

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.
threat array[object]

Currently, only threats described using the MITRE ATT&CK™ framework are supported.
Hide threat attributes Show threat attributes object
- framework string Required
  
  Relevant attack framework
- tactic object Required
  
  Object containing information on the attack type
  Hide tactic attributes Show tactic attributes object
  
  id string Required
  
  Tactic ID
  
  name string Required
  
  Tactic name
  
  reference string Required
  
  Tactic reference
- technique array[object]
  
  Array containing information on the attack techniques (optional)
  Hide technique attributes Show technique attributes object
  
  id string Required
  
  Technique ID
  
  name string Required
  
  Technique name
  
  reference string Required
  
  Technique reference
  
  subtechnique array[object]
  
  Array containing more specific information on the attack technique.
  
  Hide subtechnique attributes Show subtechnique attributes object
  
  id string Required
  
  Subtechnique ID
  
  name string Required
  
  Subtechnique name
  
  reference string Required
  
  Subtechnique reference
throttle string | null

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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
version integer
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.
It is not incremented on each update. Compare this to the revision field.
Minimum value is 1.
saved_id string Required

Kibana saved search used by the rule to create alerts.
type string Required Discriminator

Rule type

Value is saved_query.
alert_suppression object

Defines alert suppression configuration.
Hide alert_suppression attributes Show alert_suppression attributes object
- duration object
  Hide duration attributes Show duration attributes object
  
  unit string Required
  
  Time unit
  
  Values are s, m, or h.
  
  value integer Required
  
  Minimum value is 1.
- group_by array[string] Required
  
  At least 1 but not more than 3 elements.
- missing_fields_strategy string
  
  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 are doNotSuppress or suppress.
data_view_id string
filters array

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 array[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.
query string
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.
language string

Values are kuery or lucene.
invocationCount integer Required
timeframeEnd string(date-time) Required

actions array[object]

Array defining the automated actions (notifications) taken when alerts are generated.
Hide actions attributes Show actions attributes object
- 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.
  Additional properties are allowed.
- frequency object
  
  The action frequency defines when the action runs (for example, only on rule execution or at specific time intervals).
  Hide frequency attributes Show frequency attributes object
  
  notifyWhen string Required
  
  Defines how often rules run actions.
  
  Values are onActiveAlert, onThrottleInterval, or 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 string | null Required
  
  Defines how often rule actions are taken.
  
  One of:
  string-1 string | null string-2 string | null
  
  Values are no_actions or 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.
  Additional properties are allowed.
- uuid string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
alias_purpose string

Values are savedObjectConversion or savedObjectImport.
alias_target_id string
author array[string]

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 Required

The rule’s description.

Minimum length is 1.
enabled boolean

Determines whether the rule is enabled. Defaults to true.
exceptions_list array[object]

Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.
Hide exceptions_list attributes Show exceptions_list attributes object
- id string(nonempty) Required
  
  ID of the exception container
  
  Minimum length is 1.
- list_id string(nonempty) Required
  
  List ID of the exception container
  
  Minimum length is 1.
- namespace_type string Required
  
  Determines the exceptions validity in rule's Kibana space
  
  Values are agnostic or single.
- type string Required
  
  The exception type
  
  Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.
false_positives array[string]

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.
from string(date-math)

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

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.
Hide investigation_fields attribute Show investigation_fields attribute object
- field_names array[string(nonempty)] Required
  
  A string that does not contain only whitespace characters
  
  At least 1 element. Minimum length of each is 1.
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).

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.

Minimum value is 1. Default value is 100.
meta object

Placeholder for metadata about the rule.

This field is overwritten when you save changes to the rule’s settings.

Additional properties are allowed.
name string Required

A human-readable name for the rule.

Minimum length is 1.
namespace string

Has no effect.
note string

Notes to help investigate alerts produced by the rule.
outcome string

Values are exactMatch, aliasMatch, or conflict.
output_index string Deprecated

(deprecated) Has no effect.
references array[string]

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.
related_integrations array[object]
Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:
- package: name of the package (required, unique id)
- version: version of the package (required, semver-compatible)
- integration: name of the integration of this package (optional, id within the package)
There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.
Hide related_integrations attributes Show related_integrations attributes object
- integration string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- package string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- version string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
required_fields array[object]

Elasticsearch fields and their types that need to be present for the rule to function.

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.

Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.
Hide required_fields attributes Show required_fields attributes object
- name string(nonempty) Required
  
  Name of an Elasticsearch field
  
  Minimum length is 1.
- type string(nonempty) Required
  
  Type of the Elasticsearch field
  
  Minimum length is 1.
response_actions array[object]
One of:
Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object
Hide attributes Show attributes

action_type_id string Required

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

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

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[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.
Hide attributes Show attributes

action_type_id string Required

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object

Hide attributes Show attributes

command string Required

Value is isolate.

comment string

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.
risk_score integer 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
Minimum value is 0, maximum value is 100.
risk_score_mapping array[object]

Overrides generated alerts' risk_score with a value from the source event
Hide risk_score_mapping attributes Show risk_score_mapping attributes object
- field string Required
  
  Source event field used to override the default risk_score.
- operator string Required
  
  Value is equals.
- 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
  Minimum value is 0, maximum value is 100.
- value string Required
rule_id string

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

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 string 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 are low, medium, high, or critical.
severity_mapping array[object]

Overrides generated alerts' severity with values from the source event
Hide severity_mapping attributes Show severity_mapping attributes object
- field string Required
  
  Source event field used to override the default severity.
- operator string Required
  
  Value is equals.
- severity string 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 are low, medium, high, or critical.
- value string Required
tags array[string]

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.
threat array[object]

Currently, only threats described using the MITRE ATT&CK™ framework are supported.
Hide threat attributes Show threat attributes object
- framework string Required
  
  Relevant attack framework
- tactic object Required
  
  Object containing information on the attack type
  Hide tactic attributes Show tactic attributes object
  
  id string Required
  
  Tactic ID
  
  name string Required
  
  Tactic name
  
  reference string Required
  
  Tactic reference
- technique array[object]
  
  Array containing information on the attack techniques (optional)
  Hide technique attributes Show technique attributes object
  
  id string Required
  
  Technique ID
  
  name string Required
  
  Technique name
  
  reference string Required
  
  Technique reference
  
  subtechnique array[object]
  
  Array containing more specific information on the attack technique.
  
  Hide subtechnique attributes Show subtechnique attributes object
  
  id string Required
  
  Subtechnique ID
  
  name string Required
  
  Subtechnique name
  
  reference string Required
  
  Subtechnique reference
throttle string | null

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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
version integer
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.
It is not incremented on each update. Compare this to the revision field.
Minimum value is 1.
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.
threshold object Required
Hide threshold attributes Show threshold attributes object
- cardinality array[object]
  
  The field on which the cardinality is applied.
  Hide cardinality attributes Show cardinality attributes object
  
  field string Required
  
  The field on which to calculate and compare the cardinality.
  
  value integer Required
  
  The threshold value from which an alert is generated based on unique number of values of cardinality.field.
  
  Minimum value is 0.
- field string | array[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.
  
  One of:
  string-1 string array-2 array[string]
- value integer Required
  
  The threshold value from which an alert is generated.
  
  Minimum value is 1.
type string Required Discriminator

Rule type

Value is threshold.
alert_suppression object

Defines alert suppression configuration.
Hide alert_suppression attribute Show alert_suppression attribute object
- duration object Required
  Hide duration attributes Show duration attributes object
  
  unit string Required
  
  Time unit
  
  Values are s, m, or h.
  
  value integer Required
  
  Minimum value is 1.
data_view_id string
filters array

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 array[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.
saved_id string

Kibana saved search used by the rule to create alerts.
language string

Values are kuery or lucene.
invocationCount integer Required
timeframeEnd string(date-time) Required

actions array[object]

Array defining the automated actions (notifications) taken when alerts are generated.
Hide actions attributes Show actions attributes object
- 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.
  Additional properties are allowed.
- frequency object
  
  The action frequency defines when the action runs (for example, only on rule execution or at specific time intervals).
  Hide frequency attributes Show frequency attributes object
  
  notifyWhen string Required
  
  Defines how often rules run actions.
  
  Values are onActiveAlert, onThrottleInterval, or 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 string | null Required
  
  Defines how often rule actions are taken.
  
  One of:
  string-1 string | null string-2 string | null
  
  Values are no_actions or 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.
  Additional properties are allowed.
- uuid string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
alias_purpose string

Values are savedObjectConversion or savedObjectImport.
alias_target_id string
author array[string]

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 Required

The rule’s description.

Minimum length is 1.
enabled boolean

Determines whether the rule is enabled. Defaults to true.
exceptions_list array[object]

Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.
Hide exceptions_list attributes Show exceptions_list attributes object
- id string(nonempty) Required
  
  ID of the exception container
  
  Minimum length is 1.
- list_id string(nonempty) Required
  
  List ID of the exception container
  
  Minimum length is 1.
- namespace_type string Required
  
  Determines the exceptions validity in rule's Kibana space
  
  Values are agnostic or single.
- type string Required
  
  The exception type
  
  Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.
false_positives array[string]

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.
from string(date-math)

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

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.
Hide investigation_fields attribute Show investigation_fields attribute object
- field_names array[string(nonempty)] Required
  
  A string that does not contain only whitespace characters
  
  At least 1 element. Minimum length of each is 1.
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).

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.

Minimum value is 1. Default value is 100.
meta object

Placeholder for metadata about the rule.

This field is overwritten when you save changes to the rule’s settings.

Additional properties are allowed.
name string Required

A human-readable name for the rule.

Minimum length is 1.
namespace string

Has no effect.
note string

Notes to help investigate alerts produced by the rule.
outcome string

Values are exactMatch, aliasMatch, or conflict.
output_index string Deprecated

(deprecated) Has no effect.
references array[string]

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.
related_integrations array[object]
Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:
- package: name of the package (required, unique id)
- version: version of the package (required, semver-compatible)
- integration: name of the integration of this package (optional, id within the package)
There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.
Hide related_integrations attributes Show related_integrations attributes object
- integration string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- package string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- version string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
required_fields array[object]

Elasticsearch fields and their types that need to be present for the rule to function.

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.

Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.
Hide required_fields attributes Show required_fields attributes object
- name string(nonempty) Required
  
  Name of an Elasticsearch field
  
  Minimum length is 1.
- type string(nonempty) Required
  
  Type of the Elasticsearch field
  
  Minimum length is 1.
response_actions array[object]
One of:
Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object
Hide attributes Show attributes

action_type_id string Required

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

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

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[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.
Hide attributes Show attributes

action_type_id string Required

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object

Hide attributes Show attributes

command string Required

Value is isolate.

comment string

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.
risk_score integer 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
Minimum value is 0, maximum value is 100.
risk_score_mapping array[object]

Overrides generated alerts' risk_score with a value from the source event
Hide risk_score_mapping attributes Show risk_score_mapping attributes object
- field string Required
  
  Source event field used to override the default risk_score.
- operator string Required
  
  Value is equals.
- 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
  Minimum value is 0, maximum value is 100.
- value string Required
rule_id string

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

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 string 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 are low, medium, high, or critical.
severity_mapping array[object]

Overrides generated alerts' severity with values from the source event
Hide severity_mapping attributes Show severity_mapping attributes object
- field string Required
  
  Source event field used to override the default severity.
- operator string Required
  
  Value is equals.
- severity string 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 are low, medium, high, or critical.
- value string Required
tags array[string]

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.
threat array[object]

Currently, only threats described using the MITRE ATT&CK™ framework are supported.
Hide threat attributes Show threat attributes object
- framework string Required
  
  Relevant attack framework
- tactic object Required
  
  Object containing information on the attack type
  Hide tactic attributes Show tactic attributes object
  
  id string Required
  
  Tactic ID
  
  name string Required
  
  Tactic name
  
  reference string Required
  
  Tactic reference
- technique array[object]
  
  Array containing information on the attack techniques (optional)
  Hide technique attributes Show technique attributes object
  
  id string Required
  
  Technique ID
  
  name string Required
  
  Technique name
  
  reference string Required
  
  Technique reference
  
  subtechnique array[object]
  
  Array containing more specific information on the attack technique.
  
  Hide subtechnique attributes Show subtechnique attributes object
  
  id string Required
  
  Subtechnique ID
  
  name string Required
  
  Subtechnique name
  
  reference string Required
  
  Subtechnique reference
throttle string | null

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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
version integer
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.
It is not incremented on each update. Compare this to the revision field.
Minimum value is 1.
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.
threat_index array[string] Required

Elasticsearch indices used to check which field values generate alerts.
threat_mapping array[object] Required
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 Example of Threat Match rule which uses both and and or logic.
At least 1 element.
Hide threat_mapping attribute Show threat_mapping attribute object
- entries array[object] Required
  Hide entries attributes Show entries attributes object
  
  field string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  type string Required
  
  Value is mapping.
  
  value string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
threat_query string Required

Query used to determine which fields in the Elasticsearch index are used for generating alerts.
type string Required Discriminator

Rule type

Value is threat_match.
alert_suppression object

Defines alert suppression configuration.
Hide alert_suppression attributes Show alert_suppression attributes object
- duration object
  Hide duration attributes Show duration attributes object
  
  unit string Required
  
  Time unit
  
  Values are s, m, or h.
  
  value integer Required
  
  Minimum value is 1.
- group_by array[string] Required
  
  At least 1 but not more than 3 elements.
- missing_fields_strategy string
  
  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 are doNotSuppress or suppress.
concurrent_searches integer

Minimum value is 1.
data_view_id string
filters array

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 array[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.
items_per_search integer

Minimum value is 1.
saved_id string

Kibana saved search used by the rule to create alerts.
threat_filters array

Query and filter context array used to filter documents from the Elasticsearch index containing the threat values
threat_indicator_path string

Defines the path to the threat indicator in the indicator documents (optional)
threat_language string

Values are kuery or lucene.
language string

Values are kuery or lucene.
invocationCount integer Required
timeframeEnd string(date-time) Required

actions array[object]

Array defining the automated actions (notifications) taken when alerts are generated.
Hide actions attributes Show actions attributes object
- 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.
  Additional properties are allowed.
- frequency object
  
  The action frequency defines when the action runs (for example, only on rule execution or at specific time intervals).
  Hide frequency attributes Show frequency attributes object
  
  notifyWhen string Required
  
  Defines how often rules run actions.
  
  Values are onActiveAlert, onThrottleInterval, or 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 string | null Required
  
  Defines how often rule actions are taken.
  
  One of:
  string-1 string | null string-2 string | null
  
  Values are no_actions or 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.
  Additional properties are allowed.
- uuid string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
alias_purpose string

Values are savedObjectConversion or savedObjectImport.
alias_target_id string
author array[string]

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 Required

The rule’s description.

Minimum length is 1.
enabled boolean

Determines whether the rule is enabled. Defaults to true.
exceptions_list array[object]

Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.
Hide exceptions_list attributes Show exceptions_list attributes object
- id string(nonempty) Required
  
  ID of the exception container
  
  Minimum length is 1.
- list_id string(nonempty) Required
  
  List ID of the exception container
  
  Minimum length is 1.
- namespace_type string Required
  
  Determines the exceptions validity in rule's Kibana space
  
  Values are agnostic or single.
- type string Required
  
  The exception type
  
  Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.
false_positives array[string]

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.
from string(date-math)

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

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.
Hide investigation_fields attribute Show investigation_fields attribute object
- field_names array[string(nonempty)] Required
  
  A string that does not contain only whitespace characters
  
  At least 1 element. Minimum length of each is 1.
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).

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.

Minimum value is 1. Default value is 100.
meta object

Placeholder for metadata about the rule.

This field is overwritten when you save changes to the rule’s settings.

Additional properties are allowed.
name string Required

A human-readable name for the rule.

Minimum length is 1.
namespace string

Has no effect.
note string

Notes to help investigate alerts produced by the rule.
outcome string

Values are exactMatch, aliasMatch, or conflict.
output_index string Deprecated

(deprecated) Has no effect.
references array[string]

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.
related_integrations array[object]
Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:
- package: name of the package (required, unique id)
- version: version of the package (required, semver-compatible)
- integration: name of the integration of this package (optional, id within the package)
There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.
Hide related_integrations attributes Show related_integrations attributes object
- integration string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- package string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- version string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
required_fields array[object]

Elasticsearch fields and their types that need to be present for the rule to function.

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.

Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.
Hide required_fields attributes Show required_fields attributes object
- name string(nonempty) Required
  
  Name of an Elasticsearch field
  
  Minimum length is 1.
- type string(nonempty) Required
  
  Type of the Elasticsearch field
  
  Minimum length is 1.
response_actions array[object]
One of:
Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object
Hide attributes Show attributes

action_type_id string Required

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

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

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[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.
Hide attributes Show attributes

action_type_id string Required

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object

Hide attributes Show attributes

command string Required

Value is isolate.

comment string

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.
risk_score integer 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
Minimum value is 0, maximum value is 100.
risk_score_mapping array[object]

Overrides generated alerts' risk_score with a value from the source event
Hide risk_score_mapping attributes Show risk_score_mapping attributes object
- field string Required
  
  Source event field used to override the default risk_score.
- operator string Required
  
  Value is equals.
- 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
  Minimum value is 0, maximum value is 100.
- value string Required
rule_id string

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

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 string 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 are low, medium, high, or critical.
severity_mapping array[object]

Overrides generated alerts' severity with values from the source event
Hide severity_mapping attributes Show severity_mapping attributes object
- field string Required
  
  Source event field used to override the default severity.
- operator string Required
  
  Value is equals.
- severity string 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 are low, medium, high, or critical.
- value string Required
tags array[string]

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.
threat array[object]

Currently, only threats described using the MITRE ATT&CK™ framework are supported.
Hide threat attributes Show threat attributes object
- framework string Required
  
  Relevant attack framework
- tactic object Required
  
  Object containing information on the attack type
  Hide tactic attributes Show tactic attributes object
  
  id string Required
  
  Tactic ID
  
  name string Required
  
  Tactic name
  
  reference string Required
  
  Tactic reference
- technique array[object]
  
  Array containing information on the attack techniques (optional)
  Hide technique attributes Show technique attributes object
  
  id string Required
  
  Technique ID
  
  name string Required
  
  Technique name
  
  reference string Required
  
  Technique reference
  
  subtechnique array[object]
  
  Array containing more specific information on the attack technique.
  
  Hide subtechnique attributes Show subtechnique attributes object
  
  id string Required
  
  Subtechnique ID
  
  name string Required
  
  Subtechnique name
  
  reference string Required
  
  Subtechnique reference
throttle string | null

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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
version integer
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.
It is not incremented on each update. Compare this to the revision field.
Minimum value is 1.
anomaly_threshold integer Required

Anomaly score threshold above which the rule creates an alert. Valid values are from 0 to 100.

Minimum value is 0.
machine_learning_job_id string | array[string] Required

Machine learning job ID(s) the rule monitors for anomaly scores.

One of:
string-1 string array-2 array[string]
type string Required Discriminator

Rule type

Value is machine_learning.
alert_suppression object

Defines alert suppression configuration.
Hide alert_suppression attributes Show alert_suppression attributes object
- duration object
  Hide duration attributes Show duration attributes object
  
  unit string Required
  
  Time unit
  
  Values are s, m, or h.
  
  value integer Required
  
  Minimum value is 1.
- group_by array[string] Required
  
  At least 1 but not more than 3 elements.
- missing_fields_strategy string
  
  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 are doNotSuppress or suppress.
invocationCount integer Required
timeframeEnd string(date-time) Required

actions array[object]

Array defining the automated actions (notifications) taken when alerts are generated.
Hide actions attributes Show actions attributes object
- 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.
  Additional properties are allowed.
- frequency object
  
  The action frequency defines when the action runs (for example, only on rule execution or at specific time intervals).
  Hide frequency attributes Show frequency attributes object
  
  notifyWhen string Required
  
  Defines how often rules run actions.
  
  Values are onActiveAlert, onThrottleInterval, or 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 string | null Required
  
  Defines how often rule actions are taken.
  
  One of:
  string-1 string | null string-2 string | null
  
  Values are no_actions or 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.
  Additional properties are allowed.
- uuid string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
alias_purpose string

Values are savedObjectConversion or savedObjectImport.
alias_target_id string
author array[string]

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 Required

The rule’s description.

Minimum length is 1.
enabled boolean

Determines whether the rule is enabled. Defaults to true.
exceptions_list array[object]

Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.
Hide exceptions_list attributes Show exceptions_list attributes object
- id string(nonempty) Required
  
  ID of the exception container
  
  Minimum length is 1.
- list_id string(nonempty) Required
  
  List ID of the exception container
  
  Minimum length is 1.
- namespace_type string Required
  
  Determines the exceptions validity in rule's Kibana space
  
  Values are agnostic or single.
- type string Required
  
  The exception type
  
  Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.
false_positives array[string]

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.
from string(date-math)

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

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.
Hide investigation_fields attribute Show investigation_fields attribute object
- field_names array[string(nonempty)] Required
  
  A string that does not contain only whitespace characters
  
  At least 1 element. Minimum length of each is 1.
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).

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.

Minimum value is 1. Default value is 100.
meta object

Placeholder for metadata about the rule.

This field is overwritten when you save changes to the rule’s settings.

Additional properties are allowed.
name string Required

A human-readable name for the rule.

Minimum length is 1.
namespace string

Has no effect.
note string

Notes to help investigate alerts produced by the rule.
outcome string

Values are exactMatch, aliasMatch, or conflict.
output_index string Deprecated

(deprecated) Has no effect.
references array[string]

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.
related_integrations array[object]
Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:
- package: name of the package (required, unique id)
- version: version of the package (required, semver-compatible)
- integration: name of the integration of this package (optional, id within the package)
There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.
Hide related_integrations attributes Show related_integrations attributes object
- integration string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- package string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- version string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
required_fields array[object]

Elasticsearch fields and their types that need to be present for the rule to function.

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.

Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.
Hide required_fields attributes Show required_fields attributes object
- name string(nonempty) Required
  
  Name of an Elasticsearch field
  
  Minimum length is 1.
- type string(nonempty) Required
  
  Type of the Elasticsearch field
  
  Minimum length is 1.
response_actions array[object]
One of:
Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object
Hide attributes Show attributes

action_type_id string Required

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

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

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[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.
Hide attributes Show attributes

action_type_id string Required

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object

Hide attributes Show attributes

command string Required

Value is isolate.

comment string

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.
risk_score integer 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
Minimum value is 0, maximum value is 100.
risk_score_mapping array[object]

Overrides generated alerts' risk_score with a value from the source event
Hide risk_score_mapping attributes Show risk_score_mapping attributes object
- field string Required
  
  Source event field used to override the default risk_score.
- operator string Required
  
  Value is equals.
- 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
  Minimum value is 0, maximum value is 100.
- value string Required
rule_id string

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

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 string 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 are low, medium, high, or critical.
severity_mapping array[object]

Overrides generated alerts' severity with values from the source event
Hide severity_mapping attributes Show severity_mapping attributes object
- field string Required
  
  Source event field used to override the default severity.
- operator string Required
  
  Value is equals.
- severity string 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 are low, medium, high, or critical.
- value string Required
tags array[string]

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.
threat array[object]

Currently, only threats described using the MITRE ATT&CK™ framework are supported.
Hide threat attributes Show threat attributes object
- framework string Required
  
  Relevant attack framework
- tactic object Required
  
  Object containing information on the attack type
  Hide tactic attributes Show tactic attributes object
  
  id string Required
  
  Tactic ID
  
  name string Required
  
  Tactic name
  
  reference string Required
  
  Tactic reference
- technique array[object]
  
  Array containing information on the attack techniques (optional)
  Hide technique attributes Show technique attributes object
  
  id string Required
  
  Technique ID
  
  name string Required
  
  Technique name
  
  reference string Required
  
  Technique reference
  
  subtechnique array[object]
  
  Array containing more specific information on the attack technique.
  
  Hide subtechnique attributes Show subtechnique attributes object
  
  id string Required
  
  Subtechnique ID
  
  name string Required
  
  Subtechnique name
  
  reference string Required
  
  Subtechnique reference
throttle string | null

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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
version integer
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.
It is not incremented on each update. Compare this to the revision field.
Minimum value is 1.
history_window_start string(nonempty) Required

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.

Minimum length is 1.
new_terms_fields array[string] Required

Fields to monitor for new values.

At least 1 but not more than 3 elements.
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.
type string Required Discriminator

Rule type

Value is new_terms.
alert_suppression object

Defines alert suppression configuration.
Hide alert_suppression attributes Show alert_suppression attributes object
- duration object
  Hide duration attributes Show duration attributes object
  
  unit string Required
  
  Time unit
  
  Values are s, m, or h.
  
  value integer Required
  
  Minimum value is 1.
- group_by array[string] Required
  
  At least 1 but not more than 3 elements.
- missing_fields_strategy string
  
  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 are doNotSuppress or suppress.
data_view_id string
filters array

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 array[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.
language string

Values are kuery or lucene.
invocationCount integer Required
timeframeEnd string(date-time) Required

actions array[object]

Array defining the automated actions (notifications) taken when alerts are generated.
Hide actions attributes Show actions attributes object
- 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.
  Additional properties are allowed.
- frequency object
  
  The action frequency defines when the action runs (for example, only on rule execution or at specific time intervals).
  Hide frequency attributes Show frequency attributes object
  
  notifyWhen string Required
  
  Defines how often rules run actions.
  
  Values are onActiveAlert, onThrottleInterval, or 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 string | null Required
  
  Defines how often rule actions are taken.
  
  One of:
  string-1 string | null string-2 string | null
  
  Values are no_actions or 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.
  Additional properties are allowed.
- uuid string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
alias_purpose string

Values are savedObjectConversion or savedObjectImport.
alias_target_id string
author array[string]

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 Required

The rule’s description.

Minimum length is 1.
enabled boolean

Determines whether the rule is enabled. Defaults to true.
exceptions_list array[object]

Array of exception containers, which define exceptions that prevent the rule from generating alerts even when its other criteria are met.
Hide exceptions_list attributes Show exceptions_list attributes object
- id string(nonempty) Required
  
  ID of the exception container
  
  Minimum length is 1.
- list_id string(nonempty) Required
  
  List ID of the exception container
  
  Minimum length is 1.
- namespace_type string Required
  
  Determines the exceptions validity in rule's Kibana space
  
  Values are agnostic or single.
- type string Required
  
  The exception type
  
  Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.
false_positives array[string]

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.
from string(date-math)

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

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.
Hide investigation_fields attribute Show investigation_fields attribute object
- field_names array[string(nonempty)] Required
  
  A string that does not contain only whitespace characters
  
  At least 1 element. Minimum length of each is 1.
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).

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.

Minimum value is 1. Default value is 100.
meta object

Placeholder for metadata about the rule.

This field is overwritten when you save changes to the rule’s settings.

Additional properties are allowed.
name string Required

A human-readable name for the rule.

Minimum length is 1.
namespace string

Has no effect.
note string

Notes to help investigate alerts produced by the rule.
outcome string

Values are exactMatch, aliasMatch, or conflict.
output_index string Deprecated

(deprecated) Has no effect.
references array[string]

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.
related_integrations array[object]
Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:
- package: name of the package (required, unique id)
- version: version of the package (required, semver-compatible)
- integration: name of the integration of this package (optional, id within the package)
There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.
Hide related_integrations attributes Show related_integrations attributes object
- integration string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- package string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- version string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
required_fields array[object]

Elasticsearch fields and their types that need to be present for the rule to function.

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.

Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.
Hide required_fields attributes Show required_fields attributes object
- name string(nonempty) Required
  
  Name of an Elasticsearch field
  
  Minimum length is 1.
- type string(nonempty) Required
  
  Type of the Elasticsearch field
  
  Minimum length is 1.
response_actions array[object]
One of:
Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object
Hide attributes Show attributes

action_type_id string Required

Value is .osquery.

params object Required

Hide params attributes Show params attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[string]

pack_id string

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

queries array[object]

Hide queries attributes Show queries attributes object

ecs_mapping object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

Hide ecs_mapping attribute Show ecs_mapping attribute object

* object Additional properties

Hide * attributes Show * attributes object

field string

value string | array[string]

One of:
string-1 string array-2 array[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.
Hide attributes Show attributes

action_type_id string Required

Value is .endpoint.

params object Required

One of:
Security_Detections_API_DefaultParams object Security_Detections_API_ProcessesParams object

Hide attributes Show attributes

command string Required

Value is isolate.

comment string

Hide attributes Show attributes

command string Required

To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"

Values are kill-process or suspend-process.

comment string

Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"

config object Required

Hide config attributes Show config attributes object

field string Required

Field to use instead of process.pid

overwrite boolean

Whether to overwrite field with process.pid

Default value is true.
risk_score integer 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
Minimum value is 0, maximum value is 100.
risk_score_mapping array[object]

Overrides generated alerts' risk_score with a value from the source event
Hide risk_score_mapping attributes Show risk_score_mapping attributes object
- field string Required
  
  Source event field used to override the default risk_score.
- operator string Required
  
  Value is equals.
- 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
  Minimum value is 0, maximum value is 100.
- value string Required
rule_id string

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

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 string 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 are low, medium, high, or critical.
severity_mapping array[object]

Overrides generated alerts' severity with values from the source event
Hide severity_mapping attributes Show severity_mapping attributes object
- field string Required
  
  Source event field used to override the default severity.
- operator string Required
  
  Value is equals.
- severity string 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 are low, medium, high, or critical.
- value string Required
tags array[string]

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.
threat array[object]

Currently, only threats described using the MITRE ATT&CK™ framework are supported.
Hide threat attributes Show threat attributes object
- framework string Required
  
  Relevant attack framework
- tactic object Required
  
  Object containing information on the attack type
  Hide tactic attributes Show tactic attributes object
  
  id string Required
  
  Tactic ID
  
  name string Required
  
  Tactic name
  
  reference string Required
  
  Tactic reference
- technique array[object]
  
  Array containing information on the attack techniques (optional)
  Hide technique attributes Show technique attributes object
  
  id string Required
  
  Technique ID
  
  name string Required
  
  Technique name
  
  reference string Required
  
  Technique reference
  
  subtechnique array[object]
  
  Array containing more specific information on the attack technique.
  
  Hide subtechnique attributes Show subtechnique attributes object
  
  id string Required
  
  Subtechnique ID
  
  name string Required
  
  Subtechnique name
  
  reference string Required
  
  Subtechnique reference
throttle string | null

Defines how often rule actions are taken.

One of:
string-1 string | null string-2 string | null

Values are no_actions or 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
version integer
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.
It is not incremented on each update. Compare this to the revision field.
Minimum value is 1.
alert_suppression object

Defines alert suppression configuration.
Hide alert_suppression attributes Show alert_suppression attributes object
- duration object
  Hide duration attributes Show duration attributes object
  
  unit string Required
  
  Time unit
  
  Values are s, m, or h.
  
  value integer Required
  
  Minimum value is 1.
- group_by array[string] Required
  
  At least 1 but not more than 3 elements.
- missing_fields_strategy string
  
  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 are doNotSuppress or suppress.
language string Required

Value is esql.
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.
type string Required Discriminator

Rule type

Value is esql.
invocationCount integer Required
timeframeEnd string(date-time) Required

Responses

200 application/json

Successful response
Hide response attributes Show response attributes object
- isAborted boolean
- logs array[object] Required
  
  Hide logs attributes Show logs attributes object
  
  duration integer Required
  
  Execution duration in milliseconds
  
  errors array[string(nonempty)] Required
  
  A string that does not contain only whitespace characters
  
  Minimum length of each is 1.
  
  requests array[object]
  
  Hide requests attributes Show requests attributes object
  
  description string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  duration integer
  
  request string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  request_type string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  startedAt string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  warnings array[string(nonempty)] Required
  
  A string that does not contain only whitespace characters
  
  Minimum length of each is 1.
- previewId string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
400 application/json

Invalid input data response
One of:
Security_Detections_API_PlatformErrorResponse object Security_Detections_API_SiemErrorResponse object
Hide attributes Show attributes

error string Required

message string Required

statusCode integer Required
Hide attributes Show attributes

message string Required

status_code integer Required
401 application/json

Unsuccessful authentication response
Hide response attributes Show response attributes object
- error string Required
- message string Required
- statusCode integer Required
500 application/json

Internal server error response
Hide response attributes Show response attributes object
- message string Required
- status_code integer Required

POST /api/detection_engine/rules/preview

curl \
 --request POST 'https://<KIBANA_URL>/api/detection_engine/rules/preview' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"actions":[{"action_type_id":"string","alerts_filter":{},"frequency":{"notifyWhen":"onActiveAlert","summary":true,"throttle":"no_actions"},"group":"string","id":"string","params":{},"uuid":"string"}],"alias_purpose":"savedObjectConversion","alias_target_id":"string","author":["string"],"building_block_type":"string","description":"Detects anomalous Windows process creation events.","enabled":true,"exceptions_list":[{"id":"string","list_id":"string","namespace_type":"agnostic","type":"detection"}],"false_positives":["string"],"from":"string","interval":"string","investigation_fields":{"field_names":["string"]},"license":"string","max_signals":100,"meta":{},"name":"Anomalous Windows Process Creation","namespace":"string","note":"string","outcome":"exactMatch","output_index":"string","references":["string"],"related_integrations":[{"package":"azure","version":"~1.1.6","integration":"activitylogs"}],"required_fields":[{"name":"string","type":"string"}],"response_actions":[{"action_type_id":".osquery","params":{"ecs_mapping":{"additionalProperty1":{"field":"string","value":"string"},"additionalProperty2":{"field":"string","value":"string"}},"pack_id":"string","queries":[{"ecs_mapping":{"additionalProperty1":{"field":"string","value":"string"},"additionalProperty2":{"field":"string","value":"string"}},"id":"string","platform":"string","query":"string","removed":true,"snapshot":true,"version":"string"}],"query":"string","saved_query_id":"string","timeout":42.0}}],"risk_score":42,"risk_score_mapping":[{"field":"string","operator":"equals","risk_score":42,"value":"string"}],"rule_id":"string","rule_name_override":"string","setup":"string","severity":"low","severity_mapping":[{"field":"string","operator":"equals","severity":"low","value":"string"}],"tags":["string"],"threat":[{"framework":"string","tactic":{"id":"string","name":"string","reference":"string"},"technique":[{"id":"string","name":"string","reference":"string","subtechnique":[{"id":"string","name":"string","reference":"string"}]}]}],"throttle":"no_actions","timeline_id":"string","timeline_title":"string","timestamp_override":"string","timestamp_override_fallback_disabled":true,"to":"string","version":42,"language":"eql","query":"string","type":"eql","alert_suppression":{"duration":{"unit":"s","value":42},"group_by":["string"],"missing_fields_strategy":"doNotSuppress"},"data_view_id":"string","event_category_override":"string","filters":[],"index":["string"],"tiebreaker_field":"string","timestamp_field":"string","invocationCount":42,"timeframeEnd":"2025-05-04T09:42:00Z"}'

Assign and unassign users from detection alerts

POST /api/detection_engine/signals/assignees

Assign users to detection alerts, and unassign them from alerts.

You cannot add and remove the same assignee in the same request.

application/json

Body Required

assignees object Required

Details about the assignees to assign and unassign.
Hide assignees attributes Show assignees attributes object
- add array[string(nonempty)] Required
  
  A list of users ids to assign.
  
  Minimum length of each is 1.
- remove array[string(nonempty)] Required
  
  A list of users ids to unassign.
  
  Minimum length of each is 1.
ids array[string(nonempty)] Required

A list of alerts ids.

At least 1 element. Minimum length of each is 1.

Responses

200 application/ndjson

Indicates a successful call.
400

Invalid request.

POST /api/detection_engine/signals/assignees

curl \
 --request POST 'https://<KIBANA_URL>/api/detection_engine/signals/assignees' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"ids":["681c2a707335aa7df5f349b70013d87254746191712ecf0ced9b3e2d538503a6"],"assignees":{"add":["u_MxY0jbrft7EcfC6iNZSUGeI_n6iYrSwZj5mWF5EqmSU_0"],"remove":[]}}'

Request examples

{
  "ids": [
    "681c2a707335aa7df5f349b70013d87254746191712ecf0ced9b3e2d538503a6"
  ],
  "assignees": {
    "add": [
      "u_MxY0jbrft7EcfC6iNZSUGeI_n6iYrSwZj5mWF5EqmSU_0"
    ],
    "remove": []
  }
}

{
  "ids": [
    "681c2a707335aa7df5f349b70013d87254746191712ecf0ced9b3e2d538503a6"
  ],
  "assignees": {
    "add": [],
    "remove": [
      "u_MxY0jbrft7EcfC6iNZSUGeI_n6iYrSwZj5mWF5EqmSU_0"
    ]
  }
}

Response examples (200)

{
  "took": "76,",
  "noops": "0,",
  "total": "1,",
  "batches": "1,",
  "deleted": "0,",
  "retries": [
    {
      "bulk": "0,"
    },
    {
      "search": 0
    }
  ],
  "updated": "1,",
  "failures": [],
  "timed_out": "false,",
  "throttled_millis": "0,",
  "version_conflicts": "0,",
  "requests_per_second": "-1,",
  "throttled_until_millis": "0,"
}

Find and/or aggregate detection alerts

POST /api/detection_engine/signals/search

Find and/or aggregate detection alerts that match the given query.

application/json

Body Required

Search and/or aggregation query

_source boolean | string | array[string]

One of:
boolean-1 boolean string-2 string array-3 array[string]
aggs object

Additional properties are allowed.
fields array[string]
query object

Additional properties are allowed.
runtime_mappings object

Additional properties are allowed.
size integer

Minimum value is 0.
sort string | object | array[string | object]

One of:
string-1 string object-2 object array-2 array[string | object]
track_total_hits boolean

Responses

200 application/json

Successful response

Elasticsearch search response

Additional properties are allowed.
400 application/json

Invalid input data response
One of:
Security_Detections_API_PlatformErrorResponse object Security_Detections_API_SiemErrorResponse object
Hide attributes Show attributes

error string Required

message string Required

statusCode integer Required
Hide attributes Show attributes

message string Required

status_code integer Required
401 application/json

Unsuccessful authentication response
Hide response attributes Show response attributes object
- error string Required
- message string Required
- statusCode integer Required
500 application/json

Internal server error response
Hide response attributes Show response attributes object
- message string Required
- status_code integer Required

POST /api/detection_engine/signals/search

curl \
 --request POST 'https://<KIBANA_URL>/api/detection_engine/signals/search' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"aggs":{"missingFields":{"missing":{"field":"host.name"}},"alertsByGrouping":{"terms":{"size":10,"field":"host.name"}}},"size":0,"query":{"bool":{"filter":[{"bool":{"must":[],"filter":[{"match_phrase":{"kibana.alert.workflow_status":"open"}}],"should":[],"must_not":[{"exists":{"field":"kibana.alert.building_block_type"}}]}},{"range":{"@timestamp":{"gte":"2025-01-17T08:00:00.000Z","lte":"2025-01-18T07:59:59.999Z"}}}]}},"runtime_mappings":{}}'

Request example

{
  "aggs": {
    "missingFields": {
      "missing": {
        "field": "host.name"
      }
    },
    "alertsByGrouping": {
      "terms": {
        "size": 10,
        "field": "host.name"
      }
    }
  },
  "size": 0,
  "query": {
    "bool": {
      "filter": [
        {
          "bool": {
            "must": [],
            "filter": [
              {
                "match_phrase": {
                  "kibana.alert.workflow_status": "open"
                }
              }
            ],
            "should": [],
            "must_not": [
              {
                "exists": {
                  "field": "kibana.alert.building_block_type"
                }
              }
            ]
          }
        },
        {
          "range": {
            "@timestamp": {
              "gte": "2025-01-17T08:00:00.000Z",
              "lte": "2025-01-18T07:59:59.999Z"
            }
          }
        }
      ]
    }
  },
  "runtime_mappings": {}
}

Response examples (200)

{
  "hits": {
    "hits": [],
    "total": {
      "value": 5,
      "relation": "eq"
    },
    "max_score": null
  },
  "took": 0,
  "_shards": {
    "total": 1,
    "failed": 0,
    "skipped": 0,
    "successful": 1
  },
  "timed_out": false,
  "aggregations": {
    "missingFields": {
      "doc_count": 0
    },
    "alertsByGrouping": {
      "buckets": [
        {
          "key": "Host-f43kkddfyc",
          "doc_count": 5
        }
      ],
      "sum_other_doc_count": 0,
      "doc_count_error_upper_bound": 0
    }
  }
}

Set a detection alert status

POST /api/detection_engine/signals/status

Set the status of one or more detection alerts.

application/json

Body object Required

An object containing desired status and explicit alert ids or a query to select alerts

signal_ids array[string(nonempty)] Required

List of alert ids.

At least 1 element. Minimum length of each is 1.
status string Required

The status of an alert, which can be open, acknowledged, in-progress, or closed.

Values are open, closed, acknowledged, or in-progress.

conflicts string

Values are abort or proceed. Default value is abort.
query object Required

Additional properties are allowed.
status string Required

The status of an alert, which can be open, acknowledged, in-progress, or closed.

Values are open, closed, acknowledged, or in-progress.

Responses

200 application/json

Successful response

Elasticsearch update by query response

Additional properties are allowed.
400 application/json

Invalid input data response
One of:
Security_Detections_API_PlatformErrorResponse object Security_Detections_API_SiemErrorResponse object
Hide attributes Show attributes

error string Required

message string Required

statusCode integer Required
Hide attributes Show attributes

message string Required

status_code integer Required
401 application/json

Unsuccessful authentication response
Hide response attributes Show response attributes object
- error string Required
- message string Required
- statusCode integer Required
500 application/json

Internal server error response
Hide response attributes Show response attributes object
- message string Required
- status_code integer Required

POST /api/detection_engine/signals/status

curl \
 --request POST 'https://<KIBANA_URL>/api/detection_engine/signals/status' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"status":"closed","signal_ids":["80e1383f856e67c1b7f7a1634744fa6d66b6e2ef7aa26d226e57afb5a7b2b4a1"]}'

Request examples

{
  "status": "closed",
  "signal_ids": [
    "80e1383f856e67c1b7f7a1634744fa6d66b6e2ef7aa26d226e57afb5a7b2b4a1"
  ]
}

{
  "query": {
    "bool": {
      "must": [],
      "filter": [
        {
          "range": null,
          "@timestamp": {
            "gte": "2024-10-23T07:00:00.000Z",
            "lte": "2025-01-21T20:12:11.704Z",
            "format": "strict_date_optional_time"
          }
        },
        {
          "bool": {
            "filter": {
              "bool": {
                "must": [],
                "filter": [
                  {
                    "match_phrase": {
                      "kibana.alert.workflow_status": "open"
                    }
                  },
                  {
                    "range": null,
                    "@timestamp": {
                      "gte": "2024-10-23T07:00:00.000Z",
                      "lte": "2025-01-21T20:12:11.704Z",
                      "format": "strict_date_optional_time"
                    }
                  }
                ],
                "should": [],
                "must_not": [
                  {
                    "exists": {
                      "field": "kibana.alert.building_block_type"
                    }
                  }
                ]
              }
            }
          }
        }
      ],
      "should": [],
      "must_not": []
    }
  },
  "status": "closed",
  "conflicts": "proceed"
}

Response examples (200)

{
  "took": 81,
  "noops": 0,
  "total": 1,
  "batches": 1,
  "deleted": 0,
  "retries": {
    "bulk": 0,
    "search": 0
  },
  "updated": 1,
  "failures": [],
  "timed_out": false,
  "throttled_millis": 0,
  "version_conflicts": 0,
  "requests_per_second": -1,
  "throttled_until_millis": 0
}

{
  "took": 100,
  "noops": 0,
  "total": 17,
  "batches": 1,
  "deleted": 0,
  "retries": {
    "bulk": 0,
    "search": 0
  },
  "updated": 17,
  "failures": [],
  "timed_out": false,
  "throttled_millis": 0,
  "version_conflicts": 0,
  "requests_per_second": -1,
  "throttled_until_millis": 0
}

Add and remove detection alert tags

POST /api/detection_engine/signals/tags

And tags to detection alerts, and remove them from alerts.

You cannot add and remove the same alert tag in the same request.

application/json

Body Required

An object containing tags to add or remove and alert ids the changes will be applied

ids array[string(nonempty)] Required

A list of alerts ids.

At least 1 element. Minimum length of each is 1.
tags object Required

Object with list of tags to add and remove.
Hide tags attributes Show tags attributes object
- tags_to_add array[string(nonempty)] Required
  
  List of keywords to organize related alerts into categories that you can filter and group.
  
  Minimum length of each is 1.
- tags_to_remove array[string(nonempty)] Required
  
  List of keywords to organize related alerts into categories that you can filter and group.
  
  Minimum length of each is 1.

Responses

200 application/json

Successful response

Elasticsearch update by query response

Additional properties are allowed.
400 application/json

Invalid input data response
One of:
Security_Detections_API_PlatformErrorResponse object Security_Detections_API_SiemErrorResponse object
Hide attributes Show attributes

error string Required

message string Required

statusCode integer Required
Hide attributes Show attributes

message string Required

status_code integer Required
401 application/json

Unsuccessful authentication response
Hide response attributes Show response attributes object
- error string Required
- message string Required
- statusCode integer Required
500 application/json

Internal server error response
Hide response attributes Show response attributes object
- message string Required
- status_code integer Required

POST /api/detection_engine/signals/tags

curl \
 --request POST 'https://<KIBANA_URL>/api/detection_engine/signals/tags' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"ids":["549c7129c76cbd554aba1bd638f8a49dde95088f5832e50218358e7eca1cf16e"],"tags":{"tags_to_add":["Duplicate"],"tags_to_remove":[]}}'

Request examples

{
  "ids": [
    "549c7129c76cbd554aba1bd638f8a49dde95088f5832e50218358e7eca1cf16e"
  ],
  "tags": {
    "tags_to_add": [
      "Duplicate"
    ],
    "tags_to_remove": []
  }
}

{
  "ids": [
    "549c7129c76cbd554aba1bd638f8a49dde95088f5832e50218358e7eca1cf16e"
  ],
  "tags": {
    "tags_to_add": [],
    "tags_to_remove": [
      "Duplicate"
    ]
  }
}

Response examples (200)

{
  "took": "68,",
  "noops": "0,",
  "total": "1,",
  "batches": "1,",
  "deleted": "0,",
  "retries": {
    "bulk": "0,",
    "search": 0
  },
  "updated": "1,",
  "failures": [],
  "timed_out": "false,",
  "throttled_millis": "0,",
  "version_conflicts": "0,",
  "requests_per_second": "-1,",
  "throttled_until_millis": "0,"
}

List all detection rule tags

GET /api/detection_engine/tags

List all unique tags from all detection rules.

Responses

200 application/json

Indicates a successful call

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.

GET /api/detection_engine/tags

curl \
 --request GET 'https://<KIBANA_URL>/api/detection_engine/tags' \
 --header "Authorization: $API_KEY"

Response examples (200)

[
  "zeek",
  "suricata",
  "windows",
  "linux",
  "network",
  "initial access",
  "remote access",
  "phishing"
]

Create an endpoint exception list

POST /api/endpoint_list

Create an endpoint exception list, which groups endpoint exception list items. If an endpoint exception list already exists, an empty response is returned.

Responses

200 application/json

Successful response
One of:
Security_Endpoint_Exceptions_API_ExceptionList object object-2 object
Hide attributes Show attributes

_version string

The version id, normally returned by the API when the item was retrieved. Use it ensure updates are done against the latest version.

created_at string(date-time) Required

Autogenerated date of object creation.

created_by string Required

Autogenerated value - user that created object.

description string Required

Describes the exception list.

id string(nonempty) Required

Exception list's identifier.

Minimum length is 1.

immutable boolean Required

list_id string(nonempty) Required

Exception list's human readable string identifier, e.g. trusted-linux-processes.

Minimum length is 1.

meta object

Placeholder for metadata about the list container.

Additional properties are allowed.

name string Required

The name of the exception list.

namespace_type string Required

Determines whether the exception container is available in all Kibana spaces or just the space in which it is created, where:

single: Only available in the Kibana space in which it is created.

agnostic: Available in all Kibana spaces.

Values are agnostic or single.

os_types array[string]

Use this field to specify the operating system. Only enter one value.

Values are linux, macos, or windows.

tags array[string]

String array containing words and phrases to help categorize exception containers.

tie_breaker_id string Required

Field used in search to ensure all containers are sorted and returned correctly.

type string Required

The type of exception list to be created. Different list types may denote where they can be utilized.

Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.

updated_at string(date-time) Required

Autogenerated date of last object update.

updated_by string Required

Autogenerated value - user that last updated object.

version integer Required

The document version, automatically increasd on updates.

Minimum value is 1.
Additional properties are NOT allowed.
400 application/json

Invalid input data
One of:
Security_Endpoint_Exceptions_API_PlatformErrorResponse object Security_Endpoint_Exceptions_API_SiemErrorResponse object
Hide attributes Show attributes

error string Required

message string Required

statusCode integer Required
Hide attributes Show attributes

message string Required

status_code integer Required
401 application/json

Unsuccessful authentication
Hide response attributes Show response attributes object
- error string Required
- message string Required
- statusCode integer Required
403 application/json

Insufficient privileges
Hide response attributes Show response attributes object
- error string Required
- message string Required
- statusCode integer Required
500 application/json

Internal server error
Hide response attributes Show response attributes object
- message string Required
- status_code integer Required

POST /api/endpoint_list

curl \
 --request POST 'https://<KIBANA_URL>/api/endpoint_list' \
 --header "Authorization: $API_KEY"

Get an endpoint exception list item

GET /api/endpoint_list/items

Get the details of an endpoint exception list item using the id or item_id field.

Query parameters

id string(nonempty)

Either id or item_id must be specified

Minimum length is 1.
item_id string(nonempty)

Either id or item_id must be specified

Minimum length is 1.

Responses

200 application/json

Successful response
Hide response attributes Show response attributes object
- _version string
  
  The version id, normally returned by the API when the item was retrieved. Use it ensure updates are done against the latest version.
- comments array[object] Required
  
  Array of comment fields:
  
  comment (string): Comments about the exception item.
  
  Hide comments attributes Show comments attributes object
  
  comment string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  created_at string(date-time) Required
  
  Autogenerated date of object creation.
  
  created_by string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  id string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  updated_at string(date-time)
  
  Autogenerated date of last object update.
  
  updated_by string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- created_at string(date-time) Required
  
  Autogenerated date of object creation.
- created_by string Required
  
  Autogenerated value - user that created object.
- description string Required
  
  Describes the exception list.
- entries array[object] Required
  
  Any of:
  Security_Endpoint_Exceptions_API_ExceptionListItemEntryMatch object Security_Endpoint_Exceptions_API_ExceptionListItemEntryMatchAny object Security_Endpoint_Exceptions_API_ExceptionListItemEntryList object Security_Endpoint_Exceptions_API_ExceptionListItemEntryExists object Security_Endpoint_Exceptions_API_ExceptionListItemEntryNested object Security_Endpoint_Exceptions_API_ExceptionListItemEntryMatchWildcard object
  
  Hide attributes Show attributes
  
  field string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  operator string Required
  
  Values are excluded or included.
  
  type string Required Discriminator
  
  Value is match.
  
  value string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  Hide attributes Show attributes
  
  field string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  operator string Required
  
  Values are excluded or included.
  
  type string Required Discriminator
  
  Value is match_any.
  
  value array[string(nonempty)] Required
  
  A string that does not contain only whitespace characters
  
  At least 1 element. Minimum length of each is 1.
  
  Hide attributes Show attributes
  
  field string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  list object Required
  
  Hide list attributes Show list attributes object
  
  id string(nonempty) Required
  
  Value list's identifier.
  
  Minimum length is 1.
  
  type string Required
  
  Specifies the Elasticsearch data type of excludes the list container holds. Some common examples:
  
  keyword: Many ECS fields are Elasticsearch keywords
  
  ip: IP addresses
  
  ip_range: Range of IP addresses (supports IPv4, IPv6, and CIDR notation)
  
  Values are binary, boolean, byte, date, date_nanos, date_range, double, double_range, float, float_range, geo_point, geo_shape, half_float, integer, integer_range, ip, ip_range, keyword, long, long_range, shape, short, or text.
  
  operator string Required
  
  Values are excluded or included.
  
  type string Required Discriminator
  
  Value is list.
  
  Hide attributes Show attributes
  
  field string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  operator string Required
  
  Values are excluded or included.
  
  type string Required Discriminator
  
  Value is exists.
  
  Hide attributes Show attributes
  
  entries array[object] Required
  
  At least 1 element.
  
  One of:
  Security_Endpoint_Exceptions_API_ExceptionListItemEntryMatch object Security_Endpoint_Exceptions_API_ExceptionListItemEntryMatchAny object Security_Endpoint_Exceptions_API_ExceptionListItemEntryExists object
  
  Hide attributes Show attributes
  
  field string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  operator string Required
  
  Values are excluded or included.
  
  type string Required
  
  Value is match.
  
  value string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  Hide attributes Show attributes
  
  field string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  operator string Required
  
  Values are excluded or included.
  
  type string Required
  
  Value is match_any.
  
  value array[string(nonempty)] Required
  
  A string that does not contain only whitespace characters
  
  At least 1 element. Minimum length of each is 1.
  
  Hide attributes Show attributes
  
  field string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  operator string Required
  
  Values are excluded or included.
  
  type string Required
  
  Value is exists.
  
  field string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  type string Required Discriminator
  
  Value is nested.
  
  Hide attributes Show attributes
  
  field string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  operator string Required
  
  Values are excluded or included.
  
  type string Required Discriminator
  
  Value is wildcard.
  
  value string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- expire_time string(date-time)
  
  The exception item’s expiration date, in ISO format. This field is only available for regular exception items, not endpoint exceptions.
- id string(nonempty) Required
  
  Exception's identifier.
  
  Minimum length is 1.
- item_id string(nonempty) Required
  
  Human readable string identifier, e.g. trusted-linux-processes
  
  Minimum length is 1.
- list_id string(nonempty) Required
  
  Exception list's human readable string identifier, e.g. trusted-linux-processes.
  
  Minimum length is 1.
- meta object
  
  Additional properties are allowed.
- name string(nonempty) Required
  
  Exception list name.
  
  Minimum length is 1.
- namespace_type string Required
  
  Determines whether the exception container is available in all Kibana spaces or just the space in which it is created, where:
  
  single: Only available in the Kibana space in which it is created.
  
  agnostic: Available in all Kibana spaces.
  
  Values are agnostic or single.
- os_types array[string]
  
  Use this field to specify the operating system.
  
  Values are linux, macos, or windows.
- tags array[string(nonempty)]
  
  String array containing words and phrases to help categorize exception items.
  
  Minimum length of each is 1.
- tie_breaker_id string Required
  
  Field used in search to ensure all containers are sorted and returned correctly.
- type string Required
  
  Value is simple.
- updated_at string(date-time) Required
  
  Autogenerated date of last object update.
- updated_by string Required
  
  Autogenerated value - user that last updated object.
400 application/json

Invalid input data
One of:
Security_Endpoint_Exceptions_API_PlatformErrorResponse object Security_Endpoint_Exceptions_API_SiemErrorResponse object
Hide attributes Show attributes

error string Required

message string Required

statusCode integer Required
Hide attributes Show attributes

message string Required

status_code integer Required
401 application/json

Unsuccessful authentication
Hide response attributes Show response attributes object
- error string Required
- message string Required
- statusCode integer Required
403 application/json

Insufficient privileges
Hide response attributes Show response attributes object
- error string Required
- message string Required
- statusCode integer Required
404 application/json

Endpoint list item not found
Hide response attributes Show response attributes object
- message string Required
- status_code integer Required
500 application/json

Internal server error
Hide response attributes Show response attributes object
- message string Required
- status_code integer Required

GET /api/endpoint_list/items

curl \
 --request GET 'https://<KIBANA_URL>/api/endpoint_list/items' \
 --header "Authorization: $API_KEY"

Update an endpoint exception list item

PUT /api/endpoint_list/items

Update an endpoint exception list item using the id or item_id field.

application/json

Body Required

Exception list item's properties

_version string
comments array[object]
Array of comment fields:
- comment (string): Comments about the exception item.
Hide comments attributes Show comments attributes object
- comment string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- created_at string(date-time) Required
  
  Autogenerated date of object creation.
- created_by string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- id string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- updated_at string(date-time)
  
  Autogenerated date of last object update.
- updated_by string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
description string Required

Describes the exception list.
entries array[object] Required
Any of:
Security_Endpoint_Exceptions_API_ExceptionListItemEntryMatch object Security_Endpoint_Exceptions_API_ExceptionListItemEntryMatchAny object Security_Endpoint_Exceptions_API_ExceptionListItemEntryList object Security_Endpoint_Exceptions_API_ExceptionListItemEntryExists object Security_Endpoint_Exceptions_API_ExceptionListItemEntryNested object Security_Endpoint_Exceptions_API_ExceptionListItemEntryMatchWildcard object
Hide attributes Show attributes

field string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

operator string Required

Values are excluded or included.

type string Required Discriminator

Value is match.

value string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.
Hide attributes Show attributes

field string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

operator string Required

Values are excluded or included.

type string Required Discriminator

Value is match_any.

value array[string(nonempty)] Required

A string that does not contain only whitespace characters

At least 1 element. Minimum length of each is 1.
Hide attributes Show attributes

field string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

list object Required

Hide list attributes Show list attributes object

id string(nonempty) Required

Value list's identifier.

Minimum length is 1.

type string Required

Specifies the Elasticsearch data type of excludes the list container holds. Some common examples:

keyword: Many ECS fields are Elasticsearch keywords

ip: IP addresses

ip_range: Range of IP addresses (supports IPv4, IPv6, and CIDR notation)

Values are binary, boolean, byte, date, date_nanos, date_range, double, double_range, float, float_range, geo_point, geo_shape, half_float, integer, integer_range, ip, ip_range, keyword, long, long_range, shape, short, or text.

operator string Required

Values are excluded or included.

type string Required Discriminator

Value is list.
Hide attributes Show attributes

field string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

operator string Required

Values are excluded or included.

type string Required Discriminator

Value is exists.
Hide attributes Show attributes

entries array[object] Required

At least 1 element.

One of:
Security_Endpoint_Exceptions_API_ExceptionListItemEntryMatch object Security_Endpoint_Exceptions_API_ExceptionListItemEntryMatchAny object Security_Endpoint_Exceptions_API_ExceptionListItemEntryExists object

Hide attributes Show attributes

field string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

operator string Required

Values are excluded or included.

type string Required

Value is match.

value string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

Hide attributes Show attributes

field string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

operator string Required

Values are excluded or included.

type string Required

Value is match_any.

value array[string(nonempty)] Required

A string that does not contain only whitespace characters

At least 1 element. Minimum length of each is 1.

Hide attributes Show attributes

field string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

operator string Required

Values are excluded or included.

type string Required

Value is exists.

field string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

type string Required Discriminator

Value is nested.
Hide attributes Show attributes

field string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

operator string Required

Values are excluded or included.

type string Required Discriminator

Value is wildcard.

value string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.
id string(nonempty)

Exception's identifier.

Minimum length is 1.
item_id string(nonempty)

Human readable string identifier, e.g. trusted-linux-processes

Minimum length is 1.
meta object

Additional properties are allowed.
name string(nonempty) Required

Exception list name.

Minimum length is 1.
os_types array[string]

Use this field to specify the operating system.

Values are linux, macos, or windows.
tags array[string(nonempty)]

String array containing words and phrases to help categorize exception items.

Minimum length of each is 1.
type string Required

Value is simple.

Responses

200 application/json

Successful response
Hide response attributes Show response attributes object
- _version string
  
  The version id, normally returned by the API when the item was retrieved. Use it ensure updates are done against the latest version.
- comments array[object] Required
  
  Array of comment fields:
  
  comment (string): Comments about the exception item.
  
  Hide comments attributes Show comments attributes object
  
  comment string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  created_at string(date-time) Required
  
  Autogenerated date of object creation.
  
  created_by string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  id string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  updated_at string(date-time)
  
  Autogenerated date of last object update.
  
  updated_by string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- created_at string(date-time) Required
  
  Autogenerated date of object creation.
- created_by string Required
  
  Autogenerated value - user that created object.
- description string Required
  
  Describes the exception list.
- entries array[object] Required
  
  Any of:
  Security_Endpoint_Exceptions_API_ExceptionListItemEntryMatch object Security_Endpoint_Exceptions_API_ExceptionListItemEntryMatchAny object Security_Endpoint_Exceptions_API_ExceptionListItemEntryList object Security_Endpoint_Exceptions_API_ExceptionListItemEntryExists object Security_Endpoint_Exceptions_API_ExceptionListItemEntryNested object Security_Endpoint_Exceptions_API_ExceptionListItemEntryMatchWildcard object
  
  Hide attributes Show attributes
  
  field string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  operator string Required
  
  Values are excluded or included.
  
  type string Required Discriminator
  
  Value is match.
  
  value string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  Hide attributes Show attributes
  
  field string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  operator string Required
  
  Values are excluded or included.
  
  type string Required Discriminator
  
  Value is match_any.
  
  value array[string(nonempty)] Required
  
  A string that does not contain only whitespace characters
  
  At least 1 element. Minimum length of each is 1.
  
  Hide attributes Show attributes
  
  field string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  list object Required
  
  Hide list attributes Show list attributes object
  
  id string(nonempty) Required
  
  Value list's identifier.
  
  Minimum length is 1.
  
  type string Required
  
  Specifies the Elasticsearch data type of excludes the list container holds. Some common examples:
  
  keyword: Many ECS fields are Elasticsearch keywords
  
  ip: IP addresses
  
  ip_range: Range of IP addresses (supports IPv4, IPv6, and CIDR notation)
  
  Values are binary, boolean, byte, date, date_nanos, date_range, double, double_range, float, float_range, geo_point, geo_shape, half_float, integer, integer_range, ip, ip_range, keyword, long, long_range, shape, short, or text.
  
  operator string Required
  
  Values are excluded or included.
  
  type string Required Discriminator
  
  Value is list.
  
  Hide attributes Show attributes
  
  field string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  operator string Required
  
  Values are excluded or included.
  
  type string Required Discriminator
  
  Value is exists.
  
  Hide attributes Show attributes
  
  entries array[object] Required
  
  At least 1 element.
  
  One of:
  Security_Endpoint_Exceptions_API_ExceptionListItemEntryMatch object Security_Endpoint_Exceptions_API_ExceptionListItemEntryMatchAny object Security_Endpoint_Exceptions_API_ExceptionListItemEntryExists object
  
  Hide attributes Show attributes
  
  field string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  operator string Required
  
  Values are excluded or included.
  
  type string Required
  
  Value is match.
  
  value string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  Hide attributes Show attributes
  
  field string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  operator string Required
  
  Values are excluded or included.
  
  type string Required
  
  Value is match_any.
  
  value array[string(nonempty)] Required
  
  A string that does not contain only whitespace characters
  
  At least 1 element. Minimum length of each is 1.
  
  Hide attributes Show attributes
  
  field string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  operator string Required
  
  Values are excluded or included.
  
  type string Required
  
  Value is exists.
  
  field string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  type string Required Discriminator
  
  Value is nested.
  
  Hide attributes Show attributes
  
  field string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  operator string Required
  
  Values are excluded or included.
  
  type string Required Discriminator
  
  Value is wildcard.
  
  value string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- expire_time string(date-time)
  
  The exception item’s expiration date, in ISO format. This field is only available for regular exception items, not endpoint exceptions.
- id string(nonempty) Required
  
  Exception's identifier.
  
  Minimum length is 1.
- item_id string(nonempty) Required
  
  Human readable string identifier, e.g. trusted-linux-processes
  
  Minimum length is 1.
- list_id string(nonempty) Required
  
  Exception list's human readable string identifier, e.g. trusted-linux-processes.
  
  Minimum length is 1.
- meta object
  
  Additional properties are allowed.
- name string(nonempty) Required
  
  Exception list name.
  
  Minimum length is 1.
- namespace_type string Required
  
  Determines whether the exception container is available in all Kibana spaces or just the space in which it is created, where:
  
  single: Only available in the Kibana space in which it is created.
  
  agnostic: Available in all Kibana spaces.
  
  Values are agnostic or single.
- os_types array[string]
  
  Use this field to specify the operating system.
  
  Values are linux, macos, or windows.
- tags array[string(nonempty)]
  
  String array containing words and phrases to help categorize exception items.
  
  Minimum length of each is 1.
- tie_breaker_id string Required
  
  Field used in search to ensure all containers are sorted and returned correctly.
- type string Required
  
  Value is simple.
- updated_at string(date-time) Required
  
  Autogenerated date of last object update.
- updated_by string Required
  
  Autogenerated value - user that last updated object.
400 application/json

Invalid input data
One of:
Security_Endpoint_Exceptions_API_PlatformErrorResponse object Security_Endpoint_Exceptions_API_SiemErrorResponse object
Hide attributes Show attributes

error string Required

message string Required

statusCode integer Required
Hide attributes Show attributes

message string Required

status_code integer Required
401 application/json

Unsuccessful authentication
Hide response attributes Show response attributes object
- error string Required
- message string Required
- statusCode integer Required
403 application/json

Insufficient privileges
Hide response attributes Show response attributes object
- error string Required
- message string Required
- statusCode integer Required
404 application/json

Endpoint list item not found
Hide response attributes Show response attributes object
- message string Required
- status_code integer Required
500 application/json

Internal server error
Hide response attributes Show response attributes object
- message string Required
- status_code integer Required

PUT /api/endpoint_list/items

curl \
 --request PUT 'https://<KIBANA_URL>/api/endpoint_list/items' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"_version":"string","comments":[{"comment":"string","created_at":"2025-05-04T09:42:00Z","created_by":"string","id":"string","updated_at":"2025-05-04T09:42:00Z","updated_by":"string"}],"description":"string","entries":[{"field":"string","operator":"excluded","type":"match","value":"string"}],"id":"71a9f4b2-c85c-49b4-866f-c71eb9e67da2","item_id":"simple_list_item","meta":{},"name":"string","os_types":["linux"],"tags":["string"],"type":"simple"}'

Create an endpoint exception list item

POST /api/endpoint_list/items

Create an endpoint exception list item, and associate it with the endpoint exception list.

application/json

Body Required

Exception list item's properties

comments array[object]
Array of comment fields:
- comment (string): Comments about the exception item.
Hide comments attributes Show comments attributes object
- comment string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- created_at string(date-time) Required
  
  Autogenerated date of object creation.
- created_by string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- id string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- updated_at string(date-time)
  
  Autogenerated date of last object update.
- updated_by string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
description string Required

Describes the exception list.
entries array[object] Required
Any of:
Security_Endpoint_Exceptions_API_ExceptionListItemEntryMatch object Security_Endpoint_Exceptions_API_ExceptionListItemEntryMatchAny object Security_Endpoint_Exceptions_API_ExceptionListItemEntryList object Security_Endpoint_Exceptions_API_ExceptionListItemEntryExists object Security_Endpoint_Exceptions_API_ExceptionListItemEntryNested object Security_Endpoint_Exceptions_API_ExceptionListItemEntryMatchWildcard object
Hide attributes Show attributes

field string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

operator string Required

Values are excluded or included.

type string Required Discriminator

Value is match.

value string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.
Hide attributes Show attributes

field string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

operator string Required

Values are excluded or included.

type string Required Discriminator

Value is match_any.

value array[string(nonempty)] Required

A string that does not contain only whitespace characters

At least 1 element. Minimum length of each is 1.
Hide attributes Show attributes

field string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

list object Required

Hide list attributes Show list attributes object

id string(nonempty) Required

Value list's identifier.

Minimum length is 1.

type string Required

Specifies the Elasticsearch data type of excludes the list container holds. Some common examples:

keyword: Many ECS fields are Elasticsearch keywords

ip: IP addresses

ip_range: Range of IP addresses (supports IPv4, IPv6, and CIDR notation)

Values are binary, boolean, byte, date, date_nanos, date_range, double, double_range, float, float_range, geo_point, geo_shape, half_float, integer, integer_range, ip, ip_range, keyword, long, long_range, shape, short, or text.

operator string Required

Values are excluded or included.

type string Required Discriminator

Value is list.
Hide attributes Show attributes

field string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

operator string Required

Values are excluded or included.

type string Required Discriminator

Value is exists.
Hide attributes Show attributes

entries array[object] Required

At least 1 element.

One of:
Security_Endpoint_Exceptions_API_ExceptionListItemEntryMatch object Security_Endpoint_Exceptions_API_ExceptionListItemEntryMatchAny object Security_Endpoint_Exceptions_API_ExceptionListItemEntryExists object

Hide attributes Show attributes

field string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

operator string Required

Values are excluded or included.

type string Required

Value is match.

value string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

Hide attributes Show attributes

field string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

operator string Required

Values are excluded or included.

type string Required

Value is match_any.

value array[string(nonempty)] Required

A string that does not contain only whitespace characters

At least 1 element. Minimum length of each is 1.

Hide attributes Show attributes

field string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

operator string Required

Values are excluded or included.

type string Required

Value is exists.

field string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

type string Required Discriminator

Value is nested.
Hide attributes Show attributes

field string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.

operator string Required

Values are excluded or included.

type string Required Discriminator

Value is wildcard.

value string(nonempty) Required

A string that does not contain only whitespace characters

Minimum length is 1.
item_id string(nonempty)

Human readable string identifier, e.g. trusted-linux-processes

Minimum length is 1.
meta object

Additional properties are allowed.
name string(nonempty) Required

Exception list name.

Minimum length is 1.
os_types array[string]

Use this field to specify the operating system.

Values are linux, macos, or windows.
tags array[string(nonempty)]

String array containing words and phrases to help categorize exception items.

Minimum length of each is 1.
type string Required

Value is simple.

Responses

200 application/json

Successful response
Hide response attributes Show response attributes object
- _version string
  
  The version id, normally returned by the API when the item was retrieved. Use it ensure updates are done against the latest version.
- comments array[object] Required
  
  Array of comment fields:
  
  comment (string): Comments about the exception item.
  
  Hide comments attributes Show comments attributes object
  
  comment string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  created_at string(date-time) Required
  
  Autogenerated date of object creation.
  
  created_by string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  id string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  updated_at string(date-time)
  
  Autogenerated date of last object update.
  
  updated_by string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- created_at string(date-time) Required
  
  Autogenerated date of object creation.
- created_by string Required
  
  Autogenerated value - user that created object.
- description string Required
  
  Describes the exception list.
- entries array[object] Required
  
  Any of:
  Security_Endpoint_Exceptions_API_ExceptionListItemEntryMatch object Security_Endpoint_Exceptions_API_ExceptionListItemEntryMatchAny object Security_Endpoint_Exceptions_API_ExceptionListItemEntryList object Security_Endpoint_Exceptions_API_ExceptionListItemEntryExists object Security_Endpoint_Exceptions_API_ExceptionListItemEntryNested object Security_Endpoint_Exceptions_API_ExceptionListItemEntryMatchWildcard object
  
  Hide attributes Show attributes
  
  field string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  operator string Required
  
  Values are excluded or included.
  
  type string Required Discriminator
  
  Value is match.
  
  value string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  Hide attributes Show attributes
  
  field string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  operator string Required
  
  Values are excluded or included.
  
  type string Required Discriminator
  
  Value is match_any.
  
  value array[string(nonempty)] Required
  
  A string that does not contain only whitespace characters
  
  At least 1 element. Minimum length of each is 1.
  
  Hide attributes Show attributes
  
  field string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  list object Required
  
  Hide list attributes Show list attributes object
  
  id string(nonempty) Required
  
  Value list's identifier.
  
  Minimum length is 1.
  
  type string Required
  
  Specifies the Elasticsearch data type of excludes the list container holds. Some common examples:
  
  keyword: Many ECS fields are Elasticsearch keywords
  
  ip: IP addresses
  
  ip_range: Range of IP addresses (supports IPv4, IPv6, and CIDR notation)
  
  Values are binary, boolean, byte, date, date_nanos, date_range, double, double_range, float, float_range, geo_point, geo_shape, half_float, integer, integer_range, ip, ip_range, keyword, long, long_range, shape, short, or text.
  
  operator string Required
  
  Values are excluded or included.
  
  type string Required Discriminator
  
  Value is list.
  
  Hide attributes Show attributes
  
  field string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  operator string Required
  
  Values are excluded or included.
  
  type string Required Discriminator
  
  Value is exists.
  
  Hide attributes Show attributes
  
  entries array[object] Required
  
  At least 1 element.
  
  One of:
  Security_Endpoint_Exceptions_API_ExceptionListItemEntryMatch object Security_Endpoint_Exceptions_API_ExceptionListItemEntryMatchAny object Security_Endpoint_Exceptions_API_ExceptionListItemEntryExists object
  
  Hide attributes Show attributes
  
  field string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  operator string Required
  
  Values are excluded or included.
  
  type string Required
  
  Value is match.
  
  value string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  Hide attributes Show attributes
  
  field string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  operator string Required
  
  Values are excluded or included.
  
  type string Required
  
  Value is match_any.
  
  value array[string(nonempty)] Required
  
  A string that does not contain only whitespace characters
  
  At least 1 element. Minimum length of each is 1.
  
  Hide attributes Show attributes
  
  field string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  operator string Required
  
  Values are excluded or included.
  
  type string Required
  
  Value is exists.
  
  field string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  type string Required Discriminator
  
  Value is nested.
  
  Hide attributes Show attributes
  
  field string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  operator string Required
  
  Values are excluded or included.
  
  type string Required Discriminator
  
  Value is wildcard.
  
  value string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- expire_time string(date-time)
  
  The exception item’s expiration date, in ISO format. This field is only available for regular exception items, not endpoint exceptions.
- id string(nonempty) Required
  
  Exception's identifier.
  
  Minimum length is 1.
- item_id string(nonempty) Required
  
  Human readable string identifier, e.g. trusted-linux-processes
  
  Minimum length is 1.
- list_id string(nonempty) Required
  
  Exception list's human readable string identifier, e.g. trusted-linux-processes.
  
  Minimum length is 1.
- meta object
  
  Additional properties are allowed.
- name string(nonempty) Required
  
  Exception list name.
  
  Minimum length is 1.
- namespace_type string Required
  
  Determines whether the exception container is available in all Kibana spaces or just the space in which it is created, where:
  
  single: Only available in the Kibana space in which it is created.
  
  agnostic: Available in all Kibana spaces.
  
  Values are agnostic or single.
- os_types array[string]
  
  Use this field to specify the operating system.
  
  Values are linux, macos, or windows.
- tags array[string(nonempty)]
  
  String array containing words and phrases to help categorize exception items.
  
  Minimum length of each is 1.
- tie_breaker_id string Required
  
  Field used in search to ensure all containers are sorted and returned correctly.
- type string Required
  
  Value is simple.
- updated_at string(date-time) Required
  
  Autogenerated date of last object update.
- updated_by string Required
  
  Autogenerated value - user that last updated object.
400 application/json

Invalid input data
One of:
Security_Endpoint_Exceptions_API_PlatformErrorResponse object Security_Endpoint_Exceptions_API_SiemErrorResponse object
Hide attributes Show attributes

error string Required

message string Required

statusCode integer Required
Hide attributes Show attributes

message string Required

status_code integer Required
401 application/json

Unsuccessful authentication
Hide response attributes Show response attributes object
- error string Required
- message string Required
- statusCode integer Required
403 application/json

Insufficient privileges
Hide response attributes Show response attributes object
- error string Required
- message string Required
- statusCode integer Required
409 application/json

Endpoint list item already exists
Hide response attributes Show response attributes object
- message string Required
- status_code integer Required
500 application/json

Internal server error
Hide response attributes Show response attributes object
- message string Required
- status_code integer Required

POST /api/endpoint_list/items

curl \
 --request POST 'https://<KIBANA_URL>/api/endpoint_list/items' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"comments":[{"comment":"string","created_at":"2025-05-04T09:42:00Z","created_by":"string","id":"string","updated_at":"2025-05-04T09:42:00Z","updated_by":"string"}],"description":"string","entries":[{"field":"string","operator":"excluded","type":"match","value":"string"}],"item_id":"simple_list_item","meta":{},"name":"string","os_types":["linux"],"tags":["string"],"type":"simple"}'

Delete an endpoint exception list item

DELETE /api/endpoint_list/items

Delete an endpoint exception list item using the id or item_id field.

Query parameters

id string(nonempty)

Either id or item_id must be specified

Minimum length is 1.
item_id string(nonempty)

Either id or item_id must be specified

Minimum length is 1.

Responses

200 application/json

Successful response
Hide response attributes Show response attributes object
- _version string
  
  The version id, normally returned by the API when the item was retrieved. Use it ensure updates are done against the latest version.
- comments array[object] Required
  
  Array of comment fields:
  
  comment (string): Comments about the exception item.
  
  Hide comments attributes Show comments attributes object
  
  comment string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  created_at string(date-time) Required
  
  Autogenerated date of object creation.
  
  created_by string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  id string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  updated_at string(date-time)
  
  Autogenerated date of last object update.
  
  updated_by string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- created_at string(date-time) Required
  
  Autogenerated date of object creation.
- created_by string Required
  
  Autogenerated value - user that created object.
- description string Required
  
  Describes the exception list.
- entries array[object] Required
  
  Any of:
  Security_Endpoint_Exceptions_API_ExceptionListItemEntryMatch object Security_Endpoint_Exceptions_API_ExceptionListItemEntryMatchAny object Security_Endpoint_Exceptions_API_ExceptionListItemEntryList object Security_Endpoint_Exceptions_API_ExceptionListItemEntryExists object Security_Endpoint_Exceptions_API_ExceptionListItemEntryNested object Security_Endpoint_Exceptions_API_ExceptionListItemEntryMatchWildcard object
  
  Hide attributes Show attributes
  
  field string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  operator string Required
  
  Values are excluded or included.
  
  type string Required Discriminator
  
  Value is match.
  
  value string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  Hide attributes Show attributes
  
  field string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  operator string Required
  
  Values are excluded or included.
  
  type string Required Discriminator
  
  Value is match_any.
  
  value array[string(nonempty)] Required
  
  A string that does not contain only whitespace characters
  
  At least 1 element. Minimum length of each is 1.
  
  Hide attributes Show attributes
  
  field string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  list object Required
  
  Hide list attributes Show list attributes object
  
  id string(nonempty) Required
  
  Value list's identifier.
  
  Minimum length is 1.
  
  type string Required
  
  Specifies the Elasticsearch data type of excludes the list container holds. Some common examples:
  
  keyword: Many ECS fields are Elasticsearch keywords
  
  ip: IP addresses
  
  ip_range: Range of IP addresses (supports IPv4, IPv6, and CIDR notation)
  
  Values are binary, boolean, byte, date, date_nanos, date_range, double, double_range, float, float_range, geo_point, geo_shape, half_float, integer, integer_range, ip, ip_range, keyword, long, long_range, shape, short, or text.
  
  operator string Required
  
  Values are excluded or included.
  
  type string Required Discriminator
  
  Value is list.
  
  Hide attributes Show attributes
  
  field string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  operator string Required
  
  Values are excluded or included.
  
  type string Required Discriminator
  
  Value is exists.
  
  Hide attributes Show attributes
  
  entries array[object] Required
  
  At least 1 element.
  
  One of:
  Security_Endpoint_Exceptions_API_ExceptionListItemEntryMatch object Security_Endpoint_Exceptions_API_ExceptionListItemEntryMatchAny object Security_Endpoint_Exceptions_API_ExceptionListItemEntryExists object
  
  Hide attributes Show attributes
  
  field string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  operator string Required
  
  Values are excluded or included.
  
  type string Required
  
  Value is match.
  
  value string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  Hide attributes Show attributes
  
  field string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  operator string Required
  
  Values are excluded or included.
  
  type string Required
  
  Value is match_any.
  
  value array[string(nonempty)] Required
  
  A string that does not contain only whitespace characters
  
  At least 1 element. Minimum length of each is 1.
  
  Hide attributes Show attributes
  
  field string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  operator string Required
  
  Values are excluded or included.
  
  type string Required
  
  Value is exists.
  
  field string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  type string Required Discriminator
  
  Value is nested.
  
  Hide attributes Show attributes
  
  field string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  operator string Required
  
  Values are excluded or included.
  
  type string Required Discriminator
  
  Value is wildcard.
  
  value string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- expire_time string(date-time)
  
  The exception item’s expiration date, in ISO format. This field is only available for regular exception items, not endpoint exceptions.
- id string(nonempty) Required
  
  Exception's identifier.
  
  Minimum length is 1.
- item_id string(nonempty) Required
  
  Human readable string identifier, e.g. trusted-linux-processes
  
  Minimum length is 1.
- list_id string(nonempty) Required
  
  Exception list's human readable string identifier, e.g. trusted-linux-processes.
  
  Minimum length is 1.
- meta object
  
  Additional properties are allowed.
- name string(nonempty) Required
  
  Exception list name.
  
  Minimum length is 1.
- namespace_type string Required
  
  Determines whether the exception container is available in all Kibana spaces or just the space in which it is created, where:
  
  single: Only available in the Kibana space in which it is created.
  
  agnostic: Available in all Kibana spaces.
  
  Values are agnostic or single.
- os_types array[string]
  
  Use this field to specify the operating system.
  
  Values are linux, macos, or windows.
- tags array[string(nonempty)]
  
  String array containing words and phrases to help categorize exception items.
  
  Minimum length of each is 1.
- tie_breaker_id string Required
  
  Field used in search to ensure all containers are sorted and returned correctly.
- type string Required
  
  Value is simple.
- updated_at string(date-time) Required
  
  Autogenerated date of last object update.
- updated_by string Required
  
  Autogenerated value - user that last updated object.
400 application/json

Invalid input data
One of:
Security_Endpoint_Exceptions_API_PlatformErrorResponse object Security_Endpoint_Exceptions_API_SiemErrorResponse object
Hide attributes Show attributes

error string Required

message string Required

statusCode integer Required
Hide attributes Show attributes

message string Required

status_code integer Required
401 application/json

Unsuccessful authentication
Hide response attributes Show response attributes object
- error string Required
- message string Required
- statusCode integer Required
403 application/json

Insufficient privileges
Hide response attributes Show response attributes object
- error string Required
- message string Required
- statusCode integer Required
404 application/json

Endpoint list item not found
Hide response attributes Show response attributes object
- message string Required
- status_code integer Required
500 application/json

Internal server error
Hide response attributes Show response attributes object
- message string Required
- status_code integer Required

DELETE /api/endpoint_list/items

curl \
 --request DELETE 'https://<KIBANA_URL>/api/endpoint_list/items' \
 --header "Authorization: $API_KEY"

Get endpoint exception list items

GET /api/endpoint_list/items/_find

Get a list of all endpoint exception list items.

Query parameters

filter string(nonempty)

Filters the returned results according to the value of the specified field, using the <field name>:<field value> syntax.

Minimum length is 1.
page integer

The page number to return

Minimum value is 0.
per_page integer

The number of exception list items to return per page

Minimum value is 0.
sort_field string(nonempty)

Determines which field is used to sort the results

Minimum length is 1.
sort_order string

Determines the sort order, which can be desc or asc

Values are desc or asc.

Responses

200 application/json

Successful response
Hide response attributes Show response attributes object
- data array[object] Required
  
  Hide data attributes Show data attributes object
  
  _version string
  
  The version id, normally returned by the API when the item was retrieved. Use it ensure updates are done against the latest version.
  
  comments array[object] Required
  
  Array of comment fields:
  
  comment (string): Comments about the exception item.
  
  Hide comments attributes Show comments attributes object
  
  comment string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  created_at string(date-time) Required
  
  Autogenerated date of object creation.
  
  created_by string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  id string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  updated_at string(date-time)
  
  Autogenerated date of last object update.
  
  updated_by string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  created_at string(date-time) Required
  
  Autogenerated date of object creation.
  
  created_by string Required
  
  Autogenerated value - user that created object.
  
  description string Required
  
  Describes the exception list.
  
  entries array[object] Required
  
  Any of:
  Security_Endpoint_Exceptions_API_ExceptionListItemEntryMatch object Security_Endpoint_Exceptions_API_ExceptionListItemEntryMatchAny object Security_Endpoint_Exceptions_API_ExceptionListItemEntryList object Security_Endpoint_Exceptions_API_ExceptionListItemEntryExists object Security_Endpoint_Exceptions_API_ExceptionListItemEntryNested object Security_Endpoint_Exceptions_API_ExceptionListItemEntryMatchWildcard object
  
  Hide attributes Show attributes
  
  field string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  operator string Required
  
  Values are excluded or included.
  
  type string Required Discriminator
  
  Value is match.
  
  value string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  Hide attributes Show attributes
  
  field string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  operator string Required
  
  Values are excluded or included.
  
  type string Required Discriminator
  
  Value is match_any.
  
  value array[string(nonempty)] Required
  
  A string that does not contain only whitespace characters
  
  At least 1 element. Minimum length of each is 1.
  
  Hide attributes Show attributes
  
  field string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  list object Required
  
  Hide list attributes Show list attributes object
  
  id string(nonempty) Required
  
  Value list's identifier.
  
  Minimum length is 1.
  
  type string Required
  
  Specifies the Elasticsearch data type of excludes the list container holds. Some common examples:
  
  keyword: Many ECS fields are Elasticsearch keywords
  
  ip: IP addresses
  
  ip_range: Range of IP addresses (supports IPv4, IPv6, and CIDR notation)
  
  Values are binary, boolean, byte, date, date_nanos, date_range, double, double_range, float, float_range, geo_point, geo_shape, half_float, integer, integer_range, ip, ip_range, keyword, long, long_range, shape, short, or text.
  
  operator string Required
  
  Values are excluded or included.
  
  type string Required Discriminator
  
  Value is list.
  
  Hide attributes Show attributes
  
  field string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  operator string Required
  
  Values are excluded or included.
  
  type string Required Discriminator
  
  Value is exists.
  
  Hide attributes Show attributes
  
  entries array[object] Required
  
  At least 1 element.
  
  One of:
  Security_Endpoint_Exceptions_API_ExceptionListItemEntryMatch object Security_Endpoint_Exceptions_API_ExceptionListItemEntryMatchAny object Security_Endpoint_Exceptions_API_ExceptionListItemEntryExists object
  
  Hide attributes Show attributes
  
  field string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  operator string Required
  
  Values are excluded or included.
  
  type string Required
  
  Value is match.
  
  value string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  Hide attributes Show attributes
  
  field string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  operator string Required
  
  Values are excluded or included.
  
  type string Required
  
  Value is match_any.
  
  value array[string(nonempty)] Required
  
  A string that does not contain only whitespace characters
  
  At least 1 element. Minimum length of each is 1.
  
  Hide attributes Show attributes
  
  field string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  operator string Required
  
  Values are excluded or included.
  
  type string Required
  
  Value is exists.
  
  field string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  type string Required Discriminator
  
  Value is nested.
  
  Hide attributes Show attributes
  
  field string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  operator string Required
  
  Values are excluded or included.
  
  type string Required Discriminator
  
  Value is wildcard.
  
  value string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  expire_time string(date-time)
  
  The exception item’s expiration date, in ISO format. This field is only available for regular exception items, not endpoint exceptions.
  
  id string(nonempty) Required
  
  Exception's identifier.
  
  Minimum length is 1.
  
  item_id string(nonempty) Required
  
  Human readable string identifier, e.g. trusted-linux-processes
  
  Minimum length is 1.
  
  list_id string(nonempty) Required
  
  Exception list's human readable string identifier, e.g. trusted-linux-processes.
  
  Minimum length is 1.
  
  meta object
  
  Additional properties are allowed.
  
  name string(nonempty) Required
  
  Exception list name.
  
  Minimum length is 1.
  
  namespace_type string Required
  
  Determines whether the exception container is available in all Kibana spaces or just the space in which it is created, where:
  
  single: Only available in the Kibana space in which it is created.
  
  agnostic: Available in all Kibana spaces.
  
  Values are agnostic or single.
  
  os_types array[string]
  
  Use this field to specify the operating system.
  
  Values are linux, macos, or windows.
  
  tags array[string(nonempty)]
  
  String array containing words and phrases to help categorize exception items.
  
  Minimum length of each is 1.
  
  tie_breaker_id string Required
  
  Field used in search to ensure all containers are sorted and returned correctly.
  
  type string Required
  
  Value is simple.
  
  updated_at string(date-time) Required
  
  Autogenerated date of last object update.
  
  updated_by string Required
  
  Autogenerated value - user that last updated object.
- page integer Required
  
  Minimum value is 0.
- per_page integer Required
  
  Minimum value is 0.
- pit string
- total integer Required
  
  Minimum value is 0.
400 application/json

Invalid input data
One of:
Security_Endpoint_Exceptions_API_PlatformErrorResponse object Security_Endpoint_Exceptions_API_SiemErrorResponse object
Hide attributes Show attributes

error string Required

message string Required

statusCode integer Required
Hide attributes Show attributes

message string Required

status_code integer Required
401 application/json

Unsuccessful authentication
Hide response attributes Show response attributes object
- error string Required
- message string Required
- statusCode integer Required
403 application/json

Insufficient privileges
Hide response attributes Show response attributes object
- error string Required
- message string Required
- statusCode integer Required
404 application/json

Endpoint list not found
Hide response attributes Show response attributes object
- message string Required
- status_code integer Required
500 application/json

Internal server error
Hide response attributes Show response attributes object
- message string Required
- status_code integer Required

GET /api/endpoint_list/items/_find

curl \
 --request GET 'https://<KIBANA_URL>/api/endpoint_list/items/_find' \
 --header "Authorization: $API_KEY"

Get response actions

GET /api/endpoint/action

Get a list of all response actions.

Query parameters

page integer

Page number

Minimum value is 1. Default value is 1.
pageSize integer

Number of items per page

Minimum value is 1, maximum value is 100. Default value is 10.
commands array[string]

A list of response action command names.

Minimum length of each is 1. Values are isolate, unisolate, kill-process, suspend-process, running-processes, get-file, execute, upload, or scan.
agentIds array[string] | string

A list of agent IDs. Max of 50.
userIds array[string] | string

A list of user IDs.
startDate string

A start date in ISO 8601 format or Date Math format.
endDate string

An end date in ISO format or Date Math format.
agentTypes string

List of agent types to retrieve. Defaults to endpoint.

Values are endpoint, sentinel_one, crowdstrike, or microsoft_defender_endpoint.
withOutputs array[string] | string

A list of action IDs that should include the complete output of the action.
types array[string]

List of types of response actions

Values are automated or manual.

Responses

200 application/json

OK

GET /api/endpoint/action

curl \
 --request GET 'https://<KIBANA_URL>/api/endpoint/action' \
 --header "Authorization: $API_KEY"

Response examples (200)

{
  "data": [
    {
      "id": "b3d6de74-36b0-4fa8-be46-c375bf1771bf",
      "agents": [
        "afdc366c-e2e0-4cdb-ae1d-94575bd2d8e0"
      ],
      "command": "running-processes",
      "agentType": "endpoint",
      "createdBy": "elastic",
      "isExpired": false,
      "startedAt": "2022-08-08T15:24:57.402Z",
      "completedAt": "2022-08-08T09:50:47.672Z",
      "isCompleted": true,
      "wasSuccessful": true
    },
    {
      "id": "43b4098b-8752-4fbb-a7a7-6df7c74d0ee3",
      "agents": [
        "afdc366c-e2e0-4cdb-ae1d-94575bd2d8e0"
      ],
      "command": "isolate",
      "agentType": "endpoint",
      "createdBy": "elastic",
      "isExpired": false,
      "startedAt": "2022-08-08T15:23:37.359Z",
      "completedAt": "2022-08-08T10:41:57.352Z",
      "isCompleted": true,
      "wasSuccessful": true
    },
    {
      "id": "5bc92c86-b8e6-42dd-837f-12ad29e09caa",
      "agents": [
        "afdc366c-e2e0-4cdb-ae1d-94575bd2d8e0"
      ],
      "command": "kill-process",
      "comment": "bad process - taking up too much cpu",
      "agentType": "endpoint",
      "createdBy": "elastic",
      "isExpired": false,
      "startedAt": "2022-08-08T14:38:44.125Z",
      "completedAt": "2022-08-08T09:44:50.952Z",
      "isCompleted": true,
      "wasSuccessful": true
    },
    {
      "id": "790d54e0-3aa3-4e5b-8255-3ce9d851246a",
      "agents": [
        "afdc366c-e2e0-4cdb-ae1d-94575bd2d8e0"
      ],
      "command": "unisolate",
      "comment": "Not a threat to the network",
      "agentType": "endpoint",
      "createdBy": "elastic",
      "isExpired": false,
      "startedAt": "2022-08-08T14:38:15.391Z",
      "completedAt": "2022-08-08T09:40:47.398Z",
      "isCompleted": true,
      "wasSuccessful": true
    }
  ],
  "page": 1,
  "total": 4,
  "endDate": "now",
  "pageSize": 10,
  "startDate": "now-24h/h",
  "elasticAgentIds": [
    "afdc366c-e2e0-4cdb-ae1d-94575bd2d8e0"
  ]
}

Get response actions status

GET /api/endpoint/action_status

Get the status of response actions for the specified agent IDs.

Query parameters

query object Required
Hide query attribute Show query attribute object
- agent_ids array[string] | string
  
  A list of agent IDs. Max of 50.
  
  One of:
  array-1 array[string] string-2 string
  
  At least 1 but not more than 50 elements. Minimum length of each is 1.

Responses

200 application/json

OK
Hide response attribute Show response attribute object
- body object Required
  
  Hide body attribute Show body attribute object
  
  data object Required
  
  Hide data attributes Show data attributes object
  
  agent_id string Required
  
  Agent ID
  
  pending_actions object Required
  
  One of:
  object-1 object object-2 object
  
  Hide attributes Show attributes
  
  execute integer
  
  get-file integer
  
  isolate integer
  
  kill-process integer
  
  running-processes integer
  
  scan integer
  
  suspend-process integer
  
  unisolate integer
  
  upload integer

GET /api/endpoint/action_status

curl \
 --request GET 'https://<KIBANA_URL>/api/endpoint/action_status?query=%7B%7D' \
 --header "Authorization: $API_KEY"

Get action details

GET /api/endpoint/action/{action_id}

Get the details of a response action using the action ID.

Path parameters

action_id string Required

The ID of the action to retrieve.

Responses

200 application/json

OK

GET /api/endpoint/action/{action_id}

curl \
 --request GET 'https://<KIBANA_URL>/api/endpoint/action/fr518850-681a-4y60-aa98-e22640cae2b8' \
 --header "Authorization: $API_KEY"

Response examples (200)

{
  "data": {
    "id": "b3d6de74-36b0-4fa8-be46-c375bf1771bf",
    "agents": [
      "afdc366c-e2e0-4cdb-ae1d-94575bd2d8e0"
    ],
    "command": "running-processes",
    "outputs": {
      "afdc366c-e2e0-4cdb-ae1d-94575bd2d8e0": {
        "type": "json",
        "content": {
          "entries": [
            {
              "pid": "822",
              "user": "Dexter",
              "command": "/opt/cmd1",
              "entity_id": "fk2ym7bl3oiu3okjcik0xosc0i0m75x3eh49nu3uaqt4dqanjt"
            },
            {
              "pid": "984",
              "user": "Jada",
              "command": "/opt/cmd3/opt/cmd3/opt/cmd3/opt/cmd3",
              "entity_id": "pwvz91m48wpj9j7ov9gtw8fp7u2rat4eu5ipte37hnhdcbi2pt"
            }
          ]
        }
      }
    },
    "agentType": "endpoint",
    "createdBy": "elastic",
    "isExpired": false,
    "startedAt": "2022-08-08T15:24:57.402Z",
    "completedAt": "2022-08-08T09:50:47.672Z",
    "isCompleted": true,
    "wasSuccessful": true
  }
}

Get file information

GET /api/endpoint/action/{action_id}/file/{file_id}

Get information for the specified file using the file ID.

Path parameters

action_id string Required
file_id string Required

Responses

200 application/json

OK

GET /api/endpoint/action/{action_id}/file/{file_id}

curl \
 --request GET 'https://<KIBANA_URL>/api/endpoint/action/{action_id}/file/{file_id}' \
 --header "Authorization: $API_KEY"

Download a file

GET /api/endpoint/action/{action_id}/file/{file_id}/download

Download a file from an endpoint.

Path parameters

action_id string Required
file_id string Required

Responses

200 application/json

OK

GET /api/endpoint/action/{action_id}/file/{file_id}/download

curl \
 --request GET 'https://<KIBANA_URL>/api/endpoint/action/{action_id}/file/{file_id}/download' \
 --header "Authorization: $API_KEY"

Run a command

POST /api/endpoint/action/execute

Run a shell command on an endpoint.

application/json

Body Required

agent_type string

List of agent types to retrieve. Defaults to endpoint.

Values are endpoint, sentinel_one, crowdstrike, or microsoft_defender_endpoint.
alert_ids array[string(nonempty)]

A list of alerts ids.

At least 1 element. Minimum length of each is 1.
case_ids array[string]

Case IDs to be updated (cannot contain empty strings)

At least 1 element. Minimum length of each is 1.
comment string

Optional comment
endpoint_ids array[string] Required

List of endpoint IDs (cannot contain empty strings)

At least 1 element. Minimum length of each is 1.
parameters object Required

Optional parameters object
Hide parameters attributes Show parameters attributes object
- command string Required
  
  The command to be executed (cannot be an empty string)
  
  Minimum length is 1. Values are isolate, unisolate, kill-process, suspend-process, running-processes, get-file, execute, upload, or scan.
- timeout integer
  
  The maximum timeout value in milliseconds (optional)
  
  Minimum value is 1.

Responses

200 application/json

OK

POST /api/endpoint/action/execute

curl \
 --request POST 'https://<KIBANA_URL>/api/endpoint/action/execute' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"comment":"Get list of all files","parameters":{"command":"ls -al","timeout":600},"endpoint_ids":["b3d6de74-36b0-4fa8-be46-c375bf1771bf"]}'

Request example

{
  "comment": "Get list of all files",
  "parameters": {
    "command": "ls -al",
    "timeout": 600
  },
  "endpoint_ids": [
    "b3d6de74-36b0-4fa8-be46-c375bf1771bf"
  ]
}

Response examples (200)

{
  "data": {
    "id": "9f934028-2300-4927-b531-b26376793dc4",
    "hosts": {
      "ed518850-681a-4d60-bb98-e22640cae2a8": {
        "name": "gke-endpoint-gke-clu-endpoint-node-po-e1a3ab89-4c4r"
      }
    },
    "agents": [
      "ed518850-681a-4d60-bb98-e22640cae2a8"
    ],
    "status": "pending",
    "command": "execute",
    "comment": "Get list of all files",
    "outputs": {},
    "agentType": "endpoint",
    "createdBy": "myuser",
    "isExpired": false,
    "startedAt": "2023-07-28T18:43:27.362Z",
    "agentState": {
      "ed518850-681a-4d60-bb98-e22640cae2a8": {
        "isCompleted": false,
        "wasSuccessful": false
      }
    },
    "parameters": {
      "command": "ls -al",
      "timeout": 600
    },
    "isCompleted": false,
    "wasSuccessful": false
  }
}

Get a file

POST /api/endpoint/action/get_file

Get a file from an endpoint.

application/json

Body Required

agent_type string

List of agent types to retrieve. Defaults to endpoint.

Values are endpoint, sentinel_one, crowdstrike, or microsoft_defender_endpoint.
alert_ids array[string(nonempty)]

A list of alerts ids.

At least 1 element. Minimum length of each is 1.
case_ids array[string]

Case IDs to be updated (cannot contain empty strings)

At least 1 element. Minimum length of each is 1.
comment string

Optional comment
endpoint_ids array[string] Required

List of endpoint IDs (cannot contain empty strings)

At least 1 element. Minimum length of each is 1.
parameters object Required

Optional parameters object
Hide parameters attribute Show parameters attribute object
- path string Required

Responses

200 application/json

OK

POST /api/endpoint/action/get_file

curl \
 --request POST 'https://<KIBANA_URL>/api/endpoint/action/get_file' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"comment":"Get my file","parameters":{"path":"/usr/my-file.txt"},"endpoint_ids":["ed518850-681a-4d60-bb98-e22640cae2a8"]}'

Request example

{
  "comment": "Get my file",
  "parameters": {
    "path": "/usr/my-file.txt"
  },
  "endpoint_ids": [
    "ed518850-681a-4d60-bb98-e22640cae2a8"
  ]
}

Response examples (200)

{
  "data": {
    "id": "27ba1b42-7cc6-4e53-86ce-675c876092b2",
    "hosts": {
      "ed518850-681a-4d60-bb98-e22640cae2a8": {
        "name": "gke-endpoint-gke-clu-endpoint-node-po-e1a3ab89-4c4r"
      }
    },
    "agents": [
      "ed518850-681a-4d60-bb98-e22640cae2a8"
    ],
    "status": "pending",
    "command": "get-file",
    "outputs": {},
    "agentType": "endpoint",
    "createdBy": "myuser",
    "isExpired": false,
    "startedAt": "2023-07-28T19:00:03.911Z",
    "agentState": {
      "ed518850-681a-4d60-bb98-e22640cae2a8": {
        "isCompleted": false,
        "wasSuccessful": false
      }
    },
    "parameters": {
      "path": "/usr/my-file.txt"
    },
    "isCompleted": false,
    "wasSuccessful": false
  }
}

Isolate an endpoint

POST /api/endpoint/action/isolate

Isolate an endpoint from the network. The endpoint remains isolated until it's released.

application/json

Body Required

agent_type string

List of agent types to retrieve. Defaults to endpoint.

Values are endpoint, sentinel_one, crowdstrike, or microsoft_defender_endpoint.
alert_ids array[string(nonempty)]

A list of alerts ids.

At least 1 element. Minimum length of each is 1.
case_ids array[string]

Case IDs to be updated (cannot contain empty strings)

At least 1 element. Minimum length of each is 1.
comment string

Optional comment
endpoint_ids array[string] Required

List of endpoint IDs (cannot contain empty strings)

At least 1 element. Minimum length of each is 1.
parameters object

Optional parameters object

Responses

200 application/json

OK

POST /api/endpoint/action/isolate

curl \
 --request POST 'https://<KIBANA_URL>/api/endpoint/action/isolate' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"comment":"Locked down, pending further investigation","endpoint_ids":["9972d10e-4b9e-41aa-a534-a85e2a28ea42","bc0e4f0c-3bca-4633-9fee-156c0b505d16","fa89271b-b9d4-43f2-a684-307cffddeb5a"]}'

Request examples

{
  "comment": "Locked down, pending further investigation",
  "endpoint_ids": [
    "9972d10e-4b9e-41aa-a534-a85e2a28ea42",
    "bc0e4f0c-3bca-4633-9fee-156c0b505d16",
    "fa89271b-b9d4-43f2-a684-307cffddeb5a"
  ]
}

{
  "endpoint_ids": [
    "ed518850-681a-4d60-bb98-e22640cae2a8"
  ]
}

{
  "comment": "Isolating as initial response",
  "case_ids": [
    "4976be38-c134-4554-bd5e-0fd89ce63667"
  ],
  "endpoint_ids": [
    "1aa1f8fd-0fb0-4fe4-8c30-92068272d3f0",
    "b30a11bf-1395-4707-b508-fbb45ef9793e"
  ]
}

Response examples (200)

{
  "data": {
    "id": "233db9ea-6733-4849-9226-5a7039c7161d",
    "agents": [
      "ed518850-681a-4d60-bb98-e22640cae2a8"
    ],
    "errors": [],
    "command": "suspend-process",
    "comment": "suspend the process",
    "outputs": {
      "ed518850-681a-4d60-bb98-e22640cae2a8": {
        "type": "json",
        "content": {
          "key": "value"
        }
      }
    },
    "agentType": "endpoint",
    "createdBy": "myuser",
    "isExpired": false,
    "startedAt": "2022-07-29T19:08:49.126Z",
    "parameters": {
      "entity_id": "abc123"
    },
    "completedAt": "2022-07-29T19:09:44.961Z",
    "isCompleted": true,
    "wasSuccessful": true
  },
  "action": "233db9ea-6733-4849-9226-5a7039c7161d"
}

Terminate a process

POST /api/endpoint/action/kill_process

Terminate a running process on an endpoint.

application/json

Body Required

agent_type string

List of agent types to retrieve. Defaults to endpoint.

Values are endpoint, sentinel_one, crowdstrike, or microsoft_defender_endpoint.
alert_ids array[string(nonempty)]

A list of alerts ids.

At least 1 element. Minimum length of each is 1.
case_ids array[string]

Case IDs to be updated (cannot contain empty strings)

At least 1 element. Minimum length of each is 1.
comment string

Optional comment
endpoint_ids array[string] Required

List of endpoint IDs (cannot contain empty strings)

At least 1 element. Minimum length of each is 1.
parameters object Required
One of:
object-1 object object-2 object object-3 object
Hide attribute Show attribute

pid integer

The process ID (PID) of the process to terminate.

Minimum value is 1.
Hide attribute Show attribute

entity_id string

The entity ID of the process to terminate.

Minimum length is 1.
Hide attribute Show attribute

process_name string

The name of the process to terminate. Valid for SentinelOne agent type only.

Minimum length is 1.
parameters object

Optional parameters object

Responses

200 application/json

OK

POST /api/endpoint/action/kill_process

curl \
 --request POST 'https://<KIBANA_URL>/api/endpoint/action/kill_process' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"comment":"terminate the process","parameters":{"entity_id":"abc123"},"endpoint_ids":["ed518850-681a-4d60-bb98-e22640cae2a8"]}'

Request example

{
  "comment": "terminate the process",
  "parameters": {
    "entity_id": "abc123"
  },
  "endpoint_ids": [
    "ed518850-681a-4d60-bb98-e22640cae2a8"
  ]
}

Response examples (200)

{
  "data": {
    "id": "233db9ea-6733-4849-9226-5a7039c7161d",
    "agents": [
      "ed518850-681a-4d60-bb98-e22640cae2a8"
    ],
    "errors": [],
    "command": "kill-process",
    "comment": "terminate the process",
    "outputs": {
      "ed518850-681a-4d60-bb98-e22640cae2a8": {
        "type": "json",
        "content": {
          "key": "value"
        }
      }
    },
    "agentType": "endpoint",
    "createdBy": "myuser",
    "isExpired": false,
    "startedAt": "2022-07-29T19:08:49.126Z",
    "parameters": {
      "entity_id": "abc123"
    },
    "completedAt": "2022-07-29T19:09:44.961Z",
    "isCompleted": true,
    "wasSuccessful": true
  }
}

Get running processes

POST /api/endpoint/action/running_procs

Get a list of all processes running on an endpoint.

application/json

Body Required

agent_type string

List of agent types to retrieve. Defaults to endpoint.

Values are endpoint, sentinel_one, crowdstrike, or microsoft_defender_endpoint.
alert_ids array[string(nonempty)]

A list of alerts ids.

At least 1 element. Minimum length of each is 1.
case_ids array[string]

Case IDs to be updated (cannot contain empty strings)

At least 1 element. Minimum length of each is 1.
comment string

Optional comment
endpoint_ids array[string] Required

List of endpoint IDs (cannot contain empty strings)

At least 1 element. Minimum length of each is 1.
parameters object

Optional parameters object

Responses

200 application/json

OK

POST /api/endpoint/action/running_procs

curl \
 --request POST 'https://<KIBANA_URL>/api/endpoint/action/running_procs' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"endpoint_ids":["ed518850-681a-4d60-bb98-e22640cae2a8"]}'

Request example

{
  "endpoint_ids": [
    "ed518850-681a-4d60-bb98-e22640cae2a8"
  ]
}

Response examples (200)

{
  "data": {
    "id": "233db9ea-6733-4849-9226-5a7039c7161d",
    "agents": [
      "ed518850-681a-4d60-bb98-e22640cae2a8"
    ],
    "errors": [],
    "command": "running-processes",
    "comment": "",
    "outputs": {
      "ed518850-681a-4d60-bb98-e22640cae2a8": {
        "type": "json",
        "content": {
          "key": "value"
        }
      }
    },
    "agentType": "endpoint",
    "createdBy": "myuser",
    "isExpired": false,
    "startedAt": "2022-07-29T19:08:49.126Z",
    "parameters": {},
    "completedAt": "2022-07-29T19:09:44.961Z",
    "isCompleted": true,
    "wasSuccessful": true
  }
}

Run a script

POST /api/endpoint/action/runscript

Run a shell command on an endpoint.

application/json

Body Required

parameters object Required

Exactly one of 'Raw', 'HostPath', or 'CloudFile' must be provided. CommandLine and Timeout are optional for all.
One of:
Security_Endpoint_Management_API_RawScriptParameters object Security_Endpoint_Management_API_HostPathScriptParameters object Security_Endpoint_Management_API_CloudFileScriptParameters object
Hide attributes Show attributes

commandLine string

Command line arguments.

Minimum length is 1.

raw string Required

Raw script content.

Minimum length is 1.

timeout integer

Timeout in seconds.

Minimum value is 1.
Hide attributes Show attributes

commandLine string

Command line arguments.

Minimum length is 1.

hostPath string Required

Absolute or relative path of script on host machine.

Minimum length is 1.

timeout integer

Timeout in seconds.

Minimum value is 1.
Hide attributes Show attributes

cloudFile string Required

Script name in cloud storage.

Minimum length is 1.

commandLine string

Command line arguments.

Minimum length is 1.

timeout integer

Timeout in seconds.

Minimum value is 1.

Responses

200 application/json

OK

POST /api/endpoint/action/runscript

curl \
 --request POST 'https://<KIBANA_URL>/api/endpoint/action/runscript' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"parameters":{"commandLine":"string","raw":"string","timeout":42}}'

Scan a file or directory

POST /api/endpoint/action/scan

Scan a specific file or directory on an endpoint for malware.

application/json

Body Required

agent_type string

List of agent types to retrieve. Defaults to endpoint.

Values are endpoint, sentinel_one, crowdstrike, or microsoft_defender_endpoint.
alert_ids array[string(nonempty)]

A list of alerts ids.

At least 1 element. Minimum length of each is 1.
case_ids array[string]

Case IDs to be updated (cannot contain empty strings)

At least 1 element. Minimum length of each is 1.
comment string

Optional comment
endpoint_ids array[string] Required

List of endpoint IDs (cannot contain empty strings)

At least 1 element. Minimum length of each is 1.
parameters object Required

Optional parameters object
Hide parameters attribute Show parameters attribute object
- path string Required
  
  The folder or file’s full path (including the file name).

Responses

200 application/json

OK

POST /api/endpoint/action/scan

curl \
 --request POST 'https://<KIBANA_URL>/api/endpoint/action/scan' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"comment":"Scan the file for malware","parameters":{"path":"/usr/my-file.txt"},"endpoint_ids":["ed518850-681a-4d60-bb98-e22640cae2a8"]}'

Request example

{
  "comment": "Scan the file for malware",
  "parameters": {
    "path": "/usr/my-file.txt"
  },
  "endpoint_ids": [
    "ed518850-681a-4d60-bb98-e22640cae2a8"
  ]
}

Response examples (200)

{
  "data": {
    "id": "27ba1b42-7cc6-4e53-86ce-675c876092b2",
    "hosts": {
      "ed518850-681a-4d60-bb98-e22640cae2a8": {
        "name": "gke-endpoint-gke-clu-endpoint-node-po-e1a3ab89-4c4r"
      }
    },
    "agents": [
      "ed518850-681a-4d60-bb98-e22640cae2a8"
    ],
    "status": "pending",
    "command": "scan",
    "outputs": {},
    "agentType": "endpoint",
    "createdBy": "myuser",
    "isExpired": false,
    "startedAt": "2023-07-28T19:00:03.911Z",
    "agentState": {
      "ed518850-681a-4d60-bb98-e22640cae2a8": {
        "isCompleted": false,
        "wasSuccessful": false
      }
    },
    "parameters": {
      "path": "/usr/my-file.txt"
    },
    "isCompleted": false,
    "wasSuccessful": false
  }
}

Get actions state

GET /api/endpoint/action/state

Get a response actions state, which reports whether encryption is enabled.

Responses

200 application/json

OK
Hide response attribute Show response attribute object
- body object Required
  
  Hide body attribute Show body attribute object
  
  data object Required
  
  Hide data attribute Show data attribute object
  
  canEncrypt boolean

GET /api/endpoint/action/state

curl \
 --request GET 'https://<KIBANA_URL>/api/endpoint/action/state' \
 --header "Authorization: $API_KEY"

Suspend a process

POST /api/endpoint/action/suspend_process

Suspend a running process on an endpoint.

application/json

Body Required

agent_type string

List of agent types to retrieve. Defaults to endpoint.

Values are endpoint, sentinel_one, crowdstrike, or microsoft_defender_endpoint.
alert_ids array[string(nonempty)]

A list of alerts ids.

At least 1 element. Minimum length of each is 1.
case_ids array[string]

Case IDs to be updated (cannot contain empty strings)

At least 1 element. Minimum length of each is 1.
comment string

Optional comment
endpoint_ids array[string] Required

List of endpoint IDs (cannot contain empty strings)

At least 1 element. Minimum length of each is 1.
parameters object Required
One of:
object-1 object object-2 object
Hide attribute Show attribute

pid integer

The process ID (PID) of the process to suspend.

Minimum value is 1.
Hide attribute Show attribute

entity_id string

The entity ID of the process to suspend.

Minimum length is 1.
parameters object

Optional parameters object

Responses

200 application/json

OK

POST /api/endpoint/action/suspend_process

curl \
 --request POST 'https://<KIBANA_URL>/api/endpoint/action/suspend_process' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"comment":"suspend the process","parameters":{"entity_id":"abc123"},"endpoint_ids":["ed518850-681a-4d60-bb98-e22640cae2a8"]}'

Request example

{
  "comment": "suspend the process",
  "parameters": {
    "entity_id": "abc123"
  },
  "endpoint_ids": [
    "ed518850-681a-4d60-bb98-e22640cae2a8"
  ]
}

Response examples (200)

{
  "data": {
    "id": "233db9ea-6733-4849-9226-5a7039c7161d",
    "agents": [
      "ed518850-681a-4d60-bb98-e22640cae2a8"
    ],
    "errors": [],
    "command": "suspend-process",
    "comment": "suspend the process",
    "outputs": {
      "ed518850-681a-4d60-bb98-e22640cae2a8": {
        "type": "json",
        "content": {
          "key": "value"
        }
      }
    },
    "agentType": "endpoint",
    "createdBy": "myuser",
    "isExpired": false,
    "startedAt": "2022-07-29T19:08:49.126Z",
    "parameters": {
      "entity_id": "abc123"
    },
    "completedAt": "2022-07-29T19:09:44.961Z",
    "isCompleted": true,
    "wasSuccessful": true
  }
}

Release an isolated endpoint

POST /api/endpoint/action/unisolate

Release an isolated endpoint, allowing it to rejoin a network.

application/json

Body Required

agent_type string

List of agent types to retrieve. Defaults to endpoint.

Values are endpoint, sentinel_one, crowdstrike, or microsoft_defender_endpoint.
alert_ids array[string(nonempty)]

A list of alerts ids.

At least 1 element. Minimum length of each is 1.
case_ids array[string]

Case IDs to be updated (cannot contain empty strings)

At least 1 element. Minimum length of each is 1.
comment string

Optional comment
endpoint_ids array[string] Required

List of endpoint IDs (cannot contain empty strings)

At least 1 element. Minimum length of each is 1.
parameters object

Optional parameters object

Responses

200 application/json

OK

POST /api/endpoint/action/unisolate

curl \
 --request POST 'https://<KIBANA_URL>/api/endpoint/action/unisolate' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"comment":"Benign process identified, releasing group","endpoint_ids":["9972d10e-4b9e-41aa-a534-a85e2a28ea42","bc0e4f0c-3bca-4633-9fee-156c0b505d16","fa89271b-b9d4-43f2-a684-307cffddeb5a"]}'

Request examples

{
  "comment": "Benign process identified, releasing group",
  "endpoint_ids": [
    "9972d10e-4b9e-41aa-a534-a85e2a28ea42",
    "bc0e4f0c-3bca-4633-9fee-156c0b505d16",
    "fa89271b-b9d4-43f2-a684-307cffddeb5a"
  ]
}

{
  "endpoint_ids": [
    "ed518850-681a-4d60-bb98-e22640cae2a8"
  ]
}

{
  "comment": "Remediation complete, restoring network",
  "case_ids": [
    "4976be38-c134-4554-bd5e-0fd89ce63667"
  ],
  "endpoint_ids": [
    "1aa1f8fd-0fb0-4fe4-8c30-92068272d3f0",
    "b30a11bf-1395-4707-b508-fbb45ef9793e"
  ]
}

Response examples (200)

{
  "data": {
    "id": "233db9ea-6733-4849-9226-5a7039c7161d",
    "agents": [
      "ed518850-681a-4d60-bb98-e22640cae2a8"
    ],
    "errors": [],
    "command": "suspend-process",
    "comment": "suspend the process",
    "outputs": {
      "ed518850-681a-4d60-bb98-e22640cae2a8": {
        "type": "json",
        "content": {
          "key": "value"
        }
      }
    },
    "agentType": "endpoint",
    "createdBy": "myuser",
    "isExpired": false,
    "startedAt": "2022-07-29T19:08:49.126Z",
    "parameters": {
      "entity_id": "abc123"
    },
    "completedAt": "2022-07-29T19:09:44.961Z",
    "isCompleted": true,
    "wasSuccessful": true
  },
  "action": "233db9ea-6733-4849-9226-5a7039c7161d"
}

Upload a file

POST /api/endpoint/action/upload

Upload a file to an endpoint.

multipart/form-data

Body Required

agent_type string

List of agent types to retrieve. Defaults to endpoint.

Values are endpoint, sentinel_one, crowdstrike, or microsoft_defender_endpoint.
alert_ids array[string(nonempty)]

A list of alerts ids.

At least 1 element. Minimum length of each is 1.
case_ids array[string]

Case IDs to be updated (cannot contain empty strings)

At least 1 element. Minimum length of each is 1.
comment string

Optional comment
endpoint_ids array[string] Required

List of endpoint IDs (cannot contain empty strings)

At least 1 element. Minimum length of each is 1.
parameters object Required

Optional parameters object
Hide parameters attribute Show parameters attribute object
- overwrite boolean
  
  Overwrite the file on the host if it already exists.
  
  Default value is false.
file string(binary) Required

The binary content of the file.

Responses

200 application/json

OK

POST /api/endpoint/action/upload

curl \
 --request POST 'https://<KIBANA_URL>/api/endpoint/action/upload' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: multipart/form-data" \
 --form "file=RWxhc3RpYw==" \
 --form 'parameters={}' \
 --form "endpoint_ids[]=ed518850-681a-4d60-bb98-e22640cae2a8"

Request example

{"file"=>"RWxhc3RpYw==", "parameters"=>{}, "endpoint_ids"=>["ed518850-681a-4d60-bb98-e22640cae2a8"]}

Response examples (200)

{
  "data": {
    "id": "9ff6aebc-2cb6-481e-8869-9b30036c9731",
    "hosts": {
      "ed518850-681a-4d60-bb98-e22640cae2a8": {
        "name": "Host-5i6cuc8kdv"
      }
    },
    "agents": [
      "ed518850-681a-4d60-bb98-e22640cae2a8"
    ],
    "status": "pending",
    "command": "upload",
    "outputs": {},
    "agentType": "endpoint",
    "createdBy": "elastic",
    "isExpired": false,
    "startedAt": "2023-07-03T15:07:22.837Z",
    "agentState": {
      "ed518850-681a-4d60-bb98-e22640cae2a8": {
        "isCompleted": false,
        "wasSuccessful": false
      }
    },
    "parameters": {
      "file_id": "10e4ce3d-4abb-4f93-a0cd-eaf63a489280",
      "file_name": "fix-malware.sh",
      "file_size": 69,
      "file_sha256": "a0bed94220193ba4895c0aa5b4e7e293381d15765cb164ddf7be5cdd010ae42a"
    },
    "isCompleted": false,
    "wasSuccessful": false
  }
}

Get a metadata list

GET /api/endpoint/metadata

Query parameters

page integer

Page number

Minimum value is 1. Default value is 1.
pageSize integer

Number of items per page

Minimum value is 1, maximum value is 100. Default value is 10.
kuery string

A KQL string.
hostStatuses array[string] Required

A set of agent health statuses to filter by.

Values are healthy, offline, updating, inactive, or unenrolled.
sortField string

Determines which field is used to sort the results.

Values are enrolled_at, metadata.host.hostname, host_status, metadata.Endpoint.policy.applied.name, metadata.Endpoint.policy.applied.status, metadata.host.os.name, metadata.host.ip, metadata.agent.version, or last_checkin.
sortDirection string

Determines the sort order.

Values are asc or desc.

Responses

200 application/json

OK

GET /api/endpoint/metadata

curl \
 --request GET 'https://<KIBANA_URL>/api/endpoint/metadata?hostStatuses=healthy&hostStatuses=updating' \
 --header "Authorization: $API_KEY"

Response examples (200)

{
  "data": [
    {
      "metadata": {
        "ecs": {
          "version": "1.11.0"
        },
        "host": {
          "id": "0cfead88e2024bd8a27476352b5ab264",
          "ip": [
            "127.0.0.1",
            "::1",
            "10.0.2.15",
            "fe80::2ac7:8e15:b957:2fa1"
          ],
          "os": {
            "Ext": {
              "variant": "Ubuntu"
            },
            "full": "Ubuntu 20.04.2",
            "name": "Linux",
            "type": "linux",
            "family": "ubuntu",
            "kernel": "5.8.0-59-generic #66~20.04.1-Ubuntu SMP Thu Jun 17 11:14:10 UTC 2021",
            "version": "20.04.2",
            "platform": "ubuntu"
          },
          "mac": [
            "08:00:27:e6:78:8b"
          ],
          "name": "david-Xubuntu",
          "hostname": "david-Xubuntu",
          "architecture": "x86_64"
        },
        "agent": {
          "id": "285297c6-3bff-4b83-9a07-f3e749801123",
          "type": "endpoint",
          "build": {
            "original": "version: 7.16.0, compiled: Tue Nov 16 16:00:00 2021, branch: 7.16, commit: 73a51033db85e0fb3be1c934697ef6a2b08979ab"
          },
          "version": "7.16.0"
        },
        "event": {
          "id": "MNtSXK/SkhEBnmgt++++++7S",
          "kind": "metric",
          "type": [
            "info"
          ],
          "action": "endpoint_metadata",
          "module": "endpoint",
          "created": "2023-07-04T15:47:57.432173535Z",
          "dataset": "endpoint.metadata",
          "category": [
            "host"
          ],
          "ingested": "2023-07-04T15:47:58Z",
          "sequence": 400,
          "agent_id_status": "verified"
        },
        "elastic": {
          "agent": {
            "id": "285297c6-3bff-4b83-9a07-f3e749801123"
          }
        },
        "message": "Endpoint metadata",
        "Endpoint": {
          "state": {
            "isolation": false
          },
          "policy": {
            "applied": {
              "id": "d5371dcd-93b7-4627-af88-4084f7d6aa3e",
              "name": "test",
              "status": "success",
              "version": "3",
              "endpoint_policy_version": "2"
            }
          },
          "status": "enrolled",
          "capabilities": [
            "isolation"
          ],
          "configuration": {
            "isolation": false
          }
        },
        "@timestamp": "2023-07-04T15:47:57.432173535Z",
        "data_stream": {
          "type": "metrics",
          "dataset": "endpoint.metadata",
          "namespace": "default"
        }
      },
      "host_status": "healthy",
      "policy_info": {
        "agent": {
          "applied": {
            "id": "ed7e3720-4bad-11ec-a2a8-fb22e62a5753",
            "revision": 0
          },
          "configured": {
            "id": "ed7e3720-4bad-11ec-a2a8-fb22e62a5753",
            "revision": 3
          }
        },
        "endpoint": {
          "id": "d5371dcd-93b7-4627-af88-4084f7d6aa3e",
          "revision": 2
        }
      },
      "last_checkin": "2023-07-04T15:47:57.432Z"
    },
    {
      "metadata": {
        "ecs": {
          "version": "1.11.0"
        },
        "host": {
          "id": "17d9cabc-7edd-43bc-bacb-8da5f5e6c0e5",
          "ip": [
            "10.0.2.15",
            "fe80::21a6:63d3:d70e:e3ad",
            "127.0.0.1",
            "::1"
          ],
          "os": {
            "Ext": {
              "variant": "Windows 10 Enterprise Evaluation"
            },
            "full": "Windows 10 Enterprise Evaluation 20H2 (10.0.19042.906)",
            "name": "Windows",
            "type": "windows",
            "family": "windows",
            "kernel": "20H2 (10.0.19042.906)",
            "version": "20H2 (10.0.19042.906)",
            "platform": "windows"
          },
          "mac": [
            "08:00:27:b1:1d:5a"
          ],
          "name": "WinDev2104Eval",
          "hostname": "WinDev2104Eval",
          "architecture": "x86_64"
        },
        "agent": {
          "id": "abb8a826-6812-448c-a571-6d8269b51449",
          "type": "endpoint",
          "build": {
            "original": "version: 7.16.0, compiled: Tue Nov 16 17:00:00 2021, branch: 7.16, commit: 73a51033db85e0fb3be1c934697ef6a2b08979ab"
          },
          "version": "7.16.0"
        },
        "event": {
          "id": "MNtRc++KoKHXXwlj+++++/N9",
          "kind": "metric",
          "type": [
            "info"
          ],
          "action": "endpoint_metadata",
          "module": "endpoint",
          "created": "2023-07-04T15:44:31.4917849Z",
          "dataset": "endpoint.metadata",
          "category": [
            "host"
          ],
          "ingested": "2023-07-04T15:44:33Z",
          "sequence": 5159,
          "agent_id_status": "verified"
        },
        "elastic": {
          "agent": {
            "id": "abb8a826-6812-448c-a571-6d8269b51449"
          }
        },
        "message": "Endpoint metadata",
        "Endpoint": {
          "state": {
            "isolation": false
          },
          "policy": {
            "applied": {
              "id": "d5371dcd-93b7-4627-af88-4084f7d6aa3e",
              "name": "test",
              "status": "success",
              "version": "3",
              "endpoint_policy_version": "2"
            }
          },
          "status": "enrolled",
          "capabilities": [
            "isolation"
          ],
          "configuration": {
            "isolation": false
          }
        },
        "@timestamp": "2023-07-04T15:44:31.4917849Z",
        "data_stream": {
          "type": "metrics",
          "dataset": "endpoint.metadata",
          "namespace": "default"
        }
      },
      "host_status": "healthy",
      "policy_info": {
        "agent": {
          "applied": {
            "id": "ed7e3720-4bad-11ec-a2a8-fb22e62a5753",
            "revision": 0
          },
          "configured": {
            "id": "ed7e3720-4bad-11ec-a2a8-fb22e62a5753",
            "revision": 3
          }
        },
        "endpoint": {
          "id": "d5371dcd-93b7-4627-af88-4084f7d6aa3e",
          "revision": 2
        }
      },
      "last_checkin": "2023-07-04T15:44:31.491Z"
    }
  ],
  "page": 0,
  "total": 2,
  "pageSize": 10,
  "sortField": "enrolled_at",
  "sortDirection": "desc"
}

Get metadata

GET /api/endpoint/metadata/{id}

Path parameters

id string Required

Responses

200 application/json

OK

GET /api/endpoint/metadata/{id}

curl \
 --request GET 'https://<KIBANA_URL>/api/endpoint/metadata/ed518850-681a-4d60-bb98-e22640cae2a8' \
 --header "Authorization: $API_KEY"

Response examples (200)

{
  "metadata": {
    "ecs": {
      "version": "1.11.0"
    },
    "host": {
      "id": "17d9cabc-7edd-43bc-bacb-8da5f5e6c0e5",
      "ip": [
        "10.0.2.15",
        "fe80::21a6:63d3:d70e:e3ad",
        "127.0.0.1",
        "::1"
      ],
      "os": {
        "Ext": {
          "variant": "Windows 10 Enterprise Evaluation"
        },
        "full": "Windows 10 Enterprise Evaluation 20H2 (10.0.19042.906)",
        "name": "Windows",
        "type": "windows",
        "family": "windows",
        "kernel": "20H2 (10.0.19042.906)",
        "version": "20H2 (10.0.19042.906)",
        "platform": "windows"
      },
      "mac": [
        "08:00:27:b1:1d:5a"
      ],
      "name": "WinDev2104Eval",
      "hostname": "WinDev2104Eval",
      "architecture": "x86_64"
    },
    "agent": {
      "id": "abb8a826-6812-448c-a571-6d8269b51449",
      "type": "endpoint",
      "build": {
        "original": "version: 7.16.0, compiled: Tue Nov 16 17:00:00 2021, branch: 7.16, commit: 73a51033db85e0fb3be1c934697ef6a2b08979ab"
      },
      "version": "7.16.0"
    },
    "event": {
      "id": "MNtRc++KoKHXXwlj+++++OhZ",
      "kind": "metric",
      "type": [
        "info"
      ],
      "action": "endpoint_metadata",
      "module": "endpoint",
      "created": "2023-07-04T15:48:57.3609346Z",
      "dataset": "endpoint.metadata",
      "category": [
        "host"
      ],
      "ingested": "2023-07-04T15:48:58Z",
      "sequence": 43757,
      "agent_id_status": "verified"
    },
    "elastic": {
      "agent": {
        "id": "abb8a826-6812-448c-a571-6d8269b51449"
      }
    },
    "message": "Endpoint metadata",
    "Endpoint": {
      "state": {
        "isolation": false
      },
      "policy": {
        "applied": {
          "id": "d5371dcd-93b7-4627-af88-4084f7d6aa3e",
          "name": "test",
          "status": "success",
          "version": "3",
          "endpoint_policy_version": "2"
        }
      },
      "status": "enrolled",
      "capabilities": [
        "isolation"
      ],
      "configuration": {
        "isolation": false
      }
    },
    "@timestamp": "2023-07-04T15:48:57.3609346Z",
    "data_stream": {
      "type": "metrics",
      "dataset": "endpoint.metadata",
      "namespace": "default"
    },
    "policy_info": {
      "agent": {
        "applied": {
          "id": "ed7e3720-4bad-11ec-a2a8-fb22e62a5753",
          "revision": 3
        },
        "configured": {
          "id": "ed7e3720-4bad-11ec-a2a8-fb22e62a5753",
          "revision": 3
        }
      },
      "endpoint": {
        "id": "d5371dcd-93b7-4627-af88-4084f7d6aa3e",
        "revision": 2
      }
    }
  },
  "host_status": "healthy",
  "last_checkin": "2023-07-04T15:48:57.360Z"
}

Get a policy response

GET /api/endpoint/policy_response

Query parameters

query object Required
Hide query attribute Show query attribute object
- agentId string
  
  Agent ID

Responses

200 application/json

OK

GET /api/endpoint/policy_response

curl \
 --request GET 'https://<KIBANA_URL>/api/endpoint/policy_response?query=%7B%7D' \
 --header "Authorization: $API_KEY"

Get a protection updates note

GET /api/endpoint/protection_updates_note/{package_policy_id}

Path parameters

package_policy_id string Required

Responses

200 application/json

OK
Hide response attribute Show response attribute object
- note string

GET /api/endpoint/protection_updates_note/{package_policy_id}

curl \
 --request GET 'https://<KIBANA_URL>/api/endpoint/protection_updates_note/{package_policy_id}' \
 --header "Authorization: $API_KEY"

Create or update a protection updates note

POST /api/endpoint/protection_updates_note/{package_policy_id}

Path parameters

package_policy_id string Required

application/json

Body Required

note string

Responses

200 application/json

OK
Hide response attribute Show response attribute object
- note string

POST /api/endpoint/protection_updates_note/{package_policy_id}

curl \
 --request POST 'https://<KIBANA_URL>/api/endpoint/protection_updates_note/{package_policy_id}' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"note":"string"}'

Get an asset criticality record

GET /api/asset_criticality

Get the asset criticality record for a specific entity.

Query parameters

id_value string Required

The ID value of the asset.
id_field string Required

The field representing the ID.

Values are host.name, user.name, service.name, or entity.id.

Responses

200 application/json

Successful response
Hide response attributes Show response attributes object
The deleted record if it existed.
- id_field string Required
  
  Values are host.name, user.name, service.name, or entity.id.
- id_value string Required
  
  The ID value of the asset.
- criticality_level string Required
  
  The criticality level of the asset.
  
  Values are low_impact, medium_impact, high_impact, or extreme_impact.
- asset object Required
  
  Hide asset attribute Show asset attribute object
  
  criticality string
  
  The criticality level of the asset.
  
  Values are low_impact, medium_impact, high_impact, or extreme_impact.
- host object
  
  Hide host attributes Show host attributes object
  
  asset object
  
  Hide asset attribute Show asset attribute object
  
  criticality string Required
  
  The criticality level of the asset.
  
  Values are low_impact, medium_impact, high_impact, or extreme_impact.
  
  name string Required
- service object
  
  Hide service attributes Show service attributes object
  
  asset object
  
  Hide asset attribute Show asset attribute object
  
  criticality string Required
  
  The criticality level of the asset.
  
  Values are low_impact, medium_impact, high_impact, or extreme_impact.
  
  name string Required
- user object
  
  Hide user attributes Show user attributes object
  
  asset object
  
  Hide asset attribute Show asset attribute object
  
  criticality string Required
  
  The criticality level of the asset.
  
  Values are low_impact, medium_impact, high_impact, or extreme_impact.
  
  name string Required
- @timestamp string(date-time) Required
  
  The time the record was created or updated.
400

Invalid request
404

Criticality record not found

GET /api/asset_criticality

curl \
 --request GET 'https://<KIBANA_URL>/api/asset_criticality?id_value=my_host&id_field=host.name' \
 --header "Authorization: $API_KEY"

Response examples (200)

{
  "host": {
    "name": "my_host",
    "asset": {
      "criticality": "high_impact"
    }
  },
  "asset": {
    "criticality": "high_impact"
  },
  "id_field": "host.name",
  "id_value": "my_host",
  "@timestamp": "2024-08-02T11:15:34.290Z",
  "criticality_level": "high_impact"
}

Upsert an asset criticality record

POST /api/asset_criticality

Create or update an asset criticality record for a specific entity.

If a record already exists for the specified entity, that record is overwritten with the specified value. If a record doesn't exist for the specified entity, a new record is created.

application/json

Body Required

id_field string Required

Values are host.name, user.name, service.name, or entity.id.
id_value string Required

The ID value of the asset.
criticality_level string Required

The criticality level of the asset.

Values are low_impact, medium_impact, high_impact, or extreme_impact.
refresh string

If 'wait_for' the request will wait for the index refresh.

Value is wait_for.

Responses

200 application/json

Successful response
Hide response attributes Show response attributes object
The deleted record if it existed.
- id_field string Required
  
  Values are host.name, user.name, service.name, or entity.id.
- id_value string Required
  
  The ID value of the asset.
- criticality_level string Required
  
  The criticality level of the asset.
  
  Values are low_impact, medium_impact, high_impact, or extreme_impact.
- asset object Required
  
  Hide asset attribute Show asset attribute object
  
  criticality string
  
  The criticality level of the asset.
  
  Values are low_impact, medium_impact, high_impact, or extreme_impact.
- host object
  
  Hide host attributes Show host attributes object
  
  asset object
  
  Hide asset attribute Show asset attribute object
  
  criticality string Required
  
  The criticality level of the asset.
  
  Values are low_impact, medium_impact, high_impact, or extreme_impact.
  
  name string Required
- service object
  
  Hide service attributes Show service attributes object
  
  asset object
  
  Hide asset attribute Show asset attribute object
  
  criticality string Required
  
  The criticality level of the asset.
  
  Values are low_impact, medium_impact, high_impact, or extreme_impact.
  
  name string Required
- user object
  
  Hide user attributes Show user attributes object
  
  asset object
  
  Hide asset attribute Show asset attribute object
  
  criticality string Required
  
  The criticality level of the asset.
  
  Values are low_impact, medium_impact, high_impact, or extreme_impact.
  
  name string Required
- @timestamp string(date-time) Required
  
  The time the record was created or updated.
400

Invalid request

POST /api/asset_criticality

curl \
 --request POST 'https://<KIBANA_URL>/api/asset_criticality' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"id_field":"host.name","id_value":"my_host","criticality_level":"high_impact"}'

Request example

{
  "id_field": "host.name",
  "id_value": "my_host",
  "criticality_level": "high_impact"
}

Response examples (200)

{
  "host": {
    "name": "my_host",
    "asset": {
      "criticality": "high_impact"
    }
  },
  "asset": {
    "criticality": "high_impact"
  },
  "id_field": "host.name",
  "id_value": "my_host",
  "@timestamp": "2024-08-02T11:15:34.290Z",
  "criticality_level": "high_impact"
}

Delete an asset criticality record

DELETE /api/asset_criticality

Delete the asset criticality record for a specific entity.

Query parameters

id_value string Required

The ID value of the asset.
id_field string Required

The field representing the ID.

Values are host.name, user.name, service.name, or entity.id.
refresh string

If 'wait_for' the request will wait for the index refresh.

Value is wait_for.

Responses

200 application/json

Successful response
Hide response attributes Show response attributes object
- deleted boolean Required
  
  True if the record was deleted or false if the record did not exist.
- record object
  
  The deleted record if it existed.
  
  Hide record attributes Show record attributes object
  
  id_field string Required
  
  Values are host.name, user.name, service.name, or entity.id.
  
  id_value string Required
  
  The ID value of the asset.
  
  criticality_level string Required
  
  The criticality level of the asset.
  
  Values are low_impact, medium_impact, high_impact, or extreme_impact.
  
  asset object Required
  
  Hide asset attribute Show asset attribute object
  
  criticality string
  
  The criticality level of the asset.
  
  Values are low_impact, medium_impact, high_impact, or extreme_impact.
  
  host object
  
  Hide host attributes Show host attributes object
  
  asset object
  
  Hide asset attribute Show asset attribute object
  
  criticality string Required
  
  The criticality level of the asset.
  
  Values are low_impact, medium_impact, high_impact, or extreme_impact.
  
  name string Required
  
  service object
  
  Hide service attributes Show service attributes object
  
  asset object
  
  Hide asset attribute Show asset attribute object
  
  criticality string Required
  
  The criticality level of the asset.
  
  Values are low_impact, medium_impact, high_impact, or extreme_impact.
  
  name string Required
  
  user object
  
  Hide user attributes Show user attributes object
  
  asset object
  
  Hide asset attribute Show asset attribute object
  
  criticality string Required
  
  The criticality level of the asset.
  
  Values are low_impact, medium_impact, high_impact, or extreme_impact.
  
  name string Required
  
  @timestamp string(date-time) Required
  
  The time the record was created or updated.
400

Invalid request

DELETE /api/asset_criticality

curl \
 --request DELETE 'https://<KIBANA_URL>/api/asset_criticality?id_value=my_host&id_field=host.name' \
 --header "Authorization: $API_KEY"

Bulk upsert asset criticality records

POST /api/asset_criticality/bulk

Bulk upsert up to 1000 asset criticality records.

If asset criticality records already exist for the specified entities, those records are overwritten with the specified values. If asset criticality records don't exist for the specified entities, new records are created.

application/json

Body

records array[object] Required

At least 1 but not more than 1000 elements.
Hide records attributes Show records attributes object
- id_field string Required
  
  Values are host.name, user.name, service.name, or entity.id.
- id_value string Required
  
  The ID value of the asset.
- criticality_level string Required
  
  The criticality level of the asset for bulk upload. The value unassigned is used to indicate that the criticality level is not assigned and is only used for bulk upload.
  
  Values are low_impact, medium_impact, high_impact, extreme_impact, or unassigned.

Responses

200 application/json

Bulk upload successful
Hide response attributes Show response attributes object
- errors array[object] Required
  
  Hide errors attributes Show errors attributes object
  
  index integer Required
  
  message string Required
- stats object Required
  
  Hide stats attributes Show stats attributes object
  
  failed integer Required
  
  successful integer Required
  
  total integer Required
413

File too large

POST /api/asset_criticality/bulk

curl \
 --request POST 'https://<KIBANA_URL>/api/asset_criticality/bulk' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"records":[{"id_field":"host.name","id_value":"host-1","criticality_level":"low_impact"},{"id_field":"host.name","id_value":"host-2","criticality_level":"medium_impact"}]}'

Request example

{
  "records": [
    {
      "id_field": "host.name",
      "id_value": "host-1",
      "criticality_level": "low_impact"
    },
    {
      "id_field": "host.name",
      "id_value": "host-2",
      "criticality_level": "medium_impact"
    }
  ]
}

Response examples (200)

{
  "stats": {
    "total": 2,
    "failed": 1,
    "successful": 1
  },
  "errors": [
    {
      "index": 0,
      "message": "Invalid ID field"
    }
  ]
}

List asset criticality records

GET /api/asset_criticality/list

List asset criticality records, paging, sorting and filtering as needed.

Query parameters

sort_field string

The field to sort by.

Values are id_value, id_field, criticality_level, or \@timestamp.
sort_direction string

The order to sort by.

Values are asc or desc.
page integer

The page number to return.

Minimum value is 1.
per_page integer

The number of records to return per page.

Minimum value is 1, maximum value is 1000.
kuery string

The kuery to filter by.

Responses

200 application/json

Successfully retrieved asset criticality records
Hide response attributes Show response attributes object
- page integer Required
  
  Minimum value is 1.
- per_page integer Required
  
  Minimum value is 1, maximum value is 1000.
- records array[object] Required
  
  The deleted record if it existed.
  
  Hide records attributes Show records attributes object
  
  The deleted record if it existed.
  
  id_field string Required
  
  Values are host.name, user.name, service.name, or entity.id.
  
  id_value string Required
  
  The ID value of the asset.
  
  criticality_level string Required
  
  The criticality level of the asset.
  
  Values are low_impact, medium_impact, high_impact, or extreme_impact.
  
  asset object Required
  
  Hide asset attribute Show asset attribute object
  
  criticality string
  
  The criticality level of the asset.
  
  Values are low_impact, medium_impact, high_impact, or extreme_impact.
  
  host object
  
  Hide host attributes Show host attributes object
  
  asset object
  
  Hide asset attribute Show asset attribute object
  
  criticality string Required
  
  The criticality level of the asset.
  
  Values are low_impact, medium_impact, high_impact, or extreme_impact.
  
  name string Required
  
  service object
  
  Hide service attributes Show service attributes object
  
  asset object
  
  Hide asset attribute Show asset attribute object
  
  criticality string Required
  
  The criticality level of the asset.
  
  Values are low_impact, medium_impact, high_impact, or extreme_impact.
  
  name string Required
  
  user object
  
  Hide user attributes Show user attributes object
  
  asset object
  
  Hide asset attribute Show asset attribute object
  
  criticality string Required
  
  The criticality level of the asset.
  
  Values are low_impact, medium_impact, high_impact, or extreme_impact.
  
  name string Required
  
  @timestamp string(date-time) Required
  
  The time the record was created or updated.
- total integer Required
  
  Minimum value is 0.

GET /api/asset_criticality/list

curl \
 --request GET 'https://<KIBANA_URL>/api/asset_criticality/list' \
 --header "Authorization: $API_KEY"

Response examples (200)

{
  "page": 1,
  "total": 2,
  "records": [
    {
      "host": {
        "name": "my_other_host",
        "asset": {
          "criticality": "medium_impact"
        }
      },
      "asset": {
        "criticality": "medium_impact"
      },
      "id_field": "host.name",
      "id_value": "my_other_host",
      "@timestamp": "2024-08-02T14:40:35.705Z",
      "criticality_level": "medium_impact"
    },
    {
      "host": {
        "name": "my_host",
        "asset": {
          "criticality": "high_impact"
        }
      },
      "asset": {
        "criticality": "high_impact"
      },
      "id_field": "host.name",
      "id_value": "my_host",
      "@timestamp": "2024-08-02T11:15:34.290Z",
      "criticality_level": "high_impact"
    }
  ],
  "per_page": 10
}

Initialize the Privilege Monitoring Engine

POST /api/entity_analytics/monitoring/engine/init

Responses

200 application/json

Successful response
Hide response attribute Show response attribute object
- status string Required
  
  Values are installing, started, stopped, updating, or error.

POST /api/entity_analytics/monitoring/engine/init

curl \
 --request POST 'https://<KIBANA_URL>/api/entity_analytics/monitoring/engine/init' \
 --header "Authorization: $API_KEY"

Health check on Privilege Monitoring

GET /api/entity_analytics/monitoring/privileges/health

Responses

200 application/json

Successful response
Hide response attribute Show response attribute object
- ok boolean

GET /api/entity_analytics/monitoring/privileges/health

curl \
 --request GET 'https://<KIBANA_URL>/api/entity_analytics/monitoring/privileges/health' \
 --header "Authorization: $API_KEY"

Initialize the Entity Store

POST /api/entity_store/enable

application/json

Body Required

Schema for the entity store initialization

delay string

The delay before the transform will run.

Format should match the following pattern: [smdh]$. Default value is 1m.
docsPerSecond integer

The number of documents per second to process.
enrichPolicyExecutionInterval string

Interval in which enrich policy runs. For example, "1h" means the rule runs every hour. Must be less than or equal to half the duration of the lookback period,

Format should match the following pattern: ^[1-9]\d*[smh]$.
entityTypes array[string]

Values are user, host, service, or generic.
fieldHistoryLength integer

The number of historical values to keep for each field.

Default value is 10.
filter string
frequency string

The frequency at which the transform will run.

Format should match the following pattern: [smdh]$. Default value is 1m.
indexPattern string
lookbackPeriod string

The amount of time the transform looks back to calculate the aggregations.

Format should match the following pattern: [smdh]$. Default value is 24h.
timeout string

The timeout for initializing the aggregating transform.

Format should match the following pattern: [smdh]$. Default value is 180s.
timestampField string

The field to use as the timestamp.

Default value is @timestamp.

Responses

200 application/json

Successful response
Hide response attributes Show response attributes object
- engines array[object]
  
  Hide engines attributes Show engines attributes object
  
  delay string
  
  Format should match the following pattern: [smdh]$. Default value is 1m.
  
  docsPerSecond integer
  
  error object
  
  Hide error attributes Show error attributes object
  
  action string Required
  
  Value is init.
  
  message string Required
  
  fieldHistoryLength integer Required
  
  filter string
  
  frequency string
  
  Format should match the following pattern: [smdh]$. Default value is 1m.
  
  indexPattern string Required
  
  lookbackPeriod string
  
  Format should match the following pattern: [smdh]$. Default value is 24h.
  
  status string Required
  
  Values are installing, started, stopped, updating, or error.
  
  timeout string
  
  Format should match the following pattern: [smdh]$. Default value is 180s.
  
  timestampField string
  
  type string Required
  
  Values are user, host, service, or generic.
- succeeded boolean
400

Invalid request

POST /api/entity_store/enable

curl \
 --request POST 'https://<KIBANA_URL>/api/entity_store/enable' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"delay":"1m","docsPerSecond":42,"enrichPolicyExecutionInterval":"1h","entityTypes":["user"],"fieldHistoryLength":10,"filter":"string","frequency":"1m","indexPattern":"string","lookbackPeriod":"24h","timeout":"180s","timestampField":"@timestamp"}'

List the Entity Engines

GET /api/entity_store/engines

Responses

200 application/json

Successful response
Hide response attributes Show response attributes object
- count integer
- engines array[object]
  
  Hide engines attributes Show engines attributes object
  
  delay string
  
  Format should match the following pattern: [smdh]$. Default value is 1m.
  
  docsPerSecond integer
  
  error object
  
  Hide error attributes Show error attributes object
  
  action string Required
  
  Value is init.
  
  message string Required
  
  fieldHistoryLength integer Required
  
  filter string
  
  frequency string
  
  Format should match the following pattern: [smdh]$. Default value is 1m.
  
  indexPattern string Required
  
  lookbackPeriod string
  
  Format should match the following pattern: [smdh]$. Default value is 24h.
  
  status string Required
  
  Values are installing, started, stopped, updating, or error.
  
  timeout string
  
  Format should match the following pattern: [smdh]$. Default value is 180s.
  
  timestampField string
  
  type string Required
  
  Values are user, host, service, or generic.

GET /api/entity_store/engines

curl \
 --request GET 'https://<KIBANA_URL>/api/entity_store/engines' \
 --header "Authorization: $API_KEY"

Get an Entity Engine

GET /api/entity_store/engines/{entityType}

Path parameters

entityType string Required

The entity type of the engine (either 'user' or 'host').

Values are user, host, service, or generic.

Responses

200 application/json

Successful response
Hide response attributes Show response attributes object
- delay string
  
  Format should match the following pattern: [smdh]$. Default value is 1m.
- docsPerSecond integer
- error object
  
  Hide error attributes Show error attributes object
  
  action string Required
  
  Value is init.
  
  message string Required
- fieldHistoryLength integer Required
- filter string
- frequency string
  
  Format should match the following pattern: [smdh]$. Default value is 1m.
- indexPattern string Required
- lookbackPeriod string
  
  Format should match the following pattern: [smdh]$. Default value is 24h.
- status string Required
  
  Values are installing, started, stopped, updating, or error.
- timeout string
  
  Format should match the following pattern: [smdh]$. Default value is 180s.
- timestampField string
- type string Required
  
  Values are user, host, service, or generic.

GET /api/entity_store/engines/{entityType}

curl \
 --request GET 'https://<KIBANA_URL>/api/entity_store/engines/{entityType}' \
 --header "Authorization: $API_KEY"

Delete the Entity Engine

DELETE /api/entity_store/engines/{entityType}

Path parameters

entityType string Required

The entity type of the engine (either 'user' or 'host').

Values are user, host, service, or generic.

Query parameters

data boolean

Control flag to also delete the entity data.

Responses

200 application/json

Successful response
Hide response attribute Show response attribute object
- deleted boolean

DELETE /api/entity_store/engines/{entityType}

curl \
 --request DELETE 'https://<KIBANA_URL>/api/entity_store/engines/{entityType}' \
 --header "Authorization: $API_KEY"

Initialize an Entity Engine

POST /api/entity_store/engines/{entityType}/init

Path parameters

entityType string Required

The entity type of the engine (either 'user' or 'host').

Values are user, host, service, or generic.

application/json

Body Required

Schema for the engine initialization

delay string

The delay before the transform will run.

Format should match the following pattern: [smdh]$. Default value is 1m.
docsPerSecond integer

The number of documents per second to process.
enrichPolicyExecutionInterval string

Interval in which enrich policy runs. For example, "1h" means the rule runs every hour. Must be less than or equal to half the duration of the lookback period,

Format should match the following pattern: ^[1-9]\d*[smh]$.
fieldHistoryLength integer

The number of historical values to keep for each field.

Default value is 10.
filter string
frequency string

The frequency at which the transform will run.

Format should match the following pattern: [smdh]$. Default value is 1m.
indexPattern string
lookbackPeriod string

The amount of time the transform looks back to calculate the aggregations.

Format should match the following pattern: [smdh]$. Default value is 24h.
timeout string

The timeout for initializing the aggregating transform.

Format should match the following pattern: [smdh]$. Default value is 180s.
timestampField string

The field to use as the timestamp for the entity type.

Default value is @timestamp.

Responses

200 application/json

Successful response
Hide response attributes Show response attributes object
- delay string
  
  Format should match the following pattern: [smdh]$. Default value is 1m.
- docsPerSecond integer
- error object
  
  Hide error attributes Show error attributes object
  
  action string Required
  
  Value is init.
  
  message string Required
- fieldHistoryLength integer Required
- filter string
- frequency string
  
  Format should match the following pattern: [smdh]$. Default value is 1m.
- indexPattern string Required
- lookbackPeriod string
  
  Format should match the following pattern: [smdh]$. Default value is 24h.
- status string Required
  
  Values are installing, started, stopped, updating, or error.
- timeout string
  
  Format should match the following pattern: [smdh]$. Default value is 180s.
- timestampField string
- type string Required
  
  Values are user, host, service, or generic.
400

Invalid request

POST /api/entity_store/engines/{entityType}/init

curl \
 --request POST 'https://<KIBANA_URL>/api/entity_store/engines/{entityType}/init' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"delay":"1m","docsPerSecond":42,"enrichPolicyExecutionInterval":"1h","fieldHistoryLength":10,"filter":"string","frequency":"1m","indexPattern":"string","lookbackPeriod":"24h","timeout":"180s","timestampField":"@timestamp"}'

Start an Entity Engine

POST /api/entity_store/engines/{entityType}/start

Path parameters

entityType string Required

The entity type of the engine

Values are user, host, service, or generic.

Responses

200 application/json

Successful response
Hide response attribute Show response attribute object
- started boolean

POST /api/entity_store/engines/{entityType}/start

curl \
 --request POST 'https://<KIBANA_URL>/api/entity_store/engines/{entityType}/start' \
 --header "Authorization: $API_KEY"

Stop an Entity Engine

POST /api/entity_store/engines/{entityType}/stop

Path parameters

entityType string Required

The entity type of the engine (either 'user' or 'host').

Values are user, host, service, or generic.

Responses

200 application/json

Successful response
Hide response attribute Show response attribute object
- stopped boolean

POST /api/entity_store/engines/{entityType}/stop

curl \
 --request POST 'https://<KIBANA_URL>/api/entity_store/engines/{entityType}/stop' \
 --header "Authorization: $API_KEY"