bpo-37363: Add audit events for a range of modules

python · zooba · Jun 24, 2019 · Jun 21, 2019 · Jun 22, 2019 · Jun 22, 2019
commit 600548904c2953a0bb039911586658a3b2810287
diff --git a/Doc/library/ctypes.rst b/Doc/library/ctypes.rst
@@ -2046,7 +2046,7 @@ Data types
       .. audit-event:: ctypes.cdata address
 
          This method, and others that indirectly call this method, raises an
-         :func:`auditing event <sys.audit>` ``ctypes.cdata`` with argument
+         :ref:`auditing event <auditing>` ``ctypes.cdata`` with argument
          ``address``.
 
    .. method:: from_param(obj)

diff --git a/Doc/library/ensurepip.rst b/Doc/library/ensurepip.rst
@@ -119,6 +119,8 @@ Module API
    *verbosity* controls the level of output to :data:`sys.stdout` from the
    bootstrapping operation.
 
+   .. audit-event:: ensurepip.bootstrap root
+
    .. note::
 
       The bootstrapping process has side effects on both ``sys.path`` and

diff --git a/Doc/library/ftplib.rst b/Doc/library/ftplib.rst
@@ -190,6 +190,8 @@ followed by ``lines`` for the text version or ``binary`` for the binary version.
    *source_address* is a 2-tuple ``(host, port)`` for the socket to bind to as
    its source address before connecting.
 
+   .. audit-event:: ftplib.FTP.connect "self host port"
+
    .. versionchanged:: 3.3
       *source_address* parameter was added.
 
@@ -223,13 +225,17 @@ followed by ``lines`` for the text version or ``binary`` for the binary version.
 
    Send a simple command string to the server and return the response string.
 
+   .. audit-event:: ftplib.FTP.sendcmd "self cmd"
+
 
 .. method:: FTP.voidcmd(cmd)
 
    Send a simple command string to the server and handle the response.  Return
    nothing if a response code corresponding to success (codes in the range
    200--299) is received.  Raise :exc:`error_reply` otherwise.
 
+   .. audit-event:: ftplib.FTP.sendcmd "self cmd"
+
 
 .. method:: FTP.retrbinary(cmd, callback, blocksize=8192, rest=None)
 

diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst
@@ -277,7 +277,7 @@ are always available.  They are listed here in alphabetical order.
 
    .. audit-event:: compile "source filename"
 
-      Raises an :func:`auditing event <sys.audit>` ``compile`` with arguments
+      Raises an :ref:`auditing event <auditing>` ``compile`` with arguments
       ``source`` and ``filename``. This event may also be raised by implicit
       compilation.
 
@@ -490,8 +490,8 @@ are always available.  They are listed here in alphabetical order.
 
    .. audit-event:: exec code_object
 
-      Raises an :func:`auditing event <sys.audit>` ``exec`` with the code object as
-      the argument. Code compilation events may also be raised.
+      Raises an :ref:`auditing event <auditing>` ``exec`` with the code object
+      as the argument. Code compilation events may also be raised.
 
 .. index:: builtin: exec
 
@@ -525,8 +525,8 @@ are always available.  They are listed here in alphabetical order.
 
    .. audit-event:: exec code_object
 
-      Raises an :func:`auditing event <sys.audit>` ``exec`` with the code object as
-      the argument. Code compilation events may also be raised.
+      Raises an :ref:`auditing event <auditing>` ``exec`` with the code object
+      as the argument. Code compilation events may also be raised.
 
    .. note::
 
@@ -779,7 +779,7 @@ are always available.  They are listed here in alphabetical order.
 
    .. audit-event:: builtins.input prompt
 
-      Raises an :func:`auditing event <sys.audit>` ``builtins.input`` with
+      Raises an :ref:`auditing event <auditing>` ``builtins.input`` with
       argument ``prompt`` before reading input
 
    .. audit-event:: builtins.input/result result

diff --git a/Doc/library/glob.rst b/Doc/library/glob.rst
@@ -52,6 +52,8 @@ For example, ``'[?]'`` matches the character ``'?'``.
    more directories and subdirectories.  If the pattern is followed by an
    ``os.sep``, only directories and subdirectories match.
 
