upstream/vault
1
0
Fork 0
mirror of https://github.com/hashicorp/vault.git synced 2026-06-11 09:51:16 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions 9

Audit backend -> device

Browse source
This commit is contained in:
Seth Vargo 2017-09-07 22:38:47 -04:00
parent fc0ba28051
commit 965b8809e3
No known key found for this signature in database
GPG key ID: C921994F9C27E0FF
5 changed files with 139 additions and 268 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

111
website/source/docs/audit/file.html.md
View file

@ -1,97 +1,56 @@
---
layout: "docs"
page_title: "Audit Backend: File"
page_title: "File - Audit Devices"
sidebar_current: "docs-audit-file"
description: |-
The "file" audit backend writes audit logs to a file.
The "file" audit device writes audit logs to a file.
---
# Audit Backend: File
# File Audit Device
The `file` audit backend writes audit logs to a file. This is a very simple audit
backend: it appends logs to a file.
The `file` audit device writes audit logs to a file. This is a very simple audit
device: it appends logs to a file.
## Rotation
The backend does not currently assist with any log rotation. There are very
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.
As of 0.6.2, sending a `SIGHUP` to the Vault process will cause `file` audit
backends to close and re-open their underlying file, which can assist with log
rotation needs.
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.
## Format
## Examples
Each line in the audit log is a JSON object. The `type` field specifies what type of
object it is. Currently, only two types exist: `request` and `response`. The line contains
all of the information for any given request and response. By default, all the sensitive
information is first hashed before logging in the audit logs.
Enable at the default path:
## Enabling
#### Via the CLI
Audit `file` backend can be enabled by the following command.
```
$ vault audit-enable file file_path=/var/log/vault_audit.log
```text
$ vault audit enable file file_path=/var/log/vault_audit.log
```
Any number of `file` audit logs can be created by enabling it with different `path`s.
Enable at a different path. It is possible to enable multiple copies of an audit
device:
```
$ vault audit-enable -path="vault_audit_1" file file_path=/home/user/vault_audit.log
```text
$ vault audit enable -path="vault_audit_1" file file_path=/home/user/vault_audit.log
```
Note the difference between `audit-enable` command options and the `file` backend
configuration options. Use `vault audit-enable -help` to see the command options.
Following are the configuration options available for the backend.
## Configuration
<dl class="api">
<dt>Backend configuration options</dt>
<dd>
<ul>
<li>
<span class="param">file_path</span>
<span class="param-flags">required</span>
The path to where the audit log will be written. If this
path exists, the audit backend will append to it. Specify `"stdout"` to write audit log to standard output; specify `"discard"` to discard output (useful in testing scenarios).
</li>
<li>
<span class="param">log_raw</span>
<span class="param-flags">optional</span>
A string containing a boolean value ('true'/'false'), if set, logs
the security sensitive information without hashing, in the raw
format. Defaults to `false`.
</li>
<li>
<span class="param">hmac_accessor</span>
<span class="param-flags">optional</span>
A string containing a boolean value ('true'/'false'), if set,
enables the hashing of token accessor. Defaults
to `true`. This option is useful only when `log_raw` is `false`.
</li>
<li>
<span class="param">mode</span>
<span class="param-flags">optional</span>
A string containing an octal number representing the bit pattern
for the file mode, similar to `chmod`. This option defaults to
`0600`.
</li>
<li>
<span class="param">format</span>
<span class="param-flags">optional</span>
Allows selecting the output format. Valid values are `json` (the
default) and `jsonx`, which formats the normal log entries as XML.
</li>
<li>
<span class="param">prefix</span>
<span class="param-flags">optional</span>
Allows a customizable string prefix to write before the actual log
line. Defaults to an empty string.
</li>
</ul>
</dd>
</dl>
- `file_path` `(string: "")` - The path to where the audit log will be written.
If this path exists, the audit device will append to it. Specify `"stdout"` to
write audit log to standard output. Specify `"discard"` to discard output
(useful in testing scenarios).
- `log_raw` `(bool: false)` - If enabled, logs the security sensitive
information without hashing, in the raw format.
- `hmac_accessor` `(bool: true)` - If enabled, enables the hashing of token
accessor.
- `mode` `(string: "0600")` - A string containing an octal number representing
the bit pattern for the file mode, similar to `chmod`.
- `format` `(string: "json")` - Allows selecting the output format. Valid values
are `"json"` and `"jsonx"`, which formats the normal log entries as XML.
- `prefix` `(string: "")` - A customizable string prefix to write before the
actual log line.

