/sys/audit

The /sys/audit endpoint is used to list, enable, and disable audit devices. Audit devices must be enabled before use, and more than one device may be enabled at a time.

List enabled audit devices

This endpoint lists only the enabled audit devices (it does not list all available audit devices).

• sudo required – This endpoint requires sudo capability in addition to any path-specific capabilities.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/sys/audit

Sample response

{
  "file": {
    "type": "file",
    "description": "Store logs in a file",
    "options": {
      "file_path": "/var/log/vault.log"
    }
  }
}

Enable audit device

This endpoint enables a new audit device at the supplied path. The path can be a single word name or a more complex, nested path.

• sudo required – This endpoint requires sudo capability in addition to any path-specific capabilities.

Parameters

• path (string: <required>) – Specifies the path in which to enable the audit device. This is part of the request URL.

• description (string: "") – Specifies a human-friendly description of the audit device.

• options (map<string|string>: nil) – Specifies configuration options to pass to the audit device itself. There are a set of common options which can be applied to all types of audit device. For more details, please see the relevant page for an audit device type, under Audit Devices docs.

• type (string: <required>) – Specifies the type of the audit device. Valid types are file, socket and syslog.

Additionally, the following options are allowed in Vault Community Edition, but relevant functionality is only supported in Vault Enterprise:

• local (bool: false) – Applies exclusively to performance replication. Specifies if the audit device is local within the cluster only. Local audit devices are not replicated nor (if a secondary) removed by replication.

Common configuration options

• elide_list_responses (bool: false) - See Eliding list response bodies.

• exclude (string: "") - EnterpriseEnterprise Defines a set of rules such that, when the condition (optional) is matched, Vault removes the specified fields from the audit entry before writing to the audit log. Refer to the exclusion section of the auditing overview for more information.

• fallback (bool: false) - EnterpriseEnterprise Indicates whether the audit device is the fallback for filtering purposes. Vault only supports one fallback audit device at a time.

• filter (string: "") - EnterpriseEnterprise Sets an optional string used to filter the audit entries logged by the audit device. See the filtering section of the auditing overview for more information.

• format (string: "json") - Allows selecting the output format. Valid values are "json" and "jsonx", which formats the normal log entries as XML.

• hmac_accessor (bool: true) - If enabled, enables the hashing of token accessor.

• log_raw (bool: false) - If enabled, logs the security sensitive information without hashing, in the raw format.

• prefix (string: "") - A customizable string prefix to write before the actual log line.

Sample payload

{
  "type": "file",
  "options": {
    "file_path": "/var/log/vault/log"
  }
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/sys/audit/example-audit

Disable audit device

This endpoint disables the audit device at the given path.

• sudo required – This endpoint requires sudo capability in addition to any path-specific capabilities.

Parameters

• path (string: <required>) – Specifies the path of the audit device to delete. This is part of the request URL.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    http://127.0.0.1:8200/v1/sys/audit/example-audit