docs: expand site with multi-page guide, FAQ, scenarios, architecture deep-dive
This commit is contained in:
+15
-1
@@ -1,6 +1,20 @@
|
|||||||
title: unleash
|
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"
|
url: "https://mateussiqueira.github.io"
|
||||||
baseurl: "/unleash"
|
baseurl: "/unleash"
|
||||||
theme: jekyll-theme-cayman
|
theme: jekyll-theme-cayman
|
||||||
markdown: GFM
|
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
|
||||||
|
|||||||
+140
@@ -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)
|
||||||
+175
@@ -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)
|
||||||
+219
-39
@@ -10,7 +10,8 @@
|
|||||||
<a href="#install">Install</a> ·
|
<a href="#install">Install</a> ·
|
||||||
<a href="#quick-start">Quick Start</a> ·
|
<a href="#quick-start">Quick Start</a> ·
|
||||||
<a href="#commands">Commands</a> ·
|
<a href="#commands">Commands</a> ·
|
||||||
<a href="#how-it-works">How It Works</a> ·
|
<a href="guide">Architecture Guide</a> ·
|
||||||
|
<a href="faq">FAQ</a> ·
|
||||||
<a href="#troubleshooting">Troubleshooting</a>
|
<a href="#troubleshooting">Troubleshooting</a>
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
@@ -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.
|
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
|
## Install
|
||||||
@@ -73,6 +83,14 @@ Or to check your current status:
|
|||||||
sudo ./unleash status -d
|
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
|
## Commands
|
||||||
@@ -129,7 +147,7 @@ sudo ./unleash status -d
|
|||||||
|
|
||||||
| Command | Description |
|
| 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 |
|
| `uninstall` | Complete removal with safety prompts |
|
||||||
| `reinstall` | Uninstall + install (atomic update) |
|
| `reinstall` | Uninstall + install (atomic update) |
|
||||||
| `config` | View or edit persistent settings in `~/.unleash.conf` |
|
| `config` | View or edit persistent settings in `~/.unleash.conf` |
|
||||||
@@ -138,30 +156,108 @@ sudo ./unleash status -d
|
|||||||
| `demo` | Simulated bypass flow — no real changes |
|
| `demo` | Simulated bypass flow — no real changes |
|
||||||
| `test` | Dry-run simulation of any command |
|
| `test` | Dry-run simulation of any command |
|
||||||
| `dualboot` | Target an external or dual-boot volume |
|
| `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 |
|
| `suggest` | Risk-based system analysis and recommendations |
|
||||||
| `remediate` | Per-org MDM cleanup (JAMF, Mosyle, Kandji) |
|
| `remediate` | Per-org MDM cleanup (JAMF, Mosyle, Addigy, Kandji, VMware) |
|
||||||
| `predict` | Serial number lookup — predict org enrollment |
|
| `predict` | Serial number lookup — predict which org enrolled this Mac |
|
||||||
| `telemetry` | Manage anonymous usage stats (opt-in) |
|
| `telemetry` | Manage anonymous usage stats (opt-in) |
|
||||||
| `discord-bot` | Start Discord DM alert bot |
|
| `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
|
### Aliases
|
||||||
|
|
||||||
Every command has a short alias:
|
Every command has a short alias:
|
||||||
|
|
||||||
```
|
```
|
||||||
by = bypass fw = firewall fw-off = firewall-off
|
by = bypass fw = firewall fw-off = firewall-off
|
||||||
sv = suppress mn = monitor doc = doctor
|
sv = suppress mn = monitor doc = doctor
|
||||||
st = status up = update uni = uninstall
|
st = status up = update uni = uninstall
|
||||||
rei = reinstall vk = vpn-kill vkr = vpn-kill-remove
|
rei = reinstall vk = vpn-kill vkr = vpn-kill-remove
|
||||||
vks = vpn-kill-status
|
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 <path>` | 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
|
## 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
|
### 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.
|
The MDM enrollment process phones home to Apple's servers. Blocking these domains prevents the device from checking in.
|
||||||
|
|
||||||
**What unleash does**:
|
**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.
|
- **`/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. Installed via `firewall` command.
|
- **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
|
### 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
|
### 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
|
## Troubleshooting
|
||||||
|
|
||||||
### MDM returns after reboot
|
### MDM comes back after reboot
|
||||||
|
|
||||||
The most likely cause is user-level artifacts. Run from Recovery:
|
The most likely cause is user-level artifacts. Run from Recovery:
|
||||||
```bash
|
```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.
|
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?
|
### Can I use iCloud after bypass?
|
||||||
|
|
||||||
Yes, but:
|
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
|
- 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`
|
- 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
|
**This erases all data.** IPSW files at [ipsw.me](https://ipsw.me).
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Terminal Demo
|
## Logging
|
||||||
|
|
||||||
<img src="demo.svg" alt="unleash terminal demo" width="720">
|
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 <path>` 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)
|
- [GitHub Repository](https://github.com/mateussiqueira/unleash)
|
||||||
- [Full README](https://github.com/mateussiqueira/unleash/blob/main/README.md)
|
- [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)
|
- [Quick Reference (QUICKSTART.md)](https://github.com/mateussiqueira/unleash/blob/main/QUICKSTART.md)
|
||||||
- [Changelog](https://github.com/mateussiqueira/unleash/blob/main/CHANGELOG.md)
|
- [Changelog](https://github.com/mateussiqueira/unleash/blob/main/CHANGELOG.md)
|
||||||
- [Contributing](https://github.com/mateussiqueira/unleash/blob/main/CONTRIBUTING.md)
|
- [Contributing](https://github.com/mateussiqueira/unleash/blob/main/CONTRIBUTING.md)
|
||||||
|
|||||||
Reference in New Issue
Block a user