Security Analytics module

Finding workflow

When the Security Analytics module receives an event from a Wazuh manager, it performs the following actions:

1. Evaluates the event against active Sigma rules for the corresponding log category.

2. Creates a raw finding if a rule match occurs.

3. Executes the correlation engine.

4. Retrieves the triggering event and associated rule metadata.

5. Creates an enriched finding and stores it in the findings index.

Settings reference

All settings use the plugins.security_analytics prefix shown in the examples below.

History indices

Each history group (alerts, findings, correlations) is managed by an independent rollover job with the same five controls:

To tune retention for the alert history indices in the /etc/wazuh-indexer/opensearch.yml file:

plugins.security_analytics.alert_history_enabled: true
plugins.security_analytics.alert_history_rollover_period: 12h
plugins.security_analytics.alert_history_max_age: 30d
plugins.security_analytics.alert_history_max_docs: 1000
plugins.security_analytics.alert_history_retention_period: 60d

The table below summarizes the Security Analytics history-index settings for alerts, findings, and correlations, highlighting differences in available controls and configuration names:

Correlation tuning

The correlation engine runs after every matched finding and consults two in-memory caches plus a concurrency limiter. The following blocks in the /etc/wazuh-indexer/opensearch.yml file are responsible for correlation tuning:

plugins.security_analytics.correlation_time_window: 5m
plugins.security_analytics.auto_correlations_enabled: false
plugins.security_analytics.correlation.detector_cache_ttl: 5m
plugins.security_analytics.correlation.metadata_cache_ttl: 5m
plugins.security_analytics.correlation.max_in_flight_findings: 50

Both detector_cache_ttl and metadata_cache_ttl accept 0s to disable the cache entirely, which forces a lookup against the corresponding system index on every finding. Lower correlation.max_in_flight_findings on resource-constrained nodes to bound peak demand on the search thread pool.

Detector behavior

plugins.security_analytics.enable_detectors_with_dedicated_query_indices: true
plugins.security_analytics.enriched_findings_index_enabled: true
plugins.security_analytics.enable_workflow_usage: true
plugins.security_analytics.filter_by_backend_roles: false

Updating a setting at runtime

In the curl examples on this page, replace <WAZUH_INDEXER_USERNAME> and <WAZUH_INDEXER_PASSWORD> with the credentials of a Wazuh indexer user that has the permissions the request needs, such as admin. The admin password is the WAZUH_INDEXER_ADMIN_PASSWORD value in /etc/wazuh-indexer/export/credentials.env of a Wazuh indexer node, or in the credentials.env file of wazuh-install-files.tar. Replace <WAZUH_INDEXER_IP> with the IP address of the Wazuh indexer node.

Almost every Security Analytics setting is dynamic. To change one without restarting the node, use the Cluster Settings API:

curl -sk -u <WAZUH_INDEXER_USERNAME>:<WAZUH_INDEXER_PASSWORD> -X PUT "https://<WAZUH_INDEXER_IP>:9200/_cluster/settings" \
  -H 'Content-Type: application/json' -d '{
  "persistent": {
    "plugins.security_analytics.correlation.max_in_flight_findings": 100
  }
}'

Output

{"acknowledged":true,"persistent":{"plugins":{"security_analytics":{"correlation":{"max_in_flight_findings":"100"}}}},"transient":{}}

Case fields

Case information is stored under the wazuh.case field in enriched findings.

The following case statuses are supported:

Updating findings

You can update case information using the Security Analytics findings update API.

Request

PUT /_plugins/_security_analytics/findings/_update

The request body contains one or more findings to update.

{
  "findings": [
    {
      "_id": "<finding-document-id>",
      "_index": "<finding-index-name>",
      "case": {
        "status": "acknowledged",
        "comments": [
          {
            "comment": "Reviewed by SOC analyst",
            "author": "<ANALYST_NAME>"
          }
        ],
        "tags": ["critical", "reviewed"]
      }
    }
  ]
}

All fields within the case object are optional. Updates are applied as partial updates and only the supplied fields are modified. The comments array replaces the stored comments. To add a comment, send the existing comments with the new one. A request can update up to 10 findings by default, set by plugins.security_analytics.max_case_management_bulk_size.

Response codes

Investigation workflow

A typical investigation workflow consists of the following stages:

1. A Sigma rule matches an event and creates a finding.

2. An analyst reviews the finding and changes its status to acknowledged.

3. The analyst adds investigation notes and tags to the case.

4. The finding status is updated to completed when the investigation is finished.

Case management operations are typically performed through the Wazuh dashboard, which automatically manages user attribution and timestamps.

Querying findings by status

You can filter findings using the wazuh.case.status field.

The following example returns all acknowledged findings. Replace <WAZUH_INDEXER_IP> with the IP address of the Wazuh indexer node.

curl -k -u <WAZUH_INDEXER_USERNAME>:<WAZUH_INDEXER_PASSWORD> -X GET "https://<WAZUH_INDEXER_IP>:9200/wazuh-findings-v5-*/_search" \
  -H "Content-Type: application/json" \
  -d '{
  "query": {
    "term": {
      "wazuh.case.status": {
        "value": "acknowledged"
      }
    }
  }
}'