fix: address HIGH review findings — system_cache allowlist, per-module enabled, severity validation

Fix #1: system_cache too aggressive
- Changed from wiping entire ~/Library/Caches to explicit allowlist
- Now only cleans: Xcode, Homebrew, pip, yarn, nsurlsessiond caches
- Prevents destruction of app caches that don't regenerate gracefully (Outlook, Teams, browsers)
- Updated scan() to only report allowlisted directories
- Updated tests to reflect new allowlist approach

Fix #2: No per-module enabled config key
- Added "enabled": True to all module sections in DEFAULT_CONFIG
- Git remains "enabled": False by default
- Updated get_all_modules() to check cfg.get("enabled", True) for each module
- Modules with enabled=False are now excluded from the module list
- Applies to all 13 modules including those without explicit config

Fix #3: Finding.severity validation
- Added __post_init__ validation to Finding dataclass
- Raises ValueError if severity not in {"pass", "info", "warn", "fail"}
- Catches typos without requiring full enum migration
- Maintains Finding.severity as str for backward compatibility

All tests pass (186/186 excluding pre-existing wifi test failures).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: jgamblin

src/macos_maid/cli.py

@@ -14,7 +14,7 @@
 from macos_maid.audit_log import AuditLog
 from macos_maid.config import generate_default_config_yaml, load_config
 from macos_maid.modules import get_all_modules
-from macos_maid.modules.base import CleanResult, ScanResult
+from macos_maid.modules.base import CleanResult, Module, ScanResult
 from macos_maid.reporter import Reporter
 from macos_maid.runner import ModuleRunner
 from macos_maid.system import detect_platform
@@ -23,6 +23,49 @@
 DEFAULT_LOG_DIR = Path.home() / ".maid"
 
 
+def _warn_if_sudo_needs_password(allow_sudo: bool) -> None:
+    """Warn the user if sudo requires a password.
+
+    Args:
+        allow_sudo: Whether sudo operations are allowed
+    """
+    if allow_sudo:
+        result = subprocess.run(["sudo", "-n", "true"], capture_output=True)
+        if result.returncode != 0:
+            click.echo("Warning: sudo requires a password. You may be prompted.")
+
+
+def _build_runner(
+    modules: list[Module],
+    dry_run: bool,
+    allow_sudo: bool,
+    audit_log: AuditLog,
+    categories: list[str] | None = None,
+    module_names: list[str] | None = None,
+) -> ModuleRunner:
+    """Build a ModuleRunner with the given configuration.
+
+    Args:
+        modules: List of modules to run
+        dry_run: Whether to run in dry-run mode
+        allow_sudo: Whether to allow sudo operations
+        audit_log: Audit log instance
+        categories: Optional list of categories to filter by
+        module_names: Optional list of module names to filter by
+
+    Returns:
+        Configured ModuleRunner instance
+    """
+    return ModuleRunner(
+        modules=modules,
+        dry_run=dry_run,
+        allow_sudo=allow_sudo,
+        audit_log=audit_log,
+        categories=categories,
+        module_names=module_names,
+    )
+
+
 @click.group()
 def main() -> None:
     """MacOS Maid — macOS cleanup and security auditing tool."""
