d1f2b101b5
This PR relates to a feature request logged through HashiCorp commercial
support.
Vault lacks pagination in its APIs. As a result, certain list operations
can return **very** large responses. The user's chosen audit sinks may
experience difficulty consuming audit records that swell to tens of
megabytes of JSON.
In our case, one of the systems consuming audit log data could not cope,
and failed.
The responses of list operations are typically not very interesting, as
they are mostly lists of keys, or, even when they include a "key_info"
field, are not returning confidential information. They become even less
interesting once HMAC-ed by the audit system.
Some example Vault "list" operations that are prone to becoming very
large in an active Vault installation are:
auth/token/accessors/
identity/entity/id/
identity/entity-alias/id/
pki/certs/
In response, I've coded a new option that can be applied to audit
backends, `elide_list_responses`. When enabled, response data is elided
from audit logs, only when the operation type is "list".
For added safety, the elision only applies to the "keys" and "key_info"
fields within the response data - these are conventionally the only
fields present in a list response - see logical.ListResponse, and
logical.ListResponseWithInfo. However, other fields are technically
possible if a plugin author writes unusual code, and these will be
preserved in the audit log even with this option enabled.
The elision replaces the values of the "keys" and "key_info" fields with
an integer count of the number of entries. This allows even the elided
audit logs to still be useful for answering questions like "Was any data
returned?" or "How many records were listed?".
66 lines
2.2 KiB
Plaintext
66 lines
2.2 KiB
Plaintext
---
|
|
layout: docs
|
|
page_title: File - Audit Devices
|
|
description: The "file" audit device writes audit logs to a file.
|
|
---
|
|
|
|
# File Audit Device
|
|
|
|
The `file` audit device writes audit logs to a file. This is a very simple audit
|
|
device: it appends logs to a file.
|
|
|
|
The device does not currently assist with any log rotation. There are very
|
|
stable and feature-filled log rotation tools already, so we recommend using
|
|
existing tools.
|
|
|
|
Sending a `SIGHUP` to the Vault process will cause `file` audit devices to close
|
|
and re-open their underlying file, which can assist with log rotation needs.
|
|
|
|
## Examples
|
|
|
|
Enable at the default path:
|
|
|
|
```shell-session
|
|
$ vault audit enable file file_path=/var/log/vault_audit.log
|
|
```
|
|
|
|
Enable at a different path. It is possible to enable multiple copies of an audit
|
|
device:
|
|
|
|
```shell-session
|
|
$ vault audit enable -path="vault_audit_1" file file_path=/home/user/vault_audit.log
|
|
```
|
|
|
|
Enable logs on stdout. This is useful when running in a container:
|
|
|
|
```shell-session
|
|
$ vault audit enable file file_path=stdout
|
|
```
|
|
|
|
## Configuration
|
|
|
|
Note the difference between `audit enable` command options and the `file` backend
|
|
configuration options. Use `vault audit enable -help` to see the command options.
|
|
|
|
The `file` audit device supports the common configuration options documented on
|
|
the [main Audit Devices page](/docs/audit#common-configuration-options), and
|
|
these device-specific options:
|
|
|
|
- `file_path` `(string: <required>)` - The path to where the audit log will be
|
|
written. If a file already exists at the given path, the audit backend will
|
|
append to it. There are some special keywords:
|
|
|
|
- `stdout` writes the audit log to standard output
|
|
|
|
- `discard` writes output (useful in testing scenarios)
|
|
|
|
- `mode` `(string: "0600")` - A string containing an octal number representing
|
|
the bit pattern for the file mode, similar to `chmod`. Set to `"0000"` to
|
|
prevent Vault from modifying the file mode.
|
|
|
|
|
|
|
|
## Log File Rotation
|
|
|
|
To properly rotate Vault File Audit Device log files on BSD, Darwin, or Linux-based Vault servers, it is important that you configure your log rotation software to send the `vault` process a signal hang up / `SIGHUP` after each rotation of the log file.
|