From 6d2fdd739217aee62dca42be7664cdc44ca81cbd Mon Sep 17 00:00:00 2001 From: Tw93 Date: Thu, 11 Dec 2025 15:10:49 +0800 Subject: [PATCH] Supplemental Security Audit Report --- README.md | 9 +++++++++ SECURITY_AUDIT.md | 42 ++++++++++++++++++++++++++++++++++++++++++ lib/optimize/tasks.sh | 14 ++++++++------ 3 files changed, 59 insertions(+), 6 deletions(-) create mode 100644 SECURITY_AUDIT.md diff --git a/README.md b/README.md index 776efcc..50dfa5d 100644 --- a/README.md +++ b/README.md @@ -70,6 +70,15 @@ mo optimize --whitelist # Adjust protected optimization items - **Navigation**: All menus support Vim keys `h/j/k/l` in addition to arrow keys - **Debug**: Use `--debug` flag to see detailed logs: `mo clean --debug` +## Security & Safety + +Mole is built with a **"Safety First"** philosophy. We prioritize system stability over aggressive cleaning. + +- **Path Validation**: All deletion operations undergo strict validation to prevent accidents. +- **Protected Directories**: Critical system paths are hard-coded as untouchable. +- **Conservative Cleanup**: "Orphaned" data is only removed if the app is missing AND the data has been inactive for 60+ days. +- **Audit Report**: For a detailed technical breakdown of our safety mechanisms, read the [Security Audit Report](SECURITY_AUDIT.md). + ## Features in Detail ### Deep System Cleanup diff --git a/SECURITY_AUDIT.md b/SECURITY_AUDIT.md new file mode 100644 index 0000000..a3e3230 --- /dev/null +++ b/SECURITY_AUDIT.md @@ -0,0 +1,42 @@ +# Mole Security Audit Report + +**Date:** December 11, 2025 +**Status:** Passed + +## Executive Summary + +This document outlines the safety mechanisms, defensive programming strategies, and architectural decisions implemented in Mole to ensure user data integrity and system stability. Our primary design philosophy is **"Safety First"**—we prioritize system stability over aggressive cleaning. + +## 1. Core Safety Mechanisms (`lib/core/file_ops.sh`) + +All file modification and deletion operations are routed through a centralized, hardened library. No script performs raw `rm -rf` commands directly. + +* **Mandatory Path Validation**: Every deletion request (`safe_remove`, `safe_sudo_remove`) undergoes strict validation before execution. +* **Root Directory Protection**: The system explicitly rejects operations on critical system paths (`/`, `/bin`, `/usr`, `/etc`, `/var`, `/System`, etc.), even if variables resolve to these paths unexpectedly. +* **Symlink Guard**: `sudo` operations explicitly check for and refuse to traverse or delete symbolic links. This prevents "symlink attacks" where a malicious or accidental link could redirect deletion to critical system files. +* **Path Traversal Prevention**: Paths containing `..` are strictly rejected to prevent escaping the target directory. + +## 2. Conservative Cleanup Strategy (`lib/clean/`) + +Mole employs a conservative approach to cleaning to avoid "false positives" that could damage user data. + +* **Orphaned Data Protection**: + * Applications are only considered "orphaned" if they are completely missing from `/Applications` **AND** their data has been inactive for **60+ days**. + * **Vendor Whitelist**: A hardcoded whitelist protects data from major vendors (Adobe, Microsoft, Google, etc.) to prevent accidental configuration loss. +* **SIP Awareness**: The cleanup logic detects macOS System Integrity Protection (SIP) status. It automatically skips protected areas (like `/Library/Updates`) if SIP is enabled to avoid permission errors and maintain system integrity. +* **Time Machine Safety**: Cleanup of failed Time Machine backups is intelligently paused if a backup session (`backupd` process) is currently active, preventing corruption of ongoing backups. + +## 3. Optimization Safety (`lib/optimize/`) + +* **Standard macOS Tools**: Optimizations rely on official macOS maintenance binaries (`dscacheutil`, `mdutil`, `kextcache`, `periodic`) rather than manual file manipulation wherever possible. +* **Atomic Network Reset**: Network interface resets (Wi-Fi/AirDrop) utilize **atomic execution blocks**. This ensures that even if the script is forcibly interrupted (e.g., via `Ctrl+C`) during a reset, the network interface will automatically recover, preventing persistent connectivity loss. +* **Safe Swap Clearing**: Swap files are only cleared after successfully verifying the `dynamic_pager` daemon has unloaded. + +## 4. User Verification & Control + +* **Dry-Run Mode**: Users can verify every single file that *would* be deleted using `mo clean --dry-run` (or `-n`) without touching the filesystem. +* **Custom Whitelists**: Users can safeguard specific paths by adding them to `~/.config/mole/whitelist`. + +--- + +*This report verifies that Mole's architecture includes multiple layers of redundancy and safety checks to prevent data loss and system damage.* diff --git a/lib/optimize/tasks.sh b/lib/optimize/tasks.sh index 66a3e09..08a0d48 100644 --- a/lib/optimize/tasks.sh +++ b/lib/optimize/tasks.sh @@ -170,17 +170,19 @@ opt_radio_refresh() { local wifi_interface wifi_interface=$(networksetup -listallhardwareports | awk '/Wi-Fi/{getline; print $2}' | head -1) if [[ -n "$wifi_interface" ]]; then - sudo ifconfig "$wifi_interface" down 2> /dev/null || true - sleep 1 - sudo ifconfig "$wifi_interface" up 2> /dev/null || true - echo -e "${GREEN}${ICON_SUCCESS}${NC} Wi-Fi interface restarted" + # Use atomic execution to ensure interface comes back up even if interrupted + if sudo bash -c "trap '' INT TERM; ifconfig '$wifi_interface' down; sleep 1; ifconfig '$wifi_interface' up" 2> /dev/null; then + echo -e "${GREEN}${ICON_SUCCESS}${NC} Wi-Fi interface restarted" + else + echo -e "${YELLOW}!${NC} Failed to restart Wi-Fi interface" + fi else echo -e "${GRAY}-${NC} Wi-Fi interface not found" fi # Restart AirDrop interface - sudo ifconfig awdl0 down 2> /dev/null || true - sudo ifconfig awdl0 up 2> /dev/null || true + # Use atomic execution to ensure interface comes back up even if interrupted + sudo bash -c "trap '' INT TERM; ifconfig awdl0 down; ifconfig awdl0 up" 2> /dev/null || true echo -e "${GREEN}${ICON_SUCCESS}${NC} Wireless services refreshed" }