bpo-39007: Add auditing events to functions in winreg (GH-17541)

zooba · web-flow · commit ee17e3735634 · 2019-12-09T11:18:12.000-08:00
Also allows winreg.CloseKey() to accept same types as other functions.
diff --git a/Doc/library/winreg.rst b/Doc/library/winreg.rst
@@ -53,6 +53,8 @@ This module offers the following functions:
    The return value is the handle of the opened key. If the function fails, an
    :exc:`OSError` exception is raised.
 
+   .. audit-event:: winreg.ConnectRegistry computer_name,key winreg.ConnectRegistry
+
    .. versionchanged:: 3.3
       See :ref:`above <exception-changed>`.
 
@@ -75,6 +77,10 @@ This module offers the following functions:
    The return value is the handle of the opened key. If the function fails, an
    :exc:`OSError` exception is raised.
 
+   .. audit-event:: winreg.CreateKey key,sub_key,access winreg.CreateKey
+
+   .. audit-event:: winreg.OpenKey/result key winreg.CreateKey
+
    .. versionchanged:: 3.3
       See :ref:`above <exception-changed>`.
 
@@ -103,6 +109,10 @@ This module offers the following functions:
    The return value is the handle of the opened key. If the function fails, an
    :exc:`OSError` exception is raised.
 
+   .. audit-event:: winreg.CreateKey key,sub_key,access winreg.CreateKeyEx
+
+   .. audit-event:: winreg.OpenKey/result key winreg.CreateKeyEx
+
    .. versionadded:: 3.2
 
    .. versionchanged:: 3.3
@@ -124,6 +134,8 @@ This module offers the following functions:
    If the method succeeds, the entire key, including all of its values, is removed.
    If the method fails, an :exc:`OSError` exception is raised.
 
+   .. audit-event:: winreg.DeleteKey key,sub_key,access winreg.DeleteKey
+
    .. versionchanged:: 3.3
       See :ref:`above <exception-changed>`.
 
@@ -158,6 +170,8 @@ This module offers the following functions:
 
    On unsupported Windows versions, :exc:`NotImplementedError` is raised.
 
+   .. audit-event:: winreg.DeleteKey key,sub_key,access winreg.DeleteKeyEx
+
    .. versionadded:: 3.2
 
    .. versionchanged:: 3.3
@@ -173,6 +187,8 @@ This module offers the following functions:
 
    *value* is a string that identifies the value to remove.
 
+   .. audit-event:: winreg.DeleteValue key,value winreg.DeleteValue
+
 
 .. function:: EnumKey(key, index)
 
@@ -187,6 +203,8 @@ This module offers the following functions:
    typically called repeatedly until an :exc:`OSError` exception is
    raised, indicating, no more values are available.
 
+   .. audit-event:: winreg.EnumKey key,index winreg.EnumKey
+
    .. versionchanged:: 3.3
       See :ref:`above <exception-changed>`.
 
@@ -220,6 +238,8 @@ This module offers the following functions:
    |       | :meth:`SetValueEx`)                        |
    +-------+--------------------------------------------+
 
+   .. audit-event:: winreg.EnumValue key,index winreg.EnumValue
+
    .. versionchanged:: 3.3
       See :ref:`above <exception-changed>`.
 
@@ -235,6 +255,8 @@ This module offers the following functions:
       >>> ExpandEnvironmentStrings('%windir%')
       'C:\\Windows'
 
+   .. audit-event:: winreg.ExpandEnvironmentStrings str winreg.ExpandEnvironmentStrings
+
 
 .. function:: FlushKey(key)
 
@@ -279,6 +301,8 @@ This module offers the following functions:
    If *key* is a handle returned by :func:`ConnectRegistry`, then the path
    specified in *file_name* is relative to the remote computer.
 
+   .. audit-event:: winreg.LoadKey key,sub_key,file_name winreg.LoadKey
+
 
 .. function:: OpenKey(key, sub_key, reserved=0, access=KEY_READ)
               OpenKeyEx(key, sub_key, reserved=0, access=KEY_READ)
@@ -300,6 +324,10 @@ This module offers the following functions:
 
    If the function fails, :exc:`OSError` is raised.
 
+   .. audit-event:: winreg.OpenKey key,sub_key,access winreg.OpenKey
+
+   .. audit-event:: winreg.OpenKey/result key winreg.OpenKey
+
    .. versionchanged:: 3.2
       Allow the use of named arguments.
 
@@ -330,6 +358,8 @@ This module offers the following functions:
    |       | nanoseconds since Jan 1, 1601.              |
    +-------+---------------------------------------------+
 
+   .. audit-event:: winreg.QueryInfoKey key winreg.QueryInfoKey
+
 
 .. function:: QueryValue(key, sub_key)
 
@@ -347,6 +377,8 @@ This module offers the following functions:
    underlying API call doesn't return the type, so always use
    :func:`QueryValueEx` if possible.
 
+   .. audit-event:: winreg.QueryValue key,sub_key,value_name winreg.QueryValue
+
 
 .. function:: QueryValueEx(key, value_name)
 