+   .. audit-event:: glob.glob "pathname recursive"
+
    .. note::
       Using the "``**``" pattern in large directory trees may consume
       an inordinate amount of time.
@@ -65,6 +67,8 @@ For example, ``'[?]'`` matches the character ``'?'``.
    Return an :term:`iterator` which yields the same values as :func:`glob`
    without actually storing them all simultaneously.
 
+   .. audit-event:: glob.glob "pathname recursive"
+
 
 .. function:: escape(pathname)
 

diff --git a/Doc/library/imaplib.rst b/Doc/library/imaplib.rst
@@ -361,6 +361,8 @@ An :class:`IMAP4` instance has the following methods:
    :meth:`IMAP4.send`, and :meth:`IMAP4.shutdown` methods.  You may override
    this method.
 
+   ..audit-event:: imaplib.IMAP4.open "self host port"
+
 
 .. method:: IMAP4.partial(message_num, message_part, start, length)
 
@@ -430,6 +432,8 @@ An :class:`IMAP4` instance has the following methods:
 
    Sends ``data`` to the remote server. You may override this method.
 
+   .. audit-event:: imaplib.IMAP4.send "self data"
+
 
 .. method:: IMAP4.setacl(mailbox, who, what)
 

diff --git a/Doc/library/io.rst b/Doc/library/io.rst
@@ -122,7 +122,7 @@ High-level Module Interface
 
    .. audit-event:: open "path mode flags"
 
-      This function raises an :func:`auditing event <sys.audit>` ``open`` with
+      This function raises an :ref:`auditing event <auditing>` ``open`` with
       arguments ``path``, ``mode`` and ``flags``. The ``mode`` and ``flags``
       arguments may have been modified or inferred from the original call.
 

diff --git a/Doc/library/nntplib.rst b/Doc/library/nntplib.rst
@@ -79,6 +79,11 @@ The module itself defines the following classes:
     ('211 1755 1 1755 gmane.comp.python.committers', 1755, 1, 1755, 'gmane.comp.python.committers')
     >>>
 
+   .. audit-event:: nntplib.NNTP "self host port"
+
+   All commands will raise an :ref:`auditing event <auditing>`
+   ``nntplib.NNTP.putline`` with arguments ``self`` and ``line``,
+   where ``line`` is the bytes about to be sent to the remote host.
 
    .. versionchanged:: 3.2
       *usenetrc* is now ``False`` by default.
@@ -100,6 +105,12 @@ The module itself defines the following classes:
    STARTTLS as described below.  However, some servers only support the
    former.
 
+   .. audit-event:: nntplib.NNTP "self host port"
+
+   All commands will raise an :ref:`auditing event <auditing>`
+   ``nntplib.NNTP.putline`` with arguments ``self`` and ``line``,
+   where ``line`` is the bytes about to be sent to the remote host.
+
    .. versionadded:: 3.2
 
    .. versionchanged:: 3.4

diff --git a/Doc/library/os.rst b/Doc/library/os.rst
@@ -1801,6 +1801,8 @@ features:
    This function can also support :ref:`specifying a file descriptor
    <path_fd>`; the file descriptor must refer to a directory.
 
+   .. audit-event:: os.listdir path
+
    .. note::
       To encode ``str`` filenames to ``bytes``, use :func:`~os.fsencode`.
 
@@ -2178,6 +2180,8 @@ features:
    This function can also support :ref:`specifying a file descriptor
    <path_fd>`; the file descriptor must refer to a directory.
 
+   .. audit-event:: os.scandir path
+
    The :func:`scandir` iterator supports the :term:`context manager` protocol
    and has the following method:
 

diff --git a/Doc/library/poplib.rst b/Doc/library/poplib.rst
@@ -39,6 +39,12 @@ The :mod:`poplib` module provides two classes:
    connection attempt (if not specified, the global default timeout setting will
    be used).
 
