365 lines
8.8 KiB
Markdown
365 lines
8.8 KiB
Markdown
---
|
||
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.**
|
||
```bash
|
||
./runaway bypass
|
||
```
|
||
|
||
### `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 <token> <userId>
|
||
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 <path>` | Write logs to file (appended) |
|