docs: explain hardening setting rationale

setup.py

@@ -18,32 +18,44 @@ STATE_FILENAME = 'original-values.json'
 
 # Intentionally limited machine-wide controls. Keep state-file paths in the
 # legacy PowerShell format so existing installations can roll back safely.
-#
-# SETTINGS entry parameters:
-#   Path  - HKLM registry key in the format accepted by _registry_path().
-#           These keys apply to the computer, rather than one signed-in user.
-#   Name  - exact Windows policy value name within that key.
-#   Value - desired integer REG_DWORD written by _write_value().
+# Purpose explains what the policy does; Rationale records why this package
+# applies it. These fields are descriptive and do not affect registry writes.
 SETTINGS = (
-    # Set the machine policy that disables AutoRun commands.
-    {'Path': r'HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\Explorer',
-     'Name': 'NoAutorun', 'Value': 1},
-
-    # Disable AutoPlay for every drive type (0xFF mask).
-    {'Path': r'HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\Explorer',
-     'Name': 'NoDriveTypeAutoRun', 'Value': 255},
-
-    # Disable AutoPlay for devices that do not expose a volume.
-    {'Path': r'HKLM:\SOFTWARE\Policies\Microsoft\Windows\Explorer',
-     'Name': 'NoAutoplayfornonVolume', 'Value': 1},
-
-    # Prevent use of the camera from the Windows lock screen.
-    {'Path': r'HKLM:\SOFTWARE\Policies\Microsoft\Windows\Personalization',
-     'Name': 'NoLockScreenCamera', 'Value': 1},
-
-    # Prevent enabling a slideshow on the Windows lock screen.
-    {'Path': r'HKLM:\SOFTWARE\Policies\Microsoft\Windows\Personalization',
-     'Name': 'NoLockScreenSlideshow', 'Value': 1},
+    {
+        'Path': r'HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\Explorer',
+        'Name': 'NoAutorun',
+        'Value': 1,
+        'Purpose': 'Disable AutoRun commands for the computer.',
+        'Rationale': 'AutoRun can launch commands associated with removable media. Disabling it reduces the chance that connecting media starts a command without an explicit user action.',
+    },
+    {
+        'Path': r'HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\Explorer',
+        'Name': 'NoDriveTypeAutoRun',
+        'Value': 255,
+        'Purpose': 'Disable AutoPlay for all drive types covered by the Windows policy mask.',
+        'Rationale': 'The 0xFF mask applies the policy to every drive type represented by this setting, reducing automatic handling of newly connected or mounted media.',
+    },
+    {
+        'Path': r'HKLM:\SOFTWARE\Policies\Microsoft\Windows\Explorer',
+        'Name': 'NoAutoplayfornonVolume',
+        'Value': 1,
+        'Purpose': 'Disable AutoPlay for devices that do not expose a volume.',
+        'Rationale': 'The drive-type policy does not cover every device category. This additional policy closes that gap for non-volume devices.',
+    },
+    {
+        'Path': r'HKLM:\SOFTWARE\Policies\Microsoft\Windows\Personalization',
+        'Name': 'NoLockScreenCamera',
+        'Value': 1,
+        'Purpose': 'Prevent camera use from the Windows lock screen.',
+        'Rationale': 'The camera remains unavailable from the lock screen, limiting access to this device feature before a user signs in.',
+    },
+    {
+        'Path': r'HKLM:\SOFTWARE\Policies\Microsoft\Windows\Personalization',
+        'Name': 'NoLockScreenSlideshow',
+        'Value': 1,
+        'Purpose': 'Prevent a slideshow from running on the Windows lock screen.',
+        'Rationale': 'This prevents lock-screen slideshow configuration, avoiding display of rotating images while the computer is locked.',
+    },
 )