[3.15] gh-149473: Emit audit event on calling os.environ.clear() (GH-149768) (#150094)

gh-149473: Emit audit event on calling os.environ.clear() (GH-149768)
(cherry picked from commit 29415c071f368e34b504e5efab9d0a795e7c6222)

Co-authored-by: Victor Stinner <vstinner@python.org>
Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com>

diff --git a/Doc/library/os.rst b/Doc/library/os.rst
index f2c9b3914f36e623c9d6d77aa997ae1ee1912d8a..b65dbb4623af2a8c002974557b53fc99debe9819 100644 (file)
--- a/Doc/library/os.rst
+++ b/Doc/library/os.rst
@@ -219,6 +219,14 @@ process and user.
    :data:`os.environ`, and when one of the :meth:`~dict.pop` or
    :meth:`~dict.clear` methods is called.
 
+   If the :manpage:`clearenv(3)` function is available, the :meth:`~dict.clear` method
+   uses it and emits a single ``os._clearenv`` audit event. Otherwise, it emits
+   an ``os.unsetenv`` event on each deleted variable.
+
+   .. audit-event:: os.unsetenv key os.unsetenv
+
+   .. audit-event:: os._clearenv "" os._clearenv
+
    .. seealso::
 
       The :func:`os.reload_environ` function.
@@ -226,6 +234,10 @@ process and user.
    .. versionchanged:: 3.9
       Updated to support :pep:`584`'s merge (``|``) and update (``|=``) operators.
 
+   .. versionchanged:: 3.15
+      The :meth:`~dict.clear` method can now emit an ``os._clearenv`` audit
+      event.
+
 
 .. data:: environb
 

diff --git a/Misc/NEWS.d/next/Library/2026-05-13-12-16-54.gh-issue-149473.nOQZqn.rst b/Misc/NEWS.d/next/Library/2026-05-13-12-16-54.gh-issue-149473.nOQZqn.rst
new file mode 100644 (file)
index 0000000..db624ab
--- /dev/null
+++ b/Misc/NEWS.d/next/Library/2026-05-13-12-16-54.gh-issue-149473.nOQZqn.rst
@@ -0,0 +1,2 @@
+Calling ``os.environ.clear()`` now emits ``os._clearenv`` auditing event.
+Patch by Victor Stinner.

diff --git a/Modules/posixmodule.c b/Modules/posixmodule.c
index 214c4ab8602be72849b55529494e16d306aea800..60695cf116a41d6c56f585e5b1e26904ec1a2038 100644 (file)
--- a/Modules/posixmodule.c
+++ b/Modules/posixmodule.c
@@ -13678,6 +13678,10 @@ static PyObject *
 os__clearenv_impl(PyObject *module)
 /*[clinic end generated code: output=2d6705d62c014b51 input=47d2fa7f323c43ca]*/
 {
+    if (PySys_Audit("os._clearenv", NULL) < 0) {
+        return NULL;
+    }
+
     errno = 0;
     int err = clearenv();
     if (err) {