bpo-39184: Add audit events to functions in `fcntl`, `msvcrt`, `os`, `resource`, `shutil`, `signal`, `syslog` (GH-18407)

1 files changed, 68 insertions, 0 deletions

diff --git a/Doc/library/os.rst b/Doc/library/os.rst
index b06a318..af02a37 100644
--- a/Doc/library/os.rst
+++ b/Doc/library/os.rst
@@ -445,6 +445,8 @@ process and user.
       On some platforms, including FreeBSD and Mac OS X, setting ``environ`` may
       cause memory leaks. Refer to the system documentation for :c:func:`putenv`.
 
+   .. audit-event:: os.putenv key,value os.putenv
+
    .. versionchanged:: 3.9
       The function is now always available.
 
@@ -640,6 +642,8 @@ process and user.
    don't update ``os.environ``, so it is actually preferable to delete items of
    ``os.environ``.
 
+   .. audit-event:: os.unsetenv key os.unsetenv
+
    .. versionchanged:: 3.9
       The function is now always available and is also available on Windows.
 
@@ -766,6 +770,8 @@ as internal buffering of data.
    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.
 
 
@@ -776,6 +782,8 @@ as internal buffering of data.
    :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.
 
 
@@ -883,6 +891,8 @@ as internal buffering of data.
    :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
@@ -1603,6 +1613,8 @@ features:
    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.
@@ -1631,6 +1643,8 @@ features:
 
    This function can support :ref:`not following symlinks <follow_symlinks>`.
 
+   .. audit-event:: os.chflags path,flags os.chflags
+
    .. availability:: Unix.
 
    .. versionadded:: 3.3
@@ -1676,6 +1690,8 @@ features:
       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.
@@ -1696,6 +1712,8 @@ features:
    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
@@ -1722,6 +1740,8 @@ features:
    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.
 
 
@@ -1746,6 +1766,8 @@ features:
    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
@@ -1759,6 +1781,8 @@ features:
    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
@@ -1770,6 +1794,8 @@ features:
    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
@@ -1784,6 +1810,8 @@ features:
    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
@@ -1886,6 +1914,8 @@ features:
    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.
 
@@ -1918,6 +1948,8 @@ features:
 
    This function handles UNC paths correctly.
 
+   .. audit-event:: os.mkdir path,mode,dir_fd os.makedirs
+
    .. versionadded:: 3.2
       The *exist_ok* parameter.
 
@@ -2083,6 +2115,8 @@ features:
 
    This function is semantically identical to :func:`unlink`.
 
+   .. audit-event:: os.remove path,dir_fd os.remove
+
    .. versionadded:: 3.3
       The *dir_fd* argument.
 
@@ -2103,6 +2137,8 @@ features:
    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`.
 
@@ -2128,6 +2164,8 @@ features:
 
    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.
 
@@ -2147,6 +2185,8 @@ features:
       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*.
 
@@ -2162,6 +2202,8 @@ features:
    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
@@ -2178,6 +2220,8 @@ features:
    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.
 
@@ -2821,6 +2865,8 @@ features:
       :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
@@ -2873,6 +2919,8 @@ features:
    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.
 
@@ -2910,6 +2958,8 @@ features:
    :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.
@@ -3135,6 +3185,8 @@ These functions are all available on Linux only.
    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*.
 
@@ -3149,6 +3201,8 @@ These functions are all available on Linux only.
    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`.
 
@@ -3163,6 +3217,8 @@ These functions are all available on Linux only.
    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*.
 
@@ -3186,6 +3242,8 @@ These functions are all available on Linux only.
       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*.
 
@@ -3248,6 +3306,8 @@ to be ignored.
    <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
@@ -3480,6 +3540,8 @@ written in Python, such as a mail server's external command delivery program.
    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).
@@ -3499,6 +3561,8 @@ written in Python, such as a mail server's external command delivery program.
    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).
@@ -3525,6 +3589,8 @@ written in Python, such as a mail server's external command delivery program.
 
    See also :func:`signal.pthread_kill`.
 
+   .. audit-event:: os.kill pid,sig os.kill
+
    .. versionadded:: 3.2
       Windows support.
 
@@ -3537,6 +3603,8 @@ written in Python, such as a mail server's external command delivery program.
 
    Send the signal *sig* to the process group *pgid*.
 
+   .. audit-event:: os.killpg pgid,sig os.killpg
+
    .. availability:: Unix.