[Python-checkins] bpo-39498 Start linking the security warnings in the stdlib modules (GH-18272)

[ambv]

https://github.com/python/cpython/commit/c5c5326d4799fe4ae566aff32ed3461af95859cc
commit: c5c5326d4799fe4ae566aff32ed3461af95859cc
branch: main
author: Anthony Shaw <anthony.p.shaw at gmail.com>
committer: ambv <lukasz at langa.pl>
date: 2021-08-10T00:35:51+02:00
summary:

bpo-39498 Start linking the security warnings in the stdlib modules (GH-18272)

Co-authored-by: Łukasz Langa <lukasz at langa.pl>

files:
A Doc/library/security_warnings.rst
A Misc/NEWS.d/next/Documentation/2020-01-30-05-18-48.bpo-39498.Nu3sFL.rst
M Doc/library/hashlib.rst
M Doc/library/index.rst
M Doc/library/logging.config.rst
M Doc/library/multiprocessing.rst
M Doc/library/shelve.rst
M Doc/library/subprocess.rst
M Doc/library/tempfile.rst
M Doc/library/zipfile.rst

diff --git a/Doc/library/hashlib.rst b/Doc/library/hashlib.rst
index d22efa23015c6..37addee6cda80 100644
--- a/Doc/library/hashlib.rst
+++ b/Doc/library/hashlib.rst
@@ -80,6 +80,8 @@ library that Python uses on your platform. On most platforms the
 .. versionadded:: 3.6
    :func:`blake2b` and :func:`blake2s` were added.
 
+.. _hashlib-usedforsecurity:
+
 .. versionchanged:: 3.9
    All hashlib constructors take a keyword-only argument *usedforsecurity*
    with default value ``True``. A false value allows the use of insecure and
diff --git a/Doc/library/index.rst b/Doc/library/index.rst
index 1a9e52ec5ccfb..db8f0d9bdfb8f 100644
--- a/Doc/library/index.rst
+++ b/Doc/library/index.rst
@@ -75,3 +75,4 @@ the `Python Package Index <https://pypi.org>`_.
    unix.rst
    superseded.rst
    undoc.rst
+   security_warnings.rst
diff --git a/Doc/library/logging.config.rst b/Doc/library/logging.config.rst
index f833bcdd1fcf5..d3478a94345f0 100644
--- a/Doc/library/logging.config.rst
+++ b/Doc/library/logging.config.rst
@@ -152,6 +152,8 @@ in :mod:`logging` itself) and defining handlers which are declared either in
    send it to the socket as a sequence of bytes preceded by a four-byte length
    string packed in binary using ``struct.pack('>L', n)``.
 
+   .. _logging-eval-security:
+
    .. note::
 
       Because portions of the configuration are passed through
diff --git a/Doc/library/multiprocessing.rst b/Doc/library/multiprocessing.rst
index b9396c3c7531c..c9b2a3716ff32 100644
--- a/Doc/library/multiprocessing.rst
+++ b/Doc/library/multiprocessing.rst
@@ -1187,6 +1187,7 @@ For example:
     >>> arr2
     array('i', [0, 1, 2, 3, 4, 0, 0, 0, 0, 0])
 
+.. _multiprocessing-recv-pickle-security:
 
 .. warning::
 
