rename project to runaway

This commit is contained in:
2026-11-09 10:13:51 +08:00
parent 20946dd445
commit 205f2faf02
95 changed files with 1034 additions and 1034 deletions
+62 -62
View File
@@ -1,8 +1,8 @@
<p align="center">
<img src="docs/icon.svg" width="120" alt="unleash logo">
<img src="docs/icon.svg" width="120" alt="runaway logo">
</p>
# unleash
# runaway
Single-script MDM bypass for macOS. Works from Recovery mode on Apple Silicon and Intel.
@@ -10,7 +10,7 @@ I started this because the original bypass-mdm project had five different script
## Quick start
1. Copy the `unleash` folder to an external SSD (FAT32, APFS, or exFAT)
1. Copy the `runaway` folder to an external SSD (FAT32, APFS, or exFAT)
2. Boot to Recovery:
- **Apple Silicon**: hold the power button until you see "Loading Startup Options", then click Options → Continue
- **Intel**: Cmd+R at the startup chime
@@ -18,14 +18,14 @@ I started this because the original bypass-mdm project had five different script
4. Run:
```bash
chmod +x "/Volumes/YourSSD/unleash/unleash"
"/Volumes/YourSSD/unleash/unleash"
chmod +x "/Volumes/YourSSD/runaway/runaway"
"/Volumes/YourSSD/runaway/runaway"
```
Pick "Full bypass" from the menu. Or if you know what you want:
```bash
"/Volumes/YourSSD/unleash/unleash" bypass
"/Volumes/YourSSD/runaway/runaway" bypass
```
No internet needed. No SIP to disable. No typing long URLs.
@@ -33,8 +33,8 @@ No internet needed. No SIP to disable. No typing long URLs.
If you do have internet in Recovery:
```bash
curl -L https://raw.githubusercontent.com/mateussiqueira/unleash/main/unleash-standalone.sh -o /tmp/unleash
chmod +x /tmp/unleash && /tmp/unleash bypass
curl -L https://raw.githubusercontent.com/mateussiqueira/runaway/main/runaway-standalone.sh -o /tmp/runaway
chmod +x /tmp/runaway && /tmp/runaway bypass
```
---
@@ -44,7 +44,7 @@ chmod +x /tmp/unleash && /tmp/unleash bypass
### bypass — Full MDM bypass (Recovery only)
```bash
./unleash bypass
./runaway bypass
```
Creates a temporary admin account and suppresses MDM. What it does:
@@ -61,7 +61,7 @@ Creates a temporary admin account and suppresses MDM. What it does:
### suppress — Silence enrollment, no user
```bash
./unleash suppress
./runaway suppress
```
Same as bypass minus the user creation. Useful after a clean bypass breaks from a macOS update.
@@ -69,7 +69,7 @@ Same as bypass minus the user creation. Useful after a clean bypass breaks from
### admin — Create admin user only (Recovery only)
```bash
./unleash admin
./runaway admin
```
Creates a hidden local administrator account on the system without performing an MDM bypass or suppression. What it does:
@@ -84,8 +84,8 @@ Creates a hidden local administrator account on the system without performing an
### heal — Check and re-apply
```bash
sudo ./unleash heal # from booted system
./unleash heal # from Recovery
sudo ./runaway heal # from booted system
./runaway heal # from Recovery
```
Checks if suppression is still intact. If any piece (DEP markers, hosts block, daemon disable) has been reset, it re-applies it. Safe to run repeatedly.
@@ -93,17 +93,17 @@ Checks if suppression is still intact. If any piece (DEP markers, hosts block, d
### persist — Boot-time auto-heal
```bash
sudo ./unleash persist
sudo ./runaway persist
```
Installs a LaunchDaemon at `/Library/LaunchDaemons/com.unleash.heal.plist` that runs `unleash heal` on every boot and every 24 hours after that. Logs go to `/var/log/unleash-heal.log`.
Installs a LaunchDaemon at `/Library/LaunchDaemons/com.runaway.heal.plist` that runs `runaway heal` on every boot and every 24 hours after that. Logs go to `/var/log/runaway-heal.log`.
Use this before a macOS upgrade. When the update finishes and reboots, heal runs automatically and re-applies anything the update reset.
### unpersist — Remove auto-heal
```bash
sudo ./unleash unpersist
sudo ./runaway unpersist
```
Removes the LaunchDaemon and unloads it.
@@ -111,7 +111,7 @@ Removes the LaunchDaemon and unloads it.
### firewall — Kernel-level MDM block
```bash
sudo ./unleash firewall
sudo ./runaway firewall
```
Creates pf firewall rules that drop traffic to Apple's MDM IP ranges (17.0.0.0/8 and 17.128.0.0/10). pf works below DNS — DNS-over-HTTPS cannot bypass it.
@@ -121,15 +121,15 @@ Creates pf firewall rules that drop traffic to Apple's MDM IP ranges (17.0.0.0/8
### firewall-off — Remove firewall
```bash
sudo ./unleash firewall-off
sudo ./runaway firewall-off
```
Flushes the Unleash pf anchor and restores pf.conf.
Flushes the Runaway pf anchor and restores pf.conf.
### whitelist — Block only MDM, keep iCloud
```bash
sudo ./unleash whitelist
sudo ./runaway whitelist
```
Alternative to `firewall` that resolves only the essential MDM domains (mdmenrollment.apple.com, deviceenrollment.apple.com, iprofiles.apple.com) to IPs and blocks those, leaving everything else untouched. iCloud, App Store, and updates should work normally.
@@ -137,7 +137,7 @@ Alternative to `firewall` that resolves only the essential MDM domains (mdmenrol
### harden — Live cleanup from booted system
```bash
sudo ./unleash harden
sudo ./runaway harden
```
Runs from the logged-in desktop after bypass. Does:
@@ -153,7 +153,7 @@ Runs from the logged-in desktop after bypass. Does:
### audit — Deep system scan
```bash
sudo ./unleash audit
sudo ./runaway audit
```
Comprehensive scan that checks: installed profiles, enrollment state, keychain certificates, user LaunchAgents, system LaunchDaemons, running processes, MDM agent binaries, pf firewall status. Ends with a risk score (LOW / MEDIUM / HIGH / CRITICAL).
@@ -161,7 +161,7 @@ Comprehensive scan that checks: installed profiles, enrollment state, keychain c
### status — MDM health check (Recovery only)
```bash
./unleash status
./runaway status
```
Shows DEP markers, hosts block, daemon overrides, profile enrollment, and backup status. Only works from Recovery because that's where the Data volume is cleanly accessible.
@@ -169,7 +169,7 @@ Shows DEP markers, hosts block, daemon overrides, profile enrollment, and backup
### check — Pre-format / pre-upgrade assessment
```bash
sudo ./unleash check
sudo ./runaway check
```
Answers: **"If I wipe this Mac, will it lock?"** Checks DEP records, profiles, enrollment state, firewall, and persistence. Also does an upgrade safety check — tells you if `persist` and `firewall` are installed before you upgrade macOS.
@@ -182,31 +182,31 @@ Returns one of two verdicts:
### monitor — Background MDM watcher
```bash
sudo ./unleash monitor
sudo ./runaway monitor
```
Starts a daemon that checks MDM state every 5 minutes. If it detects MDM trying to re-enroll (DEP record appears, hosts block missing, enrollment becomes active), it auto-heals and sends a macOS notification.
```bash
sudo ./unleash monitor-stop # stop it
sudo ./unleash monitor-status # check if it's running
sudo ./runaway monitor-stop # stop it
sudo ./runaway monitor-status # check if it's running
```
Logs everything to `/var/log/unleash-monitor.log`. The daemon does not survive a reboot on its own — combine with `persist` for persistence.
Logs everything to `/var/log/runaway-monitor.log`. The daemon does not survive a reboot on its own — combine with `persist` for persistence.
### backup / restore — State save
```bash
./unleash backup
./unleash restore
./runaway backup
./runaway restore
```
Backup saves hosts, config profiles, and launchd override to `.unleash-backup/`. Restore reverts them.
Backup saves hosts, config profiles, and launchd override to `.runaway-backup/`. Restore reverts them.
### dualboot — External volume target
```bash
sudo ./unleash dualboot
sudo ./runaway dualboot
```
Same as bypass but lets you pick which volume to target (for external macOS installs or dual-boot setups). Prompts for system and data volume names.
@@ -214,8 +214,8 @@ Same as bypass but lets you pick which volume to target (for external macOS inst
### version / help
```bash
./unleash version
./unleash help
./runaway version
./runaway help
```
---
@@ -249,14 +249,14 @@ Global options that can go before any command:
Example:
```bash
sudo ./unleash --verbose --log-file /tmp/unleash.log heal
sudo ./runaway --verbose --log-file /tmp/runaway.log heal
```
---
## How it works
MDM enrollment on macOS sits on four layers. Unleash addresses each one.
MDM enrollment on macOS sits on four layers. Runaway addresses each one.
### Layer 1: DEP activation record
@@ -269,13 +269,13 @@ When an organization assigns a device in Apple Business Manager, macOS creates m
.cloudConfigTimerCheck ← "check again later"
```
Unleash removes these and creates decoy files (`.cloudConfigRecordNotFound`, `.cloudConfigProfileInstalled`) that signal "no enrollment needed."
Runaway removes these and creates decoy files (`.cloudConfigRecordNotFound`, `.cloudConfigProfileInstalled`) that signal "no enrollment needed."
### Layer 2: Network blocking
The enrollment client contacts Apple servers to download the MDM profile. Without network access, it cannot complete enrollment.
Unleash blocks via `/etc/hosts`:
Runaway blocks via `/etc/hosts`:
- `iprofiles.apple.com` — profile delivery
- `deviceenrollment.apple.com` — DEP service
@@ -308,7 +308,7 @@ macOS registers enrollment daemons that run at boot:
| `com.apple.mdmclient.daemon.runatboot` | MDM client |
| `com.apple.activationd` | Device activation |
Unleash disables them via the launchd override at `/private/var/db/com.apple.xpc.launchd/disabled.plist`.
Runaway disables them via the launchd override at `/private/var/db/com.apple.xpc.launchd/disabled.plist`.
### Layer 4: User-level cleanup
@@ -321,11 +321,11 @@ Home directories carry MDM artifacts that trigger re-enrollment after login:
~/Library/LaunchAgents/com.apple.mdm.*
```
Unleash removes these from every home directory on the Data volume. This is the step most scripts miss — and the reason MDM comes back after Migration Assistant.
Runaway removes these from every home directory on the Data volume. This is the step most scripts miss — and the reason MDM comes back after Migration Assistant.
### Layer 5: pf firewall (optional)
The hosts file can be bypassed by DNS-over-HTTPS or cached DNS. pf (packet filter) operates at the kernel level and is immune to both. Unleash installs pf rules that either:
The hosts file can be bypassed by DNS-over-HTTPS or cached DNS. pf (packet filter) operates at the kernel level and is immune to both. Runaway installs pf rules that either:
- **firewall**: blocks Apple's entire IP range (17.0.0.0/8 + 17.128.0.0/10) — aggressive but 100% effective
- **whitelist**: resolves only MDM domains to IPs and blocks those specifically — keeps iCloud working
@@ -365,11 +365,11 @@ The old bypass scripts only clean system-level artifacts (DEP markers, hosts, la
### Solution
**From Recovery**: run `unleash bypass` (or `suppress`). This cleans both system-level and user-level artifacts.
**From Recovery**: run `runaway bypass` (or `suppress`). This cleans both system-level and user-level artifacts.
**If MDM still comes back**: boot normally, run `sudo ./unleash harden` immediately after login. This kills active MDM processes and removes profiles before they can re-establish.
**If MDM still comes back**: boot normally, run `sudo ./runaway harden` immediately after login. This kills active MDM processes and removes profiles before they can re-establish.
**For prevention**: run `sudo ./unleash persist` and `sudo ./unleash whitelist` before Migration Assistant. The LaunchDaemon + pf rules survive the migration and catch anything that slips through.
**For prevention**: run `sudo ./runaway persist` and `sudo ./runaway whitelist` before Migration Assistant. The LaunchDaemon + pf rules survive the migration and catch anything that slips through.
## Hard lock: DFU / IPSW restore
@@ -386,7 +386,7 @@ If MDM is unbreakable — even from Recovery — the device may need a full firm
4. Right-click → Advanced → Restore (pick the IPSW file)
5. Wait 10-30 minutes for restore to finish
6. Mac reboots to Setup Assistant — **do not connect to Wi-Fi**
7. Immediately boot to Recovery (hold power) and run `unleash bypass`
7. Immediately boot to Recovery (hold power) and run `runaway bypass`
**This erases all data.** IPSW files are available at [ipsw.me](https://ipsw.me).
@@ -398,7 +398,7 @@ All commands now 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
[ERR] Firewall needs sudo: sudo ./runaway firewall
[STP] Locating Data volume by APFS role...
[DBG] Checking pfctl availability
```
@@ -408,8 +408,8 @@ Use `--verbose` to see debug messages and `--log-file <path>` to write everythin
## Files
```
unleash/
├── unleash # Main script (entry point)
runaway/
├── runaway # Main script (entry point)
├── lib/
│ ├── colors.sh # Logging, colors, prompts
│ ├── detect.sh # Recovery detection, volume mounting
@@ -432,7 +432,7 @@ unleash/
└── LICENSE (MIT)
```
The standalone variant (`unleash-standalone.sh`) bundles everything into one file. Build it with `bash examples/build-standalone.sh`.
The standalone variant (`runaway-standalone.sh`) bundles everything into one file. Build it with `bash examples/build-standalone.sh`.
## Limitations
@@ -444,7 +444,7 @@ The standalone variant (`unleash-standalone.sh`) bundles everything into one fil
## Safety
Unleash is designed to be safe:
Runaway is designed to be safe:
- **No SSV writes** — all changes target the Data volume
- **Reversible** — `backup` saves state, `restore` reverts
@@ -455,26 +455,26 @@ Unleash is designed to be safe:
## Troubleshooting
### MDM comes back after reboot
Run `unleash suppress` from Recovery. If it still returns, you have Migration Assistant artifacts. Run `unleash harden` from the booted system.
Run `runaway suppress` from Recovery. If it still returns, you have Migration Assistant artifacts. Run `runaway harden` from the booted system.
### profiles shows enrollment
Cosmetic. The SSV stores profile state but the enrollment daemons are disabled. Run `unleash status` to check the actual state on the Data volume.
Cosmetic. The SSV stores profile state but the enrollment daemons are disabled. Run `runaway status` to check the actual state on the Data volume.
### FileVault unlock fails
You need a user password or the FileVault recovery key. If neither is available, the Data volume cannot be mounted from Recovery.
### "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 one.
Runaway 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 one.
### macOS 27 and later
[#22](https://github.com/mateussiqueira/unleash/issues/22) contains two positive
[#22](https://github.com/mateussiqueira/runaway/issues/22) contains two positive
community reports for macOS 27.2:
- The [original reporter](https://github.com/mateussiqueira/unleash/issues/22#issuecomment-6522921874)
reports Unleash 2.0.0 working on an M1 Pro after upgrading an existing Sequoia
- The [original reporter](https://github.com/mateussiqueira/runaway/issues/22#issuecomment-6522921874)
reports Runaway 2.0.0 working on an M1 Pro after upgrading an existing Sequoia
setup. This was not a fresh installation.
- [Another user](https://github.com/mateussiqueira/unleash/issues/22#issuecomment-6520816615)
- [Another user](https://github.com/mateussiqueira/runaway/issues/22#issuecomment-6520816615)
reports basic commands working on a MacBook Neo (Apple A18 Pro).
These reports answer the original question but do not establish support for every
@@ -483,11 +483,11 @@ matrix. Shell regression tests are separate from hardware validation.
### Wi-Fi on an external startup disk
[#24](https://github.com/mateussiqueira/unleash/issues/24) remains under
[#24](https://github.com/mateussiqueira/runaway/issues/24) remains under
investigation. From the affected external installation, run:
```bash
./unleash doctor --network
./runaway doctor --network
```
This read-only command reports the macOS build, Wi-Fi interface, power, link, and
@@ -501,7 +501,7 @@ A failed query is reported separately from a successful query with no Wi-Fi port
Include the script commit, Mac model, exact OS build, SSD/cable/hub connection,
and whether Wi-Fi worked on that same external installation before running
Unleash, if known. Working Wi-Fi on the internal installation alone does not
Runaway, if known. Working Wi-Fi on the internal installation alone does not
isolate what changed on the external one.
The `dualboot` code does not directly rewrite Wi-Fi preferences or toggle the
@@ -515,7 +515,7 @@ disk cables or hubs, shut down before changing their connections; do not unplug
the active startup disk.
### Monitor won't start
Check if it's already running (`monitor-status`). Check permissions — it needs root. Check logs at `/var/log/unleash-monitor.log`.
Check if it's already running (`monitor-status`). Check permissions — it needs root. Check logs at `/var/log/runaway-monitor.log`.
## FAQ
@@ -538,7 +538,7 @@ The serial stays in ABM. If the device connects to the internet with enrollment
Use `whitelist` instead of `firewall` or `suppress`. It blocks only MDM endpoints.
**Why does MDM come back after Migration Assistant?**
MA copies user-level caches, preferences, and launch agents. Unleash handles this — run `bypass` or `suppress` from Recovery after migrating.
MA copies user-level caches, preferences, and launch agents. Runaway handles this — run `bypass` or `suppress` from Recovery after migrating.
## Contributing