Skip to content
Help guide the future of agentgateway — Take the survey

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

Page as Markdown

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.

RuleEffectExample
MergeSlashCollapses repeated slashes into one slash. A backslash (\) counts as a slash.//headers becomes /headers.
DotSegmentResolves . 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.
DecodeUnreservedDecodes percent-encoded unreserved characters: A-Z, a-z, 0-9, -, ., _, and ~. Other encoded characters stay encoded./%68eaders becomes /headers.
RejectEscapedSlashRejects 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.
UnescapeSlashDecodes %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

  1. Set up an agentgateway proxy.
  2. 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.

  1. Create an AgentgatewayPolicy that denies requests to the /headers path 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')"
    EOF
  2. Send a request to /headers and a request to /%68eaders, which is /headers with an encoded h. The --path-as-is option stops curl from changing the path. The gateway denies the /headers request with a 403 response. The /%68eaders request does not match the policy, so the gateway forwards the request. The httpbin app decodes the path and returns the /headers response.

    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')"
    done

    Example output:

    /headers 403
    /%68eaders 200
    
  3. Create 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
    EOF
    SettingDescription
    spec.targetRefsThe Gateway to apply path normalization to. A policy with a frontend section 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.
  4. Send requests to different forms of the /headers path. The gateway normalizes each path before it applies the authorization policy, so the policy denies every form with a 403 response. The paths with an encoded slash and an encoded null character fail with a 400 response.

    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')"
    done

    Example 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
Was this page helpful?
Agentgateway assistant

Ask me anything about agentgateway configuration, features, or usage.

Note: AI-generated content might contain errors; please verify and test all returned information.

Tip: one topic per conversation gives the best results. Use the + button in the chat header to start a new conversation.

Switching topics? Starting a new conversation improves accuracy.
↑↓ navigate ↵ select esc dismiss

What could be improved?

Your feedback helps us improve assistant answers and identify docs gaps we should fix.

Need more help? Join us on Discord: https://discord.gg/y9efgEmppm

Want to use your own agent? Add the Solo MCP server to query our docs directly. Get started here: https://search.solo.io/.