[role="xpack"]
[[xpack-security-audit-logging]]
=== Audit logs

Audit logging is a https://www.elastic.co/subscriptions[subscription feature] that you can enable to keep track of security-related events,
such as authorization success and failures. Logging these events enables you to monitor {kib} for suspicious activity and provides evidence
in the event of an attack.

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].

[NOTE]
============================================================================
Audit logs are **disabled** by default. To enable this functionality, you must
set `xpack.security.audit.enabled` to `true` in `kibana.yml`, and optionally configure
an <<audit-logging-settings, appender>> to write the audit log to a location of your choosing.
============================================================================

[[xpack-security-ecs-audit-logging]]
==== Audit events

Refer to the table of events that can be logged for auditing purposes. 

Each event is broken down into <<field-event-category, category>>, <<field-event-type, type>>, <<field-event-action, action>> and <<field-event-outcome, outcome>> fields
to make it easy to filter, query and aggregate the resulting logs. 

Refer to <<xpack-security-ecs-audit-schema>> for a table of fields that get logged with audit event. 

[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).

| `access_agreement_acknowledged`
| N/A | User has acknowledged the access agreement.

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.

.2+| `saved_object_open_point_in_time`
| `unknown` | User is creating a Point In Time to use when querying saved objects.
| `failure` | User is not authorized to create a Point In Time for the provided saved object types.

.2+| `connector_create`
| `unknown` | User is creating a connector.
| `failure` | User is not authorized to create a connector.

.2+| `rule_create`
| `unknown` | User is creating a rule.
| `failure` | User is not authorized to create a rule.

.2+| `space_create`
| `unknown` | User is creating a space.
| `failure` | User is not authorized to create a space.

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.

.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.

.2+| `connector_update`
| `unknown` | User is updating a connector.
| `failure` | User is not authorized to update a connector.

.2+| `rule_update`
| `unknown` | User is updating a rule.
| `failure` | User is not authorized to update a rule.

.2+| `rule_update_api_key`
| `unknown` | User is updating the API key of a rule.
| `failure` | User is not authorized to update the API key of a rule.

.2+| `rule_enable`
| `unknown` | User is enabling a rule.
| `failure` | User is not authorized to enable a rule.

.2+| `rule_disable`
| `unknown` | User is disabling a rule.
| `failure` | User is not authorized to disable a rule.

.2+| `rule_mute`
| `unknown` | User is muting a rule.
| `failure` | User is not authorized to mute a rule.

.2+| `rule_unmute`
| `unknown` | User is unmuting a rule.
| `failure` | User is not authorized to unmute a rule.

.2+| `rule_alert_mute`
| `unknown` | User is muting an alert.
| `failure` | User is not authorized to mute an alert.

.2+| `rule_alert_unmute`
| `unknown` | User is unmuting an alert.
| `failure` | User is not authorized to unmute an alert.

.2+| `space_update`
| `unknown` | User is updating a space.
| `failure` | User is not authorized to update a space.

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.

.2+| `saved_object_close_point_in_time`
| `unknown` | User is deleting a Point In Time that was used to query saved objects.
| `failure` | User is not authorized to delete a Point In Time.

.2+| `connector_delete`
| `unknown` | User is deleting a connector.
| `failure` | User is not authorized to delete a connector.

.2+| `rule_delete`
| `unknown` | User is deleting a rule.
| `failure` | User is not authorized to delete a rule.

.2+| `space_delete`
| `unknown` | User is deleting a space.
| `failure` | User is not authorized to delete a space.

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.

.2+| `saved_object_resolve`
| `success` | User has accessed a saved object.
| `failure` | User is not authorized to access a saved object.

.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.

.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+| `rule_get`
| `success` | User has accessed a rule.
| `failure` | User is not authorized to access a rule.

.2+| `rule_find`
| `success` | User has accessed a rule as part of a search operation.
| `failure` | User is not authorized to search for rules.

.2+| `space_get`
| `success` | User has accessed a space.
| `failure` | User is not authorized to access a space.

.2+| `space_find`
| `success` | User has accessed a space as part of a search operation.
| `failure` | User is not authorized to search for spaces.

3+a|
===== Category: web

| *Action*
| *Outcome*
| *Description*

| `http_request`
| `unknown` | User is making an HTTP request.
|======


[[xpack-security-ecs-audit-schema]]
==== 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.

|======