From 01438e5adf4a73d09de5996b318a8b9a8259055c Mon Sep 17 00:00:00 2001 From: ruihan Date: Sat, 20 Jun 2026 17:28:10 -0300 Subject: [PATCH] docs: expand site with multi-page guide, FAQ, scenarios, architecture deep-dive --- docs/_config.yml | 16 ++- docs/faq.md | 140 +++++++++++++++++++++++++ docs/guide.md | 175 ++++++++++++++++++++++++++++++++ docs/index.md | 258 ++++++++++++++++++++++++++++++++++++++++------- 4 files changed, 549 insertions(+), 40 deletions(-) create mode 100644 docs/faq.md create mode 100644 docs/guide.md diff --git a/docs/_config.yml b/docs/_config.yml index 0d9734b..3918fe3 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -1,6 +1,20 @@ title: unleash -description: Single-script MDM bypass for macOS +description: Single-script MDM bypass for macOS — covers all 5 layers of Apple MDM enrollment url: "https://mateussiqueira.github.io" baseurl: "/unleash" theme: jekyll-theme-cayman markdown: GFM +plugins: + - jekyll-relative-links +relative_links: + enabled: true + collections: false +defaults: + - scope: + path: "" + values: + layout: "default" +header_pages: + - index.md + - guide.md + - faq.md diff --git a/docs/faq.md b/docs/faq.md new file mode 100644 index 0000000..d9b0157 --- /dev/null +++ b/docs/faq.md @@ -0,0 +1,140 @@ +--- +layout: default +title: FAQ — unleash +--- + +# FAQ + +## General + +### What macOS versions are supported? + +12.x (Monterey) through 15.x (Sequoia), 26.x (Tahoe), and 27.x. Tested on Intel T2, M1, M2, M3, M4, M5. + +### Is this the same as bypass-mdm? + +No. The original bypass-mdm scripts (v2, v3, express) only handle DEP markers and `/etc/hosts`. Unleash covers all five layers: + +- DEP markers (same as original) +- Network blocking via `/etc/hosts` (same) +- Daemon overrides (original has a basic version) +- **User-level artifact cleanup** (original does not do this) +- **Kernel-level pf firewall** (original does not do this) +- **Auto-heal daemon**, **background monitor**, **audit**, **predict**, **remediate**, and 30+ more commands + +Plus a single-file distribution, Homebrew tap, DONT.md discussions, and GPG-signed releases. + +### Do I need to disable SIP? + +No. All writes target the Data volume. The system volume is never modified. + +### Do I need internet? + +`bypass` and `suppress` do not need internet. `persist`, `firewall`, and `update` do (they download resources or contact GitHub). + +### Will this survive an OS reinstall? + +No. Clean install wipes the Data volume. Re-run `bypass` from Recovery after reinstalling. + +### Will this survive a macOS update? + +Usually yes, with `persist`. The LaunchDaemon runs `heal` automatically on the next boot after an update. Without `persist`, run `sudo ./unleash heal` manually. + +### Can the organization track this? + +The device serial stays in Apple Business Manager forever. Only the organization can remove it. If the device ever connects to the internet with full protections removed, it will re-enroll. + +### Can I use iCloud after bypass? + +Yes. Use `whitelist` instead of `firewall` or the basic `suppress`. It resolves only the essential MDM domains to IPs and blocks those, leaving iCloud, App Store, and system updates untouched. + +### Why does MDM come back after Migration Assistant? + +Migration Assistant copies user-level caches, preferences, and launch agents from the old Mac. These contain MDM enrollment artifacts that re-trigger the enrollment process. Most tools only clean system-level DEP markers — Unleash also cleans every user's Library directory. + +### Is there a GUI? + +Not yet. The CLI is the primary interface. A SwiftUI wrapper is on the [roadmap](https://github.com/mateussiqueira/unleash/blob/main/ROADMAP.md). + +### How is unleash licensed? + +MIT. Free to use, modify, and distribute. + +## Technical + +### How do I know if my Mac is enrolled in MDM? + +```bash +sudo ./unleash check +``` + +Returns SAFE TO FORMAT (no MDM) or MDM DETECTED (will lock after wipe). + +### How do I check if the bypass is still working? + +```bash +sudo ./unleash status -d +``` + +Checks DEP markers, hosts file, daemon overrides, and profile enrollment state. + +### `profiles status -v` still shows an MDM profile — why? + +Cosmetic. macOS stores the profile enrollment state on the read-only System Sealed Volume. The actual enrollment daemons are disabled and the DEP markers are gone. Trust `unleash status` over `profiles status`. + +### What's the difference between `monitor` and `persist`? + +`monitor` is a daemon that checks every 5 minutes and sends a macOS notification if MDM tries to re-enroll. `persist` is a LaunchDaemon that runs `heal` on every boot. Use both for full protection. + +### What's the difference between `firewall` and `whitelist`? + +`firewall` blocks Apple's entire IP range (breaks iCloud/App Store). `whitelist` resolves only MDM domains to IPs and blocks those (keeps iCloud/App Store working). + +### Which orgs does `remediate` support? + +JAMF, Mosyle, Addigy, Kandji, VMware Workspace ONE. It auto-detects the org from your device's DEP record and applies targeted cleanup. + +### How does `predict` work? + +It reads the serial number prefix and checks it against known MDM org prefixes (from community research). If a match is found, it predicts which organization enrolled the device. + +## Troubleshooting + +### MDM comes back after reboot + +Run from Recovery: +```bash +sudo ./unleash suppress +``` + +Or from a booted system: +```bash +sudo ./unleash harden +``` + +### "Not a known DirStatus" error + +Volume auto-detection failed. Find your Data volume: +```bash +diskutil list +diskutil mount /dev/diskXsY +./unleash bypass +``` + +### FileVault unlock fails in Recovery + +You need a user password or the FileVault recovery key. If neither is available, the Data volume cannot be mounted from Recovery. Unlock it manually in Disk Utility first. + +### "Not a macOS Data volume" + +Unleash checks for `/private/var/db/dslocal/nodes/Default` on the mounted volume. If it's missing, you mounted the wrong disk. Run `diskutil list` to find the correct Data volume. + +### Monitor won't start + +1. Check if it's already running: `sudo ./unleash monitor-status` +2. Check permissions: needs root +3. Check logs: `/var/log/unleash-monitor.log` + +--- + +[Back to home](/) · [Architecture Guide](guide) diff --git a/docs/guide.md b/docs/guide.md new file mode 100644 index 0000000..294ec40 --- /dev/null +++ b/docs/guide.md @@ -0,0 +1,175 @@ +--- +layout: default +title: Architecture Guide — unleash +--- + +# Architecture Guide + +## The Five Layers of MDM + +Apple's MDM enrollment works through five independent mechanisms. Blocking just one or two is why bypass tools fail over time. Unleash addresses all five. + +``` +Layer 1: DEP markers ─── /var/db/ConfigurationProfiles/Settings/.cloudConfig* +Layer 2: Hosts block ─── /etc/hosts → 0.0.0.0 deviceenrollment.apple.com +Layer 3: Daemons ─── launchd disabled → ManagedClient.enroll, activationd +Layer 4: User data ─── ~/Library/Preferences/com.apple.mdm.* +Layer 5: pf firewall ─── pf anchor com.unleash/mdm → kernel-level drop +``` + +### Layer 1: DEP Enrollment Markers + +When an organization assigns a device in Apple Business Manager (ABM), macOS creates marker files: + +``` +/private/var/db/ConfigurationProfiles/Settings/ + .cloudConfigHasActivationRecord ← "this serial is in ABM" + .cloudConfigRecordFound ← "we checked and enrollment was triggered" + .cloudConfigTimerCheck ← "check again later" +``` + +**Attack**: Remove all `.cloudConfig*` markers. Create decoy files (`.cloudConfigRecordNotFound`, `.cloudConfigProfileInstalled`) that tell macOS "no enrollment needed." + +**Weakness**: macOS can recreate these from cached data if the network layer is not also blocked. + +### Layer 2: Network Blocking + +The enrollment client contacts Apple servers to download the MDM profile. Without network access, it cannot complete. + +**Attack**: Add 13+ Apple MDM domains to `/etc/hosts` pointing to `0.0.0.0` and `::`: + +``` +0.0.0.0 deviceenrollment.apple.com +0.0.0.0 mdmenrollment.apple.com +0.0.0.0 iprofiles.apple.com +... +``` + +Also blocks your org's specific MDM host (extracted from the DEP record during bypass). + +**Weakness**: DNS-over-HTTPS bypasses `/etc/hosts` entirely. Chrome, Firefox, and some system services use DoH by default. + +### Layer 3: Daemon Overrides + +macOS registers four enrollment daemons that run at boot: + +| Daemon | System path | Effect when disabled | +|--------|-------------|---------------------| +| `com.apple.ManagedClient.enroll` | `/System/Library/LaunchDaemons/` | Never runs enrollment | +| `com.apple.ManagedClient.cloudConfiguration` | `/System/Library/LaunchDaemons/` | No cloud config fetch | +| `com.apple.mdmclient.daemon.runatboot` | `/System/Library/LaunchDaemons/` | MDM client stays dead | +| `com.apple.activationd` | `/System/Library/LaunchDaemons/` | Activation never starts | + +**Attack**: Create launchd disabled overrides in `/private/var/db/com.apple.xpc.launchd/disabled.plist`. This is the same mechanism macOS uses internally for `sudo launchctl disable`. + +### Layer 4: User-Level Cleanup + +Home directories carry MDM artifacts that re-trigger enrollment after login or Migration Assistant: + +``` +~/Library/Preferences/com.apple.mdm.* +~/Library/Preferences/com.apple.ManagedClient.* +~/Library/Application Support/com.apple.ManagedClient*/ +~/Library/Caches/com.apple.mdmclient +~/Library/LaunchAgents/com.apple.mdm.* +``` + +**Attack**: Scan every home directory on the Data volume. Remove all MDM-related plists, caches, and launch agents. This prevents re-enrollment when the user logs in. + +**Why this matters**: Migration Assistant copies ALL of the above. This is the #1 reason MDM returns after a successful bypass — and the step most other tools skip entirely. + +### Layer 5: pf Firewall (Kernel Level) + +`/etc/hosts` can be bypassed by: +- DNS-over-HTTPS (DoH) in Chrome/Firefox +- Cached DNS responses +- Direct IP connections + +pf (packet filter) operates at the kernel networking layer, below DNS resolution. DoH cannot bypass pf. + +**`firewall` command**: Blocks Apple's entire IP range: +``` +17.0.0.0/8 ← Apple +17.128.0.0/10 ← Apple (extended) +``` + +**`whitelist` command**: Resolves only MDM domains → IPs and blocks those specifically. iCloud/App Store continue working. + +**`vpn-kill` command**: Blocks MDM IPs when the device is NOT connected to your VPN. Useful for org-provided Macs that must enroll but should only communicate while on VPN. + +## Script Architecture + +``` +unleash/ +├── unleash # Main entry point — loads libs, dispatches commands +├── lib/ +│ ├── colors.sh # Logging, colors, prompts, show_cmd_help() +│ ├── detect.sh # Recovery detection, volume mounting +│ ├── validate.sh # Username/password validation +│ ├── dscl.sh # Directory Services (user CRUD) +│ ├── suppress.sh # DEP removal, hosts, daemon disable +│ ├── backup.sh # Backup and restore +│ ├── status.sh # Health check and audit +│ ├── heal.sh # Auto-heal + LaunchDaemon persist +│ ├── firewall.sh # pf rules management +│ ├── harden.sh # Live-OS hardening +│ ├── whitelist.sh # Selective iCloud-safe block +│ ├── check.sh # Pre-format assessment +│ ├── monitor.sh # Background MDM watcher +│ ├── config.sh # Config file read/write +│ ├── doctor.sh # Pre-flight diagnostics +│ ├── history.sh # Event log read/clear +│ ├── selfupdate.sh # GPG-verified self-update +│ ├── uninstall.sh # Complete removal +│ ├── report.sh # Full system report +│ ├── ma_detect.sh # Migration Assistant detect +│ ├── demo.sh # Simulated bypass (no changes) +│ ├── vpn.sh # VPN kill-switch pf rules +│ ├── init.sh # Setup wizard +│ ├── suggest.sh # Risk-based recommendations +│ ├── remediate.sh # Per-org cleanup +│ ├── predict.sh # Serial number lookup +│ ├── telemetry.sh # Anonymous usage stats +│ └── discord.sh # Discord DM alert bot +├── docs/ # Jekyll site (GitHub Pages) +├── tests/ # Bats tests (78 tests) +└── examples/ # build-standalone.sh, auto-bypass-usb.sh, etc. +``` + +### Dispatch Flow + +1. `unleash` loads all `lib/*.sh` modules +2. `load_config()` reads `~/.unleash.conf` (if exists) +3. Command argument is matched against the `case` dispatch in main +4. Handler function is called (e.g., `cmd_bypass`, `cmd_firewall`) +5. Each handler calls lib functions that do the actual work + +### Standalone Build + +`examples/build-standalone.sh` concatenates all lib modules + main script body into a single file (`unleash-standalone.sh`, ~3200 lines). No external dependencies — runs on any macOS system with bash. + +## Build Process + +1. **Source**: Individual `lib/*.sh` modules + `unleash` entry point +2. **Test**: 78 Bats tests covering all modules +3. **Build**: `bash examples/build-standalone.sh` → `unleash-standalone.sh` +4. **Sign**: `scripts/sign-release.sh` → GPG detached signature +5. **Release**: GitHub release with standalone + signature + checksums + +## Security Design + +### No root persistence +Unleash does not install a backdoor, create hidden users, or modify the system volume. All changes are reversible. + +### GPG-signed releases +Releases are signed with a GPG key. `selfupdate` verifies the signature before applying updates. Signature verification must pass or the update is rejected. + +### Opt-in telemetry +Telemetry is OFF by default. If enabled, it sends only anonymous counts (command run, macOS version, success/failure) — no serial numbers, IPs, or identifiable data. + +### No internet dependency +Core commands (`bypass`, `suppress`, `heal`) work entirely offline. Only `update`, `firewall` (DNS resolution), and `discord-bot` need network access. + +--- + +[Back to home](/) · [FAQ](faq) diff --git a/docs/index.md b/docs/index.md index f70a9e1..5808e0e 100644 --- a/docs/index.md +++ b/docs/index.md @@ -10,7 +10,8 @@ Install · Quick Start · Commands · - How It Works · + Architecture Guide · + FAQ · Troubleshooting

