gh-XXXXX: Add audit hooks for pickle.load, pickle.loads, and pickle.Unpickler

Add sys.audit() calls to raise audit events when pickle deserializes data,
enabling security monitoring and access control via Python's audit hook system.

New audit events:
- pickle.load(file): raised by pickle.load()
- pickle.loads(data): raised by pickle.loads()
- pickle.Unpickler(file): raised when pickle.Unpickler() is instantiated

Both the C extension (_pickle) and the pure Python fallback (pickle)
emit the same events, ensuring consistent behavior regardless of which
implementation is active.

https://claude.ai/code/session_01BWEWpGi5yZzcLHwjh9FWtP

Author: claude

Doc/library/pickle.rst

@@ -240,6 +240,8 @@ process more convenient:
    Arguments *file*, *fix_imports*, *encoding*, *errors*, *strict* and *buffers*
    have the same meaning as in the :class:`Unpickler` constructor.
 
+   .. audit-event:: pickle.load file pickle.load
+
    .. versionchanged:: 3.8
       The *buffers* argument was added.
 
@@ -255,6 +257,8 @@ process more convenient:
    Arguments *fix_imports*, *encoding*, *errors*, *strict* and *buffers*
    have the same meaning as in the :class:`Unpickler` constructor.
 
+   .. audit-event:: pickle.loads data pickle.loads
+
    .. versionchanged:: 3.8
       The *buffers* argument was added.
 
@@ -430,6 +434,8 @@ The :mod:`!pickle` module exports three classes, :class:`Pickler`,
    an :ref:`out-of-band <pickle-oob>` buffer view.  Such buffers have been
    given in order to the *buffer_callback* of a Pickler object.
 
+   .. audit-event:: pickle.Unpickler file pickle.Unpickler
+
    .. versionchanged:: 3.8
       The *buffers* argument was added.
 

Lib/pickle.py

@@ -1314,6 +1314,7 @@ def __init__(self, file, *, fix_imports=True,
         default to 'ASCII' and 'strict', respectively. *encoding* can be
         'bytes' to read these 8-bit string instances as bytes objects.
         """
+        sys.audit("pickle.Unpickler", file)
         self._buffers = iter(buffers) if buffers is not None else None
         self._file_readline = file.readline
         self._file_read = file.read
@@ -1909,13 +1910,15 @@ def _dumps(obj, protocol=None, *, fix_imports=True, buffer_callback=None):
 
 def _load(file, *, fix_imports=True, encoding="ASCII", errors="strict",
           buffers=None):
+    sys.audit("pickle.load", file)
     return _Unpickler(file, fix_imports=fix_imports, buffers=buffers,
                      encoding=encoding, errors=errors).load()
 
 def _loads(s, /, *, fix_imports=True, encoding="ASCII", errors="strict",
            buffers=None):
     if isinstance(s, str):
         raise TypeError("Can't load pickle from unicode string")
+    sys.audit("pickle.loads", s)
     file = io.BytesIO(s)
     return _Unpickler(file, fix_imports=fix_imports, buffers=buffers,
                       encoding=encoding, errors=errors).load()

Lib/test/audit-tests.py

@@ -136,6 +136,7 @@ def test_marshal():
 
 
 def test_pickle():
+    import io
     import pickle
 
     class PicklePrint:
@@ -155,6 +156,24 @@ def __reduce_ex__(self, p):
         # pickles with no globals are okay
         pickle.loads(payload_2)
 
+    # Test pickle.loads audit event
+    with TestHook() as hook:
+        pickle.loads(payload_2)
+    actual = [a[0] for e, a in hook.seen if e == "pickle.loads"]
+    assertSequenceEqual(actual, [payload_2])
+
+    # Test pickle.load audit event
+    with TestHook() as hook:
+        pickle.load(io.BytesIO(payload_2))
+    actual = [e for e, a in hook.seen if e == "pickle.load"]
+    assertSequenceEqual(actual, ["pickle.load"])
+
+    # Test pickle.Unpickler audit event
+    with TestHook() as hook:
+        pickle.Unpickler(io.BytesIO(payload_2))
+    actual = [e for e, a in hook.seen if e == "pickle.Unpickler"]
+    assertSequenceEqual(actual, ["pickle.Unpickler"])
+
 
 def test_monkeypatch():
     class A:

Modules/_pickle.c

@@ -7515,6 +7515,10 @@ _pickle_Unpickler___init___impl(UnpicklerObject *self, PyObject *file,
 /*[clinic end generated code: output=09f0192649ea3f85 input=ca4c1faea9553121]*/
 {
     BEGIN_USING_UNPICKLER(self, -1);
+    if (PySys_Audit("pickle.Unpickler", "O", file) < 0) {
+        END_USING_UNPICKLER(self);
+        return -1;
+    }
     /* In case of multiple __init__() calls, clear previous content. */
     if (self->read != NULL)
         (void)Unpickler_clear((PyObject *)self);
@@ -8043,6 +8047,9 @@ _pickle_load_impl(PyObject *module, PyObject *file, int fix_imports,
                   PyObject *buffers)
 /*[clinic end generated code: output=250452d141c23e76 input=46c7c31c92f4f371]*/
 {
+    if (PySys_Audit("pickle.load", "O", file) < 0) {
+        return NULL;
+    }
     PyObject *result;
     UnpicklerObject *unpickler = _Unpickler_New(module);
 
@@ -8104,6 +8111,9 @@ _pickle_loads_impl(PyObject *module, PyObject *data, int fix_imports,
                    PyObject *buffers)
 /*[clinic end generated code: output=82ac1e6b588e6d02 input=b3615540d0535087]*/
 {
+    if (PySys_Audit("pickle.loads", "O", data) < 0) {
+        return NULL;
+    }
     PyObject *result;
     UnpicklerObject *unpickler = _Unpickler_New(module);