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 by fields.
fields (string[] <required>) - collection of fields in the audit entry to exclude, identified using JSON pointer syntax.

[
  {
    "condition": "",
    "fields": [ "" ]
  }
]

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:

[
  {
    "fields": [ "/response/data" ]
  }
]

Exclude request data (when present) for transit mounts

Exclude the request data field for audit entries with a mount type of transit:

[
  {
    "condition": "\"/request/mount_type\" == transit",
    "fields": [ "/request/data" ]
  }
]

Multiple exclusions

Use multiple JSON objects to exclude:

data from both the request and response when the mount type is transit.
entity_id from requests where the /auth/client_token starts with hmac followed by at least one other character.

[
  {
    "condition": "\"/request/mount_type\" == transit",
    "fields": [ "/request/data", "/response/data" ]
  },
  {
    "condition":  "\"/auth/client_token\" matches \"hmac.+\"",
    "fields": [ "/auth/entity_id" ]
  }
]

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

{
  "auth": <auth>,
  "error": "",
  "forwarded_from": "",
  "request": <request>,
  "time": "",
  "type": ""
}

Response audit entry

{
  "auth": <auth>,
  "error": "",
  "forwarded_from": "",
  "request": <request>,
  "response": <response>,
  "time": "",
  "type": ""
}

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.

{
  "accessor": "",
  "client_token": "",
  "display_name": "",
  "entity_created": "",
  "entity_id": "",
  "external_namespace_policies": {
    "allowed": true,
    "granting_policies": [
      {
        "name": "",
        "namespace_id": "",
        "namespace_path": "",
        "type": ""
      }
    ]
  },
  "identity_policies": [
    ""
  ],
  "metadata": {},
  "no_default_policy": false,
  "num_uses": 10,
  "policies": [
    ""
  ],
  "policy_results": {
    "allowed": true,
    "granting_policies": [
      {
        "name": "",
        "namespace_id": "",
        "namespace_path": "",
        "type": ""
      }
    ]
  },
  "remaining_uses": 5,
  "token_policies": [
    ""
  ],
  "token_issue_time": "",
  "token_ttl": 3600,
  "token_type": ""
}

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.

{
  "client_certificate_serial_number": "",
  "client_id": "",
  "client_token": "",
  "client_token_accessor": "",
  "data": {},
  "id": "",
  "headers": {},
  "mount_accessor": "",
  "mount_class": "",
  "mount_point": "",
  "mount_type": "",
  "mount_running_version": "",
  "mount_running_sha256": "",
  "mount_is_external_plugin": "",
  "namespace": {
    "id": "",
    "path": ""
  },
  "operation": "",
  "path": "",
  "policy_override": true,
  "remote_address": "",
  "remote_port": 1234,
  "replication_cluster": "",
  "request_uri": "",
  "wrap_ttl": 60
}

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.

{
  "auth": <auth>,
  "data": {},
  "headers": {},
  "mount_accessor": "",
  "mount_class": "",
  "mount_is_external_plugin": false,
  "mount_point": "",
  "mount_running_sha256": "",
  "mount_running_plugin_version": "",
  "mount_type": "",
  "redirect": "",
  "secret": {
    "lease_id": ""
  },
  "wrap_info": {
    "accessor": "",
    "creation_path": "",
    "creation_time": "",
    "token": "",
    "ttl": 60,
    "wrapped_accessor": ""
  },
  "warnings": [
    ""
  ]
}

Request audit entry schema

