From: Miss Skeleton (bot) <31488909+miss-islington@users.noreply.github.com> Date: Tue, 20 Oct 2020 20:05:13 +0000 (-0700) Subject: bpo-41192: Add documentation of undocumented audit events (GH-22831) X-Git-Tag: v3.9.1rc1~134 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=46130f85381f697dc7f609b2659cc046d2370417;p=thirdparty%2FPython%2Fcpython.git bpo-41192: Add documentation of undocumented audit events (GH-22831) (cherry picked from commit 3f7e990fd49dbabc1dde41ce58c1bdda9f56ead7) --- diff --git a/Doc/c-api/file.rst b/Doc/c-api/file.rst index ea027ee975c6..ed3735aa8360 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 3c68a1515b3e..367d56e4e373 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 101d118291d7..ca6dabfcddda 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -766,6 +766,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 79acdf4499af..a88e882305ff 100644 --- 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 354c6ce53f76..aaa161aad277 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 ` ``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 ` ``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 ` ``object.__delattr__`` with arguments + ``obj`` and ``name``. + .. method:: object.__dir__(self)