Audit logging

With a small set of exceptions, Vault audit devices record all API requests and responses in detail. An audit device can be a file, a syslog server, or a socket.

Refer to the best practices page for important considerations before you configure your audit devices.

Audit logs differ from server logs (also known as operational logs). Server logs emit information about the Vault server process, such as process errors and configuration warnings. Audit logs record the details of every request received and response sent by the Vault API. Refer to the Troubleshoot Vault tutorial for more information about server logs.

Enabling and disabling audit devices

When you initialize a new Vault cluster, auditing is disabled. You must enable audit devices with the Vault API, Vault CLI, or tools like the Terraform Vault provider.

You can set common and type-specific options when you enable a new audit device.

For example, the following command enables a file type audit device using a type-specific option to write to the file at /var/log/vault_audit.log and two common options to disable elide list responses and hashing for token accessors.

$ vault audit enable file \
    file_path=/var/log/vault_audit.log \
    hmac_accessor=false \
    elide_list_responses=true

Vault replicates audit device configurations to all nodes within a cluster. Vault Enterprise also replicates audit device configurations to performance secondary and disaster recovery secondary clusters unless you configure the audit device as local to the cluster. Before you enable an audit device, ensure that all Vault nodes to which the audit device configuration replicates can successfully log to that audit device.

When you disable an audit device, Vault immediately stops writing information to the device, but leaves the existing log information untouched.

Once you disable an audit device, you can no longer compute hashes for the associated audit log entries. Even if you re-enable the audit device at the same path, Vault creates a new hashing key for the new log entries.

Availability of audit devices

Vault sends the audit log entry of every API request and response to all enabled audit devices and guarantees that it saves to at least one of the enabled devices. As a result, if you have audit devices enabled and Vault cannot log information to at least one of the enabled devices, Vault refuses to service the corresponding API request.

When all enabled audit devices become unavailable, Vault in effect becomes unavailable as well. To prevent audit-related unavailability of Vault, HashiCorp recommends that you:

Enable at least two audit devices.
Analyze the combined audit log entries across all enabled audit devices to ensure a complete record of every API request and response.

Refer to the best practices page for additional information.

Hashing sensitive values

By default, Vault only writes a keyed hash (HMAC-SHA256) of most string values to audit logs to protect the confidentiality of potentially sensitive information.

Vault does not hash non-string values, such as integers and booleans. We recommend sending all sensitive data to Vault as string values. For example, encapsulate sensitive integer values in quotes in JSON files:

{
  "name": "sidon",
  "age": "12"
}

To calculate the keyed hash of any known value for a given audit device, use the /sys/audit-hash API endpoint.

Alternatively, you can selectively exempt specific request or response attributes from hashing for each authentication backend and secrets engine you enable.

Eliding list response bodies

Some Vault responses can be very large, especially with LIST requests. For example, listing all active leases could return a list that is tens of megabytes long.

Some audit backends cannot process individual audit records of larger sizes. To avoid overloading your audit devices, you can use the elide_list_responses option to replace keys and key_info values in audit log entries for LIST responses with the number of objects those fields contain.

Using elide_list_responses elide_list_responses improves compatibility with audit devices and reduces the amount of audit data that audit devices ingest, store, and process, while retaining some level of information about what was returned to the client.

For example, the following partial audit record shows an elided list where the keys field returns 4, instead of the actual list of keys, which would have been ["a", "b", "c", "d"]:

{
  "type": "response",
  "request": {
    "operation": "list"
  },
  "response": {
    "data": {
      "keys": 4
    }
  }
}

Logging request headers

You can use the /sys/config/auditing endpoint to configure which incoming client request headers you want Vault to record in the corresponding audit log entries.

By default, Vault records the following request headers:

Vault does not hash request header values by default. You can configure Vault to apply the keyed hash to any request header value you consider sensitive.

Exempted API endpoints

Vault does not audit requests and responses for the following API endpoints:

sys/init
sys/seal-status
sys/seal
sys/step-down
sys/unseal
sys/leader
sys/health
sys/rekey/init
sys/rekey/update
sys/rekey/verify
sys/rekey-recovery-key/init
sys/rekey-recovery-key/update
sys/rekey-recovery-key/verify
sys/storage/raft/bootstrap
sys/storage/raft/join
sys/internal/ui/feature-flags

Additionally, Vault does not audit requests to the following endpoints when the associated listener configuration allows unauthenticated access:

sys/metrics
sys/pprof/*
sys/in-flight-req

Additional resources

Recover blocked audit devices