Join our Newsletter — 33% off our NHI Course
Home› Guides› Nginx Alias Traversal and Reverse Proxy Path Normalisation…
Guide Web & API Security

Nginx Alias Traversal and Reverse Proxy Path Normalisation Guide: Safe Location, Alias and Proxy Patterns

PDF for newsletter subscribers · free to read online

← All guides
By NHI Mgmt Group, edited by Lalit Choda Updated 14 November 2026 14 min read
On this page

A single missing slash in an nginx location block, or a proxy and a backend that disagree about what a path means, can expose files outside the intended directory or let requests reach routes that access rules were meant to block. These are configuration problems, not software bugs, so patching does not fix them and they survive into every new deployment that copies the same snippet. This guide covers the alias "off by slash" pattern, how nginx normalises URIs before matching locations, the merge_slashes setting, and the wider class of path normalisation mismatches between a reverse proxy and the application behind it. It is written for platform engineers, application security teams and reviewers who own nginx configuration or assess it. Baseline hardening such as TLS, headers and module selection is in the NGINX Security Hardening Guide; this page goes deeper on paths only.

This is an independent guide from NHI Mgmt Group, based on nginx's public documentation as of November 2026. It is not sponsored or reviewed by nginx. Product features change, so confirm settings against nginx's current documentation.

Key takeaways

  • Match the trailing slash. When a prefix location uses alias, end the location with "/" whenever the alias path ends with "/", or use root instead, so the request remainder cannot step out of the aliased directory.
  • Location matching uses a normalised URI. nginx decodes %XX sequences, resolves "." and ".." and, with merge_slashes on, compresses repeated slashes before choosing a location, so rules must be written against that normalised form.
  • proxy_pass with or without a URI behaves differently. With a URI, nginx sends the normalised path; without one, it forwards the request URI as the client sent it, leaving the backend to interpret encodings and dot segments its own way.
  • Two parsers, one decision. Access rules enforced at the proxy are only safe if the backend resolves the same path to the same resource; otherwise enforce authorisation in the application as well.
  • Configuration review catches most of this. A static analyser for nginx configuration in CI, plus differential tests between proxy and backend, finds these issues before they reach production.

The alias off-by-slash pattern

The nginx alias directive defines a replacement for the part of the URI matched by the location. The documentation's own example maps location /i/ to alias /data/w3/images/;, so a request for /i/top.gif is served from /data/w3/images/top.gif. The problem appears when the location prefix and the alias path do not agree on the trailing slash.

If the location is written location /i (no trailing slash) while the alias is /data/w3/images/, the remainder of the request after "/i" is appended directly to the alias path. A remainder that begins with a dot segment can then resolve to the parent of the images directory. The Gixy project's alias_traversal check documents this exact case, where a crafted request returns a file from a sibling application directory instead of the images folder. The result is arbitrary file read within whatever the nginx worker can access, which commonly includes application source, configuration files and stored secrets.

Safe and unsafe forms

ConfigurationRiskWhy
location /static/ { alias /srv/app/static/; }SafeBoth end with "/"; the remainder always starts inside the aliased directory
location /static { alias /srv/app/static/; }UnsafePrefix without trailing slash; the remainder can begin with a dot segment and escape the directory
location /static/ { root /srv/app; }Safe, preferredThe documentation recommends root when the location matches the last part of the alias value; the full URI is appended to root after normalisation
location = /favicon.ico { alias /srv/app/static/favicon.ico; }SafeExact match location for a single file, as Gixy recommends
location ~ ^/users/(.+\.(?:gif|jpe?g|png))$ { alias /data/w3/images/$1; }ReviewIn a regex location alias is a complete file path built from captures; the capture pattern must not admit dot segments or slashes you do not intend

For the general traversal mechanics and how they differ from inclusion bugs, see the Path Traversal Guide and Local File Inclusion vs Path Traversal.

How nginx normalises URIs

