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

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

@ -3,7 +3,9 @@
=== Audit event types
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
@ -43,31 +45,203 @@ multiple audit events. The following is a list of the events that can be generat
[[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
[cols="2,7",options="header"]
|======
| Attribute | Description
| `timestamp` | When the event occurred.
| `@timestamp` | When the event occurred.
| `node_name` | The name of the node.
| `node_host_name` | The hostname 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`
| `event_type` | The type of event that occurred: `anonymous_access_denied`,
`authentication_failed`, `access_denied`, `access_granted`,
`connection_granted`, `connection_denied`, `tampered_request`,
`run_as_granted`, `run_as_denied`.
`authentication_failed`, `authentication_success`,
`realm_authentication_failed`, `access_denied`, `access_granted`,
`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.
The log level determines which attributes are included in a log entry.
For an event in the <<audit-log-output,audit log file output>>, these are
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
[cols="2,7",options="header"]
|======
| Attribute | Description
| `origin_address` | The IP address from which the request originated.
| `uri` | The REST endpoint URI.
| `request_body` | The body of the request, if enabled.
|======
@ -76,7 +250,14 @@ The log level determines which attributes are included in a log entry.
[cols="2,7",options="header"]
|======
| Attribute | Description
| `user` | The authenticated user.
| `principal` | The _effective_ (impersonated) username. Usually this is
the same as the _authenticated_ username.
| `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_ 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.
@ -87,8 +268,9 @@ The log level determines which attributes are included in a log entry.
[cols="2,7",options="header"]
|======
| Attribute | Description
| `origin_address` | The IP address from which the request originated.
| `principal` | The principal (username) that failed authentication.
If the request's authentication token is invalid, this
information might be missing.
| `uri` | The REST endpoint URI.
| `request_body` | The body of the request, if enabled.
|======
@ -97,13 +279,19 @@ The log level determines which attributes are included in a log entry.
[cols="2,7",options="header"]
|======
| Attribute | Description
| `origin_address` | The IP address from which the request originated.
| `realm` | The realm that failed to authenticate the user.
**A separate entry is logged for each consulted realm.**
| `principal` | The principal (username) that failed authentication.
| `uri` | The REST endpoint URI.
| `request_body` | The body of the request, if enabled.
| `realm` | The realm that failed to authenticate the user.
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
@ -112,13 +300,12 @@ The log level determines which attributes are included in a log entry.
| Attribute | Description
| `origin_type` | Where the request originated: `rest` (request
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).
| `origin_address` | The IP address from which the request originated.
| `action` | The name of the action that was executed.
| `request` | The type of request 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_success attributes
@ -127,12 +314,20 @@ The log level determines which attributes are included in a log entry.
| Attribute | Description
| `origin_type` | Where the request originated: `rest` (request
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).
| `origin_address` | The IP address from which the request originated.
| `user` | The authenticated user.
| `principal` | The _effective_ (impersonated) username. Usually this is
the same as the _authenticated_ username.
| `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_
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.
|======
@ -142,33 +337,39 @@ The log level determines which attributes are included in a log entry.
| Attribute | Description
| `origin_type` | Where the request originated: `rest` (request
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).
| `origin_address` | The IP address from which the request originated.
| `principal` | The principal (username) that failed authentication.
| `principal` | The _effective_ (impersonated) username. Usually this is
the same as the _authenticated_ username. If the
request's authentication token is invalid, this
information might be missing.
| `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_
users are equivalent and are indicated by the
`principal` attribute.
| `action` | The name of the action that was executed.
| `request` | The type of request 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
[cols="2,7",options="header"]
|======
| Attribute | Description
| `realm` | The realm that failed to authenticate the user.
**A separate entry is logged for each consulted realm.**
| `origin_type` | Where the request originated: `rest` (request
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).
| `origin_address` | The IP address from which the request originated.
| `principal` | The principal (username) that failed authentication.
| `action` | The name of the action that was executed.
| `request` | The type of request that was executed.
| `indices` | A comma-separated list of indices this request
pertains to (when applicable).
| `realm` | The realm that failed to authenticate the user.
NOTE: A separate entry is logged for each
consulted realm.
| `request` | The type of request that was executed.
|======
.Transport access_granted attributes
@ -177,15 +378,26 @@ The log level determines which attributes are included in a log entry.
| Attribute | Description
| `origin_type` | Where the request originated: `rest` (request
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).
| `origin_address` | The IP address from which the request originated.
| `principal` | The principal (username) that passed authentication.
| `principal` | The _effective_ (impersonated) username for which
authorization succeeded. Unless the request is using
the <<run-as-privilege, run as authorization functionality>>,
the _effective_ and _authenticated_ usernames are equivalent.
| `realm` | The realm name that `principal` belongs to.
| `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.
| `request` | The type of request 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
@ -194,15 +406,67 @@ The log level determines which attributes are included in a log entry.
| Attribute | Description
| `origin_type` | Where the request originated: `rest` (request
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).
| `origin_address` | The IP address from which the request originated.
| `principal` | The principal (username) that failed authentication.
| `principal` | The _effective_ (impersonated) username for which
authorization failed. Unless the request is using
the <<run-as-privilege, run as authorization functionality>>,
the _effective_ and the _authenticated_ usernames are
equivalent.
| `realm` | The realm name that `principal` belongs to.
| `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.
| `request` | The type of request 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
@ -211,21 +475,28 @@ The log level determines which attributes are included in a log entry.
| Attribute | Description
| `origin_type` | Where the request originated: `rest` (request
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).
| `origin_address` | The IP address from which the request originated.
| `principal` | The principal (username) that failed to authenticate.
| `principal` | The _effective_ (impersonated) username. Unless the request
is using the <<run-as-privilege, run as authorization functionality>>,
the _effective_ and the _authenticated_ usernames are
equivalent. If the requests's authentication token is
invalid, this information might be missing.
| `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.
| `request` | The type of request 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
[cols="2,7",options="header"]
|======
| Attribute | Description
| `origin_address` | The IP address from which the request originated.
| `transport_profile` | The transport profile the request targeted.
| `rule` | The <<ip-filtering, IP filtering>> rule that granted
the request.
@ -235,7 +506,6 @@ The log level determines which attributes are included in a log entry.
[cols="2,7",options="header"]
|======
| Attribute | Description
| `origin_address` | The IP address from which the request originated.
| `transport_profile` | The transport profile the request targeted.
| `rule` | The <<ip-filtering, IP filtering>> rule that denied
the request.