What Is Path Traversal (Directory Traversal)?

Quick answer
Path traversal is an attack that uses ../ sequences in a filename to read files outside the intended folder.
It works when an app builds a filesystem path from user input without checking the result stays in bounds.
The fix: never build paths from raw input — resolve and verify the final path, or use an ID-based lookup.

How does path traversal work?

An app that serves files by name — GET /download?file=report.pdf — might build a path like /data/reports/ + report.pdf. If the filename comes from the user unchecked, requesting ../../../../etc/passwd walks up out of the reports directory and reads the password file. URL encoding makes it harder to spot: %2e%2e%2f decodes to ../. The severity depends on what’s readable: source code, configuration files with secrets, or system files.

Why do naive fixes fail?

Blacklists of ‘../’ fail because of encoding tricks (..%2f, %2e%2e%2f), absolute paths (/etc/passwd), and Windows-style backslashes. The robust approach is validation by construction: resolve the final absolute path and check it starts with the allowed directory, or — simplest and safest — don’t take filenames at all: map a request to a file via an ID or a database lookup. Serving user-supplied filenames is the design error; avoiding it is the fix.

# Safe: resolve and verify the final path stays inside the base\nfrom pathlib import Path\n\nBASE = Path("/data/reports").resolve()\n\ndef safe_path(name: str) -> Path:\n    p = (BASE / name).resolve()\n    if not p.is_relative_to(BASE):\n        raise ValueError("path escapes base directory")\n    return p

Where else does path traversal show up?

Anywhere user input becomes a filesystem path: file uploads (a filename of ../../etc/cron.d/evil), archives (a zip entry named ../shell.php — zip-slip), template loading, and container volume mounts. Also watch non-filesystem variants: an IDOR-style directory walk on object storage keys, or traversal through paths in API routes. The general rule is the same everywhere: treat user input as data, never as a path component.

Where this bites vibecoders
The AI-generated file-download endpoint is the classic first exposure: ‘serve files from an uploads folder’ is generated with string concatenation, and the assistant’s hardening pass adds a ../ filter that encoding bypasses. Testing with a few encoded payloads finds it in minutes — and it’s worth doing, because a working traversal on a dev server usually means source code and .env files are readable.

Where AI coding assistants get this wrong

Building filesystem paths by string concatenation with user input.
Filtering ‘../’ with a blacklist that encoded variants bypass.
Serving files by user-supplied filename instead of an ID lookup.
Forgetting traversal applies to uploads, archives, and object-storage keys, not just downloads.

Checklist

Never build filesystem paths from raw user input.
Resolve and verify the final path stays inside the allowed directory.
Prefer ID-based file lookups over filename-based ones.
Test with encoded payloads: ..%2f, %2e%2e%2f, backslashes, absolute paths.

FAQ

What files does an attacker typically try to read?

System files like /etc/passwd, application source code, configuration files containing database credentials or API keys, and .env files. The impact ranges from confirming the vulnerability to full credential theft, depending on what’s on the server.

Does path traversal work on APIs that return JSON?

It works anywhere a path is built from input, whatever the response format. An API that takes a filename parameter and reads a file server-side is vulnerable even if it returns JSON — the response shape doesn’t change the filesystem access.