Audit Device Notes

Avatar
Brian Shumate
  • Updated

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 here
  • time: Timestamp as detailed in the Audit Log Time Format section
  • type: Type of log entry, either request or response

Auth Fields

These fields represent authentication related details:

  • client_token: HMAC SHA256 of the client token id
  • accessor: HMAC SHA256 of the client token accessor
  • display_name: The configured role display name
  • policies: a list of policies
  • token_policies: list of policies associated with the token
  • metadata: token metadata
    • role_name: Configured name of the auth method role
  • remaining_uses: Number of uses remaining for the token
  • entity_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 request
  • operation: Type of operation (create, list, read, update)
  • client_token: HMAC SHA256 of the client token id
  • client_token_accessor: HMAC SHA256 of the client token accessor
  • path: Path to the request
  • data: content of any data passed to the request
  • policy_override: true if a Sentinel soft-mandatory policy override was requested
  • remote_address: Address of the remote host initiating request
  • wrap_ttl: The response wrapping time to live for a wrapped token
  • headers: 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 here
  • time: Timestamp as detailed in the Audit Log Time Format section
  • type: Type of log entry, either request or response

Auth Fields

These fields represent authentication related details:

  • client_token: HMAC SHA256 of the client token id
  • accessor: HMAC SHA256 of the client token accessor
  • display_name: The configured role display name
  • policies: a list of policies
  • token_policies: list of policies associated with the token
  • metadata: token metadata
    • role_name: Configured name of the auth method role
  • remaining_uses: Number of uses remaining for the token
  • entity_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 request
  • operation: Type of operation (create, list, read, update)
  • client_token: HMAC SHA256 of the client token id
  • client_token_accessor: HMAC SHA256 of the client token accessor
  • path: Path to the request
  • data: content of any data passed to the request
  • policy_override: true if a Sentinel soft-mandatory policy override was requested
  • remote_address: Address of the remote host initiating request
  • wrap_ttl: The response wrapping time to live for a wrapped token
  • headers: Content of any HTTP headers which were part of request

Response Fields

These fields represent details about the response:

  • data: Contains the token’s data
    • accessor: HMAC SHA256 of the client token accessor
    • creation_time: Epoch timestamp representing creation time of token
    • creation_ttl: Token time to live at creation time in seconds
    • display_name: The configured role display name
    • entity_id: The Identity entity ID attached to the token, if any
    • expire_time: Token expiration time
    • explicit_max_ttl: Token’s explicit maximum time to live
    • id: HMAC SHA256 of the client token id
    • issue_time: Timestamp representing token issue time (same as creation time)
    • meta: Token metadata
      • role_name: HMAC SHA256 of the role name
    • num_uses: Remaining number of token uses
    • orphan: True is token is an orphan
    • path: HMAC SHA256 of response path
    • policies: token policies
      • HMAC SHA256 of policy name
    • renewable: true if token is renewable
    • ttl: 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.

Resources

  1. Audit Devices
  2. Audit Device: File
  3. Audit Device: Syslog
  4. Audit Device: Socket
  5. Tune Auth Method
  6. audit_non_hmac_request_keys
  7. audit_non_hmac_response_keys

Articles in this section

See more

Related articles