bpo-39184: Add audit events to functions in `fcntl`, `msvcrt`, `os`, `resource`, `shutil`, `signal`, `syslog` (GH-18407)
Co-authored-by: Saiyang Gou <gousaiyang@163.com>
diff --git a/Doc/library/os.rst b/Doc/library/os.rst
index 0d8df34..3157b88 100644
--- a/Doc/library/os.rst
+++ b/Doc/library/os.rst
@@ -451,6 +451,8 @@
calls to :func:`putenv` don't update ``os.environ``, so it is actually
preferable to assign to items of ``os.environ``.
+ .. audit-event:: os.putenv key,value os.putenv
+
.. function:: setegid(egid)
@@ -643,6 +645,8 @@
calls to :func:`unsetenv` don't update ``os.environ``, so it is actually
preferable to delete items of ``os.environ``.
+ .. audit-event:: os.unsetenv key os.unsetenv
+
.. availability:: most flavors of Unix.
@@ -768,6 +772,8 @@
docs for :func:`chmod` for possible values of *mode*. As of Python 3.3, this
is equivalent to ``os.chmod(fd, mode)``.
+ .. audit-event:: os.chmod path,mode,dir_fd os.fchmod
+
.. availability:: Unix.
@@ -778,6 +784,8 @@
:func:`chown`. As of Python 3.3, this is equivalent to ``os.chown(fd, uid,
gid)``.
+ .. audit-event:: os.chown path,uid,gid,dir_fd os.fchown
+
.. availability:: Unix.
@@ -885,6 +893,8 @@
:data:`F_ULOCK` or :data:`F_TEST`.
*len* specifies the section of the file to lock.
+ .. audit-event:: os.lockf fd,cmd,len os.lockf
+
.. availability:: Unix.
.. versionadded:: 3.3
@@ -1602,6 +1612,8 @@
This function can raise :exc:`OSError` and subclasses such as
:exc:`FileNotFoundError`, :exc:`PermissionError`, and :exc:`NotADirectoryError`.
+ .. audit-event:: os.chdir path os.chdir
+
.. versionadded:: 3.3
Added support for specifying *path* as a file descriptor
on some platforms.
@@ -1630,6 +1642,8 @@
This function can support :ref:`not following symlinks <follow_symlinks>`.
+ .. audit-event:: os.chflags path,flags os.chflags
+
.. availability:: Unix.
.. versionadded:: 3.3
@@ -1675,6 +1689,8 @@
read-only flag with it (via the ``stat.S_IWRITE`` and ``stat.S_IREAD``
constants or a corresponding integer value). All other bits are ignored.
+ .. audit-event:: os.chmod path,mode,dir_fd os.chmod
+
.. versionadded:: 3.3
Added support for specifying *path* as an open file descriptor,
and the *dir_fd* and *follow_symlinks* arguments.
@@ -1695,6 +1711,8 @@
See :func:`shutil.chown` for a higher-level function that accepts names in
addition to numeric ids.
+ .. audit-event:: os.chown path,uid,gid,dir_fd os.chown
+
.. availability:: Unix.
.. versionadded:: 3.3
@@ -1721,6 +1739,8 @@
descriptor *fd*. The descriptor must refer to an opened directory, not an
open file. As of Python 3.3, this is equivalent to ``os.chdir(fd)``.
+ .. audit-event:: os.chdir path os.fchdir
+
.. availability:: Unix.
@@ -1745,6 +1765,8 @@
not follow symbolic links. As of Python 3.3, this is equivalent to
``os.chflags(path, flags, follow_symlinks=False)``.
+ .. audit-event:: os.chflags path,flags os.lchflags
+
.. availability:: Unix.
.. versionchanged:: 3.6
@@ -1758,6 +1780,8 @@
for possible values of *mode*. As of Python 3.3, this is equivalent to
``os.chmod(path, mode, follow_symlinks=False)``.
+ .. audit-event:: os.chmod path,mode,dir_fd os.lchmod
+
.. availability:: Unix.
.. versionchanged:: 3.6
@@ -1769,6 +1793,8 @@
function will not follow symbolic links. As of Python 3.3, this is equivalent
to ``os.chown(path, uid, gid, follow_symlinks=False)``.
+ .. audit-event:: os.chown path,uid,gid,dir_fd os.lchown
+
.. availability:: Unix.
.. versionchanged:: 3.6
@@ -1783,6 +1809,8 @@
supply :ref:`paths relative to directory descriptors <dir_fd>`, and :ref:`not
following symlinks <follow_symlinks>`.
+ .. audit-event:: os.link src,dst,src_dir_fd,dst_dir_fd os.link
+
.. availability:: Unix, Windows.
.. versionchanged:: 3.2
@@ -1885,6 +1913,8 @@
It is also possible to create temporary directories; see the
:mod:`tempfile` module's :func:`tempfile.mkdtemp` function.
+ .. audit-event:: os.mkdir path,mode,dir_fd os.mkdir
+
.. versionadded:: 3.3
The *dir_fd* argument.
@@ -1917,6 +1947,8 @@
This function handles UNC paths correctly.
+ .. audit-event:: os.mkdir path,mode,dir_fd os.makedirs
+
.. versionadded:: 3.2
The *exist_ok* parameter.
@@ -2082,6 +2114,8 @@
This function is semantically identical to :func:`unlink`.
+ .. audit-event:: os.remove path,dir_fd os.remove
+
.. versionadded:: 3.3
The *dir_fd* argument.
@@ -2102,6 +2136,8 @@
they are empty. Raises :exc:`OSError` if the leaf directory could not be
successfully removed.
+ .. audit-event:: os.remove path,dir_fd os.removedirs
+
.. versionchanged:: 3.6
Accepts a :term:`path-like object`.
@@ -2127,6 +2163,8 @@
If you want cross-platform overwriting of the destination, use :func:`replace`.
+ .. audit-event:: os.rename src,dst,src_dir_fd,dst_dir_fd os.rename
+
.. versionadded:: 3.3
The *src_dir_fd* and *dst_dir_fd* arguments.
@@ -2146,6 +2184,8 @@
This function can fail with the new directory structure made if you lack
permissions needed to remove the leaf directory or file.
+ .. audit-event:: os.rename src,dst,src_dir_fd,dst_dir_fd os.renames
+
.. versionchanged:: 3.6
Accepts a :term:`path-like object` for *old* and *new*.
@@ -2161,6 +2201,8 @@
This function can support specifying *src_dir_fd* and/or *dst_dir_fd* to
supply :ref:`paths relative to directory descriptors <dir_fd>`.
+ .. audit-event:: os.rename src,dst,src_dir_fd,dst_dir_fd os.replace
+
.. versionadded:: 3.3
.. versionchanged:: 3.6
@@ -2177,6 +2219,8 @@
This function can support :ref:`paths relative to directory descriptors
<dir_fd>`.
+ .. audit-event:: os.rmdir path,dir_fd os.rmdir
+
.. versionadded:: 3.3
The *dir_fd* parameter.
@@ -2820,6 +2864,8 @@
:exc:`OSError` is raised when the function is called by an unprivileged
user.
+ .. audit-event:: os.symlink src,dst,dir_fd os.symlink
+
.. availability:: Unix, Windows.
.. versionchanged:: 3.2
@@ -2872,6 +2918,8 @@
traditional Unix name. Please see the documentation for
:func:`remove` for further information.
+ .. audit-event:: os.remove path,dir_fd os.unlink
+
.. versionadded:: 3.3
The *dir_fd* parameter.
@@ -2909,6 +2957,8 @@
:ref:`paths relative to directory descriptors <dir_fd>` and :ref:`not
following symlinks <follow_symlinks>`.
+ .. audit-event:: os.utime path,times,ns,dir_fd os.utime
+
.. versionadded:: 3.3
Added support for specifying *path* as an open file descriptor,
and the *dir_fd*, *follow_symlinks*, and *ns* parameters.
@@ -3134,6 +3184,8 @@
This function can support :ref:`specifying a file descriptor <path_fd>` and
:ref:`not following symlinks <follow_symlinks>`.
+ .. audit-event:: os.getxattr path,attribute os.getxattr
+
.. versionchanged:: 3.6
Accepts a :term:`path-like object` for *path* and *attribute*.
@@ -3148,6 +3200,8 @@
This function can support :ref:`specifying a file descriptor <path_fd>` and
:ref:`not following symlinks <follow_symlinks>`.
+ .. audit-event:: os.listxattr path os.listxattr
+
.. versionchanged:: 3.6
Accepts a :term:`path-like object`.
@@ -3162,6 +3216,8 @@
This function can support :ref:`specifying a file descriptor <path_fd>` and
:ref:`not following symlinks <follow_symlinks>`.
+ .. audit-event:: os.removexattr path,attribute os.removexattr
+
.. versionchanged:: 3.6
Accepts a :term:`path-like object` for *path* and *attribute*.
@@ -3185,6 +3241,8 @@
A bug in Linux kernel versions less than 2.6.39 caused the flags argument
to be ignored on some filesystems.
+ .. audit-event:: os.setxattr path,attribute,value,flags os.setxattr
+
.. versionchanged:: 3.6
Accepts a :term:`path-like object` for *path* and *attribute*.
@@ -3247,6 +3305,8 @@
<https://msdn.microsoft.com/44228cf2-6306-466c-8f16-f513cd3ba8b5>`_
for more information about how DLLs are loaded.
+ .. audit-event:: os.add_dll_directory path os.add_dll_directory
+
.. availability:: Windows.
.. versionadded:: 3.8
@@ -3479,6 +3539,8 @@
Note that some platforms including FreeBSD <= 6.3 and Cygwin have
known issues when using ``fork()`` from a thread.
+ .. audit-event:: os.fork "" os.fork
+
.. versionchanged:: 3.8
Calling ``fork()`` in a subinterpreter is no longer supported
(:exc:`RuntimeError` is raised).
@@ -3498,6 +3560,8 @@
master end of the pseudo-terminal. For a more portable approach, use the
:mod:`pty` module. If an error occurs :exc:`OSError` is raised.
+ .. audit-event:: os.forkpty "" os.forkpty
+
.. versionchanged:: 3.8
Calling ``forkpty()`` in a subinterpreter is no longer supported
(:exc:`RuntimeError` is raised).
@@ -3524,6 +3588,8 @@
See also :func:`signal.pthread_kill`.
+ .. audit-event:: os.kill pid,sig os.kill
+
.. versionadded:: 3.2
Windows support.
@@ -3536,6 +3602,8 @@
Send the signal *sig* to the process group *pgid*.
+ .. audit-event:: os.killpg pgid,sig os.killpg
+
.. availability:: Unix.