lakr233/vphone-cliBooten und Verwalten virtueller iPhones auf Apple Silicon mit Firmware-Patching, Jailbreak-Varianten und Sicherheitsforschungsfunktionen für iOS-Tests und -Analysen.
Booten Sie ein virtuelles iPhone über Apples Virtualization.framework unter Verwendung der PCC-Forschungs-VM-Infrastruktur.
Host:
Abhängigkeiten:
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 # installiert Abhängigkeiten, baut Toolchain-Submodule, erstellt die Python-Venv
./scripts/build.sh # baut + signiert vphone-cli, bündelt die .app, kreuzkompiliert vphoned
cd .build/vphone-cli.app/Contents/MacOS/
vphone-cli --help
Ein Befehl erstellt eine VM Ende-zu-Ende (Download → Patch → DFU-Restore → CFW-Installation → erster Boot):
vphone-cli vm create myphone -V jb # -V / --variant
vphone-cli vm launch myphone
vphone-cli vm create führt die gesamte Pipeline aus; die einzelnen Schritte unten ermöglichen es Ihnen, manuell zu steuern oder eine Stufe erneut auszuführen.
vphone-cli vm list # VMs auflisten (--json für Skripting)
vphone-cli vm info myphone # eine VM anzeigen
vphone-cli vm new myphone # leeres Bundle erstellen (cpu/mem/disk-Optionen)
vphone-cli vm config myphone --cpu 8 --memory 8192
vphone-cli vm clone myphone myphone-2 # schneller APFS-Klon, neue Geräteidentität
vphone-cli vm export myphone --out myphone.tzst # zstd standardmäßig schnell (--max = xz -9); --out kann ein Verzeichnis sein (automatische Namen <vm>.tzst/.txz); überspringt Restore-Verzeichnis + Staging-Dateien
vphone-cli vm import myphone.tzst --name restored
vphone-cli vm rename myphone iphone16
vphone-cli vm delete iphone16
vm create automatisiert)vphone-cli vm new myphone # 1. leeres Bundle
vphone-cli fw prepare myphone --iphone-version 26.1 # 2. IPSWs herunterladen + zusammenführen
vphone-cli fw patch myphone --variant jb # 3. Boot-Kette patchen
vphone-cli vm launch myphone --dfu & # 4. in DFU booten (Hintergrund)
vphone-cli restore myphone --get-shsh # SHSH abrufen
vphone-cli restore myphone # DFU-Restore
vphone-cli vm stop myphone # DFU-Boot stoppen
vphone-cli cfw install myphone --variant jb # 5. CFW installieren (Host-Mount; fragt nach sudo)
vphone-cli vm launch myphone # 6. erster Boot
Aktualisieren Sie auf ein neueres iOS, indem Sie fw prepare auf ein IPSW verweisen: --iphone-source /pfad/zu.ipsw --cloudos-source /pfad/zu.ipsw.
Fünf Patch-Varianten mit zunehmender Sicherheitsumgehung — übergeben Sie eine an --variant:
| Variante | Boot-Kette | CFW | Hinweise |
|---|---|---|---|
less | 4 Patches | 2 Phasen | Patchlos — hält iOS-Mitigations aktiv |
regular | 42 Patches | 10 Phasen | AMFI/SSV/Img4/TXM-Umgehung |
dev | 53 Patches | 12 Phasen | + TXM-Berechtigungs-/Debug-Umgehung |
jb | 113 Patches | 14 Phasen | + vollständiger Jailbreak (Sileo, TrollStore automatische Installation beim ersten Boot) |
exp | 141 Patches | 18 Phasen | JB-Obermenge + Anti-VM-Erkennungs-Forschungspatches |
Siehe research/0_binary_patch_comparison.md für die Aufschlüsselung pro Komponente.
ssh -p 22222 mobile@<vm-ip> (Passwort alpine)ssh -p 22222 root@<vm-ip>vnc://<vm-ip>:5901Alles, was vphone-cli erstellt, liegt unter ~/.vphone/ — außerhalb des Repos und der .app, damit das signierte Bundle portabel bleibt. Leiten Sie den gesamten Baum mit $VPHONE_ROOT um:
| Pfad | Inhalt |
|---|---|
~/.vphone/ | Das benutzerspezifische Daten-Root — überschreiben Sie den gesamten Speicherort mit $VPHONE_ROOT. |
~/.vphone/VMs/ | VM-Bundles — ein Verzeichnis pro VM. Dies ist die Bibliothek; überschreiben Sie mit $VPHONE_LIBRARY_ROOT. |
~/.vphone/ipsws/ | Heruntergeladene iPhone- + cloudOS-IPSWs, zwischengespeichert und über VMs hinweg wiederverwendet. |
~/.vphone/tools/ | Zwischengespeicherte APFS-Seal-Volume-Artefakte (apfs_sealvolume_<version>), die während fw prepare abgerufen werden. |
~/.vphone/debs/ | Zwischengespeicherte .deb-Pakete, die die jb/exp-CFW-Installation in den Gast legt (Sileo, apt, …). |
~/.vphone/venv/ | Automatisch bereitgestellte Python-Umgebung (siehe Python-Laufzeit; überschreiben Sie mit $VPHONE_VENV_DIR). |
Priorität: Die pro-Element-Überschreibungen ($VPHONE_LIBRARY_ROOT, $VPHONE_VENV_DIR) gewinnen über $VPHONE_ROOT, das über dem ~/.vphone-Standard gewinnt. Die ipsws/-, tools/- und debs/-Caches liegen immer direkt unter dem aktiven Root.
Option A — SIP vollständig deaktivieren, dann AMFI über Boot-Argument deaktivieren (am permissivsten).
Im Recovery-Modus (Power-Taste lange drücken → Terminal):
csrutil disable
csrutil allow-research-guests enable
Dann in macOS neu starten und das AMFI-Boot-Argument setzen (benötigt vollständig deaktiviertes SIP, um zu wirken):
sudo nvram boot-args="amfi_get_out_of_my_way=1 -v" # danach neu starten
Option B — SIP aktiviert lassen (nur Debug gelockert), dann die Binärdatei mit amfidont auf die Whitelist setzen (lässt AMFI systemweit aktiviert).
Im Recovery-Modus:
csrutil enable --without debug
csrutil allow-research-guests enable
Dann in macOS neu starten und:
vphone-amfidont # .build/vphone-cli.app/Contents/Resources/vphone-amfidont für lokale Builds
| 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 — AMFI/Debug-Einschränkungen sind nicht umgangen; siehe Voraussetzungen (amfi_get_out_of_my_way=1 oder amfidont).
Virtualization is not available on this hardware — Ihr Mac ist selbst eine VM; PV=3-Gast-Boot kann nicht verschachtelt werden. Verwenden Sie einen nicht verschachtelten macOS 15+-Host.
Hängt bei „Press home to continue" — verbinden Sie sich über VNC und klicken Sie mit der rechten Maustaste (Zwei-Finger-Klick), um die Home-Taste zu simulieren.
System-Apps lassen sich nicht installieren — wählen Sie während der iOS-Einrichtung nicht Japan oder die EU als Region (zusätzliche regulatorische Prüfungen, die die VM nicht erfüllen kann); wählen Sie z. B. die USA.
App stürzt beim Start mit EXC_GUARD / GUARD_TYPE_MACH_PORT ab — patchen Sie erneut mit vphone-cli fw patch <name> --variant <v> --force-exc-guard, dann erneut restoren/installieren (#291). Immer aktiv für iOS-18-Basen.
Eine .ipa/.tipa installieren — verwenden Sie das Install-Menü der laufenden VM (Drag-and-Drop oder Dateiauswahl).
cfw install hängt beim Neusignieren einer System-Binärdatei (z. B. Campo), Speicher wächst unbegrenzt — bekannter Bug in ldid-procursus bis 2.1.5-procursus7 (das aktuelle Homebrew stable): bytes(uint64_t) ruft __builtin_clzll(0) ohne Zero-Guard auf, was undefiniertes Verhalten ist, und löst sich in diesem Build zu einer 0-Länge auf, die einen unsigned Schleifenzähler unterläuft — ldid dreht sich und schreibt ein Byte nach dem anderen in einen wachsenden Puffer, statt zu terminieren. Ausgelöst durch jede Entitlements-Plist, die einen Integer-Wert von exakt 0 enthält (einige echte Apple-System-Binärdateien haben diese). Upstream behoben, aber noch nicht in einem getaggten Release; aus Quelle neu bauen: brew install --HEAD ldid-procursus && brew link --overwrite ldid-procursus. Töten Sie zuerst den hängenden ldid-Prozess (sudo kill -9 <pid>), falls Sie ihn bereits getroffen haben.
vphone-cli stellt einen Host-Steuerungs-Socket (<bundle>/vphone.sock) für programmatische Steuerung bereit — Screenshots, Touch, Wischgesten, Hardware-Tasten, Zwischenablage — jede Aktion gibt einen Inline-Screenshot für KI-gesteuertes E2E-Testing zurück. Siehe vphone-mcp für einen MCP-Server, der dies umschließt.