Loading

Detection rule concepts

Before creating detection rules, familiarize yourself with the foundational concepts that apply across all rule types. Understanding these concepts helps you design effective rules and troubleshoot issues when they arise.

A detection rule consists of three parts:

Part Purpose
Query Specifies the threat behavior or pattern to detect. The query searches your data sources using syntax that varies by rule type (KQL, EQL, machine learning anomaly scores, or threat indicator matches).
Schedule Controls when and how often the rule checks for matching events. Rules execute at intervals you define (for example, every 5 minutes) and look back over a configurable time window.
Rule actions Specifies what happens when the rule detects a match. You can send notifications, create tickets, or trigger integrations with external systems.

These three parts work together when a rule runs:

  1. At each scheduled interval, the rule runs its query against your data sources.
  2. The rule creates alerts for events that match the query (unless exceptions exceptions apply).
  3. Configured rule actions notify your team or trigger external integrations.

Behind the scenes, rules execute using the authorization of the user who last edited them.

A rule's query runs against the data sources you configure. When you create a rule (except for machine learning rules, which use anomaly jobs), you specify either:

  • Index patterns: Wildcards like logs-* or filebeat-* that match one or more indices.
  • Data views: Named references to index patterns that can include runtime fields for computed values at query time.

Data views are useful when you need consistent field definitions across multiple rules or want to add fields without reindexing data. For guidance on configuring rule data sources, refer to Set rule data sources.

Note

To use data views in Elastic Stack, you must have the required permissions. In Serverless, you must have the appropriate predefined Security user role or a custom role with the right privileges.

Important

System indices, such as the alert indices, contain important configuration and internal data. Do not change their mappings. Changes can lead to rule execution and alert indexing failures. Use runtime fields instead to add fields to existing alert and event documents.

Exceptions refine a rule's query by excluding specific conditions from generating alerts—even when the query criteria are met. Use exceptions to:

  • Exclude trusted processes, IP addresses, or user accounts
  • Filter out known-benign activity specific to your environment
  • Reduce alert noise without modifying the rule's query logic

Exceptions can be scoped to a single rule or shared across multiple rules using shared exception lists. You can add exceptions to all rule types.

Rule actions are automated responses that a rule triggers when it generates alerts. Each action uses a connector to send data to an external service. Common action types include:

  • Sending notifications (Slack messages, emails, PagerDuty alerts) to inform your team in real time

    Note

    Notifications are a specific type of action focused on alerting people. They're how rules communicate that something needs attention.

  • Creating tickets in Jira or ServiceNow for tracking and triage

  • Triggering webhooks or custom integrations for automated workflows

You can configure rule actions to run for every alert, at scheduled intervals, or only when alerts meet specific conditions (such as high severity). Rule actions are configured in the Actions tab of the rule settings. For details, refer to Rule actions.

Rules run in the background using the privileges of the user who last edited them. When you create or modify a rule, Elastic Security generates an API key that captures a snapshot of your current privileges. The rule uses this API key to:

  • Execute detection queries against the configured data sources
  • Write alerts to the alerts index
  • Execute actions (send notifications)

This means rules continue running with their editor's privileges, even when that user is not logged in.

Important

If a user without the required privileges (such as index read access) updates a rule, the rule stops functioning. Ensure that only users with appropriate access edit rules. For required privileges, refer to Detections privileges.

Rule actions
Automated responses a rule triggers when it generates alerts. Rule actions use connectors to send data to external services.
Alerts
Records created when a rule's query finds matching events. Each alert represents a potential threat for analysts to investigate.
API key
A credential that captures the privileges of the user who last edited a rule. Rules use API keys to execute queries and write alerts.
Connectors
Integrations that connect actions to external services like Slack, Jira, or PagerDuty.
Data sources
The Elasticsearch indices or data views that a rule's query searches. Configured using index patterns or data views.
Data views
Named references to index patterns that can include runtime fields. Useful for consistent field definitions across rules.
Exceptions
Conditions that prevent a rule from generating alerts, even when query criteria are met. Used to exclude trusted activity.
Index patterns
Wildcards (like logs-*) that match one or more Elasticsearch indices.
Notifications
A type of action that alerts people to something needing attention (Slack messages, emails, PagerDuty alerts).
Query
The logic that defines what threat behavior or pattern a rule detects. Syntax varies by rule type.
Rule authorization
The privilege model that determines what a rule can access. Rules execute using an API key tied to the user who last edited them.
Rule type
The detection method a rule uses (custom query, EQL, threshold, indicator match, new terms, ES|QL, or machine learning).
Schedule
How often a rule runs and how far back it looks for matching events.