Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[NET-1151 NET-11046] docs: Add request normalization, L7 headers options, and security guidance to release/1.19.x #21856

Open
wants to merge 1 commit into
base: release/1.19.x
Choose a base branch
from
Open

[NET-1151 NET-11046] docs: Add request normalization, L7 headers options, and security guidance to release/1.19.x #21856

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
105 changes: 105 additions & 0 deletions website/content/docs/connect/config-entries/mesh.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -264,6 +264,60 @@ spec:

Note that the Kubernetes example does not include a `partition` field. Configuration entries are applied on Kubernetes using [custom resource definitions (CRD)](/consul/docs/k8s/crds), which can only be scoped to their own partition.

### Request Normalization

Enable options under `HTTP.Incoming.RequestNormalization` to apply normalization to all inbound traffic to mesh proxies.

~> **Compatibility warning**: This feature is available as of Consul CE 1.20.1 and Consul Enterprise 1.20.1, 1.19.2, 1.18.3, and 1.15.15. We recommend upgrading to the latest version of Consul to take advantage of the latest features and improvements.

<CodeTabs tabs={[ "HCL", "Kubernetes YAML", "JSON" ]}>

```hcl
Kind = "mesh"
HTTP {
Incoming {
RequestNormalization {
InsecureDisablePathNormalization = false // default false, shown for completeness
MergeSlashes = true
PathWithEscapedSlashesAction = "UNESCAPE_AND_FORWARD"
HeadersWithUnderscoresAction = "REJECT_REQUEST"
}
}
}
```

```yaml
apiVersion: consul.hashicorp.com/v1alpha1
kind: Mesh
metadata:
name: mesh
spec:
http:
incoming:
requestNormalization:
insecureDisablePathNormalization: false # default false, shown for completeness
mergeSlashes: true
pathWithEscapedSlashesAction: UNESCAPE_AND_FORWARD
headersWithUnderscoresAction: REJECT_REQUEST
```

```json
{
"Kind": "mesh",
"HTTP": {
"Incoming": {
"RequestNormalization": {
"InsecureDisablePathNormalization": false,
"MergeSlashes": true,
"PathWithEscapedSlashesAction": "UNESCAPE_AND_FORWARD",
"HeadersWithUnderscoresAction": "REJECT_REQUEST"
}
}
}
}
```

</CodeTabs>

## Available Fields