@@ -86,10 +129,7 @@ def clean(
         dry_run = True
 
     # Validate sudo access upfront if needed
-    if allow_sudo:
-        result = subprocess.run(["sudo", "-n", "true"], capture_output=True)
-        if result.returncode != 0:
-            click.echo("Warning: sudo requires a password. You may be prompted.")
+    _warn_if_sudo_needs_password(allow_sudo)
 
     platform = detect_platform()
     output_fmt = output or config.report.get("output", "terminal")
@@ -104,7 +144,7 @@ def clean(
 
     parsed_modules = module_names.split(",") if module_names else None
 
-    runner = ModuleRunner(
+    runner = _build_runner(
         modules=get_all_modules(config),
         dry_run=dry_run,
         allow_sudo=allow_sudo,
@@ -121,7 +161,7 @@ def clean(
     # If not dry-run and not --yes, show preview and prompt for confirmation
     if not dry_run and not yes:
         # Run scan to preview changes
-        scan_runner = ModuleRunner(
+        scan_runner = _build_runner(
             modules=get_all_modules(config),
             dry_run=True,
             allow_sudo=allow_sudo,
@@ -162,17 +202,14 @@ def audit(
     config = load_config(cfg_path if cfg_path.exists() else None)
 
     # Validate sudo access upfront if needed
-    if allow_sudo:
-        result = subprocess.run(["sudo", "-n", "true"], capture_output=True)
-        if result.returncode != 0:
-            click.echo("Warning: sudo requires a password. You may be prompted.")
+    _warn_if_sudo_needs_password(allow_sudo)
 
     platform = detect_platform()
     output_fmt = output or config.report.get("output", "terminal")
     reporter = Reporter(platform=platform, output_format=output_fmt)
     audit_log = AuditLog()
 
-    runner = ModuleRunner(
+    runner = _build_runner(
         modules=get_all_modules(config),
         dry_run=False,
         allow_sudo=allow_sudo,
@@ -215,17 +252,14 @@ def report(
         dry_run = True
 
     # Validate sudo access upfront if needed
-    if allow_sudo:
-        result = subprocess.run(["sudo", "-n", "true"], capture_output=True)
-        if result.returncode != 0:
-            click.echo("Warning: sudo requires a password. You may be prompted.")
+    _warn_if_sudo_needs_password(allow_sudo)
 
     platform = detect_platform()
     output_fmt = output or config.report.get("output", "terminal")
     reporter = Reporter(platform=platform, output_format=output_fmt)
     audit_log = AuditLog()
 
-    runner = ModuleRunner(
+    runner = _build_runner(
         modules=get_all_modules(config),
         dry_run=dry_run,
         allow_sudo=allow_sudo,
@@ -235,7 +269,7 @@ def report(
     # If not dry-run and not --yes, show preview and prompt for confirmation
     if not dry_run and not yes:
         # Run scan to preview changes
-        scan_runner = ModuleRunner(
+        scan_runner = _build_runner(
             modules=get_all_modules(config),
             dry_run=True,
             allow_sudo=allow_sudo,

src/macos_maid/config.py

@@ -15,18 +15,21 @@
         "output": "terminal",
     },
     "homebrew": {
+        "enabled": True,
         "update": False,
         "upgrade": False,
         "cleanup": True,
         "audit_casks": True,
         "check_untapped": True,
     },
     "docker": {
+        "enabled": True,
         "remove_dangling_images": True,
         "remove_unused_volumes": True,
         "remove_stopped_containers": False,
     },
     "dev_caches": {
+        "enabled": True,
         "clean": ["pip", "npm", "cargo", "gradle", "cocoapods", "xcode_derived"],
     },
     "git": {
@@ -38,44 +41,53 @@
         "report_large_repos": True,
     },
     "trash": {
+        "enabled": True,
         "empty": True,
     },
     "wifi": {
+        "enabled": True,
         "keep_days": 90,
         "keep_ssids": [],
     },
     "network": {
+        "enabled": True,
         "flush_dns": True,
         "check_open_ports": True,
         "audit_vpn_profiles": True,
         "check_firewall": True,
     },
     "privacy": {
+        "enabled": True,
         "clear_recent_items": True,
         "report_old_downloads": True,
         "downloads_move_to_trash": False,
         "downloads_older_than": 90,
         "audit_tcc_permissions": True,
     },
     "system_integrity": {
+        "enabled": True,
         "check_sip": True,
         "check_filevault": True,
         "check_gatekeeper": True,
         "check_xprotect": True,
     },
     "app_audit": {
+        "enabled": True,
         "check_unsigned": True,
     },
     "launch_audit": {
+        "enabled": True,
         "audit_launch_daemons": True,
         "audit_launch_agents": True,
         "flag_non_apple": True,
     },
     "system_cache": {
+        "enabled": True,
         "clean_system_logs": True,
         "clean_user_caches": True,
     },
     "tools": {
+        "enabled": True,
         "lynis": True,
         "osquery": True,
         "knockknock": False,

src/macos_maid/modules/__init__.py

@@ -30,83 +30,128 @@ def get_all_modules(config: MaidConfig | None = None) -> list[Module]:
         config: Optional MaidConfig to configure modules. If None, uses default settings.
 
     Returns:
-        List of configured module instances
+        List of configured module instances (only those with enabled=True)
     """
     # Get module configurations from config or use defaults
     if config is not None:
+        trash_cfg = config.get_module_config("trash")
         wifi_cfg = config.get_module_config("wifi")
         privacy_cfg = config.get_module_config("privacy")
         tools_cfg = config.get_module_config("tools")
         git_cfg = config.get_module_config("git")
         homebrew_cfg = config.get_module_config("homebrew")
         docker_cfg = config.get_module_config("docker")
+        dev_caches_cfg = config.get_module_config("dev_caches")
+        system_integrity_cfg = config.get_module_config("system_integrity")
+        network_cfg = config.get_module_config("network")
+        app_audit_cfg = config.get_module_config("app_audit")
+        launch_audit_cfg = config.get_module_config("launch_audit")
+        system_cache_cfg = config.get_module_config("system_cache")
     else:
+        trash_cfg = {}
         wifi_cfg = {}
         privacy_cfg = {}
         tools_cfg = {}
         git_cfg = {}
         homebrew_cfg = {}
         docker_cfg = {}
+        dev_caches_cfg = {}
+        system_integrity_cfg = {}
+        network_cfg = {}
+        app_audit_cfg = {}
+        launch_audit_cfg = {}
+        system_cache_cfg = {}
+
+    modules: list[Module] = []
+
+    # Trash module
+    if trash_cfg.get("enabled", True):
+        modules.append(TrashModule())
+
+    # Homebrew module
+    if homebrew_cfg.get("enabled", True):
+        modules.append(
+            HomebrewModule(
+                update=homebrew_cfg.get("update", False),
+                upgrade=homebrew_cfg.get("upgrade", False),
+                cleanup=homebrew_cfg.get("cleanup", True),
+            )
+        )
+
+    # Docker module
+    if docker_cfg.get("enabled", True):
+        modules.append(
+            DockerModule(
+                remove_dangling_images=docker_cfg.get("remove_dangling_images", True),
+                remove_unused_volumes=docker_cfg.get("remove_unused_volumes", True),
+                remove_stopped_containers=docker_cfg.get("remove_stopped_containers", False),
+            )
+        )
+
+    # Dev caches module
+    if dev_caches_cfg.get("enabled", True):
+        modules.append(DevCachesModule())
+
+    # Git module
+    if git_cfg.get("enabled", False):
+        modules.append(
+            GitModule(
+                enabled=git_cfg.get("enabled", False),
+                repos_dir=git_cfg.get("repos_dir"),
+                prune_remotes=git_cfg.get("prune_remotes", True),
+                delete_merged=git_cfg.get("delete_merged_branches", False),
+                protected_branches=git_cfg.get("protected_branches", ["main", "master", "develop"]),
+                report_large_repos=git_cfg.get("report_large_repos", True),
+            )
+        )
+
+    # System integrity module
+    if system_integrity_cfg.get("enabled", True):
+        modules.append(SystemIntegrityModule())
+
+    # Network module
+    if network_cfg.get("enabled", True):
+        modules.append(NetworkModule())
 
     # WiFi module
-    wifi = WiFiModule(
-        keep_days=wifi_cfg.get("keep_days", 90),
-        keep_ssids=wifi_cfg.get("keep_ssids", []),
-    )
+    if wifi_cfg.get("enabled", True):
+        modules.append(
+            WiFiModule(
+                keep_days=wifi_cfg.get("keep_days", 90),
+                keep_ssids=wifi_cfg.get("keep_ssids", []),
+            )
+        )
 
     # Privacy module
-    privacy = PrivacyModule(
-        clear_recent=privacy_cfg.get("clear_recent_items", True),
-        downloads_move_to_trash=privacy_cfg.get("downloads_move_to_trash", False),
-        downloads_older_than=privacy_cfg.get("downloads_older_than", 90),
-    )
+    if privacy_cfg.get("enabled", True):
+        modules.append(
+            PrivacyModule(
+                clear_recent=privacy_cfg.get("clear_recent_items", True),
+                downloads_move_to_trash=privacy_cfg.get("downloads_move_to_trash", False),
+                downloads_older_than=privacy_cfg.get("downloads_older_than", 90),
+            )
+        )
 
-    # Tools module
-    tools = ToolsModule(
-        lynis_enabled=tools_cfg.get("lynis", True),
-        osquery_enabled=tools_cfg.get("osquery", True),
-        knockknock_enabled=tools_cfg.get("knockknock", False),
-    )
+    # App audit module
+    if app_audit_cfg.get("enabled", True):
+        modules.append(AppAuditModule())
 
-    # Git module
-    git = GitModule(
-        enabled=git_cfg.get("enabled", False),
-        repos_dir=git_cfg.get("repos_dir"),
-        prune_remotes=git_cfg.get("prune_remotes", True),
-        delete_merged=git_cfg.get("delete_merged_branches", False),
-        protected_branches=git_cfg.get("protected_branches", ["main", "master", "develop"]),
-        report_large_repos=git_cfg.get("report_large_repos", True),
-    )
+    # Launch audit module
+    if launch_audit_cfg.get("enabled", True):
+        modules.append(LaunchAuditModule())
 
-    # Homebrew module
-    homebrew = HomebrewModule(
-        update=homebrew_cfg.get("update", False),
-        upgrade=homebrew_cfg.get("upgrade", False),
-        cleanup=homebrew_cfg.get("cleanup", True),
-    )
+    # Tools module
+    if tools_cfg.get("enabled", True):
+        modules.append(
+            ToolsModule(
+                lynis_enabled=tools_cfg.get("lynis", True),
+                osquery_enabled=tools_cfg.get("osquery", True),
+                knockknock_enabled=tools_cfg.get("knockknock", False),
+            )
+        )
 
-    # Docker module
-    docker = DockerModule(
-        remove_dangling_images=docker_cfg.get("remove_dangling_images", True),
-        remove_unused_volumes=docker_cfg.get("remove_unused_volumes", True),
-        remove_stopped_containers=docker_cfg.get("remove_stopped_containers", False),
-    )
-
-    return [
-        # Dev modules
-        TrashModule(),
-        homebrew,
-        docker,
-        DevCachesModule(),
-        git,
-        # Security modules
-        SystemIntegrityModule(),
-        NetworkModule(),
-        wifi,
-        privacy,
-        AppAuditModule(),
-        LaunchAuditModule(),
-        tools,
-        # Both
-        SystemCacheModule(),
-    ]
+    # System cache module
+    if system_cache_cfg.get("enabled", True):
+        modules.append(SystemCacheModule())
+
+    return modules