lakr233/vphone-cliBoot e gerencie iPhones virtuais em Apple Silicon com patch de firmware, variantes de jailbreak e recursos de pesquisa de segurança para testes e análise de iOS.
Inicialize um iPhone virtual via o Virtualization.framework da Apple usando a infraestrutura de VM de pesquisa PCC.
Host:
Dependências:
brew install [email protected] aria2 wget gnu-tar openssl@3 ldid-procursus sshpass keystone cmake libusb ipsw zstd
brew install zqxwce/tap/vphone-cli
git clone --recurse-submodules https://github.com/Lakr233/vphone-cli.git
./scripts/setup_tools.sh # instala dependências, compila submódulos da toolchain, cria o venv Python
./scripts/build.sh # compila + assina vphone-cli, empacota o .app, compila cruzadamente vphoned
cd .build/vphone-cli.app/Contents/MacOS/
vphone-cli --help
Um único comando cria uma VM de ponta a ponta (download → patch → restauração DFU → instalação CFW → primeiro boot):
vphone-cli vm create myphone -V jb # -V / --variant
vphone-cli vm launch myphone
vphone-cli vm create executa todo o pipeline; as etapas individuais abaixo permitem que você o conduza manualmente ou reexecute uma fase.
vphone-cli vm list # lista VMs (--json para scripts)
vphone-cli vm info myphone # exibe uma VM
vphone-cli vm new myphone # cria um bundle vazio (opções de cpu/mem/disk)
vphone-cli vm config myphone --cpu 8 --memory 8192
vphone-cli vm clone myphone myphone-2 # clone APFS rápido, nova identidade de dispositivo
vphone-cli vm export myphone --out myphone.tzst # zstd rápido por padrão (--max = xz -9); --out pode ser um diretório (nomeia automaticamente <vm>.tzst/.txz); ignora o diretório de restauração + arquivos de staging
vphone-cli vm import myphone.tzst --name restored
vphone-cli vm rename myphone iphone16
vphone-cli vm delete iphone16
vm create automatiza)vphone-cli vm new myphone # 1. bundle vazio
vphone-cli fw prepare myphone --iphone-version 26.1 # 2. baixar + mesclar IPSWs
vphone-cli fw patch myphone --variant jb # 3. aplicar patch na cadeia de boot
vphone-cli vm launch myphone --dfu & # 4. boot em DFU (em segundo plano)
vphone-cli restore myphone --get-shsh # buscar SHSH
vphone-cli restore myphone # restauração DFU
vphone-cli vm stop myphone # parar o boot DFU
vphone-cli cfw install myphone --variant jb # 5. instalar CFW (montagem no host; solicita sudo)
vphone-cli vm launch myphone # 6. primeiro boot
Atualize para um iOS mais recente apontando fw prepare para um IPSW: --iphone-source /path/to.ipsw --cloudos-source /path/to.ipsw.
Cinco variantes de patch com bypass de segurança crescente — passe uma para --variant:
| Variante | Cadeia de Boot | CFW | Notas |
|---|---|---|---|
less | 4 patches | 2 fases | Sem patch — mantém as mitigações do iOS habilitadas |
regular | 42 patches | 10 fases | Bypass de AMFI/SSV/Img4/TXM |
dev | 53 patches | 12 fases | + bypass de entitlement/debug TXM |
jb | 113 patches | 14 fases | + jailbreak completo (Sileo, TrollStore com instalação automática no primeiro boot) |
exp | 141 patches | 18 fases | Superconjunto de JB + patches de pesquisa anti-detecção de VM |
Consulte research/0_binary_patch_comparison.md para o detalhamento por componente.
ssh -p 22222 mobile@<vm-ip> (senha alpine)ssh -p 22222 root@<vm-ip>vnc://<vm-ip>:5901Tudo o que o vphone-cli cria fica em ~/.vphone/ — mantido fora do repositório e do .app para que o bundle assinado permaneça portátil. Redirecione toda a árvore com $VPHONE_ROOT:
| Caminho | Conteúdo |
|---|---|
~/.vphone/ | A raiz de dados por usuário — substitua todo o local com $VPHONE_ROOT. |
~/.vphone/VMs/ | Bundles de VM — um diretório por VM. Esta é a biblioteca; substitua com $VPHONE_LIBRARY_ROOT. |
~/.vphone/ipsws/ | IPSWs de iPhone + cloudOS baixados, armazenados em cache e reutilizados entre VMs. |
~/.vphone/tools/ | Artefatos de volume selado APFS em cache (apfs_sealvolume_<version>) buscados durante fw prepare. |
~/.vphone/debs/ | Pacotes .deb em cache que a instalação CFW jb/exp insere no convidado (Sileo, apt, …). |
~/.vphone/venv/ | Ambiente Python provisionado automaticamente (consulte Python runtime; substitua com $VPHONE_VENV_DIR). |
Precedência: as substituições por item ($VPHONE_LIBRARY_ROOT, $VPHONE_VENV_DIR) têm prioridade sobre $VPHONE_ROOT, que tem prioridade sobre o padrão ~/.vphone. Os caches ipsws/, tools/ e debs/ ficam sempre diretamente sob a raiz ativa.
Opção A — desative completamente o SIP e depois desative o AMFI via boot-arg (mais permissivo).
Na Recuperação (pressione e segure o botão de energia → Terminal):
csrutil disable
csrutil allow-research-guests enable
Em seguida, reinicie no macOS e defina o boot-arg do AMFI (requer SIP totalmente desativado para ter efeito):
sudo nvram boot-args="amfi_get_out_of_my_way=1 -v" # reinicie depois
Opção B — mantenha o SIP ativado (relaxado apenas para debug) e depois coloque o binário na lista de permissões com amfidont (deixa o AMFI habilitado em todo o sistema).
Na Recuperação:
csrutil enable --without debug
csrutil allow-research-guests enable
Em seguida, reinicie no macOS e:
vphone-amfidont # .build/vphone-cli.app/Contents/Resources/vphone-amfidont para compilações locais
| Host | iPhone | CloudOS |
|---|---|---|
| Mac16,11 27.0b2 | 17,3_18.6.2_22G100 | 26.1-23B85 |
| Mac16,8 26.5.1 | 17,3_26.0_23A341 | 26.1-23B85 |
| Mac16,8 26.5.1 | 17,3_26.0.1_23A355 | 26.1-23B85 |
| Mac16,12 26.3 | 17,3_26.1_23B85 | 26.1-23B85 |
| Mac16,12 26.3 | 17,3_26.3_23D127 | 26.1-23B85 |
| Mac16,12 26.3 | 17,3_26.3_23D127 | 26.3-23D128 |
| Mac16,12 26.3 | 17,3_26.3.1_23D8133 | 26.3-23D128 |
| Mac16,11 26.2 | 17,3_26.4_23E246 | 26.4-23E5207q |
| Mac16,11 26.2 | 17,3_26.5_23F77 | 26.4-23E5207q |
| Mac16,11 27.0b2 | 17,3_26.5.2_23F84 | 26.4-23E5207q |
| Mac16,6 26.4.1 | 17,3_26.6_23G71 | 26.4-23E5207q |
| Mac16,11 27.0b2 | 17,3_26.6.1_23G83 | 26.4-23E5207q |
| Mac16,11 27.0b2 | 17,3_27.0_24A5380h | 26.4-23E5207q |
| Mac16,6 26.4.1 | 17,3_27.0_24A5390f | 26.4-23E5207q |
| Mac16,6 26.6.1 | 17,3_27.0_24A5408d | 26.4-23E5207q |
| Mac16,11 27.0b2 | 17,3_27.0_24A5418b | 26.4-23E5207q |
| Mac16,11 27.0b2 | 17,3_27.0_24A5424a | 26.4-23E5207q |
zsh: killed ./vphone-cli — as restrições de AMFI/debug não foram contornadas; consulte Pré-requisitos (amfi_get_out_of_my_way=1 ou amfidont).
Virtualization is not available on this hardware — seu Mac é ele próprio uma VM; o boot de convidado PV=3 não pode ser aninhado. Use um host macOS 15+ não aninhado.
Travado em "Press home to continue" — conecte via VNC e clique com o botão direito (clique com dois dedos) para simular o botão home.
Os apps do sistema não instalam — durante a configuração do iOS, não escolha Japão ou UE como sua região (verificações regulatórias extras que a VM não pode satisfazer); escolha, por exemplo, Estados Unidos.
O app falha ao iniciar com EXC_GUARD / GUARD_TYPE_MACH_PORT — reaplique o patch com vphone-cli fw patch <name> --variant <v> --force-exc-guard e depois restaure/instale novamente (#291). Sempre ativado para bases iOS 18.
Instalar um .ipa/.tipa — use o menu Instalar da VM em execução (arrastar e soltar ou seletor de arquivos).
cfw install trava ao reassinar um binário do sistema (ex.: Campo), com memória crescendo sem limite — bug conhecido no ldid-procursus até 2.1.5-procursus7 (o atual stable do Homebrew): bytes(uint64_t) chama __builtin_clzll(0) sem proteção contra zero, o que é comportamento indefinido, e nesta compilação resolve para um comprimento 0 que causa underflow em um contador de loop sem sinal — ldid fica em loop escrevendo um byte por vez em um buffer crescente em vez de terminar. Acionado por qualquer plist de entitlements contendo um valor inteiro exatamente 0 (alguns binários reais do sistema Apple têm esses valores). Corrigido upstream, mas ainda não em um release marcado; recompile da fonte: brew install --HEAD ldid-procursus && brew link --overwrite ldid-procursus. Encerre o processo ldid travado primeiro (sudo kill -9 <pid>) se você já o encontrou.
vphone-cli expõe um socket de controle do host (<bundle>/vphone.sock) para controle programático — capturas de tela, toque, deslizes, teclas de hardware, área de transferência — cada ação retornando uma captura de tela inline para testes E2E orientados por IA. Consulte vphone-mcp para um servidor MCP que o encapsula.