Lorixen.
EN

Stop path traversal in your app's file download links

Short answer: If your app serves files through a URL like /download?file=invoice-104.pdf, an attacker may try ../ sequences to read files outside the intended folder, such as config files holding database passwords. Don't let user input become a file path. Look the file up by an ID in your database instead, or resolve the full path and check that it still sits inside your storage folder before opening it.

What path traversal looks like

OWASP describes path traversal as manipulating variables that reference files with dot-dot-slash (../) sequences, or using absolute file paths, to reach files and directories outside the web root. A download endpoint that joins a folder name with whatever the visitor sends is the classic target:

  • Intended: /download?file=report.pdf reads /srv/app/files/report.pdf
  • Attack: /download?file=../../.env reads /srv/app/.env

OWASP also lists the many disguises the same idea wears: URL-encoded forms such as %2e%2e%2f, double encoding, backslashes on Windows servers and mixtures of all of these. That's why checking for the literal string ../ and calling it done fails so often. An attacker only needs one form your filter missed.

Where small business apps get caught

This bug turns up in features that seem harmless:

  • Invoice and receipt downloads where the file name comes from the query string.
  • Image resizing endpoints that read ?src= from disk.
  • Theme or template loaders that pick a file by name, such as ?page=about.
  • Export features that write a file somewhere and then let the user fetch it by name.
  • Admin "view log" pages built quickly during development and never removed.

The impact depends on what the server can read. Environment files, private keys, other customers' documents and source code are the usual prizes. A single readable .env can expose the database, payment keys and email credentials at once.

Fix 1: don't use names from the request at all

The safest design never builds a path from user input. Store each file's real location in your database and give the browser an opaque ID:

  1. When a file is created, save a row with an ID, the owner, the storage path and the original file name.
  2. The download link uses only the ID: /download/8f3c2a.
  3. The handler looks up the row, checks the current user is allowed to see it, then streams the stored path.

The visitor can change the ID, but they can only reach rows that exist, and only those they're authorised for. This also fixes a second problem: someone guessing other customers' invoice numbers.

If files live in object storage rather than on local disk, the same pattern applies. Look up the object key from your database and hand out a short-lived signed link, rather than accepting a key from the browser.

Fix 2: allowlist, then resolve and contain

Sometimes you do need a name, for example to choose between a fixed set of templates. In that case:

  • Allowlist. Map allowed names to files in code ({"about": "about.html", "contact": "contact.html"}) and reject anything else. OWASP's input validation guidance favours allowlists over denylists for exactly this reason.
  • Resolve and check containment. If names must be free-form, build the full path, resolve it to its canonical absolute form (following .. and symlinks), and confirm the result starts with your storage directory plus a separator. In Python, os.path.realpath gives the canonical path and os.path.commonpath can compare it with the base folder. In Node.js, path.resolve produces an absolute path you can compare. Node's own documentation warns that path.isAbsolute is not safe for mitigating path traversals, so don't use that check on its own.
  • Restrict characters. For stored files, generate your own safe names (random IDs plus a known extension) at upload time, and keep the customer's original name only as metadata for the download header.

Do the containment check after decoding, on the final path you're about to open. Checks done on the raw query string miss encoded variants.

Fix 3: reduce what a mistake can expose

Defence in depth limits the damage if a bug slips through:

  • Run the app as a user that can read only its own folders, not the whole system.
  • Keep secrets out of files inside the web app's directory where possible; use the host's secret storage or environment settings.
  • Store uploads outside the code directory, ideally on separate storage.
  • Make sure the web server doesn't serve dot-files or backup files directly.

How to test your own endpoints

Ask your developer to try, on a staging copy:

  • ../ and ..\ sequences at different depths.
  • Encoded and double-encoded versions.
  • An absolute path, such as one starting with /etc/.
  • A file name with a null byte or odd characters, if your language or framework might pass them through.

Each attempt should return a not-found or forbidden response, never a file. Add these cases to your automated tests so a later refactor doesn't quietly reintroduce the hole.

A worked example

Take a hypothetical Leeds bookkeeping portal that let clients download statements from /files?name=. A developer reviewing the code noticed the handler simply joined the folder and the name. They replaced it with ID-based links checked against the logged-in client, moved existing files to random names, and added tests for traversal strings. The old endpoint was kept for a month returning a polite "link expired" page, then removed.

FAQ

Does my framework protect me automatically?

Static file servers in most frameworks guard against traversal for their own folders. Custom download handlers you write yourself usually don't, so check them.

Is a web application firewall enough?

It can block common patterns, but encodings vary and rules can be bypassed. Treat it as an extra layer, not the fix.

What if the file name has to appear in the download?

Keep the original name in your database and send it in the download response header. The name on disk can be anything safe you choose.

Should I log blocked attempts?

Yes. Repeated traversal attempts are a useful signal that someone is probing your app.

If you'd like your app's download and upload features checked for this kind of hole, tell us how files are served today.

Sources

WhatsAppBook a call