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

@@ -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

website/source/docs/agent/index.html.md

@@ -45,6 +45,8 @@ These are the currently-available general configuration option:
 
 - `cache` <tt>([cache][caching]: \<optional\>)</tt> - Specifies options used for Caching functionality.
 
+- `listener` <tt>([listener][listener]: \<optional\>)</tt> - 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