{
  "type": "object",
  "properties": {
    "auth": {
      "type": "object",
      "properties": {
        "accessor": {
          "type": "string"
        },
        "client_token": {
          "type": "string"
        },
        "display_name": {
          "type": "string"
        },
        "entity_created": {
          "type": "boolean"
        },
        "entity_id": {
          "type": "string"
        },
        "external_namespace_policies": {
          "type": "object",
          "additionalProperties": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "identity_policies": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "metadata": {
          "type": "object",
          "additionalProperties": {
            "type": "string"
          }
        },
        "no_default_policy": {
          "type": "boolean"
        },
        "num_uses": {
          "type": "integer",
          "format": "int32"
        },
        "policies": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "policy_results": {
          "type": "object",
          "properties": {
            "allowed": {
              "type": "boolean"
            },
            "granting_policies": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "namespace_id": {
                    "type": "string"
                  },
                  "namespace_path": {
                    "type": "string"
                  },
                  "type": {
                    "type": "string"
                  }
                },
                "additionalProperties": false,
                "required": [
                  "type"
                ]
              }
            }
          },
          "additionalProperties": false,
          "required": [
            "allowed"
          ]
        },
        "remaining_uses": {
          "type": "integer",
          "format": "int32"
        },
        "token_issue_time": {
          "type": "string"
        },
        "token_policies": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "token_ttl": {
          "type": "integer",
          "format": "int64"
        },
        "token_type": {
          "type": "string"
        }
      },
      "additionalProperties": false
    },
    "error": {
      "type": "string"
    },
    "forwarded_from": {
      "type": "string"
    },
    "request": {
      "type": "object",
      "properties": {
        "client_certificate_serial_number": {
          "type": "string"
        },
        "client_id": {
          "type": "string"
        },
        "client_token": {
          "type": "string"
        },
        "client_token_accessor": {
          "type": "string"
        },
        "data": {
          "type": "object",
          "additionalProperties": {}
        },
        "headers": {
          "type": "object",
          "additionalProperties": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "id": {
          "type": "string"
        },
        "mount_accessor": {
          "type": "string"
        },
        "mount_class": {
          "type": "string"
        },
        "mount_is_external_plugin": {
          "type": "boolean"
        },
        "mount_point": {
          "type": "string"
        },
        "mount_running_sha256": {
          "type": "string"
        },
        "mount_running_version": {
          "type": "string"
        },
        "mount_type": {
          "type": "string"
        },
        "namespace": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "path": {
              "type": "string"
            }
          },
          "additionalProperties": false
        },
        "operation": {
          "type": "string"
        },
        "path": {
          "type": "string"
        },
        "policy_override": {
          "type": "boolean"
        },
        "remote_address": {
          "type": "string"
        },
        "remote_port": {
          "type": "integer",
          "format": "int32"
        },
        "replication_cluster": {
          "type": "string"
        },
        "request_uri": {
          "type": "string"
        },
        "wrap_ttl": {
          "type": "integer",
          "format": "int32"
        }
      },
      "additionalProperties": false
    },
    "time": {
      "type": "string"
    },
    "type": {
      "type": "string"
    }
  },
  "additionalProperties": false
}

Response audit entry schema

{
  "type": "object",
  "properties": {
    "auth": {
      "type": "object",
      "properties": {
        "accessor": {
          "type": "string"
        },
        "client_token": {
          "type": "string"
        },
        "display_name": {
          "type": "string"
        },
        "entity_created": {
          "type": "boolean"
        },
        "entity_id": {
          "type": "string"
        },
        "external_namespace_policies": {
          "type": "object",
          "additionalProperties": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "identity_policies": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "metadata": {
          "type": "object",
          "additionalProperties": {
            "type": "string"
          }
        },
        "no_default_policy": {
          "type": "boolean"
        },
        "num_uses": {
          "type": "integer",
          "format": "int32"
        },
        "policies": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "policy_results": {
          "type": "object",
          "properties": {
            "allowed": {
              "type": "boolean"
            },
            "granting_policies": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "namespace_id": {
                    "type": "string"
                  },
                  "namespace_path": {
                    "type": "string"
                  },
                  "type": {
                    "type": "string"
                  }
                },
                "additionalProperties": false,
                "required": [
                  "type"
                ]
              }
            }
          },
          "additionalProperties": false,
          "required": [
            "allowed"
          ]
        },
        "remaining_uses": {
          "type": "integer",
          "format": "int32"
        },
        "token_issue_time": {
          "type": "string"
        },
        "token_policies": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "token_ttl": {
          "type": "integer",
          "format": "int64"
        },
        "token_type": {
          "type": "string"
        }
      },
      "additionalProperties": false
    },
    "error": {
      "type": "string"
    },
    "forwarded_from": {
      "type": "string"
    },
    "request": {
      "type": "object",
      "properties": {
        "client_certificate_serial_number": {
          "type": "string"
        },
        "client_id": {
          "type": "string"
        },
        "client_token": {
          "type": "string"
        },
        "client_token_accessor": {
          "type": "string"
        },
        "data": {
          "type": "object",
          "additionalProperties": {}
        },
        "headers": {
          "type": "object",
          "additionalProperties": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "id": {
          "type": "string"
        },
        "mount_accessor": {
          "type": "string"
        },
        "mount_class": {
          "type": "string"
        },
        "mount_is_external_plugin": {
          "type": "boolean"
        },
        "mount_point": {
          "type": "string"
        },
        "mount_running_sha256": {
          "type": "string"
        },
        "mount_running_version": {
          "type": "string"
        },
        "mount_type": {
          "type": "string"
        },
        "namespace": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "path": {
              "type": "string"
            }
          },
          "additionalProperties": false
        },
        "operation": {
          "type": "string"
        },
        "path": {
          "type": "string"
        },
        "policy_override": {
          "type": "boolean"
        },
        "remote_address": {
          "type": "string"
        },
        "remote_port": {
          "type": "integer",
          "format": "int32"
        },
        "replication_cluster": {
          "type": "string"
        },
        "request_uri": {
          "type": "string"
        },
        "wrap_ttl": {
          "type": "integer",
          "format": "int32"
        }
      },
      "additionalProperties": false
    },
    "time": {
      "type": "string"
    },
    "type": {
      "type": "string"
    }
  },
  "additionalProperties": false
}