--- /python/branches/py3k/Doc/library/subprocess.rst +++ /python/branches/py3k/Doc/library/subprocess.rst.new @@ -76,6 +76,30 @@ Popen(['/bin/sh', '-c', args[0], args[1], ...]) + .. warning:: + + Executing shell commands that incorporate unsanitized input from an + untrusted source makes a program vulnerable to `shell injection`_, + a serious security flaw which can result in arbitrary command execution. + For this reason, the use of *shell=True* is **strongly discouraged** in cases + where the command string is constructed from external input:: + + >>> from subprocess import call + >>> filename = input("What file would you like to display?\n") + What file would you like to display? + ; rm -rf / # + >>> call("cat " + filename) # Uh-oh. This will end badly... + + *shell=False* does not suffer from this vulnerability; the above Note may be + helpful in getting code using *shell=False* to work. + + To safely use *shell=True* anyway, one must manually add the proper escaping + and/or the proper quoting to the input string; this approach is error-prone + and is not recommended. + + A list of characters with special meanings in common Unix shells may be found + in [UNIXPOWERTOOLS]_. + On Windows: the :class:`Popen` class uses CreateProcess() to execute the child program, which operates on strings. If *args* is a sequence, it will be converted to a string using the :meth:`list2cmdline` method. Please note that @@ -620,3 +644,11 @@ * popen2 closes all file descriptors by default, but you have to specify ``close_fds=True`` with :class:`Popen`. + + +Citation +-------- + +.. [UNIXPOWERTOOLS] *UNIX Power Tools*, Chapter 8 "How the Shell Interprets What + You Type", `Section 8.19 '"Special" Characters and Operators'`_, + Jerry Peek, Tim O'Reilly & Mike Loukides, ISBN 1-56592-260-3, Second Edition, August 1997.