rename project to runaway
This commit is contained in:
@@ -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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user