mirror of
https://github.com/tw93/Mole.git
synced 2026-02-04 17:24:45 +00:00
Update documents and instructions
This commit is contained in:
Tw93
@@ -2,36 +2,17 @@
|
||||
|
||||
<div align="center">
|
||||
|
||||
**Security Audit & Compliance Report**
|
||||
|
||||
Version 1.19.0 | January 5, 2026
|
||||
|
||||
---
|
||||
|
||||
**Audit Status:** PASSED | **Risk Level:** LOW
|
||||
**Status:** PASSED | **Risk Level:** LOW | **Version:** 1.19.0 (2026-01-09)
|
||||
|
||||
</div>
|
||||
|
||||
---
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [Audit Overview](#audit-overview)
|
||||
2. [Security Philosophy](#security-philosophy)
|
||||
3. [Threat Model](#threat-model)
|
||||
4. [Defense Architecture](#defense-architecture)
|
||||
5. [Safety Mechanisms](#safety-mechanisms)
|
||||
6. [User Controls](#user-controls)
|
||||
7. [Testing & Compliance](#testing--compliance)
|
||||
8. [Dependencies](#dependencies)
|
||||
|
||||
---
|
||||
|
||||
## Audit Overview
|
||||
|
||||
| Attribute | Details |
|
||||
|-----------|---------|
|
||||
| Audit Date | December 31, 2025 |
|
||||
| Audit Date | January 9, 2026 |
|
||||
| Audit Conclusion | **PASSED** |
|
||||
| Mole Version | V1.19.0 |
|
||||
| Audited Branch | `main` (HEAD) |
|
||||
@@ -42,12 +23,12 @@ Version 1.19.0 | January 5, 2026
|
||||
|
||||
**Key Findings:**
|
||||
|
||||
- Multi-layered validation prevents critical system modifications
|
||||
- Conservative cleaning logic with 60-day dormancy rules
|
||||
- Comprehensive protection for VPN, AI tools, and system components
|
||||
- Atomic operations with crash recovery mechanisms
|
||||
- Full user control with dry-run and whitelist capabilities
|
||||
- Installer cleanup safely scans common locations with user confirmation
|
||||
- Multi-layer validation effectively blocks risky system modifications.
|
||||
- Conservative cleaning logic ensures safety (e.g., 60-day dormancy rule).
|
||||
- Comprehensive protection for VPNs, AI tools, and core system components.
|
||||
- Atomic operations prevent state corruption during crashes.
|
||||
- Dry-run and whitelist features give users full control.
|
||||
- Installer cleanup scans safely and requires user confirmation.
|
||||
|
||||
---
|
||||
|
||||
@@ -55,14 +36,14 @@ Version 1.19.0 | January 5, 2026
|
||||
|
||||
**Core Principle: "Do No Harm"**
|
||||
|
||||
Mole operates under a **Zero Trust** architecture for all filesystem operations. Every modification request is treated as potentially dangerous until passing strict validation.
|
||||
We built Mole on a **Zero Trust** architecture for filesystem operations. Every modification request is treated as dangerous until it passes strict validation.
|
||||
|
||||
**Guiding Priorities:**
|
||||
|
||||
1. **System Stability First** - Prefer leaving 1GB of junk over deleting 1KB of critical data
|
||||
2. **Conservative by Default** - Require explicit user confirmation for high-risk operations
|
||||
3. **Fail Safe** - When in doubt, abort rather than proceed
|
||||
4. **Transparency** - All operations are logged and can be previewed via dry-run mode
|
||||
1. **System Stability First** - We'd rather leave 1GB of junk than delete 1KB of your data.
|
||||
2. **Conservative by Default** - High-risk operations always require explicit confirmation.
|
||||
3. **Fail Safe** - When in doubt, we abort immediately.
|
||||
4. **Transparency** - Every operation is logged and allows a preview via dry-run mode.
|
||||
|
||||
---
|
||||
|
||||
@@ -89,7 +70,7 @@ Mole operates under a **Zero Trust** architecture for all filesystem operations.
|
||||
|
||||
### Multi-Layered Validation System
|
||||
|
||||
All automated operations pass through hardened middleware (`lib/core/file_ops.sh`) with 4 validation layers:
|
||||
All automated operations pass through hardened middleware (`lib/core/file_ops.sh`) with 4 layers of validation:
|
||||
|
||||
#### Layer 1: Input Sanitization
|
||||
|
||||
@@ -114,7 +95,7 @@ Even with `sudo`, these paths are **unconditionally blocked**:
|
||||
/Library/Extensions # Kernel extensions
|
||||
```
|
||||
|
||||
**Exception:** `/System/Library/Caches/com.apple.coresymbolicationd/data` (safe, rebuildable cache)
|
||||
**Exception:** `/System/Library/Caches/com.apple.coresymbolicationd/data` (safe, rebuildable cache).
|
||||
|
||||
**Code:** `lib/core/file_ops.sh:60-78`
|
||||
|
||||
@@ -122,9 +103,9 @@ Even with `sudo`, these paths are **unconditionally blocked**:
|
||||
|
||||
For privileged operations, pre-flight checks prevent symlink-based attacks:
|
||||
|
||||
- Detects symlinks pointing from cache folders to system files
|
||||
- Refuses recursive deletion of symbolic links in sudo mode
|
||||
- Validates real path vs symlink target
|
||||
- Detects symlinks from cache folders pointing to system files.
|
||||
- Refuses recursive deletion of symbolic links in sudo mode.
|
||||
- Validates real path vs. symlink target.
|
||||
|
||||
**Code:** `lib/core/file_ops.sh:safe_sudo_recursive_delete()`
|
||||
|
||||
@@ -132,18 +113,18 @@ For privileged operations, pre-flight checks prevent symlink-based attacks:
|
||||
|
||||
When running with `sudo`:
|
||||
|
||||
- Auto-corrects ownership back to user (`chown -R`)
|
||||
- Operations restricted to user's home directory
|
||||
- Multiple validation checkpoints
|
||||
- Auto-corrects ownership back to user (`chown -R`).
|
||||
- Restricts operations to the user's home directory.
|
||||
- Enforces multiple validation checkpoints.
|
||||
|
||||
### Interactive Analyzer (Go)
|
||||
|
||||
The analyzer (`mo analyze`) uses a different security model:
|
||||
The analyzer (`mo analyze`) uses a distinct security model:
|
||||
|
||||
- Runs with standard user permissions only
|
||||
- Respects macOS System Integrity Protection (SIP)
|
||||
- All deletions require explicit user confirmation
|
||||
- OS-level enforcement (cannot delete `/System` due to Read-Only Volume)
|
||||
- Runs with standard user permissions only.
|
||||
- Respects macOS System Integrity Protection (SIP).
|
||||
- Requires explicit user confirmation for all deletions.
|
||||
- OS-level enforcement (cannot delete `/System` due to Read-Only Volume).
|
||||
|
||||
**Code:** `cmd/analyze/*.go`
|
||||
|
||||
@@ -159,7 +140,7 @@ The analyzer (`mo analyze`) uses a different security model:
|
||||
|------|--------------|-----------|
|
||||
| 1. App Check | All installation locations | Must be missing from `/Applications`, `~/Applications`, `/System/Applications` |
|
||||
| 2. Dormancy | Modification timestamps | Untouched for ≥60 days |
|
||||
| 3. Vendor Whitelist | Cross-reference database | Adobe, Microsoft, Google resources protected |
|
||||
| 3. Vendor Whitelist | Cross-reference database | Adobe, Microsoft, and Google resources are protected |
|
||||
|
||||
**Code:** `lib/clean/apps.sh:orphan_detection()`
|
||||
|
||||
@@ -169,8 +150,8 @@ For user-selected app removal:
|
||||
|
||||
- **Sanitized Name Matching:** "Visual Studio Code" → `VisualStudioCode`, `.vscode`
|
||||
- **Safety Limit:** 3-char minimum (prevents "Go" matching "Google")
|
||||
- **Disabled:** Fuzzy matching, wildcard expansion for short names
|
||||
- **User Confirmation:** Required before deletion
|
||||
- **Disabled:** Fuzzy matching and wildcard expansion for short names.
|
||||
- **User Confirmation:** Required before deletion.
|
||||
|
||||
**Code:** `lib/clean/apps.sh:uninstall_app()`
|
||||
|
||||
@@ -183,19 +164,19 @@ For user-selected app removal:
|
||||
| System Components | Control Center, System Settings, TCC | Centralized detection via `is_critical_system_component()` |
|
||||
| Time Machine | Local snapshots, backups | Checks `backupd` process, aborts if active |
|
||||
| VPN & Proxy | Shadowsocks, V2Ray, Tailscale, Clash | Protects network configs |
|
||||
| AI & LLM Tools | Cursor, Claude, ChatGPT, Ollama, LM Studio | Protects models, tokens, sessions |
|
||||
| AI & LLM Tools | Cursor, Claude, ChatGPT, Ollama, LM Studio | Protects models, tokens, and sessions |
|
||||
| Startup Items | `com.apple.*` LaunchAgents/Daemons | System items unconditionally skipped |
|
||||
|
||||
**Orphaned Helper Cleanup (`opt_startup_items_cleanup`):**
|
||||
|
||||
Removes LaunchAgents/Daemons whose associated app has been uninstalled:
|
||||
|
||||
- Checks `AssociatedBundleIdentifiers` to detect orphans
|
||||
- Skips all `com.apple.*` system items
|
||||
- Skips paths under `/System/*`, `/usr/bin/*`, `/usr/lib/*`, `/usr/sbin/*`, `/Library/Apple/*`
|
||||
- Uses `safe_remove` / `safe_sudo_remove` with path validation
|
||||
- Unloads service via `launchctl` before deletion
|
||||
- `mdfind` operations have 10-second timeout protection
|
||||
- Checks `AssociatedBundleIdentifiers` to detect orphans.
|
||||
- Skips all `com.apple.*` system items.
|
||||
- Skips paths under `/System/*`, `/usr/bin/*`, `/usr/lib/*`, `/usr/sbin/*`, `/Library/Apple/*`.
|
||||
- Uses `safe_remove` / `safe_sudo_remove` with path validation.
|
||||
- Unloads service via `launchctl` before deletion.
|
||||
- **Timeout Protection:** 10-second limit on `mdfind` operations.
|
||||
|
||||
**Code:** `lib/optimize/tasks.sh:opt_startup_items_cleanup()`
|
||||
|
||||
@@ -206,9 +187,9 @@ Removes LaunchAgents/Daemons whose associated app has been uninstalled:
|
||||
| Network Interface Reset | Atomic execution blocks | Wi-Fi/AirDrop restored to pre-operation state |
|
||||
| Swap Clearing | Daemon restart | `dynamic_pager` handles recovery safely |
|
||||
| Volume Scanning | Timeout + filesystem check | Auto-skip unresponsive NFS/SMB/AFP mounts |
|
||||
| Homebrew Cache | Pre-flight size check | Skip if <50MB (avoids 30-120s delay) |
|
||||
| Homebrew Cache | Pre-flight size check | Skip if <50MB (avoids long delays) |
|
||||
| Network Volume Check | `diskutil info` with timeout | Prevents hangs on slow/dead mounts |
|
||||
| SQLite Vacuum | App-running check + 20s timeout | Skips if Mail/Safari/Messages running |
|
||||
| SQLite Vacuum | App-running check + 20s timeout | Skips if Mail/Safari/Messages active |
|
||||
| dyld Cache Update | 24-hour freshness check + 180s timeout | Skips if recently updated |
|
||||
| App Bundle Search | 10s timeout on mdfind | Fallback to standard paths |
|
||||
|
||||
@@ -230,10 +211,10 @@ run_with_timeout 5 diskutil info "$mount_point" || skip_volume
|
||||
|
||||
**Behavior:**
|
||||
|
||||
- Simulates entire operation without filesystem modifications
|
||||
- Lists every file/directory that **would** be deleted
|
||||
- Calculates total space that **would** be freed
|
||||
- Zero risk - no actual deletion commands executed
|
||||
- Simulates the entire operation without modifying a single file.
|
||||
- Lists every file/directory that **would** be deleted.
|
||||
- Calculates total space that **would** be freed.
|
||||
- **Zero risk** - no actual deletion commands are executed.
|
||||
|
||||
### Custom Whitelists
|
||||
|
||||
@@ -247,19 +228,19 @@ run_with_timeout 5 diskutil info "$mount_point" || skip_volume
|
||||
~/Library/Application Support/CriticalApp
|
||||
```
|
||||
|
||||
- Paths are **unconditionally protected**
|
||||
- Applies to all operations (clean, optimize, uninstall)
|
||||
- Supports absolute paths and `~` expansion
|
||||
- Paths are **unconditionally protected**.
|
||||
- Applies to all operations (clean, optimize, uninstall).
|
||||
- Supports absolute paths and `~` expansion.
|
||||
|
||||
**Code:** `lib/core/file_ops.sh:is_whitelisted()`
|
||||
|
||||
### Interactive Confirmations
|
||||
|
||||
Required for:
|
||||
We mandate confirmation for:
|
||||
|
||||
- Uninstalling system-scope applications
|
||||
- Removing large data directories (>1GB)
|
||||
- Deleting items from shared vendor folders
|
||||
- Uninstalling system-scope applications.
|
||||
- Removing large data directories (>1GB).
|
||||
- Deleting items from shared vendor folders.
|
||||
|
||||
---
|
||||
|
||||
@@ -291,33 +272,33 @@ bats tests/security.bats # Run specific suite
|
||||
| Standard | Implementation |
|
||||
|----------|----------------|
|
||||
| OWASP Secure Coding | Input validation, least privilege, defense-in-depth |
|
||||
| CWE-22 (Path Traversal) | Enhanced detection: rejects `/../` components while allowing `..` in directory names (Firefox compatibility) |
|
||||
| CWE-22 (Path Traversal) | Enhanced detection: rejects `/../` components, safely handles `..` in directory names |
|
||||
| CWE-78 (Command Injection) | Control character filtering |
|
||||
| CWE-59 (Link Following) | Symlink detection before privileged operations |
|
||||
| Apple File System Guidelines | Respects SIP, Read-Only Volumes, TCC |
|
||||
|
||||
### Security Development Lifecycle
|
||||
|
||||
- **Static Analysis:** shellcheck for all shell scripts
|
||||
- **Code Review:** All changes reviewed by maintainers
|
||||
- **Dependency Scanning:** Minimal external dependencies, all vetted
|
||||
- **Static Analysis:** `shellcheck` runs on all shell scripts.
|
||||
- **Code Review:** All changes are manually reviewed by maintainers.
|
||||
- **Dependency Scanning:** Minimal external dependencies, all carefully vetted.
|
||||
|
||||
### Known Limitations
|
||||
|
||||
| Limitation | Impact | Mitigation |
|
||||
|------------|--------|------------|
|
||||
| Requires `sudo` for system caches | Initial friction | Clear documentation |
|
||||
| 60-day rule may delay cleanup | Some orphans remain longer | Manual `mo uninstall` available |
|
||||
| No undo functionality | Deleted files unrecoverable | Dry-run mode, warnings |
|
||||
| English-only name matching | May miss non-English apps | Bundle ID fallback |
|
||||
| Requires `sudo` for system caches | Initial friction | Clear documentation explaining why |
|
||||
| 60-day rule may delay cleanup | Some orphans remain longer | Manual `mo uninstall` is always available |
|
||||
| No undo functionality | Deleted files are unrecoverable | Dry-run mode and warnings are clear |
|
||||
| English-only name matching | May miss non-English apps | Fallback to Bundle ID matching |
|
||||
|
||||
**Intentionally Out of Scope (Safety):**
|
||||
|
||||
- Automatic deletion of user documents/media
|
||||
- Encryption key stores or password managers
|
||||
- System configuration files (`/etc/*`)
|
||||
- Browser history or cookies
|
||||
- Git repository cleanup
|
||||
- Automatic deletion of user documents/media.
|
||||
- Encryption key stores or password managers.
|
||||
- System configuration files (`/etc/*`).
|
||||
- Browser history or cookies.
|
||||
- Git repository cleanup.
|
||||
|
||||
---
|
||||
|
||||
@@ -325,7 +306,7 @@ bats tests/security.bats # Run specific suite
|
||||
|
||||
### System Binaries
|
||||
|
||||
Mole relies on standard macOS system binaries (all SIP-protected):
|
||||
Mole relies on standard, SIP-protected macOS system binaries:
|
||||
|
||||
| Binary | Purpose | Fallback |
|
||||
|--------|---------|----------|
|
||||
@@ -347,14 +328,14 @@ The compiled Go binary (`analyze-go`) includes:
|
||||
|
||||
**Supply Chain Security:**
|
||||
|
||||
- All dependencies pinned to specific versions
|
||||
- Regular security audits
|
||||
- No transitive dependencies with known CVEs
|
||||
- **Automated Releases**: Binaries compiled via GitHub Actions and signed
|
||||
- **Source Only**: Repository contains no pre-compiled binaries
|
||||
- All dependencies are pinned to specific versions.
|
||||
- Regular security audits.
|
||||
- No transitive dependencies with known CVEs.
|
||||
- **Automated Releases**: Binaries are compiled and signed via GitHub Actions.
|
||||
- **Source Only**: The repository contains no pre-compiled binaries.
|
||||
|
||||
---
|
||||
|
||||
**Certification:** This security audit certifies that Mole implements industry-standard defensive programming practices and adheres to macOS security guidelines. The architecture prioritizes system stability and data integrity over aggressive optimization.
|
||||
**Our Commitment:** This document certifies that Mole implements industry-standard defensive programming practices and strictly adheres to macOS security guidelines. We prioritize system stability and data integrity above all else.
|
||||
|
||||
*For security concerns or vulnerability reports, please contact the maintainers via GitHub Issues.*
|
||||
*For security concerns or vulnerability reports, please open an issue or contact the maintainers directly.*
|
||||
|
||||
Reference in New Issue
Block a user