The nginx core module documentation states that location matching is performed against a normalised URI, after decoding text encoded in the %XX form, resolving references to "." and "..", and possible compression of two or more adjacent slashes into a single slash. Three consequences matter for security:

  • Locations see the decoded path: an encoded dot or slash in the request is decoded before matching, so a location rule cannot be bypassed simply by encoding characters. The risk moves to whatever component later receives the original, undecoded URI.
  • Root and alias use the normalised path: files are located from the normalised URI, which is why a correctly slashed alias or a root directive keeps requests within the directory.
  • Variables differ: $uri holds the current normalised URI, while $request_uri holds the original request line URI with arguments, unmodified. Using $request_uri in proxy_pass, try_files or access decisions reintroduces the raw form.

merge_slashes

merge_slashes is on by default and is valid in http and server context. The documentation explains that compression is essential for correct matching of prefix and regular expression locations: without it, a request with a doubled leading slash would not match location /scripts/ and might be processed as a static file. It notes that turning compression off can become necessary when URIs contain base64-encoded names, and that for security reasons it is better to avoid turning it off. If an application genuinely needs merge_slashes off, confine it to a dedicated server block, put that application's locations in exact or regex form that tolerate repeated slashes, and enforce authorisation in the application.

Reverse proxy and backend mismatches

The wider risk is an interpretation conflict: one component decides what a path means for access control or routing, and another decides what resource to serve. MITRE classifies this as CWE-436 Interpretation Conflict, with CWE-444 Inconsistent Interpretation of HTTP Requests as a child for request-level disagreements. See the HTTP Parameter Pollution and Parser Differential Guide and the HTTP Request Smuggling Guide for those neighbouring classes.

What nginx forwards

The proxy module documentation describes the rules for the URI sent upstream:

proxy_pass formURI sent to the backendMismatch exposure
With a URI, for example proxy_pass http://127.0.0.1/remote/;The part of the normalised request URI matching the location is replaced by the URI in the directiveLower: the backend receives a path nginx has already normalised; check that re-encoding preserves meaning for reserved characters
Without a URI, for example proxy_pass http://127.0.0.1;The request URI in the same form the client sent it (or the full normalised URI if it was changed by rewrite)Higher: nginx matched the location on the normalised path, but the backend parses the raw path with its own rules
Regex or named locationMust be specified without a URIAs above: raw URI reaches the backend
Variables, for example $request_uriThe URI built from variables, passed as isHighest: raw client input chosen deliberately

Where backends disagree

RFC 3986 defines the generic algorithm for removing dot segments (section 5.2.4) and says percent-encoded unreserved characters should be decoded by normalisers, while decoding a percent-encoded reserved character such as "/" changes how most applications interpret the URI. Backends implement these rules differently. Typical disagreement points to test:

  • Path parameters: Java servlet containers treat ";" as the start of a path parameter. Spring Security's documentation explains that the servlet specification does not define exactly what servletPath and pathInfo contain, that a container that does not strip path parameters can let an attacker make a pattern match succeed or fail unexpectedly, and that its StrictHttpFirewall rejects un-normalised requests and semicolons by default.
  • Encoded slashes and backslashes: some servers decode %2F into a separator, others keep it as data or reject it; some platforms treat "\" as a separator.
  • Double decoding: a backend that decodes again after the proxy has decoded once sees a different path. MITRE CAPEC-64 and CAPEC-267 describe validation bypass through slash and alternate encodings.
  • Repeated slashes: if nginx compresses slashes for matching but forwards the raw path, the backend router may treat "//admin" and "/admin" differently from the proxy.
  • Case and trailing characters: case-insensitive file systems or routers, and trailing dots or spaces, can map distinct strings to one resource.

The defensive principle is to make the proxy and backend agree, and not to rely on the proxy alone for authorisation. Restricting /admin/ with an nginx allow list is useful as a layer, but the application must still check the caller. See API Gateway vs Reverse Proxy and the Broken Access Control Prevention Guide.

