Skip to content

Commit ad6af72

Browse files
agrawrohagrawroh
authored
docs: clean up the header validator docs and make it consistent (#40332)
Signed-off-by: Rohit Agrawal <[email protected]>
1 parent 81df680 commit ad6af72

File tree

1 file changed

+111
-35
lines changed

1 file changed

+111
-35
lines changed

‎api/envoy/extensions/http/header_validators/envoy_default/v3/header_validator.proto‎

Lines changed: 111 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -15,25 +15,33 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE;
1515

1616
// This extension validates that HTTP request and response headers are well formed according to respective RFCs.
1717
//
18-
// #. HTTP/1 header map validity according to `RFC 7230 section 3.2 <https://datatracker.ietf.org/doc/html/rfc7230#section-3.2>`_
19-
// #. Syntax of HTTP/1 request target URI and response status
20-
// #. HTTP/2 header map validity according to `RFC 7540 section 8.1.2 <https://datatracker.ietf.org/doc/html/rfc7540#section-8.1.2>`_
21-
// #. Syntax of HTTP/2 pseudo headers
22-
// #. HTTP/3 header map validity according to `RFC 9114 section 4.3 <https://www.rfc-editor.org/rfc/rfc9114.html>`_
23-
// #. Syntax of HTTP/3 pseudo headers
24-
// #. Syntax of Content-Length and Transfer-Encoding
25-
// #. Validation of HTTP/1 requests with both ``Content-Length`` and ``Transfer-Encoding`` headers
18+
// The validator performs comprehensive HTTP header validation including:
19+
//
20+
// #. HTTP/1 header map validity according to `RFC 7230 section 3.2 <https://datatracker.ietf.org/doc/html/rfc7230#section-3.2>`_.
21+
// #. Syntax of HTTP/1 request target URI and response status.
22+
// #. HTTP/2 header map validity according to `RFC 7540 section 8.1.2 <https://datatracker.ietf.org/doc/html/rfc7540#section-8.1.2>`_.
23+
// #. Syntax of HTTP/2 pseudo headers.
24+
// #. HTTP/3 header map validity according to `RFC 9114 section 4.3 <https://www.rfc-editor.org/rfc/rfc9114.html>`_.
25+
// #. Syntax of HTTP/3 pseudo headers.
26+
// #. Syntax of Content-Length and Transfer-Encoding.
27+
// #. Validation of HTTP/1 requests with both ``Content-Length`` and ``Transfer-Encoding`` headers.
2628
// #. Normalization of the URI path according to `Normalization and Comparison <https://datatracker.ietf.org/doc/html/rfc3986#section-6>`_
27-
// without `case normalization <https://datatracker.ietf.org/doc/html/rfc3986#section-6.2.2.1>`_
29+
// without `case normalization <https://datatracker.ietf.org/doc/html/rfc3986#section-6.2.2.1>`_.
30+
//
31+
// This validator ensures that HTTP traffic processed by Envoy conforms to established
32+
// standards and helps prevent issues caused by malformed headers or invalid HTTP syntax.
2833
//
2934
// [#comment:TODO(yanavlasov): Put #extension: envoy.http.header_validators.envoy_default after it is not hidden any more]
3035
// [#next-free-field: 6]
3136
message HeaderValidatorConfig {
3237
// Action to take when Envoy receives client request with header names containing underscore
3338
// characters.
34-
// Underscore character is allowed in header names by the RFC-7230 and this behavior is implemented
35-
// as a security measure due to systems that treat '_' and '-' as interchangeable. Envoy by default allows client request headers with underscore
36-
// characters.
39+
//
40+
// Underscore character is allowed in header names by RFC-7230, and this behavior is implemented
41+
// as a security measure due to systems that treat ``_`` and ``-`` as interchangeable. Envoy by
42+
// default allows client request headers with underscore characters.
43+
//
44+
// This setting provides control over how to handle such headers for security and compatibility reasons.
3745
enum HeadersWithUnderscoresAction {
3846
// Allow headers with underscores. This is the default behavior.
3947
ALLOW = 0;
@@ -51,102 +59,170 @@ message HeaderValidatorConfig {
5159
DROP_HEADER = 2;
5260
}
5361

62+
// Configuration options for URI path normalization and transformation.
63+
//
64+
// These options control how Envoy processes and normalizes incoming request URI paths
65+
// to ensure consistent behavior and security. Path normalization helps prevent
66+
// path traversal attacks and ensures that equivalent paths are handled consistently.
5467
message UriPathNormalizationOptions {
5568
// Determines the action for requests that contain ``%2F``, ``%2f``, ``%5C`` or ``%5c`` sequences in the URI path.
5669
// This operation occurs before URL normalization and the merge slashes transformations if they were enabled.
70+
//
71+
// Escaped slash sequences in URLs can be used for path confusion attacks, so proper handling
72+
// is important for security.
5773
enum PathWithEscapedSlashesAction {
5874
// Default behavior specific to implementation (i.e. Envoy) of this configuration option.
5975
// Envoy, by default, takes the ``KEEP_UNCHANGED`` action.
60-
// NOTE: the implementation may change the default behavior at-will.
76+
//
77+
// .. note::
78+
//
79+
// The implementation may change the default behavior at-will.
80+
//
6181
IMPLEMENTATION_SPECIFIC_DEFAULT = 0;
6282

63-
// Keep escaped slashes.
83+
// Keep escaped slashes unchanged in the URI path.
84+
// This preserves the original request path without any modifications to escaped sequences.
6485
KEEP_UNCHANGED = 1;
6586

6687
// Reject client request with the 400 status. gRPC requests will be rejected with the ``INTERNAL`` (13) error code.
67-
// The ``http#.downstream_rq_failed_path_normalization`` counter is incremented for each rejected request.
88+
// The :ref:`httpN.downstream_rq_failed_path_normalization <config_http_conn_man_stats_per_codec>` counter is incremented for each rejected request.
89+
//
90+
// This is the safest option when security is a primary concern, as it prevents any potential
91+
// path confusion attacks by rejecting requests with escaped slashes entirely.
6892
REJECT_REQUEST = 2;
6993

7094
// Unescape ``%2F`` and ``%5C`` sequences and redirect the request to the new path if these sequences were present.
7195
// The redirect occurs after path normalization and merge slashes transformations if they were configured.
72-
// NOTE: gRPC requests will be rejected with the ``INTERNAL`` (13) error code.
73-
// This option minimizes possibility of path confusion exploits by forcing request with unescaped slashes to
74-
// traverse all parties: downstream client, intermediate proxies, Envoy and upstream server.
75-
// The ``http#.downstream_rq_redirected_with_normalized_path`` counter is incremented for each
96+
//
97+
// .. note::
98+
//
99+
// gRPC requests will be rejected with the ``INTERNAL`` (13) error code.
100+
// This option minimizes possibility of path confusion exploits by forcing request with unescaped slashes to
101+
// traverse all parties: downstream client, intermediate proxies, Envoy and upstream server.
102+
//
103+
// The :ref:`httpN.downstream_rq_redirected_with_normalized_path <config_http_conn_man_stats_per_codec>` counter is incremented for each
76104
// redirected request.
77105
UNESCAPE_AND_REDIRECT = 3;
78106

79107
// Unescape ``%2F`` and ``%5C`` sequences.
80-
// Note: this option should not be enabled if intermediaries perform path based access control as
81-
// it may lead to path confusion vulnerabilities.
108+
//
109+
// .. attention::
110+
//
111+
// This option should not be enabled if intermediaries perform path based access control as
112+
// it may lead to path confusion vulnerabilities.
113+
//
82114
UNESCAPE_AND_FORWARD = 4;
83115
}
84116

85117
// Should paths be normalized according to RFC 3986?
118+
//
86119
// This operation overwrites the original request URI path and the new path is used for processing of
87120
// the request by HTTP filters and proxied to the upstream service.
88121
// Envoy will respond with 400 to requests with malformed paths that fail path normalization.
89122
// The default behavior is to normalize the path.
123+
//
90124
// This value may be overridden by the runtime variable
91125
// :ref:`http_connection_manager.normalize_path<config_http_conn_man_runtime_normalize_path>`.
92126
// See `Normalization and Comparison <https://datatracker.ietf.org/doc/html/rfc3986#section-6>`_
93127
// for details of normalization.
94-
// Note that Envoy does not perform
95-
// `case normalization <https://datatracker.ietf.org/doc/html/rfc3986#section-6.2.2.1>`_
96-
// URI path normalization can be applied to a portion of requests by setting the
97-
// ``envoy_default_header_validator.path_normalization`` runtime value.
128+
//
129+
// .. note::
130+
//
131+
// Envoy does not perform
132+
// `case normalization <https://datatracker.ietf.org/doc/html/rfc3986#section-6.2.2.1>`_.
133+
// URI path normalization can be applied to a portion of requests by setting the
134+
// ``envoy_default_header_validator.path_normalization`` runtime value.
135+
//
98136
bool skip_path_normalization = 1;
99137

100138
// Determines if adjacent slashes in the path are merged into one.
139+
//
101140
// This operation overwrites the original request URI path and the new path is used for processing of
102141
// the request by HTTP filters and proxied to the upstream service.
103-
// Setting this option to true will cause incoming requests with path ``//dir///file`` to not match against
104-
// route with ``prefix`` match set to ``/dir``. Defaults to ``false``. Note that slash merging is not part of
105-
// `HTTP spec <https://datatracker.ietf.org/doc/html/rfc3986>`_ and is provided for convenience.
106-
// Merging of slashes in URI path can be applied to a portion of requests by setting the
107-
// ``envoy_default_header_validator.merge_slashes`` runtime value.
142+
// Setting this option to ``true`` will cause incoming requests with path ``//dir///file`` to not match against
143+
// route with ``prefix`` match set to ``/dir``. Defaults to ``false``.
144+
//
145+
// .. note::
146+
//
147+
// Slash merging is not part of the
148+
// `HTTP spec <https://datatracker.ietf.org/doc/html/rfc3986>`_ and is provided for convenience.
149+
// Merging of slashes in URI path can be applied to a portion of requests by setting the
150+
// ``envoy_default_header_validator.merge_slashes`` runtime value.
151+
//
108152
bool skip_merging_slashes = 2;
109153

110154
// The action to take when request URL path contains escaped slash sequences (``%2F``, ``%2f``, ``%5C`` and ``%5c``).
155+
//
111156
// This operation may overwrite the original request URI path and the new path is used for processing of
112157
// the request by HTTP filters and proxied to the upstream service.
158+
//
159+
// The handling of escaped slashes is important for security as these sequences can be used
160+
// in path confusion attacks to bypass access controls.
113161
PathWithEscapedSlashesAction path_with_escaped_slashes_action = 3
114162
[(validate.rules).enum = {defined_only: true}];
115163
}
116164

165+
// HTTP/1 protocol specific options for header validation.
166+
//
167+
// These options control how Envoy handles HTTP/1 specific behaviors and edge cases
168+
// that may not apply to HTTP/2 or HTTP/3 protocols.
117169
message Http1ProtocolOptions {
118170
// Allows Envoy to process HTTP/1 requests/responses with both ``Content-Length`` and ``Transfer-Encoding``
119171
// headers set. By default such messages are rejected, but if option is enabled - Envoy will
120172
// remove the ``Content-Length`` header and process the message.
173+
//
121174
// See `RFC7230, sec. 3.3.3 <https://datatracker.ietf.org/doc/html/rfc7230#section-3.3.3>`_ for details.
122175
//
123176
// .. attention::
177+
//
124178
// Enabling this option might lead to request smuggling vulnerabilities, especially if traffic
125179
// is proxied via multiple layers of proxies.
180+
//
126181
bool allow_chunked_length = 1;
127182
}
128183

184+
// HTTP/1 protocol specific options.
185+
// These settings control HTTP/1 specific validation behaviors.
129186
Http1ProtocolOptions http1_protocol_options = 1;
130187

131188
// The URI path normalization options.
189+
//
132190
// By default Envoy normalizes URI path using the default values of the :ref:`UriPathNormalizationOptions
133191
// <envoy_v3_api_msg_extensions.http.header_validators.envoy_default.v3.HeaderValidatorConfig.UriPathNormalizationOptions>`.
134192
// URI path transformations specified by the ``uri_path_normalization_options`` configuration can be applied to a portion
135193
// of requests by setting the ``envoy_default_header_validator.uri_path_transformations`` runtime value.
136-
// Caution: disabling path normalization may lead to path confusion vulnerabilities in access control or incorrect service
137-
// selection.
194+
//
195+
// .. attention::
196+
//
197+
// Disabling path normalization may lead to path confusion vulnerabilities in access control or incorrect service
198+
// selection.
199+
//
138200
UriPathNormalizationOptions uri_path_normalization_options = 2;
139201

140-
// Restrict HTTP methods to these defined in the `RFC 7231 section 4.1 <https://datatracker.ietf.org/doc/html/rfc7231#section-4.1>`_
202+
// Restrict HTTP methods to these defined in the `RFC 7231 section 4.1 <https://datatracker.ietf.org/doc/html/rfc7231#section-4.1>`_.
203+
//
141204
// Envoy will respond with 400 to requests with disallowed methods.
142205
// By default methods with arbitrary names are accepted.
206+
//
207+
// This setting helps enforce HTTP compliance and can prevent attacks that rely on
208+
// non-standard HTTP methods.
143209
bool restrict_http_methods = 3;
144210

145211
// Action to take when a client request with a header name containing underscore characters is received.
146-
// If this setting is not specified, the value defaults to ALLOW.
212+
//
213+
// If this setting is not specified, the value defaults to ``ALLOW``.
214+
//
215+
// This setting provides security control over headers with underscores, which can be a source
216+
// of security issues when different systems interpret underscores and hyphens differently.
147217
HeadersWithUnderscoresAction headers_with_underscores_action = 4;
148218

149219
// Allow requests with fragment in URL path and strip the fragment before request processing.
150-
// By default Envoy rejects requests with fragment in URL path.
220+
//
221+
// By default Envoy rejects requests with fragment in URL path. When this option is enabled,
222+
// the fragment portion (everything after ``#``) will be removed from the path before
223+
// further processing.
224+
//
225+
// Fragments are typically used by client-side applications and should not normally
226+
// be sent to the server, so stripping them can help normalize requests.
151227
bool strip_fragment_from_path = 5;
152228
}

0 commit comments

Comments
 (0)