bpo-42800: audit hooks for frame and code attrs

* Accessing the following attributes will now fire PEP 578 style
  audit hooks as ("object.__getattr__", obj, name):
  * PyTracebackObject: tb_frame
  * PyFrameObject: f_code
  * PyGenObject: gi_code, gi_frame
  * PyCoroObject: cr_code, cr_frame
  * PyAsyncGenObject: ag_code, ag_frame

* Document audit hooks for tb_frame, f_code, and __code__
* Add an AUDIT_READ attribute flag aliased to READ_RESTRICTED.
* Update obsolete RESTRICTED flag documentation.

Author: lunixbochs

Doc/extending/newtypes.rst

@@ -287,11 +287,8 @@ combined using bitwise-OR.
 +===========================+==============================================+
 | :const:`READONLY`         | Never writable.                              |
 +---------------------------+----------------------------------------------+
-| :const:`READ_RESTRICTED`  | Not readable in restricted mode.             |
-+---------------------------+----------------------------------------------+
-| :const:`WRITE_RESTRICTED` | Not writable in restricted mode.             |
-+---------------------------+----------------------------------------------+
-| :const:`RESTRICTED`       | Not readable or writable in restricted mode. |
+| :const:`AUDIT_READ`       | Emit a :pep:`578` ``object.__getattr__``     |
+|                           | audit event before read.                     |
 +---------------------------+----------------------------------------------+
 
 .. index::

Doc/library/audit_events.rst

@@ -7,7 +7,7 @@ Audit events table
 
 This table contains all events raised by :func:`sys.audit` or
 :c:func:`PySys_Audit` calls throughout the CPython runtime and the
-standard library.  These calls were added in 3.8.0 or later.
+standard library.  These calls were added in 3.8.0 or later (see :pep:`578`).
 
 See :func:`sys.addaudithook` and :c:func:`PySys_AddAuditHook` for
 information on handling these events.

Doc/library/stdtypes.rst

@@ -5206,6 +5206,9 @@ environment.  Code objects are returned by the built-in :func:`compile` function
 and can be extracted from function objects through their :attr:`__code__`
 attribute. See also the :mod:`code` module.
 
+Accessing ``__code__`` raises an :ref:`auditing event <auditing>`
+``object.__getattr__`` with arguments ``obj`` and ``"__code__"``.
+
 .. index::
    builtin: exec
    builtin: eval

Doc/reference/datamodel.rst

@@ -1005,6 +1005,9 @@ Internal types
       :attr:`f_lasti` gives the precise instruction (this is an index into the
       bytecode string of the code object).
 
+      Accessing ``f_code`` raises an :ref:`auditing event <auditing>`
+      ``object.__getattr__`` with arguments ``obj`` and ``"f_code"``.
+
       .. index::
          single: f_trace (frame attribute)
          single: f_trace_lines (frame attribute)
@@ -1089,6 +1092,9 @@ Internal types
       :keyword:`try` statement with no matching except clause or with a
       finally clause.
 
+      Accessing ``tb_frame`` raises an :ref:`auditing event <auditing>`
+      ``object.__getattr__`` with arguments ``obj`` and ``"tb_frame"``.
+
       .. index::
          single: tb_next (traceback attribute)
 

Include/structmember.h

