Merged revisions 86419 via svnmerge from

svn+ssh://pythondev@svn.python.org/python/branches/py3k

........
  r86419 | r.david.murray | 2010-11-11 19:35:31 -0500 (Thu, 11 Nov 2010) | 4 lines

  #7950: add warning about security implications of shell=True to subprocess docs

  Patch by Chris Rebert.
........

1 files changed, 18 insertions, 0 deletions

diff --git a/Doc/library/subprocess.rst b/Doc/library/subprocess.rst
index cc64b4ac7e..03e638e40e 100644
--- a/Doc/library/subprocess.rst
+++ b/Doc/library/subprocess.rst
@@ -81,6 +81,24 @@ This module defines one class called :class:`Popen`:
 
       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
+      <http://en.wikipedia.org/wiki/Shell_injection#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?
+         non_existent; rm -rf / #
+         >>> call("cat " + filename, shell=True) # 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.
+
    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