Filtering audit entries

This page describes how to use filters with Vault audit devices to fine tune which audit entries should be written to an audit log.

Starting in Vault 1.16.0, audit devices can be enabled with a filter option, which is used to evaluate audit entries and determine if they should be written to a particular audit log. Please ensure you are familiar with the filtering concept before attempting to configure an audit device with a filter.

Audit devices with and without filtering configured will all function simultaneously in Vault. Using a filtered audit device does not restrict Operators from only using the filter and fallback type devices described on this page.

Advanced audit feature

The use of filtering in Vault's audit system should be considered an advanced feature. Whilst it has been designed to be simple and flexible, exclusively enabling filtered devices without a fallback configured could result in some requests and responses that are not audited.

Please see the Vault security model for further information about how all requests and responses to Vault are usually audited.

`filter` option

All audit device types (file, socket and syslog) support the filter option at the time they are enabled. After successfully enabling a device with a filter, every audit entry that Vault sends to that audit device will be compared to the expression in the filter. Only audit entries that match the filter will be written to the device's audit log.

Valid `filter` properties

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

mount_point - Path to the mount (e.g. auth method, secret engine), including namespaces.
mount_type - Type of mount being interacted with.
namespace - Namespace 'path' that the request is taking place within.
operation - Operation being performed.
path - Full path of the request.

Example filters

The following are examples that could be supplied as a filter value.

Purpose	Filter
Only persist audit entries for requests within `ns1`	`namespace == ns1`
Only persist audit entries for requests that are not in the root namespace	`namespace != \"\"`
Only persist audit entries that interact with `kv` engines	`mount_type == kv`
Only persist audit entries that attempt to perform `read` operations	`operation == read`
Only persist audit entries for requests that interact with `kv` within namespace `ns2`	`namespace == ns2 and mount_type == kv`

Scenario: `kv` only

A Vault Operator wants only kv type audit entries to be written to an audit log for a particular device.

Enable an audit device with the following filter option:

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

List the enabled audit devices:
```
vault audit list --detailed
```
Enable a kv secrets engine:
```
vault secrets enable -path my-kv kv-v2
```
Write secret data to the kv engine:
```
vault kv put my-kv foo=bar
```
Disable the audit device:
```
vault audit disable -path kv-only
```

The steps above performed a number of actions against Vault that generate audit entries. However, only two of them had a mount_type of kv (steps 3 and 4).

Viewing the contents of the file audit log at /var/audit.log will show that only audit entries related to steps 3 and 4, with a request and response audit entry for each.

Test message

When enabling an audit device, Vault will (by default) attempt to send a test message to the device. In cases where filtering is configured on a device, it may be possible for the evaluation of the filter to result in the test message failing to meet the specified predicate expression, and therefore not being written to the audit device's sink. This test message will always be present in fallback devices (described below).

The properties of the test message are as follows:

mount_point - not present
mount_type - not present.
namespace - not present.
operation - update.
path - sys/audit/test.

Vault Operators should use this when trying to understand when they should or should not expect a test message to appear in the sink for a newly enabled audit device.

Fallback device

The ability to filter audit entries can provide great flexibility to your workflows, however the additional complexity can make it possible for a Vault Operator to configure their audit devices in such a way that some audit entries are missed out from audit logs entirely. Therefore, we strongly encourage you to test out audit configurations in your non-production environments before deploying them to production.

The fallback audit device is the (non-mandatory) mechanism by which Vault can continue to adhere to Vault's security model, that all requests and responses are successfully logged before the client receives any secret material.

When exclusively using filtered audit devices, enable the fallback audit device to catch any audit entries that would otherwise be missed.

This means Vault is able to provide the same guarantee that 'at least one device must successfully write an audit entry' as when only standard/non-filtered audit devices are enabled.

Single fallback device

Vault supports enabling only a single fallback audit device.

Enabling the fallback audit device

Enabling the fallback audit device requires supplying the fallback option:

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

Metrics

When the fallback device is enabled, and required to persist an audit entry to the audit log, Vault will emit a fallback 'success' metric on a successful write to the audit log.

If audit devices are enabled that make use of filtering, but no fallback audit device has been enabled, Vault will produce a fallback 'miss' metric as a way to allow Operators to understand how many auditable Vault entries are not being persisted to their audit logs.