2018-08-13 18:06:25 +02:00
[role="xpack"]
[[xpack-security-audit-logging]]
2020-06-18 21:33:13 +02:00
=== Audit logs
2018-08-13 18:06:25 +02:00
You can enable auditing to keep track of security-related events such as
2020-10-21 00:54:26 +02:00
authorization success and failures. Logging these events enables you to monitor
{kib} for suspicious activity and provides evidence in the event of an attack.
2018-08-13 18:06:25 +02:00
2020-10-21 00:54:26 +02:00
Use the {kib} audit logs in conjunction with {ref}/enable-audit-logging.html[{es} audit logging] to get a
holistic view of all security related events. {kib} defers to the {es} security
model for authentication, data index authorization, and features that are driven
by cluster-wide privileges. For more information on enabling audit logging in
{es}, refer to {ref}/auditing.html[Auditing security events].
2018-08-13 18:06:25 +02:00
[IMPORTANT]
============================================================================
2020-10-21 00:54:26 +02:00
Audit logs are **disabled** by default. To enable this functionality, you must
set `xpack.security.audit.enabled` to `true` in `kibana.yml`.
2018-08-13 18:06:25 +02:00
============================================================================
2020-10-21 00:54:26 +02:00
The current version of the audit logger uses the standard {kib} logging output,
which can be configured in `kibana.yml`. For more information, refer to <<settings>>.
The audit logger uses a separate logger and can be configured using
the options in <<audit-logging-settings>>.
2018-08-13 18:06:25 +02:00
==== Audit event types
2020-10-21 00:54:26 +02:00
When you are auditing security events, each request can generate multiple audit
events. The following is a list of the events that can be generated:
2018-08-13 18:06:25 +02:00
|======
| `saved_objects_authorization_success` | Logged when a user is authorized to access a saved
objects when using a role with <<kibana-privileges>>
| `saved_objects_authorization_failure` | Logged when a user isn't authorized to access a saved
objects when using a role with <<kibana-privileges>>
2018-08-13 20:17:08 +02:00
|======
2020-10-21 00:54:26 +02:00
[[xpack-security-ecs-audit-logging]]
==== ECS audit events
[IMPORTANT]
============================================================================
The following events are only logged if the ECS audit logger is enabled.
For information on how to configure `xpack.security.audit.appender`, refer to
<<ecs-audit-logging-settings>>.
============================================================================
Refer to the table of events that can be logged for auditing purposes.
2020-12-21 16:46:31 +01:00
Each event is broken down into <<field-event-category, category>>, <<field-event-type, type>>, <<field-event-action, action>> and <<field-event-outcome, outcome>> fields
2020-10-21 00:54:26 +02:00
to make it easy to filter, query and aggregate the resulting logs.
2020-12-21 16:46:31 +01:00
Refer to <<xpack-security-ecs-audit-schema>> for a table of fields that get logged with audit event.
2020-10-21 00:54:26 +02:00
[NOTE]
============================================================================
To ensure that a record of every operation is persisted even in case of an
unexpected error, asynchronous write operations are logged immediately after all
authorization checks have passed, but before the response from {es} is received.
Refer to the corresponding {es} logs for potential write errors.
============================================================================
[cols="3*<"]
|======
3+a|
===== Category: authentication
| *Action*
| *Outcome*
| *Description*
.2+| `user_login`
| `success` | User has logged in successfully.
| `failure` | Failed login attempt (e.g. due to invalid credentials).
3+a|
===== Category: database
====== Type: creation
| *Action*
| *Outcome*
| *Description*
.2+| `saved_object_create`
| `unknown` | User is creating a saved object.
| `failure` | User is not authorized to create a saved object.
2020-12-05 13:05:46 +01:00
.2+| `connector_create`
| `unknown` | User is creating a connector.
| `failure` | User is not authorized to create a connector.
.2+| `alert_create`
2020-12-21 13:36:24 +01:00
| `unknown` | User is creating an alert.
| `failure` | User is not authorized to create an alert.
2020-12-05 13:05:46 +01:00
2020-12-21 13:36:24 +01:00
.2+| `space_create`
| `unknown` | User is creating a space.
| `failure` | User is not authorized to create a space.
2020-10-21 00:54:26 +02:00
3+a|
====== Type: change
| *Action*
| *Outcome*
| *Description*
.2+| `saved_object_update`
| `unknown` | User is updating a saved object.
| `failure` | User is not authorized to update a saved object.
.2+| `saved_object_add_to_spaces`
| `unknown` | User is adding a saved object to other spaces.
| `failure` | User is not authorized to add a saved object to other spaces.
.2+| `saved_object_delete_from_spaces`
| `unknown` | User is removing a saved object from other spaces.
| `failure` | User is not authorized to remove a saved object from other spaces.
2020-11-03 14:35:43 +01:00
.2+| `saved_object_remove_references`
| `unknown` | User is removing references to a saved object.
| `failure` | User is not authorized to remove references to a saved object.
2020-12-05 13:05:46 +01:00
.2+| `connector_update`
| `unknown` | User is updating a connector.
| `failure` | User is not authorized to update a connector.
.2+| `alert_update`
2020-12-21 13:36:24 +01:00
| `unknown` | User is updating an alert.
| `failure` | User is not authorized to update an alert.
2020-12-05 13:05:46 +01:00
.2+| `alert_update_api_key`
2020-12-21 13:36:24 +01:00
| `unknown` | User is updating the API key of an alert.
| `failure` | User is not authorized to update the API key of an alert.
2020-12-05 13:05:46 +01:00
.2+| `alert_enable`
2020-12-21 13:36:24 +01:00
| `unknown` | User is enabling an alert.
| `failure` | User is not authorized to enable an alert.
2020-12-05 13:05:46 +01:00
.2+| `alert_disable`
2020-12-21 13:36:24 +01:00
| `unknown` | User is disabling an alert.
| `failure` | User is not authorized to disable an alert.
2020-12-05 13:05:46 +01:00
.2+| `alert_mute`
2020-12-21 13:36:24 +01:00
| `unknown` | User is muting an alert.
| `failure` | User is not authorized to mute an alert.
2020-12-05 13:05:46 +01:00
.2+| `alert_unmute`
2020-12-21 13:36:24 +01:00
| `unknown` | User is unmuting an alert.
| `failure` | User is not authorized to unmute an alert.
2020-12-05 13:05:46 +01:00
.2+| `alert_instance_mute`
| `unknown` | User is muting an alert instance.
| `failure` | User is not authorized to mute an alert instance.
.2+| `alert_instance_unmute`
| `unknown` | User is unmuting an alert instance.
| `failure` | User is not authorized to unmute an alert instance.
2020-12-21 13:36:24 +01:00
.2+| `space_update`
| `unknown` | User is updating a space.
| `failure` | User is not authorized to update a space.
2020-11-03 14:35:43 +01:00
2020-10-21 00:54:26 +02:00
3+a|
====== Type: deletion
| *Action*
| *Outcome*
| *Description*
.2+| `saved_object_delete`
| `unknown` | User is deleting a saved object.
| `failure` | User is not authorized to delete a saved object.
2020-12-05 13:05:46 +01:00
.2+| `connector_delete`
| `unknown` | User is deleting a connector.
| `failure` | User is not authorized to delete a connector.
.2+| `alert_delete`
2020-12-21 13:36:24 +01:00
| `unknown` | User is deleting an alert.
| `failure` | User is not authorized to delete an alert.
.2+| `space_delete`
| `unknown` | User is deleting a space.
| `failure` | User is not authorized to delete a space.
2020-12-05 13:05:46 +01:00
2020-10-21 00:54:26 +02:00
3+a|
====== Type: access
| *Action*
| *Outcome*
| *Description*
.2+| `saved_object_get`
| `success` | User has accessed a saved object.
| `failure` | User is not authorized to access a saved object.
2021-01-22 22:53:47 +01:00
.2+| `saved_object_resolve`
| `success` | User has accessed a saved object.
| `failure` | User is not authorized to access a saved object.
2020-10-21 00:54:26 +02:00
.2+| `saved_object_find`
| `success` | User has accessed a saved object as part of a search operation.
| `failure` | User is not authorized to search for saved objects.
2020-12-05 13:05:46 +01:00
.2+| `connector_get`
| `success` | User has accessed a connector.
| `failure` | User is not authorized to access a connector.
.2+| `connector_find`
| `success` | User has accessed a connector as part of a search operation.
| `failure` | User is not authorized to search for connectors.
.2+| `alert_get`
2020-12-21 13:36:24 +01:00
| `success` | User has accessed an alert.
| `failure` | User is not authorized to access an alert.
2020-12-05 13:05:46 +01:00
.2+| `alert_find`
2020-12-21 13:36:24 +01:00
| `success` | User has accessed an alert as part of a search operation.
| `failure` | User is not authorized to search for alerts.
.2+| `space_get`
| `success` | User has accessed a space.
| `failure` | User is not authorized to access a space.
2020-12-05 13:05:46 +01:00
2020-12-21 13:36:24 +01:00
.2+| `space_find`
| `success` | User has accessed a space as part of a search operation.
| `failure` | User is not authorized to search for spaces.
2020-10-21 00:54:26 +02:00
3+a|
===== Category: web
| *Action*
| *Outcome*
| *Description*
| `http_request`
| `unknown` | User is making an HTTP request.
|======
2020-12-21 16:46:31 +01:00
[[xpack-security-ecs-audit-schema]]
==== ECS audit schema
Audit logs are written in JSON using https://www.elastic.co/guide/en/ecs/1.6/index.html[Elastic Common Schema (ECS)] specification.
[cols="2*<"]
|======
2+a| ===== Base Fields
| *Field*
| *Description*
| `@timestamp`
| Time when the event was generated.
Example: `2016-05-23T08:05:34.853Z`
| `message`
| Human readable description of the event.
2+a| ===== Event Fields
| *Field*
| *Description*
| [[field-event-action]] `event.action`
| The action captured by the event.
Refer to <<xpack-security-ecs-audit-logging>> for a table of possible actions.
| [[field-event-category]] `event.category`
| High level category associated with the event.
This field is closely related to `event.type`, which is used as a subcategory.
Possible values:
`database`,
`web`,
`authentication`
| [[field-event-type]] `event.type`
| Subcategory associated with the event.
This field can be used along with the `event.category` field to enable filtering events down to a level appropriate for single visualization.
Possible values:
`creation`,
`access`,
`change`,
`deletion`
| [[field-event-outcome]] `event.outcome`
| Denotes whether the event represents a success or failure.
Possible values:
`success`,
`failure`,
`unknown`
2+a| ===== User Fields
| *Field*
| *Description*
| `user.name`
| Login name of the user.
Example: `jdoe`
| `user.roles[]`
| Set of user roles at the time of the event.
Example: `[kibana_admin, reporting_user]`
2+a| ===== Kibana Fields
| *Field*
| *Description*
| `kibana.space_id`
| ID of the space associated with the event.
Example: `default`
| `kibana.session_id`
| ID of the user session associated with the event.
Each login attempt results in a unique session id.
| `kibana.saved_object.type`
| Type of saved object associated with the event.
Example: `dashboard`
| `kibana.saved_object.id`
| ID of the saved object associated with the event.
| `kibana.authentication_provider`
| Name of the authentication provider associated with the event.
Example: `my-saml-provider`
| `kibana.authentication_type`
| Type of the authentication provider associated with the event.
Example: `saml`
| `kibana.authentication_realm`
| Name of the Elasticsearch realm that has authenticated the user.
Example: `native`
| `kibana.lookup_realm`
| Name of the Elasticsearch realm where the user details were retrieved from.
Example: `native`
| `kibana.add_to_spaces[]`
| Set of space IDs that a saved object is being shared to as part of the event.
Example: `[default, marketing]`
| `kibana.delete_from_spaces[]`
| Set of space IDs that a saved object is being removed from as part of the event.
Example: `[marketing]`
2+a| ===== Error Fields
| *Field*
| *Description*
| `error.code`
| Error code describing the error.
| `error.message`
| Error message.
2+a| ===== HTTP and URL Fields
| *Field*
| *Description*
| `http.request.method`
| HTTP request method.
Example: `get`, `post`, `put`, `delete`
| `url.domain`
| Domain of the url.
Example: `www.elastic.co`
| `url.path`
| Path of the request.
Example: `/search`
| `url.port`
| Port of the request.
Example: `443`
| `url.query`
| The query field describes the query string of the request.
Example: `q=elasticsearch`
| `url.scheme`
| Scheme of the request.
Example: `https`
2+a| ===== Tracing Fields
| *Field*
| *Description*
| `trace.id`
| Unique identifier allowing events of the same transaction from {kib} and {es} to be be correlated.
|======