Elasticsearch Audit
Configure and query Elasticsearch cluster audit logging via xpack.security.audit settings and related APIs when hardening production search.
Overview
Elasticsearch-audit is an agent skill for the Operate phase that documents Elasticsearch xpack security audit cluster settings and event configuration APIs.
Install
npx skills add https://github.com/elastic/agent-skills --skill elasticsearch-auditWhat is this skill?
- Cluster settings reference for xpack.security.audit.enabled and outputs (logfile, index)
- Event include/exclude lists for logfile audit streams
- PUT /_cluster/settings workflow with persistent vs transient behavior called out
- Cross-links to kibana-audit skill for Kibana-side audit logging
Adoption & trust: 1.1k installs on skills.sh; 502 GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
You must turn on or tune Elasticsearch audit logs for compliance but keep misconfiguring cluster settings or event filters.
Who is it for?
Indie SaaS builders or small teams self-hosting Elastic who need audit logging wired correctly without a dedicated platform engineer.
Skip if: Greenfield app developers with no Elasticsearch cluster, or teams that only need application-level auth logs outside Elastic.
When should I use this skill?
User configures Elasticsearch audit logging, xpack.security.audit settings, or queries audit-related cluster APIs.
What do I get? / Deliverables
You apply the correct PUT /_cluster/settings payloads and audit namespace keys so security events land in logfile or index outputs as intended.
- Correct audit cluster setting payloads
- Documented output and event filter choices for the cluster
Recommended Skills
Journey fit
Audit enablement, event filters, and log review are ongoing production concerns after the cluster is live. Monitoring subphase covers security audit trails, event inclusion rules, and observability into cluster access patterns.
How it compares
Reference skill for Elastic audit APIs—not a generic SOC2 checklist or a Kibana UI walkthrough (see kibana-audit for that slice).
Common Questions / FAQ
Who is elasticsearch-audit for?
Builders operating Elasticsearch who configure security auditing via cluster APIs and need accurate setting names and defaults.
When should I use elasticsearch-audit?
During Operate when enabling audits after Ship security review, when tuning event filters for monitoring, or when preparing access logs for infra compliance checks.
Is elasticsearch-audit safe to install?
The skill describes cluster mutations that affect production logging; review the Security Audits panel on this page and test settings in a non-production cluster first.
SKILL.md
READMESKILL.md - Elasticsearch Audit
# Elasticsearch Audit Logging API Reference Quick reference for Elasticsearch audit logging configuration via the cluster settings API and audit event querying. For Kibana audit logging, see the **kibana-audit** skill. For full documentation, see the linked Elastic docs. ## Cluster Settings — Audit Configuration ```text PUT /_cluster/settings ``` All audit settings are configured under the `xpack.security.audit` namespace in `persistent` (survives restart) or `transient` (cleared on restart) cluster settings. [Full documentation](https://www.elastic.co/guide/en/elasticsearch/reference/current/auditing-settings.html) ### Core settings | Setting | Type | Default | Description | | ------------------------------ | ------- | ----------- | --------------------------------------- | | `xpack.security.audit.enabled` | boolean | `false` | Enable or disable audit logging | | `xpack.security.audit.outputs` | list | `[logfile]` | Output destinations: `logfile`, `index` | ### Event selection settings | Setting | Type | Default | Description | | ------------------------------------------------------- | ---- | ------- | ------------------------------------ | | `xpack.security.audit.logfile.events.include` | list | all | Event types to record (whitelist) | | `xpack.security.audit.logfile.events.exclude` | list | none | Event types to suppress (blacklist) | | `xpack.security.audit.logfile.events.emit_request_body` | bool | `false` | Include request body in audit events | When both `include` and `exclude` are set, `include` is applied first, then `exclude` removes from that set. ### Filter policy settings Filter policies are nested under `xpack.security.audit.logfile.events.ignore_filters.<policy_name>`: | Field | Type | Description | | --------- | ---- | ---------------------------------------------------- | | `users` | list | Usernames to exclude (supports wildcards like `*`) | | `realms` | list | Realm names to exclude | | `roles` | list | Role names to exclude | | `indices` | list | Index names or patterns to exclude | | `actions` | list | Action names to exclude (e.g. `indices:data/read/*`) | An event is filtered out only when it matches **all** non-empty fields in the policy. Empty fields are ignored (match anything). ## Audit Event Types | Event | Description | Key fields | | ------------------------- | ---------------------------------------------------- | ------------------------------------- | | `authentication_failed` | Credentials were rejected by all realms | `user.name`, `source.ip`, `realm` | | `authentication_success` | User authenticated successfully | `user.name`, `source.ip`, `realm` | | `access_granted` | An authorized action was performed | `user.name`, `indices`, `action` | | `access_denied` | An action was denied (insufficient privileges) | `user.name`, `indices`, `action` | | `anonymous_access_denied` | An unauthenticated request was rejected | `source.ip`, `action` | | `tampered_request` | A request was detected as tampered with | `source.ip`, `action` | | `connection_granted` | A transport-layer node connection was accepted | `source.ip`, `node.name` | | `connection_denied` | A transport-layer node connection was rejected | `source.ip` | | `run_as_granted` | A run-as impersonation was authorized | `user.name`, `run_as.user`, `action` | | `run_as_denied` | A run