@@ -370,6 +402,8 @@ This module offers the following functions:
    |       | :meth:`SetValueEx`)                     |
    +-------+-----------------------------------------+
 
+   .. audit-event:: winreg.QueryValue key,sub_key,value_name winreg.QueryValueEx
+
 
 .. function:: SaveKey(key, file_name)
 
@@ -393,6 +427,8 @@ This module offers the following functions:
 
    This function passes ``NULL`` for *security_attributes* to the API.
 
+   .. audit-event:: winreg.SaveKey key,file_name winreg.SaveKey
+
 
 .. function:: SetValue(key, sub_key, type, value)
 
@@ -419,6 +455,8 @@ This module offers the following functions:
    The key identified by the *key* parameter must have been opened with
    :const:`KEY_SET_VALUE` access.
 
+   .. audit-event:: winreg.SetValue key,sub_key,type,value winreg.SetValue
+
 
 .. function:: SetValueEx(key, value_name, reserved, type, value)
 
@@ -447,6 +485,8 @@ This module offers the following functions:
    bytes) should be stored as files with the filenames stored in the configuration
    registry.  This helps the registry perform efficiently.
 
+   .. audit-event:: winreg.SetValue key,sub_key,type,value winreg.SetValueEx
+
 
 .. function:: DisableReflectionKey(key)
 
@@ -463,6 +503,8 @@ This module offers the following functions:
    effect.  Disabling reflection for a key does not affect reflection of any
    subkeys.
 
+   .. audit-event:: winreg.DisableReflectionKey key winreg.DisableReflectionKey
+
 
 .. function:: EnableReflectionKey(key)
 
@@ -476,6 +518,8 @@ This module offers the following functions:
 
    Restoring reflection for a key does not affect reflection of any subkeys.
 
+   .. audit-event:: winreg.EnableReflectionKey key winreg.EnableReflectionKey
+
 
 .. function:: QueryReflectionKey(key)
 
@@ -489,6 +533,8 @@ This module offers the following functions:
    Will generally raise :exc:`NotImplementedError` if executed on a 32-bit
    operating system.
 
+   .. audit-event:: winreg.QueryReflectionKey key winreg.QueryReflectionKey
+
 
 .. _constants:
 
@@ -741,6 +787,9 @@ integer handle, and also disconnect the Windows handle from the handle object.
    handle is not closed.  You would call this function when you need the
    underlying Win32 handle to exist beyond the lifetime of the handle object.
 
+   .. audit-event:: winreg.PyHKEY.Detach key winreg.PyHKEY.Detach
+
+
 .. method:: PyHKEY.__enter__()
             PyHKEY.__exit__(\*exc_info)
 
diff --git a/Lib/test/audit-tests.py b/Lib/test/audit-tests.py
@@ -304,6 +304,29 @@ def hook(event, args):
     write_unraisable_exc(RuntimeError("nonfatal-error"), "for audit hook test", None)
 
 
+def test_winreg():
+    from winreg import OpenKey, EnumKey, CloseKey, HKEY_LOCAL_MACHINE
+
+    def hook(event, args):
+        if not event.startswith("winreg."):
+            return
+        print(event, *args)
+
+    sys.addaudithook(hook)
+
+    k = OpenKey(HKEY_LOCAL_MACHINE, "Software")
+    EnumKey(k, 0)
+    try:
+        EnumKey(k, 10000)
+    except OSError:
+        pass
+    else:
+        raise RuntimeError("Expected EnumKey(HKLM, 10000) to fail")
+
+    kv = k.Detach()
+    CloseKey(kv)
+
+
 if __name__ == "__main__":
     from test.libregrtest.setup import suppress_msvcrt_asserts
 
diff --git a/Lib/test/test_audit.py b/Lib/test/test_audit.py
@@ -104,6 +104,20 @@ def test_unraisablehook(self):
             "RuntimeError('nonfatal-error') Exception ignored for audit hook test",
         )
 
+    def test_winreg(self):
+        support.import_module("winreg")
+        returncode, events, stderr = self.run_python("test_winreg")
+        if returncode:
+            self.fail(stderr)
+
+        self.assertEqual(events[0][0], "winreg.OpenKey")
+        self.assertEqual(events[1][0], "winreg.OpenKey/result")
+        expected = events[1][2]
+        self.assertTrue(expected)
+        self.assertSequenceEqual(["winreg.EnumKey", " ", f"{expected} 0"], events[2])
+        self.assertSequenceEqual(["winreg.EnumKey", " ", f"{expected} 10000"], events[3])
+        self.assertSequenceEqual(["winreg.PyHKEY.Detach", " ", expected], events[4])
+
 
 if __name__ == "__main__":
     unittest.main()
diff --git a/Misc/NEWS.d/next/Windows/2019-12-09-10-40-34.bpo-39007.vtarxo.rst b/Misc/NEWS.d/next/Windows/2019-12-09-10-40-34.bpo-39007.vtarxo.rst
@@ -0,0 +1 @@
+Add auditing events to functions in :mod:`winreg`.
diff --git a/PC/winreg.c b/PC/winreg.c

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	+Add auditing events to functions in :mod:`winreg`.