Filter syntax for audit results

Appropriate Vault Enterprise license required

As of Vault 1.16.0, you can enable audit devices with a filter option to limit the audit entries written to a particular audit log and fine-tune your auditing process.

Proceed with caution

Filtering audit logs is an advanced feature. Exclusively enabling filtered devices without configuring an audit fallback may lead to gaps in your audit logs.

Always test your audit configuration in a non-production environment before deploying filters to production. And make sure to read the Vault security model and filtering overview to familiarize yourself with Vault auditing and filtering basics before enabling filtered audit devices.

Once you enable an audit device with a filter, every audit entry Vault sends to that audit device is compared to the predicate expression in the filter. Only audit entries that match the filter are written to the audit log for the device.

When you enable filtered audit devices, the behavior of any existing audit device and the behavior of new audit devices that do not use filters remain unchanged.

Fallback auditing devices

Filtering adds flexibility to your auditing workflows, but filtering also adds complexity that can lead to entries missing from your logs by mistake. For example, writing audit entries to one device for (N < 10) and another device for (N > 10)would exclude audit entries where (N == 10), which may not be the intended behavior.

The fallback audit device saves all audit entries that would otherwise get filtered out and dropped from the audit record. Enabling an audit device with the fallback parameter ensures that Vault continues to adhere to the default security model which mandates that all requests and responses must be successfully logged before clients receive secret material.

Vault installations that use filtered audit devices exclusively, should always configure a fallback audit device to guarantee a comparable security standard as Vault installations that only use standard, non-filtered audit devices.

You can only have 1 fallback device

Choose your fallback audit device carefully. You can only designate one fallback audit device for the entire Vault installation out of all your active audit devices.

Fallback telemetry metrics

When the fallback device successfully writes an audit entry to the audit log, Vault emits a fallback 'success' metric.

If you enable filtering without a fallback device, Vault emits a fallback 'miss' metric metric anytime an audit entry would have been written to the fallback device, so you can track how many auditable events you have lost.

Audit device limitations

You cannot add filtering to an existing audit device.
You can configure filtering when enabling one of the following supported audit device types:
You can only designate one auditing fallback device.

Filtering and test messages

By default, Vault sends a test message to the audit device when you enable it. Depending on how you configure your filters, the default test message may fail the predicate expression and not write to the new device.

You can determine whether the test message should appear in the sink for the newly enabled audit device based on the following property table, which are common to all default test messages.

Property	Value
`mount_point`	empty
`mount_type`	empty
`namespace`	empty
`operation`	`update`
`path`	`sys/audit/test`

`filter` properties for audit devices

Filters can only reference the following properties of an audit entry:

Property	Example	Description
`mount_point`	`mount_point == \"auth/oidc\"`	Log all entries for the `auth/oidc` mount point
`mount_type`	`mount_type == \"kv-v2\"`	Log all entries from `kv-v2` plugins
`namespace`	`namespace != \"admin/\"`	Log all entries not in the admin namespace
`operation`	`operation == \"read\"`	Log all read operations
`path`	`path == \"auth/approle/login\"`	Log all activity against the AppRole login path

Root namespaces are unnamed

Non-root namespace paths must end with a trailing slash (/) to match correctly. But the root namespace does not have a path and only matches to an empty string. To match to the root namespace in your filter use \"\". For example, namespace != \"\" matches any audited request not in the root namespace.

A practical example

Assume you already have an audit file called vault-audit.log but you want to filter your audit entries and persist all the key/value (kv) type events to a specific audit log file called kv-audit.log.

To filter the events:

Enable a file audit device with a mount_type filter:

vault audit enable                \
  -path kv-only                   \
  file                            \
  filter="mount_type == \"kv\""   \
  file_path=/logs/kv-audit.log

Enable a fallback device:

vault audit enable                \
  -path=my-fallback               \
  -description="fallback device"  \
  file                            \
  fallback=true                   \
  file_path=/tmp/kv-audit.fallback.log

Confirm the audit devices are enabled:
```
  vault audit list --detailed
```

Enable a new kv secrets engine called my-kv:

  vault secrets enable -path my-kv kv-v2

Write secret data to the kv engine:

  vault kv put -mount=my-kv my_secret the_value=always_angry

The /var/kv-audit.log now includes four entries in total:

the command request that enabled my-kv
the response entry from enabling my-kv
the command request that wrote a secret to my-kv
the response entry from writing the secret to my-kv.

The fallback device captured entries for the other commands. And the original audit file, vault-audit.log, continues to capture all audit events.