Secure configuration patterns

  • Prefer root over alias: use alias only when the URI must be rewritten to a different directory name, and then with matching trailing slashes or an exact match location.
  • Keep merge_slashes on: leave the default in place unless an application requires otherwise, and isolate any exception.
  • Use proxy_pass with a URI where possible: so the backend receives the path nginx matched. Where the raw URI must be forwarded, document why and add backend-side normalisation and rejection.
  • Reject what you do not use: if no legitimate route contains encoded slashes, semicolons or dot segments, reject requests containing them early with a 400, at the proxy and in the application. Spring Security's StrictHttpFirewall is one example of a backend-side guard.
  • Deny by default: end each server block with a catch-all location that returns 404 so unmatched paths do not fall through to a broad static root.
  • Constrain the file system: run workers as an unprivileged user, keep secrets and source outside any directory reachable by root or alias, and consider disable_symlinks (off by default) where untrusted users can write to served directories.
  • Constrain regex captures: in regex locations that build alias or proxy paths from captures, use character classes that exclude "/" and "." sequences you do not expect.

Implementing a review: a phased approach

  1. Inventory. Collect every nginx configuration in scope, including included files, container images, Helm charts and ingress templates. Run nginx -T in a non-production environment to dump the effective configuration.
  2. Static analysis. Run a configuration analyser such as Gixy, whose alias_traversal check flags prefix locations without a trailing slash that use alias. Add the check to CI in report-only mode first.
  3. Manual review. For each alias, proxy_pass without a URI, use of $request_uri, regex location and merge_slashes setting, record the owner and justification.
  4. Differential testing. In a test environment, send a defined set of path variants (encoded, doubled slashes, dot segments, path parameters) through the proxy to an instrumented backend and compare what nginx matched with what the backend routed. Treat any difference on a protected route as a finding. Use authorised testers and keep tests to your own systems.
  5. Fix and enforce. Correct slashes or switch to root, add backend rejection, then switch the CI check to blocking.
  6. Roll out and roll back. Deploy changes behind a canary or a single upstream, watch 4xx rates for legitimate traffic, and keep the previous configuration ready with nginx -t validation before reload.

Decision guidance

  • alias or root: choose root when the URI path and directory structure line up. Choose alias only when they must differ, and then require a trailing-slash rule in review.
  • proxy_pass with or without URI: with a URI is easier to reason about because the backend receives the normalised path. Without a URI preserves the original encoding, which some APIs need (for example identifiers containing encoded slashes); in that case the backend owns normalisation and must reject ambiguous input.
  • Where to enforce authorisation: treat proxy path rules as coarse filtering and the application as the authority. For small deployments with a single backend, matching both layers is manageable; at scale, with many backends behind shared ingress, standardise one normalisation policy and test it centrally.
  • Ingress controllers: annotation-driven configuration generates location and proxy blocks you do not write by hand. Review the generated output, not just the manifest. See Ingress NGINX Retirement if you are migrating ingress controllers.

Detection and measurement

Logging the raw and normalised forms side by side is the most useful single step. Add $request_uri and $uri to the access log format so analysts can see where they differ.

  • Signals to alert on: requests whose raw URI contains dot segments, encoded dots or slashes, backslashes or semicolons on routes that never use them; 200 responses from static locations for files with source or configuration extensions; spikes of 400 or 404 on a single prefix.
  • Metric: alias findings open: count of unslashed alias prefixes and unjustified proxy_pass without URI across all configurations, trending to zero.
  • Metric: CI coverage: percentage of nginx configurations scanned by the analyser on every change.
  • Metric: differential test pass rate: share of protected routes where proxy and backend resolve every test variant identically.
  • Metric: mean time to remediate: days from configuration finding to fix in production.
  • Metric: authorisation in depth: percentage of proxy-restricted routes that also enforce authorisation in the application.

Framework mapping

