gh-149473: Emit audit event on calling os.environ.clear() (#149768)

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 1a759fd9e7dc9163eb216ed864536951b422a008..d406d43cdf7f4fb92459fb2dc90972b8763fd12b 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 7552cd150f0c2afc147562cdf1e3828eae51a9e8..db29c6e5f08d6f8e204ad0c80df7e11d5707d791 100644 (file)
--- a/Modules/posixmodule.c
+++ b/Modules/posixmodule.c
@@ -13692,6 +13692,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) {