Vault File Audit Device Practical Guide: Safe Local File Output Operations

Vault audit logs track who requested what and when, and how Vault responded — they are the foundation for accountability. The File Audit Device writes those events to a local file on the host as one JSON event per line.

This article focuses on local file output, walking through the commands and terminology commonly tested on certifications, the permissions and rotation design you cannot skip in real operations, and the security pitfalls — all at a hands-on level of detail.

Vault File Audit Device Overview and Local File Output

Vault audit devices record the metadata of every request and response. The File Audit Device is the simplest: it appends JSON lines to the path you specify. Sensitive values are HMAC-hashed by default, so plaintext is not left on disk.

Local file output fits well with single-node setups, the OS-standard logrotate, and shipper agents such as Filebeat or Fluent Bit. On certification exams, the most frequent topics are the enable/disable commands, the parameter name (file_path), and the HMAC behavior (sensitive values hashed by default).

• Strengths: simple to configure, few dependencies, fits cleanly on top of OS-standard operations
• Watch out for: files scattered across each node, permission and rotation design is mandatory, disk-full impact
• Typical use: keep a reliable local copy first, then forward to an aggregation backend separately

Flow of local file output

Check the list of audit devices

vault audit list -detailed

Enabling and Basic Configuration Commands

Enabling the device takes a single command. Create the directory in advance and set ownership and permissions so that the Vault process can write to it. By default, sensitive values are HMAC-hashed, so the default configuration does not emit plaintext.

After enabling, generate a single request (for example, vault status or a kv operation) and confirm that events are written to the file. Disable by specifying the mount path (e.g., file/).

• Required parameter: file_path=/var/log/vault/audit.log
• Recommended: set log file permissions to around 0640 and limit ownership to the vault user
• Caution: log_raw=true emits plaintext, so it should normally not be used (default is false)

Example of enable → verify → disable

sudo mkdir -p /var/log/vault
sudo chown vault:vault /var/log/vault

# Enable the audit device (local file)
vault audit enable file file_path=/var/log/vault/audit.log

# Check status
vault audit list -detailed

# Trigger an event to verify
vault status
sudo tail -n1 /var/log/vault/audit.log

# Disable (the default path name is file/)
vault audit disable file/

Audit Log Structure and How to Read It (JSON)

The File Audit Device writes one JSON event per line (i.e., NDJSON). Representative fields include time, type (request/response), request.path, request.operation, remote_address, auth info (such as policies), and whether an error occurred. Sensitive values (such as secret data or token values) are HMAC-hashed by default, and plaintext is not retained.

When you need to correlate events, the audit hash API (sys/audit-hash/<device-name>) lets you compute what HMAC value a given string would become in the log — locally. This lets you track without storing plaintext.

• JSON is complete on a per-line basis, making it easy to ingest into collection and search platforms
• HMAC is salted per audit device, so the same plaintext does not produce the same hash across different devices
• Lines with error=true are good candidates for alerting

Sample line (some fields abbreviated)

{
  "time":"2026-04-19T10:15:30.123456Z",
  "type":"request",
  "auth":{
    "client_token":"hmac-sha256:2f9c...",
    "display_name":"root",
    "policies":["root"]
  },
  "request":{
    "id":"c7b0...",
    "operation":"read",
    "path":"sys/health",
    "remote_address":"192.0.2.10",
    "data":{
      "foo":"hmac-sha256:91ab..."
    }
  },
  "response":{
    "status":200
  },
  "error":false
}

Operational Practices: Permissions, Rotation, and Monitoring

Permissions should follow least privilege. Make the audit log directory vault-owned, restrict the group to roles that actually need read access, and set files to roughly 0640. Keep read access for backup and shipper agents to the minimum necessary.

Use existing infrastructure such as the OS logrotate for rotation. The copytruncate approach is simple, but make the decision with the understanding that it may briefly drop lines. Be explicit about post-rotation permissions (the create directive), compression, and generation count. Monitoring disk usage (with thresholds and alerts) is mandatory.

• Store audit logs as highly sensitive data (encrypted volumes are recommended)
• Collect via read-only access from agents; write access should be limited to Vault
• Combine capacity, inode, and I/O latency monitoring
• In container environments, consider the stderr device plus an external log platform as an alternative

Example logrotate configuration (/etc/logrotate.d/vault-audit)

/var/log/vault/audit.log {
  weekly
  rotate 12
  compress
  dateext
  missingok
  notifempty
  create 0640 vault vault
  copytruncate
}

Security and Compliance

log_raw is disabled by default, so plaintext secrets are not emitted in the default behavior. Avoid setting log_raw=true outside of verification scenarios. Grant read permissions strictly based on separation of duties, and keep an audit trail of accesses as well.

HMAC is salted per audit device. During investigations, use the audit hash API to generate the equivalent value and compare. Retention period, encryption, and tamper detection (such as WORM) should be aligned with internal policy and external regulations (for example, finance or healthcare).

• Encrypt the audit log destination and protect the transport path with TLS
• Document retention and deletion policies and review them periodically
• Multiple audit devices can be enabled at once (combining redundancy and aggregation)

Comparing HMAC values (audit hash API example)

# When the audit device name is file/
vault write sys/audit-hash/file input="[email protected]"

Troubleshooting and Key Exam Points

When you see Permission denied or No such file or directory, check whether the directory exists, who owns it, and any SELinux / AppArmor constraints. If nothing is written to the file, distinguish between the enable state of the audit device (vault audit list) and whether you actually triggered an event (whether any operation occurred).

For exam preparation, the enable / disable / list commands, the required parameter file_path, the fact that sensitive values are HMAC-hashed by default, and the operational premise that local file output relies on OS-side rotation are all high-yield points.

• Cannot write: create the directory and adjust chown / chmod
• Log not growing: verify whether a recent operation produced an event by checking tail and timestamps
• Distributed across the cluster: understand that each node produces its own file and prepare an aggregation strategy
• Parse on the assumption of NDJSON: ingest one line = one event

One-liner for a sanity check (generate an event → confirm the most recent line)

vault kv put secret/demo foo=bar
sudo tail -n1 /var/log/vault/audit.log | jq -r '.type + " " + .request.path'

Check Your Understanding

Frequently Asked Questions