WARNING: Version 5.5 of the Elastic Stack has passed its EOL date.
This documentation is no longer being maintained and may be removed. If you are running this version, we strongly advise you to upgrade. For the latest information, see the current release documentation.
Auditing Security Events
editAuditing Security Events
editYou 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.
Audit logs are disabled by default. To enable this functionality, you
must set xpack.security.audit.enabled
to true
in elasticsearch.yml
.
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.
Audit events are batched for indexing so there is a lag before
events appear in the index. You can control how frequently batches of
events are pushed to the index by setting
xpack.security.audit.index.flush_interval
in elasticsearch.yml
.
Audit Event Types
editEach request may generate multiple audit events. The following is a list of the events that can be generated:
|
Logged when a request is denied due to a missing authentication token. |
||
|
Logged when a user successfully authenticates. |
||
|
Logged when the authentication token cannot be matched to a known user. |
||
|
Logged for every realm that fails to present a valid
authentication token. |
||
|
Logged when an authenticated user attempts to execute an action they do not have the necessary privilege to perform. |
||
|
Logged when an authenticated user attempts to execute
an action they have the necessary privilege to perform.
When the |
||
|
Logged when an authenticated user attempts to run as another user that they have the necessary privileges to do. |
||
|
Logged when an authenticated user attempts to run as another user action they do not have the necessary privilege to do so. |
||
|
Logged when X-Pack security detects that the request has
been tampered with. Typically relates to |
||
|
Logged when an incoming TCP connection passes the IP Filter for a specific profile. |
||
|
Logged when an incoming TCP connection does not pass the IP Filter for a specific profile. |
Audit Event Attributes
editThe following table shows the common attributes that can be associated with every event.
Table 12. Common Attributes
Attribute | Description |
---|---|
|
When the event occurred. |
|
The name of the node. |
|
The hostname of the node. |
|
The IP address of the node. |
|
The layer from which this event originated: |
|
The type of event that occurred: |
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.
Table 13. REST anonymous_access_denied Attributes
Attribute | Description |
---|---|
|
The IP address from which the request originated. |
|
The REST endpoint URI. |
|
The body of the request, if enabled. |
Table 14. REST authentication_success Attributes
Attribute | Description |
---|---|
|
The authenticated user. |
|
The realm that authenticated the user. |
|
The REST endpoint URI. |
|
The REST URI query parameters. |
|
The body of the request, if enabled. |
Table 15. REST authentication_failed Attributes
Attribute | Description |
---|---|
|
The IP address from which the request originated. |
|
The principal (username) that failed authentication. |
|
The REST endpoint URI. |
|
The body of the request, if enabled. |
Table 16. REST realm_authentication_failed Attributes
Attribute | Description |
---|---|
|
The IP address from which the request originated. |
|
The principal (username) that failed authentication. |
|
The REST endpoint URI. |
|
The body of the request, if enabled. |
|
The realm that failed to authenticate the user. NOTE: A separate entry is logged for each consulted realm. |
Table 17. Transport anonymous_access_denied Attributes
Attribute | Description |
---|---|
|
Where the request originated: |
|
The IP address from which the request originated. |
|
The name of the action that was executed. |
|
The type of request that was executed. |
|
A comma-separated list of indices this request pertains to (when applicable). |
Table 18. Transport authentication_success Attributes
Attribute | Description |
---|---|
|
Where the request originated: |
|
The IP address from which the request originated. |
|
The authenticated user. |
|
The realm that authenticated the user. |
|
The name of the action that was executed. |
|
The type of request that was executed. |
Table 19. Transport authentication_failed Attributes
Attribute | Description |
---|---|
|
Where the request originated: |
|
The IP address from which the request originated. |
|
The principal (username) that failed authentication. |
|
The name of the action that was executed. |
|
The type of request that was executed. |
|
A comma-separated list of indices this request pertains to (when applicable). |
Table 20. Transport realm_authentication_failed Attributes
Attribute | Description |
---|---|
|
Where the request originated: |
|
The IP address from which the request originated. |
|
The principal (username) that failed authentication. |
|
The name of the action that was executed. |
|
The type of request that was executed. |
|
A comma-separated list of indices this request pertains to (when applicable). |
|
The realm that failed to authenticate the user. NOTE: A separate entry is logged for each consulted realm. |
Table 21. Transport access_granted Attributes
Attribute | Description |
---|---|
|
Where the request originated: |
|
The IP address from which the request originated. |
|
The principal (username) that passed authentication. |
|
The name of the action that was executed. |
|
The type of request that was executed. |
|
A comma-separated list of indices this request pertains to (when applicable). |
Table 22. Transport access_denied Attributes
Attribute | Description |
---|---|
|
Where the request originated: |
|
The IP address from which the request originated. |
|
The principal (username) that failed authentication. |
|
The name of the action that was executed. |
|
The type of request that was executed. |
|
A comma-separated list of indices this request relates to (when applicable). |
Table 23. Transport tampered_request Attributes
Attribute | Description |
---|---|
|
Where the request originated: |
|
The IP address from which the request originated. |
|
The principal (username) that failed to authenticate. |
|
The name of the action that was executed. |
|
The type of request that was executed. |
|
A comma-separated list of indices this request pertains to (when applicable). |
Table 24. IP Filter connection_granted Attributes
Attribute | Description |
---|---|
|
The IP address from which the request originated. |
|
The transport profile the request targeted. |
|
The IP filtering rule that granted the request. |
Table 25. IP Filter connection_denied Attributes
Attribute | Description |
---|---|
|
The IP address from which the request originated. |
|
The transport profile the request targeted. |
|
The IP filtering rule that denied the request. |
Logfile Audit Output
editThe logfile
audit output is the default output for auditing. It writes data to
the <clustername>_access.log
file in the logs directory.
Log Entry Format
editThe format of a log entry is:
[<timestamp>] [<local_node_info>] [<layer>] [<entry_type>] <attribute_list>
-
<timestamp>
-
When the event occurred. You can configure the
timestamp format in
log4j2.properties
. -
<local_node_info>
- Information about the local node that generated the log entry. You can control what node information is included by configuring the local node info settings.
-
<layer>
-
The layer from which this event originated:
rest
,transport
orip_filter
. -
<entry_type>
-
The type of event that occurred:
anonymous_access_denied
,authentication_failed
,access_denied
,access_granted
,connection_granted
,connection_denied
. -
<attribute_list>
-
A comma-separated list of key-value pairs that contain
data pertaining to the event. Formatted as
attr1=[val1], attr2=[val2]
. See Audit Entry Attributes for the attributes that can be included for each type of event.
Logfile Output Settings
editThe 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.
No filtering is performed when auditing, so sensitive data may be audited in plain text when including the request body in audit events.
You configure also configure how the logfile is written in the log4j2.properties
file located in CONFIG_DIR/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.
Index Audit Output
editIn 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.
No filtering is performed when auditing, so sensitive data may be audited in plain text when including the request body in audit events.
Audit Index Settings
editYou 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
Forwarding Audit Logs to a Remote Cluster
editTo index audit events to a remote Elasticsearch cluster, you configure
the following xpack.security.audit.index.client
settings:
-
xpack.security.audit.index.client.hosts
-
xpack.security.audit.index.client.cluster.name
-
xpack.security.audit.index.client.xpack.security.user
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