Envoy’s default Header Validator config (proto)

extensions.http.header_validators.envoy_default.v3.HeaderValidatorConfig

[extensions.http.header_validators.envoy_default.v3.HeaderValidatorConfig proto]

This extension validates that HTTP request and response headers are well formed according to respective RFCs.

  1. HTTP/1 header map validity according to RFC 7230 section 3.2

  2. Syntax of HTTP/1 request target URI and response status

  3. HTTP/2 header map validity according to RFC 7540 section 8.1.2

  4. Syntax of HTTP/2 pseudo headers

  5. HTTP/3 header map validity according to RFC 9114 section 4.3

  6. Syntax of HTTP/3 pseudo headers

  7. Syntax of Content-Length and Transfer-Encoding

  8. Validation of HTTP/1 requests with both Content-Length and Transfer-Encoding headers

  9. Normalization of the URI path according to Normalization and Comparison without case normalization

{
  "http1_protocol_options": {...},
  "uri_path_normalization_options": {...},
  "restrict_http_methods": ...,
  "headers_with_underscores_action": ...
}
http1_protocol_options

(extensions.http.header_validators.envoy_default.v3.HeaderValidatorConfig.Http1ProtocolOptions)

uri_path_normalization_options

(extensions.http.header_validators.envoy_default.v3.HeaderValidatorConfig.UriPathNormalizationOptions) The URI path normalization options. By default Envoy normalizes URI path using the default values of the UriPathNormalizationOptions. URI path transformations specified by the uri_path_normalization_options configuration can be applied to a portion of requests by setting the envoy_default_header_validator.uri_path_transformations runtime value. Caution: disabling path normalization may lead to path confusion vulnerabilities in access control or incorrect service selection.

restrict_http_methods

(bool) Restrict HTTP methods to these defined in the RFC 7231 section 4.1 Envoy will respond with 400 to requests with disallowed methods. By default methods with arbitrary names are accepted.

headers_with_underscores_action

(extensions.http.header_validators.envoy_default.v3.HeaderValidatorConfig.HeadersWithUnderscoresAction) Action to take when a client request with a header name containing underscore characters is received. If this setting is not specified, the value defaults to ALLOW.

extensions.http.header_validators.envoy_default.v3.HeaderValidatorConfig.UriPathNormalizationOptions

[extensions.http.header_validators.envoy_default.v3.HeaderValidatorConfig.UriPathNormalizationOptions proto]

{
  "skip_path_normalization": ...,
  "skip_merging_slashes": ...,
  "path_with_escaped_slashes_action": ...
}
skip_path_normalization

(bool) Should paths be normalized according to RFC 3986? This operation overwrites the original request URI path and the new path is used for processing of the request by HTTP filters and proxied to the upstream service. Envoy will respond with 400 to requests with malformed paths that fail path normalization. The default behavior is to normalize the path. This value may be overridden by the runtime variable http_connection_manager.normalize_path. See Normalization and Comparison for details of normalization. Note that Envoy does not perform case normalization URI path normalization can be applied to a portion of requests by setting the envoy_default_header_validator.path_normalization runtime value.

skip_merging_slashes

(bool) Determines if adjacent slashes in the path are merged into one. This operation overwrites the original request URI path and the new path is used for processing of the request by HTTP filters and proxied to the upstream service. Setting this option to true will cause incoming requests with path //dir///file to not match against route with prefix match set to /dir. Defaults to false. Note that slash merging is not part of HTTP spec and is provided for convenience. Merging of slashes in URI path can be applied to a portion of requests by setting the envoy_default_header_validator.merge_slashes runtime value.

path_with_escaped_slashes_action

(extensions.http.header_validators.envoy_default.v3.HeaderValidatorConfig.UriPathNormalizationOptions.PathWithEscapedSlashesAction) The action to take when request URL path contains escaped slash sequences (%2F, %2f, %5C and %5c). This operation may overwrite the original request URI path and the new path is used for processing of the request by HTTP filters and proxied to the upstream service.

Enum extensions.http.header_validators.envoy_default.v3.HeaderValidatorConfig.UriPathNormalizationOptions.PathWithEscapedSlashesAction

[extensions.http.header_validators.envoy_default.v3.HeaderValidatorConfig.UriPathNormalizationOptions.PathWithEscapedSlashesAction proto]

Determines the action for requests that contain %2F, %2f, %5C or %5c sequences in the URI path. This operation occurs before URL normalization and the merge slashes transformations if they were enabled.

IMPLEMENTATION_SPECIFIC_DEFAULT

(DEFAULT) ⁣Default behavior specific to implementation (i.e. Envoy) of this configuration option. Envoy, by default, takes the KEEP_UNCHANGED action. NOTE: the implementation may change the default behavior at-will.

KEEP_UNCHANGED

⁣Keep escaped slashes.

REJECT_REQUEST

⁣Reject client request with the 400 status. gRPC requests will be rejected with the INTERNAL (13) error code. The http#.downstream_rq_failed_path_normalization counter is incremented for each rejected request.

UNESCAPE_AND_REDIRECT

⁣Unescape %2F and %5C sequences and redirect the request to the new path if these sequences were present. The redirect occurs after path normalization and merge slashes transformations if they were configured. NOTE: gRPC requests will be rejected with the INTERNAL (13) error code. This option minimizes possibility of path confusion exploits by forcing request with unescaped slashes to traverse all parties: downstream client, intermediate proxies, Envoy and upstream server. The http#.downstream_rq_redirected_with_normalized_path counter is incremented for each redirected request.

UNESCAPE_AND_FORWARD

⁣Unescape %2F and %5C sequences. Note: this option should not be enabled if intermediaries perform path based access control as it may lead to path confusion vulnerabilities.

extensions.http.header_validators.envoy_default.v3.HeaderValidatorConfig.Http1ProtocolOptions

[extensions.http.header_validators.envoy_default.v3.HeaderValidatorConfig.Http1ProtocolOptions proto]

{
  "allow_chunked_length": ...
}
allow_chunked_length

(bool) Allows Envoy to process HTTP/1 requests/responses with both Content-Length and Transfer-Encoding headers set. By default such messages are rejected, but if option is enabled - Envoy will remove the Content-Length header and process the message. See RFC7230, sec. 3.3.3 for details.

Attention

Enabling this option might lead to request smuggling vulnerabilities, especially if traffic is proxied via multiple layers of proxies.

Enum extensions.http.header_validators.envoy_default.v3.HeaderValidatorConfig.HeadersWithUnderscoresAction

[extensions.http.header_validators.envoy_default.v3.HeaderValidatorConfig.HeadersWithUnderscoresAction proto]

Action to take when Envoy receives client request with header names containing underscore characters. Underscore character is allowed in header names by the RFC-7230 and this behavior is implemented as a security measure due to systems that treat ‘_’ and ‘-’ as interchangeable. Envoy by default allows client request headers with underscore characters.

ALLOW

(DEFAULT) ⁣Allow headers with underscores. This is the default behavior.

REJECT_REQUEST

⁣Reject client request. HTTP/1 requests are rejected with the 400 status. HTTP/2 requests end with the stream reset. The httpN.requests_rejected_with_underscores_in_headers counter is incremented for each rejected request.

DROP_HEADER

⁣Drop the client header with name containing underscores. The header is dropped before the filter chain is invoked and as such filters will not see dropped headers. The httpN.dropped_headers_with_underscores is incremented for each dropped header.