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>

Doc/library/fcntl.rst

@@ -57,6 +57,8 @@ The module defines the following functions:
 
    If the :c:func:`fcntl` fails, an :exc:`OSError` is raised.
 
+   .. audit-event:: fcntl.fcntl fd,cmd,arg fcntl.fcntl
+
 
 .. function:: ioctl(fd, request, arg=0, mutate_flag=True)
 
@@ -106,6 +108,8 @@ The module defines the following functions:
       >>> buf
       array('h', [13341])
 
+   .. audit-event:: fcntl.ioctl fd,request,arg fcntl.ioctl
+
 
 .. function:: flock(fd, operation)
 
@@ -116,6 +120,8 @@ The module defines the following functions:
 
    If the :c:func:`flock` fails, an :exc:`OSError` exception is raised.
 
+   .. audit-event:: fcntl.flock fd,operation fcntl.flock
+
 
 .. function:: lockf(fd, cmd, len=0, start=0, whence=0)
 
@@ -149,6 +155,8 @@ The module defines the following functions:
    The default for *len* is 0 which means to lock to the end of the file.  The
    default for *whence* is also 0.
 
+   .. audit-event:: fcntl.lockf fd,cmd,len,start,whence fcntl.lockf
+
 Examples (all on a SVR4 compliant system)::
 
    import struct, fcntl, os

Doc/library/msvcrt.rst

@@ -42,6 +42,8 @@ File Operations
    regions in a file may be locked at the same time, but may not overlap.  Adjacent
    regions are not merged; they must be unlocked individually.
 
+   .. audit-event:: msvcrt.locking fd,mode,nbytes msvcrt.locking
+
 
 .. data:: LK_LOCK
           LK_RLCK
@@ -77,12 +79,16 @@ File Operations
    and :const:`os.O_TEXT`.  The returned file descriptor may be used as a parameter
    to :func:`os.fdopen` to create a file object.
 
+   .. audit-event:: msvcrt.open_osfhandle handle,flags msvcrt.open_osfhandle
+
 
 .. function:: get_osfhandle(fd)
 
    Return the file handle for the file descriptor *fd*.  Raises :exc:`OSError` if
    *fd* is not recognized.
 
+   .. audit-event:: msvcrt.get_osfhandle fd msvcrt.get_osfhandle
+
 
 .. _msvcrt-console:
 

Doc/library/os.rst

@@ -451,6 +451,8 @@ process and user.
    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 @@ process and user.
    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 @@ 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.
 
 
@@ -778,6 +784,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.
 
 
@@ -885,6 +893,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
@@ -1602,6 +1612,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.
@@ -1630,6 +1642,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
@@ -1675,6 +1689,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.
@@ -1695,6 +1711,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
@@ -1721,6 +1739,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.
 
 
@@ -1745,6 +1765,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
@@ -1758,6 +1780,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
@@ -1769,6 +1793,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
@@ -1783,6 +1809,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
@@ -1885,6 +1913,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.
 
@@ -1917,6 +1947,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.
 
@@ -2082,6 +2114,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.
 
@@ -2102,6 +2136,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`.
 
@@ -2127,6 +2163,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.
 
@@ -2146,6 +2184,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*.
 
@@ -2161,6 +2201,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
@@ -2177,6 +2219,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.
 
@@ -2820,6 +2864,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
@@ -2872,6 +2918,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.
 
@@ -2909,6 +2957,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.
@@ -3134,6 +3184,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*.
 
@@ -3148,6 +3200,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`.
 
@@ -3162,6 +3216,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*.
 
@@ -3185,6 +3241,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*.
 
@@ -3247,6 +3305,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
@@ -3479,6 +3539,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).
@@ -3498,6 +3560,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).
@@ -3524,6 +3588,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.
 
@@ -3536,6 +3602,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.
 
 

Doc/library/resource.rst

@@ -78,6 +78,9 @@ this module for those platforms.
 
    VxWorks only supports setting :data:`RLIMIT_NOFILE`.
 
+   .. audit-event:: resource.setrlimit resource,limits resource.setrlimit
+
+
 .. function:: prlimit(pid, resource[, limits])
 
    Combines :func:`setrlimit` and :func:`getrlimit` in one function and
@@ -94,6 +97,8 @@ this module for those platforms.
    :exc:`PermissionError` when the user doesn't have ``CAP_SYS_RESOURCE`` for
    the process.
 
+   .. audit-event:: resource.prlimit pid,resource,limits resource.prlimit
+
    .. availability:: Linux 2.6.36 or later with glibc 2.13 or later.
 
    .. versionadded:: 3.4