[3.14] annotationlib: add note on security to docs (GH-138508) (#138550)

annotationlib: add note on security to docs (GH-138508)
(cherry picked from commit 9158bcf86b54df419cab3131412c25edd11fb0d5)

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>

diff --git a/Doc/library/annotationlib.rst b/Doc/library/annotationlib.rst
index b31be97d04519111c1bdcde67b4d4552dad0d57e..d6f5055955e8cf2ebd7fef28694c6fda6403421b 100644 (file)
--- a/Doc/library/annotationlib.rst
+++ b/Doc/library/annotationlib.rst
@@ -46,6 +46,10 @@ and :func:`call_annotate_function`, as well as the
 :func:`call_evaluate_function` function for working with
 :term:`evaluate functions <evaluate function>`.
 
+.. caution::
+
+   Most functionality in this module can execute arbitrary code; see
+   :ref:`the security section <annotationlib-security>` for more information.
 
 .. seealso::
 
@@ -604,3 +608,23 @@ Below are a few examples of the behavior with unsupported expressions:
    >>> def ifexp(x: 1 if y else 0): ...
    >>> get_annotations(ifexp, format=Format.STRING)
    {'x': '1'}
+
+.. _annotationlib-security:
+
+Security implications of introspecting annotations
+--------------------------------------------------
+
+Much of the functionality in this module involves executing code related to annotations,
+which can then do arbitrary things. For example,
+:func:`get_annotations` may call an arbitrary :term:`annotate function`, and
+:meth:`ForwardRef.evaluate` may call :func:`eval` on an arbitrary string. Code contained
+in an annotation might make arbitrary system calls, enter an infinite loop, or perform any
+other operation. This is also true for any access of the :attr:`~object.__annotations__` attribute,
+and for various functions in the :mod:`typing` module that work with annotations, such as
+:func:`typing.get_type_hints`.
+
+Any security issue arising from this also applies immediately after importing
+code that may contain untrusted annotations: importing code can always cause arbitrary operations
+to be performed. However, it is unsafe to accept strings or other input from an untrusted source and
+pass them to any of the APIs for introspecting annotations, for example by editing an
+``__annotations__`` dictionary or directly creating a :class:`ForwardRef` object.

diff --git a/Doc/library/inspect.rst b/Doc/library/inspect.rst
index e8d1176f4778667e382a74d2ad08daf20003db24..1061ae8849f48f9015fd577ec743f610bcd08d95 100644 (file)
--- a/Doc/library/inspect.rst
+++ b/Doc/library/inspect.rst
@@ -1289,6 +1289,11 @@ Classes and functions
    This is an alias for :func:`annotationlib.get_annotations`; see the documentation
    of that function for more information.
 
+   .. caution::
+
+      This function may execute arbitrary code contained in annotations.
+      See :ref:`annotationlib-security` for more information.
+
    .. versionadded:: 3.10
 
    .. versionchanged:: 3.14

diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst
index 9dbac8ce75d4892039a8c66929243f35e9a3fdc0..b20e1bcc1f012aad694ec26fea15b51fda2b5b55 100644 (file)
--- a/Doc/library/typing.rst
+++ b/Doc/library/typing.rst
@@ -3360,6 +3360,11 @@ Introspection helpers
    See also :func:`annotationlib.get_annotations`, a lower-level function that
    returns annotations more directly.
 
+   .. caution::
+
+      This function may execute arbitrary code contained in annotations.
+      See :ref:`annotationlib-security` for more information.
+
    .. note::
 
       If any forward references in the annotations of *obj* are not resolvable
@@ -3506,6 +3511,11 @@ Introspection helpers
    See the documentation for :meth:`annotationlib.ForwardRef.evaluate` for
    the meaning of the *owner*, *globals*, *locals*, *type_params*, and *format* parameters.
 
+   .. caution::
+
+      This function may execute arbitrary code contained in annotations.
+      See :ref:`annotationlib-security` for more information.
+
    .. versionadded:: 3.14
 
 .. data:: NoDefault