From be833de403fb9387bcdcc2f4e7da654b42bba60c Mon Sep 17 00:00:00 2001 From: jvelezpo Date: Thu, 18 Jan 2018 11:35:24 -0500 Subject: [PATCH 1/2] doc: shell option for the execFile and execFileSync functions Useful for executing in a shell because it accepts arguments as an array instead of a string as exec does. Depending on the circumstances, that can prove to be useful if the arguments are already prepared. Fixes: https://github.com/nodejs/node/issues/18199 --- doc/api/child_process.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/doc/api/child_process.md b/doc/api/child_process.md index 50b5be5473d5f4..8c1cf04aa100ba 100644 --- a/doc/api/child_process.md +++ b/doc/api/child_process.md @@ -266,6 +266,9 @@ changes: normally be created on Windows systems. **Default:** `false`. * `windowsVerbatimArguments` {boolean} No quoting or escaping of arguments is done on Windows. Ignored on Unix. **Default:** `false`. + * `shell` {string} Shell to execute the command with. + **Default:** `'/bin/sh'` on UNIX, `process.env.ComSpec` on Windows. See + [Shell Requirements][] and [Default Windows Shell][]. * `callback` {Function} Called with the output when process terminates. * `error` {Error} * `stdout` {string|Buffer} @@ -705,6 +708,9 @@ changes: * `encoding` {string} The encoding used for all stdio inputs and outputs. **Default:** `'buffer'` * `windowsHide` {boolean} Hide the subprocess console window that would normally be created on Windows systems. **Default:** `false`. + * `shell` {string} Shell to execute the command with. + **Default:** `'/bin/sh'` on UNIX, `process.env.ComSpec` on Windows. See + [Shell Requirements][] and [Default Windows Shell][]. * Returns: {Buffer|string} The stdout from the command. The `child_process.execFileSync()` method is generally identical to From eae920a643aca94ae0e23704749886c9b1f7489e Mon Sep 17 00:00:00 2001 From: jvelezpo Date: Mon, 22 Jan 2018 14:36:16 -0500 Subject: [PATCH 2/2] doc: add boolean or string to shell option and also a nice note after each method Useful for executing in a shell because it accepts arguments as an array instead of a string as exec does. Depending on the circumstances, that can prove to be useful if the arguments are already prepared. Fixes: https://github.com/nodejs/node/issues/18199 --- doc/api/child_process.md | 28 +++++++++++++++++++--------- 1 file changed, 19 insertions(+), 9 deletions(-) diff --git a/doc/api/child_process.md b/doc/api/child_process.md index 8c1cf04aa100ba..715eb9d269c38d 100644 --- a/doc/api/child_process.md +++ b/doc/api/child_process.md @@ -44,7 +44,7 @@ implemented on top of [`child_process.spawn()`][] or [`child_process.spawnSync() * [`child_process.exec()`][]: spawns a shell and runs a command within that shell, passing the `stdout` and `stderr` to a callback function when complete. * [`child_process.execFile()`][]: similar to [`child_process.exec()`][] except that - it spawns the command directly without first spawning a shell. + it spawns the command directly without first spawning a shell by default. * [`child_process.fork()`][]: spawns a new Node.js process and invokes a specified module with an IPC communication channel established that allows sending messages between parent and child. @@ -78,7 +78,7 @@ when the child process terminates. The importance of the distinction between [`child_process.exec()`][] and [`child_process.execFile()`][] can vary based on platform. On Unix-type operating systems (Unix, Linux, macOS) [`child_process.execFile()`][] can be more efficient -because it does not spawn a shell. On Windows, however, `.bat` and `.cmd` +because it does not spawn a shell by default. On Windows, however, `.bat` and `.cmd` files are not executable on their own without a terminal, and therefore cannot be launched using [`child_process.execFile()`][]. When running on Windows, `.bat` and `.cmd` files can be invoked using [`child_process.spawn()`][] with the `shell` @@ -266,9 +266,10 @@ changes: normally be created on Windows systems. **Default:** `false`. * `windowsVerbatimArguments` {boolean} No quoting or escaping of arguments is done on Windows. Ignored on Unix. **Default:** `false`. - * `shell` {string} Shell to execute the command with. - **Default:** `'/bin/sh'` on UNIX, `process.env.ComSpec` on Windows. See - [Shell Requirements][] and [Default Windows Shell][]. + * `shell` {boolean|string} If `true`, runs `command` inside of a shell. Uses + `'/bin/sh'` on UNIX, and `process.env.ComSpec` on Windows. A different + shell can be specified as a string. See [Shell Requirements][] and + [Default Windows Shell][]. **Default:** `false` (no shell). * `callback` {Function} Called with the output when process terminates. * `error` {Error} * `stdout` {string|Buffer} @@ -276,7 +277,7 @@ changes: * Returns: {ChildProcess} The `child_process.execFile()` function is similar to [`child_process.exec()`][] -except that it does not spawn a shell. Rather, the specified executable `file` +except that it does not spawn a shell by default. Rather, the specified executable `file` is spawned directly as a new process making it slightly more efficient than [`child_process.exec()`][]. @@ -315,6 +316,10 @@ async function getVersion() { getVersion(); ``` +*Note*: If the `shell` option is enabled, do not pass unsanitized user input +to this function. Any input containing shell metacharacters may be used to +trigger arbitrary command execution. + ### child_process.fork(modulePath[, args][, options])