@@ -62,6 +62,7 @@ typedef struct PyMemberDef {
 #define PY_WRITE_RESTRICTED 4
 #define RESTRICTED          (READ_RESTRICTED | PY_WRITE_RESTRICTED)
 
+#define AUDIT_READ          READ_RESTRICTED
 
 /* Current API, use this */
 PyAPI_FUNC(PyObject *) PyMember_GetOne(const char *, struct PyMemberDef *);

Misc/ACKS

@@ -718,6 +718,7 @@ Kevan Heydon
 Wouter van Heyst
 Kelsey Hightower
 Jason Hildebrand
+Ryan Hileman
 Aaron Hill
 Joel Hillacre
 Richie Hindle

Misc/NEWS.d/next/Security/2021-01-09-17-07-36.bpo-42800._dtZvW.rst

@@ -0,0 +1 @@
+Audit hooks are now fired for frame.f_code, traceback.tb_frame, and generator code/frame attribute access.

Objects/descrobject.c

@@ -164,7 +164,7 @@ member_get(PyMemberDescrObject *descr, PyObject *obj, PyObject *type)
     if (descr_check((PyDescrObject *)descr, obj, &res))
         return res;
 
-    if (descr->d_member->flags & READ_RESTRICTED) {
+    if (descr->d_member->flags & AUDIT_READ) {
         if (PySys_Audit("object.__getattr__", "Os",
             obj ? obj : Py_None, descr->d_member->name) < 0) {
             return NULL;

Objects/frameobject.c

@@ -13,7 +13,7 @@
 
 static PyMemberDef frame_memberlist[] = {
     {"f_back",          T_OBJECT,       OFF(f_back),      READONLY},
-    {"f_code",          T_OBJECT,       OFF(f_code),      READONLY},
+    {"f_code",          T_OBJECT,       OFF(f_code),      READONLY|AUDIT_READ},
     {"f_builtins",      T_OBJECT,       OFF(f_builtins),  READONLY},
     {"f_globals",       T_OBJECT,       OFF(f_globals),   READONLY},
     {"f_lasti",         T_INT,          OFF(f_lasti),     READONLY},

Objects/genobject.c

@@ -756,8 +756,8 @@ static PyGetSetDef gen_getsetlist[] = {
 };
 
 static PyMemberDef gen_memberlist[] = {
-    {"gi_frame",     T_OBJECT, offsetof(PyGenObject, gi_frame),    READONLY},
-    {"gi_code",      T_OBJECT, offsetof(PyGenObject, gi_code),     READONLY},
+    {"gi_frame",     T_OBJECT, offsetof(PyGenObject, gi_frame),    READONLY|AUDIT_READ},
+    {"gi_code",      T_OBJECT, offsetof(PyGenObject, gi_code),     READONLY|AUDIT_READ},
     {NULL}      /* Sentinel */
 };
 
@@ -993,8 +993,8 @@ static PyGetSetDef coro_getsetlist[] = {
 };
 
 static PyMemberDef coro_memberlist[] = {
-    {"cr_frame",     T_OBJECT, offsetof(PyCoroObject, cr_frame),    READONLY},
-    {"cr_code",      T_OBJECT, offsetof(PyCoroObject, cr_code),     READONLY},
+    {"cr_frame",     T_OBJECT, offsetof(PyCoroObject, cr_frame),    READONLY|AUDIT_READ},
+    {"cr_code",      T_OBJECT, offsetof(PyCoroObject, cr_code),     READONLY|AUDIT_READ},
     {"cr_origin",    T_OBJECT, offsetof(PyCoroObject, cr_origin),   READONLY},
     {NULL}      /* Sentinel */
 };
@@ -1375,10 +1375,10 @@ static PyGetSetDef async_gen_getsetlist[] = {
 };
 
 static PyMemberDef async_gen_memberlist[] = {
-    {"ag_frame",   T_OBJECT, offsetof(PyAsyncGenObject, ag_frame),   READONLY},
+    {"ag_frame",   T_OBJECT, offsetof(PyAsyncGenObject, ag_frame),   READONLY|AUDIT_READ},
     {"ag_running", T_BOOL,   offsetof(PyAsyncGenObject, ag_running_async),
         READONLY},
-    {"ag_code",    T_OBJECT, offsetof(PyAsyncGenObject, ag_code),    READONLY},
+    {"ag_code",    T_OBJECT, offsetof(PyAsyncGenObject, ag_code),    READONLY|AUDIT_READ},
     {NULL}      /* Sentinel */
 };