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.

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.

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. Install the agentgateway binary.
  2. 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.

  1. 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.0
  2. Create a configuration file with a route to the httpbin app. The route has an authorization rule that denies requests to the /headers path.

    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")'
    EOF
  3. Run agentgateway with the configuration file.

    agentgateway -f config.yaml
  4. In another terminal, 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. Agentgateway denies the /headers request with a 403 response. The /%68eaders request does not match the rule, so agentgateway 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://localhost:3000$p)"
    done

    Example output:

    /headers 403
    /%68eaders 200
    
  5. Add the frontendPolicies section to the top of the configuration file. Agentgateway reloads the file when it changes.

    frontendPolicies:
      http:
        normalize: [mergeSlash, dotSegment, decodeUnreserved, rejectEscapedSlash]
    SettingDescription
    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.
  6. Send requests to different forms of the /headers path. Agentgateway normalizes each path before it applies the authorization rule, so the rule 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://localhost:3000$p)"
    done

    Example output:

    /headers 403
    /%68eaders 403
    //headers 403
    /anything/../headers 403
    /anything/..%2Fheaders 400
    /head%00ers 400
    

Cleanup

  1. Stop agentgateway by pressing Ctrl+C in the terminal where agentgateway runs.

  2. Remove the httpbin container and the configuration file.

    docker rm -f httpbin
    rm config.yaml
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/.