lakr233/vphone-cliArranca y gestiona iPhones virtuales en Apple Silicon con parcheo de firmware, variantes de jailbreak y funciones de investigación de seguridad para pruebas y análisis de iOS.
Arranca un iPhone virtual mediante el Virtualization.framework de Apple usando la infraestructura de VM de investigación PCC.
Host:
Dependencias:
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 dependencias, compila los submódulos de la toolchain, crea el venv de Python
./scripts/build.sh # compila y firma vphone-cli, empaqueta el .app, compila de forma cruzada vphoned
cd .build/vphone-cli.app/Contents/MacOS/
vphone-cli --help
Un solo comando crea una VM de extremo a extremo (descarga → parcheo → restauración DFU → instalación de CFW → primer arranque):
vphone-cli vm create myphone -V jb # -V / --variant
vphone-cli vm launch myphone
vphone-cli vm create ejecuta todo el pipeline; los pasos individuales que se muestran a continuación te permiten manejarlo manualmente o volver a ejecutar una etapa.
vphone-cli vm list # lista las VMs (--json para scripting)
vphone-cli vm info myphone # muestra una VM
vphone-cli vm new myphone # crea un bundle vacío (opciones de cpu/mem/disk)
vphone-cli vm config myphone --cpu 8 --memory 8192
vphone-cli vm clone myphone myphone-2 # clon APFS rápido, identidad de dispositivo nueva
vphone-cli vm export myphone --out myphone.tzst # zstd rápido por defecto (--max = xz -9); --out puede ser un directorio (nombres automáticos <vm>.tzst/.txz); omite el directorio de restauración y los archivos de staging
vphone-cli vm import myphone.tzst --name restored
vphone-cli vm rename myphone iphone16
vphone-cli vm delete iphone16
vm create)vphone-cli vm new myphone # 1. bundle vacío
vphone-cli fw prepare myphone --iphone-version 26.1 # 2. descarga y fusiona los IPSW
vphone-cli fw patch myphone --variant jb # 3. parchea la cadena de arranque
vphone-cli vm launch myphone --dfu & # 4. arranca en DFU (en segundo plano)
vphone-cli restore myphone --get-shsh # obtiene el SHSH
vphone-cli restore myphone # restauración DFU
vphone-cli vm stop myphone # detiene el arranque DFU
vphone-cli cfw install myphone --variant jb # 5. instala el CFW (montaje en host; pide sudo)
vphone-cli vm launch myphone # 6. primer arranque
Actualiza a un iOS más reciente apuntando fw prepare a un IPSW: --iphone-source /path/to.ipsw --cloudos-source /path/to.ipsw.
Cinco variantes de parcheo con bypass de seguridad creciente — pasa una a --variant:
| Variante | Cadena de arranque | CFW | Notas |
|---|---|---|---|
less | 4 parches | 2 fases | Sin parcheo — mantiene las mitigaciones de iOS activadas |
regular | 42 parches | 10 fases | Bypass de AMFI/SSV/Img4/TXM |
dev | 53 parches | 12 fases | + bypass de entitlement/debug de TXM |
jb | 113 parches | 14 fases | + jailbreak completo (Sileo, TrollStore auto-instalado en el primer arranque) |
exp | 141 parches | 18 fases | Superconjunto de JB + parches de investigación anti-detección de VM |
Consulta research/0_binary_patch_comparison.md para el desglose por componente.
ssh -p 22222 mobile@<vm-ip> (contraseña alpine)ssh -p 22222 root@<vm-ip>vnc://<vm-ip>:5901Todo lo que crea vphone-cli vive bajo ~/.vphone/ — se mantiene fuera del repositorio y del .app para que el bundle firmado siga siendo portable. Redirige todo el árbol con $VPHONE_ROOT:
| Ruta | Contenido |
|---|---|
~/.vphone/ | La raíz de datos por usuario — sobrescribe toda la ubicación con $VPHONE_ROOT. |
~/.vphone/VMs/ | Bundles de VM — un directorio por VM. Esta es la biblioteca; sobrescribe con $VPHONE_LIBRARY_ROOT. |
~/.vphone/ipsws/ | IPSW de iPhone y cloudOS descargados, almacenados en caché y reutilizados entre VMs. |
~/.vphone/tools/ | Artefactos de volumen sellado APFS en caché (apfs_sealvolume_<version>) obtenidos durante fw prepare. |
~/.vphone/debs/ | Paquetes .deb en caché que la instalación de CFW jb/exp coloca en el invitado (Sileo, apt, …). |
~/.vphone/venv/ | Entorno de Python aprovisionado automáticamente (consulta Python runtime; sobrescribe con $VPHONE_VENV_DIR). |
Precedencia: las sobrescrituras por elemento ($VPHONE_LIBRARY_ROOT, $VPHONE_VENV_DIR) ganan sobre $VPHONE_ROOT, que gana sobre el valor predeterminado ~/.vphone. Las cachés ipsws/, tools/ y debs/ siempre se encuentran directamente bajo la raíz activa.
Opción A — desactiva SIP por completo y luego desactiva AMFI mediante boot-arg (la más permisiva).
En Recovery (mantén pulsado el botón de encendido → Terminal):
csrutil disable
csrutil allow-research-guests enable
Luego reinicia en macOS y establece el boot-arg de AMFI (necesita SIP completamente desactivado para surtir efecto):
sudo nvram boot-args="amfi_get_out_of_my_way=1 -v" # reinicia después
Opción B — mantén SIP activado (solo relajado en debug) y luego incluye el binario en la lista blanca con amfidont (deja AMFI habilitado en todo el sistema).
En Recovery:
csrutil enable --without debug
csrutil allow-research-guests enable
Luego reinicia en macOS y:
vphone-amfidont # .build/vphone-cli.app/Contents/Resources/vphone-amfidont para compilaciones locales
| 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 — las restricciones de AMFI/debug no están eludidas; consulta Requisitos previos (amfi_get_out_of_my_way=1 o amfidont).
Virtualization is not available on this hardware — tu Mac es en sí mismo una VM; el arranque de invitado PV=3 no puede anidarse. Usa un host macOS 15+ sin anidamiento.
Atascado en "Press home to continue" — conéctate mediante VNC y haz clic derecho (clic con dos dedos) para simular el botón de inicio.
Las apps del sistema no se instalan — durante la configuración de iOS, no elijas Japón o la UE como región (comprobaciones regulatorias adicionales que la VM no puede satisfacer); elige, por ejemplo, Estados Unidos.
La app falla al iniciar con EXC_GUARD / GUARD_TYPE_MACH_PORT — vuelve a parchear con vphone-cli fw patch <name> --variant <v> --force-exc-guard y luego vuelve a restaurar/instalar (#291). Siempre activo en bases de iOS 18.
Instalar un .ipa/.tipa — usa el menú de Instalación de la VM en ejecución (arrastrar y soltar o selector de archivos).
cfw install se cuelga al volver a firmar un binario del sistema (p. ej. Campo), con la memoria creciendo sin límite — error conocido en ldid-procursus hasta 2.1.5-procursus7 (el stable actual de Homebrew): bytes(uint64_t) llama a __builtin_clzll(0) sin protección contra cero, lo que es un comportamiento indefinido, y en esta compilación se resuelve en una longitud 0 que desborda un contador de bucle sin signo — ldid gira escribiendo un byte a la vez en un buffer en crecimiento en lugar de terminar. Lo desencadena cualquier plist de entitlements que contenga un valor entero de exactamente 0 (algunos binarios reales de Apple del sistema los tienen). Corregido upstream pero aún no en una versión etiquetada; recompila desde el código fuente: brew install --HEAD ldid-procursus && brew link --overwrite ldid-procursus. Mata primero el proceso ldid colgado (sudo kill -9 <pid>) si ya lo has encontrado.
vphone-cli expone un socket de control del host (<bundle>/vphone.sock) para control programático — capturas de pantalla, toques, deslizamientos, teclas de hardware, portapapeles — cada acción devuelve una captura de pantalla en línea para pruebas E2E impulsadas por IA. Consulta vphone-mcp para un servidor MCP que lo envuelve.