Alerting module

Query-level monitors

Query-level monitors execute a search query against one or more indices and evaluate the query results as a whole. They are best suited for detecting conditions based on aggregated search results, where a single alert represents the outcome of the entire query. These monitors use the QueryLevelTrigger trigger type with a SearchInput data source.

Common use cases include:

• Detecting an excessive number of authentication failures.

• Monitoring application error rates.

• Identifying abnormal event volumes.

• Tracking threshold-based operational metrics.

Bucket-level monitors

Bucket-level monitors evaluate aggregation buckets rather than individual search results. Each bucket can generate its own alert, making this monitor type suitable for monitoring individual hosts, users, services, applications, or other grouped entities. Bucket-level monitors use the BucketLevelTrigger trigger type with a SearchInput data source that includes aggregations.

Common use cases include:

• Monitoring authentication failures per host.

• Detecting excessive network activity by users.

• Identifying the top systems generating security events.

• Monitoring threshold violations across grouped resources.

Cluster metrics monitors

Cluster metrics monitors evaluate the health and operational status of the Wazuh indexer cluster instead of indexed data. Rather than executing search queries, these monitors periodically call cluster APIs, such as cluster health and cluster statistics, and evaluate the responses against configured trigger conditions. Cluster metrics monitors use the QueryLevelTrigger trigger type with a ClusterMetricsInput data source.

Common use cases include:

• Monitoring cluster health.

• Detecting unavailable nodes.

• Monitoring pending cluster tasks.

• Tracking cluster performance and resource utilization.

Document-level monitors

Document-level monitors evaluate individual documents as they are indexed. When a document matches the configured conditions, the monitor generates a finding that records the matching document, query, and timestamp. Findings provide traceability and support investigation workflows. Document-level monitors use the DocumentLevelTrigger trigger type with a DocLevelMonitorInput data source.

These monitors are commonly used for:

• Security detections.

• Compliance monitoring.

• Event correlation.

• Threat detection workflows.

Active Response monitors

Active Response monitors extend document-level monitoring to support automated response workflows within Wazuh. When trigger conditions are met, the monitor generates execution requests that are written to the wazuh-active-responses data stream. The Wazuh manager retrieves these requests and distributes the corresponding Active Response actions to managed agents. Active Response monitors use the DocumentLevelTrigger trigger type with a DocLevelMonitorInput data source.

Active Response monitors have the following requirements:

Common use cases include:

• Blocking malicious IP addresses.

• Terminating malicious processes.

• Disabling compromised accounts.

• Executing custom response actions on affected endpoints.

Triggers

A trigger defines the condition that determines whether a monitor generates an alert. Each monitor contains one or more triggers that evaluate the monitor results against user-defined conditions.

When a monitor runs, the trigger processes the monitor output and determines whether the configured conditions have been met. If a trigger evaluates to true, the Alerting module creates an alert and executes any associated actions.

The Alerting module supports the following trigger types.

Query-level triggers

Query-level triggers evaluate the complete results of a search query or cluster metrics request. These triggers use a Painless script to evaluate the query response, including search results, aggregations, and monitor metadata. An alert is generated when the script evaluates to true.

Query-level triggers are supported by Query-level monitors and Cluster metrics monitors.

Bucket-level triggers

Bucket-level triggers evaluate each aggregation bucket returned by a bucket-level monitor. Rather than evaluating the entire query result, each bucket is processed independently. A separate alert can be generated for every bucket that satisfies the configured condition.

This trigger type supports composite aggregations, allowing large result sets to be processed efficiently across multiple execution cycles. Bucket-level triggers are supported only by bucket-level monitors.

Document-level triggers

Document-level triggers evaluate individual documents using OpenSearch Query DSL and percolate queries. When a document matches the configured conditions, the monitor generates a finding that records the matching document. If configured, the monitor also generates an alert and executes the associated actions. Document-level triggers are supported by Document-level monitors and Active Response monitors.

Chained alert triggers

Chained alert triggers evaluate the alerts generated by monitors that participate in a workflow. Instead of evaluating indexed data directly, these triggers evaluate the results produced by other monitors. This enables multi-stage detection scenarios in which alerts are generated only after multiple monitoring conditions have been satisfied.

Chained alert triggers are used internally by workflows and are not configured independently.

Findings and Security Analytics

The findings created by the Alerting module are different from the findings displayed by the Wazuh Security Analytics module.

Alerting findings contain the raw results generated by document-level monitors and are stored in the .opensearch-alerting-finding-history-* indices.

