This article shares some generally useful notes about Vault’s Audit Device system and specifics on the Audit Device log format.
Audit Log Time Format
All Audit Device logging in Vault versions prior to version 0.9.0 uses the RFC3339 time format through the Go standard library time package at a resolution of 1 second.
After Vault version 0.9.0 the resolution is increased to the nanosecond level by using RFC3339Nano.
Comparison of the formats is shown below, taken from the package constants:
- RFC3339 = “2006-01-02T15:04:05Z07:00”
- RFC3339Nano = “2006-01-02T15:04:05.999999999Z07:00”
This level of precision can cause sorting issues in log file aggregation and analysis, but please keep in mind that the design decision to change was driven by a requirement for more precise log entries.
Audit Log List Output
Here is an example detailed Audit Device list output from Vault configured with multiple Audit Devices:
$ vault audit list -detailed
Path Type Description Replication Options
---- ---- ----------- ----------- -------
file/ file n/a replicated description=File audit device file_path=/vault/logs/audit.log
socket/ socket n/a replicated socket_type=tcp address=10.10.42.111:7474
This output shows three Audit Devices enabled. Here are their details:
- Path: this is the vault internal path, not to be confused with filesytem path
- Type: the Audit Device type; one of file, socket, or syslog
- Description: optional device description
- Replicated Behavior: whether the audit log backend is local or replicated
- Options: device specific options, such as hostnames, paths, and syslog facilities. See the individual Audit Devices
Audit Log Output Description
The following provides some examples of Audit Device log output and description of the fields contained within the output.
NOTE: The Audit Device log format is JSON by default.
This example demonstrates a login with the AppRole Auth Method. Upon login, the following two entries are present in the audit log representing an entry for the request and response respectively.
Request Log Entry Example
The following is an request Audit Device log entry:
{
"time": "2018-07-13T14:15:07.8425825Z",
"type": "request",
"auth": {
"client_token": "hmac-sha256:bb69c1b39b8ddf0e3f07abcc1c6074c4b0c0b4cb5b9a3d5227982d66424cc666",
"accessor": "hmac-sha256:9859b159f58e84bd0bd0ffa2f99960734e917083f658ecdc01ab4b9d61b5c74d",
"display_name": "vaultron-approle",
"policies": [
"default",
"sudo",
"vaultron-dev"
],
"token_policies": [
"default",
"sudo",
"vaultron-dev"
],
"metadata": {
"role_name": "approle-d73ec724"
},
"remaining_uses": 999999,
"entity_id": "48f3f5f3-fe6d-03f9-79a3-cf12b312ec67"
},
"request": {
"id": "03f3f487-974b-b8f2-8162-77223a6e57d5",
"operation": "read",
"client_token": "hmac-sha256:bb69c1b39b8ddf0e3f07abcc1c6074c4b0c0b4cb5b9a3d5227982d66424cc666",
"client_token_accessor": "hmac-sha256:9859b159f58e84bd0bd0ffa2f99960734e917083f658ecdc01ab4b9d61b5c74d",
"path": "auth/token/lookup-self",
"data": null,
"policy_override": false,
"remote_address": "172.17.0.1",
"wrap_ttl": 0,
"headers": {}
},
"error": ""
}
The request (noted here by type
of request
) contains two sections, the auth
section and the request
section; each of these in turn contain fields relevant to that section.
Main Fields
These fields are part of any log entry and denote the time, type, and related errors:
error
: If there is an error in the request, it will be contained heretime
: Timestamp as detailed in the Audit Log Time Format sectiontype
: Type of log entry, eitherrequest
orresponse
Auth Fields
These fields represent authentication related details:
client_token
: HMAC SHA256 of the client token idaccessor
: HMAC SHA256 of the client token accessordisplay_name
: The configured role display namepolicies
: a list of policiestoken_policies
: list of policies associated with the tokenmetadata
: token metadatarole_name
: Configured name of the auth method role
remaining_uses
: Number of uses remaining for the tokenentity_id
: The Identity entity ID attached to the token, if any
Request Fields
These fields represent details about the request:
id
: Unique identifier for the requestoperation
: Type of operation (create, list, read, update)client_token
: HMAC SHA256 of the client token idclient_token_accessor
: HMAC SHA256 of the client token accessorpath
: Path to the requestdata
: content of any data passed to the requestpolicy_override
: true if a Sentinelsoft-mandatory
policy override was requestedremote_address
: Address of the remote host initiating requestwrap_ttl
: The response wrapping time to live for a wrapped tokenheaders
: Content of any HTTP headers which were part of request
Response Log Entry Example
The following is an response Audit Device log entry:
{
"time": "2018-07-13T14:15:07.8436007Z",
"type": "response",
"auth": {
"client_token": "hmac-sha256:bb69c1b39b8ddf0e3f07abcc1c6074c4b0c0b4cb5b9a3d5227982d66424cc666",
"accessor": "hmac-sha256:9859b159f58e84bd0bd0ffa2f99960734e917083f658ecdc01ab4b9d61b5c74d",
"display_name": "vaultron-approle",
"policies": [
"default",
"sudo",
"vaultron-dev"
],
"token_policies": [
"default",
"sudo",
"vaultron-dev"
],
"metadata": {
"role_name": "apprulez-d73ec724"
},
"remaining_uses": 999999,
"entity_id": "48f3f5f3-fe6d-03f9-79a3-cf12b312ec67"
},
"request": {
"id": "03f3f487-974b-b8f2-8162-77223a6e57d5",
"operation": "read",
"client_token": "hmac-sha256:bb69c1b39b8ddf0e3f07abcc1c6074c4b0c0b4cb5b9a3d5227982d66424cc666",
"client_token_accessor": "hmac-sha256:9859b159f58e84bd0bd0ffa2f99960734e917083f658ecdc01ab4b9d61b5c74d",
"path": "auth/token/lookup-self",
"data": null,
"policy_override": false,
"remote_address": "172.17.0.1",
"wrap_ttl": 0,
"headers": {}
},
"response": {
"data": {
"accessor": "hmac-sha256:9859b159f58e84bd0bd0ffa2f99960734e917083f658ecdc01ab4b9d61b5c74d",
"creation_time": 1531491265,
"creation_ttl": 1296000,
"display_name": "hmac-sha256:8a7d70ae0adb7190f26cbeed674d1d7d25700e5cedc438b614e7f821e14bd863",
"entity_id": "hmac-sha256:d16cdb195a5ef53809d0aeffbb04a382ce0e4420a929046d72d7de13945cebdd",
"expire_time": "2018-07-28T14:14:25.7039896Z",
"explicit_max_ttl": 0,
"id": "hmac-sha256:bb69c1b39b8ddf0e3f07abcc1c6074c4b0c0b4cb5b9a3d5227982d66424cc666",
"issue_time": "2018-07-13T14:14:25.7039831Z",
"meta": {
"role_name": "hmac-sha256:b3fe57400d637c68b677acf39ff1c7c9610a251915206bbcb8e12969a4cd665b"
},
"num_uses": 999998,
"orphan": true,
"path": "hmac-sha256:e68ab13e5778b151d856f8f00c8e02357bd3169408a39f44b138e901fcd68aea",
"policies": [
"hmac-sha256:2df25b57897b1ed3c74e4e24d5c6c36baec9be1fac5101200c64b2331a717dd1",
"hmac-sha256:c74da106b2e8e9176b84782c6e21131a0c06d6d1b4dcd476f5e9fad3d0721f81",
"hmac-sha256:1ddeb5854b7847f2b53623859f358d6675c54cc6654f48b2b37c7153bf8c0a6f"
],
"renewable": true,
"ttl": 1295957
}
},
"error": ""
}
The response (denoted here by type
of response
) contains three sections, the auth
section, the request
section, and the response
section; each of these in turn contain fields relevant to that section.
Main Fields
These fields are part of any log entry and denote the time, type, and related errors:
error
: If there is an error in the request, it will be contained heretime
: Timestamp as detailed in the Audit Log Time Format sectiontype
: Type of log entry, eitherrequest
orresponse
Auth Fields
These fields represent authentication related details:
client_token
: HMAC SHA256 of the client token idaccessor
: HMAC SHA256 of the client token accessordisplay_name
: The configured role display namepolicies
: a list of policiestoken_policies
: list of policies associated with the tokenmetadata
: token metadatarole_name
: Configured name of the auth method role
remaining_uses
: Number of uses remaining for the tokenentity_id
: The Identity entity ID attached to the token, if any
Request Fields
These fields represent details about the request:
id
: Unique identifier for the requestoperation
: Type of operation (create, list, read, update)client_token
: HMAC SHA256 of the client token idclient_token_accessor
: HMAC SHA256 of the client token accessorpath
: Path to the requestdata
: content of any data passed to the requestpolicy_override
: true if a Sentinelsoft-mandatory
policy override was requestedremote_address
: Address of the remote host initiating requestwrap_ttl
: The response wrapping time to live for a wrapped tokenheaders
: Content of any HTTP headers which were part of request
Response Fields
These fields represent details about the response:
data
: Contains the token’s dataaccessor
: HMAC SHA256 of the client token accessorcreation_time
: Epoch timestamp representing creation time of tokencreation_ttl
: Token time to live at creation time in secondsdisplay_name
: The configured role display nameentity_id
: The Identity entity ID attached to the token, if anyexpire_time
: Token expiration timeexplicit_max_ttl
: Token’s explicit maximum time to liveid
: HMAC SHA256 of the client token idissue_time
: Timestamp representing token issue time (same as creation time)meta
: Token metadatarole_name
: HMAC SHA256 of the role name
num_uses
: Remaining number of token usesorphan
: True is token is an orphanpath
: HMAC SHA256 of response pathpolicies
: token policies- HMAC SHA256 of policy name
renewable
: true if token is renewablettl
: Token time to live
Note on HMAC’d Fields
Certain potentially sensitive fields are HMAC’ed by default; you can compare a known value to the HMAC by using the /sys/audit-hash API or if you’d prefer that certain fields are not HMAC’d, you can exclude the fields in the Auth Method’s role configuration with the Tune Auth Method API and specifically these options:
- audit_non_hmac_request_keys to specify a comma-separated list of keys that will not be HMAC’d by Audit Devices in the request data object
- audit_non_hmac_response_keys to specify a comma-separated list of keys that will not be HMAC’d by Audit Devices in the response data object
Configuring File Audit Device with /dev/null
A tip that can help with initial Audit Device log setup: you can prevent a mistake in configuration resulting in a blocked Audit Device by enabling a temporary file based Audit Device using /dev/null
on Linux:
$ vault audit enable -path=audit-temp file file_path=/dev/null
Success! Enabled the file Audit Device at: audit-temp/
When you have successfully configured all Audit Devices, you can then disable the temporary device.