Elasticsearch Audit Logging

Enable and configure security audit logging for Elasticsearch via the cluster settings API. Audit logs record security events such as authentication attempts, access grants and denials, role changes, and API key operations — essential for compliance and incident investigation.

For Kibana audit logging (saved object access, login/logout, space operations), see kibana-audit. For authentication and API key management, see elasticsearch-authn. For roles and user management, see elasticsearch-authz. For diagnosing security errors, see elasticsearch-security-troubleshooting.

For detailed API endpoints and event types, see references/api-reference.md.

Deployment note: Audit logging configuration differs across deployment types. See Deployment Compatibility for details.

Jobs to Be Done

• Enable or disable security audit logging on a cluster
• Select which security events to record (authentication, access, config changes)
• Create filter policies to reduce audit log noise
• Query audit logs for failed authentication attempts
• Investigate unauthorized access or privilege escalation incidents
• Set up compliance-focused audit configuration
• Detect brute-force login patterns from audit data
• Configure audit output to an index for programmatic querying

Prerequisites

Prompt the user for any missing values.

Enable Audit Logging

Enable audit logging dynamically without a restart:

curl -X PUT "${ELASTICSEARCH_URL}/_cluster/settings" \
  <auth_flags> \
  -H "Content-Type: application/json" \
  -d '{
    "persistent": {
      "xpack.security.audit.enabled": true
    }
  }'

To disable, set xpack.security.audit.enabled to false. Verify current state:

curl "${ELASTICSEARCH_URL}/_cluster/settings?include_defaults=true&flat_settings=true" \
  <auth_flags> | jq '.defaults | with_entries(select(.key | startswith("xpack.security.audit")))'

Audit Output

Audit events can be written to two outputs. Both can be active simultaneously.

Configure output via API

curl -X PUT "${ELASTICSEARCH_URL}/_cluster/settings" \
  <auth_flags> \
  -H "Content-Type: application/json" \
  -d '{
    "persistent": {
      "xpack.security.audit.enabled": true,
      "xpack.security.audit.outputs": ["index", "logfile"]
    }
  }'

The index output is required for programmatic querying of audit events. The logfile output is useful for shipping to external SIEM tools via Filebeat.

Note: On self-managed clusters, xpack.security.audit.outputs may require a static setting in elasticsearch.yml on older versions (pre-8.x). On 8.x+, prefer the cluster settings API.

Select Events to Record

Control which event types are included or excluded. By default, all events are recorded when audit is enabled.

Include specific events only

curl -X PUT "${ELASTICSEARCH_URL}/_cluster/settings" \
  <auth_flags> \
  -H "Content-Type: application/json" \
  -d '{
    "persistent": {
      "xpack.security.audit.logfile.events.include": [
        "authentication_failed",
        "access_denied",
        "access_granted",
        "anonymous_access_denied",
        "tampered_request",
        "run_as_denied",
        "connection_denied"
      ]
    }
  }'

Exclude noisy events

curl -X PUT "${ELASTICSEARCH_URL}/_cluster/settings" \
  <auth_flags> \
  -H "Content-Type: application/json" \
  -d '{
    "persistent": {
      "xpack.security.audit.logfile.events.exclude": [
        "access_granted"
      ]
    }
  }'

Excluding access_granted significantly reduces log volume on busy clusters — use this when only failures matter.

Event types reference

See references/api-reference.md for the complete event type list with field details.

Filter Policies

Filter policies let you suppress specific audit events by user, realm, role, or index without disabling the event type globally. Multiple policies can be active — an event is logged only if no policy filters it out.

Ignore system and internal users

curl -X PUT "${ELASTICSEARCH_URL}/_cluster/settings" \
  <auth_flags> \
  -H "Content-Type: application/json" \
  -d '{
    "persistent": {
      "xpack.security.audit.logfile.events.ignore_filters": {
        "system_users": {
          "users": ["_xpack_security", "_xpack", "elastic/fleet-server"],
          "realms": ["_service_account"]
        }
      }
    }
  }'

Ignore health-check traffic on specific indices

curl -X PUT "${ELASTICSEARCH_URL}/_cluster/settings" \
  <auth_flags> \
  -H "Content-Type: application/json" \
  -d '{
    "persistent": {
      "xpack.security.audit.logfile.events.ignore_filters": {
        "health_checks": {
          "users": ["monitoring-user"],
          "indices": [".monitoring-*"]
        }
      }
    }
  }'

Filter policy fields

An event is filtered out if it matches all specified fields within a single policy.

Remove a filter policy

Set the policy to null:

curl -X PUT "${ELASTICSEARCH_URL}/_cluster/settings" \
  <auth_flags> \
  -H "Content-Type: application/json" \
  -d '{
    "persistent": {
      "xpack.security.audit.logfile.events.ignore_filters.health_checks": null
    }
  }'

Query Audit Events

When the index output is enabled, audit events are stored in .security-audit-* indices and can be queried.

Search for failed authentication attempts

curl -X POST "${ELASTICSEARCH_URL}/.security-audit-*/_search" \
  <auth_flags> \
  -H "Content-Type: application/json" \
  -d '{
    "query": {
      "bool": {
        "filter": [
          { "term": { "event.action": "authentication_failed" } },
          { "range": { "@timestamp": { "gte": "now-24h" } } }
        ]
      }
    },
    "sort": [{ "@timestamp": { "order": "desc" } }],
    "size": 50
  }'

Search for access denied events on a specific index

curl -X POST "${ELASTICSEARCH_URL}/.security-audit-*/_search" \
  <auth_flags> \
  -H "Content-Type: application/json" \
  -d '{
    "query": {
      "bool": {
        "filter": [
          { "term": { "event.action": "access_denied" } },
          { "term": { "indices": "logs-*" } },
          { "range": { "@timestamp": { "gte": "now-7d" } } }
        ]
      }
    },
    "sort": [{ "@timestamp": { "order": "desc" } }],
    "size": 20
  }'

Search for security configuration changes

curl -X POST "${ELASTICSEARCH_URL}/.security-audit-*/_search" \
  <auth_flags> \
  -H "Content-Type: application/json" \
  -d '{
    "query": {
      "bool": {
        "filter": [
          { "term": { "event.action": "security_config_change" } },
          { "range": { "@timestamp": { "gte": "now-7d" } } }
        ]
      }
    },
    "sort": [{ "@timestamp": { "order": "desc" } }],
    "size": 50
  }'

This captures role creation/deletion, user changes, API key operations, and role mapping updates.

Count events by type and detect brute-force patterns

Use terms aggregations on event.action (with size: 0) to count events by type over a time window. To detect brute-force attempts, aggregate authentication_failed events by source.ip<