open-vault/website/source/docs/audit/index.html.md

82 lines
3.2 KiB
Markdown
Raw Normal View History

2015-04-20 05:59:39 +00:00
---
layout: "docs"
2017-09-08 02:38:47 +00:00
page_title: "Audit Devices"
2015-04-20 05:59:39 +00:00
sidebar_current: "docs-audit"
description: |-
2017-09-08 02:38:47 +00:00
Audit devices are mountable devices that log requests and responses in Vault.
2015-04-20 05:59:39 +00:00
---
2017-09-08 02:38:47 +00:00
# Audit Devices
2015-04-20 05:59:39 +00:00
2017-09-08 02:38:47 +00:00
Audit devices are the components in Vault that keep a detailed log
2015-04-20 05:59:39 +00:00
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.
2017-09-08 02:38:47 +00:00
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.
2015-04-20 05:59:39 +00:00
## Sensitive Information
The audit logs contain the full request and response objects for every
2016-07-25 01:23:12 +00:00
interaction with Vault. The request and response can be matched utilizing a
unique identifier assigned to each request. The data in the request and the
data in the response (including secrets and authentication tokens) will be
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
2017-09-08 02:38:47 +00:00
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).
2015-04-20 05:59:39 +00:00
2017-09-08 02:38:47 +00:00
## Enabling/Disabling Audit Devices
2015-04-20 05:59:39 +00:00
When a Vault server is first initialized, no auditing is enabled. Audit
devices must be enabled by a root user using `vault audit enable`.
2015-04-20 05:59:39 +00:00
2017-09-08 02:38:47 +00:00
When enabling an audit device, options can be passed to it to configure it.
For example, the command below enables the file audit device:
2015-04-20 05:59:39 +00:00
2017-09-08 02:38:47 +00:00
```text
$ vault audit enable file file_path=/var/log/vault_audit.log
2015-04-20 05:59:39 +00:00
```
In the command above, we passed the "file_path" parameter to specify the path
2017-09-08 02:38:47 +00:00
where the audit log will be written to. Each audit device has its own
2015-04-20 05:59:39 +00:00
set of parameters. See the documentation to the left for more details.
2017-09-08 02:38:47 +00:00
When an audit device is disabled, it will stop receiving logs immediately.
2015-04-20 05:59:39 +00:00
The existing logs that it did store are untouched.
2017-09-08 02:38:47 +00:00
## Blocked Audit Devices
2015-04-20 05:59:39 +00:00
2017-09-08 02:38:47 +00:00
If there are any audit devices enabled, Vault requires that at least
2015-04-20 05:59:39 +00:00
one be able to persist the log before completing a Vault request.
2017-09-08 02:38:47 +00:00
!> 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.
2015-04-20 05:59:39 +00:00
2017-09-08 02:38:47 +00:00
If you have more than one audit device, then Vault will complete the request
as long as one audit device persists the log.
2015-04-20 05:59:39 +00:00
2017-09-08 02:38:47 +00:00
Vault will not respond to requests if audit devices are blocked because
2015-04-20 05:59:39 +00:00
audit logs are critically important and ignoring blocked requests opens
2017-09-08 02:38:47 +00:00
an avenue for attack. Be absolutely certain that your audit devices cannot
2015-04-20 05:59:39 +00:00
block.
## API
2017-09-08 02:38:47 +00:00
Audit devices also have a full HTTP API. Please see the [Audit device API
docs](/api/system/audit.html) for more details.