Intekhab Rizvi

Chapter 22 / 28

Understanding Vault Audit Devices

HashiCorp Vault For Beginners13 min read

In a secure system, knowing who did what is as important as protecting what can be done. Vault, being a system of secrets, takes this seriously.

Vault doesn't store an activity history by default. To know what happened inside your Vault—who accessed what secret, when, and how—you must enable audit devices.

Think of audit devices as Vault’s black box recorder.

What Are Audit Devices?

An audit device in Vault is a configured sink where every request and response to the Vault server gets logged—before and after Vault handles it.

Key Characteristics:

  • Immutable and append-only
  • Logs both request and response payloads
  • Logs are not stored in Vault—they go to an external system
  • Each configured device receives a full audit log entry

Audit logging is disabled by default. You must explicitly enable it.

Why Enable Audit Logging?

  • Security visibility: Know who accessed which secrets
  • Compliance: Regulatory requirements like SOC2, ISO 27001, HIPAA
  • Forensics: Investigate a leaked secret or suspicious access
  • Monitoring: Feed logs into SIEM systems for real-time alerting

Vault does not provide a built-in log viewer or dashboard—you ship the logs elsewhere for storage and analysis.

Types of Audit Devices

Audit DeviceDescription
FileWrites logs to a local file. Easy for standalone servers or testing.
SyslogForwards logs to the system’s syslog service (e.g., journald, rsyslog).
SocketSends logs to a Unix socket. Often used with log shippers.
HTTPSends logs as HTTP POST requests to a remote service. Useful for centralized logging pipelines.
Kafka (Plugin)Enterprise plugin that streams logs into Kafka.
Datadog (Plugin)Community or enterprise plugin that sends to Datadog.

For this chapter, we’ll use the file audit device, as it’s the most common starting point.

Audit Log Format

Each log entry is a JSON object with fields looks like:

{
  "time": "2025-04-14T17:22:00.123456Z",
  "type": "request",
  "auth": {
    "client_token": "hmac-sha256:...",
    "accessor": "hmac-sha256:...",
    "display_name": "approle"
  },
  "request": {
    "id": "b9b3e92b-...",
    "operation": "read",
    "path": "secret/data/production/api-key",
    "remote_address": "10.0.0.15"
  }
}

HMAC Protection: Vault never writes secrets or plaintext tokens to logs. Sensitive fields (like token, accessor, paths, and response data) are hashed with HMAC. Even if the logs leak, they don't leak secrets.

Let’s setup our lab before we start our hands-on exceises.

Step 1: Start Vault Container

Let’s begin by starting the standalone Vault container using the command below: Make sure you are at the top folder of the cloned repo.

docker run -d \
  -p 8200:8200 \
  -v $(pwd)/vault-data/config:/vault/config \
  -v $(pwd)/vault-data/file:/vault/file \
  -v $(pwd)/vault-data/logs:/vault/logs \
  -v $(pwd):/home/vault/vault-beginner \
  -e VAULT_ADDR="http://localhost:8200/" \
  --cap-add=IPC_LOCK \
  --name vault-dev \
    hashicorp/vault:latest server

Step 2: Attach to the Vault Container

Execute the following command to connect to the running Vault container:

docker exec -it vault-dev /bin/sh

Once you're inside the container, set the Vault address by exporting it as an environment variable. This ensures the Vault CLI knows where to send requests.

export VAULT_ADDR='http://127.0.0.1:8200'

Step 3: Unseal the Vault

Vault is sealed by default for security. To unseal it, you need to provide at least three unseal key shares from the initialization step in Chapter 3.

Run the following command three times, each time providing one unseal key when prompted:

vault operator unseal

Paste a different unseal key each time. After the third key, Vault will be unsealed and ready to use.

Step 4: Login to Vault

Login as root

vault login <your-root-token>

(Replace <your-root-token> with your actual root token you have received when you performed the vault operator init.)

Step 5: Pick a secure path to store logs

Before enabling an audit device, Vault needs a location to store the generated logs. Let’s begin by selecting a directory for this purpose. In our case, we’ll use /vault/logs as the designated path inside the Vault container.

Outside the container, this directory is mapped to vault-beginner/vault-data/logs on your local machine.

Make sure this directory exists and is writable by Vault before proceeding. This setup ensures that audit logs persist even if the container is restarted.

Step 6: Set the Correct Folder Permissions

