lakr233/vphone-cliAvvia e gestisci iPhone virtuali su Apple Silicon con patch del firmware, varianti di jailbreak e funzionalità di ricerca sulla sicurezza per test e analisi iOS.
Avvia un iPhone virtuale tramite il framework Virtualization.framework di Apple utilizzando l'infrastruttura VM di ricerca PCC.
Host:
Dipendenze:
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 # installa le dipendenze, compila i sottomoduli della toolchain, crea il venv Python
./scripts/build.sh # compila + firma vphone-cli, crea il bundle .app, compila in cross vphoned
cd .build/vphone-cli.app/Contents/MacOS/
vphone-cli --help
Un singolo comando crea una VM end-to-end (download → patch → ripristino DFU → installazione CFW → primo avvio):
vphone-cli vm create myphone -V jb # -V / --variant
vphone-cli vm launch myphone
vphone-cli vm create esegue l'intera pipeline; i singoli passaggi seguenti ti consentono di gestirla manualmente o di rieseguire una singola fase.
vphone-cli vm list # elenca le VM (--json per lo scripting)
vphone-cli vm info myphone # mostra una VM
vphone-cli vm new myphone # crea un bundle vuoto (opzioni cpu/mem/disk)
vphone-cli vm config myphone --cpu 8 --memory 8192
vphone-cli vm clone myphone myphone-2 # clonazione APFS rapida, nuova identità del dispositivo
vphone-cli vm export myphone --out myphone.tzst # zstd veloce di default (--max = xz -9); --out può essere una directory (nome automatico <vm>.tzst/.txz); salta la directory di ripristino e i file di staging
vphone-cli vm import myphone.tzst --name restored
vphone-cli vm rename myphone iphone16
vphone-cli vm delete iphone16
vm create automatizza)vphone-cli vm new myphone # 1. bundle vuoto
vphone-cli fw prepare myphone --iphone-version 26.1 # 2. download + unione IPSW
vphone-cli fw patch myphone --variant jb # 3. patch della catena di avvio
vphone-cli vm launch myphone --dfu & # 4. avvio in DFU (in background)
vphone-cli restore myphone --get-shsh # recupero SHSH
vphone-cli restore myphone # ripristino DFU
vphone-cli vm stop myphone # arresto dell'avvio DFU
vphone-cli cfw install myphone --variant jb # 5. installazione CFW (mount host; richiede sudo)
vphone-cli vm launch myphone # 6. primo avvio
Aggiorna a una versione iOS più recente puntando fw prepare a un IPSW: --iphone-source /path/to.ipsw --cloudos-source /path/to.ipsw.
Cinque varianti di patch con bypass di sicurezza crescente — passane una a --variant:
| Variante | Catena di avvio | CFW | Note |
|---|---|---|---|
less | 4 patch | 2 fasi | Senza patch — mantiene le mitigazioni iOS attive |
regular | 42 patch | 10 fasi | Bypass AMFI/SSV/Img4/TXM |
dev | 53 patch | 12 fasi | + bypass entitlement/debug TXM |
jb | 113 patch | 14 fasi | + jailbreak completo (Sileo, installazione automatica di TrollStore al primo avvio) |
exp | 141 patch | 18 fasi | Superset di JB + patch di ricerca anti-rilevamento VM |
Consulta research/0_binary_patch_comparison.md per la ripartizione per componente.
ssh -p 22222 mobile@<vm-ip> (password alpine)ssh -p 22222 root@<vm-ip>vnc://<vm-ip>:5901Tutto ciò che vphone-cli crea risiede sotto ~/.vphone/ — mantenuto fuori dal repository e dalla .app affinché il bundle firmato resti portabile. Reindirizza l'intero albero con $VPHONE_ROOT:
| Percorso | Contenuti |
|---|---|
~/.vphone/ | La radice dati per utente — sovrascrivi l'intera posizione con $VPHONE_ROOT. |
~/.vphone/VMs/ | Bundle VM — una directory per VM. Questa è la libreria; sovrascrivi con $VPHONE_LIBRARY_ROOT. |
~/.vphone/ipsws/ | IPSW iPhone + cloudOS scaricati, memorizzati nella cache e riutilizzati tra le VM. |
~/.vphone/tools/ | Artefatti APFS seal-volume memorizzati nella cache (apfs_sealvolume_<version>) recuperati durante fw prepare. |
~/.vphone/debs/ | Pacchetti .deb memorizzati nella cache che l'installazione CFW jb/exp inserisce nel guest (Sileo, apt, …). |
~/.vphone/venv/ | Ambiente Python auto-provisionato (vedi Runtime Python; sovrascrivi con $VPHONE_VENV_DIR). |
Precedenza: le sovrascritture per singolo elemento ($VPHONE_LIBRARY_ROOT, $VPHONE_VENV_DIR) hanno priorità su $VPHONE_ROOT, che a sua volta ha priorità sul default ~/.vphone. Le cache ipsws/, tools/ e debs/ risiedono sempre direttamente sotto la radice attiva.
Opzione A — disabilita completamente SIP, poi disabilita AMFI tramite boot-arg (la più permissiva).
In Recovery (pressione prolungata sul pulsante di accensione → Terminale):
csrutil disable
csrutil allow-research-guests enable
Poi riavvia in macOS e imposta il boot-arg AMFI (richiede SIP completamente disattivato per avere effetto):
sudo nvram boot-args="amfi_get_out_of_my_way=1 -v" # riavvia dopo
Opzione B — mantieni SIP attivo (rilassato solo in debug), poi inserisci il binario nella lista consentita con amfidont (lascia AMFI attivo a livello di sistema).
In Recovery:
csrutil enable --without debug
csrutil allow-research-guests enable
Poi riavvia in macOS e:
vphone-amfidont # .build/vphone-cli.app/Contents/Resources/vphone-amfidont per build locali
| 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 — le restrizioni AMFI/debug non sono state bypassate; consulta Prerequisiti (amfi_get_out_of_my_way=1 o amfidont).
Virtualization is not available on this hardware — il tuo Mac è esso stesso una VM; l'avvio del guest PV=3 non può essere annidato. Usa un host macOS 15+ non annidato.
Bloccato su "Press home to continue" — connettiti tramite VNC e fai clic destro (clic con due dita) per simulare il pulsante home.
Le app di sistema non si installano — durante la configurazione di iOS, non scegliere Giappone o UE come regione (controlli normativi aggiuntivi che la VM non può soddisfare); scegli ad esempio Stati Uniti.
L'app si arresta in modo anomalo all'avvio con EXC_GUARD / GUARD_TYPE_MACH_PORT — riapplica la patch con vphone-cli fw patch <name> --variant <v> --force-exc-guard, poi ripristina/reinstalla (#291). Sempre attivo per le basi iOS 18.
Installa un .ipa/.tipa — usa il menu Install della VM in esecuzione (trascina e rilascia o selettore file).
cfw install si blocca durante la ri-firma di un binario di sistema (es. Campo), la memoria cresce senza limiti — bug noto in ldid-procursus fino a 2.1.5-procursus7 (l'attuale stable di Homebrew): bytes(uint64_t) chiama __builtin_clzll(0) senza guardia per lo zero, che è un comportamento indefinito, e su questa build si risolve in una lunghezza 0 che causa un underflow del contatore di loop unsigned — ldid gira scrivendo un byte alla volta in un buffer in crescita invece di terminare. Innescato da qualsiasi plist di entitlement contenente un valore intero esattamente 0 (alcuni binari di sistema Apple reali li hanno). Corretto a monte ma non ancora in una release taggata; ricompila dalla sorgente: brew install --HEAD ldid-procursus && brew link --overwrite ldid-procursus. Termina prima il processo ldid bloccato (sudo kill -9 <pid>) se lo hai già incontrato.
vphone-cli espone un socket di controllo host (<bundle>/vphone.sock) per il controllo programmatico — screenshot, tocco, swipe, tasti hardware, clipboard — ogni azione restituisce uno screenshot inline per test E2E guidati da IA. Consulta vphone-mcp per un server MCP che lo incapsula.