Auditing Security Events

You can enable auditing to keep track of security-related events such as authentication failures and refused connections. Logging these events enables you to monitor your cluster for suspicious activity and provides evidence in the event of an attack.

X-Pack security provides two ways to persist audit logs:

By default, only the logfile output is used when enabling auditing. To facilitate browsing and analyzing the events, you can also enable indexing by setting xpack.security.audit.outputs in elasticsearch.yml:

xpack.security.audit.outputs: [ index, logfile ]

The index output type should be used in conjunction with the logfile output type Because it is possible for the index output type to lose messages if the target index is unavailable, the access.log should be used as the official record of events.

Each request may generate multiple audit events. The following is a list of the events that can be generated:

The following table shows the common attributes that can be associated with every event.

The following tables show the attributes that can be associated with each type of event. The log level determines which attributes are included in a log entry.

The logfile audit output is the default output for auditing. It writes data to the <clustername>_access.log file in the logs directory.

The format of a log entry is:

[<timestamp>] [<local_node_info>] [<layer>] [<entry_type>] <attribute_list>

The events and some other information about what gets logged can be controlled using settings in the elasticsearch.yml file. See Audited Event Settings and Local Node Info Settings.

You can also configure how the logfile is written in the log4j2.properties file located in ES_PATH_CONF/x-pack. By default, audit information is appended to the <clustername>_access.log file located in the standard Elasticsearch logs directory (typically located at $ES_HOME/logs). The file rolls over on a daily basis.

The comprehensive audit trail is necessary to ensure accountability. It offers tremendous value during incident response and can even be required for demonstrating compliance.

The drawback of an audited system is represented by the inevitable performance penalty incurred. In all truth, the audit trail spends I/O ops that are not available anymore for the user’s queries. Sometimes the verbosity of the audit trail may become a problem that the event type restrictions, defined by include and exclude, will not alleviate.

Audit events ignore policies are a finer way to tune the verbosity of the audit trail. These policies define rules that match audit events which will be ignored (read as: not printed). Rules match on the values of attributes of audit events and complement the include/exclude method. Imagine the corpus of audit events and the policies chopping off unwanted events.

A policy is a named set of filter rules. Each filter rule applies to a single event attribute, one of the users, realms, roles or indices attributes. The filter rule defines a list of Lucene regexp, any of which has to match the value of the audit event attribute for the rule to match. A policy matches an event if all the rules comprising it match the event. An audit event is ignored, therefore not printed, if it matches any policy. All other non-matching events are printed as usual.

All policies are defined under the xpack.security.audit.logfile.events.ignore_filters settings namespace. For example, the following policy named example1 matches events from the kibana or admin_user principals and operating over indices of the wildcard form app-logs*:

xpack.security.audit.logfile.events.ignore_filters:
  example1:
    users: ["kibana", "admin_user"]
    indices: ["app-logs*"]

An audit event generated by the kibana user and operating over multiple indices , some of which do not match the indices wildcard, will not match. As expected, operations generated by all other users (even operating only on indices that match the indices filter) will not match this policy either.

Audit events of different types may have different attributes. If an event does not contain an attribute for which some policy defines filters, the event will not match the policy. For example, the following policy named example2, will never match authentication_success or authentication_failed events, irrespective of the user’s roles, because these event schemas do not contain the role attribute:

xpack.security.audit.logfile.events.ignore_filters:
  example2:
    roles: ["admin", "ops_admin_*"]

Likewise, any events of users with multiple roles, some of which do not match the regexps will not match this policy.

For completeness, although practical use cases should be sparse, a filter can match a missing attribute of an event, using the empty string ("") or the empty list ([]). For example, the following policy will match events that do not have the indices attribute (anonymous_access_denied, authentication_success and other types) as well as events over the next index.

xpack.security.audit.logfile.events.ignore_filters:
  example3:
    indices: ["next", ""]

In addition to logging to a file, you can store audit logs in Elasticsearch rolling indices. These indices can be either on the same cluster, or on a remote cluster. You configure the following settings in elasticsearch.yml to control how audit entries are indexed. To enable this output, you need to configure the setting xpack.security.audit.outputs in the elasticsearch.yml file:

xpack.security.audit.outputs: [ index, logfile ]

For more configuration options, see Audit Log Indexing Configuration Settings.

You can also configure settings for the indices that the events are stored in. These settings are configured in the xpack.security.audit.index.settings namespace in elasticsearch.yml. For example, the following configuration sets the number of shards and replicas to 1 for the audit indices:

xpack.security.audit.index.settings:
  index:
    number_of_shards: 1
    number_of_replicas: 1

These settings apply to the local audit indices, as well as to the remote audit indices, but only if the remote cluster does not have X-Pack security installed, or the Elasticsearch versions are different. If the remote cluster has X-Pack security installed, and the versions coincide, the settings for the audit indices there will take precedence, even if they are unspecified (i.e. left to defaults).

To index audit events to a remote Elasticsearch cluster, you configure the following xpack.security.audit.index.client settings:

For more information about these settings, see Remote Audit Log Indexing Configuration Settings.

You can pass additional settings to the remote client by specifying them in the xpack.security.audit.index.client namespace. For example, to allow the remote client to discover all of the nodes in the remote cluster you can specify the client.transport.sniff setting:

xpack.security.audit.index.client.transport.sniff: true