docs: explain hardening setting rationale

README.md

@@ -8,7 +8,7 @@ Five HKLM registry settings: disable AutoRun and AutoPlay (including non-volume
 ## Implementation
 - `setup.py` now contains the complete install, audit and conditional rollback logic.
 - Registry reads and writes use WAPT 2.6 `setuphelpers` (`reg_key_exists`, `reg_value_exists`, `reg_openkey_noredir`, `reg_getvalue`, `registry_set`, and `reg_delvalue`). No PowerShell process or external command is launched.
-- The approved setting table is centralized in `SETTINGS`. A future `update_package.py` can validate operator-selected settings and serialize them as package data; this refactor keeps the current five-setting policy fixed.
+- The approved setting table is centralized in `SETTINGS`. Each dictionary documents `Path`, `Name`, `Value`, `Purpose` and `Rationale`, so maintainers can see both the exact registry operation and why the policy is included. A future `update_package.py` can validate operator-selected settings and serialize them as package data; the current five-setting policy remains fixed.
 - If a future package configuration changes a setting’s target, its update flow must migrate the saved uninstall target while preserving the original pre-install value. That migration is not part of this refactor.
 - The WAPT package source currently has no `WAPT/control` or `update_package.py`; it is code-only and is not yet a complete buildable WAPT package.
 

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.
-#
+# Purpose explains what the policy does; Rationale records why this package
-# SETTINGS entry parameters:
+# applies it. These fields are descriptive and do not affect registry writes.
-#   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().
 SETTINGS = (
-    # Set the machine policy that disables AutoRun commands.
+    {
-    {'Path': r'HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\Explorer',
+        'Path': r'HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\Explorer',
-     'Name': 'NoAutorun', 'Value': 1},
+        'Name': 'NoAutorun',
-
+        'Value': 1,
-    # Disable AutoPlay for every drive type (0xFF mask).
+        'Purpose': 'Disable AutoRun commands for the computer.',
-    {'Path': r'HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\Explorer',
+        '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.',
-     'Name': 'NoDriveTypeAutoRun', 'Value': 255},
+    },
-
+    {
-    # Disable AutoPlay for devices that do not expose a volume.
+        'Path': r'HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\Explorer',
-    {'Path': r'HKLM:\SOFTWARE\Policies\Microsoft\Windows\Explorer',
+        'Name': 'NoDriveTypeAutoRun',
-     'Name': 'NoAutoplayfornonVolume', 'Value': 1},
+        'Value': 255,
-
+        'Purpose': 'Disable AutoPlay for all drive types covered by the Windows policy mask.',
-    # Prevent use of the camera from the Windows lock screen.
+        '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\Personalization',
+    },
-     'Name': 'NoLockScreenCamera', 'Value': 1},
+    {
-
+        'Path': r'HKLM:\SOFTWARE\Policies\Microsoft\Windows\Explorer',
-    # Prevent enabling a slideshow on the Windows lock screen.
+        'Name': 'NoAutoplayfornonVolume',
-    {'Path': r'HKLM:\SOFTWARE\Policies\Microsoft\Windows\Personalization',
+        'Value': 1,
-     'Name': 'NoLockScreenSlideshow', '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.',
+    },
 )