From f9a8386e44a695551a1e54e709969e90e9b96bc4 Mon Sep 17 00:00:00 2001 From: Ammar Askar Date: Wed, 11 Nov 2020 02:29:56 -0500 Subject: [PATCH] bpo-40932: Note security caveat of shlex.quote on Windows (GH-21502) Added a note in the `subprocess` docs that recommend using `shlex.quote` without mentioning that this is only applicable to Unix. Also added a warning straight into the `shlex` docs since it only says "for simple syntaxes resembling that of the Unix shell" and says using `quote` plugs the security hole without mentioning this important caveat. --- Doc/library/shlex.rst | 14 ++++++++++++++ Doc/library/subprocess.rst | 7 ++----- 2 files changed, 16 insertions(+), 5 deletions(-) diff --git a/Doc/library/shlex.rst b/Doc/library/shlex.rst index 7f7f0c7f124..aab6a543792 100644 --- a/Doc/library/shlex.rst +++ b/Doc/library/shlex.rst @@ -61,6 +61,20 @@ The :mod:`shlex` module defines the following functions: string that can safely be used as one token in a shell command line, for cases where you cannot use a list. + .. _shlex-quote-warning: + + .. warning:: + + The ``shlex`` module is **only designed for Unix shells**. + + The :func:`quote` function is not guaranteed to be correct on non-POSIX + compliant shells or shells from other operating systems such as Windows. + Executing commands quoted by this module on such shells can open up the + possibility of a command injection vulnerability. + + Consider using functions that pass command arguments with lists such as + :func:`subprocess.run` with ``shell=False``. + This idiom would be unsafe: >>> filename = 'somefile; rm -rf ~' diff --git a/Doc/library/subprocess.rst b/Doc/library/subprocess.rst index 85d0f46624c..292f8be20aa 100644 --- a/Doc/library/subprocess.rst +++ b/Doc/library/subprocess.rst @@ -718,11 +718,8 @@ If the shell is invoked explicitly, via ``shell=True``, it is the application's responsibility to ensure that all whitespace and metacharacters are quoted appropriately to avoid `shell injection `_ -vulnerabilities. - -When using ``shell=True``, the :func:`shlex.quote` function can be -used to properly escape whitespace and shell metacharacters in strings -that are going to be used to construct shell commands. +vulnerabilities. On :ref:`some platforms `, it is possible +to use :func:`shlex.quote` for this escaping. Popen Objects