+   .. audit-event:: poplib.POP3 "self host port"
+
+   All commands will raise an :ref:`auditing event <auditing>`
+   ``poplib.POP3.putline`` with arguments ``self`` and ``line``,
+   where ``line`` is the bytes about to be sent to the remote host.
+
 
 .. class:: POP3_SSL(host, port=POP3_SSL_PORT, keyfile=None, certfile=None, timeout=None, context=None)
 
@@ -54,6 +60,12 @@ The :mod:`poplib` module provides two classes:
    point to PEM-formatted private key and certificate chain files,
    respectively, for the SSL connection.
 
+   .. audit-event:: poplib.POP3 "self host port"
+
+   All commands will raise an :ref:`auditing event <auditing>`
+   ``poplib.POP3.putline`` with arguments ``self`` and ``line``,
+   where ``line`` is the bytes about to be sent to the remote host.
+
    .. versionchanged:: 3.2
       *context* parameter added.
 

diff --git a/Doc/library/smtplib.rst b/Doc/library/smtplib.rst
@@ -55,6 +55,10 @@ Protocol) and :rfc:`1869` (SMTP Service Extensions).
     (250, b'Ok')
     >>>
 
+   All commands will raise an :ref:`auditing event <auditing>`
+   ``smtplib.SMTP.send`` with arguments ``self`` and ``data``,
+   where ``data`` is the bytes about to be sent to the remote host.
+
    .. versionchanged:: 3.3
       Support for the :keyword:`with` statement was added.
 
@@ -242,6 +246,8 @@ An :class:`SMTP` instance has the following methods:
    2-tuple of the response code and message sent by the server in its
    connection response.
 
+   .. audit-event:: smtplib.SMTP.connect "self host port"
+
 
 .. method:: SMTP.helo(name='')
 

diff --git a/Doc/library/subprocess.rst b/Doc/library/subprocess.rst
@@ -585,6 +585,13 @@ functions.
       with Popen(["ifconfig"], stdout=PIPE) as proc:
           log.write(proc.stdout.read())
 
+   .. audit-event:: subprocess.Popen "executable args cwd env"
+
+      Popen and the other functions in this module that use it raise an
+      :ref:`auditing event <auditing>` ``subprocess.Popen`` with arguments
+      ``executable``, ``args``, ``cwd``, ``env``. The value for ``args``
+      may be a single string or a list of strings, depending on platform.
+
    .. versionchanged:: 3.2
       Added context manager support.
 

diff --git a/Doc/library/telnetlib.rst b/Doc/library/telnetlib.rst
@@ -141,6 +141,8 @@ Telnet Objects
 
    Do not try to reopen an already connected instance.
 
+   .. audit-event:: telnetlib.Telnet.open "self host port"
+
 
 .. method:: Telnet.msg(msg, *args)
 
@@ -176,6 +178,8 @@ Telnet Objects
    block if the connection is blocked.  May raise :exc:`OSError` if the
    connection is closed.
 
+   .. audit-event:: telnetlib.Telnet.write "self buffer"
+
    .. versionchanged:: 3.3
       This method used to raise :exc:`socket.error`, which is now an alias
       of :exc:`OSError`.

diff --git a/Doc/library/tempfile.rst b/Doc/library/tempfile.rst
@@ -62,6 +62,8 @@ The module defines the following user-callable items:
    The :py:data:`os.O_TMPFILE` flag is used if it is available and works
    (Linux-specific, requires Linux kernel 3.11 or later).
 
+   .. audit-event:: tempfile.mkstemp "full-path"
+
    .. versionchanged:: 3.5
 
       The :py:data:`os.O_TMPFILE` flag is now used if available.
@@ -85,6 +87,8 @@ The module defines the following user-callable items:
    attribute is the underlying true file object. This file-like object can
    be used in a :keyword:`with` statement, just like a normal file.
 
+   .. audit-event:: tempfile.mkstemp "full-path"
+
    .. versionchanged:: 3.8
       Added *errors* parameter.
 
@@ -130,6 +134,8 @@ The module defines the following user-callable items:
    The directory can be explicitly cleaned up by calling the
    :func:`cleanup` method.
 
+   .. audit-event:: tempfile.mkdtemp "full-path"
+
    .. versionadded:: 3.2
 
 
