--- layout: default title: Commands Reference — runaway --- # Commands Reference ## Bypass & Suppress | Command | Description | Recovery | Booted | |---------|-------------|----------|--------| | `bypass` | Full bypass: create admin user + suppress MDM | ✓ | ✗ | | `suppress` | Suppress enrollment without creating a user | ✓ | ✓ | | `heal` | Re-apply suppression after macOS updates | ✓ | ✓ | | `persist` | Install LaunchDaemon for auto-heal on every boot | ✓ | ✓ | | `unpersist` | Remove the auto-heal LaunchDaemon | ✗ | ✓ | ### `bypass` Creates a temporary admin account and suppresses all 5 layers of MDM. **Must run from Recovery.** Credentials are prompted interactively (defaults `Apple` / `1234`); flags make it unattended (also works for `admin` and `dualboot`): ```bash ./runaway bypass --username me --password 'hunter2!' --full-name "My Name" ``` ### `suppress` Silences MDM enrollment without creating a new user. Works from both Recovery and booted systems. ```bash sudo ./runaway suppress ``` ### `heal` Re-applies suppression after macOS updates re-enable enrollment daemons. On booted systems, needs sudo. With `persist`, runs automatically on each boot. ```bash sudo ./runaway heal ``` ### `persist` Installs a LaunchDaemon that runs `heal` automatically on every boot. Survives macOS updates. ```bash sudo ./runaway persist ``` ### `unpersist` Removes the persistence LaunchDaemon. ```bash sudo ./runaway unpersist ``` --- ## Firewall & Network | Command | Description | Privilege | |---------|-------------|-----------| | `firewall` | Block Apple MDM IP ranges via pf | sudo | | `firewall-off` | Remove pf firewall MDM block | sudo | | `whitelist` | Block MDM domains only, keep iCloud/App Store | sudo | ### `firewall` Kernel-level packet filtering. Blocks Apple's entire IP range (`17.0.0.0/8`). DoH-proof — cannot be bypassed by DNS-over-HTTPS. **Warning:** Breaks iCloud, App Store, and system updates. ```bash sudo ./runaway firewall ``` ### `firewall-off` Removes pf firewall rules added by `firewall`. ```bash sudo ./runaway firewall-off ``` ### `whitelist` Resolves only MDM domains to IPs and blocks those specifically. Keeps iCloud and App Store working while blocking MDM enrollment. ```bash sudo ./runaway whitelist ``` --- ## Living System | Command | Description | Privilege | |---------|-------------|-----------| | `harden` | Kill MDM processes + remove profiles + flush DNS | sudo | | `audit` | Deep system scan with risk score | sudo | ### `harden` Kills running MDM processes, removes configuration profiles, and flushes DNS cache. Useful when MDM is actively enrolling on a booted system. ```bash sudo ./runaway harden ``` ### `audit` Performs a deep MDM scan: - Checks DEP markers - Scans for configuration profiles - Checks launch agents and daemons - Searches for MDM certificates - Generates a risk score (0–100) ```bash sudo ./runaway audit ``` --- ## Monitoring | Command | Description | |---------|-------------| | `check` | Pre-format / pre-upgrade safety report | | `monitor` | Start background MDM watcher (5 min interval) | | `monitor-install` | Install monitor as a LaunchDaemon | | `monitor-uninstall` | Remove monitor LaunchDaemon | | `monitor-stop` | Stop the monitor daemon | | `monitor-status` | Check if the monitor is running | | `history` | Show event log from monitor/heal runs | | `history-clear` | Clear the event log | ### `check` Returns **SAFE TO FORMAT** (no MDM) or **MDM DETECTED** (will lock after wipe). Also checks upgrade safety for macOS updates. ```bash sudo ./runaway check ``` ### `monitor` Background daemon that checks MDM state every 5 minutes. Sends a macOS notification if MDM tries to re-enroll. Supports optional `--webhook` for Discord alerts. ```bash sudo ./runaway monitor sudo ./runaway monitor --webhook https://discord.com/api/webhooks/... ``` ### `history` Shows the event log from previous monitor and heal runs. ```bash sudo ./runaway history ``` --- ## State Management | Command | Description | |---------|-------------| | `backup` | Save current state (hosts, profiles, launchd, settings) | | `restore` | Restore from a previous backup | | `dualboot` | Target an external macOS install | ### `backup` Saves `/etc/hosts`, MDM profile state, launchd disabled overrides, and Runaway config. ```bash sudo ./runaway backup ``` ### `restore` Reverts the system to a previously saved state. ```bash sudo ./runaway restore ``` ### `dualboot` Creates an admin account and applies suppression to an external/bootcamp volume. ```bash sudo ./runaway dualboot ``` --- ## Smart Commands (v2.0) | Command | Description | |---------|-------------| | `init` | Interactive setup wizard | | `suggest` | Risk-based system analysis and recommendations | | `remediate` | Per-org MDM cleanup | | `predict` | Serial number lookup — predict which org enrolled this Mac | | `telemetry` | Manage anonymous usage stats (opt-in) | ### `init` Interactive wizard that runs the full setup: firewall → monitor → persist → backup → audit. ```bash sudo ./runaway init ``` ### `suggest` Analyzes your system and provides risk-based recommendations. ```bash sudo ./runaway suggest ``` ### `remediate` Per-org MDM cleanup. Supports: JAMF, Mosyle, Addigy, Kandji, VMware. Auto-detects the org from your DEP record. ```bash sudo ./runaway remediate ``` ### `predict` Reads the serial number prefix and checks against known MDM org prefixes. Useful before buying a used Mac. ```bash ./runaway predict ABC12345678 ``` ### `telemetry` Manages anonymous usage stats (opt-in, OFF by default). ```bash ./runaway telemetry on ./runaway telemetry off ./runaway telemetry status ``` --- ## VPN Kill-Switch | Command | Description | |---------|-------------| | `vpn-kill` | Install pf kill-switch — blocks MDM outside VPN | | `vpn-kill-remove` | Remove the VPN kill-switch | | `vpn-kill-status` | Check VPN kill-switch state | Designed for org-provided Macs that must enroll but should only communicate while on VPN. Blocks MDM IPs when the device is NOT connected to your VPN tunnel. ```bash sudo ./runaway vpn-kill sudo ./runaway vpn-kill-status sudo ./runaway vpn-kill-remove ``` --- ## Management | Command | Description | |---------|-------------| | `update` | Self-update from the latest release | | `uninstall` | Complete removal with safety prompts | | `reinstall` | Uninstall + reinstall (persist + whitelist + monitor) | | `config` | View or edit persistent settings | | `report` | Full system report (markdown or JSON) | | `demo` | Simulated bypass flow (no real changes) | | `version` | Show version | ### `update` Downloads the latest release. GPG-verifies the signature. ```bash sudo ./runaway update ``` ### `uninstall` Removes all Runaway traces. Prompts for confirmation. ```bash sudo ./runaway uninstall ``` ### `reinstall` Uninstalls then re-applies persist + whitelist + monitor. ```bash sudo ./runaway reinstall ``` ### `config` View or edit persistent settings in `~/.runaway.conf`. ```bash ./runaway config ./runaway config show ./runaway config set key value ``` ### `report` Generates a full status report. Supports `--json` for machine-readable output. ```bash sudo ./runaway report sudo ./runaway report --json ``` ### `demo` Runs a simulated bypass flow. No real changes are made. ```bash ./runaway demo ``` --- ## Discord Bot | Command | Description | |---------|-------------| | `discord-bot` | Start Discord DM alert bot | | `discord-bot-stop` | Stop the Discord bot | | `discord-bot-status` | Check if the Discord bot is running | Sends Discord DMs when MDM activity is detected. ```bash sudo ./runaway discord-bot sudo ./runaway discord-bot-status sudo ./runaway discord-bot-stop ``` --- ## Diagnostics | Command | Description | |---------|-------------| | `doctor` | Pre-flight diagnostics — root, Recovery, libs, disk, dependencies | | `status` | MDM enrollment status (Recovery only, use `-d` for deep) | | `test` | Dry-run simulation of any command | ### `doctor` Checks: root privileges, Recovery mode detection, bash version, disk/volume availability required libraries, and internet connectivity. ```bash ./runaway doctor ``` ### `status` Shows DEP marker state, hosts file, daemon overrides. Only works from Recovery. Use `check` or `audit` on booted systems. ```bash ./runaway status ./runaway status -d ``` ### `test` Dry-run mode. Simulates a command without making real changes. ```bash ./runaway test bypass ./runaway test all ``` --- ## Aliases ``` by = bypass sv = suppress st = status ls = status fw = firewall fw-off = firewall-off wl = whitelist mn = monitor mn-install = monitor-install mn-uninstall = monitor-uninstall mn-stop = monitor-stop mn-st = monitor-status doc = doctor up = update uni = uninstall rei = reinstall vk = vpn-kill vkr = vpn-kill-remove vks = vpn-kill-status ``` --- ## Global Options | Option | Effect | |--------|--------| | `--verbose` | Show debug messages | | `--dry-run` | Simulate without making changes | | `--log-file ` | Write logs to file (appended) |