Mole/SECURITY_AUDIT.md

Mole Security Reference

Version 1.29.0 | 2026-03-08

This document describes the security-relevant behavior of the current codebase on main.

Path Validation

All destructive file operations go through lib/core/file_ops.sh.

• validate_path_for_deletion() rejects empty paths, relative paths, traversal segments such as /../, and control characters.
• Security-sensitive cleanup paths do not use raw find ... -delete.
• Removal flows use guarded helpers such as safe_remove(), safe_sudo_remove(), safe_find_delete(), and safe_sudo_find_delete().

Blocked paths remain protected even with sudo, including:

/
/System
/bin
/sbin
/usr
/etc
/var
/private
/Library/Extensions

Some subpaths under protected roots are explicitly allowlisted for bounded cache and log cleanup, for example:

• /private/tmp
• /private/var/tmp
• /private/var/log
• /private/var/folders
• /private/var/db/diagnostics
• /private/var/db/DiagnosticPipeline
• /private/var/db/powerlog
• /private/var/db/reportmemoryexception

When running with sudo, symlinked targets are validated before deletion and system-target symlinks are refused.

Cleanup Rules

Orphan Detection

Orphaned app data is handled in lib/clean/apps.sh.

• Generic orphaned app data requires both:
  • the app is not found by installed-app scanning and fallback checks, and
  • the target has been inactive for at least 30 days.
• Claude VM bundles use a stricter app-specific window:
  • ~/Library/Application Support/Claude/vm_bundles/claudevm.bundle must appear orphaned, and
  • it must be inactive for at least 7 days before cleanup.
• Sensitive categories such as keychains, password-manager data, and protected app families are excluded from generic orphan cleanup.

Installed-app detection is broader than a simple /Applications scan and includes:

• /Applications
• /System/Applications
• ~/Applications
• Homebrew Caskroom locations
• Setapp application paths

Spotlight fallback checks are bounded with short timeouts to avoid hangs.

Uninstall Matching

App uninstall behavior is implemented in lib/uninstall/batch.sh and related helpers.

• LaunchAgent and LaunchDaemon lookups require a valid reverse-DNS bundle identifier.
• Deletion candidates are decoded and validated as absolute paths before removal.
• Homebrew casks are preferentially removed with brew uninstall --cask --zap.
• LaunchServices unregister and rebuild steps are skipped safely if lsregister is unavailable.

Developer and Project Cleanup

Project artifact cleanup in lib/clean/project.sh protects recently modified targets:

• recently modified project artifacts are treated as recent for 7 days
• protected vendor and build-output heuristics prevent broad accidental deletions
• nested artifacts are filtered to avoid duplicate or parent-child over-deletion

Developer-cache cleanup preserves toolchains and other high-value state. Examples intentionally left alone include:

• ~/.cargo/bin
• ~/.rustup
• ~/.mix/archives
• ~/.stack/programs

Protected Categories

Protected or conservatively handled categories include:

• system components such as Control Center, System Settings, TCC, Spotlight, and /Library/Updates
• password managers and keychain-related data
• VPN / proxy tools such as Shadowsocks, V2Ray, Clash, and Tailscale
• AI tools in generic protected-data logic, including Cursor, Claude, ChatGPT, and Ollama
• ~/Library/Messages/Attachments
• browser history and cookies
• Time Machine data while backup state is active or ambiguous
• com.apple.* LaunchAgents and LaunchDaemons

Analyzer

mo analyze is intentionally lower-risk than cleanup flows:

• it does not require sudo
• it respects normal user permissions and SIP
• interactive deletion requires an extra confirmation sequence
• deletions route through Trash/Finder behavior rather than direct permanent removal

Code lives under cmd/analyze/*.go.

Timeouts and Hang Resistance

lib/core/timeout.sh uses this fallback order:

1. gtimeout / timeout
2. a Perl helper with process-group cleanup
3. a shell fallback

Current notable timeouts in security-relevant paths:

• orphan/Spotlight mdfind checks: 2s
• LaunchServices rebuild during uninstall: 10s / 15s bounded steps
• Homebrew uninstall cask flow: 300s default, extended to 600s or 900s for large apps
• Application Support sizing: direct file stat, bounded du for directories

Additional safety behavior:

• brew_uninstall_cask() treats exit code 124 as timeout failure and returns failure immediately
• font cache rebuild is skipped while browsers are running
• project-cache discovery and scans use strict timeouts to avoid whole-home stalls

User Configuration

Protected paths can be added to ~/.config/mole/whitelist, one path per line.

Example:

/Users/me/important-cache
~/Library/Application Support/MyApp

Exact path protection is preferred over pattern-style broad deletion rules.

Use --dry-run before destructive operations when validating new cleanup behavior.

Testing

There is no dedicated tests/security.bats. Security-relevant behavior is covered by targeted BATS suites, including:

• tests/clean_core.bats
• tests/clean_user_core.bats
• tests/clean_dev_caches.bats
• tests/clean_system_maintenance.bats
• tests/clean_apps.bats
• tests/purge.bats
• tests/core_safe_functions.bats
• tests/optimize.bats

Local verification used for the current branch includes:

bats tests/clean_core.bats tests/clean_user_core.bats tests/clean_dev_caches.bats tests/clean_system_maintenance.bats tests/purge.bats tests/core_safe_functions.bats tests/clean_apps.bats tests/optimize.bats
bash -n lib/core/base.sh lib/clean/apps.sh tests/clean_apps.bats tests/optimize.bats

CI additionally runs shell and Go validation on push.

Dependencies

Primary Go dependencies are pinned in go.mod, including:

• github.com/charmbracelet/bubbletea v1.3.10
• github.com/charmbracelet/lipgloss v1.1.0
• github.com/shirou/gopsutil/v4 v4.26.2
• github.com/cespare/xxhash/v2 v2.3.0

System tooling relies mainly on Apple-provided binaries and standard macOS utilities such as:

• tmutil
• diskutil
• plutil
• launchctl
• osascript
• find
• stat

Dependency vulnerability status should be checked separately from this document.

Limitations

• Cleanup is destructive. There is no undo.
• Generic orphan data waits 30 days before automatic cleanup.
• Claude VM orphan cleanup waits 7 days before automatic cleanup.
• Time Machine safety windows are hour-based, not day-based, and remain more conservative.
• Localized app names may still be missed in some heuristic paths, though bundle IDs are preferred where available.
• Users who want immediate removal of app data should use explicit uninstall flows rather than waiting for orphan cleanup.