431 lines
12 KiB
Text
431 lines
12 KiB
Text
[role="xpack"]
|
|
[[xpack-security-audit-logging]]
|
|
=== Audit logs
|
|
|
|
You can enable auditing 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].
|
|
|
|
[IMPORTANT]
|
|
============================================================================
|
|
Audit logs are **disabled** by default. To enable this functionality, you must
|
|
set `xpack.security.audit.enabled` to `true` in `kibana.yml`.
|
|
============================================================================
|
|
|
|
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>>.
|
|
|
|
==== Audit event types
|
|
|
|
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:
|
|
|
|
|======
|
|
| `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>>
|
|
|======
|
|
|
|
[[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.
|
|
|
|
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).
|
|
|
|
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+| `alert_create`
|
|
| `unknown` | User is creating an alert.
|
|
| `failure` | User is not authorized to create an alert.
|
|
|
|
.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+| `alert_update`
|
|
| `unknown` | User is updating an alert.
|
|
| `failure` | User is not authorized to update an alert.
|
|
|
|
.2+| `alert_update_api_key`
|
|
| `unknown` | User is updating the API key of an alert.
|
|
| `failure` | User is not authorized to update the API key of an alert.
|
|
|
|
.2+| `alert_enable`
|
|
| `unknown` | User is enabling an alert.
|
|
| `failure` | User is not authorized to enable an alert.
|
|
|
|
.2+| `alert_disable`
|
|
| `unknown` | User is disabling an alert.
|
|
| `failure` | User is not authorized to disable an alert.
|
|
|
|
.2+| `alert_mute`
|
|
| `unknown` | User is muting an alert.
|
|
| `failure` | User is not authorized to mute an alert.
|
|
|
|
.2+| `alert_unmute`
|
|
| `unknown` | User is unmuting an alert.
|
|
| `failure` | User is not authorized to unmute an alert.
|
|
|
|
.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.
|
|
|
|
.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+| `alert_delete`
|
|
| `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.
|
|
|
|
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+| `alert_get`
|
|
| `success` | User has accessed an alert.
|
|
| `failure` | User is not authorized to access an alert.
|
|
|
|
.2+| `alert_find`
|
|
| `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.
|
|
|
|
.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]]
|
|
==== 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.
|
|
|
|
|======
|