docs: explain hardening setting rationale

Reviewed-on: #1

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

@@ -11,22 +11,51 @@ import os
 
 uninstallkey = []
 
+# Relative subdirectories under ProgramData used for this package's rollback state.
 STATE_DIRECTORY = ('Comitari', 'HardeningSafe')
+# Stores original registry values plus their package target for conditional rollback.
 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
+# applies it. These fields are descriptive and do not affect registry writes.
 SETTINGS = (
-    {'Path': r'HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\Explorer',
-     'Name': 'NoAutorun', 'Value': 1},
-    {'Path': r'HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\Explorer',
-     'Name': 'NoDriveTypeAutoRun', 'Value': 255},
-    {'Path': r'HKLM:\SOFTWARE\Policies\Microsoft\Windows\Explorer',
-     'Name': 'NoAutoplayfornonVolume', 'Value': 1},
-    {'Path': r'HKLM:\SOFTWARE\Policies\Microsoft\Windows\Personalization',
-     'Name': 'NoLockScreenCamera', 'Value': 1},
-    {'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.',
+    },
 )
 
 
@@ -46,10 +75,11 @@ def _read_value(path, name):
     subkey = _registry_path(path)
     if not reg_key_exists(HKEY_LOCAL_MACHINE, subkey):
         return {'Exists': False, 'Value': None}
-    if not reg_value_exists(HKEY_LOCAL_MACHINE, subkey, name):
-        return {'Exists': False, 'Value': None}
+    missing = object()
     with reg_openkey_noredir(HKEY_LOCAL_MACHINE, subkey) as key:
-        value = reg_getvalue(key, name)
+        value = reg_getvalue(key, name, default=missing)
+    if value is missing:
+        return {'Exists': False, 'Value': None}
     if value is None:
         raise RuntimeError('Registry value disappeared while it was being read: %s' % name)
     try: