Node.js Reference ยท Concepts and Pitfalls
Path traversal in Node.js
How path traversal attacks work with ../ and symlinks, why path.join() is not enough, and how to build a safe resolver that keeps paths inside a base folder.
Path traversal (also called directory traversal) is an attack where a user-controlled file name such as ../../etc/passwd makes your program read or write outside the folder it meant to serve. It happens whenever you glue user input onto a base path and hand the result to fs.
The fix is not to strip ../ from the string. Attackers have many encodings and the file system has more ways to move around than text patterns can list. The robust fix is to resolve the final path and verify that it is still inside the base directory, and, when symbolic links are possible, to resolve those as well.
const target = path.resolve(base, userInput); if (!target.startsWith(base + path.sep)) throw new Error('outside base');
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
How the checks work
path.join(base, input)only concatenates and normalizes...segments are applied, sojoin('/srv/files', '../x')is/srv/x. It never refuses anything.path.resolve(base, input)treats an absoluteinputas the answer and ignoresbasecompletely.- Containment by
path.relative()is safer thanstartsWith(base). A prefix test accepts/srv/files-evilfor the base/srv/files; testingrelative()does not. - Symlinks defeat lexical checks.
public/link/secret.txtlooks insidepublicbut points outside.fs.realpath()returns the real location so you can check again; it throwsENOENTif the path does not exist. - Null bytes (
\0) in a path are refused by Node'sfsfunctions withERR_INVALID_ARG_VALUE; do not rely on it for your own parsing or logging. - Windows adds cases: drive letters (
C:), backslashes, and reserved names likeCON. Usingpath.relative()with the platform's ownpathmodule handles the separators.
Usage notes
- Check after resolving, not before. Validate the final absolute path, not the raw string.
- Prefer identifiers over paths. Map
idvalues from a database or an allow-list to file names so users never supply a path at all. - Decode first. If paths come from URLs, decode percent-encoding once and then check; double-decoding bugs reopen the hole.
- There is a race. A symlink could be swapped between your check and the actual open. For highest security, open the file and verify the opened handle, run with minimal privileges, or use a separate directory users cannot write into.
- Write paths matter as much as read paths. Uploads with a user-supplied file name can overwrite files; generate your own names.
- Static file servers have the same risk. Use a well-tested library or the checks above.
- The permission model (
--permission --allow-fs-read=...) is an additional layer, not a replacement for validation.