Node.js Reference ยท child_process, worker_threads and cluster
Node.js shell injection with child_process
Why child_process.exec() with user input is dangerous in Node.js, how shell injection works, and safe alternatives: execFile, spawn without a shell, validation and allow-lists.
Shell injection happens when a program builds a command line by pasting untrusted text into a string and gives that string to a shell. The shell does not know which part was yours and which part came from a visitor: characters such as ;, &&, |, $( ), backticks, > and newlines are instructions to it. A visitor who controls a fragment of the string can end your command and start their own.
In Node.js the risk lives in functions that run a command string through a shell: exec(), execSync(), and any function called with shell: true. The safe family passes an argument array straight to the program with no shell in between: execFile(), spawn() and spawnSync() (without shell). With those, the input is data only; it can never become a second command.
// DANGEROUS: filename is pasted into a shell command exec(`cat ${filename}`); // SAFE: filename is one argument, never parsed by a shell execFile('cat', [filename]);
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 attack works
A shell reads one line and splits it into commands before anything runs. These characters change the meaning of the line:
| Input fragment | Effect in a POSIX shell |
|---|---|
; or a newline |
Ends one command and starts another. |
&&, || |
Runs the next command depending on the result of the first. |
| |
Pipes output into another command. |
$(cmd) or backticks |
Runs cmd and inserts its output. |
>, >>, < |
Redirects output or input to a file. |
$VAR |
Expands an environment variable. |
*, ? |
Expands to file names. |
On Windows, cmd.exe has its own set (&, |, %VAR%, ^), and quoting rules differ, which makes correct escaping even harder. Do not rely on hand-written escaping.
Safe patterns
- No shell: use
execFile()orspawn()with an array. Each element reaches the program as one argument, exactly as given. - Allow-lists: when a value must be one of a few choices (a format, a branch name pattern, a mode), check it against a fixed set or a strict regular expression such as
/^[a-z0-9-]{1,40}$/and reject everything else. - End-of-options marker: put
--before untrusted values for programs that support it, so a value that starts with-is not read as a flag. Programs that do not support--need a different guard, such as prefixing relative paths with./. - Prefer libraries over commands: reading a file with
fs, compressing withzliband talking to Git with a library need no process at all. - Run with least privilege: a process that runs commands should not have more rights than it needs, and should never run as an administrator.
- Never pass secrets on the command line. They are visible to other users in the process list. Use environment variables or stdin.
Usage notes
execFile()is not automatically safe on Windows when running.cmdor.batfiles, which need a shell. Node.js refuses to run them withoutshell: trueprecisely because of this danger.shell: truereintroduces the problem for every function, includingspawn(). Arguments are joined into one string and given to the shell.- Escaping libraries are a last resort. If you truly need a shell, quote every variable value with a well-reviewed library, and still validate input first.
- The danger is not only web input. File names, Git branch names, environment variables and data from other services can all carry shell characters.
- Logging is not protection. Printing the command before running it does not prevent the damage.