docs: add search, sidebar nav, dedicated pages, PT translations

This commit is contained in:
2026-06-24 11:19:43 -03:00
parent 3d8f02e526
commit e0f2026a2f
19 changed files with 1926 additions and 6 deletions
+1
View File
@@ -2,3 +2,4 @@
*.swp
*.swo
.DS_Store
.vercel
+1
View File
@@ -1,3 +1,4 @@
source "https://rubygems.org"
gem "jekyll", "~> 4.3"
gem "jekyll-theme-cayman"
gem "jekyll-relative-links"
+3 -3
View File
@@ -1,9 +1,9 @@
title: unleash
description: Single-script MDM bypass for macOS — covers all 5 layers of Apple MDM enrollment
url: "https://mateussiqueira.github.io"
baseurl: "/unleash"
url: "https://unleash-nine.vercel.app"
baseurl: ""
theme: jekyll-theme-cayman
markdown: GFM
markdown: kramdown
plugins:
- jekyll-relative-links
relative_links:
+31 -2
View File
@@ -8,15 +8,43 @@
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="theme-color" content="#157878">
<meta name="apple-mobile-web-app-status-bar-style" content="black-translucent">
<link rel="stylesheet" href="{{ '/assets/css/style.css?v=' | append: site.github.build_revision | relative_url }}">
<link rel="stylesheet" href="{{ '/assets/css/style.css' | relative_url }}">
{% include head-custom.html %}
<style>
.lang-toggle{position:fixed;top:12px;right:12px;z-index:1000;display:flex;gap:2px;background:#fff;border:1px solid #d0d7de;border-radius:6px;overflow:hidden;box-shadow:0 1px 3px rgba(0,0,0,.12)}.lang-toggle a{padding:4px 10px;font-size:13px;font-weight:500;text-decoration:none;color:#656d76;transition:background .15s,color .15s}.lang-toggle a:hover{background:#0969da;color:#fff}.lang-toggle a.active{background:#0969da;color:#fff;cursor:default}@media(prefers-color-scheme:dark){.lang-toggle{background:#161b22;border-color:#30363d}.lang-toggle a{color:#8b949e}.lang-toggle a:hover{background:#1f6feb;color:#fff}.lang-toggle a.active{background:#1f6feb;color:#fff;cursor:default}}
:root{--nav-w:220px}@media(min-width:64em){.main-content{margin-left:var(--nav-w);max-width:calc(64rem - var(--nav-w))}.nav{position:fixed;top:0;left:0;width:var(--nav-w);height:100vh;background:#f6f8fa;border-right:1px solid #d0d7de;padding:1rem;overflow-y:auto;z-index:999;font-size:14px}}@media(max-width:64em){.nav{display:none}}.nav a{display:block;padding:4px 8px;color:#24292f;text-decoration:none;border-radius:4px;margin-bottom:2px}.nav a:hover{background:#ddf4ff}.nav a.active{background:#0969da;color:#fff;font-weight:600}.nav h3{font-size:11px;text-transform:uppercase;letter-spacing:1px;color:#656d76;margin:16px 0 4px 8px}.nav .logo{font-size:18px;font-weight:700;color:#159957;padding:8px;margin-bottom:8px;text-decoration:none;border-bottom:1px solid #d0d7de}#search-wrap{position:relative;margin:0 0 12px 8px}#search-input{width:calc(100% - 16px);padding:6px 8px;border:1px solid #d0d7de;border-radius:6px;font-size:13px;background:#fff}#search-input:focus{outline:none;border-color:#0969da}#search-results{display:none;position:absolute;top:100%;left:0;right:0;background:#fff;border:1px solid #d0d7de;border-radius:6px;box-shadow:0 4px 12px rgba(0,0,0,.15);z-index:1001;max-height:300px;overflow-y:auto}.search-result-item{padding:8px;border-bottom:1px solid #f0f0f0;cursor:pointer}.search-result-item:last-child{border-bottom:none}.search-result-item:hover{background:#f6f8fa}.search-result-item strong{display:block;font-size:13px;color:#0969da}.search-snippet{font-size:11px;color:#656d76;display:block;margin-top:2px;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
</style>
</head>
<body>
<a id="skip-to-content" href="#content">Skip to the content.</a>
<nav class="nav" role="navigation" aria-label="Documentation navigation">
<a href="/" class="logo" data-pt="/pt/">unleash</a>
<div id="search-wrap">
<input type="text" id="search-input" placeholder="Search docs..." autocomplete="off">
<div id="search-results"></div>
</div>
<h3>Getting Started</h3>
<a href="/" data-pt="/pt/">Home</a>
<a href="/install" data-pt="/pt/install">Installation</a>
<a href="/commands" data-pt="/pt/commands">Commands</a>
<h3>Guides</h3>
<a href="/guide" data-pt="/pt/guide">Architecture Guide</a>
<a href="/scenarios" data-pt="/pt/scenarios">Scenarios</a>
<h3>Reference</h3>
<a href="/troubleshooting" data-pt="/pt/troubleshooting">Troubleshooting</a>
<a href="/faq" data-pt="/pt/faq">FAQ</a>
<a href="/security" data-pt="/pt/security">Security</a>
<h3>External</h3>
<a href="https://github.com/mateussiqueira/unleash" target="_blank">GitHub</a>
<a href="https://github.com/mateussiqueira/unleash/blob/main/CHANGELOG.md" target="_blank">Changelog</a>
</nav>
<header class="page-header" role="banner">
<h1 class="project-name">{{ page.title | default: site.title | default: site.github.repository_name }}</h1>
<h2 class="project-tagline">{{ page.description | default: site.description | default: site.github.project_tagline }}</h2>
@@ -45,8 +73,9 @@
<a href="#" data-lang="pt">PT</a>
</div>
<script src="{{ '/assets/js/search.js' | relative_url }}"></script>
<script>
(function(){var p=window.location.pathname.replace(/\/unleash/,'')||'/';var i=p.startsWith('/pt');var e=p.replace(/^\/pt/,'')||'/';var t='/pt'+(p==='/'||p==='/pt'?'':p.replace(/^\/pt/,''))||'/pt/';document.querySelectorAll('.lang-toggle a').forEach(function(l){var n=l.getAttribute('data-lang');l.href='/unleash'+(n==='en'?e:t).replace(/\/+/g,'/');if((n==='en'&&!i)||(n==='pt'&&i))l.classList.add('active')})})();
(function(){var p=window.location.pathname.replace(/\/$/,'')||'/';var i=p.startsWith('/pt');var e=i?p.replace(/^\/pt/,'')||'/':p;var t='/pt'+p;document.querySelectorAll('.lang-toggle a').forEach(function(l){var n=l.getAttribute('data-lang');l.href=n==='en'?e:t;if((n==='en'&&!i)||(n==='pt'&&i))l.classList.add('active')});if(i){document.querySelectorAll('.nav a[data-pt]').forEach(function(a){a.href=a.getAttribute('data-pt')})}var c=document.querySelector('.nav a[href="'+p+'"],.nav a[href="'+p+'.html"]');if(!c&&i){var en=p.replace(/^\/pt/,'')||'/';c=document.querySelector('.nav a[href="'+en+'"],.nav a[href="'+en+'.html"]')}if(c)c.classList.add('active')})();
</script>
</body>
</html>
+50
View File
@@ -0,0 +1,50 @@
(function () {
var searchInput = document.getElementById("search-input");
var searchResults = document.getElementById("search-results");
if (!searchInput) return;
var searchData = [];
fetch("/search.json")
.then(function (r) { return r.json(); })
.then(function (data) { searchData = data; })
.catch(function () {});
searchInput.addEventListener("input", function () {
var query = searchInput.value.trim().toLowerCase();
if (query.length < 2) {
searchResults.innerHTML = "";
searchResults.style.display = "none";
return;
}
var results = searchData.filter(function (item) {
return item.title.toLowerCase().indexOf(query) !== -1 ||
item.content.toLowerCase().indexOf(query) !== -1;
}).slice(0, 10);
if (results.length === 0) {
searchResults.innerHTML = '<div class="search-result-item">No results found</div>';
} else {
var html = "";
results.forEach(function (item) {
var idx = item.content.toLowerCase().indexOf(query);
var snippet = idx === -1
? item.content.slice(0, 120)
: "…" + item.content.slice(Math.max(0, idx - 40), idx + 80) + "…";
html += '<a href="' + item.url + '" class="search-result-item">' +
'<strong>' + item.title + '</strong>' +
'<span class="search-snippet">' + snippet + '</span>' +
'</a>';
});
searchResults.innerHTML = html;
}
searchResults.style.display = "block";
});
document.addEventListener("click", function (e) {
if (!searchInput.contains(e.target) && !searchResults.contains(e.target)) {
searchResults.style.display = "none";
}
});
})();
+364
View File
@@ -0,0 +1,364 @@
---
layout: default
title: Commands Reference — unleash
---
# 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
./unleash bypass
```
### `suppress`
Silences MDM enrollment without creating a new user.
Works from both Recovery and booted systems.
```bash
sudo ./unleash 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 ./unleash heal
```
### `persist`
Installs a LaunchDaemon that runs `heal` automatically on every boot.
Survives macOS updates.
```bash
sudo ./unleash persist
```
### `unpersist`
Removes the persistence LaunchDaemon.
```bash
sudo ./unleash 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 ./unleash firewall
```
### `firewall-off`
Removes pf firewall rules added by `firewall`.
```bash
sudo ./unleash 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 ./unleash 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 ./unleash 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 ./unleash 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 ./unleash 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 ./unleash monitor
sudo ./unleash monitor --webhook https://discord.com/api/webhooks/...
```
### `history`
Shows the event log from previous monitor and heal runs.
```bash
sudo ./unleash 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 Unleash config.
```bash
sudo ./unleash backup
```
### `restore`
Reverts the system to a previously saved state.
```bash
sudo ./unleash restore
```
### `dualboot`
Creates an admin account and applies suppression to an external/bootcamp volume.
```bash
sudo ./unleash 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 ./unleash init
```
### `suggest`
Analyzes your system and provides risk-based recommendations.
```bash
sudo ./unleash suggest
```
### `remediate`
Per-org MDM cleanup. Supports: JAMF, Mosyle, Addigy, Kandji, VMware.
Auto-detects the org from your DEP record.
```bash
sudo ./unleash remediate
```
### `predict`
Reads the serial number prefix and checks against known MDM org prefixes.
Useful before buying a used Mac.
```bash
./unleash predict ABC12345678
```
### `telemetry`
Manages anonymous usage stats (opt-in, OFF by default).
```bash
./unleash telemetry on
./unleash telemetry off
./unleash 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 ./unleash vpn-kill
sudo ./unleash vpn-kill-status
sudo ./unleash vpn-kill-remove
```
---
## Management
| Command | Description |
|---------|-------------|
| `update` | Self-update from the latest GitHub 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 from GitHub. GPG-verifies the signature.
```bash
sudo ./unleash update
```
### `uninstall`
Removes all Unleash traces. Prompts for confirmation.
```bash
sudo ./unleash uninstall
```
### `reinstall`
Uninstalls then re-applies persist + whitelist + monitor.
```bash
sudo ./unleash reinstall
```
### `config`
View or edit persistent settings in `~/.unleash.conf`.
```bash
./unleash config
./unleash config show
./unleash config set key value
```
### `report`
Generates a full status report. Supports `--json` for machine-readable output.
```bash
sudo ./unleash report
sudo ./unleash report --json
```
### `demo`
Runs a simulated bypass flow. No real changes are made.
```bash
./unleash 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 ./unleash discord-bot <token> <userId>
sudo ./unleash discord-bot-status
sudo ./unleash 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
./unleash doctor
```
### `status`
Shows DEP marker state, hosts file, daemon overrides.
Only works from Recovery. Use `check` or `audit` on booted systems.
```bash
./unleash status
./unleash status -d
```
### `test`
Dry-run mode. Simulates a command without making real changes.
```bash
./unleash test bypass
./unleash 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) |
+6
View File
@@ -1,3 +1,9 @@
---
layout: default
title: unleash
description: Single-script MDM bypass for macOS — covers all 5 layers of Apple MDM enrollment
---
<p align="center">
<img src="icon.svg" width="100" alt="unleash logo">
<br>
+58
View File
@@ -0,0 +1,58 @@
---
layout: default
title: Installation — unleash
---
# Installation
## Homebrew (easiest)
```bash
brew tap mateussiqueira/unleash
brew install unleash
```
Or in one step:
```bash
brew install mateussiqueira/unleash/unleash
```
## Direct download
```bash
curl -L https://raw.githubusercontent.com/mateussiqueira/unleash/main/unleash-standalone.sh -o unleash
chmod +x unleash
sudo ./unleash init
```
## From a USB drive (for Recovery mode)
1. Format a USB/SSD as **FAT32**, **APFS**, or **exFAT**
2. Copy the `unleash` folder (or just `unleash-standalone.sh`) to the drive
3. Boot to Recovery and run from `/Volumes/YourDrive/unleash`
## Via curl in Recovery (needs internet)
```bash
curl -L https://raw.githubusercontent.com/mateussiqueira/unleash/main/unleash -o /tmp/unleash
chmod +x /tmp/unleash && /tmp/unleash bypass
```
## Building from source
```bash
git clone https://github.com/mateussiqueira/unleash.git
cd unleash
bash examples/build-standalone.sh
# Output: unleash-standalone.sh (~3200 lines)
```
## Verifying the installation
```bash
./unleash version
# → unleash v2.0.0
./unleash doctor
# Runs pre-flight diagnostics
```
+364
View File
@@ -0,0 +1,364 @@
---
layout: default
title: Referência de Comandos — unleash
---
# Referência de Comandos
## Bypass & Suppress
| Comando | Descrição | Recovery | Iniciado |
|---------|-----------|----------|----------|
| `bypass` | Bypass completo: cria usuário admin + suprime MDM | ✓ | ✗ |
| `suppress` | Suprime registro sem criar um usuário | ✓ | ✓ |
| `heal` | Reaplica supressão após atualizações do macOS | ✓ | ✓ |
| `persist` | Instala LaunchDaemon para auto-recuperação na inicialização | ✓ | ✓ |
| `unpersist` | Remove o LaunchDaemon de auto-recuperação | ✗ | ✓ |
### `bypass`
Cria uma conta admin temporária e suprime todas as 5 camadas do MDM.
**Deve executar do Recovery.**
```bash
./unleash bypass
```
### `suppress`
Silencia o registro MDM sem criar um novo usuário.
Funciona tanto do Recovery quanto do sistema já iniciado.
```bash
sudo ./unleash suppress
```
### `heal`
Reaplica a supressão após atualizações do macOS reativarem os daemons de registro.
Em sistemas já iniciados, precisa de sudo. Com `persist`, executa automaticamente em cada inicialização.
```bash
sudo ./unleash heal
```
### `persist`
Instala um LaunchDaemon que executa `heal` automaticamente em cada inicialização.
Sobrevive a atualizações do macOS.
```bash
sudo ./unleash persist
```
### `unpersist`
Remove o LaunchDaemon de persistência.
```bash
sudo ./unleash unpersist
```
---
## Firewall & Rede
| Comando | Descrição | Privilégio |
|---------|-----------|------------|
| `firewall` | Bloqueia faixas de IP Apple MDM via pf | sudo |
| `firewall-off` | Remove o bloqueio pf do MDM | sudo |
| `whitelist` | Bloqueia apenas domínios MDM, mantém iCloud/App Store | sudo |
### `firewall`
Filtragem de pacotes a nível de kernel. Bloqueia toda a faixa de IP da Apple (`17.0.0.0/8`).
À prova de DoH — não pode ser contornado por DNS-over-HTTPS.
**Aviso:** Quebra iCloud, App Store e atualizações do sistema.
```bash
sudo ./unleash firewall
```
### `firewall-off`
Remove as regras pf adicionadas por `firewall`.
```bash
sudo ./unleash firewall-off
```
### `whitelist`
Resolve apenas domínios MDM para IPs e bloqueia especificamente aqueles.
Mantém iCloud e App Store funcionando enquanto bloqueia o registro MDM.
```bash
sudo ./unleash whitelist
```
---
## Sistema em Execução
| Comando | Descrição | Privilégio |
|---------|-----------|------------|
| `harden` | Mata processos MDM + remove perfis + limpa DNS | sudo |
| `audit` | Varredura profunda do sistema com score de risco | sudo |
### `harden`
Mata processos MDM em execução, remove perfis de configuração e limpa o cache DNS.
Útil quando o MDM está registrando ativamente em um sistema já iniciado.
```bash
sudo ./unleash harden
```
### `audit`
Executa uma varredura MDM profunda:
- Verifica marcadores DEP
- Escaneia perfis de configuração
- Verifica launch agents e daemons
- Procura certificados MDM
- Gera um score de risco (0–100)
```bash
sudo ./unleash audit
```
---
## Monitoramento
| Comando | Descrição |
|---------|-----------|
| `check` | Relatório de segurança pré-formatação/pré-atualização |
| `monitor` | Inicia vigia MDM em segundo plano (intervalo de 5 min) |
| `monitor-install` | Instala o monitor como um LaunchDaemon |
| `monitor-uninstall` | Remove o LaunchDaemon do monitor |
| `monitor-stop` | Para o daemon do monitor |
| `monitor-status` | Verifica se o monitor está rodando |
| `history` | Mostra o log de eventos do monitor/heal |
| `history-clear` | Limpa o log de eventos |
### `check`
Retorna **SAFE TO FORMAT** (sem MDM) ou **MDM DETECTED** (vai travar após limpar).
Também verifica segurança para atualizações do macOS.
```bash
sudo ./unleash check
```
### `monitor`
Daemon em segundo plano que verifica o estado do MDM a cada 5 minutos.
Envia uma notificação do macOS se o MDM tentar re-registrar.
Suporta `--webhook` opcional para alertas no Discord.
```bash
sudo ./unleash monitor
sudo ./unleash monitor --webhook https://discord.com/api/webhooks/...
```
### `history`
Mostra o log de eventos de execuções anteriores do monitor e heal.
```bash
sudo ./unleash history
```
---
## Gerenciamento de Estado
| Comando | Descrição |
|---------|-----------|
| `backup` | Salva o estado atual (hosts, perfis, launchd, configurações) |
| `restore` | Restaura a partir de um backup anterior |
| `dualboot` | Mira uma instalação macOS externa |
### `backup`
Salva `/etc/hosts`, estado dos perfis MDM, overrides launchd desabilitados e config do Unleash.
```bash
sudo ./unleash backup
```
### `restore`
Reverte o sistema para um estado salvo anteriormente.
```bash
sudo ./unleash restore
```
### `dualboot`
Cria uma conta admin e aplica supressão em um volume externo/bootcamp.
```bash
sudo ./unleash dualboot
```
---
## Comandos Inteligentes (v2.0)
| Comando | Descrição |
|---------|-----------|
| `init` | Assistente de configuração interativo |
| `suggest` | Análise de risco e recomendações baseadas no sistema |
| `remediate` | Limpeza MDM por organização |
| `predict` | Consulta de número serial — prevê qual organização registrou este Mac |
| `telemetry` | Gerencia estatísticas de uso anônimas (opt-in) |
### `init`
Assistente interativo que executa a configuração completa:
firewall → monitor → persist → backup → audit.
```bash
sudo ./unleash init
```
### `suggest`
Analisa seu sistema e fornece recomendações baseadas em risco.
```bash
sudo ./unleash suggest
```
### `remediate`
Limpeza MDM por organização. Suporta: JAMF, Mosyle, Addigy, Kandji, VMware.
Detecta automaticamente a organização a partir do registro DEP.
```bash
sudo ./unleash remediate
```
### `predict`
Lê o prefixo do número serial e verifica contra prefixos conhecidos de organizações MDM.
Útil antes de comprar um Mac usado.
```bash
./unleash predict ABC12345678
```
### `telemetry`
Gerencia estatísticas anônimas de uso (opt-in, DESLIGADO por padrão).
```bash
./unleash telemetry on
./unleash telemetry off
./unleash telemetry status
```
---
## VPN Kill-Switch
| Comando | Descrição |
|---------|-----------|
| `vpn-kill` | Instala pf kill-switch — bloqueia MDM fora da VPN |
| `vpn-kill-remove` | Remove o VPN kill-switch |
| `vpn-kill-status` | Verifica o estado do VPN kill-switch |
Projetado para Macs fornecidos por organizações que precisam registrar mas só devem se comunicar enquanto na VPN.
Bloqueia IPs MDM quando o dispositivo NÃO está conectado ao túnel VPN.
```bash
sudo ./unleash vpn-kill
sudo ./unleash vpn-kill-status
sudo ./unleash vpn-kill-remove
```
---
## Gerenciamento
| Comando | Descrição |
|---------|-----------|
| `update` | Autoatualização a partir do último release do GitHub |
| `uninstall` | Remoção completa com confirmações de segurança |
| `reinstall` | Desinstalar + reinstalar (persist + whitelist + monitor) |
| `config` | Ver ou editar configurações persistentes |
| `report` | Relatório completo do sistema (markdown ou JSON) |
| `demo` | Fluxo de bypass simulado (sem alterações reais) |
| `version` | Mostra a versão |
### `update`
Baixa o último release do GitHub. Verifica a assinatura GPG.
```bash
sudo ./unleash update
```
### `uninstall`
Remove todos os vestígios do Unleash. Pede confirmação.
```bash
sudo ./unleash uninstall
```
### `reinstall`
Desinstala e então reaplica persist + whitelist + monitor.
```bash
sudo ./unleash reinstall
```
### `config`
Ver ou editar configurações persistentes em `~/.unleash.conf`.
```bash
./unleash config
./unleash config show
./unleash config set key value
```
### `report`
Gera um relatório completo de status. Suporta `--json` para saída legível por máquina.
```bash
sudo ./unleash report
sudo ./unleash report --json
```
### `demo`
Executa um fluxo de bypass simulado. Nenhuma alteração real é feita.
```bash
./unleash demo
```
---
## Bot do Discord
| Comando | Descrição |
|---------|-----------|
| `discord-bot` | Inicia o bot de alertas do Discord |
| `discord-bot-stop` | Para o bot do Discord |
| `discord-bot-status` | Verifica se o bot do Discord está rodando |
Envia DMs no Discord quando atividade MDM é detectada.
```bash
sudo ./unleash discord-bot <token> <userId>
sudo ./unleash discord-bot-status
sudo ./unleash discord-bot-stop
```
---
## Diagnósticos
| Comando | Descrição |
|---------|-----------|
| `doctor` | Diagnóstico pré-voo — root, Recovery, libs, disco, dependências |
| `status` | Status do registro MDM (Recovery apenas, use `-d` para profundo) |
| `test` | Simulação dry-run de qualquer comando |
### `doctor`
Verifica: privilégios root, detecção do modo Recovery, versão do bash,
disco/volume, bibliotecas necessárias e conectividade com a internet.
```bash
./unleash doctor
```
### `status`
Mostra estado dos marcadores DEP, arquivo hosts, overrides de daemon.
Só funciona do Recovery. Use `check` ou `audit` em sistemas já iniciados.
```bash
./unleash status
./unleash status -d
```
### `test`
Modo dry-run. Simula um comando sem fazer alterações reais.
```bash
./unleash test bypass
./unleash 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
```
---
## Opções Globais
| Opção | Efeito |
|-------|--------|
| `--verbose` | Mostra mensagens de debug |
| `--dry-run` | Simula sem fazer alterações |
| `--log-file <caminho>` | Escreve logs em um arquivo (anexado) |
+7 -1
View File
@@ -1,9 +1,15 @@
---
layout: default
title: unleash
description: Bypass MDM em um único script para macOS — cobre todas as 5 camadas do MDM da Apple
---
<p align="center">
<img src="../icon.svg" width="100" alt="unleash logo">
<br>
<strong>unleash</strong>
<br>
<em>Script único de bypass MDM para macOS</em>
<em>unleash</em>
</p>
<p align="center">
+58
View File
@@ -0,0 +1,58 @@
---
layout: default
title: Instalação — unleash
---
# Instalação
## Homebrew (mais fácil)
```bash
brew tap mateussiqueira/unleash
brew install unleash
```
Ou em um passo:
```bash
brew install mateussiqueira/unleash/unleash
```
## Download direto
```bash
curl -L https://raw.githubusercontent.com/mateussiqueira/unleash/main/unleash-standalone.sh -o unleash
chmod +x unleash
sudo ./unleash init
```
## De um pendrive USB (para o modo Recovery)
1. Formate um USB/SSD como **FAT32**, **APFS** ou **exFAT**
2. Copie a pasta `unleash` (ou apenas `unleash-standalone.sh`) para o drive
3. Inicialize no Recovery e execute de `/Volumes/SeuDrive/unleash`
## Via curl no Recovery (precisa de internet)
```bash
curl -L https://raw.githubusercontent.com/mateussiqueira/unleash/main/unleash -o /tmp/unleash
chmod +x /tmp/unleash && /tmp/unleash bypass
```
## Compilando a partir do código-fonte
```bash
git clone https://github.com/mateussiqueira/unleash.git
cd unleash
bash examples/build-standalone.sh
# Saída: unleash-standalone.sh (~3200 linhas)
```
## Verificando a instalação
```bash
./unleash version
# → unleash v2.0.0
./unleash doctor
# Executa diagnósticos pré-voo
```
+134
View File
@@ -0,0 +1,134 @@
---
layout: default
title: Cenários — unleash
---
# Cenários
## Antes de comprar um Mac usado
Verifique o número serial antes de comprar:
```bash
./unleash predict ABC12345678 # verifica serial contra prefixos conhecidos
./unleash check # este Mac é seguro para limpar?
```
`predict` consulta o serial contra prefixos conhecidos de organizações MDM.
Se corresponder a JAMF, Mosyle ou outra organização, você sabe o que esperar antes de comprar.
---
## Recuperação após Migration Assistant
1. Instale o macOS em um Mac novo
2. O Migration Assistant copia seus dados antigos
3. O MDM aparece em minutos após o login
**Solução:** Inicialize no Recovery e execute:
```bash
./unleash suppress
```
Ou `bypass` se precisar de um novo usuário admin. Remove os marcadores DEP,
artefatos de nível de usuário e preferências MDM que o MA transferiu.
*Este é o caso #1 que a maioria das outras ferramentas não trata — o Unleash lida com ele.*
---
## Atualização do macOS trouxe o MDM de volta
1. A atualização do sistema restaura os daemons de registro automaticamente
2. O bloqueio MDM em `/etc/hosts` geralmente é preservado
**Solução:**
```bash
sudo ./unleash heal
```
Re-desabilita daemons e verifica todas as camadas. Se você executou `persist`
antes da atualização, isso acontece automaticamente na próxima inicialização.
---
## Comprou um Mac de escritório
1. O serial pode ainda estar no ABM da empresa
2. Mesmo após limpeza total, conectar ao Wi-Fi no Assistente de Configuração aciona o registro
**Estratégia:**
1. Inicialize no Recovery **sem conectar ao Wi-Fi**
2. Execute `unleash bypass` antes do dispositivo contatar a Apple
3. Execute `unleash persist` e `unleash whitelist` para mantê-lo limpo
4. Só então conecte-se à internet
O serial fica no ABM para sempre — mas enquanto o dispositivo nunca conectar
com todas as proteções removidas, ele não vai re-registrar.
---
## Mac usado que já tem um usuário logado
```bash
sudo ./unleash audit # verifica o estado atual
sudo ./unleash harden # mata processos MDM imediatamente
sudo ./unleash whitelist # bloqueia MDM mantendo iCloud
sudo ./unleash persist # sobrevive a atualizações futuras
```
---
## Configurando um Mac novo antes do primeiro boot
1. Inicialize no Recovery sem Wi-Fi
2. Execute `unleash init` — assistente interativo
3. Ele irá: suprimir MDM, instalar persist, instalar whitelist, executar audit
4. Reinicie, configure normalmente, o MDM nunca incomoda
---
## Mac fornecido pela organização (deve registrar apenas na VPN)
Algumas organizações exigem que o Mac registre, mas somente quando conectado à VPN corporativa.
```bash
sudo ./unleash vpn-kill
```
Isso instala um pf kill-switch que bloqueia tráfego MDM quando o dispositivo
NÃO está conectado ao túnel VPN. O MDM só pode se comunicar através
da conexão VPN criptografada.
---
## Após uma restauração completa DFU/IPSW
Uma restauração DFU apaga tudo mas não remove a atribuição ABM.
1. Restaure via Apple Configurator 2
2. **Não conecte ao Wi-Fi**
3. Inicialize no Recovery
4. Execute `unleash bypass`
5. Execute `unleash persist && unleash whitelist`
6. Reinicie e conecte-se à internet com segurança
---
## Implantação automatizada (admins de TI)
Para implantar em múltiplas máquinas:
```bash
# Bypass via script
./unleash suppress --log-file /var/log/unleash-deploy.log
# Com persist + monitor
sudo ./unleash persist
sudo ./unleash monitor
# Relatório de auditoria em JSON
sudo ./unleash report --json
# Alertas no Discord
sudo ./unleash discord-bot <token> <userId>
```
+61
View File
@@ -0,0 +1,61 @@
---
layout: default
title: Segurança — unleash
---
# Segurança & Proteção
## Princípios de Design
### Sem persistência root
O Unleash não instala backdoor, cria usuários ocultos ou modifica o
volume do sistema. Todas as alterações miram o **volume de Dados**
apenas e são totalmente reversíveis.
### Releases assinados com GPG
Todo release é assinado com uma chave GPG. O comando `update` verifica
a assinatura antes de aplicar atualizações. Se a verificação falhar, a
atualização é **rejeitada**.
### Telemetria opt-in
A telemetria está **DESLIGADA por padrão**. Se ativada, envia apenas
contagens anônimas:
- Nome do comando executado
- Versão do macOS
- Status de sucesso/falha
Sem números de série, IPs ou informações pessoalmente identificáveis.
### Sem dependência de internet
Comandos principais (`bypass`, `suppress`, `heal`) funcionam completamente
offline. Apenas `update`, `firewall` (resolução DNS) e `discord-bot`
precisam de acesso à rede.
---
## Garantias de Segurança
- **Sem escritas no SSV** — todas as alterações miram o volume de Dados
- **Reversível** — `backup` salva o estado, `restore` reverte
- **Sem apagar dados** — nunca executa `profiles renew` ou comandos de apagar
- **Idempotente** — executar múltiplas vezes é inofensivo
- **Pede confirmação** antes de ações destrutivas
---
## Níveis de Risco
| Nível | Descrição | Comandos |
|-------|-----------|----------|
| Seguro | Somente leitura, sem alterações | `status`, `check`, `doctor`, `audit`, `predict`, `report` |
| Baixo | Escreve apenas no arquivo hosts | `suppress`, `heal` |
| Médio | Cria/modifica arquivos do sistema | `bypass`, `dualboot`, `persist`, `whitelist` |
| Alto | Firewall a nível de kernel | `firewall`, `vpn-kill` |
| Destrutivo | Remoção completa | `uninstall`, `reinstall` |
---
## Divulgação Responsável
Encontrou um problema de segurança?
Veja a [Política de Segurança](https://github.com/mateussiqueira/unleash/blob/main/SECURITY.md).
+284
View File
@@ -0,0 +1,284 @@
---
layout: default
title: Solução de Problemas — unleash
---
# Solução de Problemas
## Erros Comuns
### "Not a known DirStatus"
A detecção automática de volume falhou.
```
[ERR] Not a known DirStatus
```
**Solução:**
1. Execute `diskutil list` para encontrar seu volume de Dados
2. Monte: `diskutil mount /dev/diskXsY`
3. Execute o unleash novamente
---
### "Full bypass must run from Recovery mode"
```
[ERR] Full bypass must run from Recovery mode.
```
**Causa:** `bypass` cria usuários admin via dscl, que só funciona no Recovery.
**Solução:** Inicialize no Recovery e tente novamente. Ou use `suppress` de um sistema já iniciado.
---
### Erros "Needs sudo"
Vários comandos precisam de root:
```
[ERR] Firewall needs sudo: sudo ./unleash firewall
[ERR] Heal needs sudo: sudo ./unleash heal
[ERR] Hardening needs sudo: sudo ./unleash harden
[ERR] Audit needs sudo: sudo ./unleash audit
[ERR] Check needs sudo: sudo ./unleash check
```
**Solução:** Anteceda `sudo` ao comando.
---
### MDM volta após reiniciar
A causa mais comum são **artefatos de nível de usuário** trazidos pelo Migration Assistant.
**Solução do Recovery:**
```bash
sudo ./unleash suppress
```
**Solução do sistema já iniciado:**
```bash
sudo ./unleash harden
```
Se continuar voltando:
```bash
sudo ./unleash persist # auto-recuperação em cada inicialização
sudo ./unleash monitor # vigia re-registro
```
---
### Atualização do macOS reativou o MDM
Atualizações do sistema restauram os daemons de registro automaticamente.
**Solução:**
```bash
sudo ./unleash heal
```
Se você executou `persist` antes da atualização, isso acontece automaticamente na próxima inicialização.
---
### "Profiles status" ainda mostra registro
Isso é **cosmético**. O macOS armazena o estado dos perfis no SSV (Volume Selado do Sistema) somente leitura.
**Não confie** em `profiles status -v`.
**Confie** em `unleash status -d`.
---
### FileVault está ativado
O Unleash detecta FileVault e pede a chave de recuperação ou senha do volume.
**Solução:** Se o desbloqueio automático falhar, desbloqueie o volume manualmente no Utilitário de Disco primeiro:
1. Vá para o Utilitário de Disco no Recovery
2. Selecione o volume de Dados
3. Arquivo → Desbloquear → Digite a senha
4. Execute o unleash novamente
---
### iCloud para de funcionar após o bypass
O bloqueio básico de `/etc/hosts` inclui `albert.apple.com` (ativação do iCloud) e `gdmf.apple.com`.
**Solução:** Use `whitelist` em vez do bloqueio básico:
```bash
sudo ./unleash whitelist
```
Ou remova manualmente estas duas linhas de `/etc/hosts`:
```
0.0.0.0 albert.apple.com
0.0.0.0 gdmf.apple.com
```
---
### "Not a macOS Data volume"
```
[ERR] Not a macOS Data volume
```
**Causa:** O volume montado não tem a estrutura esperada.
**Solução:** Execute `diskutil list` para encontrar o volume de Dados correto (procure por "Data" no nome ou pelo código `69414d41-...`). Monte o correto e tente novamente.
---
### Monitor não inicia
**Verifique:**
1. Já está rodando? `sudo ./unleash monitor-status`
2. Permissões: precisa de root
3. Logs: `/var/log/unleash-monitor.log`
**Solução:**
```bash
sudo ./unleash monitor-stop
sudo ./unleash monitor
```
---
### Não consigo baixar arquivos no Recovery
O modo Recovery não tem internet por padrão.
**Solução:**
1. Use um pendrive USB com o unleash copiado
2. Ou conecte-se ao Wi-Fi no Recovery (menu superior direito → ícone Wi-Fi)
---
### Erro "Library not found" na inicialização
```
ERROR: Library not found: /path/to/lib/colors.sh
```
**Causa:** Executando o script `unleash` fonte de fora do diretório do repositório.
**Solução:**
- Use a versão standalone (`unleash-standalone.sh`)
- Ou execute da raiz do repositório onde o diretório `lib/` existe
- Ou instale via Homebrew
---
### Regras do firewall não estão sendo aplicadas
pf pode ter regras existentes que conflitam.
**Solução:**
```bash
sudo ./unleash firewall-off # limpa regras existentes
sudo ./unleash firewall # reaplica
```
---
### "Dispositivo ainda trava após restauração DFU"
Uma restauração DFU/IPSW completa não remove a atribuição ABM — o serial permanece no Apple Business Manager.
**Estratégia:**
1. Após restaurar, **não conecte ao Wi-Fi**
2. Inicialize no Recovery
3. Execute `unleash bypass` antes do dispositivo contatar a Apple
4. Execute `unleash persist` e `unleash whitelist`
5. Só então conecte-se à internet
O serial fica no ABM para sempre — mas se o dispositivo nunca conectar sem proteções, ele não vai re-registrar.
---
### Verificação de assinatura GPG falha na atualização
```
[ERR] GPG signature verification failed
```
**Solução:**
1. Certifique-se de ter `gpg` instalado
2. Importe a chave de assinatura: `gpg --keyserver keys.openpgp.org --recv-key <KEY_ID>`
3. Tente `sudo ./unleash update` novamente
4. Ou baixe manualmente de [GitHub Releases](https://github.com/mateussiqueira/unleash/releases)
---
### Instalação via Homebrew falha
```
Error: ... homebrew-core ...
```
**Solução:** Certifique-se de que o tap está atualizado:
```bash
brew untap mateussiqueira/unleash
brew tap mateussiqueira/unleash
brew install unleash
```
---
## Logging
Todos os comandos produzem logs estruturados:
```
[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
[STP] Locating Data volume by APFS role...
[DBG] Checking pfctl availability
```
**Formato do log:**
| Prefixo | Nível |
|---------|-------|
| `[INF]` | Info — operação normal |
| `[ OK]` | Sucesso — operação concluída |
| `[WRN]` | Aviso — problema não crítico |
| `[ERR]` | Erro — operação falhou |
| `[STP]` | Passo — ação atual |
| `[DBG]` | Debug — verbose apenas |
Use `--verbose` para mensagens de debug e `--log-file <caminho>` para salvar em um arquivo:
```bash
sudo ./unleash heal --verbose --log-file /tmp/unleash.log
```
---
## Comandos de Diagnóstico
Execute estes para coletar informações antes de buscar ajuda:
```bash
# Verificação rápida de saúde
sudo ./unleash doctor
# Auditoria completa do sistema
sudo ./unleash audit
# Gerar relatório
sudo ./unleash report
# Simular um bypass
sudo ./unleash demo
```
---
## Obtendo Ajuda
- [GitHub Issues](https://github.com/mateussiqueira/unleash/issues)
- [Discussões](https://github.com/mateussiqueira/unleash/discussions)
- [Política de Segurança](https://github.com/mateussiqueira/unleash/blob/main/SECURITY.md)
+134
View File
@@ -0,0 +1,134 @@
---
layout: default
title: Scenarios — unleash
---
# Scenarios
## Before buying a used Mac
Check the serial number before you buy:
```bash
./unleash predict ABC12345678 # check serial against known org prefixes
./unleash check # is this Mac safe to wipe?
```
`predict` looks up the device serial against known MDM org prefixes.
If it matches JAMF, Mosyle, or another org, you know what you're dealing with before you buy.
---
## Recovery after Migration Assistant
1. Fresh install macOS on a new Mac
2. Migration Assistant copies your old data
3. MDM appears within minutes of login
**Fix:** Boot to Recovery and run:
```bash
./unleash suppress
```
Or `bypass` if you need a new admin user. This removes the DEP markers,
user-level artifacts, and MDM preferences that MA transferred over.
*This is the #1 case most other tools miss — Unleash handles it.*
---
## macOS update brought MDM back
1. System update restores enrollment daemons automatically
2. MDM block in `/etc/hosts` is often preserved
**Fix:**
```bash
sudo ./unleash heal
```
Re-disables daemons and re-checks all layers. If you ran `persist`
before the update, this happens automatically on the next boot.
---
## Buying a former office Mac
1. The serial might still be in the company's ABM
2. Even after a clean wipe, connecting to Wi-Fi at Setup Assistant triggers enrollment
**Strategy:**
1. Boot to Recovery **without connecting to Wi-Fi**
2. Run `unleash bypass` before the device ever phones home
3. Run `unleash persist` and `unleash whitelist` so it stays clean
4. Only then connect to the internet
The serial stays in ABM forever — but as long as the device never
connects with full protections removed, it will not re-enroll.
---
## Used Mac that already has a user logged in
```bash
sudo ./unleash audit # check current state
sudo ./unleash harden # kill MDM processes immediately
sudo ./unleash whitelist # block MDM while keeping iCloud
sudo ./unleash persist # survive future updates
```
---
## Setting up a new Mac before first boot
1. Boot to Recovery without Wi-Fi
2. Run `unleash init` — interactive wizard
3. It will: suppress MDM, install persist, install whitelist, run audit
4. Reboot, set up normally, MDM never bothers you
---
## Org-provided Mac (must enroll on VPN only)
Some organizations require the Mac to enroll but only when connected to the corporate VPN.
```bash
sudo ./unleash vpn-kill
```
This installs a pf kill-switch that blocks MDM traffic when the device
is NOT connected to the VPN tunnel. MDM can only communicate through
the encrypted VPN connection.
---
## After a full DFU/IPSW restore
A DFU restore erases everything but doesn't remove ABM assignment.
1. Restore via Apple Configurator 2
2. **Do not connect to Wi-Fi**
3. Boot to Recovery
4. Run `unleash bypass`
5. Run `unleash persist && unleash whitelist`
6. Reboot and connect to the internet safely
---
## Automated deployment (IT admins)
For deploying across multiple machines:
```bash
# Scripted bypass
./unleash suppress --log-file /var/log/unleash-deploy.log
# With persist + monitor
sudo ./unleash persist
sudo ./unleash monitor
# Audit report in JSON
sudo ./unleash report --json
# Discord alerts
sudo ./unleash discord-bot <token> <userId>
```
+13
View File
@@ -0,0 +1,13 @@
---
layout: null
---
[
{% assign pages = site.html_pages | where_exp:"p","p.title != null" %}
{% for page in pages %}
{
"title": "{{ page.title | escape }}",
"url": "{{ page.url | relative_url | replace:'.html','' }}",
"content": "{{ page.content | strip_html | normalize_whitespace | escape }}"
}{% unless forloop.last %},{% endunless %}
{% endfor %}
]
+61
View File
@@ -0,0 +1,61 @@
---
layout: default
title: Security — unleash
---
# Security & Safety
## Design Principles
### No root persistence
Unleash does not install backdoors, create hidden users, or modify the
system volume. All changes target the **Data volume** only and are
fully reversible.
### GPG-signed releases
Every release is signed with a GPG key. The `update` command verifies
the signature before applying updates. If verification fails, the
update is **rejected**.
### Opt-in telemetry
Telemetry is **OFF by default**. If enabled, it sends only anonymous
counts:
- Command name executed
- macOS version
- Success/failure status
No serial numbers, IPs, or personally identifiable information.
### No internet dependency
Core commands (`bypass`, `suppress`, `heal`) work entirely offline.
Only `update`, `firewall` (DNS resolution), and `discord-bot` need
network access.
---
## Safety Guarantees
- **No SSV writes** — all changes target the Data volume
- **Reversible** — `backup` saves state, `restore` reverts
- **No data erasure** — never runs `profiles renew` or erase commands
- **Idempotent** — running multiple times is harmless
- **Prompts for confirmation** before destructive actions
---
## Risk Levels
| Level | Description | Commands |
|-------|-------------|----------|
| Safe | Read-only, no changes | `status`, `check`, `doctor`, `audit`, `predict`, `report` |
| Low | Writes hosts file only | `suppress`, `heal` |
| Medium | Creates/modifies system files | `bypass`, `dualboot`, `persist`, `whitelist` |
| High | Kernel-level firewall | `firewall`, `vpn-kill` |
| Destructive | Full removal | `uninstall`, `reinstall` |
---
## Responsible Disclosure
Found a security issue?
See the [Security Policy](https://github.com/mateussiqueira/unleash/blob/main/SECURITY.md).
+284
View File
@@ -0,0 +1,284 @@
---
layout: default
title: Troubleshooting — unleash
---
# Troubleshooting
## Common Errors
### "Not a known DirStatus"
Volume auto-detection failed.
```
[ERR] Not a known DirStatus
```
**Fix:**
1. Run `diskutil list` to find your Data volume
2. Mount it: `diskutil mount /dev/diskXsY`
3. Re-run unleash
---
### "Full bypass must run from Recovery mode"
```
[ERR] Full bypass must run from Recovery mode.
```
**Cause:** `bypass` creates admin users via dscl, which only works in Recovery.
**Fix:** Boot to Recovery and try again. Or use `suppress` instead from a booted system.
---
### "Needs sudo" errors
Various commands require root:
```
[ERR] Firewall needs sudo: sudo ./unleash firewall
[ERR] Heal needs sudo: sudo ./unleash heal
[ERR] Hardening needs sudo: sudo ./unleash harden
[ERR] Audit needs sudo: sudo ./unleash audit
[ERR] Check needs sudo: sudo ./unleash check
```
**Fix:** Prepend `sudo` to the command.
---
### MDM comes back after reboot
The most common cause is **user-level artifacts** carried over by Migration Assistant.
**Fix from Recovery:**
```bash
sudo ./unleash suppress
```
**Fix from booted system:**
```bash
sudo ./unleash harden
```
If it keeps returning:
```bash
sudo ./unleash persist # auto-heal on every boot
sudo ./unleash monitor # watch for re-enrollment
```
---
### macOS update re-enabled MDM
System updates restore enrollment daemons automatically.
**Fix:**
```bash
sudo ./unleash heal
```
If you ran `persist` before the update, this runs automatically on next boot.
---
### "Profiles status" still shows enrollment
This is **cosmetic**. macOS stores profile state on the read-only SSV (System Sealed Volume).
**Don't trust** `profiles status -v`.
**Trust** `unleash status -d` instead.
---
### FileVault is enabled
Unleash detects FileVault and prompts for the recovery key or volume password.
**Fix:** If automatic unlock fails, unlock the volume manually in Disk Utility first:
1. Go to Disk Utility in Recovery
2. Select the Data volume
3. File → Unlock → Enter password
4. Re-run unleash
---
### iCloud stops working after bypass
The basic `/etc/hosts` block includes `albert.apple.com` (iCloud activation) and `gdmf.apple.com`.
**Fix:** Use `whitelist` instead of the basic block:
```bash
sudo ./unleash whitelist
```
Or manually remove these two lines from `/etc/hosts`:
```
0.0.0.0 albert.apple.com
0.0.0.0 gdmf.apple.com
```
---
### "Not a macOS Data volume"
```
[ERR] Not a macOS Data volume
```
**Cause:** The mounted volume doesn't have the expected structure.
**Fix:** Run `diskutil list` to find the correct Data volume (look for "Data" in the name or the `69414d41-...` role). Mount the right one and retry.
---
### Monitor won't start
**Check:**
1. Is it already running? `sudo ./unleash monitor-status`
2. Permissions: needs root
3. Check logs: `/var/log/unleash-monitor.log`
**Fix:**
```bash
sudo ./unleash monitor-stop
sudo ./unleash monitor
```
---
### Can't download files in Recovery
Recovery mode has no internet by default.
**Fix:**
1. Use a USB drive with unleash copied to it
2. Or connect to Wi-Fi in Recovery (top-right menu → Wi-Fi icon)
---
### "Library not found" error on startup
```
ERROR: Library not found: /path/to/lib/colors.sh
```
**Cause:** Running the source `unleash` script from outside the repo directory.
**Fix:**
- Use the standalone version (`unleash-standalone.sh`) instead
- Or run from the repo root where the `lib/` directory exists
- Or install via Homebrew
---
### Firewall rules not applying
pf might have existing rules that conflict.
**Fix:**
```bash
sudo ./unleash firewall-off # clear existing rules
sudo ./unleash firewall # re-apply
```
---
### "Device still locks after DFU restore"
A full DFU/IPSW restore doesn't remove ABM assignment — the serial stays in Apple Business Manager.
**Strategy:**
1. After restore, **do not connect to Wi-Fi**
2. Boot to Recovery
3. Run `unleash bypass` before the device ever phones home
4. Run `unleash persist` and `unleash whitelist`
5. Only then connect to the internet
The serial stays in ABM forever — but if the device never connects without protections, it won't re-enroll.
---
### GPG signature verification fails on update
```
[ERR] GPG signature verification failed
```
**Fix:**
1. Make sure you have `gpg` installed
2. Import the signing key: `gpg --keyserver keys.openpgp.org --recv-key <KEY_ID>`
3. Try `sudo ./unleash update` again
4. Or download manually from [GitHub Releases](https://github.com/mateussiqueira/unleash/releases)
---
### Homebrew installation fails
```
Error: ... homebrew-core ...
```
**Fix:** Make sure the tap is up to date:
```bash
brew untap mateussiqueira/unleash
brew tap mateussiqueira/unleash
brew install unleash
```
---
## Logging
All commands produce structured logs:
```
[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
[STP] Locating Data volume by APFS role...
[DBG] Checking pfctl availability
```
**Log format:**
| Prefix | Level |
|--------|-------|
| `[INF]` | Info — normal operation |
| `[ OK]` | Success — operation completed |
| `[WRN]` | Warning — non-critical issue |
| `[ERR]` | Error — operation failed |
| `[STP]` | Step — current action |
| `[DBG]` | Debug — verbose only |
Use `--verbose` for debug messages and `--log-file <path>` to save to a file:
```bash
sudo ./unleash heal --verbose --log-file /tmp/unleash.log
```
---
## Diagnostic Commands
Run these to gather information before seeking help:
```bash
# Quick health check
sudo ./unleash doctor
# Full system audit
sudo ./unleash audit
# Generate report
sudo ./unleash report
# Dry-run a bypass
sudo ./unleash demo
```
---
## Getting Help
- [GitHub Issues](https://github.com/mateussiqueira/unleash/issues)
- [Discussions](https://github.com/mateussiqueira/unleash/discussions)
- [Security Policy](https://github.com/mateussiqueira/unleash/blob/main/SECURITY.md)
+12
View File
@@ -0,0 +1,12 @@
{
"git": {
"deploymentEnabled": {
"main": true
}
},
"installCommand": "cd docs && bundle install",
"buildCommand": "cd docs && jekyll build",
"outputDirectory": "docs/_site",
"framework": "jekyll",
"cleanUrls": true
}