mirror of
https://github.com/python/cpython.git
synced 2026-01-06 15:32:22 +00:00
Remove the warning-soup from the subprocess documentation by adding
a Security Considerations section as preferred by both the devguide and documentation users who do not wish to go insane.
This commit is contained in:
Gregory P. Smith
parent
5c8ce188ee
commit
6436cba9db
1 changed files with 48 additions and 79 deletions
|
|
@ -54,18 +54,12 @@ use cases, the underlying :class:`Popen` interface can be used directly.
|
|||
>>> subprocess.call("exit 1", shell=True)
|
||||
1
|
||||
|
||||
.. warning::
|
||||
|
||||
Invoking the system shell with ``shell=True`` can be a security hazard
|
||||
if combined with untrusted input. See the warning under
|
||||
:ref:`frequently-used-arguments` for details.
|
||||
|
||||
.. note::
|
||||
|
||||
Do not use ``stdout=PIPE`` or ``stderr=PIPE`` with this function. As
|
||||
the pipes are not being read in the current process, the child
|
||||
process may block if it generates enough output to a pipe to fill up
|
||||
the OS pipe buffer.
|
||||
Do not use ``stdout=PIPE`` or ``stderr=PIPE`` with this
|
||||
function. The child process will block if it generates enough
|
||||
output to a pipe to fill up the OS pipe buffer as the pipes are
|
||||
not being read from.
|
||||
|
||||
.. versionchanged:: 3.3
|
||||
*timeout* was added.
|
||||
|
|
@ -99,18 +93,12 @@ use cases, the underlying :class:`Popen` interface can be used directly.
|
|||
...
|
||||
subprocess.CalledProcessError: Command 'exit 1' returned non-zero exit status 1
|
||||
|
||||
.. warning::
|
||||
|
||||
Invoking the system shell with ``shell=True`` can be a security hazard
|
||||
if combined with untrusted input. See the warning under
|
||||
:ref:`frequently-used-arguments` for details.
|
||||
|
||||
.. note::
|
||||
|
||||
Do not use ``stdout=PIPE`` or ``stderr=PIPE`` with this function. As
|
||||
the pipes are not being read in the current process, the child
|
||||
process may block if it generates enough output to a pipe to fill up
|
||||
the OS pipe buffer.
|
||||
Do not use ``stdout=PIPE`` or ``stderr=PIPE`` with this
|
||||
function. The child process will block if it generates enough
|
||||
output to a pipe to fill up the OS pipe buffer as the pipes are
|
||||
not being read from.
|
||||
|
||||
.. versionchanged:: 3.3
|
||||
*timeout* was added.
|
||||
|
|
@ -177,17 +165,12 @@ use cases, the underlying :class:`Popen` interface can be used directly.
|
|||
... shell=True)
|
||||
'ls: non_existent_file: No such file or directory\n'
|
||||
|
||||
.. warning::
|
||||
|
||||
Invoking the system shell with ``shell=True`` can be a security hazard
|
||||
if combined with untrusted input. See the warning under
|
||||
:ref:`frequently-used-arguments` for details.
|
||||
|
||||
.. note::
|
||||
|
||||
Do not use ``stderr=PIPE`` with this function. As the pipe is not being
|
||||
read in the current process, the child process may block if it
|
||||
generates enough output to the pipe to fill up the OS pipe buffer.
|
||||
Do not use ``stdout=PIPE`` or ``stderr=PIPE`` with this
|
||||
function. The child process will block if it generates enough
|
||||
output to a pipe to fill up the OS pipe buffer as the pipes are
|
||||
not being read from.
|
||||
|
||||
.. versionadded:: 3.1
|
||||
|
||||
|
|
@ -210,7 +193,7 @@ use cases, the underlying :class:`Popen` interface can be used directly.
|
|||
|
||||
Special value that can be used as the *stdin*, *stdout* or *stderr* argument
|
||||
to :class:`Popen` and indicates that a pipe to the standard stream should be
|
||||
opened.
|
||||
opened. Most useful with :meth:`Popen.communicate`.
|
||||
|
||||
|
||||
.. data:: STDOUT
|
||||
|
|
@ -336,28 +319,9 @@ default values. The arguments that are most commonly needed are:
|
|||
instead of ``locale.getpreferredencoding()``. See the
|
||||
:class:`io.TextIOWrapper` class for more information on this change.
|
||||
|
||||
.. warning::
|
||||
.. note::
|
||||
|
||||
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`` disables all shell based features, but does not suffer
|
||||
from this vulnerability; see the Note in the :class:`Popen` constructor
|
||||
documentation for helpful hints in getting ``shell=False`` to work.
|
||||
|
||||
When using ``shell=True``, :func:`shlex.quote` can be used to properly
|
||||
escape whitespace and shell metacharacters in strings that are going to
|
||||
be used to construct shell commands.
|
||||
Read the `Security Considerations`_ section before using ``shell=True``.
|
||||
|
||||
These options, along with all of the other options, are described in more
|
||||
detail in the :class:`Popen` constructor documentation.
|
||||
|
|
@ -438,11 +402,9 @@ functions.
|
|||
into the shell (e.g. :command:`dir` or :command:`copy`). You do not need
|
||||
``shell=True`` to run a batch file or console-based executable.
|
||||
|
||||
.. warning::
|
||||
.. note::
|
||||
|
||||
Passing ``shell=True`` can be a security hazard if combined with
|
||||
untrusted input. See the warning under :ref:`frequently-used-arguments`
|
||||
for details.
|
||||
Read the `Security Considerations`_ section before using ``shell=True``.
|
||||
|
||||
*bufsize* will be supplied as the corresponding argument to the :func:`open`
|
||||
function when creating the stdin/stdout/stderr pipe file objects: :const:`0`
|
||||
|
|
@ -598,14 +560,21 @@ Exceptions defined in this module all inherit from :exc:`SubprocessError`.
|
|||
The :exc:`SubprocessError` base class was added.
|
||||
|
||||
|
||||
Security
|
||||
^^^^^^^^
|
||||
Security Considerations
|
||||
-----------------------
|
||||
|
||||
Unlike some other popen functions, this implementation will never call a
|
||||
system shell implicitly. This means that all characters, including shell
|
||||
metacharacters, can safely be passed to child processes. Obviously, if the
|
||||
shell is invoked explicitly, then it is the application's responsibility to
|
||||
ensure that all whitespace and metacharacters are quoted appropriately.
|
||||
Unlike some other popen functions, this implementation will never
|
||||
implicitly call a system shell. This means that all characters,
|
||||
including shell metacharacters, can safely be passed to child processes.
|
||||
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 <http://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.
|
||||
|
||||
|
||||
Popen Objects
|
||||
|
|
@ -629,27 +598,27 @@ Instances of the :class:`Popen` class have the following methods:
|
|||
:exc:`TimeoutExpired` exception. It is safe to catch this exception and
|
||||
retry the wait.
|
||||
|
||||
.. note::
|
||||
|
||||
This will deadlock when using ``stdout=PIPE`` or ``stderr=PIPE``
|
||||
and the child process generates enough output to a pipe such that
|
||||
it blocks waiting for the OS pipe buffer to accept more data.
|
||||
Use :meth:`Popen.communicate` when using pipes to avoid that.
|
||||
|
||||
.. note::
|
||||
|
||||
The function is implemented using a busy loop (non-blocking call and
|
||||
short sleeps). Use the :mod:`asyncio` module for an asynchronous wait:
|
||||
see :class:`asyncio.create_subprocess_exec`.
|
||||
|
||||
.. warning::
|
||||
|
||||
This will deadlock when using ``stdout=PIPE`` and/or
|
||||
``stderr=PIPE`` and the child process generates enough output to
|
||||
a pipe such that it blocks waiting for the OS pipe buffer to
|
||||
accept more data. Use :meth:`communicate` to avoid that.
|
||||
|
||||
.. versionchanged:: 3.3
|
||||
*timeout* was added.
|
||||
|
||||
.. deprecated:: 3.4
|
||||
|
||||
Do not use the undocumented *endtime* parameter. It is was
|
||||
unintentionally exposed in 3.3 but was intended to be private
|
||||
for internal use. Use *timeout* instead.
|
||||
Do not use the *endtime* parameter. It is was unintentionally
|
||||
exposed in 3.3 but was left undocumented as it was intended to be
|
||||
private for internal use. Use *timeout* instead.
|
||||
|
||||
.. method:: Popen.communicate(input=None, timeout=None)
|
||||
|
||||
|
|
@ -716,13 +685,6 @@ Instances of the :class:`Popen` class have the following methods:
|
|||
|
||||
The following attributes are also available:
|
||||
|
||||
.. warning::
|
||||
|
||||
Use :meth:`~Popen.communicate` rather than :attr:`.stdin.write <Popen.stdin>`,
|
||||
:attr:`.stdout.read <Popen.stdout>` or :attr:`.stderr.read <Popen.stderr>` to avoid
|
||||
deadlocks due to any of the other OS pipe buffers filling up and blocking the
|
||||
child process.
|
||||
|
||||
.. attribute:: Popen.args
|
||||
|
||||
The *args* argument as it was passed to :class:`Popen` -- a
|
||||
|
|
@ -756,6 +718,13 @@ The following attributes are also available:
|
|||
``True``, the stream is a text stream, otherwise it is a byte stream. If the
|
||||
*stderr* argument was not :data:`PIPE`, this attribute is ``None``.
|
||||
|
||||
.. warning::
|
||||
|
||||
Use :meth:`~Popen.communicate` rather than :attr:`.stdin.write <Popen.stdin>`,
|
||||
:attr:`.stdout.read <Popen.stdout>` or :attr:`.stderr.read <Popen.stderr>` to avoid
|
||||
deadlocks due to any of the other OS pipe buffers filling up and blocking the
|
||||
child process.
|
||||
|
||||
|
||||
.. attribute:: Popen.pid
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue