Exclusion syntax for audit results
Appropriate Vault Enterprise license required
As of Vault 1.18.0, you can enable audit devices with an exclude option to exclude
specific fields in an audit entry that is written to a particular audit log, and fine-tune
your auditing process.
Proceed with caution
Excluding audit entry fields is an advanced feature. Use of exclusion settings could lead to missing data in your audit logs.
Always test your audit configuration in a non-production environment before deploying exclusions to production. Read the Vault security model and filtering overview to familiarize yourself with Vault auditing and filtering basics before enabling audit devices that use exclusions.
Once you enable an audit device with exclusions, every audit entry Vault sends to that audit device is compared to an (optional) condition in the form of a predicate expression. Vault checks exclusions before writing to the audit log for a device. Vault modifies any audit entries that match the exclusion expression to remove the fields specified for that condition. You can specify multiple sets of condition and field combinations for an individual audit device.
When you enable audit devices that use exclusion, the behavior of any existing audit device and the behavior of new audit devices that do not use exclusion remains unchanged.
exclude option
The value provided with the exclude option must be a parsable JSON array (i.e. JSON or
an escaped JSON string) of exclusion objects.
Exclusion object
condition(string: <optional>)- predicate expression using filtering syntax. When matched, Vault removes the values identified byfields.fields(string[] <required>)- collection of fields in the audit entry to exclude, identified using JSON pointer syntax.
Vault always compares exclusion conditions against the original, immutable audit entry (the 'golden source'). As a result, evaluating a given condition does not affect the evaluation of subsequent conditions.
Exclusion examples
Exclude response data (when present)
Exclude the response data field from any audit entry that contains it:
Exclude request data (when present) for transit mounts
Exclude the request data field for audit entries with a mount type of transit:
Multiple exclusions
Use multiple JSON objects to exclude:
datafrom both the request and response when the mount type istransit.entity_idfrom requests where the/auth/client_tokenstarts withhmacfollowed by at least one other character.
Audit entry structure
To accurately construct condition and fields, Vault operators need a solid
understanding of their audit entry structures. At a high level, there are only
request audit entries and response audit entries, but each of these
entries can contain different objects such as auth, request and response.
We strongly encourage operaters to review existing audit logs from a timeframe of at least 2-4 weeks to better identify appropriate exclusion conditions and fields.
Request audit entry
Response audit entry
Auth object (<auth>)
The following auth object definition includes example data with simple types
(string, bool, int) and used in other JSON examples that include an
<auth> object.
Request object (<request>)
The following request object definition includes example data with simple types
(string, bool, int) and used in other JSON examples that include a
<request> object.
Response object (<response>)
The following response object definition includes example data with simple types
(string, bool, int) and used in other JSON examples that include a
<response> object.
Request audit entry schema
Response audit entry schema