Skip to content
Tutorials Center
My learning

Topics

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.

NODE
// 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

Node.js The same input, two outcomes

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.

Node.js Substitution, allow-lists and option injection

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() or spawn() 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 with zlib and 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 .cmd or .bat files, which need a shell. Node.js refuses to run them without shell: true precisely because of this danger.
  • shell: true reintroduces the problem for every function, including spawn(). 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.