Architecture

The Alerting plugin runs inside the Wazuh Indexer as an OpenSearch plugin. It schedules monitors that query indices, evaluates trigger conditions against the results, and executes actions (typically sending notifications) when conditions are met.

Core Concepts

The alerting pipeline follows a linear flow:

1. A Monitor runs on a schedule, executing a query against one or more indices.
2. The query results are evaluated against one or more Triggers — boolean conditions that determine whether an alert should fire.
3. When a trigger condition is met, the monitor executes its configured Actions — typically sending a notification through the Notifications plugin.
4. An Alert record is created to track the triggered condition through its lifecycle.
5. For document-level monitors, Findings record which specific documents matched the trigger.

Monitor Types

Active Response Monitor Constraints

The Active Response monitor type enforces stricter validation than standard document-level monitors:

• Indices must match the wazuh-findings-v5-* prefix.
• Schedule interval cannot exceed 60,000 milliseconds (1 minute).
• Only DocumentLevelTrigger is accepted — other trigger types are rejected.

Triggers

Each monitor type uses a corresponding trigger type:

• QueryLevelTrigger: Evaluates a script condition against the full query response. The script has access to the query results, aggregations, and monitor metadata.
• BucketLevelTrigger: Evaluates a condition per aggregation bucket. Supports composite aggregations for paginating through large result sets.
• DocumentLevelTrigger: Defines per-document matching conditions using query DSL. Documents that match the trigger’s queries generate findings.
• ChainedAlertTrigger: Evaluates a condition over the alerts produced by the delegate monitors of a composite (workflow) monitor, allowing alerts to fire based on combinations of upstream monitor results.

Cluster metrics monitors reuse QueryLevelTrigger, evaluating a script condition against the cluster API response.

Actions

Actions define what happens when a trigger fires. Each action specifies:

• A destination — a notification channel configured in the Notifications plugin (Slack, email, webhook, etc.).
• A message template — a Mustache template that formats the alert details into the notification body.
• An optional throttle — a minimum interval between repeated notifications for the same alert (up to plugins.alerting.action_throttle_max_value, default 24 hours).

When a trigger fires, the plugin calls the Notifications plugin via its internal transport interface to deliver the message.

Alert Lifecycle

Alerts transition through the following states:

Findings

Document-level monitors produce findings — records of individual documents that matched the monitor’s trigger conditions. Each finding contains:

• The matching document IDs and source index.
• The queries (rules) that matched.
• A timestamp of when the match was detected.

Findings are stored in rolling indices (.opensearch-alerting-finding-history-*) with a default retention of 30 days.

These raw alerting findings are not the same as the findings surfaced in the Wazuh context. Detectors managed by the Security Analytics plugin run on document-level monitors internally, but produce their own enriched findings — augmented with the full event payload and rule metadata — which are written to wazuh-findings-v5-* indices. A plain document-level monitor only produces the raw findings described above; it does not perform this enrichment.

Workflows

Workflows chain multiple monitors into a composite execution unit. A workflow defines an ordered sequence of monitors (delegates) that run together. This enables multi-stage detection scenarios where the output of one monitor informs the next.

Workflows have their own CRUD API and can be executed, searched, and managed independently of individual monitors.

Alerting Indices

The plugin manages the following system indices:

Rollover periods and retention are configurable through plugin settings.