@@ -18,6 +19,15 @@ unleash replaces the original five bypass-mdm scripts with a single file that handles every layer of Apple's MDM enrollment: DEP markers, network blocking, daemon overrides, user-level artifacts, and kernel-level firewall. Works from Recovery mode on Apple Silicon and Intel. +**What makes unleash different from other bypass tools:** + +- **Covers all 5 layers** — not just DEP markers or hosts file. Kills every path MDM uses to re-enroll. +- **User-level artifact cleanup** — Migration Assistant copies MDM caches per user. Unleash cleans every home directory. +- **Kernel-level pf firewall** — `/etc/hosts` is bypassed by DNS-over-HTTPS. pf is not. +- **Auto-heal daemon** — survives macOS updates. `persist` + `heal` catches whatever the update resets. +- **39 commands** — bypass, suppress, monitor, harden, audit, backup, predict, remediate, and more. +- **macOS 12–27** — tested on Intel T2, M1, M2, M3, M4, M5. + --- ## Install @@ -73,6 +83,14 @@ Or to check your current status: sudo ./unleash status -d ``` +### One-command setup (new Mac) + +```bash +sudo ./unleash init +``` + +Interactive wizard that runs the full setup: firewall, monitor, persist, backup, and audit. + --- ## Commands @@ -129,7 +147,7 @@ sudo ./unleash status -d | Command | Description | |---------|-------------| -| `update` | Self-update from the latest GitHub release | +| `update` | Self-update from the latest GitHub release (GPG-verified) | | `uninstall` | Complete removal with safety prompts | | `reinstall` | Uninstall + install (atomic update) | | `config` | View or edit persistent settings in `~/.unleash.conf` | @@ -138,30 +156,108 @@ sudo ./unleash status -d | `demo` | Simulated bypass flow — no real changes | | `test` | Dry-run simulation of any command | | `dualboot` | Target an external or dual-boot volume | -| `init` | Interactive setup wizard | + +### Smart commands (v2.0) + +| Command | Description | +|---------|-------------| +| `init` | Interactive setup wizard — firewall, monitor, persist, backup | | `suggest` | Risk-based system analysis and recommendations | -| `remediate` | Per-org MDM cleanup (JAMF, Mosyle, Kandji) | -| `predict` | Serial number lookup — predict org enrollment | +| `remediate` | Per-org MDM cleanup (JAMF, Mosyle, Addigy, Kandji, VMware) | +| `predict` | Serial number lookup — predict which org enrolled this Mac | | `telemetry` | Manage anonymous usage stats (opt-in) | | `discord-bot` | Start Discord DM alert bot | +| `discord-bot-stop` | Stop the Discord bot | +| `discord-bot-status` | Check if the Discord bot is running | ### Aliases Every command has a short alias: ``` -by = bypass fw = firewall fw-off = firewall-off -sv = suppress mn = monitor doc = doctor -st = status up = update uni = uninstall -rei = reinstall vk = vpn-kill vkr = vpn-kill-remove -vks = vpn-kill-status +by = bypass fw = firewall fw-off = firewall-off +sv = suppress mn = monitor doc = doctor +st = status up = update uni = uninstall +rei = reinstall vk = vpn-kill vkr = vpn-kill-remove +vks = vpn-kill-status wl = whitelist +it = init su = suggest rm = remediate +pr = predict tel = telemetry db = discord-bot +dbs = discord-bot-stop dbs2 = discord-bot-status ``` +### Global options + +| Option | Effect | +|--------|--------| +| `--verbose` | Show debug messages | +| `--log-file ` | Write log output to a file | + +--- + +## Scenarios + +### Before buying a used Mac + +```bash +./unleash predict ABC12345678 # check serial against known org prefixes +./unleash check # is this Mac safe to wipe? +``` + +`predict` looks up the device serial against known MDM org prefixes. If it matches JAMF, Mosyle, or another org, you know what you're dealing with before you buy. + +### Recovery after Migration Assistant + +1. Fresh install macOS on a new Mac +2. Migration Assistant copies your old data +3. MDM appears within minutes of login + +**Fix**: Boot to Recovery and run `unleash suppress` (or `bypass` if you need a new admin user). This removes the DEP markers, user-level artifacts, and MDM preferences that MA transferred over. + +### macOS update brought MDM back + +1. System update restores enrollment daemons automatically +2. MDM block in `/etc/hosts` is often preserved + +**Fix**: `sudo ./unleash heal` — re-disables daemons and re-checks all layers. If you ran `persist` before the update, this happens automatically on the next boot. + +### Buying a former office Mac + +1. The serial might still be in the company's ABM +2. Even after a clean wipe, connecting to Wi-Fi at Setup Assistant triggers enrollment + +**Strategy**: +- Boot to Recovery without connecting to Wi-Fi +- Run `unleash bypass` before the device ever phones home +- Run `unleash persist` and `unleash whitelist` so it stays clean +- The serial stays in ABM forever — but as long as the device never connects with full protections removed, it will not re-enroll + +### Used Mac that already has a user logged in + +```bash +sudo ./unleash audit # check current state +sudo ./unleash harden # kill MDM processes immediately +sudo ./unleash whitelist # block MDM while keeping iCloud +sudo ./unleash persist # survive future updates +``` + +### Setting up a new Mac before first boot + +1. Boot to Recovery without Wi-Fi +2. Run `unleash init` — interactive wizard +3. It will: suppress MDM, install persist, install whitelist, run audit +4. Reboot, set up normally, MDM never bothers you + --- ## How It Works -MDM (Mobile Device Management) operates in four layers on macOS. Unleash blocks every layer: +MDM (Mobile Device Management) operates in five layers on macOS. Unleash blocks every layer: + +**Layer 1: DEP enrollment markers** → `/etc/hosts` block → **Layer 2: Network blocking** + +**Layer 3: Daemon overrides** → launchd disabled → **Layer 4: User-level artifacts** + +**Layer 5: pf firewall** → kernel-level, DoH-proof ### Layer 1: DEP enrollment markers @@ -174,26 +270,97 @@ In `/var/db/ConfigurationProfiles/Settings/`, Apple stores `.cloudConfig*` files The MDM enrollment process phones home to Apple's servers. Blocking these domains prevents the device from checking in. **What unleash does**: -- **`/etc/hosts`** (basic): Blocks 13+ Apple MDM domains including `deviceenrollment.apple.com`, `mdmenrollment.apple.com`, `iprofiles.apple.com`. Can be bypassed by DNS-over-HTTPS. -- **pf firewall** (advanced): Kernel-level packet filtering that blocks MDM IP ranges even when DoH is used. Installed via `firewall` command. +- **`/etc/hosts`** (basic): Blocks 13+ Apple MDM domains including `deviceenrollment.apple.com`, `mdmenrollment.apple.com`, `iprofiles.apple.com`. Both IPv4 (0.0.0.0) and IPv6 (::) entries. +- **pf firewall** (advanced): Kernel-level packet filtering that blocks MDM IP ranges even when DoH is used. + +Blocked domains: + +| Domain | Service | +|--------|---------| +| `iprofiles.apple.com` | Profile delivery | +| `deviceenrollment.apple.com` | DEP service | +| `mdmenrollment.apple.com` | MDM enrollment | +| `acmdm.apple.com` | Apple Configurator 2 MDM | +| `axm-adm-mdm.apple.com` | ACM enrollment | +| `albert.apple.com` | ABM device assignment | +| `gdmf.apple.com` | MDM framework | +| `configuration.apple.com` | Configuration service | +| `xp.apple.com` | Device management | +| `gs.apple.com` | GSM enrollment | +| `tb.apple.com` | Device trust | +| `vpp.itunes.apple.com` | Volume purchase program | + +Plus your org's specific MDM host, extracted from the DEP record. ### Layer 3: Daemon overrides -macOS ships with enrollment daemons (`ManagedClient.enroll`, `activationd`) that trigger enrollment on boot. Disabling these prevents automatic MDM checks. +macOS ships with enrollment daemons that trigger enrollment on boot: -**What unleash does**: Creates `launchd` disabled plists for 4 enrollment-related daemons, preventing them from starting. +| Daemon | Purpose | +|--------|---------| +| `com.apple.ManagedClient.enroll` | Main enrollment | +| `com.apple.ManagedClient.cloudConfiguration` | Cloud configuration | +| `com.apple.mdmclient.daemon.runatboot` | MDM client | +| `com.apple.activationd` | Device activation | + +**What unleash does**: Creates launchd disabled overrides for all four, preventing them from starting. Also disables Spotlight shortcut for Remote Management. ### Layer 4: User-level artifacts -Migration Assistant and user login caches leave MDM enrollment data in `/Users/*/Library/Preferences/` and `/Users/*/Library/Caches/`. This is the #1 reason MDM comes back after a successful bypass. +Migration Assistant and login caches leave MDM enrollment data in home directories: -**What unleash does**: Scans every user's Library directory and removes `com.apple.mdm.plist`, `com.apple.mdmclient.plist`, and `com.apple.enrollmenttool` cache. +``` +~/Library/Preferences/com.apple.mdm.* +~/Library/Preferences/com.apple.ManagedClient.* +~/Library/Application Support/com.apple.ManagedClient*/ +~/Library/LaunchAgents/com.apple.mdm.* +``` + +**What unleash does**: Scans every user's Library directory and removes all MDM-related preferences, caches, and launch agents. This is the step most other tools miss. + +### Layer 5: pf firewall (optional, advanced) + +`/etc/hosts` can be bypassed by DNS-over-HTTPS (DoH). The pf packet filter operates at the kernel level — DoH cannot bypass it. + +**`firewall` command**: Blocks Apple's entire IP range (`17.0.0.0/8` + `17.128.0.0/10`). 100% effective but breaks iCloud, App Store, and system updates. + +**`whitelist` command**: Resolves only the essential MDM domains to IPs and blocks those specifically. Keeps iCloud and App Store working. + +--- + +## Intel vs Apple Silicon + +| | Intel T2 | Apple Silicon | +|---|---|---| +| Recovery | Cmd+R at boot | Hold power button | +| System volume | Writable with SIP disabled | Read-only (SSV) | +| FileVault unlock | `diskutil apfs unlockVolume` | Same, needs user password or recovery key | +| Enrollment daemons | Fewer | `activationd` + `cloudConfiguration` | +| NVRAM flags | Some | More firmware-level flags | +| Migration Assistant | Less risky | **Carries MDM state** — always clean after | + +On Apple Silicon, all writes target the Data volume. The system volume is never modified. SIP does not need to be disabled. + +--- + +## macOS Version Support + +| Version | Codename | Status | +|---------|----------|--------| +| 12.x | Monterey | ✓ Tested | +| 13.x | Ventura | ✓ Tested | +| 14.x | Sonoma | ✓ Tested | +| 15.x | Sequoia | ✓ Tested | +| 26.x | Tahoe | ✓ Tested | +| 27.x | (current) | ✓ Tested | + +Should work on any version that uses the same MDM enrollment mechanism — which has been unchanged since Monterey. If a future macOS changes `ManagedClient.enroll`, activationd, or the DEP markers, open an issue. --- ## Troubleshooting -### MDM returns after reboot +### MDM comes back after reboot The most likely cause is user-level artifacts. Run from Recovery: ```bash @@ -226,10 +393,6 @@ Unleash will detect FileVault and prompt for the recovery key or volume password Run `sudo ./unleash heal` after any macOS update. If you used `persist` before the update, it does this automatically on next boot. -### Monitor won't start - -Check if it's already running (`monitor-status`), check permissions (needs root), and check logs at `/var/log/unleash-monitor.log`. - ### Can I use iCloud after bypass? Yes, but: @@ -237,31 +400,46 @@ Yes, but: - Use the `whitelist` command instead of `firewall` to block only MDM domains and leave iCloud/App Store working - Or manually remove those two lines from `/etc/hosts` ---- +### DFU / IPSW restore (hard lock) -## Smart Features +If MDM is unbreakable even from Recovery, the device may need a full firmware restore. This applies to Apple Silicon only. -### `suggest` — Risk-Based Recommendations +You need a second Mac with Apple Configurator 2 (free), a USB-C cable, and the IPSW file for your Mac model. -Reads your system state (DEP markers, hosts file, pf firewall, user artifacts, Configurator enrollment) and gives a risk score plus specific commands to run. +1. Open Apple Configurator 2 on the helper Mac +2. Connect the locked Mac via USB-C while holding power +3. In Configurator: right-click the DFU device → Advanced → Restore +4. Pick the IPSW file, wait 10–30 minutes +5. After restore, boot to Recovery without Wi-Fi and run `unleash bypass` -### `remediate` — Per-Org Cleanup - -Some MDM vendors (JAMF, Mosyle, Addigy, Kandji, VMware) leave vendor-specific artifacts. `remediate` auto-detects the org and applies targeted cleanup — including extra DNS blocks for their management domains. - -### `predict` — Serial Number Lookup - -Enter a serial number and unleash checks known org prefixes to predict whether a Mac was enrolled by a specific organization. Useful for buying used Macs. - -### `init` — Setup Wizard - -Walks you through first-time setup: Migration Assistant scan, Configurator check, firewall enable, monitor install, persist install, and system backup. One command to go from zero to protected. +**This erases all data.** IPSW files at [ipsw.me](https://ipsw.me). --- -## Terminal Demo +## Logging -unleash terminal demo +All commands log with timestamps and levels: + +``` +[INF] Data volume: /Volumes/Macintosh HD - Data +[ OK] Admin 'apple' created (UID 501) +[WRN] DEP activation record present +[ERR] Firewall needs sudo: sudo ./unleash firewall +[STP] Locating Data volume by APFS role... +[DBG] Checking pfctl availability +``` + +Use `--verbose` for debug messages and `--log-file ` to write everything to a file. + +--- + +## Safety + +- **No SSV writes** — all changes target the Data volume +- **Reversible** — `backup` saves state, `restore` reverts +- **No data erasure** — never runs `profiles renew` or erase commands +- **Idempotent** — running multiple times is harmless +- **Prompts for confirmation** before destructive actions --- @@ -269,6 +447,8 @@ Walks you through first-time setup: Migration Assistant scan, Configurator check - [GitHub Repository](https://github.com/mateussiqueira/unleash) - [Full README](https://github.com/mateussiqueira/unleash/blob/main/README.md) +- [Architecture Guide](guide) +- [FAQ](faq) - [Quick Reference (QUICKSTART.md)](https://github.com/mateussiqueira/unleash/blob/main/QUICKSTART.md) - [Changelog](https://github.com/mateussiqueira/unleash/blob/main/CHANGELOG.md) - [Contributing](https://github.com/mateussiqueira/unleash/blob/main/CONTRIBUTING.md)