176 lines
7.7 KiB
Markdown
176 lines
7.7 KiB
Markdown
---
|
|
layout: default
|
|
title: Architecture Guide — runaway
|
|
---
|
|
|
|
# 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. Runaway 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.runaway/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
|
|
|
|
```
|
|
runaway/
|
|
├── runaway # 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. `runaway` loads all `lib/*.sh` modules
|
|
2. `load_config()` reads `~/.runaway.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 (`runaway-standalone.sh`, ~3200 lines). No external dependencies — runs on any macOS system with bash.
|
|
|
|
## Build Process
|
|
|
|
1. **Source**: Individual `lib/*.sh` modules + `runaway` entry point
|
|
2. **Test**: 78 Bats tests covering all modules
|
|
3. **Build**: `bash examples/build-standalone.sh` → `runaway-standalone.sh`
|
|
4. **Sign**: `scripts/sign-release.sh` → GPG detached signature
|
|
5. **Release**: GitHub release with standalone + signature + checksums
|
|
|
|
## Security Design
|
|
|
|
### No root persistence
|
|
Runaway 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)
|