Lakr233/vphone-cli 来源：https://github.com/Lakr233/vphone-cli 🇰🇷한국어 | 🇯🇵日本語 | 🇨🇳中文 | 🇬🇧English # vphone-cli 基于 Apple 的虚拟化框架，利用 PCC 研究 VM 基础设施启动虚拟 iPhone。概念验证 (POC) ## 先决条件 宿主机： - Apple Silicon - macOS 15+ (Sequoia) - Xcode + iOS SDK（交叉编译客户端守护进程） - 放松 SIP/AMFI 以允许未签名二进制使用私有 PV=3 权限 依赖项： bash brew install [email protected] aria2 wget gnu-tar openssl@3 ldid-procursus sshpass keystone cmake libusb ipsw zstd ## 安装 bash brew install zqxwce/tap/vphone-cli ## 构建 bash git clone --recurse-submodules https://github.com/Lakr233/vphone-cli.git ./scripts/setup_tools.sh # 安装依赖、构建工具链子模块、创建 Python 虚拟环境 ./scripts/build.sh # 构建 + 签名 vphone-cli，打包 .app，交叉编译 vphoned cd .build/vphone-cli.app/Contents/MacOS/ vphone-cli --help ## 快速开始 一个命令即可端到端创建虚拟机（下载 → 修补 → DFU 恢复 → CFW 安装 → 首次启动）： bash vphone-cli vm create myphone -V jb # -V / --variant vphone-cli vm launch myphone ## 命令 vphone-cli vm create 运行整个流程；以下单独步骤可让您手动操作或重新运行某一阶段。 ### 管理 bash vphone-cli vm list # 列出虚拟机（--json 用于脚本） vphone-cli vm info myphone # 显示一个虚拟机 vphone-cli vm new myphone # 创建一个空包（可选 cpu/mem/disk） vphone-cli vm config myphone --cpu 8 --memory 8192 vphone-cli vm clone myphone myphone-2 # 快速 APFS 克隆，刷新设备标识 vphone-cli vm export myphone --out myphone.tzst # 默认使用 zstd 快速压缩（--max = xz -9）；--out 可以是目录（自动命名 .tzst/.txz）；跳过恢复目录和暂存文件 vphone-cli vm import myphone.tzst --name restored vphone-cli vm rename myphone iphone16 vphone-cli vm delete iphone16 ### 手动构建虚拟机（vm create 自动化的内容） bash vphone-cli vm new myphone # 1. 空包 vphone-cli fw prepare myphone --iphone-version 26.1 # 2. 下载 + 合并 IPSW vphone-cli fw patch myphone --variant jb # 3. 修补引导链 vphone-cli vm launch myphone --dfu & # 4. 启动进入 DFU（后台） vphone-cli restore myphone --get-shsh # 获取 SHSH vphone-cli restore myphone # DFU 恢复 vphone-cli vm stop myphone # 停止 DFU 引导 vphone-cli cfw install myphone --variant jb # 5. 安装 CFW（主机挂载；需要 sudo） vphone-cli vm launch myphone # 6. 首次启动 通过将 fw prepare 指向一个 IPSW 来更新到更新的 iOS：--iphone-source /path/to.ipsw --cloudos-source /path/to.ipsw。 ## 固件变体 五种修补变体，安全绕过程度递增——通过 --variant 传递一个： | 变体 | 引导链 | CFW | 备注 | | ———— | ———– | ——— | ————————————————————— | | less | 4 个补丁 | 2 个阶段 | 无补丁 — 保持 iOS 缓解措施启用 | | regular | 42 个补丁 | 10 个阶段 | 绕过 AMFI/SSV/Img4/TXM | | dev | 53 个补丁 | 12 个阶段 | + 绕过 TXM 权限/调试 | | jb | 113 个补丁 | 14 个阶段 | + 完整越狱（Sileo、TrollStore 首次启动自动安装） | | exp | 141 个补丁 | 18 个阶段 | 越狱超集 + 防虚拟机检测研究补丁 | 详见 research/0_binary_patch_comparison.md 了解每个组件的详细分解。 ## 运行与连接 - SSH（越狱）： ssh -p 22222 mobile@（密码 alpine） - SSH（regular/dev）： ssh -p 22222 root@ - VNC： vnc://:5901 ## 位置 vphone-cli 创建的所有内容都位于 ~/.vphone/ 下——保持在仓库和 .app 之外，以便签名的包保持可移植性。使用 $VPHONE_ROOT 重定向整个目录树： | 路径 | 内容 | | —————– | –––––––––––––––––––––––––––––––––––––––––––––– | | ~/.vphone/ | 每个用户的数据根目录——使用 $VPHONE_ROOT 覆盖整个位置。 | | ~/.vphone/VMs/ | 虚拟机包——每个虚拟机一个目录。这是库；使用 $VPHONE_LIBRARY_ROOT 覆盖。 | | ~/.vphone/ipsws/| 下载的 iPhone + cloudOS IPSW，跨虚拟机缓存和重用。 | | ~/.vphone/tools/| 在 fw prepare 期间获取的缓存 APFS 密封卷产物（apfs_sealvolume_）。 | | ~/.vphone/debs/ | jb/exp CFW 安装到客户端的缓存 .deb 包（Sileo、apt 等）。 | | ~/.vphone/venv/ | 自动配置的 Python 环境（参见 Python 运行时；使用 $VPHONE_VENV_DIR 覆盖）。 | 优先级：特定项目的覆盖（$VPHONE_LIBRARY_ROOT、$VPHONE_VENV_DIR）优先于 $VPHONE_ROOT，后者优先于 ~/.vphone 默认值。ipsws/、tools/ 和 debs/ 缓存始终位于活动根目录下。 ## SIP/AMFI 放松 选项 A — 完全禁用 SIP，然后通过启动参数禁用 AMFI（最宽松）。 在恢复模式下（长按电源键 → 终端）： bash csrutil disable csrutil allow-research-guests enable 然后重启进入 macOS 并设置 AMFI 启动参数（需要 SIP 完全关闭才能生效）： bash sudo nvram boot-args="amfi_get_out_of_my_way=1 -v" # 之后重启 选项 B — 保持 SIP 开启（仅调试放松），然后使用 amfidont 允许列表二进制文件（保持系统范围 AMFI 启用）。 在恢复模式下： bash csrutil enable --without debug csrutil allow-research-guests enable 然后重启进入 macOS 并： bash vphone-amfidont # 本地构建为 .build/vphone-cli.app/Contents/Resources/vphone-amfidont ## 测试环境 | 宿主机 | 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/调试限制未绕过；参见先决条件（amfi_get_out_of_my_way=1 或 amfidont）。 Virtualization is not available on this hardware — 您的 Mac 本身就是一个虚拟机；PV=3 客户端启动无法嵌套。请使用非嵌套的 macOS 15+ 宿主机。 卡在“Press home to continue” — 通过 VNC 连接并右键单击（两指点击）以模拟主屏幕按钮。 系统应用无法安装 — 在 iOS 设置期间，不要选择日本或欧盟作为您的地区（虚拟机无法满足的额外监管要求）；请选择例如美国。 应用启动时崩溃并出现 EXC_GUARD / GUARD_TYPE_MACH_PORT — 使用 vphone-cli fw patch --variant --force-exc-guard 重新修补，然后重新恢复/安装（参见 #291 (https://github.com/Lakr233/vphone-cli/issues/291)）。iOS 18 基础版本始终如此。 安装 .ipa/.tipa — 使用运行中虚拟机的安装菜单（拖放或文件选择器）。 cfw install 在重新签名系统二进制文件（例如 Campo）时挂起，内存无限增长 — 已知在 ldid-procursus 至 2.1.5-procursus7（当前 Homebrew stable）中存在错误：bytes(uint64_t) 调用 __builtin_clzll(0) 没有零保护，这是未定义行为，在此构建中解析为 0 长度，导致无符号循环计数器下溢——ldid 陷入每次写入一个字节到不断增长的缓冲区而非终止。触发于任何包含整数值恰好为 0 的权限 plist（一些真实的 Apple 系统二进制文件有这些）。上游已修复但尚未在标记版本中；从源代码重新构建：brew install --HEAD ldid-procursus && brew link --overwrite ldid-procursus。如果已经遇到，请先终止挂起的 ldid 进程（sudo kill -9 ）。 ## 自动化 vphone-cli 暴露一个主机控制套接字（/vphone.sock），用于程序化控制——截图、触摸、滑动、硬件按键、剪贴板——每个操作都返回内联截图，用于 AI 驱动的端到端测试。 参见 vphone-mcp (https://github.com/pluginslab/vphone-mcp) 了解封装它的 MCP 服务器。 ## 致谢 - wh1te4ever/super-tart-vphone-writeup (https://github.com/wh1te4ever/super-tart-vphone-writeup)