/sys/audit

Restricted endpoint

The API path can only be called from the root namespace.

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.

Method	Path
`GET`	`/sys/audit`

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.

Method	Path
`POST`	`/sys/audit/:path`

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.
fallback (bool: false) - Enterprise Indicates whether the audit device is the fallback for filtering purposes. Vault only supports one fallback audit device at a time.
filter (string: "") - Enterprise 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.

Note: Once an audit device is disabled, you will no longer be able to HMAC values for comparison with entries in the audit logs. This is true even if you re-enable the audit device at the same path, as a new salt will be created for hashing.

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

Method	Path
`DELETE`	`/sys/audit/:path`

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