[Python-checkins] bpo-41192: Add documentation of undocumented audit events (GH-21308)

[akuchling]

https://github.com/python/cpython/commit/3f7e990fd49dbabc1dde41ce58c1bdda9f56ead7
commit: 3f7e990fd49dbabc1dde41ce58c1bdda9f56ead7
branch: master
author: Saiyang Gou <gousaiyang at 163.com>
committer: akuchling <amk at amk.ca>
date: 2020-10-20T15:23:15-04:00
summary:

bpo-41192: Add documentation of undocumented audit events (GH-21308)

files:
M Doc/c-api/file.rst
M Doc/library/audit_events.rst
M Doc/library/functions.rst
M Doc/library/types.rst
M Doc/reference/datamodel.rst

diff --git a/Doc/c-api/file.rst b/Doc/c-api/file.rst
index ea027ee975c65..ed3735aa83608 100644
--- a/Doc/c-api/file.rst
+++ b/Doc/c-api/file.rst
@@ -82,6 +82,8 @@ the :mod:`io` APIs instead.
 
    This function is safe to call before :c:func:`Py_Initialize`.
 
+   .. audit-event:: setopencodehook "" c.PyFile_SetOpenCodeHook
+
    .. versionadded:: 3.8
 
 
diff --git a/Doc/library/audit_events.rst b/Doc/library/audit_events.rst
index 3c68a1515b3ef..367d56e4e3735 100644
--- a/Doc/library/audit_events.rst
+++ b/Doc/library/audit_events.rst
@@ -19,3 +19,29 @@ information on handling these events.
    specific documentation for actual events raised.
 
 .. audit-event-table::
+
+The following events are raised internally and do not correspond to any
+public API of CPython:
+
++--------------------------+-------------------------------------------+
+| Audit event              | Arguments                                 |
++==========================+===========================================+
+| _winapi.CreateFile       | ``file_name``, ``desired_access``,        |
+|                          | ``share_mode``, ``creation_disposition``, |
+|                          | ``flags_and_attributes``                  |
++--------------------------+-------------------------------------------+
+| _winapi.CreateJunction   | ``src_path``, ``dst_path``                |
++--------------------------+-------------------------------------------+
+| _winapi.CreateNamedPipe  | ``name``, ``open_mode``, ``pipe_mode``    |
++--------------------------+-------------------------------------------+
+| _winapi.CreatePipe       |                                           |
++--------------------------+-------------------------------------------+
+| _winapi.CreateProcess    | ``application_name``, ``command_line``,   |
+|                          | ``current_directory``                     |
++--------------------------+-------------------------------------------+
+| _winapi.OpenProcess      | ``process_id``, ``desired_access``        |
++--------------------------+-------------------------------------------+
+| _winapi.TerminateProcess | ``handle``, ``exit_code``                 |
++--------------------------+-------------------------------------------+
+| ctypes.PyObj_FromPtr     | ``obj``                                   |
++--------------------------+-------------------------------------------+
diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst
index a052e724c5ebe..b33aa81c643dc 100644
--- a/Doc/library/functions.rst
+++ b/Doc/library/functions.rst
@@ -783,6 +783,8 @@ are always available.  They are listed here in alphabetical order.
 
    .. impl-detail:: This is the address of the object in memory.
 
+   .. audit-event:: builtins.id id id
+
 
 .. function:: input([prompt])
 
diff --git a/Doc/library/types.rst b/Doc/library/types.rst
index e4a8dec5cb95a..a5cf9ab1344a3 100644
--- a/Doc/library/types.rst
+++ b/Doc/library/types.rst
@@ -116,6 +116,11 @@ Standard names are defined for the following types:
    The type of user-defined functions and functions created by
    :keyword:`lambda`  expressions.
 
+   .. audit-event:: function.__new__ code types.FunctionType
+
+   The audit event only occurs for direct instantiation of function objects,
+   and is not raised for normal compilation.
+
 
 .. data:: GeneratorType
 
@@ -145,10 +150,11 @@ Standard names are defined for the following types:
 
    The type for code objects such as returned by :func:`compile`.
 
-   .. audit-event:: code.__new__ code,filename,name,argcount,posonlyargcount,kwonlyargcount,nlocals,stacksize,flags CodeType
+   .. audit-event:: code.__new__ code,filename,name,argcount,posonlyargcount,kwonlyargcount,nlocals,stacksize,flags types.CodeType
 
    Note that the audited arguments may not match the names or positions
-   required by the initializer.
+   required by the initializer.  The audit event only occurs for direct
+   instantiation of code objects, and is not raised for normal compilation.
 
    .. method:: CodeType.replace(**kwargs)
 
diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst
index 4396f1b9b7299..29e64cba2ca3a 100644
--- a/Doc/reference/datamodel.rst
+++ b/Doc/reference/datamodel.rst
@@ -1540,6 +1540,12 @@ access (use of, assignment to, or deletion of ``x.name``) for class instances.
       result of implicit invocation via language syntax or built-in functions.
       See :ref:`special-lookup`.
 
+   .. audit-event:: object.__getattr__ obj,name object.__getattribute__
+
+      For certain sensitive attribute accesses, raises an
+      :ref:`auditing event <auditing>` ``object.__getattr__`` with arguments
+      ``obj`` and ``name``.
+
 
 .. method:: object.__setattr__(self, name, value)
 
@@ -1551,12 +1557,24 @@ access (use of, assignment to, or deletion of ``x.name``) for class instances.
    call the base class method with the same name, for example,
    ``object.__setattr__(self, name, value)``.
 
+   .. audit-event:: object.__setattr__ obj,name,value object.__setattr__
+
+      For certain sensitive attribute assignments, raises an
+      :ref:`auditing event <auditing>` ``object.__setattr__`` with arguments
+      ``obj``, ``name``, ``value``.
+
 
 .. method:: object.__delattr__(self, name)
 
    Like :meth:`__setattr__` but for attribute deletion instead of assignment.  This
    should only be implemented if ``del obj.name`` is meaningful for the object.
 
+   .. audit-event:: object.__delattr__ obj,name object.__delattr__
+
+      For certain sensitive attribute deletions, raises an
+      :ref:`auditing event <auditing>` ``object.__delattr__`` with arguments
+      ``obj`` and ``name``.
+
 
 .. method:: object.__dir__(self)