Security Analytics builds on this functionality by using document-level monitors internally to evaluate events against Sigma detection rules. When a rule matches, Security Analytics enriches the resulting findings with additional event data and rule metadata before storing them in the wazuh-findings-v5-* indices.

This enrichment provides additional context for investigation and enables downstream workflows such as Active Response.

The following table summarizes the differences between the two finding types.

How workflows work

A workflow consists of one or more monitors that execute according to their configured schedules.

Each monitor evaluates its own data source and generates alerts independently. The workflow then evaluates the combined results of those monitors to determine whether to run additional actions.

This approach enables the Alerting module to evaluate relationships between alerts generated by different monitors rather than relying on a single monitor execution.

Workflow management

Workflows are managed independently of individual monitors and support the same lifecycle operations.

You can use the Alerting API to:

• Create workflows.

• Retrieve workflow configurations.

• Update existing workflows.

• Delete workflows.

• Execute workflows on demand.

The Wazuh dashboard also provides an interface for creating, managing, and monitoring workflows.

Security Analytics

The Security Analytics module uses alerting monitors to evaluate incoming events against Sigma detection rules.

When an event matches a detection rule, Security Analytics creates a finding and can generate an alert. Alerting monitors drive this process by periodically querying newly indexed events and evaluating them against configured detectors.

This integration enables Security Analytics to leverage the Alerting framework for rule execution, alert generation, and lifecycle management while enriching findings with additional detection context.

Notifications

The Alerting module integrates with the Notifications module to deliver alert notifications to external communication platforms and services.

When a trigger condition is met, the Alerting module executes one or more configured actions. Notification actions are forwarded to the Notifications module, which delivers messages using the configured notification channel.

Supported notification destinations include:

• Slack

• Microsoft Teams

• Amazon Chime

• Email

• Webhooks

• Amazon SNS

• PagerDuty

• Jira

• Shuffle

This integration allows the Alerting module to focus on evaluating monitoring conditions while the Notifications module manages message formatting, delivery, and channel-specific communication.

Active Response

The Alerting module includes a Wazuh-specific Active Response monitor type for automated response workflows.

When an Active Response monitor is triggered, it writes execution requests to the wazuh-active-responses data stream. The Wazuh manager retrieves these requests and distributes the corresponding Active Response actions to agents. Each execution request contains a reference to the event that triggered the response.

Active Response monitors have the following requirements:

Monitor settings

Monitor settings control how the Alerting module creates, executes, and manages monitors. These settings define operational limits and configure the behavior of document-level monitors.

Timeout settings

Timeout settings define how long the Alerting module waits for queries, indexing operations, and bulk requests before cancelling the operation.

Alert history settings

Alert history settings control how alert records are stored, rolled over, and retained. These settings help manage the size of alert history indices while ensuring that historical alerts remain available for investigation and auditing.

Finding history settings

Finding history settings control how findings generated by document-level and Active Response monitors are stored and retained. These settings determine whether findings are indexed, when finding history indices are rolled over, and how long historical findings remain available for analysis.

Comment settings

Comment settings control the management and retention of comments added to alerts. These settings determine whether comments are enabled, define storage limits, and configure the retention and rollover of comment history indices.

General settings

General settings control module-wide behavior, including role-based access control, action throttling, and cross-cluster monitoring.

Update dynamic settings

Most Alerting module settings can be updated dynamically without restarting the Wazuh indexer. Use the Cluster Settings API to apply persistent or transient settings.

The following example updates two Alerting module settings:

• plugins.alerting.monitor.max_monitors: Increases the maximum number of monitors a user can create to 20.

• plugins.alerting.alert_history_max_age: Extends the maximum age of alert history indices to 60d.

Run the following command from a terminal on a host that can communicate with the Wazuh indexer REST API.

curl -sk -u <USERNAME>:<PASSWORD> -X PUT \
  "https://localhost:9200/_cluster/settings" \
  -H "Content-Type: application/json" \
  -d '{
  "persistent": {
    "plugins.alerting.monitor.max_monitors": 20,
    "plugins.alerting.alert_history_max_age": "60d"
  }
}'

Output

{
  "acknowledged": true,
  "persistent": {
    "plugins": {
      "alerting": {
        "monitor": {
          "max_monitors": "20"
        },
        "alert_history_max_age": "60d"
      }
    }
  },
  "transient": {}
}

The acknowledged value confirms that the Wazuh indexer accepted the settings update. The updated values appear under the persistent section, which means they remain in effect after the Wazuh indexer restarts.