Expand Down Expand Up @@ -452,6 +506,57 @@ Note that the Kubernetes example does not include a `partition` field. Configura
for all Envoy proxies. As a result, Consul will not include the \`x-forwarded-client-cert\` header in the next hop.
If set to \`false\` (default), the XFCC header is propagated to upstream applications.`,
},
{
name: 'Incoming',
type: 'DirectionalHTTPConfig: <optional>',
description: `HTTP configuration for inbound traffic to mesh proxies.`,
children: [
{
name: 'RequestNormalization',
type: 'RequestNormalizationConfig: <optional>',
description: `Request normalization configuration for inbound traffic to mesh proxies.`,
children: [
{
name: 'InsecureDisablePathNormalization',
type: 'bool: false',
description: `Sets the value of the \`normalize_path\` option in the Envoy listener's \`HttpConnectionManager\`. The default value is \`false\`.
When set to \`true\` in Consul, \`normalize_path\` is set to \`false\` for the Envoy proxy.
This parameter disables the normalization of request URL paths according to RFC 3986,
conversion of \`\\\` to \`/\`, and decoding non-reserved %-encoded characters. When using L7
intentions with path match rules, we recommend enabling path normalization in order
to avoid match rule circumvention with non-normalized path values.`,
},
{
name: 'MergeSlashes',
type: 'bool: false',
description: `Sets the value of the \`merge_slashes\` option in the Envoy listener's \`HttpConnectionManager\`. The default value is \`false\`.
This option controls the normalization of request URL paths by merging consecutive \`/\` characters. This normalization is not part
of RFC 3986. When using L7 intentions with path match rules, we recommend enabling this setting to avoid match rule circumvention through non-normalized path values, unless legitimate service
traffic depends on allowing for repeat \`/\` characters, or upstream services are configured to
differentiate between single and multiple slashes.`,
},
{
name: 'PathWithEscapedSlashesAction',
type: 'string: ""',
description: `Sets the value of the \`path_with_escaped_slashes_action\` option in the Envoy listener's
\`HttpConnectionManager\`. The default value of this option is empty, which is
equivalent to \`IMPLEMENTATION_SPECIFIC_DEFAULT\`. This parameter controls the action taken in response to request URL paths with escaped
slashes in the path. When using L7 intentions with path match rules, we recommend enabling this setting to avoid match rule circumvention through non-normalized path values, unless legitimate service
traffic depends on allowing for escaped \`/\` or \`\\\` characters, or upstream services are configured to
differentiate between escaped and unescaped slashes. Refer to the Envoy documentation for more information on available
options.`,
},
{
name: 'HeadersWithUnderscoresAction',
type: 'string: ""',
description: `Sets the value of the \`headers_with_underscores_action\` option in the Envoy listener's
\`HttpConnectionManager\` under \`common_http_protocol_options\`. The default value of this option is
empty, which is equivalent to \`ALLOW\`. Refer to the Envoy documentation for more information on available options.`,
},
],
},
],
}
],
},
{
Expand Down
75 changes: 62 additions & 13 deletions website/content/docs/connect/config-entries/service-intentions.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,9 @@ The following outline shows how to format the service intentions configuration e
- [`Exact`](#sources-permissions-http-header): string
- [`Prefix`](#sources-permissions-http-header): string
- [`Suffix`](#sources-permissions-http-header): string
- [`Regex`](#sources-permissions-http-header): string
- [`Contains`](#spec-sources-permissions-http-header): string
- [`Regex`](#spec-sources-permissions-http-header): string
- [`IgnoreCase`](#spec-sources-permissions-http-header): boolean | `false`
- [`Invert`](#sources-permissions-http-header): boolean | `false`
- [`Precedence`](#sources-precedence): number
- [`Type`](#sources-type): string | `consul`
Expand Down Expand Up @@ -96,7 +98,9 @@ The following outline shows how to format the service intentions configuration e
- [`exact`](#spec-sources-permissions-http-header): string | no default
- [`prefix`](#spec-sources-permissions-http-header): string | no default
- [`suffix`](#spec-sources-permissions-http-header): string | no default
- [`contains`](#spec-sources-permissions-http-header): string | no default
- [`regex`](#spec-sources-permissions-http-header): string | no default
- [`ignoreCase`](#spec-sources-permissions-http-header): boolean | `false`
- [`invert`](#spec-sources-permissions-http-header): boolean | `false`
- [`description`](#spec-sources-description): string

Expand Down Expand Up @@ -156,18 +160,31 @@ Sources = [
{
Name = "<http header name>" # string
Present = <true or false> # boolean
Invert = <true or false> # boolean
},
{
Name = "<http header name>" # string
Exact = "<header-value>" # boolean
IgnoreCase = <true or false> # boolean
Invert = <true or false> # boolean
},
{
Name = "<http header name>" # string
Prefix = "<source header value prefix>" # string
IgnoreCase = <true or false> # boolean
Invert = <true or false> # boolean
},
{
Name = "<http header name>" # string
Suffix = "<source header value suffix>" # string
IgnoreCase = <true or false> # boolean
Invert = <true or false> # boolean
},
{
Name = "<http header name>" # string
Contains = "<value to search for>" # string
IgnoreCase = <true or false> # boolean
Invert = <true or false> # boolean
},
{
Name = "<http header name>" # string
Expand Down Expand Up @@ -227,12 +244,23 @@ spec:
header:
- name: <http header name>
present: true
invert: false
- name: <http header name>
exact: false
exact: <header-value>
ignoreCase: false
invert: false
- name: <http header name>
prefix: <source header value prefix>
ignoreCase: false
invert: false
- name: <http header name>
suffix: <source header value suffix>
ignoreCase: false
invert: false
- name: <http header name>
contains: <value to search for>
ignoreCase: false
invert: false
- name: <http header name>
regex: <regex pattern to match>
invert: false
Expand Down Expand Up @@ -287,19 +315,32 @@ spec:
"Header":[
{
"Name":"<http header name>",
"Present":true
"Present":true,
"Invert":false
},
{
"Name":"<http header name>",
"Exact":"<header-value>",
"IgnoreCase":false,,
"Invert":false
},
{
"Name":"<http header name>",
"Exact":false
"Prefix":"<source header value prefix>",
"IgnoreCase":false,
"Invert":false
},
{
"Name":"<http header name>",
"Prefix":"<source header value prefix>"
"Suffix":"<source header value suffix>",
"IgnoreCase":false,
"Invert":false
},
{
"Name":"<http header name>",
"Suffix":"<source header value suffix>"
"Contains":"<value to search for>",
"IgnoreCase":false,
"Invert":false
},
{
"Name":"<http header name>",
Expand Down Expand Up @@ -609,7 +650,9 @@ Each member of the `Header` list is a map that contains a `Name` field and at le
| `Exact` | Specifies a value for the header key set in the `Name` field. If the request header value matches the `Exact` value, Consul applies the permission. Do not specify `Exact` if `Present`, `Prefix`, `Suffix`, or `Regex` are configured in the same `Header` configuration. | string | optional |
| `Prefix` | Specifies a prefix value for the header key set in the `Name` field. If the request header value starts with the `Prefix` value, Consul applies the permission. Do not specify `Prefix` if `Present`, `Exact`, `Suffix`, or `Regex` are configured in the same `Header` configuration. | string | optional |
| `Suffix` | Specifies a suffix value for the header key set in the `Name` field. If the request header value ends with the `Suffix` value, Consul applies the permission. Do not specify `Suffix` if `Present`, `Exact`, `Prefix`, or `Regex` are configured in the same `Header` configuration. | string | optional |
| `Regex` | Specifies a regular expression pattern as the value for the header key set in the `Name` field. If the request header value matches the regex, Consul applies the permission. Do not specify `Regex` if `Present`, `Exact`, `Prefix`, or `Suffix` are configured in the same `Header` configuration. The regex syntax is proxy-specific. If using Envoy, refer to the [re2 documentation](https://github.com/google/re2/wiki/Syntax) for details. | string | optional |
| `Contains` | Specifies a contains value for the header key set in the `Name` field. If the request header value includes the `Contains` value, Consul applies the permission. Do not specify `Contains` if `Present`, `Exact`, `Prefix`, `Suffix`, or `Regex` are configured in the same `header` configuration. | string | optional |
| `Regex` | Specifies a regular expression pattern as the value for the header key set in the `Name` field. If the request header value matches the regex, Consul applies the permission. Do not specify `Regex` if `Present`, `Exact`, `Prefix`, `Suffix`, or `Contains` are configured in the same `Header` configuration. The regex syntax is proxy-specific. If using Envoy, refer to the [re2 documentation](https://github.com/google/re2/wiki/Syntax) for details. | string | optional |
| `IgnoreCase` | Ignores the case of the provided header value when matching with `Exact`, `Prefix`, `Suffix`, or `Contains`. Default is `false`. | boolean | optional |
| `Invert` | Inverts the matching logic configured in the `Header`. Default is `false`. | boolean | optional |

### `Sources[].Precedence`
Expand Down Expand Up @@ -923,16 +966,22 @@ Specifies a set of criteria for matching HTTP request headers. The request heade
- Default: None
- Data type: List of maps

Each member of the `header` list is a map that contains a `name` field and at least one match criterion. The following table describes the parameters that each member of the `header` list may contain:
Each member of the `header` list is a map that contains a `name` field and at least one match criterion.

~> **Warning**: If it is possible for a header to contain multiple values, we recommend using `contains` or `regex` rather than `exact`, `prefix`, or `suffix`. Envoy internally concatenates multiple header values into a single CSV value prior to applying match rules, which may result in match rules that depend on the beginning or end of a string vulnerable to circumvention. A more robust alternative is using `contains` or, if a stricter value match is required, configuring a regex pattern that is tolerant of comma-separated values. These options are available as of Consul CE 1.20.1 and Consul Enterprise 1.20.1, 1.19.2, 1.18.3, and 1.15.15.

The following table describes the parameters that each member of the `header` list may contain:

| Parameter | Description | Data type | Required |
| --- | --- | --- | --- |
| `name` | Specifies the name of the header to match. | string | required |
| `present` | Enables a match if the header configured in the `name` field appears in the request. Consul matches on any value as long as the header key appears in the request. Do not specify `present` if `exact`, `prefix`, `suffix`, or `regex` are configured in the same `header` configuration. | boolean | optional |
| `Exact` | Specifies a value for the header key set in the `Name` field. If the request header value matches the `exact` value, Consul applies the permission. Do not specify `exact` if `present`, `prefix`, `suffix`, or `regex` are configured in the same `header` configuration. | string | optional |
| `prefix` | Specifies a prefix value for the header key set in the `name` field. If the request header value starts with the `prefix` value, Consul applies the permission. Do not specify `prefix` if `present`, `exact`, `suffix`, or `regex` are configured in the same `header` configuration. | string | optional |
| `suffix` | Specifies a suffix value for the header key set in the `name` field. If the request header value ends with the `suffix` value, Consul applies the permission. Do not specify `suffix` if `present`, `exact`, `prefix`, or `regex` are configured in the same `header` configuration. | string | optional |
| `regex` | Specifies a regular expression pattern as the value for the header key set in the `name` field. If the request header value matches the regex, Consul applies the permission. Do not specify `regex` if `present`, `exact`, `prefix`, or `suffix` are configured in the same `header` configuration. The regex syntax is proxy-specific. If using Envoy, refer to the [re2 documentation](https://github.com/google/re2/wiki/Syntax) for details. | string | optional |
| `present` | Enables a match if the header configured in the `name` field appears in the request. Consul matches on any value as long as the header key appears in the request. Do not specify `present` if `exact`, `prefix`, `suffix`, `contains`, or `regex` are configured in the same `header` configuration. | boolean | optional |
| `Exact` | Specifies a value for the header key set in the `Name` field. If the request header value matches the `exact` value, Consul applies the permission. Do not specify `exact` if `present`, `prefix`, `suffix`, `contains`, or `regex` are configured in the same `header` configuration. | string | optional |
| `prefix` | Specifies a prefix value for the header key set in the `name` field. If the request header value starts with the `prefix` value, Consul applies the permission. Do not specify `prefix` if `present`, `exact`, `suffix`, `contains`, or `regex` are configured in the same `header` configuration. | string | optional |
| `suffix` | Specifies a suffix value for the header key set in the `name` field. If the request header value ends with the `suffix` value, Consul applies the permission. Do not specify `suffix` if `present`, `exact`, `prefix`, `contains`, or `regex` are configured in the same `header` configuration. | string | optional |
| `contains` | Specifies a contains value for the header key set in the `name` field. If the request header value includes the `contains` value, Consul applies the permission. Do not specify `contains` if `present`, `exact`, `prefix`, `suffix`, or `regex` are configured in the same `header` configuration. | string | optional |
| `regex` | Specifies a regular expression pattern as the value for the header key set in the `name` field. If the request header value matches the regex, Consul applies the permission. Do not specify `regex` if `present`, `exact`, `prefix`, `suffix`, or `contains` are configured in the same `header` configuration. The regex syntax is proxy-specific. If using Envoy, refer to the [re2 documentation](https://github.com/google/re2/wiki/Syntax) for details. | string | optional |
| `ignoreCase` | Ignores the case of the provided header value when matching with exact, prefix, suffix, or contains. Default is `false`. | boolean | optional |
| `invert` | Inverts the matching logic configured in the `header`. Default is `false`. | boolean | optional |

### `spec.sources[].type`
Expand Down
Loading