To allow Vault to write audit logs to the /vault/logs directory, we need to ensure that it has the proper ownership inside the container.

Attach to the Vault container, once inside the container, run the following command to change the ownership:

chown vault:vault /vault/logs

This sets the Vault user and group as the owner of the log directory, ensuring Vault has the necessary write permissions. After this step, you're ready to enable the audit device.

Important: Logs are append-only. Never delete or edit them manually. Rotate using logrotate.

Step 7: Enabling the Audit Device

To enable auditing, we instruct Vault to log each request and response to a specified audit device—in our case, a file on disk. To activate this feature, we'll enable the file-based audit device and point it to the /vault/logs/audit.log file inside the container.

Once enabled, Vault will start appending structured log entries for each API operation. These logs are extremely detailed and include timestamps, request paths, client identity, and response status—making them essential for understanding what’s happening inside your Vault cluster.

vault audit enable file \
    file_path=/vault/logs/audit.log

You’ll see:

Success! Enabled the file audit device at: file/

You can verify the enabled audit devices by executing below command:

vault audit list

Output:

Path    Type    Description
----    ----    -----------
file/   file    n/a

Step 8: Generate Some Logs

Run a quick command:

vault kv get api-exp/app1

Then view the audit log:

cat /vault/logs/audit.log

Each entry will show type:request and type:response for every command Vault handles.

Please note, using cat alone just dumps the file contents, which is okay for small logs—but when you’re dealing with Vault’s audit logs (which can get huge), you'll want more control.

Here are some useful options and alternatives to make your cat command more effective when viewing /vault/logs/audit.log:

Command / OptionPurposeExample
cat /vault/logs/audit.logDisplays the entire log file (not ideal for large logs).cat /vault/logs/audit.log
tail -n <N>Shows the last N lines of the log. Good for recent activity.tail -n 50 /vault/logs/audit.log
tail -fContinuously displays new log entries in real-time (live view).tail -f /vault/logs/audit.log
tail -n <N> -fShows last N lines and follows new logs.tail -n 50 -f /vault/logs/audit.log
head -n <N>Displays the first N lines of the log. Useful for seeing earliest entries.head -n 20 /vault/logs/audit.log
grep "<keyword>"Filters log lines by keyword (case-sensitive).grep "transit" /vault/logs/audit.log
grep -i "<keyword>"Case-insensitive search for keyword.grep -i "LOGIN" /vault/logs/audit.log
grep -A <N> "<keyword>"Shows N lines after a match. Helpful for context.grep -A 3 "login" /vault/logs/audit.log
grep -B <N> "<keyword>"Shows N lines before a match.grep -B 3 "login" /vault/logs/audit.log

Optional: Configure Audit Log Rotation

Vault does not automatically rotate its audit log, which means the log file can grow indefinitely over time. To manage this, you can use the logrotate utility to rotate logs safely and efficiently.

Start by creating a logrotate configuration file:

sudo nano /etc/logrotate.d/vault-audit

Add the following configuration:

/vault/logs/audit.log {
  daily
  rotate 7
  compress
  missingok
  notifempty
  create 0640 vault vault
  postrotate
    systemctl kill -HUP vault
  endscript
}

Here’s a breakdown of what this does:

  • daily: Rotates the log every day.
  • rotate 7: Keeps the last 7 log files before deleting old ones.
  • compress: Compresses older logs to save space.
  • missingok: Doesn’t throw an error if the log file is missing.
  • notifempty: Skips rotation if the file is empty.
  • create 0640 vault vault: Creates a new log file with proper permissions.
  • postrotate / endscript: Sends a HUP signal to Vault, prompting it to close the current log and open a new one.

This setup ensures that Vault's audit logging remains clean, controlled, and doesn't fill up your disk over time.

Audit Log Permissions & Security

  • Store logs in a tamper-evident location (e.g., remote S3 bucket, read-only volume)
  • Use a log forwarder (e.g., FluentBit, Filebeat) to ship logs off-box
  • Lock down file access (chmod 640, only readable by Vault and log collector)
  • Regularly monitor audit logs for unusual paths or access patterns

Recap

Audit devices are Vault’s window into user behavior. They record every request and response interaction without ever logging secrets. You learned:

  • What audit devices are and why they matter
  • Different types: file, syslog, HTTP, Kafka
  • How to configure a file-based audit device
  • How to monitor and rotate your logs securely

You should now have full visibility into what happens inside your Vault.