Skip to content

Commit f9a8386

Browse files
authored
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.
1 parent fa476fe commit f9a8386

File tree

2 files changed

+16
-5
lines changed

2 files changed

+16
-5
lines changed

Doc/library/shlex.rst

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -61,6 +61,20 @@ The :mod:`shlex` module defines the following functions:
6161
string that can safely be used as one token in a shell command line, for
6262
cases where you cannot use a list.
6363

64+
.. _shlex-quote-warning:
65+
66+
.. warning::
67+
68+
The ``shlex`` module is **only designed for Unix shells**.
69+
70+
The :func:`quote` function is not guaranteed to be correct on non-POSIX
71+
compliant shells or shells from other operating systems such as Windows.
72+
Executing commands quoted by this module on such shells can open up the
73+
possibility of a command injection vulnerability.
74+
75+
Consider using functions that pass command arguments with lists such as
76+
:func:`subprocess.run` with ``shell=False``.
77+
6478
This idiom would be unsafe:
6579

6680
>>> filename = 'somefile; rm -rf ~'

Doc/library/subprocess.rst

Lines changed: 2 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -718,11 +718,8 @@ If the shell is invoked explicitly, via ``shell=True``, it is the application's
718718
responsibility to ensure that all whitespace and metacharacters are
719719
quoted appropriately to avoid
720720
`shell injection <https://en.wikipedia.org/wiki/Shell_injection#Shell_injection>`_
721-
vulnerabilities.
722-
723-
When using ``shell=True``, the :func:`shlex.quote` function can be
724-
used to properly escape whitespace and shell metacharacters in strings
725-
that are going to be used to construct shell commands.
721+
vulnerabilities. On :ref:`some platforms <shlex-quote-warning>`, it is possible
722+
to use :func:`shlex.quote` for this escaping.
726723

727724

728725
Popen Objects

0 commit comments

Comments
 (0)