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

Add sys.audit() calls to pickle deserialization entry points so that
audit hook callbacks can monitor or block untrusted pickle data before
deserialization begins. This complements the existing pickle.find_class
audit event which only fires when resolving globals during unpickling.

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

These are added to both the pure Python (Lib/pickle.py) and C-accelerated
(Modules/_pickle.c) implementations.

https://claude.ai/code/session_01EonnbetfRuaXpkjG3KHw4f

Author: claude

Doc/library/pickle.rst

@@ -240,9 +240,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:: 3.15
+      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
@@ -255,9 +260,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:: 3.15
+      Added the ``pickle.loads`` audit event.
+
 
 The :mod:`!pickle` module defines three exceptions:
 
@@ -430,9 +440,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:: 3.15
+      Added the ``pickle.Unpickler`` audit event.
+
    .. method:: load()
 
       Read the pickled representation of an object from the open file object

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

@@ -137,6 +137,7 @@ def test_marshal():
 
 def test_pickle():
     import pickle
+    import io
 
     class PicklePrint:
         def __reduce_ex__(self, p):
@@ -156,6 +157,50 @@ def __reduce_ex__(self, p):
         pickle.loads(payload_2)
 
 
+def test_pickle_load_audit():
+    import pickle
+    import io
+
+    payload = pickle.dumps(("a", "b", "c", 1, 2, 3))
+
+    # Test pickle.loads audit event
+    with TestHook() as hook:
+        pickle.loads(payload)
+    actual = [e for e, a in hook.seen if e == "pickle.loads"]
+    assertSequenceEqual(actual, ["pickle.loads"])
+
+    # Test pickle.load audit event
+    with TestHook() as hook:
+        f = io.BytesIO(payload)
+        pickle.load(f)
+    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:
+        f = io.BytesIO(payload)
+        pickle.Unpickler(f).load()
+    actual = [e for e, a in hook.seen if e == "pickle.Unpickler"]
+    assertSequenceEqual(actual, ["pickle.Unpickler"])
+
+    # Test that pickle.loads can be blocked
+    with TestHook(raise_on_events="pickle.loads") as hook:
+        with assertRaises(RuntimeError):
+            pickle.loads(payload)
+
+    # Test that pickle.load can be blocked
+    with TestHook(raise_on_events="pickle.load") as hook:
+        with assertRaises(RuntimeError):
+            f = io.BytesIO(payload)
+            pickle.load(f)
+
+    # Test that pickle.Unpickler can be blocked
+    with TestHook(raise_on_events="pickle.Unpickler") as hook:
+        with assertRaises(RuntimeError):
+            f = io.BytesIO(payload)
+            pickle.Unpickler(f)
+
+
 def test_monkeypatch():
     class A:
         pass

Lib/test/test_audit.py

@@ -68,6 +68,11 @@ def test_pickle(self):
 
         self.do_test("test_pickle")
 
+    def test_pickle_load_audit(self):
+        import_helper.import_module("pickle")
+
+        self.do_test("test_pickle_load_audit")
+
     def test_monkeypatch(self):
         self.do_test("test_monkeypatch")
 

Misc/NEWS.d/next/Security/2026-03-07-17-30-00.gh-issue-0.pickle-audit.rst

@@ -0,0 +1,4 @@
+Added audit events ``pickle.load``, ``pickle.loads``, and
+``pickle.Unpickler`` that are raised when unpickling operations are initiated.
+These hooks allow audit hook callbacks to monitor or block deserialization of
+untrusted pickle data.

Modules/_pickle.c

@@ -7514,6 +7514,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)
@@ -8044,6 +8048,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)
@@ -8105,6 +8114,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)