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

(cherry picked from commit 3f7e990fd49dbabc1dde41ce58c1bdda9f56ead7)

diff --git a/Doc/c-api/file.rst b/Doc/c-api/file.rst
index ea027ee975c65159e9a1056c6551989c906114c3..ed3735aa83608a8545f906a909a0ae7d0a57fdc6 100644 (file)
--- 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 3c68a1515b3effbc4b5efef985f4f1ab87ebc833..367d56e4e37359cd04ee9def5abfb983be568a0f 100644 (file)
--- 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 6003898d5f6b8d06d3af3f8b040a540327ea1beb..76a0ba4b0c7667d39df13c2acc6104bcfd6777a9 100644 (file)
--- a/Doc/library/functions.rst
+++ b/Doc/library/functions.rst
@@ -767,6 +767,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 3529c2b0edb896630fdf6c9a78ddff033f9114b3..71d7a126ac320fc9f6babff06af9212e58c71676 100644 (file)
--- a/Doc/library/types.rst
+++ b/Doc/library/types.rst
@@ -109,6 +109,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
 
@@ -138,10 +143,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 924f6d9e2d7e0ca6dac07f80a5570d685bb3c7f3..c5d8f3a009bc5b5499e7113076e5d792c11f7c4e 100644 (file)
--- a/Doc/reference/datamodel.rst
+++ b/Doc/reference/datamodel.rst
@@ -1535,6 +1535,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)
 
@@ -1546,12 +1552,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)