diff --git a/website/content/docs/connect/config-entries/mesh.mdx b/website/content/docs/connect/config-entries/mesh.mdx index 9352b2cc240d..cf75c4bfa4ab 100644 --- a/website/content/docs/connect/config-entries/mesh.mdx +++ b/website/content/docs/connect/config-entries/mesh.mdx @@ -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. + + + +```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" + } + } + } +} +``` + + ## Available Fields @@ -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: ', + description: `HTTP configuration for inbound traffic to mesh proxies.`, + children: [ + { + name: 'RequestNormalization', + type: 'RequestNormalizationConfig: ', + 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.`, + }, + ], + }, + ], + } ], }, { diff --git a/website/content/docs/connect/config-entries/service-intentions.mdx b/website/content/docs/connect/config-entries/service-intentions.mdx index 929f9e2e606e..d15bfbc0959c 100644 --- a/website/content/docs/connect/config-entries/service-intentions.mdx +++ b/website/content/docs/connect/config-entries/service-intentions.mdx @@ -96,7 +96,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 @@ -156,18 +158,31 @@ Sources = [ { Name = "" # string Present = # boolean + Invert = # boolean }, { Name = "" # string Exact = "" # boolean + IgnoreCase = # boolean + Invert = # boolean }, { Name = "" # string Prefix = "" # string + IgnoreCase = # boolean + Invert = # boolean }, { Name = "" # string Suffix = "" # string + IgnoreCase = # boolean + Invert = # boolean + }, + { + Name = "" # string + Contains = "" # string + IgnoreCase = # boolean + Invert = # boolean }, { Name = "" # string @@ -227,12 +242,23 @@ spec: header: - name: present: true + invert: false - name: - exact: false + exact: + ignoreCase: false + invert: false - name: prefix: + ignoreCase: false + invert: false - name: suffix: + ignoreCase: false + invert: false + - name: + contains: + ignoreCase: false + invert: false - name: regex: invert: false @@ -287,19 +313,32 @@ spec: "Header":[ { "Name":"", - "Present":true + "Present":true, + "Invert":false + }, + { + "Name":"", + "Exact":"", + "IgnoreCase":false,, + "Invert":false }, { "Name":"", - "Exact":false + "Prefix":"", + "IgnoreCase":false, + "Invert":false }, { "Name":"", - "Prefix":"" + "Suffix":"", + "IgnoreCase":false, + "Invert":false }, { "Name":"", - "Suffix":"" + "Contains":"", + "IgnoreCase":false, + "Invert":false }, { "Name":"", @@ -923,16 +962,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` diff --git a/website/content/docs/connect/intentions/index.mdx b/website/content/docs/connect/intentions/index.mdx index c9bbbabf2acc..ef59c92f8f53 100644 --- a/website/content/docs/connect/intentions/index.mdx +++ b/website/content/docs/connect/intentions/index.mdx @@ -38,6 +38,10 @@ L4 intentions mediate the ability to establish new connections. Modifying an int L7 intentions mediate the ability to issue new requests. When an intention is modified, requests received after the modification use the latest intention rules to enforce access. Changing a connection from `allow` to `deny` does not sever the connection, but doing so blocks new requests from being processed. +When using L7 intentions, we recommend that you review and update the [Mesh request normalization configuration](/consul/docs/connect/security#request-normalization-and-configured) to avoid unintended match rule circumvention. More details are available in the [Mesh configuration entry reference](/consul/docs/connect/config-entries/mesh#request-normalization). + +When you use L7 intentions with header matching and it is possible for a header to contain multiple values, we recommend using `contains` or `regex` instead of `exact`, `prefix`, or `suffix`. For more information, refer to the [service intentions configuration entry reference](/consul/docs/connect/config-entries/service-intentions#spec-sources-permissions-http-header). + ### Caching The intentions for services registered with a Consul agent are cached locally on the agent. Supported proxies also cache intention data in their own configurations so that they can authorize inbound connections or requests without relying on the Consul agent. All actions in the data path of connections take place within the proxy. diff --git a/website/content/docs/connect/security.mdx b/website/content/docs/connect/security.mdx index 1889f57406d8..cefcaa3be21d 100644 --- a/website/content/docs/connect/security.mdx +++ b/website/content/docs/connect/security.mdx @@ -32,10 +32,40 @@ Consul should be configured with a default deny intention policy. This forces all service-to-service communication to be explicitly allowed via an allow [intention](/consul/docs/connect/intentions). +One advantage of using a default deny policy in combination with specific "allow" rules +is that a failure of intentions due to misconfiguration always results in +_denied_ traffic, rather than unwanted _allowed_ traffic. + In the absence of `default_intention_policy` Consul will fall back to the ACL default policy when determining whether to allow or deny communications without an explicit intention. +### Request Normalization Configured for L7 Intentions + +~> **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. + +Atypical traffic patterns may interfere with the enforcement of L7 intentions. For +example, if a service makes request to a non-normalized URI path and Consul is not +configured to force path normalization, it becomes possible to circumvent path match rules. While a +default deny policy can limit the impact of this issue, we still recommend +that you review your current request normalization configuration. Normalization is critical to avoid unwanted +traffic, especially when using unrecommended security options such as a default allow intentions policy. + +Consul adopts a default normalization mode that adheres to [RFC 3986]( +https://tools.ietf.org/html/rfc3986#section-6), but additional options to enable stricter +normalization are available in the cluster-wide [Mesh configuration entry]( +/consul/docs/connect/config-entries/mesh). We recommend reviewing these options and +enabling the strictest set that does not interfere with application traffic. + +We also recommend that you review L7 intention header match rules for potential +issues with multiple header values. Refer to the [service intentions +configuration entry reference](/consul/docs/connect/config-entries/service-intentions#spec-sources-permissions-http-header) +for more information. + +You do not need to enable request normalization if you are not using L7 intentions. +However, normalization may also benefit the use of other service mesh features that +rely on L7 attribute matching, such as [service routers](/consul/docs/connect/manage-traffic#routing). + ### ACLs Enabled with Default Deny Consul must be configured to use ACLs with a default deny policy. This forces @@ -51,6 +81,10 @@ this. **If ACLs are not enabled**, deny intentions will still be enforced, but a may edit intentions. This renders the security of the created intentions effectively useless. +The advantage of a default deny policy in combination with specific "allow" rules +is that at worst, a failure of intentions due to misconfiguration will result in +_denied_ traffic, rather than unwanted _allowed_ traffic. + ### TCP and UDP Encryption Enabled TCP and UDP encryption must be enabled to prevent plaintext communication diff --git a/website/content/docs/security/security-models/core.mdx b/website/content/docs/security/security-models/core.mdx index 1140cdab30e8..7eafb02ca257 100644 --- a/website/content/docs/security/security-models/core.mdx +++ b/website/content/docs/security/security-models/core.mdx @@ -26,6 +26,10 @@ environment, but the general mechanisms for a secure Consul deployment revolve a [authentication methods](/consul/docs/security/acl/auth-methods) can be used to enable trusted external parties to authorize ACL token creation. +- **Intentions** - If in use, configure service intentions to use a default-deny policy. If L7 intentions are + in use, enable [Mesh request normalization](/consul/docs/connect/config-entries/mesh#request-normalization) + and review your [header match rules](/consul/docs/connect/config-entries/service-intentions#spec-sources-permissions-http-header) to prevent malformed requests from bypassing intentions. + - **Namespaces** - Read and write operations can be scoped to a logical namespace to restrict access to Consul components within a multi-tenant environment. @@ -178,6 +182,13 @@ environment and adapt these configurations accordingly. - **🏷 Namespace** - a named, logical scoping of Consul Enterprise resources, typically to enable multi-tenant environments. Consul CE clusters always operate within the "default" namespace. +- **Intentions** - Service intentions control traffic communication between services at the network layer (L4) and + application layer (L7). If in use, we strongly recommend configuring intentions to use a default-deny policy. + When L7 intentions are in use, review your configuration for [Mesh request normalization](/consul/docs/connect/config-entries/mesh#request-normalization) + and use the strictest set of options suitable to your environment. At minimum, we + recommend keeping path normalization enabled, because this default setting prevents requests that do not conform to [RFC 3986]( + https://tools.ietf.org/html/rfc3986#section-6) from bypassing path match rules. + - **Gossip Encryption** - A shared, base64-encoded 32-byte symmetric key is required to [encrypt Serf gossip communication](/consul/tutorials/security/gossip-encryption-secure?utm_source=consul.io&utm_medium=docs) within a cluster using AES GCM. The key size determines which AES encryption types to use; 16, 24, or 32 bytes to select AES-128, AES-192, @@ -252,6 +263,10 @@ environment and adapt these configurations accordingly. } ``` +- **Customize Mesh HTTP Request Normalization** - If L7 intentions are in use, we recommend configuring request normalization to + avoid match rule circumvention. Other normalization options, such as dropping or rejecting headers with underscores, + may also be appropriate depending on your requirements. Review the options in the [Mesh configuration entry](/consul/docs/connect/config-entries/mesh#request-normalization) to determine the appropriate settings for your use case. + - **Customize Default Limits** - Consul has a number of builtin features with default connection limits that should be tuned to fit your environment. diff --git a/website/content/docs/upgrading/upgrade-specific.mdx b/website/content/docs/upgrading/upgrade-specific.mdx index b731408f2711..a29d137bd524 100644 --- a/website/content/docs/upgrading/upgrade-specific.mdx +++ b/website/content/docs/upgrading/upgrade-specific.mdx @@ -43,6 +43,15 @@ The Kubernetes-only legacy API gateway is superseded by the modern, multi-runtim [API gateway](/consul/docs/connect/config-entries/api-gateway). On Kubernetes, the modern API gateway is associated with the `connectInject.apiGateway` stanza. +### Mesh traffic request path normalization enabled by default + +As of Consul v1.19.3, inbound traffic to mesh proxies will have Envoy request [path normalization](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto#envoy-v3-api-field-extensions-filters-network-http-connection-manager-v3-httpconnectionmanager-normalize-path) applied by default. This should not interfere with the majority of service traffic, but can be disabled if needed by setting `http.incoming.request_normalization.insecure_disable_path_normalization` to `true` in the [global `mesh` configuration entry](/consul/docs/connect/config-entries/mesh#request-normalization). This setting is generally safe to change if not using L7 intentions with path matching. + +## Consul 1.18.x + +### Mesh traffic request path normalization enabled by default + +As of Consul v1.18.5, inbound traffic to mesh proxies will have Envoy request [path normalization](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto#envoy-v3-api-field-extensions-filters-network-http-connection-manager-v3-httpconnectionmanager-normalize-path) applied by default. This should not interfere with the majority of service traffic, but can be disabled if needed by setting `http.incoming.request_normalization.insecure_disable_path_normalization` to `true` in the [global `mesh` configuration entry](/consul/docs/connect/config-entries/mesh#request-normalization). This setting is generally safe to change if not using L7 intentions with path matching. ## Consul 1.17.x @@ -241,6 +250,10 @@ In Consul v1.15 and higher: +### Mesh traffic request path normalization enabled by default + +As of Consul v1.15.15, inbound traffic to mesh proxies will have Envoy request [path normalization](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto#envoy-v3-api-field-extensions-filters-network-http-connection-manager-v3-httpconnectionmanager-normalize-path) applied by default. This should not interfere with the majority of service traffic, but can be disabled if needed by setting `http.incoming.request_normalization.insecure_disable_path_normalization` to `true` in the [global `mesh` configuration entry](/consul/docs/connect/config-entries/mesh#request-normalization). This setting is generally safe to change if not using L7 intentions with path matching. + ## Consul 1.14.x ### Service Mesh Compatibility