/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. 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.

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