For the complete documentation index, see llms.txt. Markdown versions of all docs pages are available by appending .md to any docs URL.
Path normalization
Harden path-based authorization by rewriting each request path to one form before route matching.
Normalize request paths before route matching, so that routes, policies, and the backend all see the same path.
About path normalization
A client can write the same path in more than one way. For example, /%68eaders, //headers, and /anything/../headers all point to /headers on many backends. The gateway matches policies on the path as the client wrote it. If the backend decodes or cleans up the path before it serves the request, a client can bypass a path-based rule. For example, an authorization rule that denies /headers does not match /%68eaders, but the backend serves /headers for that request.
Path normalization closes this gap. The gateway rewrites the path before route matching. Route matching, policies such as authorization and rate limiting, and the request to the backend use the normalized path. Access logs keep the original path, so you can see what the client sent.
To turn on path normalization, list the rules in the frontend.http.normalize field of an AgentgatewayPolicy that targets a Gateway. The rules apply to all requests on that Gateway.
| Rule | Effect | Example |
|---|---|---|
MergeSlash | Collapses repeated slashes into one slash. A backslash (\) counts as a slash. | //headers becomes /headers. |
DotSegment | Resolves . and .. segments. %2E counts as ., and a backslash counts as a slash. The rule ignores parameters on dot segments, such as ;x in ..;x. | /anything/../headers becomes /headers. |
DecodeUnreserved | Decodes percent-encoded unreserved characters: A-Z, a-z, 0-9, -, ., _, and ~. Other encoded characters stay encoded. | /%68eaders becomes /headers. |
RejectEscapedSlash | Rejects a path that contains an encoded slash, %2F or %5C, with a 400 response. Do not use this rule if a backend expects encoded slashes in a path segment. You cannot set this rule together with UnescapeSlash. | /anything/..%2Fheaders returns 400. |
UnescapeSlash | Decodes %2F and %5C into /. You cannot set this rule together with RejectEscapedSlash. | /anything%2Fheaders becomes /anything/headers. |
The gateway applies the rules in a fixed order, regardless of the order in the list. First, the gateway decodes or rejects percent-encoded characters. Then, the gateway merges slashes. Last, the gateway resolves dot segments.
When you set any rule other than the merge-slash rule, the gateway also checks every percent-encoded character in the path. The gateway rejects a path with a malformed escape, such as %zz, or an encoded null character, %00, with a 400 response and the body invalid request.
Note
The rule names are in TitleCase in Kubernetes resources, such as MergeSlash, and in camelCase in the standalone configuration file, such as mergeSlash. A rule name in the wrong case fails validation.
Before you begin
- Set up an agentgateway proxy.
- Install the httpbin sample app.
Normalize request paths
Create an authorization policy that denies a path, and send a request that bypasses the policy with an encoded path. Then, turn on path normalization and verify that the gateway applies the policy to every form of the path.
Create an AgentgatewayPolicy that denies requests to the
/headerspath of the httpbin app.kubectl apply -f- <<EOF apiVersion: agentgateway.dev/v1alpha1 kind: AgentgatewayPolicy metadata: name: deny-headers namespace: httpbin spec: targetRefs: - group: gateway.networking.k8s.io kind: HTTPRoute name: httpbin traffic: authorization: action: Deny policy: matchExpressions: - "request.path.startsWith('/headers')" EOFSend a request to
/headersand a request to/%68eaders, which is/headerswith an encodedh. The--path-as-isoption stops curl from changing the path. The gateway denies the/headersrequest with a403response. The/%68eadersrequest does not match the policy, so the gateway forwards the request. The httpbin app decodes the path and returns the/headersresponse.for p in /headers /%68eaders; do echo "$p $(curl -s --path-as-is -o /dev/null -w '%{http_code}' http://$INGRESS_GW_ADDRESS:80$p -H 'host: www.example.com:80')" doneExample output:
/headers 403 /%68eaders 200Create an AgentgatewayPolicy that turns on path normalization for the Gateway.
kubectl apply -f- <<EOF apiVersion: agentgateway.dev/v1alpha1 kind: AgentgatewayPolicy metadata: name: path-normalization namespace: agentgateway-system spec: targetRefs: - group: gateway.networking.k8s.io kind: Gateway name: agentgateway-proxy frontend: http: normalize: - MergeSlash - DotSegment - DecodeUnreserved - RejectEscapedSlash EOFSetting Description spec.targetRefsThe Gateway to apply path normalization to. A policy with a frontendsection must target a Gateway. A route target fails validation.spec.frontend.http.normalizeThe normalization rules to apply, from 1 to 5 unique values. This example resolves the encoded, repeated-slash, and dot-segment forms of a path, and rejects encoded slashes. Send requests to different forms of the
/headerspath. The gateway normalizes each path before it applies the authorization policy, so the policy denies every form with a403response. The paths with an encoded slash and an encoded null character fail with a400response.for p in /headers /%68eaders //headers /anything/../headers /anything/..%2Fheaders /head%00ers; do echo "$p $(curl -s --path-as-is -o /dev/null -w '%{http_code}' http://$INGRESS_GW_ADDRESS:80$p -H 'host: www.example.com:80')" doneExample output:
/headers 403 /%68eaders 403 //headers 403 /anything/../headers 403 /anything/..%2Fheaders 400 /head%00ers 400
Cleanup
You can remove the resources that you created in this guide.
kubectl delete AgentgatewayPolicy deny-headers -n httpbin
kubectl delete AgentgatewayPolicy path-normalization -n agentgateway-system