honeymoose
/
OpenSearch
mirror of https://github.com/honeymoose/OpenSearch.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

DOCS Audit event attributes in new format (#35510) 

Accounts for the `Structured Audit Entries` in the format
documentation.
This commit is contained in:
Albert Zaharovits 2018-11-28 01:24:03 +02:00 committed by GitHub
parent 383713d4e9
commit 36819f78ef
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 384 additions and 114 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

498
x-pack/docs/en/security/auditing/event-types.asciidoc
View File

@ -2,8 +2,10 @@
[[audit-event-types]] [[audit-event-types]]
=== Audit event types === Audit event types
When you are <<auditing,auditing security events>>, each request can generate When you are <<auditing,auditing security events>>, each request can generate
multiple audit events. The following is a list of the events that can be generated: multiple audit events.
The following is a list of the events that can be generated:
|====== |======
| `anonymous_access_denied` | | | Logged when a request is denied due to a missing | `anonymous_access_denied` | | | Logged when a request is denied due to a missing
@ -43,189 +45,458 @@ multiple audit events. The following is a list of the events that can be generat
[[audit-event-attributes]] [[audit-event-attributes]]
=== Audit event attributes === Audit event attributes
The following table shows the common attributes that can be associated with every event. In 6.5.0, there is a new <<audit-log-output, `logfile` audit output>> format.
This format also brings in a few changes for audit event attributes.
The new format is output to the `<clustername>_audit.log` file.
The audit entries are formatted as flat JSON documents (that is to say, no
nested objects), one per line. Hence, the attribute names are JSON keys and they
follow a dotted name syntax. Any attributes that lack a value (`null`) are not
output.
The following list shows attributes that are common to all audit events.
Their names and values are analogous to those in the deprecated `logfile` or
`index` output formats. However, it is expected that the formats will evolve
independently during the 6.x releases, so it is advisable to follow the attribute
descriptions for the format that you are using.
`@timestamp` :: The time, in ISO9601 format, when the event occurred.
`node.name` :: The name of the node. This can be changed
in the `elasticsearch.yml` config file.
`node.id` :: The node id. This is automatically generated and is
persistent across full cluster restarts.
`host.ip` :: The bound IP address of the node, with which the node
can be communicated with.
`host.name` :: The unresolved node's hostname.
`origin.address` :: The source IP address of the request associated with
this event. This could be the address of the remote client,
the address of another cluster node, or the local node's
bound address, if the request originated locally. Unless
the remote client connects directly to the cluster, the
_client address_ will actually be the address of the first
OSI layer 3 proxy in front of the cluster.
`origin.type` :: The origin type of the request associated with this event:
`rest` (request originated from a REST API request),
`transport` (request was received on the transport channel),
or `local_node` (the local node issued the request).
`event.type` :: The internal processing layer that generated the event:
`rest`, `transport` or `ip_filter`.
This is different from `origin.type` because a request
originating from the REST API is translated to a number
of transport messages, generating audit events with
`origin.type: rest` and `event.type: transport`.
`event.action` :: The type of event that occurred: `anonymous_access_denied`,
`authentication_failed`, `authentication_success`,
`realm_authentication_failed`, `access_denied`, `access_granted`,
`connection_denied`, `connection_granted`, `tampered_request`,
`run_as_denied`, or `run_as_granted`.
`opaque_id` :: The value of the `X-Opaque-Id` HTTP header (if present) of
the request associated with this event. This header can
be used freely by the client to mark API calls, as it has
no semantics in Elasticsearch.
==== Audit event attributes of the REST event type
The events with `event.type` equal to `rest` have one of the following `event.action`
attribute values: `authentication_success`, `anonymous_access_denied`, `authentication_failed`,
`realm_authentication_failed`, `tampered_request` or `run_as_denied`.
These event types also have the following extra attributes (in addition to the
common ones):
`url.path` :: The path part of the URL (between the port and the query
string) of the REST request associated with this event.
This is URL encoded.
`url.query` :: The query part of the URL (after "?", if present) of the
REST request associated with this event. This is URL encoded.
`request.body` :: The full content of the REST request associated with this
event, if enabled. This contains the query body. The body
is escaped according to the JSON RFC 4627.
==== Audit event attributes of the transport event type
The events with `event.type` equal to `transport` have one of the following `event.action`
attribute values: `authentication_success`, `anonymous_access_denied`, `authentication_failed`,
`realm_authentication_failed`, `access_granted`, `access_denied`, `run_as_granted`,
`run_as_denied`, or `tampered_request`.
These event types also have the following extra attributes (in addition to the common
ones):
`action` :: The name of the transport action that was executed.
This is like the URL for a REST request.
`indices` :: The indices names array that the request associated
with this event pertains to (when applicable).
`request.name` :: The name of the request handler that was executed.
==== Audit event attributes of the ip_filter event type
The events with `event.type` equal to `ip_filter` have one of the following `event.action`
attribute values: `connection_granted` or `connection_denied`.
These event types also have the following extra attributes (in addition to the common
ones):
`transport_profile` :: The transport profile the request targeted.
`rule` :: The <<ip-filtering, IP filtering>> rule that denied
the request.
==== Extra audit event attributes for specific events
There are a few events that have some more attributes in addition to those
that have been previously described:
* `authentication_success`:
`realm` :: The name of the realm that successfully
authenticated the user.
`user.name` :: The name of the _effective_ user. This is usually the
same as the _authenticated_ user, but if using the
<<run-as-privilege, run as authorization functionality>>
this instead denotes the name of the _impersonated_ user.
`user.run_by.name` :: This attribute is present only if the request is
using the <<run-as-privilege, run as authorization functionality>>
and denotes the name of the _authenticated_ user,
which is also known as the _impersonator_.
* `authentication_failed`:
`user.name` :: The name of the user that failed authentication.
If the request authentication token is invalid or
unparsable, this information might be missing.
* `realm_authentication_failed`:
`user.name` :: The name of the user that failed authentication.
`realm` :: The name of the realm that rejected this authentication.
**This event is generated for each consulted realm
in the chain.**
* `run_as_denied` and `run_as_granted`:
`user.roles` :: The role names of the user as an array.
`user.name` :: The name of the _authenticated_ user which is being
granted or denied the _impersonation_ action.
`user.realm` :: The realm name that the _authenticated_ user belongs to.
`user.run_as.name` :: The name of the user as which the _impersonation_
action is granted or denied.
`user.run_as.realm` :: The realm name of that the _impersonated_ user belongs to.
* `access_granted` or `access_denied`:
`user.roles` :: The role names of the user as an array.
`user.name` :: The name of the _effective_ user that is being
authorized or unauthorized. This is usually the _authenticated_
user, but if using the <<run-as-privilege, run as authorization functionality>>
this instead denotes the name of the _impersonated_ user.
`user.realm` :: The realm name that the _effective_ user belongs to.
`user.run_by.name` :: This attribute is present only if the request is
using the <<run-as-privilege, run as authorization functionality>>
and denoted the name of the _authenticated_ user,
which is also known as the _impersonator_.
`user.run_by.realm` :: This attribute is present only if the request is
using the <<run-as-privilege, run as authorization functionality>>
and denotes the name of the realm that the _authenticated_
(_impersonator_) user belongs to.
[float]
[[audit-event-attributes-deprecated-formats]]
=== Audit event attributes for the deprecated formats
The following table shows the common attributes that can be associated with
every event, when it is output to the `<clustername>_access.log` file or to the
<<audit-index, index>>.
.Common attributes .Common attributes
[cols="2,7",options="header"] [cols="2,7",options="header"]
|====== |======
| Attribute | Description | Attribute | Description
| `timestamp` | When the event occurred. | `@timestamp` | When the event occurred.
| `node_name` | The name of the node. | `node_name` | The name of the node.
| `node_host_name` | The hostname of the node. | `node_host_name` | The hostname of the node.
| `node_host_address` | The IP address of the node. | `node_host_address` | The IP address of the node.
| `layer` | The layer from which this event originated: `rest`, `transport` or `ip_filter` | `layer` | The layer from which this event originated: `rest`, `transport` or `ip_filter`
| `event_type` | The type of event that occurred: `anonymous_access_denied`, | `event_type` | The type of event that occurred: `anonymous_access_denied`,
`authentication_failed`, `access_denied`, `access_granted`, `authentication_failed`, `authentication_success`,
`connection_granted`, `connection_denied`, `tampered_request`, `realm_authentication_failed`, `access_denied`, `access_granted`,
`run_as_granted`, `run_as_denied`. `connection_denied`, `connection_granted`, `tampered_request`,
`run_as_denied`, `run_as_granted`.
|====== |======
The following tables show the attributes that can be associated with each type of event. For an event in the <<audit-log-output,audit log file output>>, these are
The log level determines which attributes are included in a log entry. positional attributes, which are printed at the beginning of each log line and
are not adjoined by the attribute name. As a matter of course, the names are
present for each attribute when the event is forwarded to the <<audit-index, index audit output>>.
The attribute `origin_address` is also common to every audit event. It is always
named, that is, it is not positional. It denotes the source IP address of the
request associated with this event. This might be the address of the client, the
address of another cluster node, or the local node's bound address (if the request
originated locally). Unless the client connects directly to the cluster, the
_client address_ is the address of the first OSI layer 3 proxy in front of the
cluster.
In addition, every event might have the `opaque_id` attribute, with the value as
it has been passed in by the `X-Opaque-Id` HTTP request header. This header can
be used freely by the client to mark API calls, as it has no semantics in
Elasticsearch. Every audit event, generated as part of handling a request thus
marked, contains the `opaque_id` attribute.
The following tables show the attributes that can are associated with each type
of event, in addition to the common ones previously described:
.REST anonymous_access_denied attributes .REST anonymous_access_denied attributes
[cols="2,7",options="header"] [cols="2,7",options="header"]
|====== |======
| Attribute | Description | Attribute | Description
| `origin_address` | The IP address from which the request originated. | `uri` | The REST endpoint URI.
| `uri` | The REST endpoint URI. | `request_body` | The body of the request, if enabled.
| `request_body` | The body of the request, if enabled.
|====== |======
.REST authentication_success attributes .REST authentication_success attributes
[cols="2,7",options="header"] [cols="2,7",options="header"]
|====== |======
| Attribute | Description | Attribute | Description
| `user` | The authenticated user. | `principal` | The _effective_ (impersonated) username. Usually this is
| `realm` | The realm that authenticated the user. the same as the _authenticated_ username.
| `uri` | The REST endpoint URI. | `run_by_principal` | The _authenticated_ (impersonator) username.
| `params` | The REST URI query parameters. This attribute is present only if the request is
| `request_body` | The body of the request, if enabled. using the <<run-as-privilege, run as authorization functionality>>.
Otherwise, the _effective_ user is the same as the
_authenticated_ one, which is indicated by the `principal`
attribute.
| `realm` | The realm that authenticated the user.
| `uri` | The REST endpoint URI.
| `params` | The REST URI query parameters.
| `request_body` | The body of the request, if enabled.
|====== |======
.REST authentication_failed attributes .REST authentication_failed attributes
[cols="2,7",options="header"] [cols="2,7",options="header"]
|====== |======
| Attribute | Description | Attribute | Description
| `origin_address` | The IP address from which the request originated. | `principal` | The principal (username) that failed authentication.
| `principal` | The principal (username) that failed authentication. If the request's authentication token is invalid, this
| `uri` | The REST endpoint URI. information might be missing.
| `request_body` | The body of the request, if enabled. | `uri` | The REST endpoint URI.
| `request_body` | The body of the request, if enabled.
|====== |======
.REST realm_authentication_failed attributes .REST realm_authentication_failed attributes
[cols="2,7",options="header"] [cols="2,7",options="header"]
|====== |======
| Attribute | Description | Attribute | Description
| `origin_address` | The IP address from which the request originated. | `realm` | The realm that failed to authenticate the user.
| `principal` | The principal (username) that failed authentication. **A separate entry is logged for each consulted realm.**
| `uri` | The REST endpoint URI. | `principal` | The principal (username) that failed authentication.
| `request_body` | The body of the request, if enabled. | `uri` | The REST endpoint URI.
| `realm` | The realm that failed to authenticate the user. | `request_body` | The body of the request, if enabled.
NOTE: A separate entry is logged for each |======
consulted realm.
.REST tampered_request attributes
[cols="2,7",options="header"]
|======
| Attribute | Description
| `uri` | The REST endpoint URI.
| `request_body` | The body of the request, if enabled.
|====== |======
.Transport anonymous_access_denied attributes .Transport anonymous_access_denied attributes
[cols="2,7",options="header"] [cols="2,7",options="header"]
|====== |======
| Attribute | Description | Attribute | Description
| `origin_type` | Where the request originated: `rest` (request | `origin_type` | Where the request originated: `rest` (request
originated from a REST API request), `transport` originated from a REST API request), `transport`
(request was received on the transport channel), (request was received on the transport channel), or
`local_node` (the local node issued the request). `local_node` (the local node issued the request).
| `origin_address` | The IP address from which the request originated. | `action` | The name of the action that was executed.
| `action` | The name of the action that was executed. | `indices` | A comma-separated list of indices this request
| `request` | The type of request that was executed. pertains to (when applicable).
| `indices` | A comma-separated list of indices this request | `request` | The type of request that was executed.
pertains to (when applicable).
|====== |======
.Transport authentication_success attributes .Transport authentication_success attributes
[cols="2,7",options="header"] [cols="2,7",options="header"]
|====== |======
| Attribute | Description | Attribute | Description
| `origin_type` | Where the request originated: `rest` (request | `origin_type` | Where the request originated: `rest` (request
originated from a REST API request), `transport` originated from a REST API request), `transport`
(request was received on the transport channel), (request was received on the transport channel), or
`local_node` (the local node issued the request). `local_node` (the local node issued the request).
| `origin_address` | The IP address from which the request originated. | `principal` | The _effective_ (impersonated) username. Usually this is
| `user` | The authenticated user. the same as the _authenticated_ username.
| `realm` | The realm that authenticated the user. | `run_by_principal` | The _authenticated_ (impersonator) username.
| `action` | The name of the action that was executed. This attribute is present only if the request is
| `request` | The type of request that was executed. using the <<run-as-privilege, run as authorization functionality>>.
Otherwise, the _effective_ and the _authenticated_
users are equivalent and are indicated by the
`principal` attribute.
| `realm` | The realm that authenticated the user.
| `action` | The name of the action that was executed.
| `indices` | A comma-separated list of indices this request
pertains to (when applicable).
| `request` | The type of request that was executed.
|====== |======
.Transport authentication_failed attributes .Transport authentication_failed attributes
[cols="2,7",options="header"] [cols="2,7",options="header"]
|====== |======
| Attribute | Description | Attribute | Description
| `origin_type` | Where the request originated: `rest` (request | `origin_type` | Where the request originated: `rest` (request
originated from a REST API request), `transport` originated from a REST API request), `transport`
(request was received on the transport channel), (request was received on the transport channel), or
`local_node` (the local node issued the request). `local_node` (the local node issued the request).
| `origin_address` | The IP address from which the request originated. | `principal` | The _effective_ (impersonated) username. Usually this is
| `principal` | The principal (username) that failed authentication. the same as the _authenticated_ username. If the
| `action` | The name of the action that was executed. request's authentication token is invalid, this
| `request` | The type of request that was executed. information might be missing.
| `indices` | A comma-separated list of indices this request | `run_by_principal` | The _authenticated_ (impersonator) username.
pertains to (when applicable). This attribute is present only if the request is
using the <<run-as-privilege, run as authorization functionality>>.
Otherwise, the _effective_ and the _authenticated_
users are equivalent and are indicated by the
`principal` attribute.
| `action` | The name of the action that was executed.
| `indices` | A comma-separated list of indices this request
pertains to (when applicable).
| `request` | The type of request that was executed.
|====== |======
.Transport realm_authentication_failed attributes .Transport realm_authentication_failed attributes
[cols="2,7",options="header"] [cols="2,7",options="header"]
|====== |======
| Attribute | Description | Attribute | Description
| `origin_type` | Where the request originated: `rest` (request | `realm` | The realm that failed to authenticate the user.
originated from a REST API request), `transport` **A separate entry is logged for each consulted realm.**
(request was received on the transport channel), | `origin_type` | Where the request originated: `rest` (request
`local_node` (the local node issued the request). originated from a REST API request), `transport`
| `origin_address` | The IP address from which the request originated. (request was received on the transport channel), or
| `principal` | The principal (username) that failed authentication. `local_node` (the local node issued the request).
| `action` | The name of the action that was executed. | `principal` | The principal (username) that failed authentication.
| `request` | The type of request that was executed. | `action` | The name of the action that was executed.
| `indices` | A comma-separated list of indices this request | `indices` | A comma-separated list of indices this request
pertains to (when applicable). pertains to (when applicable).
| `realm` | The realm that failed to authenticate the user. | `request` | The type of request that was executed.
NOTE: A separate entry is logged for each
consulted realm.
|====== |======
.Transport access_granted attributes .Transport access_granted attributes
[cols="2,7",options="header"] [cols="2,7",options="header"]
|====== |======
| Attribute | Description | Attribute | Description
| `origin_type` | Where the request originated: `rest` (request | `origin_type` | Where the request originated: `rest` (request
originated from a REST API request), `transport` originated from a REST API request), `transport`
(request was received on the transport channel), (request was received on the transport channel), or
`local_node` (the local node issued the request). `local_node` (the local node issued the request).
| `origin_address` | The IP address from which the request originated. | `principal` | The _effective_ (impersonated) username for which
| `principal` | The principal (username) that passed authentication. authorization succeeded. Unless the request is using
| `roles` | The set of roles granting permissions. the <<run-as-privilege, run as authorization functionality>>,
| `action` | The name of the action that was executed. the _effective_ and _authenticated_ usernames are equivalent.
| `request` | The type of request that was executed. | `realm` | The realm name that `principal` belongs to.
| `indices` | A comma-separated list of indices this request | `run_by_principal` | The _authenticated_ (impersonator) username.
pertains to (when applicable). This attribute is present only if the request is
using the <<run-as-privilege, run as authorization functionality>>.
Otherwise, the _effective_ and the _authenticated_
usernames are equivalent and are indicated by the
`principal` attribute.
| `run_by_realm` | The realm name that `run_by_principal` belongs to
(when applicable).
| `roles` | The set of roles granting permissions.
| `action` | The name of the action that was executed.
| `indices` | A comma-separated list of indices this request
pertains to (when applicable).
| `request` | The type of request that was executed.
|====== |======
.Transport access_denied attributes .Transport access_denied attributes
[cols="2,7",options="header"] [cols="2,7",options="header"]
|====== |======
| Attribute | Description | Attribute | Description
| `origin_type` | Where the request originated: `rest` (request | `origin_type` | Where the request originated: `rest` (request
originated from a REST API request), `transport` originated from a REST API request), `transport`
(request was received on the transport channel), (request was received on the transport channel), or
`local_node` (the local node issued the request). `local_node` (the local node issued the request).
| `origin_address` | The IP address from which the request originated. | `principal` | The _effective_ (impersonated) username for which
| `principal` | The principal (username) that failed authentication. authorization failed. Unless the request is using
| `roles` | The set of roles granting permissions. the <<run-as-privilege, run as authorization functionality>>,
| `action` | The name of the action that was executed. the _effective_ and the _authenticated_ usernames are
| `request` | The type of request that was executed. equivalent.
| `indices` | A comma-separated list of indices this request | `realm` | The realm name that `principal` belongs to.
relates to (when applicable). | `run_by_principal` | The _authenticated_ (impersonator) username.
This attribute is present only if the request is
using the <<run-as-privilege, run as authorization functionality>>.
Otherwise, the _effective_ and the _authenticated_
usernames are equivalent and are indicated by the
`principal` attribute.
| `run_by_realm` | The realm name that `run_by_principal` belongs to
(when applicable).
| `roles` | The set of roles granting permissions.
| `action` | The name of the action that was executed.
| `indices` | A comma-separated list of indices this request
relates to (when applicable).
| `request` | The type of request that was executed.
|======
.Transport run_as_granted attributes
[cols="2,7",options="header"]
|======
| Attribute | Description
| `origin_type` | Where the request originated: `rest` (request
originated from a REST API request), `transport`
(request was received on the transport channel), or
`local_node` (the local node issued the request).
| `principal` | The _authenticated_ (_impersonator_) username for which
the impersonation operation was granted.
| `realm` | The realm name that the _authenticated_ user belongs to.
| `run_as_principal` | The _impersonated_ username.
| `run_as_realm` | The realm name that the _impersonated_ username belongs to.
| `roles` | The set of roles granting permissions.
| `action` | The name of the action that was executed.
| `indices` | A comma-separated list of indices this request
relates to (when applicable).
| `request` | The type of request that was executed.
|======
.Transport run_as_denied attributes
[cols="2,7",options="header"]
|======
| Attribute | Description
| `origin_type` | Where the request originated: `rest` (request
originated from a REST API request), `transport`
(request was received on the transport channel), or
`local_node` (the local node issued the request).
| `principal` | The _authenticated_ (_impersonator_) username for which
the impersonation operation was denied.
| `realm` | The realm name that the _authenticated_ user belongs to.
| `run_as_principal` | The _impersonated_ username.
| `run_as_realm` | The realm name that the _impersonated_ username belongs to.
| `roles` | The set of roles granting permissions.
| `action` | The name of the action that was executed.
| `indices` | A comma-separated list of indices this request
relates to (when applicable).
| `request` | The type of request that was executed.
|====== |======
.Transport tampered_request attributes .Transport tampered_request attributes
[cols="2,7",options="header"] [cols="2,7",options="header"]
|====== |======
| Attribute | Description | Attribute | Description
| `origin_type` | Where the request originated: `rest` (request | `origin_type` | Where the request originated: `rest` (request
originated from a REST API request), `transport` originated from a REST API request), `transport`
(request was received on the transport channel), (request was received on the transport channel), or
`local_node` (the local node issued the request). `local_node` (the local node issued the request).
| `origin_address` | The IP address from which the request originated. | `principal` | The _effective_ (impersonated) username. Unless the request
| `principal` | The principal (username) that failed to authenticate. is using the <<run-as-privilege, run as authorization functionality>>,
| `action` | The name of the action that was executed. the _effective_ and the _authenticated_ usernames are
| `request` | The type of request that was executed. equivalent. If the requests's authentication token is
| `indices` | A comma-separated list of indices this request invalid, this information might be missing.
pertains to (when applicable). | `run_by_principal` | The _authenticated_ (impersonator) username.
This attribute is present only if the request is
using the <<run-as-privilege, run as authorization functionality>>.
Otherwise, the _effective_ and the _authenticated_ usernames
are equivalent and are indicated by the `principal` attribute.
| `action` | The name of the action that was executed.
| `indices` | A comma-separated list of indices this request
pertains to (when applicable).
| `request` | The type of request that was executed.
|====== |======
.IP filter connection_granted attributes .IP filter connection_granted attributes
[cols="2,7",options="header"] [cols="2,7",options="header"]
|====== |======
| Attribute | Description | Attribute | Description
| `origin_address` | The IP address from which the request originated.
| `transport_profile` | The transport profile the request targeted. | `transport_profile` | The transport profile the request targeted.
| `rule` | The <<ip-filtering, IP filtering>> rule that granted | `rule` | The <<ip-filtering, IP filtering>> rule that granted
the request. the request.
@ -235,7 +506,6 @@ The log level determines which attributes are included in a log entry.
[cols="2,7",options="header"] [cols="2,7",options="header"]
|====== |======
| Attribute | Description | Attribute | Description
| `origin_address` | The IP address from which the request originated.
| `transport_profile` | The transport profile the request targeted. | `transport_profile` | The transport profile the request targeted.
| `rule` | The <<ip-filtering, IP filtering>> rule that denied | `rule` | The <<ip-filtering, IP filtering>> rule that denied
the request. the request.