96
website/source/docs/audit/index.html.md
View file

@ -1,22 +1,29 @@
---
layout: "docs"
page_title: "Audit Backends"
page_title: "Audit Devices"
sidebar_current: "docs-audit"
description: |-
Audit backends are mountable backends that log requests and responses in Vault.
Audit devices are mountable devices that log requests and responses in Vault.
---
# Audit Backends
# Audit Devices
Audit backends are the components in Vault that keep a detailed log
Audit devices are the components in Vault that keep a detailed log
of all requests and response to Vault. Because _every_ operation with
Vault is an API request/response, the audit log contains _every_ interaction
with Vault, including errors.
Vault ships with multiple audit backends, depending on the location you want
the logs sent to. Multiple audit backends can be enabled and Vault will send
the audit logs to both. This allows you to not only have a redundant copy,
but also a second copy in case the first is tampered with.
Multiple audit devices can be enabled and Vault will send the audit logs to
both. This allows you to not only have a redundant copy, but also a second copy
in case the first is tampered with.
## Format
Each line in the audit log is a JSON object. The `type` field specifies what
type of object it is. Currently, only two types exist: `request` and `response`.
The line contains all of the information for any given request and response. By
default, all the sensitive information is first hashed before logging in the
audit logs.
## Sensitive Information
@ -28,80 +35,47 @@ hashed with a salt using HMAC-SHA256.
The purpose of the hash is so that secrets aren't in plaintext within your
audit logs. However, you're still able to check the value of secrets by
generating HMACs yourself; this can be done with the audit backend's hash
generating HMACs yourself; this can be done with the audit device's hash
function and salt by using the `/sys/audit-hash` API endpoint (see the
documentation for more details).
## Enabling/Disabling Audit Backends
## Enabling/Disabling Audit Devices
When a Vault server is first initialized, no auditing is enabled. Audit
backends must be enabled by a root user using `vault audit-enable`.
devices must be enabled by a root user using `vault audit-enable`.
When enabling an audit backend, options can be passed to it to configure it.
For example, the command below enables the file audit backend:
When enabling an audit device, options can be passed to it to configure it.
For example, the command below enables the file audit device:
```
$ vault audit-enable file file_path=/var/log/vault_audit.log
...
```text
$ vault audit enable file file_path=/var/log/vault_audit.log
```
In the command above, we passed the "file_path" parameter to specify the path
where the audit log will be written to. Each audit backend has its own
where the audit log will be written to. Each audit device has its own
set of parameters. See the documentation to the left for more details.
When an audit backend is disabled, it will stop receiving logs immediately.
When an audit device is disabled, it will stop receiving logs immediately.
The existing logs that it did store are untouched.
## Blocked Audit Backends
## Blocked Audit Devices
If there are any audit backends enabled, Vault requires that at least
If there are any audit devices enabled, Vault requires that at least
one be able to persist the log before completing a Vault request.
If you have only one audit backend enabled, and it is blocking (network
block, etc.), then Vault will be _unresponsive_. Vault _will not_ complete
any requests until the audit backend can write.
!> If you have only one audit device enabled, and it is blocking (network
block, etc.), then Vault will be _unresponsive_. Vault **will not** complete
any requests until the audit device can write.
If you have more than one audit backend, then Vault will complete the request
as long as one audit backend persists the log.
If you have more than one audit device, then Vault will complete the request
as long as one audit device persists the log.
Vault will not respond to requests if audit backends are blocked because
Vault will not respond to requests if audit devices are blocked because
audit logs are critically important and ignoring blocked requests opens
an avenue for attack. Be absolutely certain that your audit backends cannot
an avenue for attack. Be absolutely certain that your audit devices cannot
block.
## API
### /sys/audit/[path]
#### POST
<dl class="api">
<dt>Description</dt>
<dd>
Enables audit backend at the specified path.
</dd>
<dt>Method</dt>
<dd>POST</dd>
<dd>
<ul>
<li>
<span class="param">type</span>
<span class="param-flags">required</span>
The path to where the audit log will be written. If this
path exists, the audit backend will append to it.
</li>
<li>
<span class="param">description</span>
<span class="param-flags">optional</span>
A description.
</li>
<li>
<span class="param">options</span>
<span class="param-flags">optional</span>
Configuration options of the backend in JSON format.
Refer to `syslog`, `file` and `socket` audit backend options.
</li>
</ul>
</dd>
</dl>
Audit devices also have a full HTTP API. Please see the [Audit device API
docs](/api/system/audit.html) for more details.

104
website/source/docs/audit/socket.html.md
View file

@ -1,85 +1,55 @@
---
layout: "docs"
page_title: "Audit Backend: Socket"
page_title: "Socket - Audit Devices"
sidebar_current: "docs-audit-socket"
description: |-
The "socket" audit backend writes audit writes to a TCP or UDP socket.
The "socket" audit device writes audit writes to a TCP or UDP socket.
---
# Audit Backend: Socket
# Socket Audit Device
The `socket` audit backend writes to a TCP, UDP, or UNIX socket.
The `socket` audit device writes to a TCP, UDP, or UNIX socket.
~> **Warning:** Due to the nature of the underlying protocols used in this backend there exists a case when the connection to a socket is lost a single audit entry could be omitted from the logs and the request will still succeed. Using this backend in conjunction with another audit backend will help to improve accuracy, but the socket backend should not be used if strong guarantees are needed for audit logs.
## Format
Each line in the audit log is a JSON object. The `type` field specifies what type of
object it is. Currently, only two types exist: `request` and `response`. The line contains
all of the information for any given request and response. By default, all the sensitive
information is first hashed before logging in the audit logs.
~> **Warning:** Due to the nature of the underlying protocols used in this
device there exists a case when the connection to a socket is lost a single
audit entry could be omitted from the logs and the request will still succeed.
Using this device in conjunction with another audit device will help to improve
accuracy, but the socket device should not be used if strong guarantees are
needed for audit logs.
## Enabling
#### Via the CLI
Enable at the default path:
Audit `socket` backend can be enabled by the following command.
```
$ vault audit-enable socket
```text
$ vault audit enable socket
```
Backend configuration options can also be provided from command-line.
Supply configuration parameters via K=V pairs:
```
$ vault audit-enable socket address="127.0.0.1:9090" socket_type="tcp"
```text
$ vault audit enable socket address=127.0.0.1:9090 socket_type=tcp
```
Following are the configuration options available for the backend.
## Configuration
<dl class="api">
<dt>Backend configuration options</dt>
<dd>
<ul>
<li>
<span class="param">address</span>
<span class="param-flags">required</span>
The socket server address to use. Example `127.0.0.1:9090` or `/tmp/audit.sock`.
</li>
<li>
<span class="param">socket_type</span>
<span class="param-flags">optional</span>
The socket type to use, any type compatible with <a href="https://golang.org/pkg/net/#Dial">net.Dial</a> is acceptable. Defaults to `tcp`.
</li>
<li>
<span class="param">log_raw</span>
<span class="param-flags">optional</span>
A string containing a boolean value ('true'/'false'), if set, logs the security sensitive information without
hashing, in the raw format. Defaults to `false`.
</li>
<li>
<span class="param">hmac_accessor</span>
<span class="param-flags">optional</span>
A string containing a boolean value ('true'/'false'), if set, enables the hashing of token accessor. Defaults
to `true`. This option is useful only when `log_raw` is `false`.
</li>
<li>
<span class="param">format</span>
<span class="param-flags">optional</span>
Allows selecting the output format. Valid values are `json` (the
default) and `jsonx`, which formats the normal log entries as XML.
</li>
<li>
<span class="param">write_timeout</span>
<span class="param-flags">optional</span>
Sets the timeout for writes to the socket. Defaults to "2s" (2 seconds).
</li>
<li>
<span class="param">prefix</span>
<span class="param-flags">optional</span>
Allows a customizable string prefix to write before the actual log
line. Defaults to an empty string.
</li>
</ul>
</dd>
</dl>
- `address` `(string: "")` - The socket server address to use. Example
`127.0.0.1:9090` or `/tmp/audit.sock`.
- `socket_type` `(string: "tcp")` - The socket type to use, any type compatible
with <a href="https://golang.org/pkg/net/#Dial">net.Dial</a> is acceptable.
- `log_raw` `(bool: false)` - If enabled, logs the security sensitive
information without hashing, in the raw format.
- `hmac_accessor` `(bool: true)` - If enabled, enables the hashing of token
accessor.
- `mode` `(string: "0600")` - A string containing an octal number representing
the bit pattern for the file mode, similar to `chmod`.
- `format` `(string: "json")` - Allows selecting the output format. Valid values
are `"json"` and `"jsonx"`, which formats the normal log entries as XML.
- `prefix` `(string: "")` - A customizable string prefix to write before the
actual log line.

94
website/source/docs/audit/syslog.html.md
View file

@ -1,82 +1,50 @@
---
layout: "docs"
page_title: "Audit Backend: Syslog"
page_title: "Syslog - Audit Devices"
sidebar_current: "docs-audit-syslog"
description: |-
The "syslog" audit backend writes audit logs to syslog.
The "syslog" audit device writes audit logs to syslog.
---
# Audit Backend: Syslog
# Syslog Audit Device
The `syslog` audit backend writes audit logs to syslog.
The `syslog` audit device writes audit logs to syslog.
It currently does not support a configurable syslog destination, and always
sends to the local agent. This backend is only supported on Unix systems,
sends to the local agent. This device is only supported on Unix systems,
and should not be enabled if any standby Vault instances do not support it.
## Format
## Examples
Each line in the audit log is a JSON object. The `type` field specifies what type of
object it is. Currently, only two types exist: `request` and `response`. The line contains
all of the information for any given request and response. By default, all the sensitive
information is first hashed before logging in the audit logs.
Audit `syslog` device can be enabled by the following command:
## Enabling
#### Via the CLI
Audit `syslog` backend can be enabled by the following command.
```
$ vault audit-enable syslog
```text
$ vault audit enable syslog
```
Backend configuration options can also be provided from command-line.
Supply configuration parameters via K=V pairs:
```
$ vault audit-enable syslog tag="vault" facility="AUTH"
```text
$ vault audit enable syslog tag="vault" facility="AUTH"
```
Following are the configuration options available for the backend.
## Configuration
<dl class="api">
<dt>Backend configuration options</dt>
<dd>
<ul>
<li>
<span class="param">facility</span>
<span class="param-flags">optional</span>
The syslog facility to use. Defaults to `AUTH`.
</li>
<li>
<span class="param">tag</span>
<span class="param-flags">optional</span>
The syslog tag to use. Defaults to `vault`.
</li>
<li>
<span class="param">log_raw</span>
<span class="param-flags">optional</span>
A string containing a boolean value ('true'/'false'), if set, logs the security sensitive information without
hashing, in the raw format. Defaults to `false`.
</li>
<li>
<span class="param">hmac_accessor</span>
<span class="param-flags">optional</span>
A string containing a boolean value ('true'/'false'), if set, enables the hashing of token accessor. Defaults
to `true`. This option is useful only when `log_raw` is `false`.
</li>
<li>
<span class="param">format</span>
<span class="param-flags">optional</span>
Allows selecting the output format. Valid values are `json` (the
default) and `jsonx`, which formats the normal log entries as XML.
</li>
<li>
<span class="param">prefix</span>
<span class="param-flags">optional</span>
Allows a customizable string prefix to write before the actual log
line. Defaults to an empty string.
</li>
</ul>
</dd>
</dl>
- `facility` `(string: "AUTH")` - The syslog facility to use.
- `tag` `(string: "vault")` - The syslog tag to use.
- `log_raw` `(bool: false)` - If enabled, logs the security sensitive
information without hashing, in the raw format.
- `hmac_accessor` `(bool: true)` - If enabled, enables the hashing of token
accessor.
- `mode` `(string: "0600")` - A string containing an octal number representing
the bit pattern for the file mode, similar to `chmod`.
- `format` `(string: "json")` - Allows selecting the output format. Valid values
are `"json"` and `"jsonx"`, which formats the normal log entries as XML.
- `prefix` `(string: "")` - A customizable string prefix to write before the
actual log line.

2
website/source/layouts/docs.erb
View file

@ -491,7 +491,7 @@
</li>
<li<%= sidebar_current("docs-audit") %>>
<a href="/docs/audit/index.html">Audit Backends</a>
<a href="/docs/audit/index.html">Audit Devices</a>
<ul class="nav">
<li<%= sidebar_current("docs-audit-file") %>>
<a href="/docs/audit/file.html">File</a>