gh-87604: Clarify in docs that sys.addaudithook is not for sandboxes (GH-99372)

(cherry picked from commit c3c3871415c86088d45abcf73ccd2c2b09dc5772)

Co-authored-by: Steve Dower <steve.dower@python.org>

diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst
index 0417d2752689e54db044ae8aef6c74e22a19980d..5da5ffa07012d2eb38b2df5d6d8a77c1732fa7a8 100644 (file)
--- a/Doc/library/sys.rst
+++ b/Doc/library/sys.rst
@@ -35,6 +35,15 @@ always available.
    can then log the event, raise an exception to abort the operation,
    or terminate the process entirely.
 
+   Note that audit hooks are primarily for collecting information about internal
+   or otherwise unobservable actions, whether by Python or libraries written in
+   Python. They are not suitable for implementing a "sandbox". In particular,
+   malicious code can trivially disable or bypass hooks added using this
+   function. At a minimum, any security-sensitive hooks must be added using the
+   C API :c:func:`PySys_AddAuditHook` before initialising the runtime, and any
+   modules allowing arbitrary memory modification (such as :mod:`ctypes`) should
+   be completely removed or closely monitored.
+
    .. audit-event:: sys.addaudithook "" sys.addaudithook
 
       Calling :func:`sys.addaudithook` will itself raise an auditing event