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/fcntl.rst b/Doc/library/fcntl.rst
index a739015..69484b6 100644
--- a/Doc/library/fcntl.rst
+++ b/Doc/library/fcntl.rst
@@ -57,6 +57,8 @@
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 @@
>>> buf
array('h', [13341])
+ .. audit-event:: fcntl.ioctl fd,request,arg fcntl.ioctl
+
.. function:: flock(fd, operation)
@@ -116,6 +120,8 @@
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 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
diff --git a/Doc/library/msvcrt.rst b/Doc/library/msvcrt.rst
index 14ad2cd..42fffee 100644
--- a/Doc/library/msvcrt.rst
+++ b/Doc/library/msvcrt.rst
@@ -42,6 +42,8 @@
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 @@
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:
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.
diff --git a/Doc/library/resource.rst b/Doc/library/resource.rst
index 3573da7..e4eac43 100644
--- a/Doc/library/resource.rst
+++ b/Doc/library/resource.rst
@@ -78,6 +78,9 @@
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 @@
: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
diff --git a/Doc/library/shutil.rst b/Doc/library/shutil.rst
index 174b7e8..bd24de7 100644
--- a/Doc/library/shutil.rst
+++ b/Doc/library/shutil.rst
@@ -67,6 +67,8 @@
a new symbolic link will be created instead of copying the
file *src* points to.
+ .. audit-event:: shutil.copyfile src,dst shutil.copyfile
+
.. versionchanged:: 3.3
:exc:`IOError` used to be raised instead of :exc:`OSError`.
Added *follow_symlinks* argument.
@@ -101,6 +103,8 @@
:func:`copymode` cannot modify symbolic links on the local platform, and it
is asked to do so, it will do nothing and return.
+ .. audit-event:: shutil.copymode src,dst shutil.copymode
+
.. versionchanged:: 3.3
Added *follow_symlinks* argument.
@@ -146,6 +150,8 @@
Please see :data:`os.supports_follow_symlinks`
for more information.
+ .. audit-event:: shutil.copystat src,dst shutil.copystat
+
.. versionchanged:: 3.3
Added *follow_symlinks* argument and support for Linux extended attributes.
@@ -167,6 +173,10 @@
To preserve all file metadata from the original, use
:func:`~shutil.copy2` instead.
+ .. audit-event:: shutil.copyfile src,dst shutil.copy
+
+ .. audit-event:: shutil.copymode src,dst shutil.copy
+
.. versionchanged:: 3.3
Added *follow_symlinks* argument.
Now returns path to the newly created file.
@@ -194,6 +204,10 @@
Please see :func:`copystat` for more information
about platform support for modifying symbolic link metadata.
+ .. audit-event:: shutil.copyfile src,dst shutil.copy2
+
+ .. audit-event:: shutil.copystat src,dst shutil.copy2
+
.. versionchanged:: 3.3
Added *follow_symlinks* argument, try to copy extended
file system attributes too (currently Linux only).
@@ -342,6 +356,8 @@
*copy_function* allows the move to succeed when it is not possible to also
copy the metadata, at the expense of not copying any of the metadata.
+ .. audit-event:: shutil.move src,dst shutil.move
+
.. versionchanged:: 3.3
Added explicit symlink handling for foreign filesystems, thus adapting
it to the behavior of GNU's :program:`mv`.
@@ -378,6 +394,8 @@
See also :func:`os.chown`, the underlying function.
+ .. audit-event:: shutil.chown path,user,group shutil.chown
+
.. availability:: Unix.
.. versionadded:: 3.3
@@ -629,6 +647,8 @@
registered for that extension. In case none is found,
a :exc:`ValueError` is raised.
+ .. audit-event:: shutil.unpack_archive filename,extract_dir,format shutil.unpack_archive
+
.. versionchanged:: 3.7
Accepts a :term:`path-like object` for *filename* and *extract_dir*.
diff --git a/Doc/library/signal.rst b/Doc/library/signal.rst
index 8fecc2b..932201b 100644
--- a/Doc/library/signal.rst
+++ b/Doc/library/signal.rst
@@ -264,6 +264,8 @@
If *signalnum* is 0, then no signal is sent, but error checking is still
performed; this can be used to check if the target thread is still running.
+ .. audit-event:: signal.pthread_kill thread_id,signalnum signal.pthread_kill
+
.. availability:: Unix. See the man page :manpage:`pthread_kill(3)` for further
information.
diff --git a/Doc/library/syslog.rst b/Doc/library/syslog.rst
index 7151527..d264a33 100644
--- a/Doc/library/syslog.rst
+++ b/Doc/library/syslog.rst
@@ -31,6 +31,8 @@
If :func:`openlog` has not been called prior to the call to :func:`syslog`,
``openlog()`` will be called with no arguments.
+ .. audit-event:: syslog.syslog priority,message syslog.syslog
+
.. function:: openlog([ident[, logoption[, facility]]])
@@ -45,6 +47,8 @@
keyword argument (default is :const:`LOG_USER`) sets the default facility for
messages which do not have a facility explicitly encoded.
+ .. audit-event:: syslog.openlog ident,logoption,facility syslog.openlog
+
.. versionchanged:: 3.2
In previous versions, keyword arguments were not allowed, and *ident* was
required. The default for *ident* was dependent on the system libraries,
@@ -60,6 +64,8 @@
:func:`openlog` hasn't already been called), and *ident* and other
:func:`openlog` parameters are reset to defaults.
+ .. audit-event:: syslog.closelog "" syslog.closelog
+
.. function:: setlogmask(maskpri)
@@ -70,6 +76,8 @@
``LOG_UPTO(pri)`` calculates the mask for all priorities up to and including
*pri*.
+ .. audit-event:: syslog.setlogmask maskpri syslog.setlogmask
+
The module defines the following constants:
Priority levels (high to low):