Add audit hooks for pickle.load, pickle.loads, and pickle.Unpickler

Add sys.audit / PySys_Audit calls for deserialization entry points in
the pickle module to allow security monitoring of pickle usage. This
complements the existing pickle.find_class audit event by providing
visibility into when pickle deserialization is initiated, not just when
classes are resolved during unpickling.

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

These hooks are implemented in both the Python (Lib/pickle.py) and C
(Modules/_pickle.c) implementations.

https://claude.ai/code/session_01HKopnL4QijaMQU4drGEefL

Author: claude

Doc/library/pickle.rst

@@ -236,9 +236,14 @@ 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.
 
+   .. versionchanged:: next
+      Added the ``pickle.load`` audit event.
+
 .. function:: loads(data, /, *, fix_imports=True, encoding="ASCII", errors="strict", buffers=None)
 
    Return the reconstituted object hierarchy of the pickled representation
@@ -251,9 +256,14 @@ 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.
 
+   .. versionchanged:: next
+      Added the ``pickle.loads`` audit event.
+
 
 The :mod:`pickle` module defines three exceptions:
 
@@ -417,9 +427,14 @@ 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.
 
+   .. versionchanged:: next
+      Added the ``pickle.Unpickler`` audit event.
+
    .. method:: load()
 
       Read the pickled representation of an object from the open file object

Lib/pickle.py

@@ -1218,6 +1218,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
@@ -1803,13 +1804,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

@@ -135,6 +135,7 @@ def test_marshal():
 
 def test_pickle():
     import pickle
+    import io
 
     class PicklePrint:
         def __reduce_ex__(self, p):
@@ -153,6 +154,21 @@ def __reduce_ex__(self, p):
         # pickles with no globals are okay
         pickle.loads(payload_2)
 
+    # Test that pickle.loads raises the pickle.loads audit event
+    with TestHook(raise_on_events="pickle.loads") as hook:
+        with assertRaises(RuntimeError):
+            pickle.loads(payload_2)
+
+    # Test that pickle.load raises the pickle.load audit event
+    with TestHook(raise_on_events="pickle.load") as hook:
+        with assertRaises(RuntimeError):
+            pickle.load(io.BytesIO(payload_2))
+
+    # Test that pickle.Unpickler raises the pickle.Unpickler audit event
+    with TestHook(raise_on_events="pickle.Unpickler") as hook:
+        with assertRaises(RuntimeError):
+            pickle.Unpickler(io.BytesIO(payload_2))
+
 
 def test_monkeypatch():
     class A:

Modules/_pickle.c

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