diff --git a/Doc/library/security_warnings.rst b/Doc/library/security_warnings.rst
new file mode 100644
index 0000000000000..61fd4e6e487f7
--- /dev/null
+++ b/Doc/library/security_warnings.rst
@@ -0,0 +1,32 @@
+.. _security-warnings:
+
+.. index:: single: security considerations
+
+Security Considerations
+=======================
+
+The following modules have specific security considerations:
+
+* :mod:`cgi`: :ref:`CGI security considerations <cgi-security>`
+* :mod:`hashlib`: :ref:`all constructors take a "usedforsecurity" keyword-only
+  argument disabling known insecure and blocked algorithms
+  <hashlib-usedforsecurity>`
+* :mod:`http.server` is not suitable for production use, only implementing
+  basic security checks
+* :mod:`logging`: :ref:`Logging configuration uses eval()
+  <logging-eval-security>`
+* :mod:`multiprocessing`: :ref:`Connection.recv() uses pickle
+  <multiprocessing-recv-pickle-security>`
+* :mod:`pickle`: :ref:`Restricting globals in pickle <pickle-restrict>`
+* :mod:`random` shouldn't be used for security purposes, use :mod:`secrets`
+  instead
+* :mod:`shelve`: :ref:`shelve is based on pickle and thus unsuitable for
+  dealing with untrusted sources <shelve-security>`
+* :mod:`ssl`: :ref:`SSL/TLS security considerations <ssl-security>`
+* :mod:`subprocess`: :ref:`Subprocess security considerations
+  <subprocess-security>`
+* :mod:`tempfile`: :ref:`mktemp is deprecated due to vulnerability to race
+  conditions <tempfile-mktemp-deprecated>`
+* :mod:`xml`: :ref:`XML vulnerabilities <xml-vulnerabilities>`
+* :mod:`zipfile`: :ref:`maliciously prepared .zip files can cause disk volume
+  exhaustion <zipfile-resources-limitations>`
diff --git a/Doc/library/shelve.rst b/Doc/library/shelve.rst
index 1031888a5889b..684f239ef06fa 100644
--- a/Doc/library/shelve.rst
+++ b/Doc/library/shelve.rst
@@ -54,6 +54,8 @@ lots of shared  sub-objects.  The keys are ordinary strings.
           with shelve.open('spam') as db:
               db['eggs'] = 'eggs'
 
+.. _shelve-security:
+
 .. warning::
 
    Because the :mod:`shelve` module is backed by :mod:`pickle`, it is insecure
diff --git a/Doc/library/subprocess.rst b/Doc/library/subprocess.rst
index a95047433d240..af5463364c44b 100644
--- a/Doc/library/subprocess.rst
+++ b/Doc/library/subprocess.rst
@@ -710,6 +710,7 @@ Exceptions defined in this module all inherit from :exc:`SubprocessError`.
    .. versionadded:: 3.3
       The :exc:`SubprocessError` base class was added.
 
+.. _subprocess-security:
 
 Security Considerations
 -----------------------
diff --git a/Doc/library/tempfile.rst b/Doc/library/tempfile.rst
index 49396b5f4bdc4..3e904d04642d8 100644
--- a/Doc/library/tempfile.rst
+++ b/Doc/library/tempfile.rst
@@ -344,6 +344,7 @@ Here are some examples of typical usage of the :mod:`tempfile` module::
     >>>
     # directory and contents have been removed
 
+.. _tempfile-mktemp-deprecated:
 
 Deprecated functions and variables
 ----------------------------------
diff --git a/Doc/library/zipfile.rst b/Doc/library/zipfile.rst
index a0bbdbf595aa8..9d0d894c05b57 100644
--- a/Doc/library/zipfile.rst
+++ b/Doc/library/zipfile.rst
@@ -886,6 +886,8 @@ Exceeding limitations on different file systems can cause decompression failed.
 Such as allowable characters in the directory entries, length of the file name,
 length of the pathname, size of a single file, and number of files, etc.
 
+.. _zipfile-resources-limitations:
+
 Resources limitations
 ~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/Misc/NEWS.d/next/Documentation/2020-01-30-05-18-48.bpo-39498.Nu3sFL.rst b/Misc/NEWS.d/next/Documentation/2020-01-30-05-18-48.bpo-39498.Nu3sFL.rst
new file mode 100644
index 0000000000000..a3e899a80a0fc
--- /dev/null
+++ b/Misc/NEWS.d/next/Documentation/2020-01-30-05-18-48.bpo-39498.Nu3sFL.rst
@@ -0,0 +1 @@
+Add a "Security Considerations" index which links to standard library modules that have explicitly documented security considerations.