@@ -177,6 +183,8 @@ The module defines the following user-callable items:
    file (as would be returned by :func:`os.open`) and the absolute pathname
    of that file, in that order.
 
+   .. audit-event:: tempfile.mkstemp "full-path"
+
    .. versionchanged:: 3.5
       *suffix*, *prefix*, and *dir* may now be supplied in bytes in order to
       obtain a bytes return value.  Prior to this, only str was allowed.
@@ -198,6 +206,8 @@ The module defines the following user-callable items:
 
    :func:`mkdtemp` returns the absolute pathname of the new directory.
 
+   .. audit-event:: tempfile.mkdtemp "full-path"
+
    .. versionchanged:: 3.5
       *suffix*, *prefix*, and *dir* may now be supplied in bytes in order to
       obtain a bytes return value.  Prior to this, only str was allowed.

diff --git a/Doc/library/urllib.request.rst b/Doc/library/urllib.request.rst
@@ -97,7 +97,7 @@ The :mod:`urllib.request` module defines the following functions:
 
    .. audit-event:: urllib.Request "fullurl data headers method"
 
-      The default opener raises an :func:`auditing event <sys.audit>`
+      The default opener raises an :ref:`auditing event <auditing>`
       ``urllib.Request`` with arguments ``fullurl``, ``data``, ``headers``,
       ``method`` taken from the request object.
 

diff --git a/Doc/library/webbrowser.rst b/Doc/library/webbrowser.rst
@@ -64,6 +64,8 @@ The following functions are defined:
    may work and start the operating system's associated program.  However, this
    is neither supported no
1E0A
r portable.
 
+   .. audit-event:: webbrowser.open "url"
+
 
 .. function:: open_new(url)
 

diff --git a/Lib/ensurepip/__init__.py b/Lib/ensurepip/__init__.py
@@ -73,6 +73,8 @@ def _bootstrap(*, root=None, upgrade=False, user=False,
     if altinstall and default_pip:
         raise ValueError("Cannot use altinstall and default_pip together")
 
+    sys.audit("ensurepip.bootstrap", root)
+
     _disable_pip_configuration_settings()
 
     # By default, installing pip and setuptools installs all of the

diff --git a/Lib/ftplib.py b/Lib/ftplib.py
@@ -148,6 +148,7 @@ def connect(self, host='', port=0, timeout=-999, source_address=None):
             self.timeout = timeout
         if source_address is not None:
             self.source_address = source_address
+        sys.audit("ftplib.FTP.connect", self, self.host, self.port)
         self.sock = socket.create_connection((self.host, self.port), self.timeout,
                                              source_address=self.source_address)
         self.af = self.sock.family
@@ -188,6 +189,7 @@ def sanitize(self, s):
     def putline(self, line):
         if '\r' in line or '\n' in line:
             raise ValueError('an illegal newline character should not be contained')
+        sys.audit("ftplib.FTP.sendcmd", self, line)
         line = line + CRLF
         if self.debugging > 1:
             print('*put*', self.sanitize(line))

diff --git a/Lib/glob.py b/Lib/glob.py
@@ -3,6 +3,7 @@
 import os
 import re
 import fnmatch
+import sys
 
 __all__ = ["glob", "iglob", "escape"]
 
@@ -37,6 +38,7 @@ def iglob(pathname, *, recursive=False):
     return it
 
 def _iglob(pathname, recursive, dironly):
+    sys.audit("glob.glob", pathname, recursive)
     dirname, basename = os.path.split(pathname)
     if not has_magic(pathname):
         assert not dironly

diff --git a/Lib/imaplib.py b/Lib/imaplib.py
@@ -289,6 +289,7 @@ def _create_socket(self):
         # (which is used by socket.create_connection()) expects None
         # as a default value for host.
         host = None if not self.host else self.host
+        sys.audit("imaplib.IMAP4.open", self, self.host, self.port)
         return socket.create_connection((host, self.port))
 
     def open(self, host = '', port = IMAP4_PORT):
@@ -318,6 +319,7 @@ def readline(self):
 
     def send(self, data):
         """Send data to remote."""
+        sys.audit("imaplib.IMAP4.send", self, data)
         self.sock.sendall(data)