[Python-checkins] bpo-40932: Note security caveat of shlex.quote on Windows (GH-21502)

Wed Nov 11 02:30:06 EST 2020

https://github.com/python/cpython/commit/f9a8386e44a695551a1e54e709969e90e9b96bc4
commit: f9a8386e44a695551a1e54e709969e90e9b96bc4
branch: master
author: Ammar Askar <ammar at ammaraskar.com>
committer: miss-islington <31488909+miss-islington at users.noreply.github.com>
date: 2020年11月10日T23:29:56-08:00
summary:
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.
files:
M Doc/library/shlex.rst
M Doc/library/subprocess.rst

diff --git a/Doc/library/shlex.rst b/Doc/library/shlex.rst
index 7f7f0c7f124ac..aab6a54379209 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 85d0f46624cea..292f8be20aa98 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 <https://en.wikipedia.org/wiki/Shell_injection#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 <shlex-quote-warning>`, it is possible
+to use :func:`shlex.quote` for this escaping.
 
 
 Popen Objects
