mirror of https://github.com/Lakr233/vphone-cli.git synced 2026-04-05 04:59:05 +08:00

Files

Lakr 5388e0c9c5 Squash merge startup-hang-fix into main

Prefix research patch comparison doc and normalize root markdown names

Rename research root markdown files to scoped topic names

2026-03-06 02:42:12 +08:00

7.2 KiB

Raw Blame History

🇰🇷한국어 | 🇯🇵日本語 | 🇨🇳中文 | 🇬🇧English

vphone-cli

通过 Apple 的 Virtualization.framework 使用 PCC 研究虚拟机基础设施引导虚拟 iPhone（iOS 26）。

测试环境

主机	iPhone 系统	CloudOS
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`

固件变体

提供三种补丁变体，安全绕过级别逐步递增：

变体	启动链	自定义固件	Make 目标
常规版	41 个补丁	10 个阶段	`fw_patch` + `cfw_install`
开发版	52 个补丁	12 个阶段	`fw_patch_dev` + `cfw_install_dev`
越狱版（WIP）	66 / 78 个补丁	14 个阶段	`fw_patch_jb` + `cfw_install_jb`

66 表示 JB 默认内核补丁计划；78 表示默认 + 可选内核补丁（VPHONE_JB_ENABLE_OPTIONAL=1）。

详见 research/00_patch_comparison_all_variants.md 了解各组件的详细分项对比。

先决条件

主机系统： PV=3 虚拟化要求 macOS 15+（Sequoia）。

禁用 SIP 和 AMFI —— 需要私有的 Virtualization.framework 权限。

重启到恢复模式（长按电源键），打开终端：

csrutil disable
csrutil allow-research-guests enable

重新启动回 macOS 后：

sudo nvram boot-args="amfi_get_out_of_my_way=1 -v"

再重启一次。

安装依赖：

brew install ideviceinstaller wget gnu-tar openssl@3 ldid-procursus sshpass keystone autoconf automake pkg-config libtool

Submodules —— 本仓库使用 git submodule 存储资源文件。克隆时请使用：

git clone --recurse-submodules https://github.com/Lakr233/vphone-cli.git

快速开始

make setup_machine            # 完全自动化完成"首次启动"流程（包含 restore/ramdisk/CFW）

手动设置

make setup_tools              # 安装 brew 依赖、构建 trustcache + libimobiledevice、创建 Python 虚拟环境
make build                    # 构建并签名 vphone-cli
make vm_new                   # 创建 vm/ 目录（ROM、磁盘、SEP 存储）
make fw_prepare               # 下载 IPSWs，提取、合并、生成 manifest
make fw_patch                 # 修补启动链（常规变体）
# 或：make fw_patch_dev       # 开发变体（+ TXM 权限/调试绕过）
# 或：make fw_patch_jb        # 越狱变体（+ 完整安全绕过）（WIP）

恢复过程

该过程需要 两个终端。保持终端 1 运行，同时在终端 2 操作。

# 终端 1
make boot_dfu                 # 以 DFU 模式启动 VM（保持运行）

# 终端 2
make restore_get_shsh         # 获取 SHSH blob
make restore                  # 通过 idevicerestore 刷写固件

安装自定义固件

在终端 1 中停止 DFU 引导（Ctrl+C），然后再次进入 DFU，用于 ramdisk：

# 终端 1
make boot_dfu                 # 保持运行

# 终端 2
make ramdisk_build            # 构建签名的 SSH ramdisk
make ramdisk_send             # 发送到设备

当 ramdisk 运行后（输出中应显示 Running server），打开第三个终端运行 iproxy 隧道，然后在终端 2 安装 CFW：

# 终端 3 —— 保持运行
iproxy 2222 22

# 终端 2
make cfw_install

首次启动

在终端 1 中停止 DFU 引导（Ctrl+C），然后：

make boot

这会为你提供 VM 的直接控制台。当看到 bash-4.4# 时，按回车并运行以下命令以初始化 shell 环境并生成 SSH 主机密钥：

export PATH='/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/bin/X11:/usr/games:/iosbinpack64/usr/local/sbin:/iosbinpack64/usr/local/bin:/iosbinpack64/usr/sbin:/iosbinpack64/usr/bin:/iosbinpack64/sbin:/iosbinpack64/bin'

mkdir -p /var/dropbear
cp /iosbinpack64/etc/profile /var/profile
cp /iosbinpack64/etc/motd /var/motd

# 生成 SSH 主机密钥（SSH 能正常工作所必需）
dropbearkey -t rsa -f /var/dropbear/dropbear_rsa_host_key
dropbearkey -t ecdsa -f /var/dropbear/dropbear_ecdsa_host_key

shutdown -h now

注意： 若不执行主机密钥生成步骤，dropbear（SSH 服务器）会接受连接但立刻关闭，因为它没有密钥进行握手。

后续启动

make boot

在另一个终端中启动 iproxy 隧道：

iproxy 22222 22222   # SSH
iproxy 5901 5901     # VNC
iproxy 5910 5910     # RPC

连接方式：

SSH： ssh -p 22222 root@127.0.0.1（密码：alpine）
VNC： vnc://127.0.0.1:5901
RPC： rpcclient -p 5910 127.0.0.1

常见问题（FAQ）

在做其他任何事情之前——先运行 git pull 确保你有最新版。

问：运行时出现 zsh: killed ./vphone-cli。

AMFI 未禁用。设置 boot-arg 并重启：

sudo nvram boot-args="amfi_get_out_of_my_way=1 -v"

问：系统应用（App Store、信息等）无法下载或安装。

在 iOS 初始设置过程中，请不要选择日本或欧盟地区作为你的国家/地区。这些地区要求额外的合规检查（如侧载披露、相机快门声等），虚拟机无法满足这些要求，因此系统应用无法正常下载安装。请选择其他地区（例如美国）以避免此问题。

问：卡在"Press home to continue"屏幕。

通过 VNC (vnc://127.0.0.1:5901) 连接，并在屏幕上右键单击任意位置（在 Mac 触控板上双指点击）。这会模拟 Home 按钮按下。

问：SSH 连接后立即关闭（Connection closed by 127.0.0.1）。

首次启动时未生成 dropbear 主机密钥。通过 VNC 或 make boot 控制台连接并运行：

export PATH='/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/bin/X11:/usr/games:/iosbinpack64/usr/local/sbin:/iosbinpack64/usr/local/bin:/iosbinpack64/usr/sbin:/iosbinpack64/usr/bin:/iosbinpack64/sbin:/iosbinpack64/bin'
mkdir -p /var/dropbear
dropbearkey -t rsa -f /var/dropbear/dropbear_rsa_host_key
dropbearkey -t ecdsa -f /var/dropbear/dropbear_ecdsa_host_key
killall dropbear
dropbear -R -p 22222

问：可以升级到更新的 iOS 版本吗？

可以。使用你想要的版本的 IPSW URL 覆盖 fw_prepare：

export IPHONE_SOURCE=/path/to/some_os.ipsw
export CLOUDOS_SOURCE=/path/to/some_os.ipsw
make fw_prepare
make fw_patch

我们的补丁是通过二进制分析（binary analysis）而非静态偏移（static offsets）应用的，因此更新的版本应该也能正常工作。如果出现问题，可以寻求 AI 的帮助。

致谢

wh1te4ever/super-tart-vphone-writeup

7.2 KiB Raw Blame History Unescape Escape