annotationlib: add note on security to docs (#138508)

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 c8eb1d08a1bb2a4a514a923c7bd6415f947719ba..022c76b084c08c90c8e000b326b8cb8cc3b8779a 100644 (file)
--- a/Doc/library/typing.rst
+++ b/Doc/library/typing.rst
@@ -3367,6 +3367,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
@@ -3513,6 +3518,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