|
| 1 | +--- |
| 2 | +layout: docs |
| 3 | +page_title: Audit logging best practices |
| 4 | +description: Recommendations for setting up audit logging in HashiCorp Vault. |
| 5 | +--- |
| 6 | + |
| 7 | +# Best practices for audit logging |
| 8 | + |
| 9 | +The following recommendations apply generally to most Vault deployments. You should always independently evaluate whether a given recommendation makes sense in the context of your deployment and use of Vault. |
| 10 | + |
| 11 | +## Test configuration changes |
| 12 | + |
| 13 | +Always test your audit logging changes in a non-production environment that closely mirrors your production environment. Your test environment should include performance benchmarking under production-like loads and match in all aspects relevant to the audit logging configuration you want to test. |
| 14 | + |
| 15 | +## Enable audit devices at cluster initialization |
| 16 | + |
| 17 | +Enable at least one audit device immediately after you initialize a new Vault cluster, and ensure that the configuration of your audit device is [valid for all Vault cluster nodes](/vault/docs/audit#enabling-and-disabling-audit-devices). |
| 18 | + |
| 19 | +Audit logging is disabled by default on new Vault clusters. By enabling at least one audit device post-initialization, you ensure that Vault will audit all subsequent API requests, including those for initial cluster configuration and root token revocation. |
| 20 | + |
| 21 | +## Enable at least two audit devices |
| 22 | + |
| 23 | +Enable at least two audit devices, of different types, on each Vault cluster. Configure *at least one* of those devices to forward logs to a remote system for analysis and long-term storage. |
| 24 | + |
| 25 | +Vault does not respond to client requests it cannot log. Enabling at least two audit devices reduces the risk of Vault not responding to client requests when the only audit device becomes partially or fully unavailable. |
| 26 | + |
| 27 | +<Warning> |
| 28 | + |
| 29 | + Vault sends each audit log entry to all enabled devices, and guarantees that it writes the audit log entry successfully to at least one audit device. To ensure that you have a complete record of all API requests and responses, you **must** analyze audit log entries across all configured devices. You may deduplicate audit log entries based on the value of `.request.id`. |
| 30 | + |
| 31 | +</Warning> |
| 32 | + |
| 33 | +<Tabs> |
| 34 | + |
| 35 | +<Tab heading="File devices"> |
| 36 | + |
| 37 | +If you enable a `file` audit device, use a dedicated volume or partition for Vault's audit logs to protect against other workloads on the system taking up the disk space intended for your log files. |
| 38 | + |
| 39 | +Additionally, establish a log rotation process that is appropriate for your organization, deployment, and policies, using a purpose-built system like *logrotate*. Configure your log rotation system to send Vault an `HUP` signal, which causes Vault to start writing audit log entries to the new log file. |
| 40 | + |
| 41 | +<Tip title="Logging with Kubernetes"> |
| 42 | + |
| 43 | + When running Vault on a Kubernetes cluster, a common approach is to configure a `file` audit device with `file_path` set to `stdout`. Vault will write audit logs to the standard output for the container, which lets you process the logs with a Kubernetes cluster-level log collector. |
| 44 | + |
| 45 | + If you choose this approach, we suggest configuring the audit device with a `prefix`, so your log collector can separate audit logs from server logs. |
| 46 | + |
| 47 | +</Tip> |
| 48 | + |
| 49 | +</Tab> |
| 50 | + |
| 51 | +<Tab heading="Syslog devices"> |
| 52 | + |
| 53 | +To configure a `syslog` audit device, you must deploy Vault on Unix, and you must use the default syslog service running on the same host as the Vault server. If you enable a `syslog` audit device, use a TCP listener so that Vault can record large audit log entries that may exceed the size limit of UDP listeners. |
| 54 | + |
| 55 | +</Tab> |
| 56 | + |
| 57 | +<Tab heading="Socket devices"> |
| 58 | + |
| 59 | +If you configure a `socket` audit device, configure a local service to bind a Unix socket. |
| 60 | + |
| 61 | +Socket devices using TCP and UDP listeners can result in lost audit log data if the TCP connection is interrupted or the receiving UDP endpoint becomes unavailable. Using a local socket helps protect against data loss. |
| 62 | + |
| 63 | +</Tab> |
| 64 | + |
| 65 | +</Tabs> |
| 66 | + |
| 67 | +## Configure audit devices |
| 68 | + |
| 69 | +Review the configuration options that are specific to the type of audit device, as well as those [common](/vault/api-docs/system/audit#parameters) to all audit device types, and ensure that you configure all audit devices in a way that is appropriate for your organization and deployment. |
| 70 | + |
| 71 | +In general, we recommend the following options for all audit devices: |
| 72 | + |
| 73 | +- Set `elide_list_responses = true` to reduce the volume of log data produced by API list requests (see [Eliding list response bodies](/vault/docs/audit#eliding-list-response-bodies)). |
| 74 | +- Set `hmac_accessor = false`. A token accessor is generally not considered sensitive information: it does not grant any access to Vault, but rather serves as a unique identifier for a single Vault token. A token accessor enables you to [revoke](/vault/docs/commands/token/revoke) its corresponding Vault token, even when you do not know the token itself. By disabling token accessor hashing, if you identify unusual access patterns in your audit logs, you can quickly revoke the corresponding Vault token through its accessor. |
| 75 | + |
| 76 | +## Monitor audit device health |
| 77 | + |
| 78 | +Configure monitoring and alerting on the health of your audit devices through Vault telemetry and device-specific monitoring (such as available disk space, disk IOPS, and log rotation status for `file` type audit devices). |
| 79 | + |
| 80 | +Vault produces several audit logging [telemetry metrics](/vault/docs/internals/telemetry/metrics/audit). We especially recommend monitoring the following metrics for spikes, which can indicate one or more audit devices failing: |
| 81 | + |
| 82 | +- [`vault.audit.log_request_failure`](/vault/docs/internals/telemetry/metrics/audit#vault-audit-log_request_failure) |
| 83 | +- [`vault.audit.log_response_failure`](/vault/docs/internals/telemetry/metrics/audit#vault-audit-log_response_failure) |
| 84 | +- [`vault.audit.{DEVICE}.log_request`](/vault/docs/internals/telemetry/metrics/audit#vault-audit-device-log_request) |
| 85 | +- [`vault.audit.{DEVICE}.log_response`](/vault/docs/internals/telemetry/metrics/audit#vault-audit-device-log_response) |
| 86 | + |
| 87 | +## Configure attribute hashing |
| 88 | + |
| 89 | +Evaluate which request and response attributes need *not* be [hashed](/vault/docs/audit#hashing-sensitive-values) in the audit logs for each authentication backend and secrets engine mount you configure in Vault. Leave hashing enabled for attributes that are sensitive (e.g., passwords, private keys) or that may be excessively large for your audit log. |
| 90 | + |
| 91 | +You can disable hashing for individual request and response attributes with the `audit_non_hmac_request_keys` and `audit_non_hmac_response_keys` attributes in the following tuning endpoints: |
| 92 | + |
| 93 | +- [`/sys/auth/{path}/tune`](/vault/api-docs/system/auth#tune-auth-method) |
| 94 | +- [`/sys/mounts/{path}/tune`](/vault/api-docs/system/mounts#tune-mount-configuration) |
| 95 | + |
| 96 | +## Monitor suspicious activity |
| 97 | + |
| 98 | +Configure monitoring and alerting for unusual or suspicious activity in your audit logs. Examples of events to monitor include: |
| 99 | + |
| 100 | +- Root token creation |
| 101 | +- Root token usage |
| 102 | +- Modifications to audit logging configuration |
| 103 | +- Spikes in authentication failures |
| 104 | +- Spikes in permission denied failures |
0 commit comments