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.
Attaches to:
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 frontendPolicies.http.normalize field of the configuration file. The rules apply to all requests on every 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
- Install the
agentgatewaybinary. - Make sure that you have
docker, such as by installing Docker Desktop.
Normalize request paths
Configure a route with an authorization rule that denies a path, and send a request that bypasses the rule with an encoded path. Then, turn on path normalization and verify that agentgateway applies the rule to every form of the path.
Start the httpbin sample app in Docker. The app listens on port 8000 on your machine.
docker run -d --name httpbin -p 8000:8080 mccutchen/go-httpbin:v2.15.0Create a configuration file with a route to the httpbin app. The route has an authorization rule that denies requests to the
/headerspath.cat > config.yaml <<EOF # yaml-language-server: \$schema=https://agentgateway.dev/schema/config gateways: default: port: 3000 routes: - backends: - host: localhost:8000 policies: authorization: rules: - deny: 'request.path.startsWith("/headers")' EOFRun agentgateway with the configuration file.
agentgateway -f config.yamlIn another terminal, send a request to
/headersand a request to/%68eaders, which is/headerswith an encodedh. The--path-as-isoption stops curl from changing the path. Agentgateway denies the/headersrequest with a403response. The/%68eadersrequest does not match the rule, so agentgateway 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://localhost:3000$p)" doneExample output:
/headers 403 /%68eaders 200Add the
frontendPoliciessection to the top of the configuration file. Agentgateway reloads the file when it changes.frontendPolicies: http: normalize: [mergeSlash, dotSegment, decodeUnreserved, rejectEscapedSlash]Setting Description frontendPolicies.http.normalizeThe normalization rules to apply to requests on every gateway. 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. Agentgateway normalizes each path before it applies the authorization rule, so the rule 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://localhost:3000$p)" doneExample output:
/headers 403 /%68eaders 403 //headers 403 /anything/../headers 403 /anything/..%2Fheaders 400 /head%00ers 400
Cleanup
Stop agentgateway by pressing
Ctrl+Cin the terminal where agentgateway runs.Remove the httpbin container and the configuration file.
docker rm -f httpbin rm config.yaml