FrameworkReferenceHow it applies
MITRE CWECWE-22 Path Traversal; CWE-436 Interpretation Conflict; CWE-444Alias escape is CWE-22; proxy and backend disagreement is CWE-436
MITRE CAPECCAPEC-126 Path Traversal; CAPEC-64; CAPEC-267Attack patterns to include in test cases
MITRE ATT&CKT1190 Exploit Public-Facing ApplicationMisconfigured public web servers are an initial access route
NIST SP 800-53 Rev. 5CM-6, CM-7, SI-10, AC-3, SA-11, RA-5, SI-4Configuration settings, least functionality, input validation, access enforcement in the application, testing, scanning, monitoring
NIST CSF 2.0PR.PS-01, DE.CM-09Configuration management and monitoring of runtime environments
OWASP ASVS 5.0V5.3.2File paths built from internally generated or trusted data, not user-submitted names
CIS Controls v8.1Control 4 Secure Configuration; Control 16 Application Software SecurityBaseline configuration and secure development review

Where identity fits

Files exposed through an alias escape are often the ones that hold machine credentials: environment files, application configuration with database passwords, cloud access keys and private keys for service-to-service TLS. Keep these out of any served directory tree, load secrets at runtime from a secrets manager, and rotate any credential that sat in a directory reachable by nginx when a finding is confirmed. See the Secrets Management Guide.

Common failure patterns

  • Copy-pasted alias snippets: a location without a trailing slash is copied between services and container images, spreading the same exposure everywhere.
  • Proxy-only access control: an admin path is blocked at nginx but the backend accepts a variant that nginx did not match, so the block is bypassed.
  • Raw URI forwarding by habit: proxy_pass without a URI or with $request_uri is used everywhere, even where the backend does not need the original encoding.
  • merge_slashes switched off globally: to support one application, weakening matching for every server block.
  • Secrets inside the web tree: configuration and environment files stored beside static assets, turning a small path bug into credential exposure.
  • Reviewing manifests, not output: generated ingress configuration is never inspected, so unsafe locations go unnoticed.

Practitioner checklist

  • Find every alias directive and confirm the location ends with "/" when the alias does, or replace it with root.
  • Use exact match locations for single-file aliases.
  • Keep merge_slashes on, and isolate and document any exception.
  • Prefer proxy_pass with a URI; justify every proxy_pass without one and every use of $request_uri.
  • Reject encoded slashes, dot segments and semicolons on routes that do not need them, at the proxy and the backend.
  • Enforce authorisation in the application, not only in nginx location rules.
  • Run a configuration analyser in CI and dump effective configuration with nginx -T for review.
  • Log $request_uri and $uri together and alert on suspicious differences.
  • Keep secrets and source out of served directories and rotate any that were exposed.

Standards and references

Related NHI Mgmt Group resources: NGINX Security Hardening Guide · Local File Inclusion vs Path Traversal · API Gateway vs Reverse Proxy · HTTP Parameter Pollution and Parser Differential Guide

PDF for subscribers

Take this guide with you

Every section, table and checklist in one PDF, with links to the sources and related guides. Subscribe to our weekly NHI & AI Identity Journal and we’ll email you a download link.

Free weekly newsletter

Subscribe to the NHI & AI Identity Journal

The latest on NHI and Agentic AI security – articles, research, breaches, news and events every week.

Bonus 33% off our NHI Course when you subscribe.

NHIMG Editorial Note
Researched and written by the NHI Mgmt Group editorial team using AI tools, under the editorial direction of Lalit Choda. Facts are drawn from the sources listed on this page and checked by our automated quality process. Last updated 14 November 2026. Spotted an error? Use our contact page.
NHI Mgmt Group, the independent authority on Non-Human Identity, IAM and Agentic AI security. nhimg.org

PDF Downloads for Newsletter Subscribers

Get the guide

Enter your details and we’ll email you a download link.

The full guide is free to read online. The PDF is a thank you for subscribing.

Fill in all fields marked * and tick the PDF box to continue.