documentation for redaction configuration on listeners #23568

peteski22 · 2023-10-09T11:54:40Z

Documentation for per-listener redaction configuration (#23534)

Deployed page: https://vault-git-docs-peteski22vault-19863listener-re-abd165-hashicorp.vercel.app/vault/docs/configuration/listener

kubawi

Looks good!

ccapurso

I have one minor question regarding ordering of sections but this looks great!

ccapurso · 2023-10-09T14:57:48Z

website/content/docs/configuration/listener/index.mdx

+Please see [redaction settings](/vault/docs/configuration/listener#redaction-settings)
+(below) for details on each redaction setting.


🤔 I wonder if it would make sense to provide the settings first so that the reader has further context prior to reading through the examples. What do you think?

+1, it's generally a better idea to provide instruction before the examples. Examples without context don't necessarily help the reader. Especially if the first sentence encourages the reader to jump to those instructions anyway 😅

😨 I missed this comment before I just hit merge! 😢 Lemme fix that.

@ccapurso #23572 👍🏼

schavis · 2023-10-09T18:47:26Z

website/content/docs/configuration/listener/index.mdx

+There are four different types of information deemed sensitive that can be returned
+by unauthenticated API endpoints:
+
+1. Version number
+2. Build date
+3. Cluster name
+4. IP address


Suggested change

There are four different types of information deemed sensitive that can be returned

by unauthenticated API endpoints:

1. Version number

2. Build date

3. Cluster name

4. IP address

Unauthenticated API endpoints may return the following sensitive

information:

1. Version number

1. Build date

1. Cluster name

1. IP address

Style correction: write in active voice

schavis · 2023-10-09T18:50:52Z

website/content/docs/configuration/listener/index.mdx

+There are four different types of information deemed sensitive that can be returned
+by unauthenticated API endpoints:
+
+1. Version number


Can we elaborate on these items a bit? What does the information belong to? For example, the version and build date of what?

schavis · 2023-10-09T18:51:57Z

website/content/docs/configuration/listener/index.mdx

 - [TCP][tcp]
 - [Unix Domain Socket][unix]

 [tcp]: /vault/docs/configuration/listener/tcp
 [unix]: /vault/docs/configuration/listener/unix
+
+## Unauthenticated endpoints - sensitive data redaction


Suggested change

## Unauthenticated endpoints - sensitive data redaction

## Sensitive data redaction for unauthenticated endpoints

The key topic here seems to be about the sensitive data redaction, so lets lead with that in the heading

schavis · 2023-10-09T18:56:41Z

website/content/docs/configuration/listener/index.mdx

+Vault offers the ability to configure each `listener` stanza such that when appropriate,
+these values will be redacted from responses.
+
+The following API endpoints support redaction based on `listener` stanza configuration:


Suggested change

Vault offers the ability to configure each `listener` stanza such that when appropriate,

these values will be redacted from responses.

The following API endpoints support redaction based on `listener` stanza configuration:

You can protect sensitive information by configuring your `listener`

stanzas to redact key values in responses for the following API

endpoints:

schavis · 2023-10-09T19:06:19Z

website/content/docs/configuration/listener/index.mdx

+When a value is redacted by Vault, it will be replaced with an empty string (`""`).
+
+~> Note: In certain situations, due to an empty string value, the related key may
+no longer be present in the response object returned from the API, as that field is
+omitted when the value is empty (`""`).
+
+~> Note: The Vault API is also consumed by the Vault CLI and UI, therefore enabling redaction
+settings will also affect them both.


Suggested change

When a value is redacted by Vault, it will be replaced with an empty string (`""`).

~> Note: In certain situations, due to an empty string value, the related key may

no longer be present in the response object returned from the API, as that field is

omitted when the value is empty (`""`).

~> Note: The Vault API is also consumed by the Vault CLI and UI, therefore enabling redaction

settings will also affect them both.

Vault replaces redacted information with an empty string (`""`). APIs that

omit response parameters with empty values also suppress redacted values in

response objects.

<Note title="Redacting values affects all API responses">

The Vault CLI and UI consume Vault API responses. As a result, your redaction

settings will apply to CLI and UI output in addition to direct API calls.

</Note>

Style correction: write in active voice, avoid back-to-back asides when possible

schavis · 2023-10-09T19:38:29Z

website/content/docs/configuration/listener/index.mdx

+The following options apply to both types of listener (see above), and can be configured
+for each individual listener stanza.
+
+Please see the [sensitive data redaction](/vault/docs/configuration/listener#unauthenticated-endpoints-sensitive-data-redaction) explanation above for further information.


Including this link here doesn't make sense as we're expecting folks to have already skimmed past those sections to get here. In general, we should avoid in-page links unless it's really needed from an accessibility or discoverability perspective.

Suggested change

Please see the [sensitive data redaction](/vault/docs/configuration/listener#unauthenticated-endpoints-sensitive-data-redaction) explanation above for further information.

schavis · 2023-10-09T19:39:33Z

website/content/docs/configuration/listener/index.mdx

+The following options apply to both types of listener (see above), and can be configured
+for each individual listener stanza.


I'm not sure this sentence adds much as folks typically assume a parameter applies unless we say otherwise. Something like "Use the following parameters to configure redaction for your listeners" would be more appropriate.

I know what you mean, but I was trying to add something that meant the common config options section could be extended later if we had settings that weren't for just redaction (e.g. disabling an endpoint via config here). 🤔

schavis · 2023-10-09T19:40:35Z

website/content/docs/configuration/listener/index.mdx

+
+### Redaction settings
+
+- `redact_addresses` `(bool: false)` - If enabled, will redact `leader_address` and `cluster_leader_address` values when applicable.


Suggested change

- `redact_addresses` `(bool: false)` - If enabled, will redact `leader_address` and `cluster_leader_address` values when applicable.

- `redact_addresses` `(bool: false)` - Redacts `leader_address` and `cluster_leader_address` values in applicable API responses when `true`.

schavis · 2023-10-09T19:41:10Z

website/content/docs/configuration/listener/index.mdx

+### Redaction settings
+
+- `redact_addresses` `(bool: false)` - If enabled, will redact `leader_address` and `cluster_leader_address` values when applicable.
+- `redact_cluster_name` `(bool: false)` - If enabled, will redact `cluster_name` values when applicable.


Suggested change

- `redact_cluster_name` `(bool: false)` - If enabled, will redact `cluster_name` values when applicable.

- `redact_cluster_name` `(bool: false)` - Redacts `cluster_name` values in applicable API responses when `true`.

schavis · 2023-10-09T19:41:32Z

website/content/docs/configuration/listener/index.mdx

+
+- `redact_addresses` `(bool: false)` - If enabled, will redact `leader_address` and `cluster_leader_address` values when applicable.
+- `redact_cluster_name` `(bool: false)` - If enabled, will redact `cluster_name` values when applicable.
+- `redact_version` `(bool: false)` - If enabled, will redact `version` and `build_date` values when applicable.


Suggested change

- `redact_version` `(bool: false)` - If enabled, will redact `version` and `build_date` values when applicable.

- `redact_version` `(bool: false)` - Redacts `version` and `build_date` values in applicable API responses when `true`.

schavis · 2023-10-09T19:42:40Z

In future, please do not merge documentation changes until a member of the EDU team has had a chance to review it.

documentation for redaction configuration on listeners

8293f3c

peteski22 added docs pr/no-changelog hashicorp-contributed-pr If the PR is HashiCorp (i.e. not-community) contributed labels Oct 9, 2023

peteski22 added this to the 1.16.0-rc1 milestone Oct 9, 2023

peteski22 requested a review from a team as a code owner October 9, 2023 11:54

peteski22 requested review from marcboudreau and a team October 9, 2023 11:54

vercel bot deployed to Preview October 9, 2023 11:58 View deployment

vercel bot deployed to Preview October 9, 2023 12:09 View deployment

hashicorp deleted a comment from digital-content-events bot Oct 9, 2023

peteski22 force-pushed the docs/peteski22/VAULT-19863/listener-response-redaction branch from bf8e762 to 8293f3c Compare October 9, 2023 12:50

fix relative paths for /vault/

2f34cd0

kubawi approved these changes Oct 9, 2023

View reviewed changes

peteski22 mentioned this pull request Oct 9, 2023

VAULT-19863: Per-listener redaction settings #23534

Merged

vercel bot deployed to Preview October 9, 2023 12:59 View deployment

ccapurso approved these changes Oct 9, 2023

View reviewed changes

peteski22 merged commit 2912f5b into main Oct 9, 2023
42 checks passed

peteski22 deleted the docs/peteski22/VAULT-19863/listener-response-redaction branch October 9, 2023 19:34

schavis requested changes Oct 9, 2023

View reviewed changes

peteski22 mentioned this pull request Oct 9, 2023

Docs listener config - tweak #23572

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

documentation for redaction configuration on listeners #23568

documentation for redaction configuration on listeners #23568

peteski22 commented Oct 9, 2023 •

edited

Loading

kubawi left a comment

ccapurso left a comment

ccapurso Oct 9, 2023

schavis Oct 9, 2023

peteski22 Oct 9, 2023

peteski22 Oct 9, 2023

schavis Oct 9, 2023

schavis Oct 9, 2023

schavis Oct 9, 2023

schavis Oct 9, 2023

schavis Oct 9, 2023

schavis Oct 9, 2023

schavis Oct 9, 2023

peteski22 Oct 9, 2023

schavis Oct 9, 2023

schavis Oct 9, 2023

schavis Oct 9, 2023

schavis commented Oct 9, 2023

		Please see [redaction settings](/vault/docs/configuration/listener#redaction-settings)
		(below) for details on each redaction setting.

	## Unauthenticated endpoints - sensitive data redaction
	## Sensitive data redaction for unauthenticated endpoints

		The following options apply to both types of listener (see above), and can be configured
		for each individual listener stanza.


		### Redaction settings

		- `redact_addresses` `(bool: false)` - If enabled, will redact `leader_address` and `cluster_leader_address` values when applicable.

	- `redact_addresses` `(bool: false)` - If enabled, will redact `leader_address` and `cluster_leader_address` values when applicable.
	- `redact_addresses` `(bool: false)` - Redacts `leader_address` and `cluster_leader_address` values in applicable API responses when `true`.

	- `redact_cluster_name` `(bool: false)` - If enabled, will redact `cluster_name` values when applicable.
	- `redact_cluster_name` `(bool: false)` - Redacts `cluster_name` values in applicable API responses when `true`.

	- `redact_version` `(bool: false)` - If enabled, will redact `version` and `build_date` values when applicable.
	- `redact_version` `(bool: false)` - Redacts `version` and `build_date` values in applicable API responses when `true`.

documentation for redaction configuration on listeners #23568

documentation for redaction configuration on listeners #23568

Conversation

peteski22 commented Oct 9, 2023 • edited Loading

kubawi left a comment

Choose a reason for hiding this comment

ccapurso left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

schavis commented Oct 9, 2023

peteski22 commented Oct 9, 2023 •

edited

Loading