From 9e7beeb56d9a2395307a44a85b138130d3900dc4 Mon Sep 17 00:00:00 2001 From: Mike Jarmy Date: Thu, 17 Oct 2019 10:08:59 -0400 Subject: [PATCH] Document the Agent request_require_header option (#7678) * document the require_request_header option in Agent * document the require_request_header option in Agent * document the require_request_header option in Agent * document the require_request_header option in Agent * minor tweaks to docs --- website/source/api/overview.html.md | 22 ++++++++++++++++++++++ website/source/docs/agent/index.html.md | 17 +++++++++++++++++ 2 files changed, 39 insertions(+) diff --git a/website/source/api/overview.html.md b/website/source/api/overview.html.md index feb318528..917ecbb6a 100644 --- a/website/source/api/overview.html.md +++ b/website/source/api/overview.html.md @@ -162,6 +162,26 @@ more flexible. For more examples, please look at the Vault API client. +## The `X-Vault-Request` Header + +Requests that are sent to a [Vault Agent][agent] that is configured to use the +`require_request_header` option must include the `X-Vault-Request` header +entry, e.g.: + +```shell +$ curl \ + -H "X-Vault-Token: f3b09679-3001-009d-2b80-9c306ab81aa6" \ + -H "X-Vault-Request: true" \ + -H "Content-Type: application/json" \ + -X POST \ + -d '{"value":"bar"}' \ + http://127.0.0.1:8200/v1/secret/baz +``` + +The Vault CLI always adds this header to every request, regardless of whether +the request is being sent to a Vault Agent or directly to a Vault Server. In +addition, the Vauld SDK always adds this header to every request. + ## Help To retrieve the help for any API within Vault, including mounted backends, auth @@ -271,3 +291,5 @@ warnings are generated during the operation. A maximum request size of 32MB is imposed to prevent a denial of service attack with arbitrarily large requests; this can be tuned per `listener` block in Vault's server configuration file. + +[agent]: /docs/agent/index.html#listener-stanza diff --git a/website/source/docs/agent/index.html.md b/website/source/docs/agent/index.html.md index 4a71e6cc5..c4f40137f 100644 --- a/website/source/docs/agent/index.html.md +++ b/website/source/docs/agent/index.html.md @@ -45,6 +45,8 @@ These are the currently-available general configuration option: - `cache` ([cache][caching]: \) - Specifies options used for Caching functionality. +- `listener` ([listener][listener]: \) - Specifies the addresses and ports on which the Agent will respond to requests. + - `pid_file` `(string: "")` - Path to the file in which the agent's Process ID (PID) should be stored @@ -85,6 +87,19 @@ configuration entries: security of data transmissions to and from the Vault server. This value can be overridden by setting the `VAULT_SKIP_VERIFY` environment variable. +### listener Stanza + +Agent supports one or more [listener][listener_main] stanzas. In addition to +the standard listener configuration, an Agent's listener configuration also +supports an additional optional entry: + +- `require_request_header (bool: false)` - Require that all incoming HTTP + requests on this listener must have an `X-Vault-Request: true` header entry. + Using this option offers an additional layer of protection from Service Side + Request Forgery attacks. Requests on the listener that do not have the proper + `X-Vault-Request` header will fail, with a HTTP response status code of `412: + Precondition Failed`. + ## Example Configuration An example configuration, with very contrived values, follows: @@ -140,3 +155,5 @@ listener "tcp" { [vault]: /docs/agent/index.html#vault-stanza [autoauth]: /docs/agent/autoauth/index.html [caching]: /docs/agent/caching/index.html +[listener]: /docs/agent/index.html#listener-stanza +[listener_main]: /docs/configuration/listener/tcp.html