Skip to content

Commit c311aa9

Browse files
PreeticpPreeticp
authored
Merge pull request #32580 from JStickler/OSSMDOC-331
OSSMDOC-331 Additional RN content.
2 parents 3353285 + cf9eb24 commit c311aa9

File tree

2 files changed

+277
-0
lines changed

2 files changed

+277
-0
lines changed

‎modules/ossm-rn-new-features-1x.adoc

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,121 @@ This release of {ProductName} addresses Common Vulnerabilities and Exposures (CV
4444

4545
This release of {ProductName} addresses Common Vulnerabilities and Exposures (CVEs) and bug fixes.
4646

47+
[IMPORTANT]
48+
====
49+
There are manual steps that must be completed to address CVE-2021-29492 and CVE-2021-31920.
50+
====
51+
52+
[id="manual-updates-cve-2021-29492_{context}"]
53+
=== Manual updates required by CVE-2021-29492 and CVE-2021-31920
54+
55+
Istio contains a remotely exploitable vulnerability where an HTTP request path with multiple slashes or escaped slash characters (``%2F` or ``%5C`) could potentially bypass an Istio authorization policy when path-based authorization rules are used.
56+
57+
For example, assume an Istio cluster administrator defines an authorization DENY policy to reject the request at path `/admin`. A request sent to the URL path `//admin` will NOT be rejected by the authorization policy.
58+
59+
According to https://tools.ietf.org/html/rfc3986#section-6[RFC 3986], the path `//admin` with multiple slashes should technically be treated as a different path from the `/admin`. However, some backend services choose to normalize the URL paths by merging multiple slashes into a single slash. This can result in a bypass of the authorization policy (`//admin` does not match `/admin`), and a user can access the resource at path `/admin` in the backend; this would represent a security incident.
60+
61+
Your cluster is impacted by this vulnerability if you have authorization policies using `ALLOW action + notPaths` field or `DENY action + paths field` patterns. These patterns are vulnerable to unexpected policy bypasses.
62+
63+
Your cluster is NOT impacted by this vulnerability if:
64+
65+
* You don’t have authorization policies.
66+
* Your authorization policies don’t define `paths` or `notPaths` fields.
67+
* Your authorization policies use `ALLOW action + paths` field or `DENY action + notPaths` field patterns. These patterns could only cause unexpected rejection instead of policy bypasses. The upgrade is optional for these cases.
68+
69+
[NOTE]
70+
====
71+
The {ProductName} configuration location for path normalization is different from the Istio configuration.
72+
====
73+
74+
=== Updating the path normalization configuration
75+
76+
Istio authorization policies can be based on the URL paths in the HTTP request.
77+
https://en.wikipedia.org/wiki/URI_normalization[Path normalization], also known as URI normalization, modifies and standardizes the incoming requests' paths so that the normalized paths can be processed in a standard way.
78+
Syntactically different paths may be equivalent after path normalization.
79+
80+
Istio supports the following normalization schemes on the request paths before evaluating against the authorization policies and routing the requests:
81+
82+
.Normalization schemes
83+
[options="header"]
84+
[cols="a, a, a, a"]
85+
|====
86+
| Option | Description | Example |Notes
87+
|`NONE`
88+
|No normalization is done. Anything received by Envoy will be forwarded exactly as-is to any backend service.
89+
|`../%2Fa../b` is evaluated by the authorization policies and sent to your service.
90+
|This setting is vulnerable to CVE-2021-31920.
91+
92+
|`BASE`
93+
|This is currently the option used in the *default* installation of Istio. This applies the 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[`normalize_path`] option on Envoy proxies, which follows https://tools.ietf.org/html/rfc3986[RFC 3986] with extra normalization to convert backslashes to forward slashes.
94+
|`/a/../b` is normalized to `/b`. `\da` is normalized to `/da`.
95+
|This setting is vulnerable to CVE-2021-31920.
96+
97+
| `MERGE_SLASHES`
98+
| Slashes are merged after the _BASE_ normalization.
99+
| `/a//b` is normalized to `/a/b`.
100+
|Update to this setting to mitigate CVE-2021-31920.
101+
102+
|`DECODE_AND_MERGE_SLASHES`
103+
|The strictest setting when you allow all traffic by default. This setting is recommended, with the caveat that you must thoroughly test your authorization policies routes. https://tools.ietf.org/html/rfc3986#section-2.1[Percent-encoded] slash and backslash characters (`%2F`, `%2f`, `%5C` and `%5c`) are decoded to `/` or `\`, before the `MERGE_SLASHES` normalization.
104+
|`/a%2fb` is normalized to `/a/b`.
105+
|Update to this setting to mitigate CVE-2021-31920. This setting is more secure, but also has the potential to break applications. Test your applications before deploying to production.
106+
|====
107+
108+
The normalization algorithms are conducted in the following order:
109+
110+
. Percent-decode `%2F`, `%2f`, `%5C` and `%5c`.
111+
. The https://tools.ietf.org/html/rfc3986[RFC 3986] and other normalization implemented by the 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[`normalize_path`] option in Envoy.
112+
. Merge slashes.
113+
114+
[WARNING]
115+
====
116+
While these normalization options represent recommendations from HTTP standards and common industry practices, applications may interpret a URL in any way it chooses to. When using denial policies, ensure that you understand how your application behaves.
117+
====
118+
119+
=== Path normalization configuration examples
120+
121+
Ensuring Envoy normalizes request paths to match your backend services' expectations is critical to the security of your system.
122+
The following examples can be used as a reference for you to configure your system.
123+
The normalized URL paths, or the original URL paths if `NONE` is selected, will be:
124+
125+
. Used to check against the authorization policies.
126+
. Forwarded to the backend application.
127+
128+
.Configuration examples
129+
[options="header"]
130+
[cols="a, a"]
131+
|====
132+
|If your application... |Choose...
133+
|Relies on the proxy to do normalization
134+
|`BASE`, `MERGE_SLASHES` or `DECODE_AND_MERGE_SLASHES`
135+
136+
|Normalizes request paths based on https://tools.ietf.org/html/rfc3986[RFC 3986] and does not merge slashes.
137+
|`BASE`
138+
139+
|Normalizes request paths based on https://tools.ietf.org/html/rfc3986[RFC 3986] and merges slashes, but does not decode https://tools.ietf.org/html/rfc3986#section-2.1[percent-encoded] slashes.
140+
|`MERGE_SLASHES`
141+
142+
|Normalizes request paths based on https://tools.ietf.org/html/rfc3986[RFC 3986], decodes https://tools.ietf.org/html/rfc3986#section-2.1[percent-encoded] slashes, and merges slashes.
143+
|`DECODE_AND_MERGE_SLASHES`
144+
145+
|Processes request paths in a way that is incompatible with https://tools.ietf.org/html/rfc3986[RFC 3986].
146+
|`NONE`
147+
|====
148+
149+
=== Configuring your SMCP for path normalization
150+
151+
To configure path normalization for {ProductName}, specify the following in your `ServiceMeshControlPlane`. Use the configuration examples to help determine the settings for your system.
152+
153+
.SMCP v1 pathNormalization
154+
[source,yaml]
155+
----
156+
spec:
157+
global:
158+
pathNormalization: <option>
159+
----
160+
161+
47162
== New features {ProductName} 1.1.13
48163

49164
This release of {ProductName} addresses Common Vulnerabilities and Exposures (CVEs) and bug fixes.

‎modules/ossm-rn-new-features.adoc

Lines changed: 162 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,168 @@ This release of {ProductName} addresses Common Vulnerabilities and Exposures (CV
4444

4545
This release of {ProductName} addresses Common Vulnerabilities and Exposures (CVEs) and bug fixes.
4646

47+
[IMPORTANT]
48+
====
49+
There are manual steps that must be completed to address CVE-2021-29492 and CVE-2021-31920.
50+
====
51+
52+
[id="manual-updates-cve-2021-29492_{context}"]
53+
=== Manual updates required by CVE-2021-29492 and CVE-2021-31920
54+
55+
Istio contains a remotely exploitable vulnerability where an HTTP request path with multiple slashes or escaped slash characters (``%2F` or ``%5C`) could potentially bypass an Istio authorization policy when path-based authorization rules are used.
56+
57+
For example, assume an Istio cluster administrator defines an authorization DENY policy to reject the request at path `/admin`. A request sent to the URL path `//admin` will NOT be rejected by the authorization policy.
58+
59+
According to https://tools.ietf.org/html/rfc3986#section-6[RFC 3986], the path `//admin` with multiple slashes should technically be treated as a different path from the `/admin`. However, some backend services choose to normalize the URL paths by merging multiple slashes into a single slash. This can result in a bypass of the authorization policy (`//admin` does not match `/admin`), and a user can access the resource at path `/admin` in the backend; this would represent a security incident.
60+
61+
Your cluster is impacted by this vulnerability if you have authorization policies using `ALLOW action + notPaths` field or `DENY action + paths field` patterns. These patterns are vulnerable to unexpected policy bypasses.
62+
63+
Your cluster is NOT impacted by this vulnerability if:
64+
65+
* You don’t have authorization policies.
66+
* Your authorization policies don’t define `paths` or `notPaths` fields.
67+
* Your authorization policies use `ALLOW action + paths` field or `DENY action + notPaths` field patterns. These patterns could only cause unexpected rejection instead of policy bypasses. The upgrade is optional for these cases.
68+
69+
[NOTE]
70+
====
71+
The {ProductName} configuration location for path normalization is different from the Istio configuration.
72+
====
73+
74+
=== Updating the path normalization configuration
75+
76+
Istio authorization policies can be based on the URL paths in the HTTP request.
77+
https://en.wikipedia.org/wiki/URI_normalization[Path normalization], also known as URI normalization, modifies and standardizes the incoming requests' paths so that the normalized paths can be processed in a standard way.
78+
Syntactically different paths may be equivalent after path normalization.
79+
80+
Istio supports the following normalization schemes on the request paths before evaluating against the authorization policies and routing the requests:
81+
82+
.Normalization schemes
83+
[options="header"]
84+
[cols="a, a, a, a"]
85+
|====
86+
| Option | Description | Example |Notes
87+
|`NONE`
88+
|No normalization is done. Anything received by Envoy will be forwarded exactly as-is to any backend service.
89+
|`../%2Fa../b` is evaluated by the authorization policies and sent to your service.
90+
|This setting is vulnerable to CVE-2021-31920.
91+
92+
|`BASE`
93+
|This is currently the option used in the *default* installation of Istio. This applies the 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[`normalize_path`] option on Envoy proxies, which follows https://tools.ietf.org/html/rfc3986[RFC 3986] with extra normalization to convert backslashes to forward slashes.
94+
|`/a/../b` is normalized to `/b`. `\da` is normalized to `/da`.
95+
|This setting is vulnerable to CVE-2021-31920.
96+
97+
| `MERGE_SLASHES`
98+
| Slashes are merged after the _BASE_ normalization.
99+
| `/a//b` is normalized to `/a/b`.
100+
|Update to this setting to mitigate CVE-2021-31920.
101+
102+
|`DECODE_AND_MERGE_SLASHES`
103+
|The strictest setting when you allow all traffic by default. This setting is recommended, with the caveat that you must thoroughly test your authorization policies routes. https://tools.ietf.org/html/rfc3986#section-2.1[Percent-encoded] slash and backslash characters (`%2F`, `%2f`, `%5C` and `%5c`) are decoded to `/` or `\`, before the `MERGE_SLASHES` normalization.
104+
|`/a%2fb` is normalized to `/a/b`.
105+
|Update to this setting to mitigate CVE-2021-31920. This setting is more secure, but also has the potential to break applications. Test your applications before deploying to production.
106+
|====
107+
108+
The normalization algorithms are conducted in the following order:
109+
110+
. Percent-decode `%2F`, `%2f`, `%5C` and `%5c`.
111+
. The https://tools.ietf.org/html/rfc3986[RFC 3986] and other normalization implemented by the 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[`normalize_path`] option in Envoy.
112+
. Merge slashes.
113+
114+
[WARNING]
115+
====
116+
While these normalization options represent recommendations from HTTP standards and common industry practices, applications may interpret a URL in any way it chooses to. When using denial policies, ensure that you understand how your application behaves.
117+
====
118+
119+
=== Path normalization configuration examples
120+
121+
Ensuring Envoy normalizes request paths to match your backend services' expectations is critical to the security of your system.
122+
The following examples can be used as a reference for you to configure your system.
123+
The normalized URL paths, or the original URL paths if `NONE` is selected, will be:
124+
125+
. Used to check against the authorization policies.
126+
. Forwarded to the backend application.
127+
128+
.Configuration examples
129+
[options="header"]
130+
[cols="a, a"]
131+
|====
132+
|If your application... |Choose...
133+
|Relies on the proxy to do normalization
134+
|`BASE`, `MERGE_SLASHES` or `DECODE_AND_MERGE_SLASHES`
135+
136+
|Normalizes request paths based on https://tools.ietf.org/html/rfc3986[RFC 3986] and does not merge slashes.
137+
|`BASE`
138+
139+
|Normalizes request paths based on https://tools.ietf.org/html/rfc3986[RFC 3986] and merges slashes, but does not decode https://tools.ietf.org/html/rfc3986#section-2.1[percent-encoded] slashes.
140+
|`MERGE_SLASHES`
141+
142+
|Normalizes request paths based on https://tools.ietf.org/html/rfc3986[RFC 3986], decodes https://tools.ietf.org/html/rfc3986#section-2.1[percent-encoded] slashes, and merges slashes.
143+
|`DECODE_AND_MERGE_SLASHES`
144+
145+
|Processes request paths in a way that is incompatible with https://tools.ietf.org/html/rfc3986[RFC 3986].
146+
|`NONE`
147+
|====
148+
149+
=== Configuring your SMCP for path normalization
150+
151+
To configure path normalization for {ProductName}, specify the following in your `ServiceMeshControlPlane`. Use the configuration examples to help determine the settings for your system.
152+
153+
.SMCP v2 pathNormalization
154+
[source,yaml]
155+
----
156+
spec:
157+
techPreview:
158+
global:
159+
pathNormalization: <option>
160+
----
161+
162+
=== Configuring for case normalization
163+
164+
In some environments, it may be useful to have paths in authorization policies compared in a case insensitive manner.
165+
For example, treating `https://myurl/get` and `https://myurl/GeT` as equivalent.
166+
In those cases, you can use the `EnvoyFilter` shown below.
167+
This filter will change both the path used for comparison and the path presented to the application.
168+
169+
Save the `EnvoyFilter` to a file and execute the following command:
170+
171+
[source,terminal]
172+
----
173+
$ oc create -f <myEnvoyFilterFile>
174+
----
175+
176+
[source,yaml]
177+
----
178+
apiVersion: networking.istio.io/v1alpha3
179+
kind: EnvoyFilter
180+
metadata:
181+
name: ingress-case-insensitive
182+
namespace: istio-system
183+
spec:
184+
configPatches:
185+
- applyTo: HTTP_FILTER
186+
match:
187+
context: GATEWAY
188+
listener:
189+
filterChain:
190+
filter:
191+
name: "envoy.filters.network.http_connection_manager"
192+
subFilter:
193+
name: "envoy.filters.http.router"
194+
patch:
195+
operation: INSERT_BEFORE
196+
value:
197+
name: envoy.lua
198+
typed_config:
199+
"@type": "type.googleapis.com/envoy.extensions.filters.http.lua.v3.Lua"
200+
inlineCode: |
201+
function envoy_on_request(request_handle)
202+
local path = request_handle:headers():get(":path")
203+
request_handle:headers():replace(":path", string.lower(path))
204+
end
205+
206+
----
207+
208+
47209
== New features {ProductName} 2.0.3
48210

49211
This release of {ProductName} addresses Common Vulnerabilities and Exposures (CVEs) and bug fixes.

0 commit comments

Comments
 (0)