Run a virtual iPhone on an Apple Silicon Mac.
Swift
docs: organize guides and research, align firmware compatibility data
Lakr74924cdf95f2
diff --git a/AGENTS.md b/AGENTS.mdindex 724d47b5..51b3d74c 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -9,8 +9,8 @@ Virtual iPhone boot tool using Apple's Virtualization.framework with PCC researc- **Boot (DFU):** `make boot_dfu`- **All targets:** `make help`- **AMFI refuses `vphone-vm`?** `make amfi_allow` (asks for root). Re-run it after every build — it allowlists cdhashes. `make amfi_status` to look, `make amfi_off` to revert. See Key Patterns.-- **Restore:** `vphone-cli restore`, in process. Vendored libirecovery + idevicerestore (`sources/MobileRecoveryCore`, `sources/MobileRestoreCore`) over the `AppleMobileDeviceLibrary` xcframeworks. No interpreter, no environment to provision, no setup step. See `research/p2_restore_off_python.md`.-- **Platform:** macOS 15+ (Sequoia). `vphone-vm` needs amfid to accept its private entitlements: either SIP off with `amfi_get_out_of_my_way=1`, or SIP on (`--without debug`) plus an allowlist bypass the user runs. Both are in README's "SIP/AMFI Relaxation"; neither is installed by this project.+- **Restore:** `vphone-cli restore`, in process. Vendored libirecovery + idevicerestore (`sources/MobileRecoveryCore`, `sources/MobileRestoreCore`) over the `AppleMobileDeviceLibrary` xcframeworks. No interpreter, no environment to provision, no setup step. See `research/restore/p2_restore_off_python.md`.+- **Platform:** macOS 15+ (Sequoia). `vphone-vm` needs amfid to accept its private entitlements: either SIP off with `amfi_get_out_of_my_way=1`, or SIP on (`--without debug`) plus an allowlist bypass the user runs. Both are in `docs/guides/host-setup.md`; neither is installed by this project.- **Language:** Swift 6.0 (SwiftPM), private APIs via [Dynamic](https://github.com/mhdhejazi/Dynamic). This package's own manifest is `swift-tools-version:6.0`, but the **toolchain floor is Swift 6.2**: `libcapstone-spm` declares 6.2 so that it can reach `CSetting.disableWarning` instead of `.unsafeFlags`, which is what lets it be depended on by version at all.- **Dependencies:** seven SwiftPM packages, every one resolved by URL and **every one by version** — there is no `vendor/` directory, no `branch:` requirement, and `Package.resolved` pins fourteen once transitives are counted. The only git submodule is `scripts/repos/insert_dylib`, a build-time test reference. **No Python anywhere, and no Homebrew package at runtime** — see Tiers below.- **Tiers.** Three environments run code here and the rules differ. **build** (the machine that builds the `.app`) may use Xcode, `xcrun`, clang, swift, git and Homebrew. **dist** (the shipped `.app`, on a clean macOS) may use `/usr/lib`, `/System` and the bundle — nothing else, no `PATH` lookup. **guest** (inside the VM) is out of host self-containment scope. Every script declares its tier on **line 2** (`# vphone-tier: dist`); `scripts/dist_manifest.sh` reads those and is what `build.sh` and `make bundle` stage from, so a script that declares nothing ships nowhere. `make check-aux` gates all of it. The dist tier's registered-exception list is **empty** and a release requires it to stay that way.@@ -193,7 +193,7 @@ research/ # Detailed firmware/patch documentation- **Three host binaries, one of them entitled.** `vphone-cli` carries no entitlements, so it launches on any host and is always there to explain what is wrong. `vphone-vm` holds all 7 private keys and is the only thing amfid can refuse. `vphone-archive` does the unpacking. **Do not sign `vphone-cli` with entitlements** — that is how it used to be, and it is why the entry point could not start without a bypass already running.- **The AMFI bypass is ours, and it writes heap, not code.** `vphone-amfi-allow` (`sources/vphone-amfi-allow/`, this project's copy of [Lakr233/amfi-allow](https://github.com/Lakr233/amfi-allow)) puts the cdhashes of both `vphone-vm` copies into `/Library/Preferences/com.apple.security.coderequirements.plist` — a file AMFI already reads — and flips one byte of `_isRunningInternalBuild` in amfid's `AMFIRequirementsManager` singleton so it consults that file. It is an **allowlist**, scoped to the cdhashes you name; do not describe it as a global switch. `make amfi_allow` runs it, `amfi_status` shows it, `amfi_off` removes it. It is a **per-build** step, because a cdhash changes with every signature. It must be **arm64e** to match amfid's slice, which is why it is a clang rule and not a SwiftPM target. The heap write is the load-bearing detail: `vphone-letmein` and LLDB-based tools dirty an executable page, and on a host with `vm.cs_system_enforcement = 1` the kernel kills amfid for that and takes the guest with it.- **Guest launches go through `VPhoneGuestLaunchPlanner`** (`VPhoneCore`). It resolves `vphone-vm` as a sibling of the running image — never through `PATH` — checks its two PV=3 entitlements, then probes with `vphone-vm --help` for SIGKILL. A refusal is reported with the exact command the user has to run; the planner never arranges a bypass itself. Never spawn the guest directly.-- **Restore runs in `vphone-cli`'s own process.** `VPhoneRestore` calls `vphone_restore_run()` in `MobileRestoreCore`; there is no subprocess, no bridge script and no environment to resolve first. The three commands the old Python bridge exposed became `restore --get-shsh`, `restore` and `restore --offline`; its fourth, `usbmux-list`, had no call site and was not ported. `research/p2_restore_off_python.md` has the decision and the behaviour table.+- **Restore runs in `vphone-cli`'s own process.** `VPhoneRestore` calls `vphone_restore_run()` in `MobileRestoreCore`; there is no subprocess, no bridge script and no environment to resolve first. The three commands the old Python bridge exposed became `restore --get-shsh`, `restore` and `restore --offline`; its fourth, `usbmux-list`, had no call site and was not ported. `research/restore/p2_restore_off_python.md` has the decision and the behaviour table.- **Private API access:** Via [Dynamic](https://github.com/mhdhejazi/Dynamic) library (runtime method dispatch from pure Swift). No ObjC bridge.- **App lifecycle:** `vphone-vm/main.swift` → `VPhoneGuestApp.run()` → `NSApplication` + `VPhoneAppDelegate`. Entry points hold no logic.- **Configuration:** `ArgumentParser` → `VPhoneBootCLI` (in `VPhoneCore`, parsed by both binaries) → `VPhoneVirtualMachine.Options` → `VZVirtualMachineConfiguration`.@@ -243,7 +243,7 @@ There is none, and adding any is a regression.returns nothing; that is the standing check.- There is no environment to activate and no dependency list to install. Therestore backend was the last holdout and is now `sources/VPhoneRestore` over- two vendored C targets — see `research/p2_restore_off_python.md`.+ two vendored C targets — see `research/restore/p2_restore_off_python.md`.- A patch, a probe, a format reader or a device protocol belongs in Swift,where it is built, signed, gated by `make check-aux` and tested witheverything else. Adding an interpreter back brings with it a provisioningdiff --git a/README.md b/README.mdindex de5573f7..66df0433 100644--- a/README.md+++ b/README.md@@ -1,56 +1,18 @@-<div align="right"><strong><a href="./docs/README_ko.md">🇰🇷한국어</a></strong> | <strong><a href="./docs/README_ja.md">🇯🇵日本語</a></strong> | <strong><a href="./docs/README_zh.md">🇨🇳中文</a></strong> | <strong><a href="./docs/README_ru.md">🇷🇺Русский</a></strong> | <strong><a href="./docs/README_pt.md">🇧🇷Português</a></strong> | <strong>🇬🇧English</strong></div>+<div align="right"><strong>English</strong> · <a href="docs/README_zh.md">中文</a> · <a href="docs/README_ja.md">日本語</a> · <a href="docs/README_ko.md">한국어</a> · <a href="docs/README_ru.md">Русский</a> · <a href="docs/README_pt.md">Português</a></div># vphone-cli-Boot a virtual iPhone via Apple's Virtualization.framework using PCC research VM infrastructure.+Boot a virtual iPhone with Apple's Virtualization.framework and PCC research VM infrastructure.-+-## Prerequisites+The supported firmware flow is **JB only**. It applies the required system patches and installs **vphoned** for host control. It leaves the guest user environment alone: no package manager, SSH server, VNC server, or first-boot bootstrap is installed.-**To run it:**+## Quick start-- Apple Silicon-- macOS 15+ (Sequoia)-- [SIP/AMFI relaxation to allow private PV=3 entitlements with unsigned-binary](#sipamfi-relaxation)+Use an Apple Silicon Mac running macOS 15 or newer. The host must permit PV=3 research guests and the private entitlements on `vphone-vm`; see [host setup](docs/guides/host-setup.md) before the first boot. A Mac running inside another VM cannot boot this guest.-**Nothing else.** No Homebrew packages, no interpreter, no package environment,-no Xcode. Everything vphone-cli runs is either a system binary under `/usr/bin`,-`/bin`, `/usr/sbin` or `/sbin`, or is inside the `.app` — including the signer-(it replaced `ldid`), the archive reader (`gtar`, `zstd`, `unzip`), the firmware-catalogue and IM4P/AEA handling (`ipsw`), and the vphoned daemon installed in the guest, which is cross-compiled at build time and shipped-rather than built on your machine. `make check-aux` is the gate that keeps it-that way.--**To build it from source**, add Xcode for the iOS SDK used to compile vphoned.--## Install--```bash-brew install zqxwce/tap/vphone-cli-```--## Build--```bash-git clone --recurse-submodules https://github.com/Lakr233/vphone-cli.git--./scripts/build.sh # build + sign vphone-cli, cross-compile the guest- # binaries, bundle the .app--cd .build/vphone-cli.app/Contents/MacOS/-vphone-cli --help-```--`./scripts/setup_tools.sh` is optional and builds one thing: `insert_dylib`, the-independent reference a Mach-O test compares the Swift dylib injector against.-Nothing shipped runs it.--## Quick Start--One command creates a VM end-to-end (download → patch → DFU restore → CFW install → first boot):--```bash+```shvphone-cli vm create myphone \--iphone-source /path/to/iPhone17,3_Restore.ipsw \--cloudos-source /path/to/cloudOS.ipsw@@ -58,195 +20,46 @@ vphone-cli vm create myphone \vphone-cli vm launch myphone```-The single supported firmware mode is JB. Creation installs vphoned and the-required system patches, then checks that vphoned connects. It does not install-a package manager, SSH server, or user bootstrap.--## Commands--`vphone-cli vm create` runs the whole pipeline; the individual steps below let you drive it manually or re-run one stage.--### Manage--```bash-vphone-cli vm list # list VMs (--json for scripting)-vphone-cli vm info myphone # show one VM-vphone-cli vm new myphone # create an empty bundle (cpu/mem/disk options)-vphone-cli vm config myphone --cpu 8 --memory 8192-vphone-cli vm clone myphone myphone-2 # fast APFS clone, fresh device identity-vphone-cli vm export myphone --out myphone.tzst # zstd fast by default (--max = xz -9); --out may be a dir (auto-names <vm>.tzst/.txz); skips restore dir + staging files-vphone-cli vm import myphone.tzst --name restored-vphone-cli vm rename myphone iphone16-vphone-cli vm delete iphone16-```--### Build a VM manually (what `vm create` automates)+`vm create` prepares and patches firmware, restores the VM, installs the JB system changes and vphoned, then boots once to check a real vphoned ping. **It stops that verification boot before returning.** Run `vm launch` to keep using the VM. The create flow needs network access for Apple's restore ticket and asks for administrator authentication during CFW installation.-```bash-vphone-cli vm new myphone # 1. empty bundle-vphone-cli fw prepare myphone --iphone-source /path/to/iPhone17,3_Restore.ipsw \- --cloudos-source /path/to/cloudOS.ipsw # 2. merge IPSWs-vphone-cli fw patch myphone # 3. patch the JB boot chain+For local validation, iPhone17,3 **26.6.2 (23G90)** and **27.0 (24A435)** both reached the lock screen and answered vphoned ping with cloudOS **26.4 (23E5207q)**. See [compatibility and evidence](docs/guides/compatibility.md); other firmware combinations are not implied by these results.-vphone-cli vm launch myphone --dfu & # 4. boot into DFU (background)-vphone-cli restore myphone # fetch a ticket and DFU restore-vphone-cli vm stop myphone # stop the DFU boot+## Install or build-vphone-cli cfw install myphone # 5. install CFW (host-mount; asks for sudo)-vphone-cli vm launch myphone # 6. first boot-```+A distributed `.app` uses macOS system tools and its own bundled binaries; it does not need Homebrew, Python, or Xcode to run. Building from source does not install a separate runtime environment.-Update to a newer iOS by pointing `fw prepare` at an IPSW: `--iphone-source /path/to.ipsw --cloudos-source /path/to.ipsw`.+Building from source needs Xcode, including its iPhoneOS SDK for vphoned:-The restore command runs in `vphone-cli`'s own process. It drives vendored-libirecovery and idevicerestore directly — no external restore tool, no setup-step before the first one works. Use `restore --get-shsh` separately if you-need to save a ticket, then add `--offline` to restore from that `.shsh`-instead of asking Apple for a fresh one.--## Firmware Mode--The CLI exposes one firmware mode: JB. There is no `--variant` choice.--See [`research/0_binary_patch_comparison.md`](./research/0_binary_patch_comparison.md) for the per-component breakdown.--## Running & Connecting--- **SSH (jailbreak):** `ssh -p 22222 mobile@<vm-ip>` (password `alpine`)-- **VNC:** `vnc://<vm-ip>:5901`--## Locations--Everything vphone-cli creates lives under `~/.vphone/` — kept outside the repo and the `.app` so the signed bundle stays portable. Redirect the whole tree with `$VPHONE_ROOT`:--| Path | Contents |-| ----------------- | -------------------------------------------------------------------------------------------- |-| `~/.vphone/` | The per-user data root — override the entire location with `$VPHONE_ROOT`. |-| `~/.vphone/VMs/` | VM bundles — one directory per VM. This is the library; override with `$VPHONE_LIBRARY_ROOT`. |-| `~/.vphone/ipsws/`| Downloaded iPhone + cloudOS IPSWs, cached and reused across VMs. |-| `~/.vphone/tools/`| Cached APFS seal-volume artifacts used by firmware patching. |--Precedence: the per-item override `$VPHONE_LIBRARY_ROOT` wins over `$VPHONE_ROOT`, which wins over the `~/.vphone` default. The `ipsws/`, `tools/`, and `debs/` caches always sit directly under whichever root is active.--## SIP/AMFI Relaxation--**Option A — fully disable SIP, then disable AMFI via boot-arg (most permissive).**--In Recovery (long-press power → Terminal):--```bash-csrutil disable-csrutil allow-research-guests enable-```--Then reboot into macOS and set the AMFI boot-arg (needs SIP fully off to take effect):--```bash-sudo nvram boot-args="amfi_get_out_of_my_way=1 -v" # reboot after+```sh+git clone --recurse-submodules https://github.com/Lakr233/vphone-cli.git+cd vphone-cli+make build+.build/release/vphone-cli --help```-This is still the simplest path, and the only one that needs nothing running-alongside the VM: with AMFI relaxed, `vphone-vm` launches on its own.+`make build` signs and bundles the binaries. After every rebuild, a host using the AMFI allowlist must run `make amfi_allow` again because the signed cdhash changes. See [host setup](docs/guides/host-setup.md).-**Option B — keep SIP on (debug-only relaxed) and allowlist this build** (AMFI-stays enabled the rest of the time, and for every binary you did not allow).+## Everyday commands-In Recovery:+| Task | Command |+| --- | --- |+| List VMs | `vphone-cli vm list` |+| Inspect a VM | `vphone-cli vm info myphone` |+| Start its window | `vphone-cli vm launch myphone` |+| Stop it | `vphone-cli vm stop myphone` |+| Back it up | `vphone-cli vm export myphone --out myphone.tzst` |+| Restore a backup | `vphone-cli vm import myphone.tzst --name restored` |+| Inspect firmware pairings | `vphone-cli fw catalog` |+| Check the host | `vphone-cli host preflight` |-```bash-csrutil enable --without debug-csrutil allow-research-guests enable-```+VMs and downloaded firmware live under `~/.vphone/` by default. `VPHONE_ROOT` relocates the tree; `VPHONE_LIBRARY_ROOT` overrides just the VM library. Use `vphone-cli <group> --help` for current command options.-Then reboot into macOS and run:--```bash-make amfi_allow # asks for root; run it again after every build-make amfi_status # show the allowlist, and whether this host can carry one-make amfi_off # remove it and restart amfid clean-```+## Documentation-That runs `vphone-amfi-allow`, which is built from this repository's own C and-ships inside the `.app`. It writes two things:--* the cdhashes of **both** copies of `vphone-vm` into- `/Library/Preferences/com.apple.security.coderequirements.plist`, which AMFI- already reads — this is a feature amfid ships, not a hole;-* one byte of amfid's **heap**, to flip the `_isRunningInternalBuild` flag that- makes it consult that file in the first place.--Both, because `make boot` launches both: `boot_binary_check` runs-`.build/release/vphone-vm` and the boot itself runs the one inside the `.app`.-They sign under different identifiers and hash differently, so allowing one-covers exactly half the flow.--**Re-run it after every build.** It allowlists cdhashes, and those change with-every signature — including a bare `swift build`.--`vphone-vm` is the binary to allow. `vphone-cli` carries no entitlements and-always launches, so its cdhash is not the one you want.--> **Be clear about what this allows.** It is an allowlist keyed on cdhash:-> amfid keeps enforcing for every binary you did not name. `make amfi_off`-> removes the file and restarts amfid.->-> The one byte is in amfid's heap, not its `__TEXT`, and that is the whole-> reason this works. Earlier attempts patched the code — `vphone-letmein`-> overwrote the `ldrb` in `-[AMFIPathValidator_macos validateWithError:]`, and-> LLDB-based tools plant a `BRK` for a breakpoint. Both leave a dirty unsigned-> executable page, and on a host where `sysctl vm.cs_system_enforcement` reads-> 1 — as it does on macOS 27.0 (26A428), arm64e, with exactly the `csrutil`-> settings above — the kernel validates that page on the next fault, kills-> amfid, and takes the guest down with it. The sysctl is read-only at runtime,-> so no amount of care makes "patch the code" survive it. A heap write is not-> code, so enforcement has nothing to object to.--## Tested Environments--| 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,6 26.6.1 | `17,3_26.6.2_23G90` | `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` |-| Mac16,11 27.0b2 | `17,3_27.0_24A5430a` | `26.4-23E5207q` |-| Mac16,6 26.6.1 | `17,3_27.0_24A435` | `26.4-23E5207q` |--## FAQ--**`zsh: killed ./vphone-vm`** — AMFI/debug restrictions aren't bypassed; see [SIP/AMFI Relaxation](#sipamfi-relaxation) — either `amfi_get_out_of_my_way=1` (Option A), or `make amfi_allow` for this build (Option B). If you ran it before your last build, run it again: the allowlist is keyed on cdhash, and signing changes that. Note this cannot happen to `vphone-cli` itself: it carries no entitlements, so if *it* is being killed, something else is wrong.--**`Virtualization is not available on this hardware`** — your Mac is itself a VM; PV=3 guest boot can't nest. Use a non-nested macOS 15+ host.--**Stuck on "Press home to continue"** — connect via VNC and right-click (two-finger click) to simulate the home button.--**System apps won't install** — during iOS setup, don't pick Japan or the EU as your region (extra regulatory checks the VM can't satisfy); pick e.g. United States.--**App crashes on launch with `EXC_GUARD` / `GUARD_TYPE_MACH_PORT`** — re-patch with `vphone-cli fw patch <name> --force-exc-guard`, then re-restore/install ([#291](https://github.com/Lakr233/vphone-cli/issues/291)). Always on for iOS 18 bases.--**Install a `.ipa`/`.tipa`** — use the running VM's Install menu (drag-drop or file picker).--**Do I need Homebrew, or Xcode, to use this?** — No. `vphone-cli` runs on a clean macOS 15+: everything it shells out to is in `/usr/bin`, `/bin`, `/usr/sbin` or `/sbin`, and everything else is inside the `.app`. `make check-aux` is the gate that keeps it that way — it walks the bundle's dependency closure, checks the bundle holds exactly what it is supposed to, scans every shipped script for a `PATH` lookup, and smoke-tests the binaries with `env -i PATH=/usr/bin:/bin`. Building from source needs Xcode for the iOS SDK used to compile vphoned.--**`cfw install` hangs re-signing a system binary (e.g. `Campo`), memory climbing unbounded** — this was a bug in `ldid-procursus` up to `2.1.5-procursus7`: `bytes(uint64_t)` called `__builtin_clzll(0)` with no zero-guard, which is undefined behavior, and on that build resolved to a `0`-length that underflowed an unsigned loop counter, so `ldid` span writing one byte at a time into a growing buffer instead of terminating. Any entitlements plist with an integer value of exactly `0` triggered it, and some real Apple system binaries have one. It cannot happen any more: signing is `vphone-cli sign`, in-process, and `ldid` is not installed, invoked or shipped.--## Automation--`vphone-cli` exposes a host control socket (`<bundle>/vphone.sock`) for programmatic control — screenshots, touch, swipes, hardware keys, clipboard — each action returning an inline screenshot for AI-driven E2E testing. See [vphone-mcp](https://github.com/pluginslab/vphone-mcp) for an MCP server wrapping it.+- [Documentation index](docs/README.md) — setup, workflows, compatibility, troubleshooting, and translations.+- [Create and run a VM](docs/guides/create-and-run.md) — full flow, manual stages, storage, and vphoned.+- [Research index](research/README.md) — patch inventory, firmware analysis, restore work, and historical notes.+- [Patch inventory](research/0_binary_patch_comparison.md) — per-component patch breakdown and historical variant comparison. Only JB is exposed by the current CLI.## Acknowledgementsdiff --git a/docs/README.md b/docs/README.mdnew file mode 100644index 00000000..c225d9c7--- /dev/null+++ b/docs/README.md@@ -0,0 +1,25 @@+# Documentation++[Project overview](../README.md) · [Research notes](../research/README.md)++Start with the [one-command VM flow](guides/create-and-run.md). The guides below describe the current **JB-only** CLI. Older patch variants and installation experiments remain in research notes as historical context, not supported user workflows.++| Guide | Use it for |+| --- | --- |+| [Host setup](guides/host-setup.md) | Apple Silicon, SIP/AMFI settings, signing and preflight |+| [Create and run a VM](guides/create-and-run.md) | Firmware inputs, full or manual pipeline, vphoned, storage and backups |+| [Compatibility](guides/compatibility.md) | Verified firmware pairs and what the checks actually prove |+| [Troubleshooting](guides/troubleshooting.md) | Launch refusals, restore failures, Home key and app problems |++## Translations++[中文](README_zh.md) · [日本語](README_ja.md) · [한국어](README_ko.md) · [Русский](README_ru.md) · [Português](README_pt.md)++These pages give a translated overview and quick start. The English guides above hold the detailed, current procedures so that a change to the host or firmware flow has one place to update.++## For contributors++- [Research index](../research/README.md) groups the patch and implementation records by subject.+- [Patch inventory](../research/0_binary_patch_comparison.md) is the canonical per-component comparison.+- `make help` and `vphone-cli <group> --help` show the current command surface.+- `make check-aux` checks the bundled application's runtime dependency closure.diff --git a/docs/README_ja.md b/docs/README_ja.mdindex bb11374c..4b26b6cc 100644--- a/docs/README_ja.md+++ b/docs/README_ja.md@@ -1,236 +1,38 @@-<div align="right"><strong><a href="./README_ko.md">🇰🇷한국어</a></strong> | <strong>🇯🇵日本語</strong> | <strong><a href="./README_zh.md">🇨🇳中文</a></strong> | <strong><a href="./README_ru.md">🇷🇺Русский</a></strong> | <strong><a href="./README_pt.md">🇧🇷Português</a></strong> | <strong><a href="../README.md">🇬🇧English</a></strong></div>+<div align="right"><a href="../README.md">English</a> · <a href="README_zh.md">中文</a> · <strong>日本語</strong> · <a href="README_ko.md">한국어</a> · <a href="README_ru.md">Русский</a> · <a href="README_pt.md">Português</a></div># vphone-cli-PCC リサーチ VM インフラストラクチャを使用し、Apple の Virtualization.framework 経由で仮想 iPhone を起動します。+Apple の Virtualization.framework と PCC 研究用 VM 基盤を使って、仮想 iPhone を起動します。-+-## 前提条件--**実行に必要なもの:**--- Apple Silicon-- macOS 15+ (Sequoia)-- [未署名バイナリでプライベートな PV=3 エンタイトルメントを許可するための SIP/AMFI の緩和](#sipamfi-の緩和)--**それ以外は何も要りません。** Homebrew パッケージも、インタープリタも、パッケージ環境も、-Xcode も不要です。vphone-cli が実行するものは、`/usr/bin`・`/bin`・`/usr/sbin`・`/sbin`-にあるシステムバイナリか、`.app` の中にあるもののどちらかです。署名器(`ldid` の置き換え)、-アーカイブ処理(`gtar`・`zstd`・`unzip`)、ファームウェアカタログと IM4P/AEA の処理-(`ipsw`)、そして CFW インストーラがゲストに入れる 5 つの iOS バイナリ——これらは-ビルド時にクロスコンパイルして同梱されるので、手元のマシンではコンパイルしません。-その状態を保つゲートが `make check-aux` です。--**ソースからビルドする場合**は、Xcode(その 5 つのゲストバイナリのクロスコンパイルに-iOS SDK を使います)と `git-lfs`(`git clone` が `scripts/resources` のアーカイブを-取得するのに必要)が追加で要ります。--## インストール--```bash-brew install zqxwce/tap/vphone-cli-```--## ビルド--```bash-brew install git-lfs-git clone --recurse-submodules https://github.com/Lakr233/vphone-cli.git--./scripts/build.sh # vphone-cli のビルド + 署名、ゲストバイナリのクロスコンパイル、.app のバンドル--cd .build/vphone-cli.app/Contents/MacOS/-vphone-cli --help-```--`./scripts/setup_tools.sh` は任意で、ビルドするのは `insert_dylib` ひとつだけです。-Mach-O のテストが Swift の dylib インジェクタをバイト単位で照合するための独立した参照で、-配布物がこれを実行することはありません。+公開されているファームウェア構成は **JB のみ**です。必要なシステムパッチとホスト制御用の vphoned を導入します。ゲストのユーザー環境はそのままにし、パッケージマネージャー、SSH、VNC、初回起動時の bootstrap はインストールしません。## クイックスタート-1 つのコマンドで VM をエンドツーエンドで作成します(ダウンロード → パッチ → DFU 復元 → CFW インストール → 初回起動):+Apple Silicon、macOS 15 以降、および PV=3 研究用 VM と `vphone-vm` の権限を許可する[ホスト設定](guides/host-setup.md)が必要です。-```bash-vphone-cli vm create myphone -V jb # -V / --variant+```sh+vphone-cli vm create myphone \+ --iphone-source /path/to/iPhone17,3_Restore.ipsw \+ --cloudos-source /path/to/cloudOS.ipswvphone-cli vm launch myphone```-## コマンド--`vphone-cli vm create` はパイプライン全体を実行します。以下の個別ステップを使うと、手動で操作したり 1 つの段階を再実行したりできます。--### 管理--```bash-vphone-cli vm list # VM の一覧表示(スクリプト用に --json)-vphone-cli vm info myphone # 1 つの VM を表示-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 fast by default (--max = xz -9); --out がディレクトリなら <vm>.tzst/.txz を自動命名; 復元ディレクトリ + ステージングファイルをスキップ-vphone-cli vm import myphone.tzst --name restored-vphone-cli vm rename myphone iphone16-vphone-cli vm delete iphone16-```--### VM を手動でビルドする(`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. 初回起動-```--新しい iOS に更新するには、`fw prepare` を IPSW に向けます: `--iphone-source /path/to.ipsw --cloudos-source /path/to.ipsw`。--ステップ 4 と 5 は `vphone-cli` 自身のプロセス内で実行されます。`restore` は同梱の-libirecovery と idevicerestore を直接駆動します — 外部の復元ツールも、最初の 1 回の前に-必要なセットアップ手順もありません。`--offline` を付けると、Apple に新しい ticket を-要求する代わりに、VM の横に保存済みの `.shsh` で復元します。--## ファームウェアバリアント--セキュリティバイパスの度合いが段階的に増す 5 つのパッチバリアント — いずれか 1 つを `--variant` に渡します:--| バリアント | ブートチェーン | CFW | 備考 |-| ------------ | ----------- | --------- | ----------------------------------------------------------------- |-| `less` | 4 patches | 2 phases | パッチなし — iOS の緩和策を有効なまま維持 |-| `regular` | 42 patches | 10 phases | AMFI/SSV/Img4/TXM バイパス |-| `dev` | 53 patches | 12 phases | + TXM エンタイトルメント/デバッグバイパス |-| `jb` | 113 patches | 14 phases | + 完全な脱獄(Sileo、TrollStore を初回起動時に自動インストール) |-| `exp` | 141 patches | 18 phases | JB のスーパーセット + VM 検出対策リサーチパッチ |--コンポーネントごとの内訳については [`research/0_binary_patch_comparison.md`](../research/0_binary_patch_comparison.md) を参照してください。--## 実行と接続--- **SSH(脱獄):** `ssh -p 22222 mobile@<vm-ip>`(パスワード `alpine`)-- **SSH(regular/dev):** `ssh -p 22222 root@<vm-ip>`-- **VNC:** `vnc://<vm-ip>:5901`--## 場所--vphone-cli が生成するものはすべて `~/.vphone/` 以下に置かれます — 署名済みバンドルがポータブルであり続けるよう、リポジトリと `.app` の外に保管されます。`$VPHONE_ROOT` でツリー全体をリダイレクトできます:+`vm create` は準備、JB パッチ、DFU 復元、CFW インストールを実行し、初回起動で vphoned に ping します。**確認用の起動は成功後に停止します。** 継続して使うには `vm launch` を実行してください。復元にはネットワーク接続、CFW インストールには管理者認証が必要です。-| パス | 内容 |-| ----------------- | ------------------------------------------------------------------------------------------ |-| `~/.vphone/` | ユーザー別データルート — `$VPHONE_ROOT` で場所全体を上書きします。 |-| `~/.vphone/VMs/` | VM バンドル — VM ごとに 1 ディレクトリ。これがライブラリです。`$VPHONE_LIBRARY_ROOT` で上書きできます。 |-| `~/.vphone/ipsws/`| ダウンロードされた iPhone + cloudOS の IPSW。キャッシュされ、複数の VM で再利用されます。 |-| `~/.vphone/tools/`| `fw prepare` 中に取得された APFS seal-volume アーティファクト(`apfs_sealvolume_<version>`)のキャッシュ。 |-| `~/.vphone/debs/` | `jb`/`exp` の CFW インストールがゲストに配置する `.deb` パッケージのキャッシュ(Sileo、apt など)。 |+cloudOS 26.4(`23E5207q`)との組み合わせで、iPhone17,3 の iOS 26.6.2(`23G90`)と 27.0(`24A435`)がロック画面に到達し、vphoned ping に応答しました。詳細は[互換性の記録](guides/compatibility.md)を参照してください。-優先順位: 項目ごとの上書き `$VPHONE_LIBRARY_ROOT` が `$VPHONE_ROOT` より優先され、`$VPHONE_ROOT` は `~/.vphone` のデフォルトより優先されます。`ipsws/`、`tools/`、`debs/` キャッシュは、常に現在有効なルートの直下に置かれます。+## インストールとビルド-## SIP/AMFI の緩和+配布 `.app` の実行に Homebrew、Python、Xcode や別の実行環境は不要です。ソースからのビルドには、vphoned をコンパイルするための iPhoneOS SDK を含む Xcode が必要です。-**オプション A — SIP を完全に無効化し、boot-arg で AMFI を無効化する(最も緩い)。**--リカバリーモードで(電源ボタン長押し → ターミナル):--```bash-csrutil disable-csrutil allow-research-guests enable-```--その後 macOS で再起動し、AMFI の boot-arg を設定します(有効化には SIP を完全に無効化する必要があります):--```bash-sudo nvram boot-args="amfi_get_out_of_my_way=1 -v" # 後で再起動-```--これが依然として最も手軽な方法であり、VM のそばで何かを走らせ続ける必要がない唯一の方法です: AMFI が緩和されていれば `vphone-vm` は単体で起動します。--**オプション B — SIP を有効なまま(デバッグのみ緩和)にし、このビルドを許可リストに入れる**(それ以外の時間、および許可していないすべてのバイナリに対しては AMFI が有効なまま)。--リカバリーモードで:--```bash-csrutil enable --without debug-csrutil allow-research-guests enable-```--その後 macOS で再起動し、次を実行します:--```bash-make amfi_allow # root が必要。ビルドのたびに再実行してください-make amfi_status # 許可リストと、このホストがそれを持てるかどうかを表示-make amfi_off # 許可リストを削除し、amfid をクリーンに再起動+```sh+git clone --recurse-submodules https://github.com/Lakr233/vphone-cli.git+cd vphone-cli+make build+.build/release/vphone-cli host preflight```-これが実行するのは `vphone-amfi-allow` — 本リポジトリ自身の C で書かれ、`.app` に同梱されています。書き込むのは 2 つだけです:--* 2 つの `vphone-vm` の cdhash を- `/Library/Preferences/com.apple.security.coderequirements.plist` に。これは AMFI が- もともと読むファイルで、穴ではなく AMFI 自身の機能です;-* amfid の**ヒープの 1 バイト**。`_isRunningInternalBuild` フラグを立てて、そのファイルを読ませます。--2 つとも必要なのは、`make boot` が両方を起動するからです: `boot_binary_check` は-`.build/release/vphone-vm` を、起動処理そのものは `.app` の中のものを実行します。-署名の識別子が異なりハッシュも異なるため、片方だけを許可してもフローの半分しかカバーできません。--**ビルドのたびに再実行してください。** 許可は cdhash をキーにしており、署名のたびに cdhash は変わります — 素の `swift build` でも変わります。--許可すべきバイナリは `vphone-vm` です。`vphone-cli` は entitlement を持たず常に起動できるため、必要なのはその cdhash ではありません。--> **何が許可されるのかを正しく理解してください。** これは cdhash をキーにした許可リストです: 指定していないバイナリに対して amfid は通常どおり検証を続けます。`make amfi_off` はそのファイルを削除し amfid を再起動します。->-> 書き込む 1 バイトは amfid の `__TEXT` ではなく**ヒープ**にあり、それがこの方式が成り立つ理由のすべてです。以前の手法はコードを書き換えていました — `vphone-letmein` は `-[AMFIPathValidator_macos validateWithError:]` の `ldrb` を上書きし、LLDB ベースのツールはブレークポイントのために `BRK` を埋め込みます。どちらも dirty で未署名の実行ページを残し、`sysctl vm.cs_system_enforcement` が 1 のホスト — macOS 27.0 (26A428)、arm64e、上記の `csrutil` 設定そのままで実測 — ではカーネルが次のフォルトでそのページを検証し、amfid を kill し、ゲストも巻き添えにします。この sysctl は実行時には読み取り専用なので、「コードにパッチを当てる」方式はどれだけ気をつけても生き残れません。ヒープはコードではないので、強制検証は何も文句を言いません。--## 動作確認済み環境--| ホスト | 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,6 26.6.1 | `17,3_26.6.2_23G90` | `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` |-| Mac16,11 27.0b2 | `17,3_27.0_24A5430a` | `26.4-23E5207q` |-| Mac16,6 26.6.1 | `17,3_27.0_24A435` | `26.4-23E5207q` |--## FAQ--**`zsh: killed ./vphone-vm`** — AMFI/デバッグ制限がバイパスされていません。[SIP/AMFI の緩和](#sipamfi-の緩和) を参照してください(`amfi_get_out_of_my_way=1`(オプション A)、またはこのビルドに対する `make amfi_allow`(オプション B))。直近のビルドより前に実行したのであれば、もう一度実行してください: 許可は cdhash をキーにしており、署名がそれを変えます。なお `vphone-cli` 自体にこれは起こりません: entitlement を持たないため、*それ* が kill されている場合は別の原因があります。--**`Virtualization is not available on this hardware`** — お使いの Mac 自体が VM です。PV=3 ゲスト起動はネストできません。ネストされていない macOS 15+ ホストを使用してください。--**「Press home to continue」で止まる** — VNC で接続し、右クリック(2 本指クリック)してホームボタンをシミュレートします。--**システムアプリがインストールできない** — iOS のセットアップ中に、地域として日本や EU を選ばないでください(VM が満たせない追加の規制チェックが入ります)。例えば United States を選択してください。--**アプリが起動時に `EXC_GUARD` / `GUARD_TYPE_MACH_PORT` でクラッシュする** — `vphone-cli fw patch <name> --variant <v> --force-exc-guard` で再パッチし、再度復元/インストールしてください([#291](https://github.com/Lakr233/vphone-cli/issues/291))。iOS 18 ベースでは常に有効です。--**`.ipa`/`.tipa` をインストールする** — 実行中の VM の Install メニューを使用します(ドラッグ&ドロップまたはファイルピッカー)。--## 自動化--`vphone-cli` はプログラムによる制御のためにホスト制御ソケット(`<bundle>/vphone.sock`)を公開します — スクリーンショット、タッチ、スワイプ、ハードウェアキー、クリップボード — 各アクションは AI 駆動の E2E テスト用にインラインのスクリーンショットを返します。それをラップする MCP サーバーについては [vphone-mcp](https://github.com/pluginslab/vphone-mcp) を参照してください。--## 謝辞--- [wh1te4ever/super-tart-vphone-writeup](https://github.com/wh1te4ever/super-tart-vphone-writeup)+AMFI の許可リストを使う場合、ビルドのたびに `make amfi_allow` を再実行してください。[ドキュメント一覧](README.md)から現在の手順と研究資料に進めます。詳しいガイドは現在英語です。diff --git a/docs/README_ko.md b/docs/README_ko.mdindex 3fd3cafc..52c33f86 100644--- a/docs/README_ko.md+++ b/docs/README_ko.md@@ -1,236 +1,38 @@-<div align="right"><strong>🇰🇷한국어</strong> | <strong><a href="./README_ja.md">🇯🇵日本語</a></strong> | <strong><a href="./README_zh.md">🇨🇳中文</a></strong> | <strong><a href="./README_ru.md">🇷🇺Русский</a></strong> | <strong><a href="./README_pt.md">🇧🇷Português</a></strong> | <strong><a href="../README.md">🇬🇧English</a></strong></div>+<div align="right"><a href="../README.md">English</a> · <a href="README_zh.md">中文</a> · <a href="README_ja.md">日本語</a> · <strong>한국어</strong> · <a href="README_ru.md">Русский</a> · <a href="README_pt.md">Português</a></div># vphone-cli-PCC 리서치 VM 인프라를 사용하여 Apple의 Virtualization.framework로 가상 iPhone을 부팅합니다.+Apple Virtualization.framework와 PCC 연구용 VM 기반으로 가상 iPhone을 부팅합니다.-+-## 사전 요구 사항--**실행에 필요한 것:**--- Apple Silicon-- macOS 15+ (Sequoia)-- [서명되지 않은 바이너리로 private PV=3 권한을 허용하기 위한 SIP/AMFI 완화](#sipamfi-완화)--**그 밖에는 아무것도 필요 없습니다.** Homebrew 패키지도, 인터프리터도, 패키지 환경도,-Xcode도 필요하지 않습니다. vphone-cli가 실행하는 모든 것은 `/usr/bin`·`/bin`·`/usr/sbin`·-`/sbin` 아래의 시스템 바이너리이거나 `.app` 안에 들어 있습니다 — 서명기(`ldid`를 대체),-아카이브 처리(`gtar`, `zstd`, `unzip`), 펌웨어 카탈로그와 IM4P/AEA 처리(`ipsw`), 그리고-CFW 설치기가 게스트에 넣는 다섯 개의 iOS 바이너리까지. 이 다섯 개는 빌드 시점에 크로스-컴파일되어 함께 배포되며, 사용자 머신에서 컴파일하지 않습니다. 이 상태를 지키는 관문이-`make check-aux`입니다.--**소스에서 빌드하려면** Xcode(그 다섯 개 게스트 바이너리를 크로스 컴파일할 iOS SDK가-필요합니다)와 `git-lfs`(`git clone`이 `scripts/resources`의 아카이브를 받는 데 필요)가-추가로 있어야 합니다.--## 설치--```bash-brew install zqxwce/tap/vphone-cli-```--## 빌드--```bash-brew install git-lfs-git clone --recurse-submodules https://github.com/Lakr233/vphone-cli.git--./scripts/build.sh # vphone-cli 빌드 및 서명, 게스트 바이너리 크로스 컴파일, .app 번들 생성--cd .build/vphone-cli.app/Contents/MacOS/-vphone-cli --help-```--`./scripts/setup_tools.sh`는 선택 사항이며 딱 하나, `insert_dylib`만 빌드합니다. Mach-O-테스트가 Swift dylib 주입기를 바이트 단위로 대조하기 위한 독립 참조물이며, 배포물은 이를-실행하지 않습니다.+공개 펌웨어 흐름은 **JB 한 가지**입니다. 필요한 시스템 패치와 호스트 제어용 vphoned를 설치합니다. 게스트 사용자 환경은 그대로 두며 패키지 관리자, SSH, VNC 또는 첫 부팅 bootstrap은 설치하지 않습니다.## 빠른 시작-하나의 명령으로 VM을 처음부터 끝까지 생성합니다 (다운로드 → 패치 → DFU 복원 → CFW 설치 → 첫 부팅):+Apple Silicon Mac, macOS 15 이상, 그리고 PV=3 연구용 VM과 `vphone-vm` 권한을 허용하는 [호스트 설정](guides/host-setup.md)이 필요합니다.-```bash-vphone-cli vm create myphone -V jb # -V / --variant+```sh+vphone-cli vm create myphone \+ --iphone-source /path/to/iPhone17,3_Restore.ipsw \+ --cloudos-source /path/to/cloudOS.ipswvphone-cli vm launch myphone```-## 명령어--`vphone-cli vm create`는 전체 파이프라인을 실행합니다; 아래 개별 단계들을 사용하면 수동으로 진행하거나 한 단계만 다시 실행할 수 있습니다.--### 관리--```bash-vphone-cli vm list # VM 목록 표시 (스크립팅용 --json)-vphone-cli vm info myphone # VM 하나 표시-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 fast by default (--max = xz -9); --out 이 디렉토리면 <vm>.tzst/.txz 자동 명명; restore 디렉토리 + 스테이징 파일 건너뜀-vphone-cli vm import myphone.tzst --name restored-vphone-cli vm rename myphone iphone16-vphone-cli vm delete iphone16-```--### VM 수동 빌드 (`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. 첫 부팅-```--최신 iOS로 업데이트하려면 `fw prepare`를 IPSW로 지정하세요: `--iphone-source /path/to.ipsw --cloudos-source /path/to.ipsw`.--4단계와 5단계는 `vphone-cli` 자체 프로세스에서 실행됩니다. `restore`는 내장된-libirecovery와 idevicerestore를 직접 구동합니다 — 외부 복원 도구도, 첫 실행 전-준비 단계도 없습니다. `--offline`을 붙이면 Apple에 새 ticket을 요청하는 대신 VM-옆에 이미 저장된 `.shsh`로 복원합니다.--## 펌웨어 변형--보안 우회 수준이 점점 강해지는 5가지 패치 변형이 있습니다 — 하나를 `--variant`에 전달하세요:--| 변형 | 부트 체인 | CFW | 참고 |-| ------------ | ----------- | --------- | --------------------------------------------------------------- |-| `less` | 4 patches | 2 phases | Patchless — iOS 완화 기능을 활성 상태로 유지 |-| `regular` | 42 patches | 10 phases | AMFI/SSV/Img4/TXM 우회 |-| `dev` | 53 patches | 12 phases | + TXM 권한/디버그 우회 |-| `jb` | 113 patches | 14 phases | + 전체 탈옥 (Sileo, TrollStore가 첫 부팅 시 자동 설치) |-| `exp` | 141 patches | 18 phases | JB 상위 집합 + VM 탐지 방지 연구 패치 |--컴포넌트별 상세 분류는 [`research/0_binary_patch_comparison.md`](../research/0_binary_patch_comparison.md)를 참조하세요.--## 실행 및 연결--- **SSH (탈옥):** `ssh -p 22222 mobile@<vm-ip>` (비밀번호 `alpine`)-- **SSH (regular/dev):** `ssh -p 22222 root@<vm-ip>`-- **VNC:** `vnc://<vm-ip>:5901`--## 위치--vphone-cli가 생성하는 모든 것은 `~/.vphone/` 아래에 있습니다 — 서명된 번들이 이식 가능하도록 저장소와 `.app` 외부에 보관됩니다. `$VPHONE_ROOT`로 전체 트리를 리디렉션할 수 있습니다:+`vm create`는 준비, JB 패치, DFU 복원, CFW 설치를 수행하고 첫 부팅에서 vphoned에 실제로 ping합니다. **검증용 부팅은 성공 후 종료됩니다.** 계속 사용하려면 `vm launch`를 실행하세요. 복원에는 네트워크가, CFW 설치에는 관리자 인증이 필요합니다.-| 경로 | 내용 |-| ----------------- | ------------------------------------------------------------------------------------------ |-| `~/.vphone/` | 사용자별 데이터 루트 — `$VPHONE_ROOT`로 전체 위치를 재정의합니다. |-| `~/.vphone/VMs/` | VM 번들 — VM마다 하나의 디렉터리. 라이브러리이며, `$VPHONE_LIBRARY_ROOT`로 재정의할 수 있습니다. |-| `~/.vphone/ipsws/`| 다운로드된 iPhone + cloudOS IPSW, 캐시되어 여러 VM에서 재사용됩니다. |-| `~/.vphone/tools/`| `fw prepare` 중에 가져온 APFS seal-volume 아티팩트(`apfs_sealvolume_<version>`) 캐시. |-| `~/.vphone/debs/` | `jb`/`exp` CFW 설치가 게스트에 넣는 `.deb` 패키지 캐시 (Sileo, apt 등). |+cloudOS 26.4(`23E5207q`)와 함께 iPhone17,3 iOS 26.6.2(`23G90`), 27.0(`24A435`)이 잠금 화면에 도달하고 vphoned ping에 응답했습니다. 범위는 [호환성 기록](guides/compatibility.md)을 참고하세요.-우선순위: 항목별 재정의 `$VPHONE_LIBRARY_ROOT`가 `$VPHONE_ROOT`보다 우선하고, `$VPHONE_ROOT`는 `~/.vphone` 기본값보다 우선합니다. `ipsws/`, `tools/`, `debs/` 캐시는 항상 현재 활성 루트 바로 아래에 위치합니다.+## 설치와 빌드-## SIP/AMFI 완화+배포된 `.app` 실행에는 Homebrew, Python, Xcode나 별도의 런타임 환경이 필요하지 않습니다. 소스 빌드에는 vphoned용 iPhoneOS SDK가 포함된 Xcode가 필요합니다.-**방법 A — SIP를 완전히 비활성화한 후, boot-arg로 AMFI를 비활성화 (가장 관대).**--복구 모드에서 (전원 버튼 길게 누르기 → 터미널):--```bash-csrutil disable-csrutil allow-research-guests enable-```--그런 다음 macOS로 재부팅하고 AMFI boot-arg를 설정합니다 (적용되려면 SIP가 완전히 꺼져 있어야 합니다):--```bash-sudo nvram boot-args="amfi_get_out_of_my_way=1 -v" # 이후 재부팅-```--이 방법이 여전히 가장 간단하며, VM 옆에서 무언가를 계속 띄워 둘 필요가 없는 유일한 방법입니다: AMFI가 완화되어 있으면 `vphone-vm`이 혼자서 실행됩니다.--**방법 B — SIP 유지 (디버그만 완화), 이번 빌드를 허용 목록에 넣기** (그 외의 시간에는, 그리고 허용하지 않은 모든 바이너리에 대해서는 AMFI가 활성 상태 유지).--복구 모드에서:--```bash-csrutil enable --without debug-csrutil allow-research-guests enable-```--그런 다음 macOS로 재부팅하고 실행합니다:--```bash-make amfi_allow # root 필요. 빌드할 때마다 다시 실행하세요-make amfi_status # 허용 목록과, 이 호스트가 그것을 가질 수 있는지 표시-make amfi_off # 허용 목록을 제거하고 amfid를 깨끗하게 재시작+```sh+git clone --recurse-submodules https://github.com/Lakr233/vphone-cli.git+cd vphone-cli+make build+.build/release/vphone-cli host preflight```-이것이 실행하는 것은 `vphone-amfi-allow` — 이 저장소 자체의 C 코드로 만들어져 `.app` 안에 함께 배포됩니다. 쓰는 것은 두 가지뿐입니다:--* 두 개의 `vphone-vm` cdhash를- `/Library/Preferences/com.apple.security.coderequirements.plist`에. 이것은 AMFI가- 원래부터 읽는 파일이며, 구멍이 아니라 AMFI 자신의 기능입니다;-* amfid **힙의 1바이트**. `_isRunningInternalBuild` 플래그를 뒤집어 그 파일을 읽게 만듭니다.--둘 다 필요한 이유는 `make boot`이 둘 다 실행하기 때문입니다: `boot_binary_check`는-`.build/release/vphone-vm`을, 부팅 자체는 `.app` 안의 것을 실행합니다. 서로 다른 식별자로-서명되어 해시도 다르므로, 한쪽만 허용하면 흐름의 절반만 덮게 됩니다.--**빌드할 때마다 다시 실행하세요.** 허용은 cdhash를 기준으로 하며, 서명할 때마다 cdhash가 바뀝니다 — 맨 `swift build`로도 바뀝니다.--허용해야 할 바이너리는 `vphone-vm`입니다. `vphone-cli`는 entitlement가 없어 항상 실행되므로 필요한 것은 그쪽 cdhash가 아닙니다.--> **무엇을 허용하는지 정확히 알아 두세요.** 이것은 cdhash를 기준으로 하는 허용 목록입니다: 지정하지 않은 바이너리에 대해서는 amfid가 계속 검증을 강제합니다. `make amfi_off`가 그 파일을 지우고 amfid를 재시작합니다.->-> 그 1바이트는 amfid의 `__TEXT`가 아니라 **힙**에 쓰이며, 이것이 이 방식이 통하는 이유의 전부입니다. 이전 방식들은 코드를 고쳤습니다 — `vphone-letmein`은 `-[AMFIPathValidator_macos validateWithError:]`의 `ldrb`를 덮어썼고, LLDB 기반 도구는 중단점을 위해 `BRK`를 심습니다. 둘 다 dirty하고 서명되지 않은 실행 페이지를 남기며, `sysctl vm.cs_system_enforcement`가 1인 호스트 — macOS 27.0 (26A428), arm64e, 위의 `csrutil` 설정 그대로에서 실측 — 에서는 커널이 다음 폴트에 그 페이지를 검증하고 amfid를 종료시키며 게스트까지 함께 죽입니다. 이 sysctl은 런타임에 읽기 전용이므로 "코드에 패치" 방식은 아무리 조심해도 살아남을 수 없습니다. 힙은 코드가 아니므로 강제 검증이 트집 잡을 것이 없습니다.--## 테스트 환경--| 호스트 | 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,6 26.6.1 | `17,3_26.6.2_23G90` | `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` |-| Mac16,11 27.0b2 | `17,3_27.0_24A5430a` | `26.4-23E5207q` |-| Mac16,6 26.6.1 | `17,3_27.0_24A435` | `26.4-23E5207q` |--## FAQ--**`zsh: killed ./vphone-vm`** — AMFI/디버그 제한이 우회되지 않았습니다; [SIP/AMFI 완화](#sipamfi-완화)를 참조하세요 (`amfi_get_out_of_my_way=1` (방법 A), 또는 이번 빌드에 대한 `make amfi_allow` (방법 B)). 마지막 빌드 *전에* 실행했다면 다시 실행하세요: 허용은 cdhash를 기준으로 하고, 서명이 그것을 바꿉니다. 참고로 `vphone-cli` 자체에는 이런 일이 생길 수 없습니다: entitlement가 없으므로 *그것*이 종료되고 있다면 다른 문제가 있는 것입니다.--**`Virtualization is not available on this hardware`** — Mac 자체가 VM입니다; PV=3 게스트 부팅은 중첩할 수 없습니다. 중첩되지 않은 macOS 15+ 호스트를 사용하세요.--**"Press home to continue"에서 멈춤** — VNC로 접속하여 우클릭(두 손가락 클릭)으로 홈 버튼을 시뮬레이션하세요.--**시스템 앱이 설치되지 않음** — iOS 초기 설정 시 지역으로 일본이나 EU를 선택하지 마세요 (VM이 충족할 수 없는 추가 규제 검사가 있습니다); 예를 들어 United States를 선택하세요.--**앱이 실행 시 `EXC_GUARD` / `GUARD_TYPE_MACH_PORT`로 충돌** — `vphone-cli fw patch <name> --variant <v> --force-exc-guard`로 다시 패치한 다음, 다시 복원/설치하세요 ([#291](https://github.com/Lakr233/vphone-cli/issues/291)). iOS 18 베이스에서는 항상 켜져 있습니다.--**`.ipa`/`.tipa` 설치** — 실행 중인 VM의 Install 메뉴를 사용하세요 (드래그 앤 드롭 또는 파일 선택기).--## 자동화--`vphone-cli`는 프로그래밍 방식 제어를 위한 호스트 제어 소켓(`<bundle>/vphone.sock`)을 노출합니다 — 스크린샷, 터치, 스와이프, 하드웨어 키, 클립보드 — 각 동작은 AI 주도 E2E 테스트를 위해 인라인 스크린샷을 반환합니다. 이를 감싸는 MCP 서버는 [vphone-mcp](https://github.com/pluginslab/vphone-mcp)를 참조하세요.--## 감사의 말--- [wh1te4ever/super-tart-vphone-writeup](https://github.com/wh1te4ever/super-tart-vphone-writeup)+AMFI 허용 목록을 사용하는 호스트에서는 빌드할 때마다 `make amfi_allow`를 다시 실행하세요. 현재 가이드와 연구 자료는 [문서 목차](README.md)에 모았습니다. 상세 가이드는 현재 영어로 제공됩니다.diff --git a/docs/README_pt.md b/docs/README_pt.mdindex 7837bf58..d0835738 100644--- a/docs/README_pt.md+++ b/docs/README_pt.md@@ -1,244 +1,38 @@-<div align="right"><strong><a href="./README_ko.md">🇰🇷한국어</a></strong> | <strong><a href="./README_ja.md">🇯🇵日本語</a></strong> | <strong><a href="./README_zh.md">🇨🇳中文</a></strong> | <strong><a href="./README_ru.md">🇷🇺Русский</a></strong> | <strong><a href="../README.md">🇬🇧English</a></strong> | <strong>🇧🇷Português</strong></div>+<div align="right"><a href="../README.md">English</a> · <a href="README_zh.md">中文</a> · <a href="README_ja.md">日本語</a> · <a href="README_ko.md">한국어</a> · <a href="README_ru.md">Русский</a> · <strong>Português</strong></div># vphone-cli-Inicie um iPhone virtual usando o Virtualization.framework da Apple com a infraestrutura de VMs de pesquisa PCC.+Inicializa um iPhone virtual com o Virtualization.framework da Apple e a infraestrutura de pesquisa PCC VM.-+-## Pré-requisitos+O fluxo público de firmware agora oferece **apenas JB**. Ele aplica os patches de sistema necessários e instala o vphoned para controle pelo host. O ambiente do usuário no guest permanece vazio: não instala gerenciador de pacotes, SSH, VNC nem bootstrap no primeiro boot.-**Para executar:**+## Início rápido-- Apple Silicon-- macOS 15+ (Sequoia)-- [Relaxamento de SIP/AMFI para permitir entitlements privados PV=3 com binário não assinado](#relaxamento-sipamfi)+É necessário um Mac com Apple Silicon e macOS 15 ou posterior. O host precisa permitir VMs de pesquisa PV=3 e os direitos privados do `vphone-vm`; veja a [configuração do host](guides/host-setup.md).-**E nada mais.** Nenhum pacote do Homebrew, nenhum interpretador, nenhum ambiente de-pacotes, nenhum Xcode. Tudo o que o vphone-cli executa é um binário do sistema em-`/usr/bin`, `/bin`, `/usr/sbin` ou `/sbin`, ou está dentro do próprio `.app` — o assinador-(substituiu o `ldid`), a leitura de arquivos compactados (`gtar`, `zstd`, `unzip`), o-catálogo de firmwares e o tratamento de IM4P/AEA (`ipsw`), e os cinco binários iOS que os-instaladores de CFW colocam no guest, que são compilados cruzadamente no build e-distribuídos prontos, não compilados na sua máquina. `make check-aux` é o portão que mantém-isso assim.+```sh+vphone-cli vm create myphone \+ --iphone-source /path/to/iPhone17,3_Restore.ipsw \+ --cloudos-source /path/to/cloudOS.ipsw-**Para compilar a partir do código-fonte**, acrescente o Xcode (o iOS SDK dele é contra o-que esses cinco binários são compilados) e o `git-lfs` (o `git clone` precisa dele para os-arquivos em `scripts/resources`).--## Instalação--```bash-brew install zqxwce/tap/vphone-cli-```--## Compilação--```bash-brew install git-lfs-git clone --recurse-submodules https://github.com/Lakr233/vphone-cli.git--./scripts/build.sh # compila + assina vphone-cli, compila os binários guest, empacota o .app--cd .build/vphone-cli.app/Contents/MacOS/-vphone-cli --help-```--`./scripts/setup_tools.sh` é opcional e compila uma coisa só: `insert_dylib`, a referência-independente contra a qual um teste Mach-O compara o injetor de dylib em Swift, byte a byte.-Nada do que é distribuído o executa.--## Início Rápido--Um único comando cria a VM do início ao fim (download → patch → restore DFU → instalação CFW → primeiro boot):--```bash-vphone-cli vm create meuiphone -V jb # -V / --variant--vphone-cli vm launch meuiphone-```--## Comandos--`vphone-cli vm create` executa todo o pipeline; os passos individuais abaixo permitem executar manualmente ou repetir uma etapa.--### Gerenciamento--```bash-vphone-cli vm list # lista VMs (--json para scripts)-vphone-cli vm info meuiphone # mostra uma VM-vphone-cli vm new meuiphone # cria um bundle vazio (opções cpu/mem/disk)-vphone-cli vm config meuiphone --cpu 8 --memory 8192-vphone-cli vm clone meuiphone meuiphone-2 # clone APFS rápido, nova identidade de dispositivo-vphone-cli vm export meuiphone --out meuiphone.tzst # zstd rápido por padrão (--max = xz -9); --out pode ser diretório (auto-nomeia <vm>.tzst/.txz); ignora diretório restore + arquivos staging-vphone-cli vm import meuiphone.tzst --name restaurado-vphone-cli vm rename meuiphone iphone16-vphone-cli vm delete iphone16+vphone-cli vm launch myphone```-### Construir uma VM manualmente (o que `vm create` automatiza)--```bash-vphone-cli vm new meuiphone # 1. bundle vazio-vphone-cli fw prepare meuiphone --iphone-version 26.1 # 2. baixa + mescla IPSWs-vphone-cli fw patch meuiphone --variant jb # 3. aplica patches na cadeia de boot--vphone-cli vm launch meuiphone --dfu & # 4. inicia em modo DFU (background)-vphone-cli restore meuiphone --get-shsh # obtém SHSH-vphone-cli restore meuiphone # restore DFU-vphone-cli vm stop meuiphone # para o boot DFU--vphone-cli cfw install meuiphone --variant jb # 5. instala CFW (host-mount; pede sudo)-vphone-cli vm launch meuiphone # 6. primeiro boot-```--Atualize para um iOS mais novo apontando `fw prepare` para um IPSW: `--iphone-source /caminho/para.ipsw --cloudos-source /caminho/para.ipsw`.--Os passos 4 e 5 rodam no próprio processo do `vphone-cli`. O `restore` controla-diretamente as cópias embutidas de libirecovery e idevicerestore — sem ferramenta-externa de restauração e sem nenhum passo de preparação antes da primeira-execução. Com `--offline`, a restauração usa um `.shsh` já salvo ao lado da VM em-vez de pedir um novo à Apple.--## Variantes de Firmware--Cinco variantes de patch com bypass de segurança crescente — passe uma para `--variant`:--| Variante | Boot Chain | CFW | Notas |-| ------------ | ----------- | --------- | ------------------------------------------------------------------ |-| `less` | 4 patches | 2 fases | Patchless — mantém mitigações do iOS habilitadas |-| `regular` | 42 patches | 10 fases | Bypass de AMFI/SSV/Img4/TXM |-| `dev` | 53 patches | 12 fases | + bypass de entitlements/debug do TXM |-| `jb` | 113 patches | 14 fases | + jailbreak completo (Sileo, TrollStore auto-instalados no boot) |-| `exp` | 141 patches | 18 fases | Superset do JB + patches de pesquisa anti-detecção-de-VM |--Veja [`research/0_binary_patch_comparison.md`](../research/0_binary_patch_comparison.md) para o detalhamento por componente.--## Execução & Conexão--- **SSH (jailbreak):** `ssh -p 22222 mobile@<vm-ip>` (senha `alpine`)-- **SSH (regular/dev):** `ssh -p 22222 root@<vm-ip>`-- **VNC:** `vnc://<vm-ip>:5901`--## Localizações--Tudo que o vphone-cli cria fica em `~/.vphone/` — fora do repo e do `.app` para que o bundle assinado continue portátil. Redirecione toda a árvore com `$VPHONE_ROOT`:--| Caminho | Conteúdo |-| ----------------- | --------------------------------------------------------------------------------------------- |-| `~/.vphone/` | Raiz de dados por usuário — substitua toda a localização com `$VPHONE_ROOT`. |-| `~/.vphone/VMs/` | Bundles de VM — um diretório por VM. Esta é a biblioteca; substitua com `$VPHONE_LIBRARY_ROOT`. |-| `~/.vphone/ipsws/`| IPSWs de iPhone + cloudOS baixados, em cache e reutilizados entre VMs. |-| `~/.vphone/tools/`| Artefatos de seal-volume APFS em cache (`apfs_sealvolume_<versão>`) obtidos durante `fw prepare`. |-| `~/.vphone/debs/` | Pacotes `.deb` em cache que o CFW `jb`/`exp` instala no guest (Sileo, apt, …). |+`vm create` prepara e aplica os patches, restaura via DFU, instala o CFW e confirma um ping real do vphoned no primeiro boot. **A VM usada nessa verificação é encerrada após o sucesso.** Execute `vm launch` para continuar usando-a. A restauração precisa de rede; a instalação do CFW pede autenticação de administrador.-Precedência: a substituição por item `$VPHONE_LIBRARY_ROOT` tem prioridade sobre `$VPHONE_ROOT`, que tem prioridade sobre o padrão `~/.vphone`. Os caches `ipsws/`, `tools/` e `debs/` sempre ficam diretamente sob qualquer raiz ativa.+Com cloudOS 26.4 (`23E5207q`), iPhone17,3 iOS 26.6.2 (`23G90`) e 27.0 (`24A435`) chegaram à tela bloqueada e responderam ao ping do vphoned. Veja o alcance desses testes na [compatibilidade](guides/compatibility.md).-## Relaxamento SIP/AMFI+## Instalação e compilação-**Opção A — desabilitar SIP completamente, depois desabilitar AMFI via boot-arg (mais permissivo).**+O `.app` distribuído roda sem Homebrew, Python, Xcode ou outro ambiente de execução. A compilação a partir do código-fonte requer Xcode com o SDK do iPhoneOS para compilar o vphoned.-No Recovery (pressione e segure power → Terminal):--```bash-csrutil disable-csrutil allow-research-guests enable-```--Depois reinicie no macOS e configure o boot-arg do AMFI (requer SIP completamente desligado para funcionar):--```bash-sudo nvram boot-args="amfi_get_out_of_my_way=1 -v" # reinicie após-```--Esse ainda é o caminho mais simples, e o único que não exige nada rodando ao lado da VM: com o AMFI relaxado, o `vphone-vm` inicia sozinho.--**Opção B — manter SIP ligado (relaxado apenas para debug) e colocar esta build na allowlist** (o AMFI continua habilitado no resto do tempo e para todo binário que você não liberar).--No Recovery:--```bash-csrutil enable --without debug-csrutil allow-research-guests enable-```--Depois reinicie no macOS e rode:--```bash-make amfi_allow # pede root; rode de novo depois de cada build-make amfi_status # mostra a allowlist e se este host consegue carregá-la-make amfi_off # remove a allowlist e reinicia o amfid limpo+```sh+git clone --recurse-submodules https://github.com/Lakr233/vphone-cli.git+cd vphone-cli+make build+.build/release/vphone-cli host preflight```-Isso executa o `vphone-amfi-allow`, compilado do C deste próprio repositório e distribuído dentro do `.app`. Ele escreve duas coisas:--* os cdhashes das **duas** cópias do `vphone-vm` em- `/Library/Preferences/com.apple.security.coderequirements.plist`, um arquivo que o AMFI- já lê — é um recurso que ele traz, não um buraco;-* **um byte do heap** do amfid, para virar a flag `_isRunningInternalBuild` que faz ele- consultar esse arquivo.--As duas, porque o `make boot` inicia as duas: o `boot_binary_check` roda-`.build/release/vphone-vm` e o boot em si roda a que está dentro do `.app`. Elas são-assinadas sob identificadores diferentes e têm hashes diferentes, então liberar uma cobre-exatamente metade do fluxo.--**Rode de novo depois de cada build.** A allowlist é por cdhash, e qualquer assinatura muda o cdhash — inclusive um `swift build` puro.--O binário a liberar é o `vphone-vm`. O `vphone-cli` não carrega entitlements e sempre inicia, então não é o cdhash dele que você quer.--> **Seja claro sobre o que isso libera.** É uma allowlist por cdhash: o amfid continua validando todo binário que você não listou. `make amfi_off` apaga o arquivo e reinicia o amfid.->-> Esse um byte fica no **heap** do amfid, não no `__TEXT` dele, e é isso que faz a coisa funcionar. As tentativas anteriores alteravam código — o `vphone-letmein` sobrescrevia o `ldrb` em `-[AMFIPathValidator_macos validateWithError:]`, e ferramentas baseadas em LLDB plantam um `BRK` para o breakpoint. As duas deixam uma página executável suja e não assinada, e num host onde `sysctl vm.cs_system_enforcement` vale 1 — medido no macOS 27.0 (26A428), arm64e, exatamente com as configurações de `csrutil` acima — o kernel valida essa página na próxima falta, mata o amfid e leva o guest junto. O sysctl é somente leitura em runtime, então "corrigir o código" não sobrevive por mais cuidado que se tenha. Heap não é código, e o enforcement não tem do que reclamar.--## Ambientes Testados--| 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,6 26.6.1 | `17,3_26.6.2_23G90` | `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` |-| Mac16,11 27.0b2 | `17,3_27.0_24A5430a` | `26.4-23E5207q` |-| Mac16,6 26.6.1 | `17,3_27.0_24A435` | `26.4-23E5207q` |--## FAQ--**`zsh: killed ./vphone-vm`** — Restrições de AMFI/debug não foram desativadas; veja [Relaxamento SIP/AMFI](#relaxamento-sipamfi) (`amfi_get_out_of_my_way=1`, a Opção A, ou `make amfi_allow` para esta build, a Opção B). Se você rodou *antes* da última build, rode de novo: a allowlist é por cdhash, e assinar muda o cdhash. Note que isso não pode acontecer com o próprio `vphone-cli`: ele não carrega entitlements, então se *ele* está sendo morto, algo mais está errado.--**`Virtualization is not available on this hardware`** — Seu Mac é uma VM; boot de guest PV=3 não pode ser aninhado. Use um host macOS 15+ não-virtualizado.--**Travado em "Press home to continue"** — Conecte via VNC e clique com botão direito (clique com dois dedos) para simular o botão home.--**Apps do sistema não instalam** — Durante a configuração do iOS, não escolha Japão ou UE como região (verificações regulatórias extras que a VM não consegue satisfazer); escolha por exemplo Estados Unidos.--**App trava ao iniciar com `EXC_GUARD` / `GUARD_TYPE_MACH_PORT`** — Reaplique patches com `vphone-cli fw patch <nome> --variant <v> --force-exc-guard`, depois re-restore/install ([#291](https://github.com/Lakr233/vphone-cli/issues/291)). Sempre ativo para bases iOS 18.--**Instalar um `.ipa`/`.tipa`** — Use o menu Install da VM em execução (arrastar-soltar ou seletor de arquivos).--**Preciso de Homebrew, ou de Xcode, para usar isto?** — Não. O `vphone-cli` roda num macOS 15+ limpo: tudo o que ele chama está em `/usr/bin`, `/bin`, `/usr/sbin` ou `/sbin`, e todo o resto está dentro do `.app`. `make check-aux` é o portão que mantém isso. Compilar do código-fonte é outra história: aí são necessários o Xcode (o iOS SDK contra o qual os binários guest são compilados) e o `git-lfs` (para `scripts/resources`).--**`cfw install` trava re-assinando um binário de sistema (ex: `Campo`), memória crescendo indefinidamente** — Era um bug no `ldid-procursus` até `2.1.5-procursus7`: `bytes(uint64_t)` chamava `__builtin_clzll(0)` sem verificação de zero, que é comportamento indefinido, e naquele build resolvia para um length `0` que causava underflow num contador de loop unsigned — o `ldid` ficava em loop escrevendo um byte por vez num buffer crescente em vez de terminar. Qualquer plist de entitlements com um valor inteiro exatamente `0` acionava isso, e alguns binários de sistema reais da Apple têm um. Não pode mais acontecer: a assinatura é `vphone-cli sign`, no próprio processo, e o `ldid` não é instalado, invocado nem distribuído.--## Automação--`vphone-cli` expõe um socket de controle no host (`<bundle>/vphone.sock`) para controle programático — screenshots, touch, swipes, teclas de hardware, clipboard — cada ação retornando um screenshot inline para testes E2E orientados por IA. Veja [vphone-mcp](https://github.com/pluginslab/vphone-mcp) para um servidor MCP que o encapsula.--## Agradecimentos--- [wh1te4ever/super-tart-vphone-writeup](https://github.com/wh1te4ever/super-tart-vphone-writeup)+Se o host usar a lista de permissões AMFI, execute `make amfi_allow` novamente após cada compilação. O [índice da documentação](README.md) reúne os guias atuais e as notas de pesquisa. Os guias detalhados estão em inglês no momento.diff --git a/docs/README_ru.md b/docs/README_ru.mdindex 3c790dd6..94815f41 100644--- a/docs/README_ru.md+++ b/docs/README_ru.md@@ -1,241 +1,38 @@-<div align="right"><strong><a href="./README_ko.md">🇰🇷한국어</a></strong> | <strong><a href="./README_ja.md">🇯🇵日本語</a></strong> | <strong><a href="./README_zh.md">🇨🇳中文</a></strong> | <strong>🇷🇺Русский</strong> | <strong><a href="./README_pt.md">🇧🇷Português</a></strong> | <strong><a href="../README.md">🇬🇧English</a></strong></div>+<div align="right"><a href="../README.md">English</a> · <a href="README_zh.md">中文</a> · <a href="README_ja.md">日本語</a> · <a href="README_ko.md">한국어</a> · <strong>Русский</strong> · <a href="README_pt.md">Português</a></div># vphone-cli-Запуск виртуального iPhone через Apple Virtualization.framework с использованием инфраструктуры исследовательской ВМ PCC.+Запускает виртуальный iPhone через Apple Virtualization.framework и исследовательскую инфраструктуру PCC VM.-+-## Предварительные требования--**Чтобы запускать:**--- Apple Silicon-- macOS 15+ (Sequoia)-- Ослабление SIP/AMFI для разрешения приватных прав PV=3 с неподписанным бинарником--**И больше ничего.** Ни пакетов Homebrew, ни интерпретатора, ни окружения пакетного-менеджера, ни Xcode. Всё, что запускает vphone-cli, — это либо системный бинарник из-`/usr/bin`, `/bin`, `/usr/sbin` или `/sbin`, либо содержимое самого `.app`: подписывальщик-(заменил `ldid`), работа с архивами (`gtar`, `zstd`, `unzip`), каталог прошивок и обработка-IM4P/AEA (`ipsw`), а также пять iOS-бинарников, которые установщики CFW кладут в гостя —-они кросс-компилируются при сборке и поставляются готовыми, а не собираются на вашей машине.-Следит за этим `make check-aux`.--**Чтобы собрать из исходников**, дополнительно нужны Xcode (его iOS SDK — то, под что-кросс-компилируются те пять гостевых бинарников) и `git-lfs` (`git clone` берёт им архивы-из `scripts/resources`).--## Установка--```-brew install zqxwce/tap/vphone-cli-```--## Сборка--```-brew install git-lfs-git clone --recurse-submodules https://github.com/Lakr233/vphone-cli.git--./scripts/build.sh # сборка + подпись vphone-cli, кросс-компиляция гостевых бинарников, сборка .app--cd .build/vphone-cli.app/Contents/MacOS/-vphone-cli --help-```--`./scripts/setup_tools.sh` необязателен и собирает ровно одну вещь — `insert_dylib`,-независимый эталон, с которым Mach-O-тест побайтово сверяет Swift-инжектор dylib. Ничего-из поставляемого его не запускает.+Публичный режим прошивки теперь **только JB**. Он применяет необходимые системные патчи и устанавливает vphoned для управления с хоста. Пользовательское окружение гостя остаётся пустым: менеджер пакетов, SSH, VNC и bootstrap при первом запуске не устанавливаются.## Быстрый старт-Одна команда создаёт ВМ от начала до конца (загрузка → патчинг → DFU-восстановление → установка CFW → первая загрузка):+Нужен Mac с Apple Silicon и macOS 15 или новее. Хост должен разрешать исследовательские PV=3 VM и приватные разрешения `vphone-vm`; см. [настройку хоста](guides/host-setup.md).-```-vphone-cli vm create myphone -V jb # -V / --variant+```sh+vphone-cli vm create myphone \+ --iphone-source /path/to/iPhone17,3_Restore.ipsw \+ --cloudos-source /path/to/cloudOS.ipswvphone-cli vm launch myphone```-## Команды--`vphone-cli vm create` выполняет весь конвейер; отдельные шаги ниже позволяют запускать его вручную или повторять отдельные стадии.--### Управление--```-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 может быть директорией (автоимена <vm>.tzst/.txz); пропускает restore-директорию + 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. пустой бандл-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 (host-mount; запросит sudo)-vphone-cli vm launch myphone # 6. первая загрузка-```--Обновление до более новой iOS: укажите `fw prepare` на IPSW: `--iphone-source /path/to.ipsw --cloudos-source /path/to.ipsw`.--Шаги 4 и 5 выполняются в собственном процессе `vphone-cli`. `restore` напрямую-управляет встроенными libirecovery и idevicerestore — ни внешней утилиты-восстановления, ни подготовительного шага перед первым запуском. Флаг `--offline`-восстанавливает из уже сохранённого рядом с ВМ `.shsh` вместо запроса нового у Apple.--## Варианты прошивки--Пять вариантов патчей с нарастающим обходом безопасности — передайте один в `--variant`:--| Вариант | Цепочка загрузки | CFW | Примечания |-|---|---|---|---|-| `less` | 4 патча | 2 фазы | Без патчей — сохраняет включённые митигации iOS |-| `regular` | 42 патча | 10 фаз | Обход AMFI/SSV/Img4/TXM |-| `dev` | 53 патча | 12 фаз | + обход TXM entitlement/debug |-| `jb` | 113 патчей | 14 фаз | + полный jailbreak (Sileo, TrollStore автоустанавливаются при первой загрузке) |-| `exp` | 141 патч | 18 фаз | Надмножество JB + исследовательские патчи anti-VM-detection |--См. [`research/0_binary_patch_comparison.md`](https://./research/0_binary_patch_comparison.md) для разбивки по компонентам.--## Запуск и подключение--- **SSH (jailbreak):** `ssh -p 22222 mobile@<vm-ip>` (пароль `alpine`)-- **SSH (regular/dev):** `ssh -p 22222 root@<vm-ip>`-- **VNC:** `vnc://<vm-ip>:5901`--## Расположения--Всё, что создаёт vphone-cli, находится в `~/.vphone/` — вне репозитория и `.app`, чтобы подписанный бандл оставался портативным. Перенаправьте всё дерево через `$VPHONE_ROOT`:--| Путь ↕▾ | Содержимое ↕▾ |-|---|---|-| −`~/.vphone/` | Корень пользовательских данных — переопределите всё расположение через `$VPHONE_ROOT`. |-| −`~/.vphone/VMs/` | Бандлы ВМ — одна директория на ВМ. Это библиотека; переопределяется через `$VPHONE_LIBRARY_ROOT`. |-| −`~/.vphone/ipsws/` | Загруженные IPSW iPhone + cloudOS, кэшируются и переиспользуются между ВМ. |-| −`~/.vphone/tools/` | Кэшированные артефакты APFS seal-volume (`apfs_sealvolume_<version>`), получаемые при `fw prepare`. |-| −`~/.vphone/debs/` | Кэшированные `.deb`-пакеты, которые установка CFW `jb`/`exp` кладёт в гостя (Sileo, apt, …). |--Приоритет: переопределение по элементу `$VPHONE_LIBRARY_ROOT` имеет больший вес, чем `$VPHONE_ROOT`, который имеет больший вес, чем значение по умолчанию `~/.vphone`. Кэши `ipsws/`, `tools/` и `debs/` всегда располагаются непосредственно под активным корнем.--## Ослабление SIP/AMFI--**Вариант A — полностью отключить SIP, затем отключить AMFI через boot-arg (наиболее разрешительно).**--В Recovery (долгое нажатие питания → Terminal):--```-csrutil disable-csrutil allow-research-guests enable-```--Затем перезагрузитесь в macOS и установите boot-arg AMFI (требует полностью отключённого SIP, чтобы вступить в силу):+`vm create` подготавливает и патчит прошивку, выполняет DFU-восстановление, устанавливает CFW и проверяет настоящий ping к vphoned при первом запуске. **После успешной проверки VM останавливается.** Для дальнейшей работы выполните `vm launch`. Восстановлению нужен доступ к сети, установке CFW — права администратора.-```-sudo nvram boot-args="amfi_get_out_of_my_way=1 -v" # перезагрузка после-```--Это по-прежнему самый простой путь и единственный, при котором рядом с ВМ ничего не должно работать: при ослабленном AMFI `vphone-vm` запускается сам.--**Вариант B — оставить SIP включённым (ослабленным только для отладки) и внести эту сборку в allowlist** (в остальное время и для всех бинарников, которые вы не разрешили, AMFI остаётся включённым).+С cloudOS 26.4 (`23E5207q`) проверены iPhone17,3 iOS 26.6.2 (`23G90`) и 27.0 (`24A435`): обе VM дошли до экрана блокировки и ответили на ping vphoned. Границы проверки описаны в [таблице совместимости](guides/compatibility.md).-В Recovery:+## Установка и сборка-```-csrutil enable --without debug-csrutil allow-research-guests enable-```+Готовому `.app` для запуска не нужны Homebrew, Python, Xcode или отдельное окружение. Для сборки из исходников требуется Xcode с iPhoneOS SDK для vphoned.-Затем перезагрузитесь в macOS и выполните:--```-make amfi_allow # спросит root; повторяйте после каждой сборки-make amfi_status # показать allowlist и может ли этот хост его нести-make amfi_off # удалить allowlist и чисто перезапустить amfid+```sh+git clone --recurse-submodules https://github.com/Lakr233/vphone-cli.git+cd vphone-cli+make build+.build/release/vphone-cli host preflight```-Это запускает `vphone-amfi-allow` — он собран из собственного C этого репозитория и поставляется внутри `.app`. Он пишет ровно две вещи:--* cdhash **обеих** копий `vphone-vm` в- `/Library/Preferences/com.apple.security.coderequirements.plist` — файл, который AMFI- и так читает; это его собственная функция, а не дыра;-* **один байт кучи** amfid, чтобы перевернуть флаг `_isRunningInternalBuild`, из-за- которого он вообще заглядывает в этот файл.--Обеих — потому что `make boot` запускает обе: `boot_binary_check` запускает-`.build/release/vphone-vm`, а сама загрузка — ту, что внутри `.app`. Они подписаны под-разными идентификаторами и хешируются по-разному, так что разрешение одной покрывает ровно-половину сценария.--**Повторяйте после каждой сборки.** Allowlist привязан к cdhash, а тот меняется при любой подписи — в том числе от голого `swift build`.--Разрешать нужно `vphone-vm`. У `vphone-cli` нет entitlements и он запускается всегда, так что его cdhash не нужен.--> **Честно о том, что это разрешает.** Это allowlist по cdhash: для всех бинарников, которые вы не указали, amfid продолжает проверять подписи. `make amfi_off` удаляет файл и перезапускает amfid.->-> Этот один байт лежит в **куче** amfid, а не в его `__TEXT`, и именно в этом всё дело. Прежние подходы правили код: `vphone-letmein` переписывал `ldrb` в `-[AMFIPathValidator_macos validateWithError:]`, а инструменты на LLDB ставят `BRK` ради точки останова. Оба оставляют «грязную» неподписанную исполняемую страницу, и на хосте, где `sysctl vm.cs_system_enforcement` равен 1 — измерено на macOS 27.0 (26A428), arm64e, ровно с теми настройками `csrutil`, что выше, — ядро проверяет её при следующем фолте, убивает amfid и забирает с собой гостя. Sysctl доступен только для чтения во время работы, так что «пропатчить код» не выживет при любой аккуратности. Куча — это не код, и enforcement нечего возразить.--## Протестированные окружения--| Хост ↕▾ | 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` |-| −Mac16,11 27.0b2 | `17,3_27.0_24A5430a` | `26.4-23E5207q` |-⚙--## FAQ--**`zsh: killed ./vphone-vm`** — ограничения AMFI/debug не обойдены; см. «Ослабление SIP/AMFI» (`amfi_get_out_of_my_way=1` — вариант A, либо `make amfi_allow` для этой сборки — вариант B). Если вы запускали его *до* последней сборки, запустите ещё раз: allowlist привязан к cdhash, а подпись его меняет. Обратите внимание: с самим `vphone-cli` такого произойти не может — у него нет entitlements, поэтому если убивают *его*, дело в чём-то другом.--**`Virtualization is not available on this hardware`** — ваш Mac сам является ВМ; загрузка гостя PV=3 не может быть вложенной. Используйте невложенный хост macOS 15+.--**Застряли на "Press home to continue"** — подключитесь через VNC и щёлкните правой кнопкой (клик двумя пальцами), чтобы смоделировать кнопку Home.--**Системные приложения не устанавливаются** — при настройке iOS не выбирайте Японию или ЕС в качестве региона (дополнительные регуляторные проверки, которые ВМ не может пройти); выберите, например, США.--**Приложение падает при запуске с `EXC_GUARD` / `GUARD_TYPE_MACH_PORT`** — перепатчите с `vphone-cli fw patch <name> --variant <v> --force-exc-guard`, затем переустановите/восстановите ([#291](https://github.com/Lakr233/vphone-cli/issues/291)). Всегда включено для баз iOS 18.--**Установка `.ipa`/`.tipa`** — используйте меню Install работающей ВМ (drag-drop или выбор файла).--**Нужен ли Homebrew или Xcode, чтобы этим пользоваться?** — Нет. `vphone-cli` работает на чистой macOS 15+: всё, что он запускает, лежит в `/usr/bin`, `/bin`, `/usr/sbin` или `/sbin`, а всё остальное — внутри `.app`. Следит за этим `make check-aux`. Сборка из исходников — другое дело: для неё нужны Xcode (iOS SDK, под который кросс-компилируются гостевые бинарники) и `git-lfs` (для `scripts/resources`).--**`cfw install` зависает при переподписи системного бинарника (например, `Campo`), память растёт бесконтрольно** — это был баг в `ldid-procursus` вплоть до `2.1.5-procursus7`: `bytes(uint64_t)` вызывал `__builtin_clzll(0)` без защиты от нуля, что является неопределённым поведением, и в той сборке приводило к длине `0`, вызывавшей underflow беззнакового счётчика цикла, — `ldid` крутился, записывая по одному байту в растущий буфер, вместо завершения. Срабатывало на *любом* plist прав с целочисленным значением ровно `0`, а такие есть у настоящих системных бинарников Apple. Больше этого случиться не может: подпись делает `vphone-cli sign` внутри процесса, а `ldid` не устанавливается, не вызывается и не поставляется.--## Автоматизация--`vphone-cli` предоставляет сокет управления хостом (`<bundle>/vphone.sock`) для программного управления — скриншоты, касания, свайпы, аппаратные кнопки, буфер обмена — каждое действие возвращает встроенный скриншот для AI-driven E2E-тестирования. См. [vphone-mcp](https://github.com/pluginslab/vphone-mcp) для MCP-сервера, оборачивающего его.--## Благодарности--- [wh1te4ever/super-tart-vphone-writeup](https://github.com/wh1te4ever/super-tart-vphone-writeup)+Если хост использует список разрешений AMFI, повторяйте `make amfi_allow` после каждой сборки. Актуальные руководства и исследовательские заметки собраны в [оглавлении](README.md). Подробные руководства пока доступны на английском.diff --git a/docs/README_zh.md b/docs/README_zh.mdindex 3fc79353..a20e03ff 100644--- a/docs/README_zh.md+++ b/docs/README_zh.md@@ -1,230 +1,51 @@-<div align="right"><strong><a href="./README_ko.md">🇰🇷한국어</a></strong> | <strong><a href="./README_ja.md">🇯🇵日本語</a></strong> | <strong>🇨🇳中文</strong> | <strong><a href="./README_ru.md">🇷🇺Русский</a></strong> | <strong><a href="./README_pt.md">🇧🇷Português</a></strong> | <strong><a href="../README.md">🇬🇧English</a></strong></div>+<div align="right"><a href="../README.md">English</a> · <strong>中文</strong> · <a href="README_ja.md">日本語</a> · <a href="README_ko.md">한국어</a> · <a href="README_ru.md">Русский</a> · <a href="README_pt.md">Português</a></div># vphone-cli-使用 PCC 研究虚拟机基础设施,通过 Apple 的 Virtualization.framework 启动一台虚拟 iPhone。+用 Apple Virtualization.framework 和 PCC 研究虚拟机基础设施启动虚拟 iPhone。-+-## 前置条件--**运行需要:**--- Apple Silicon-- macOS 15+(Sequoia)-- [放宽 SIP/AMFI,以允许未签名二进制使用私有 PV=3 授权](#放宽-sipamfi)--**除此之外什么都不需要。** 没有 Homebrew 包,没有解释器,没有包管理环境,也不需要-Xcode。vphone-cli 运行的每一个程序,要么是 `/usr/bin`、`/bin`、`/usr/sbin`、`/sbin`-下的系统二进制,要么就在 `.app` 里面 —— 包括签名器(取代了 `ldid`)、归档读写-(`gtar`、`zstd`、`unzip`)、固件目录与 IM4P/AEA 处理(`ipsw`),以及 CFW 安装器-写进访客系统的那五个 iOS 二进制:它们在构建时交叉编译好随包分发,不在你的机器上编译。-`make check-aux` 就是守住这条线的准入门。--**从源码构建**则还需要 Xcode(那五个访客二进制要用它的 iOS SDK 交叉编译)和-`git-lfs`(`git clone` 取 `scripts/resources` 里的归档要用)。--## 安装--```bash-brew install zqxwce/tap/vphone-cli-```--## 构建--```bash-brew install git-lfs-git clone --recurse-submodules https://github.com/Lakr233/vphone-cli.git--./scripts/build.sh # 构建并签名 vphone-cli、交叉编译访客二进制、打包 .app--cd .build/vphone-cli.app/Contents/MacOS/-vphone-cli --help-```--`./scripts/setup_tools.sh` 是可选的,只构建一样东西:`insert_dylib` —— 一个-Mach-O 测试用来逐字节对照 Swift 注入器的独立参照物。分发出去的东西不会运行它。+目前公开的固件流程**只有 JB 一种**:打齐必要的系统补丁并安装 vphoned,方便宿主机控制。访客用户环境保持空白;本项目不会安装 Sileo、apt、TrollStore、SSH、VNC 或首次启动 bootstrap。## 快速开始-一条命令即可端到端创建一台虚拟机(下载 → 打补丁 → DFU 恢复 → CFW 安装 → 首次启动):+需要 Apple Silicon Mac、macOS 15 或更新版本,以及允许 PV=3 研究虚拟机和 `vphone-vm` 私有授权的宿主机设置。先看[宿主机准备](guides/host-setup.md)。-```bash-vphone-cli vm create myphone -V jb # -V / --variant+```sh+vphone-cli vm create myphone \+ --iphone-source /path/to/iPhone17,3_Restore.ipsw \+ --cloudos-source /path/to/cloudOS.ipswvphone-cli vm launch myphone```-## 命令--`vphone-cli vm create` 会运行整个流水线;下面的各个步骤让你可以手动驱动它,或重新运行某一个阶段。--### 管理--```bash-vphone-cli vm list # 列出虚拟机(--json 用于脚本)-vphone-cli vm info myphone # 显示某台虚拟机-vphone-cli vm new myphone # 创建一个空 bundle(cpu/内存/磁盘选项)-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 fast by default(--max = xz -9);--out 为目录时自动命名 <vm>.tzst/.txz;跳过 restore 目录 + 暂存文件-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. 空 bundle-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. 首次启动-```--要升级到更新的 iOS,把 `fw prepare` 指向一个 IPSW:`--iphone-source /path/to.ipsw --cloudos-source /path/to.ipsw`。--第 4、5 步都在 `vphone-cli` 自己的进程里完成。`restore` 直接驱动内置的 libirecovery-和 idevicerestore——没有外部刷机工具,第一次运行之前也不需要任何准备步骤。加-`--offline` 可以用虚拟机目录里已保存的 `.shsh` 刷机,而不再向 Apple 申请新的。--## 固件变体--五种补丁变体,安全绕过程度递增——将其中之一传给 `--variant`:--| 变体 | 引导链 | CFW | 说明 |-| --------- | ----------- | --------- | ------------------------------------------------- |-| `less` | 4 patches | 2 phases | 无补丁——保持 iOS 缓解措施启用 |-| `regular` | 42 patches | 10 phases | 绕过 AMFI/SSV/Img4/TXM |-| `dev` | 53 patches | 12 phases | + 绕过 TXM 授权/调试 |-| `jb` | 113 patches | 14 phases | + 完整越狱(首次启动时自动安装 Sileo、TrollStore)|-| `exp` | 141 patches | 18 phases | JB 超集 + 反虚拟机检测研究补丁 |--各组件的详细拆解见 [`research/0_binary_patch_comparison.md`](../research/0_binary_patch_comparison.md)。--## 运行与连接--- **SSH(越狱):** `ssh -p 22222 mobile@<vm-ip>`(密码 `alpine`)-- **SSH(regular/dev):** `ssh -p 22222 root@<vm-ip>`-- **VNC:** `vnc://<vm-ip>: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 seal-volume 制品(`apfs_sealvolume_<version>`)缓存。 |-| `~/.vphone/debs/` | `jb`/`exp` CFW 安装写入客户机的 `.deb` 包缓存(Sileo、apt 等)。 |--优先级:单项覆盖 `$VPHONE_LIBRARY_ROOT` 优先于 `$VPHONE_ROOT`,`$VPHONE_ROOT` 优先于 `~/.vphone` 默认值。`ipsws/`、`tools/` 和 `debs/` 缓存始终位于当前生效的根目录之下。--## 放宽 SIP/AMFI--**方案 A——完全禁用 SIP,然后通过 boot-arg 禁用 AMFI(最宽松)。**--在恢复模式下(长按电源键 → 终端):--```bash-csrutil disable-csrutil allow-research-guests enable-```--然后重启进入 macOS 并设置 AMFI boot-arg(需要 SIP 完全关闭才能生效):--```bash-sudo nvram boot-args="amfi_get_out_of_my_way=1 -v" # 之后重启-```--这依然是最省事的方案,也是唯一不需要在虚拟机旁边额外跑东西的方案:AMFI 一旦放宽,`vphone-vm` 自己就能启动。--**方案 B——保持 SIP 开启(仅放宽 debug),把这次构建加进白名单**(其余时间、以及所有未被你放行的二进制,AMFI 仍然生效)。+`vm create` 会完成固件准备、JB 补丁、DFU 恢复、CFW 安装,并在首次启动时真正 ping 一次 vphoned。**验收成功后,它会关闭这次临时启动**;要继续使用,请再执行 `vm launch`。恢复阶段需要网络,CFW 安装需要管理员认证。两个 VM 请依次创建,避免磁盘与内存占用叠加。-在恢复模式下:+已用 cloudOS 26.4(`23E5207q`)验证 iPhone17,3 的 iOS 26.6.2(`23G90`)和 27.0(`24A435`):两者都到达锁屏并收到 vphoned ping。其他组合请看[兼容性记录](guides/compatibility.md),不要把它们视为已完成同等验收。-```bash-csrutil enable --without debug-csrutil allow-research-guests enable-```+## 安装与构建-然后重启进入 macOS,运行:+成品 `.app` 运行时不需要 Homebrew、Python 或 Xcode,也不需要额外安装运行环境。从源码构建则需要 Xcode 的 iPhoneOS SDK,以编译 vphoned:-```bash-make amfi_allow # 需要 root;每次构建之后都要重跑-make amfi_status # 查看白名单,以及这台机器能不能承载它-make amfi_off # 移除白名单并干净地重启 amfid+```sh+git clone --recurse-submodules https://github.com/Lakr233/vphone-cli.git+cd vphone-cli+make build+.build/release/vphone-cli host preflight```-它运行的是 `vphone-amfi-allow`——本仓库自己的 C 代码,随 `.app` 一起分发。它写两样东西:--* 把两份 `vphone-vm` 的 cdhash 写进 `/Library/Preferences/com.apple.security.coderequirements.plist`,- 这是 AMFI 本来就会读的文件——是它自带的机制,不是什么漏洞;-* 改 amfid 堆上的**一个字节**,把 `_isRunningInternalBuild` 标志翻过来,让它去读那个文件。--两份都要,因为 `make boot` 两份都会跑:`boot_binary_check` 跑 `.build/release/vphone-vm`,-开机本身跑 `.app` 里的那份。它们用不同的标识符签名,哈希也不同,只放行一份恰好只覆盖一半流程。--**每次构建之后都要重跑。** 它按 cdhash 放行,而任何一次签名都会改变 cdhash——包括一次裸的 `swift build`。--要放行的是 `vphone-vm`。`vphone-cli` 不带任何 entitlement、总能正常启动,所以要的不是它的 cdhash。--> **请如实看待它放行了什么。** 这是一个按 cdhash 匹配的白名单:对于你没有列出的一切,amfid 照常校验。`make amfi_off` 会删掉那个文件并重启 amfid。->-> 那一个字节写的是 amfid 的**堆**,不是它的 `__TEXT`,而这正是它能work的全部原因。早先的做法都在改代码——`vphone-letmein` 覆写 `-[AMFIPathValidator_macos validateWithError:]` 里的 `ldrb`,基于 LLDB 的工具则会为断点植入 `BRK`。两者都会留下一个被写脏的、未签名的可执行页面;在 `sysctl vm.cs_system_enforcement` 为 1 的主机上(在 macOS 27.0 (26A428)、arm64e,以及上面那套 `csrutil` 配置下实测就是 1),内核会在下一次缺页时校验该页面、杀掉 amfid,并连带杀掉客户机。该 sysctl 在运行时是只读的,所以「改代码」这条路再小心也活不下来。写堆不是代码,强制校验就无从反对。--## 测试环境--| 宿主机 | 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,6 26.6.1 | `17,3_26.6.2_23G90` | `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` |-| Mac16,11 27.0b2 | `17,3_27.0_24A5430a` | `26.4-23E5207q` |-| Mac16,6 26.6.1 | `17,3_27.0_24A435` | `26.4-23E5207q` |--## 常见问题--**`zsh: killed ./vphone-vm`** —— AMFI/debug 限制未被绕过;见[放宽 SIP/AMFI](#放宽-sipamfi):要么用 `amfi_get_out_of_my_way=1`(方案 A),要么对这次构建跑 `make amfi_allow`(方案 B)。如果你是在上一次构建*之前*跑的,请再跑一次:白名单按 cdhash 匹配,而签名会改变它。注意这不会发生在 `vphone-cli` 自身上:它不带任何 entitlement,所以如果被杀的是*它*,那就是别处出了问题。--**`Virtualization is not available on this hardware`** —— 你的 Mac 本身就是一台虚拟机;PV=3 客户机启动无法嵌套。请使用非嵌套的 macOS 15+ 宿主机。--**卡在 “Press home to continue”** —— 通过 VNC 连接,然后右键点击(双指点击)来模拟 home 键。--**系统应用无法安装** —— 在 iOS 设置过程中,不要选择日本或欧盟作为你的地区(会有额外的监管检查,虚拟机无法满足);请选择例如美国。--**应用启动时崩溃并报 `EXC_GUARD` / `GUARD_TYPE_MACH_PORT`** —— 用 `vphone-cli fw patch <name> --variant <v> --force-exc-guard` 重新打补丁,然后重新恢复/安装([#291](https://github.com/Lakr233/vphone-cli/issues/291))。对于 iOS 18 基础版本始终启用。--**安装 `.ipa`/`.tipa`** —— 使用运行中虚拟机的 Install 菜单(拖放或文件选择器)。--## 自动化+采用 AMFI 白名单的宿主机,每次重编译后都要重新运行 `make amfi_allow`。详细设置见[宿主机准备](guides/host-setup.md)。-`vphone-cli` 暴露了一个宿主控制套接字(`<bundle>/vphone.sock`)用于程序化控制——截图、触控、滑动、硬件按键、剪贴板——每个动作都会返回一张内联截图,用于 AI 驱动的端到端测试。包装它的 MCP 服务器见 [vphone-mcp](https://github.com/pluginslab/vphone-mcp)。+## 常用命令-## 致谢+| 操作 | 命令 |+| --- | --- |+| 列出虚拟机 | `vphone-cli vm list` |+| 启动窗口 | `vphone-cli vm launch myphone` |+| 停止虚拟机 | `vphone-cli vm stop myphone` |+| 导出备份 | `vphone-cli vm export myphone --out myphone.tzst` |+| 导入备份 | `vphone-cli vm import myphone.tzst --name restored` |+| 查看固件配对 | `vphone-cli fw catalog` |-- [wh1te4ever/super-tart-vphone-writeup](https://github.com/wh1te4ever/super-tart-vphone-writeup)+虚拟机和固件缓存默认位于 `~/.vphone/`。完整步骤、手动流水线和存储路径见[创建与运行指南](guides/create-and-run.md)。[文档目录](README.md)汇总其余指南;[研究目录](../research/README.md)收录补丁与实现记录。详细指南目前以英文为准。diff --git a/docs/guides/compatibility.md b/docs/guides/compatibility.mdnew file mode 100644index 00000000..e9dc928a--- /dev/null+++ b/docs/guides/compatibility.md@@ -0,0 +1,41 @@+# Firmware compatibility++[Documentation](../README.md) · [Create a VM](create-and-run.md) · [Patch inventory](../../research/0_binary_patch_comparison.md)++## Tested Environments++These are the two iPhone17,3 combinations exercised with the native JB pipeline in [PR #486](https://github.com/Lakr233/vphone-cli/pull/486). Both reached the lock screen and answered a vphoned ping. A fresh 26.6.2 `vm create` also completed all stages and exited successfully after its first-boot ping.++| Validation | iPhone restore IPSW | PCC/cloudOS IPSW | Observed result |+| --- | --- | --- | --- |+| PR #486 | `17,3_26.6.2_23G90` | `26.4-23E5207q` | JB patches, restore, CFW, boot, vphoned ping |+| PR #486 | `17,3_27.0_24A435` | `26.4-23E5207q` | JB patches, restore, CFW, boot, vphoned ping |++The cloudOS 26.4 image was the latest one **verified to contain `vphone600ap` during that investigation**. This is a dated observation, not a promise that it remains the newest available release. Use `vphone-cli fw catalog` to inspect the current catalogue. Other versions may work, but they have not passed this same end-to-end check.++## Earlier reported combinations++The previous README recorded the following host and firmware pairings. They predate the current single-mode flow or lack the same vphoned acceptance evidence, so treat them as research history rather than the current support matrix.++| 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,6 26.6.1 | `17,3_26.6.2_23G90` | `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` |+| Mac16,11 27.0b2 | `17,3_27.0_24A5430a` | `26.4-23E5207q` |+| Mac16,6 26.6.1 | `17,3_27.0_24A435` | `26.4-23E5207q` |diff --git a/docs/guides/create-and-run.md b/docs/guides/create-and-run.mdnew file mode 100644index 00000000..4a53a80d--- /dev/null+++ b/docs/guides/create-and-run.md@@ -0,0 +1,68 @@+# Create and run a VM++[Documentation](../README.md) · [Host setup](host-setup.md) · [Compatibility](compatibility.md)++The public firmware workflow creates one **JB** configuration. It patches the boot chain and guest system, installs vphoned, and leaves the user's environment empty. It does not install Sileo, apt, TrollStore, an SSH server or VNC server.++## One-command flow++Supply an iPhone17,3 restore IPSW and a compatible PCC/cloudOS IPSW as local paths or URLs. [Compatibility](compatibility.md) records the pairs actually verified here.++```sh+vphone-cli host preflight+vphone-cli vm create myphone \+ --iphone-source /path/to/iPhone17,3_Restore.ipsw \+ --cloudos-source /path/to/cloudOS.ipsw+```++Creation runs prepare → JB patch → online DFU restore → host-mounted CFW installation → first GUI boot. It needs network access for the restore ticket. CFW installation needs administrator authentication; on a host without an interactive terminal, `--root-popup` uses a macOS authentication dialog. The default virtual disk is 64 GB. `--keep-artifacts` retains the large prepared restore tree; omit it when disk space matters.++Success ends with `First boot: vphoned ping succeeded` and `JB VM created; vphoned connected`. **The verification VM is then stopped.** The ping proves the daemon answered over the host control socket during that boot; it does not leave a running VM behind.++```sh+vphone-cli vm launch myphone # start the VM window and keep it running+vphone-cli vm stop myphone # run from another terminal to stop it+```++`vm launch` starts the guest without waiting for vphoned; the daemon connects during boot. The VM window and menu provide Home/power keys, app installation and file browsing. The host control socket is `<VM bundle>/vphone.sock`. No SSH or VNC endpoint is installed by this workflow.++## Manual stages++Use these when investigating or repeating one phase. Keep a DFU boot running while `restore` talks to it:++```sh+vphone-cli vm new myphone+vphone-cli fw prepare myphone \+ --iphone-source /path/to/iPhone17,3_Restore.ipsw \+ --cloudos-source /path/to/cloudOS.ipsw+vphone-cli fw patch myphone++vphone-cli vm launch myphone --dfu &+vphone-cli restore myphone+vphone-cli vm stop myphone++vphone-cli cfw install myphone+vphone-cli vm launch myphone+```++The online restore obtains its ticket in process. For an offline restore, see `vphone-cli restore --help` for `--get-shsh` and `--offline`. The manual flow does not perform the automatic first-boot ping check from `vm create`.++## Library, firmware and backups++| Default path | Contents |+| --- | --- |+| `~/.vphone/VMs/` | One bundle per VM, including its disk and `config.plist` |+| `~/.vphone/ipsws/` | Cached source IPSWs |+| `~/.vphone/tools/` | Cached firmware patching tools and artifacts |++`VPHONE_ROOT` relocates the complete tree. `VPHONE_LIBRARY_ROOT` takes precedence for the VM library alone. Source IPSWs remain cached; the prepared restore tree is removed after a successful `vm create` unless `--keep-artifacts` is set.++```sh+vphone-cli vm list+vphone-cli vm info myphone+vphone-cli vm clone myphone copy+vphone-cli vm export myphone --out myphone.tzst+vphone-cli vm import myphone.tzst --name restored+```++Run resource-heavy creations **one at a time**. Both the IPSWs and temporary restore tree consume substantial disk space, and patching large caches can be memory intensive. Check free space before starting a second VM.diff --git a/docs/guides/host-setup.md b/docs/guides/host-setup.mdnew file mode 100644index 00000000..4837fa01--- /dev/null+++ b/docs/guides/host-setup.md@@ -0,0 +1,62 @@+# Host setup++[Documentation](../README.md) · [Create a VM](create-and-run.md) · [Troubleshooting](troubleshooting.md)++The VM needs an Apple Silicon Mac running macOS 15 or newer. PV=3 research guests do not run inside a nested macOS VM. The signed `vphone-vm` companion carries Apple-private virtualization entitlements; the unentitled `vphone-cli` entry point can still print a useful error if the host refuses it.++## Build and preflight++A distributed `.app` needs no Homebrew, Python or Xcode **at runtime**. A source build needs Xcode and its iPhoneOS SDK to compile vphoned. From a source checkout:++```sh+make build+.build/release/vphone-cli host preflight+```++Use `make build` rather than bare `swift build`: the latter does not perform the required signing and bundling. `host preflight` checks the entitled companion before any VM is started. If AMFI refuses it, the error prints the exact command for the bundled allowlist helper.++## Permit the entitled VM binary++These are host policy choices, performed by the machine owner. Both require `csrutil allow-research-guests enable` in Recovery. Choose one path.++### A. Disable SIP and AMFI++In macOS Recovery, open Terminal:++```sh+csrutil disable+csrutil allow-research-guests enable+```++After rebooting into macOS, set the boot argument and reboot again:++```sh+sudo nvram boot-args="amfi_get_out_of_my_way=1 -v"+```++This is the more permissive host configuration. Review existing `boot-args` before replacing them.++### B. Keep SIP enabled with debugging restrictions relaxed++In macOS Recovery:++```sh+csrutil enable --without debug+csrutil allow-research-guests enable+```++After rebooting, allowlist the **current signed build**. In a source checkout:++```sh+make amfi_allow+make amfi_status+.build/release/vphone-cli host preflight+```++`make amfi_allow` asks for administrator authentication and includes both the standalone and bundled copies of `vphone-vm`. The helper records their cdhashes in the AMFI code-requirements preference and enables amfid to consult it by changing one byte in its heap. It is scoped to these signed binaries. **Run `make amfi_allow` again after every build**, including a rebuild that only changes the signature. `make amfi_off` removes the allowlist and restarts amfid.++For a distributed app without a source checkout, run `vphone-cli host preflight` first. If AMFI refuses the guest, its error gives the full `sudo .../vphone-amfi-allow allow .../vphone-vm` command for that installed app.++## What the build contains++`vphone-cli` orchestrates the work without private entitlements. `vphone-vm` is the signed, entitled GUI/VM process. `vphone-archive` handles archives. The project also bundles vphoned, compiled for iOS at build time; it is installed into each created guest. The [research notes on the binary split](../../research/host/host_binary_split.md) record the implementation history, including superseded approaches.diff --git a/docs/guides/troubleshooting.md b/docs/guides/troubleshooting.mdnew file mode 100644index 00000000..53256900--- /dev/null+++ b/docs/guides/troubleshooting.md@@ -0,0 +1,29 @@+# Troubleshooting++[Documentation](../README.md) · [Host setup](host-setup.md) · [Create a VM](create-and-run.md)++## `vphone-vm` is killed before the VM opens++Run `vphone-cli host preflight`. The CLI is unentitled and can explain an AMFI refusal of its signed `vphone-vm` companion. If you rebuilt, the cdhash changed: run `make amfi_allow` again in the source checkout, or use the bundled helper command printed by preflight. [Host setup](host-setup.md) covers the required Recovery settings.++## `Virtualization is not available on this hardware`++PV=3 guests cannot be nested. Boot on an Apple Silicon Mac rather than inside another macOS VM.++## `vm create` printed vphoned success, but no VM is running++That is expected. Creation starts a temporary GUI boot, sends a real ping, and stops that boot before returning. Start the VM for use with `vphone-cli vm launch <name>`.++## Stuck at “Press home to continue”++Use the VM window's **Keys → Home** action. The current JB workflow does not install a VNC server.++## App exits with `EXC_GUARD` / `GUARD_TYPE_MACH_PORT`++The optional `vphone-cli fw patch <name> --force-exc-guard` patch can address this class of crash. Repatching firmware alone does not alter an already restored guest: restore and reinstall CFW after changing the patch set. See [issue #291](https://github.com/Lakr233/vphone-cli/issues/291).++## Restore or first boot fails++Keep the VM in DFU until `restore` exits in a manual flow, and check that online ticket requests can reach Apple. For the complete pipeline, rerun `vm create` with a **new name** and `-v` for tool detail; avoid parallel VM creation when memory or disk is tight. Inspect [firmware compatibility](compatibility.md) before combining an iPhone IPSW with a PCC image.++If the guest boots but vphoned does not answer, the first-boot check times out after 300 seconds. A GUI boot is used because a newly restored guest may not bring up vphoned during its first headless boot. See [create and run](create-and-run.md) for what the success marker proves.diff --git a/research/0_binary_patch_comparison.md b/research/0_binary_patch_comparison.mdindex 7d740f62..490807dc 100644--- a/research/0_binary_patch_comparison.md+++ b/research/0_binary_patch_comparison.md@@ -371,7 +371,7 @@ The tests asserting a frozen digest moved off it first, onto the real 24A435`seputil`; the rest of `CFWMachOTests` — structural cases that only needed *some*signed Mach-O — kept pointing at the build product, and that stopped being viablewhen `vphone-letmein` was deleted from the tree (see-`research/host_binary_split.md`). All of `CFWMachOTests` now takes its fixture+`research/host/host_binary_split.md`). All of `CFWMachOTests` now takes its fixturethe way the sibling CFW parity suites do: `macho_pristine/seputil`, resolvedthrough `VPHONE_MACHO_PRISTINE` with `ipsws/ref_extract/macho_pristine` as thedefault, **failing** rather than skipping when it is absent, since a skipped test@@ -429,7 +429,7 @@ list; P2 then deleted the list.** `requirements.txt`, `scripts/setup_venv.sh`,`scripts/pymobiledevice3_bridge.py` are all gone — the restore backend was thelast program holding any of them up, and it is `sources/VPhoneRestore` overvendored libirecovery and idevicerestore now-(`research/p2_restore_off_python.md`). No Python is tracked in this repository+(`research/restore/p2_restore_off_python.md`). No Python is tracked in this repositoryand nothing resolves a `python3` at runtime.### Installed Components@@ -455,7 +455,7 @@ consumers, ~15 entries). Patched dylibs query the renamed OID and get thetruthful 1 (graphics + accel passthrough); blacklisted dylibs keep theoriginal cstring, hit ENOENT on the renamed kernel, and defensively cache 0("not running on a VM") for sign-in / device-attestation surfaces.-Source-of-truth research: `research/hv_vmm_present_usermode_xrefs.md`.+Source-of-truth research: `research/patches/hv_vmm_present_usermode_xrefs.md`.JB and other variants are NOT affected by this patcher.diff --git a/research/README.md b/research/README.mdnew file mode 100644index 00000000..26004b37--- /dev/null+++ b/research/README.md@@ -0,0 +1,26 @@+# Research library++[Project overview](../README.md) · [User documentation](../docs/README.md)++This directory keeps the evidence behind firmware patches, restore and the self-contained host runtime. **The current public workflow is JB only.** Many notes record earlier experiments and command names; use the [user guides](../docs/README.md) and `vphone-cli --help` for current instructions.++## Start here++1. [Patch comparison](0_binary_patch_comparison.md) is the canonical per-component inventory. Its regular/dev/exp columns are historical.+2. [Firmware manifest and origins](firmware/firmware_manifest_and_origins.md) explains the hybrid firmware inputs.+3. [JB kernel patch notes](kernel/kernel_jb_patch_notes.md) and the [individual patch index](kernel_patch_jb/README.md) lead to the kernel evidence.+4. [Native restore design](restore/p2_restore_off_python.md) and [self-contained runtime](host/d2_d3_self_containment.md) explain the host migration.++## By subject++| Subject | Notes |+| --- | --- |+| Firmware and boot chain | [Manifest and origins](firmware/firmware_manifest_and_origins.md), [iBoot patches](firmware/iboot_patches.md), [TXM full chain](firmware/txm_fullchain_analysis.md), [TXM JB patches](firmware/txm_jb_patches.md), [selector 24](firmware/txm_selector24_analysis.md), [variant differences](firmware/txm_variant_diff.md) |+| Kernel | [JB overview](kernel/kernel_jb_patch_notes.md), [patcher verification](kernel/kernel_patcher_verification.md), [FairPlay kexts](kernel/kernel_fairplay_kexts.md), [base validation 1–5](kernel/kernel_patch_base_first5_validation.md), [11–15](kernel/kernel_patch_base_11_15_validation.md), [16–20](kernel/kernel_patch_base_16_20_validation.md), [sandbox hooks](kernel/kernel_patch_sandbox_hooks_17_26_validation.md), [individual patch notes](kernel_patch_jb/README.md) |+| Other patches and captures | [Launchd jetsam](patches/cfw_patch_launchd_jetsam.md), [user-mode hypervisor references](patches/hv_vmm_present_usermode_xrefs.md), [reference capture](patches/patch_reference_capture.md) |+| Restore | [DFU probe](restore/p2_dfu_spike.md), [in-process restore](restore/p2_restore_off_python.md) |+| Host and archives | [Binary split](host/host_binary_split.md), [runtime dependency tiers](host/d2_d3_self_containment.md), [archive extraction contracts](host/archive_extraction_contracts.md), [libarchive validation](host/libarchive_xcframework_validation.md) |+| Guest interaction and VM identity | [DevMode XPC](guest/devmode_xpc_protocol.md), [keyboard events](guest/keyboard_event_pipeline.md), [machine identifier](guest/machine_identifier_storage_analysis.md) |+| Historical project records | [Migration ledger](history/intg_update_status.md), [manifest refactoring summary](history/manifest_and_refactoring_summary.md) |++`kernel_info/` holds symbol datasets and indexes; `reference/` holds source references when present. They are evidence inputs, not steps for running the distributed app. The files in `history/` are preserved snapshots and may describe scripts or variants that have since been removed.diff --git a/research/firmware_manifest_and_origins.md b/research/firmware/firmware_manifest_and_origins.mdsimilarity index 100%rename from research/firmware_manifest_and_origins.mdrename to research/firmware/firmware_manifest_and_origins.mddiff --git a/research/iboot_patches.md b/research/firmware/iboot_patches.mdsimilarity index 100%rename from research/iboot_patches.mdrename to research/firmware/iboot_patches.mddiff --git a/research/txm_fullchain_analysis.md b/research/firmware/txm_fullchain_analysis.mdsimilarity index 100%rename from research/txm_fullchain_analysis.mdrename to research/firmware/txm_fullchain_analysis.mddiff --git a/research/txm_jb_patches.md b/research/firmware/txm_jb_patches.mdsimilarity index 100%rename from research/txm_jb_patches.mdrename to research/firmware/txm_jb_patches.mddiff --git a/research/txm_selector24_analysis.md b/research/firmware/txm_selector24_analysis.mdsimilarity index 100%rename from research/txm_selector24_analysis.mdrename to research/firmware/txm_selector24_analysis.mddiff --git a/research/txm_variant_diff.md b/research/firmware/txm_variant_diff.mdsimilarity index 100%rename from research/txm_variant_diff.mdrename to research/firmware/txm_variant_diff.mddiff --git a/research/devmode_xpc_protocol.md b/research/guest/devmode_xpc_protocol.mdsimilarity index 100%rename from research/devmode_xpc_protocol.mdrename to research/guest/devmode_xpc_protocol.mddiff --git a/research/keyboard_event_pipeline.md b/research/guest/keyboard_event_pipeline.mdsimilarity index 100%rename from research/keyboard_event_pipeline.mdrename to research/guest/keyboard_event_pipeline.mddiff --git a/research/machine_identifier_storage_analysis.md b/research/guest/machine_identifier_storage_analysis.mdsimilarity index 100%rename from research/machine_identifier_storage_analysis.mdrename to research/guest/machine_identifier_storage_analysis.mddiff --git a/research/intg_update_status.md b/research/history/intg_update_status.mdsimilarity index 94%rename from research/intg_update_status.mdrename to research/history/intg_update_status.mdindex 5b546226..3c055d5d 100644--- a/research/intg_update_status.md+++ b/research/history/intg_update_status.md@@ -1,5 +1,12 @@# `vphone-intg-update` — progress against the migration plan+> **Historical snapshot (2026-09-23).** This ledger records work in progress+> before the JB-only native pipeline was completed in+> [PR #486](https://github.com/Lakr233/vphone-cli/pull/486). Its percentages,+> script names and remaining-work list are not the current project status.+> Start with the [project README](../../README.md) and+> [research index](../README.md) for current entry points.+> 2026-09-23. Branch off `qof-update-26-fall` @ `6d5ce7d`.>> Plan: `~/Desktop/vphone-cli-migration-plan.md`. Its phases are P0 → P4. This@@ -13,7 +20,7 @@>> **Updated at `a908f81`**, after D2 and D3 landed. The D2/D3 rows below are> rewritten; the D4 row is not, and the detail is in-> [`d2_d3_self_containment.md`](./d2_d3_self_containment.md), which is the+> [`d2_d3_self_containment.md`](../host/d2_d3_self_containment.md), which is the> handover for that work — what the tiers are, what each removed program was> replaced by, what was verified against the real tool, and what is left open.@@ -45,15 +52,15 @@ is 2,396 lines against 2,410 at the branch base.| P0.5 | `VPhoneArchive` + `vphone-archive` | ✅ library, binary, tests, fingerprint tool || P0.5 | switch the archive call sites | ✅ **done at `356bec6`.** `$TAR` is gone from `cfw_install*.sh`; only `cfw-kit` still finds `gtar`, and it is build tier and does not ship || P0.5 | `VPhoneSign`, drop `ldid` | ✅ **done at `356bec6`.** The installers and the Makefile call `vphone-cli sign`; nothing looks `ldid` up any more except `cfw-kit` |-| P0.5 | admission gates | ✅ **`make check-aux`, six gates, all green, dist list empty** — see [`d2_d3_self_containment.md`](./d2_d3_self_containment.md) |+| P0.5 | admission gates | ✅ **`make check-aux`, six gates, all green, dist list empty** — see [`d2_d3_self_containment.md`](../host/d2_d3_self_containment.md) || **P1.0–1.5** | CFW patchers | ✅ **complete** — `scripts/patchers/` deleted at `d90371a`, 26 files / 6,539 lines into 24 `vphone-cli cfw` verbs |-| **P2.0** | can libirecovery see the virtual DFU endpoint? | ✅ **yes** — `research/p2_dfu_spike.md` |+| **P2.0** | can libirecovery see the virtual DFU endpoint? | ✅ **yes** — `research/restore/p2_dfu_spike.md` || **P2.1–2.2** | vendor libirecovery + idevicerestore | ✅ `sources/MobileRecoveryCore`, `sources/MobileRestoreCore` || **P2.3** | Swift wrapper + call-site replacement | ◐ **built and unit-tested; 4 of the 7 behaviour rows still need a device** || **P2.4** | Python → zero | ✅ **complete** — see D1 above || P3, P4 | shell | ❌ not started |-`research/p2_restore_off_python.md` records what P2 decided and why, including+`research/restore/p2_restore_off_python.md` records what P2 decided and why, includingthe behaviour table row by row.That AMFI row went round in a circle in one day, so it is worth restating where@@ -63,7 +70,7 @@ it landed. The `amfidont` scripts came out and `vphone-letmein` went in; thenbypass: `vphone-cli` probes with `vphone-vm --help`, and on a refusal prints whatto run. `amfidont` is what it names, installed by the user into their own Python.This costs D1 nothing — it is not a dependency of this repo, and nothing here-imports or invokes it. `research/host_binary_split.md` has the measurement.+imports or invokes it. `research/host/host_binary_split.md` has the measurement.## D1, counted@@ -105,7 +112,7 @@ Two corrections to the earlier ledger's arithmetic:>> **Now**: `zsh scripts/check_aux.sh` reports gates 0, 1, 1b, 1c, 2 and 3 all> green, with the **dist tier's registered list empty**. See-> [`d2_d3_self_containment.md`](./d2_d3_self_containment.md).+> [`d2_d3_self_containment.md`](../host/d2_d3_self_containment.md).`zsh scripts/check_aux.sh --fast`, as of the previous revision:@@ -178,7 +185,7 @@ Nothing below can be done without root or a real guest.1. ~~**Can `vphone-vm` start a VM holding the entitlements alone?**~~**Answered: yes.** A guest booted and libirecovery enumerated its virtual- DFU endpoint — `research/p2_dfu_spike.md`.+ DFU endpoint — `research/restore/p2_dfu_spike.md`.2. ~~**`vphone-letmein` end to end.**~~ **Answered, and the answer removed thetool.** With `vm.cs_system_enforcement` = 1 the patched `__TEXT` page getsamfid killed (`CODESIGNING`, "Invalid Page") and the guest dies with it.@@ -189,11 +196,11 @@ Nothing below can be done without root or a real guest.3. **The four unverified rows of the P2 behaviour table** — a real restore(online and `--offline`), `--no-erase` update-in-place, and the exit-codecontract on failure. Table and criteria in- `research/p2_restore_off_python.md`. **Run these on a disposable VM**: a+ `research/restore/p2_restore_off_python.md`. **Run these on a disposable VM**: afailed restore leaves the guest in recovery.4. **FDR equivalence.** The old bridge ran `Restore(..., ignore_fdr=False)`;idevicerestore's FDR handling is internal. Device enumeration cannot settle- it, so `research/p2_dfu_spike.md` explicitly did not. It shows up only during+ it, so `research/restore/p2_dfu_spike.md` explicitly did not. It shows up only duringan actual restore, and it must not be assumed away.5. **Ownership restoration in `VPhoneArchive`**, which only happens as root, so`ARCHIVE_EXTRACT_OWNER` has never come into play. This is the blocker on@@ -258,7 +265,7 @@ Recorded because they were measured, not reasoned about.`AppleMobileDeviceLibrary` ships all five of those libraries plus OpenSSL asprebuilt xcframeworks, so only libirecovery (4,629 lines) and idevicerestore(20,918, of which 1,399 are ours) are vendored. The argument is in- `research/p2_restore_off_python.md`.+ `research/restore/p2_restore_off_python.md`.- **The admission rule caught a bug the plan did not predict**: signing`vphone-vm` first sealed the bundle over its siblings in an earlier state,and `codesign -v` reported "nested code is modified or invalid". The maindiff --git a/research/manifest_and_refactoring_summary.md b/research/history/manifest_and_refactoring_summary.mdsimilarity index 96%rename from research/manifest_and_refactoring_summary.mdrename to research/history/manifest_and_refactoring_summary.mdindex 062edc80..d8275217 100644--- a/research/manifest_and_refactoring_summary.md+++ b/research/history/manifest_and_refactoring_summary.md@@ -1,5 +1,10 @@# VPhone-CLI Manifest Implementation & Code Clarity Review+> **Historical snapshot.** This document describes the earlier shell/Python+> manifest implementation. Those commands and files have since been replaced+> by the native Swift workflow. See the [current VM guide](../../docs/guides/create-and-run.md)+> and [research index](../README.md).+## Summary1. **Implemented VM manifest system** compatible with security-pcc's VMBundle.Config formatdiff --git a/research/archive_extraction_contracts.md b/research/host/archive_extraction_contracts.mdsimilarity index 98%rename from research/archive_extraction_contracts.mdrename to research/host/archive_extraction_contracts.mdindex 58707ac7..463094aa 100644--- a/research/archive_extraction_contracts.md+++ b/research/host/archive_extraction_contracts.md@@ -3,7 +3,7 @@> 2026-09-23, branch `vphone-intg-update`. libarchive 3.8.9 from> `Lakr233/libarchive.xcframework` 0.1.1, macOS 26 (26A428).>-> Companion to `research/libarchive_xcframework_validation.md`, which covers+> Companion to `research/host/libarchive_xcframework_validation.md`, which covers> whether libzstd and the liblzma MT encoder are compiled in. This one is> about behaviour on disk.diff --git a/research/d2_d3_self_containment.md b/research/host/d2_d3_self_containment.mdsimilarity index 100%rename from research/d2_d3_self_containment.mdrename to research/host/d2_d3_self_containment.mddiff --git a/research/host_binary_split.md b/research/host/host_binary_split.mdsimilarity index 99%rename from research/host_binary_split.mdrename to research/host/host_binary_split.mdindex 74ea184b..9757c1cc 100644--- a/research/host_binary_split.md+++ b/research/host/host_binary_split.md@@ -227,7 +227,7 @@ nothing in the tree now.**Not verified — needs root and a real guest:**1. **Whether `vphone-vm` can actually start a VM holding the entitlements- alone.** — **settled**, see `research/p2_dfu_spike.md`: it booted a guest+ alone.** — **settled**, see `research/restore/p2_dfu_spike.md`: it booted a guestand libirecovery saw its DFU endpoint. Everything here rested on this, andit is the one item the DFU spike closed on the way past.2. **That the instructions printed on a refusal are the ones that work**, on adiff --git a/research/libarchive_xcframework_validation.md b/research/host/libarchive_xcframework_validation.mdsimilarity index 100%rename from research/libarchive_xcframework_validation.mdrename to research/host/libarchive_xcframework_validation.mddiff --git a/research/kernel_fairplay_kexts.md b/research/kernel/kernel_fairplay_kexts.mdsimilarity index 100%rename from research/kernel_fairplay_kexts.mdrename to research/kernel/kernel_fairplay_kexts.mddiff --git a/research/kernel_jb_patch_notes.md b/research/kernel/kernel_jb_patch_notes.mdsimilarity index 100%rename from research/kernel_jb_patch_notes.mdrename to research/kernel/kernel_jb_patch_notes.mddiff --git a/research/kernel_patch_base_11_15_validation.md b/research/kernel/kernel_patch_base_11_15_validation.mdsimilarity index 100%rename from research/kernel_patch_base_11_15_validation.mdrename to research/kernel/kernel_patch_base_11_15_validation.mddiff --git a/research/kernel_patch_base_16_20_validation.md b/research/kernel/kernel_patch_base_16_20_validation.mdsimilarity index 100%rename from research/kernel_patch_base_16_20_validation.mdrename to research/kernel/kernel_patch_base_16_20_validation.mddiff --git a/research/kernel_patch_base_first5_validation.md b/research/kernel/kernel_patch_base_first5_validation.mdsimilarity index 100%rename from research/kernel_patch_base_first5_validation.mdrename to research/kernel/kernel_patch_base_first5_validation.mddiff --git a/research/kernel_patch_sandbox_hooks_17_26_validation.md b/research/kernel/kernel_patch_sandbox_hooks_17_26_validation.mdsimilarity index 100%rename from research/kernel_patch_sandbox_hooks_17_26_validation.mdrename to research/kernel/kernel_patch_sandbox_hooks_17_26_validation.mddiff --git a/research/kernel_patcher_verification.md b/research/kernel/kernel_patcher_verification.mdsimilarity index 100%rename from research/kernel_patcher_verification.mdrename to research/kernel/kernel_patcher_verification.mddiff --git a/research/kernel_patch_jb/README.md b/research/kernel_patch_jb/README.mdnew file mode 100644index 00000000..210933b7--- /dev/null+++ b/research/kernel_patch_jb/README.md@@ -0,0 +1,16 @@+# JB kernel patch notes++[Research library](../README.md) · [Patch comparison](../0_binary_patch_comparison.md) · [Document framework](PATCH_DOC_FRAMEWORK.md)++These notes explain the source anchors, binary matches and validation evidence for individual JB kernel patches. The Swift implementations live under `sources/FirmwarePatcher/Kernel/JBPatches/`; the notes are research records, not commands to apply a patch by hand.++| Area | Patch notes |+| --- | --- |+| Boot, root and mount | [BSD init auth](patch_bsd_init_auth.md), [IO secure BSD root](patch_io_secure_bsd_root.md), [dounmount](patch_dounmount.md), [mac mount](patch_mac_mount.md), [load dylinker](patch_load_dylinker.md) |+| AMFI, credentials and policy | [CDHash in trust cache](patch_amfi_cdhash_in_trustcache.md), [execve kill path](patch_amfi_execve_kill_path.md), [credential label update](patch_cred_label_update_execve.md), [credential hook](patch_hook_cred_label_update_execve.md), [proc security policy](patch_proc_security_policy.md), [persona validation](patch_spawn_validate_persona.md), [sandbox hooks](patch_sandbox_hooks_extended.md), [NVRAM permission](patch_nvram_verify_permission.md) |+| Tasks, ports and threads | [convert port to map](patch_convert_port_to_map.md), [task conversion](patch_task_conversion_eval_internal.md), [task for PID](patch_task_for_pid.md), [thread set state](patch_thread_set_state.md), [thread crash gate](patch_thid_should_crash.md) |+| VM and shared regions | [VM fault](patch_vm_fault_enter_prepare.md), [immutable map delete](patch_vm_map_delete_immutable_code.md), [VM map protect](patch_vm_map_protect.md), [shared region map](patch_shared_region_map.md) |+| Process and syscall paths | [proc PID info](patch_proc_pidinfo.md), [syscall mask](patch_syscallmask_apply_to_proc.md), [kcall10](patch_kcall10.md) |+| Follow-up evidence | [26.5 hook fixes](26.5_jb_hook_fixes.md), [post-validation additions](patch_post_validation_additional.md), [runtime verification archive](runtime_verification/README.md) |++For the supported firmware flow, use `vphone-cli fw patch` or `vphone-cli vm create`; see the [user guide](../../docs/guides/create-and-run.md).diff --git a/research/kernel_patch_jb/runtime_verification/README.md b/research/kernel_patch_jb/runtime_verification/README.mdindex ee08f199..1f51ca38 100644--- a/research/kernel_patch_jb/runtime_verification/README.md+++ b/research/kernel_patch_jb/runtime_verification/README.md@@ -1,5 +1,11 @@# JB Runtime Verification Runbook+> **Archived research procedure.** The commands and local file paths below+> describe the 2026-03-05 investigation and may not exist in the current+> checkout. For the current JB flow, see the+> [VM guide](../../../docs/guides/create-and-run.md) and+> [patch notes index](../README.md).+This folder contains runtime + IDA verification artifacts for jailbreak kernel patches.## Quick Commandsdiff --git a/research/cfw_patch_launchd_jetsam.md b/research/patches/cfw_patch_launchd_jetsam.mdsimilarity index 100%rename from research/cfw_patch_launchd_jetsam.mdrename to research/patches/cfw_patch_launchd_jetsam.mddiff --git a/research/hv_vmm_present_usermode_xrefs.md b/research/patches/hv_vmm_present_usermode_xrefs.mdsimilarity index 100%rename from research/hv_vmm_present_usermode_xrefs.mdrename to research/patches/hv_vmm_present_usermode_xrefs.mddiff --git a/research/patch_reference_capture.md b/research/patches/patch_reference_capture.mdsimilarity index 100%rename from research/patch_reference_capture.mdrename to research/patches/patch_reference_capture.mddiff --git a/research/p2_dfu_spike.md b/research/restore/p2_dfu_spike.mdsimilarity index 95%rename from research/p2_dfu_spike.mdrename to research/restore/p2_dfu_spike.mdindex aeb7867f..89b334f9 100644--- a/research/p2_dfu_spike.md+++ b/research/restore/p2_dfu_spike.md@@ -9,7 +9,7 @@> the restore path is `sources/VPhoneRestore` over vendored libirecovery and> idevicerestore, and `scripts/pymobiledevice3_bridge.py` no longer exists.> Everything below is written as of the day of the spike, when it still did.-> `research/p2_restore_off_python.md` has what P2 went on to do.+> `research/restore/p2_restore_off_python.md` has what P2 went on to do.## Why it was a real question@@ -71,7 +71,7 @@ entire point of moving the entitlements off the entry point.> `vm.cs_system_enforcement` reads 1 — the kernel kills amfid for the dirty page> — so the tool was removed the same day. The spike's own findings do not depend> on it: what was shown is that a bypass lasting one exec suffices, not that any-> particular tool provides it. `research/host_binary_split.md` has the+> particular tool provides it. `research/host/host_binary_split.md` has the> measurement. The replacement is `amfidont`, below.## Reproducing it@@ -113,4 +113,4 @@ It was not, and cannot be from device enumeration alone: pymobiledevice3 ranWhether the two behave the same only shows up during an actual restore. That staysan open risk on P2.2 and must not be assumed away — it is called out here so thenext person does not read "P2.0 passed" as covering it. It is still open;-`research/p2_restore_off_python.md` carries it forward.+`research/restore/p2_restore_off_python.md` carries it forward.diff --git a/research/p2_restore_off_python.md b/research/restore/p2_restore_off_python.mdsimilarity index 98%rename from research/p2_restore_off_python.mdrename to research/restore/p2_restore_off_python.mdindex 2ef06044..af1e691d 100644--- a/research/p2_restore_off_python.md+++ b/research/restore/p2_restore_off_python.md@@ -59,7 +59,7 @@ autotools project, so the only file here that is not upstream's own bytes is`IOKit/usb/IOUSBLib.h`, upstream's `configure.ac` picks IOKit and never looksfor libusb; that is deliberate here too, because a libusb backend would put aHomebrew dylib in the link and gate 1 rejects it. It is also what-`research/p2_dfu_spike.md` proved works — see below.+`research/restore/p2_dfu_spike.md` proved works — see below.### `sources/MobileRestoreCore` — idevicerestore@@ -229,7 +229,7 @@ The rows still open are **1** (only as a single invocation — see its cell),**4** (the flag is new), **6** and the tail of **7**. **Run them on a disposableVM** — a failed restore leaves the guest sitting in recovery.-### `research/p2_dfu_spike.md` already settled the riskiest question+### `research/restore/p2_dfu_spike.md` already settled the riskiest questionP2.0 asked whether libirecovery's IOKit path can see a Virtualization.frameworkvirtual DFU endpoint at all — pymobiledevice3 reached it through pyusb, so one@@ -267,7 +267,7 @@ comparison.## Still open**FDR equivalence.** The Python ran `Restore(..., ignore_fdr=False)`;-idevicerestore's FDR handling is internal. `research/p2_dfu_spike.md` says+idevicerestore's FDR handling is internal. `research/restore/p2_dfu_spike.md` saysexplicitly that this could not be settled from device enumeration and was not,and it stays an open risk on P2.2. It shows up only during an actual restore.Do not read "P2.0 passed" as covering it.diff --git a/scripts/build.sh b/scripts/build.shindex a989d3d7..72665b45 100755--- a/scripts/build.sh+++ b/scripts/build.sh@@ -173,9 +173,13 @@ zsh scripts/dist_manifest.sh | rsync -a --files-from=- scripts/ "${RES}/scripts/mkdir -p "${RES}/guest"cp -f .build/guest/vphoned "${RES}/guest/vphoned"[[ -f .build/vphoned.signed ]] && cp -f .build/vphoned.signed "${RES}/vphoned.signed" || true-# README.md holds the Tested-Environments table used by `fw prepare`.-cp -f README.md "${RES}/README.md"-echo " bundled: scripts/ (dist tier), guest/vphoned, vphoned.signed, README.md"+# The compatibility guide is the only documentation `fw prepare` reads at runtime.+# Remove an old bundled README so it cannot silently become a stale data source.+rm -f "${RES}/README.md"+rm -rf "${RES}/docs"+mkdir -p "${RES}/docs/guides"+cp -f docs/guides/compatibility.md "${RES}/docs/guides/compatibility.md"+echo " bundled: scripts/ (dist tier), guest/vphoned, vphoned.signed, compatibility.md"# Re-sign: codesign seals Contents/Resources at sign time, so the earlier# bundle-step signature (made before these assets existed) is now stale —diff --git a/sources/FirmwarePatcher/CFW/Patches/CFWJetsam.swift b/sources/FirmwarePatcher/CFW/Patches/CFWJetsam.swiftindex f8894cdc..9fb29864 100644--- a/sources/FirmwarePatcher/CFW/Patches/CFWJetsam.swift+++ b/sources/FirmwarePatcher/CFW/Patches/CFWJetsam.swift@@ -51,7 +51,7 @@// is a live bug in the reference: rewriting the gate drops it out of the// conditional-branch set, so the Python's backward scan walks past it and// patches the *next* branch into the same return block — a second, wrong site-// on a binary that was already correct (`research/patch_reference_capture.md`,+// on a binary that was already correct (`research/patches/patch_reference_capture.md`,// "The non-idempotency itself is a separate, pre-existing bug"). The fix has to// live inside the scan, because on a re-run neither implementation picks the// site it patched before. So the scan collects unconditional `b`s into a returndiff --git a/sources/VPhoneArchive/VPhoneArchiveWriter.swift b/sources/VPhoneArchive/VPhoneArchiveWriter.swiftindex ce153f8f..6a5a9cdc 100644--- a/sources/VPhoneArchive/VPhoneArchiveWriter.swift+++ b/sources/VPhoneArchive/VPhoneArchiveWriter.swift@@ -64,7 +64,7 @@ public enum VPhoneArchiveWriter {// is worth about 4.8x -- but only above one xz block, roughly// 192 MiB at level 9. A smaller archive gets no benefit, and that// is arithmetic rather than a fault. See- // research/libarchive_xcframework_validation.md.+ // research/host/libarchive_xcframework_validation.md.try setFilterOption(writer, "xz", "threads", "0")case let .gzip(level):archive_write_add_filter_gzip(writer)diff --git a/sources/VPhoneCore/VPhoneFirmwareMatrix.swift b/sources/VPhoneCore/VPhoneFirmwareMatrix.swiftindex 0dd6ca92..cb753d34 100644--- a/sources/VPhoneCore/VPhoneFirmwareMatrix.swift+++ b/sources/VPhoneCore/VPhoneFirmwareMatrix.swift@@ -4,7 +4,7 @@ import Foundation/// How much confidence this project has in one downloadable iPhone firmware.///-/// `supported` means the README's "Tested Environments" table records a boot on+/// `supported` means the compatibility guide's "Tested Environments" table records a boot on/// that exact version/build; `notTested` means Apple still serves it but nobody/// wrote a row for it. `unsupported` is never a table verdict — it is the/// prefix the selector puts on "nothing matched", and it exists here only@@ -90,7 +90,7 @@ public struct VPhoneFirmwareRelease: Sendable, Hashable {// MARK: - VPhoneFirmwareBuildID-/// The (version, build) pair the README table and the URL list are joined on.+/// The (version, build) pair the compatibility table and the URL list are joined on.public struct VPhoneFirmwareBuildID: Sendable, Hashable {public let version: Stringpublic let build: String@@ -138,25 +138,25 @@ public enum VPhoneFirmwareSelection: Sendable, Equatable {// MARK: - VPhoneFirmwareMatrix-/// The firmware support matrix: the README's "Tested Environments" table joined+/// The firmware support matrix: the compatibility guide's "Tested Environments" table joined/// against the restore images Apple still serves.////// This replaces the two Python heredocs that used to live inside/// `scripts/fw_prepare.sh` (`list_firmwares` and `resolve_selector_from_downloads`).-/// They were 166 lines that duplicated the same three parsers — the README+/// They were 166 lines that duplicated the same three parsers — the Markdown/// section scan, the URL scan, and the version sort — once each, so this is one/// parser with two renderers on top of it.public enum VPhoneFirmwareMatrix {// MARK: Parsing- /// Every `(version, build)` the README's "Tested Environments" section+ /// Every `(version, build)` the compatibility guide's "Tested Environments" section/// records for `device`.////// The section runs from the `## Tested Environments` heading to the next/// `## ` heading. Inside it, any backticked `17,3_26.1_23B85` cell whose/// device part equals `device` minus its `iPhone` prefix counts as tested;/// the cloudOS column uses `26.1-23B85`, which cannot match. A missing- /// README is not an error — it just means nothing is known to be tested.+ /// guide is not an error — it just means nothing is known to be tested.public static func testedBuilds(readme: String?, device: String) -> Set<VPhoneFirmwareBuildID> {guard let readme else { return [] }let deviceSuffix = device.hasPrefix("iPhone")@@ -213,7 +213,7 @@ public enum VPhoneFirmwareMatrix {return found}- /// The verdict for one release, given what the README records.+ /// The verdict for one release, given what the compatibility guide records.public static func support(of release: VPhoneFirmwareRelease,tested: Set<VPhoneFirmwareBuildID>diff --git a/sources/VPhoneCore/VPhoneGuestLauncher.swift b/sources/VPhoneCore/VPhoneGuestLauncher.swiftindex d78373fc..1bbc00db 100644--- a/sources/VPhoneCore/VPhoneGuestLauncher.swift+++ b/sources/VPhoneCore/VPhoneGuestLauncher.swift@@ -33,7 +33,8 @@ public enum VPhoneGuestLaunchError: Error, CustomStringConvertible {sudo '\(helper.path)' allow '\(guest.path)'The allowlist is specific to this signature, so repeat after a- rebuild. See "SIP/AMFI Relaxation" in README.md for host settings.+ rebuild. See https://github.com/Lakr233/vphone-cli/blob/main/docs/guides/host-setup.md+ for host settings."""case let .missingEntitlements(guest):diff --git a/sources/vphone-cli/VPhoneFWCLI.swift b/sources/vphone-cli/VPhoneFWCLI.swiftindex 272d262d..336af782 100644--- a/sources/vphone-cli/VPhoneFWCLI.swift+++ b/sources/vphone-cli/VPhoneFWCLI.swift@@ -72,7 +72,7 @@ struct VPhoneFWListCommand: ParsableCommand {)@Option(help: "Device identifier, e.g. iPhone17,3") var device: String- @Option(help: "README.md holding the 'Tested Environments' table") var readme: String+ @Option(help: "Compatibility Markdown holding the 'Tested Environments' table") var readme: Stringfunc run() throws {let code = VPhoneFirmwareMatrixCommandLine.list(@@ -100,7 +100,7 @@ struct VPhoneFWResolveCommand: ParsableCommand {@Option(help: "Device identifier, e.g. iPhone17,3") var device: String@Option(help: "iOS version to match; empty matches any") var version: String = ""@Option(help: "Build to match; empty matches any") var build: String = ""- @Option(help: "README.md holding the 'Tested Environments' table") var readme: String+ @Option(help: "Compatibility Markdown holding the 'Tested Environments' table") var readme: Stringfunc run() throws {let code = VPhoneFirmwareMatrixCommandLine.resolve(@@ -204,7 +204,7 @@ struct VPhoneFWPrepareCommand: ParsableCommand {func run() throws {let resources = projectRoot.map { VPhoneResources(base: URL(fileURLWithPath: $0)) } ?? .resolve()- let readme = resources.base.appendingPathComponent("README.md").path+ let readme = resources.base.appendingPathComponent("docs/guides/compatibility.md").pathlet needsCatalog = list || iphoneVersion != nil || iphoneBuild != nillet urls = if needsCatalog {try vphoneRunBlocking {diff --git a/tests/VPhoneArchiveTests/BundleTransferTests.swift b/tests/VPhoneArchiveTests/BundleTransferTests.swiftindex 8abd2cce..3bfd8b93 100644--- a/tests/VPhoneArchiveTests/BundleTransferTests.swift+++ b/tests/VPhoneArchiveTests/BundleTransferTests.swift@@ -452,7 +452,7 @@ struct BundleTransferTests {////// gzip rather than zstd only so the check does not need a `zstd(1)` on/// PATH — which is the whole point of the migration. The compressor is- /// detected either way; `research/archive_extraction_contracts.md` records+ /// detected either way; `research/host/archive_extraction_contracts.md` records/// the .tzst and .txz runs.@Test func importReadsArchiveWrittenByTheOldTarPipeline() throws {let root = try makeRoot()diff --git a/tests/VPhoneCoreTests/FirmwareMatrixTests.swift b/tests/VPhoneCoreTests/FirmwareMatrixTests.swiftindex 010087a9..8a234801 100644--- a/tests/VPhoneCoreTests/FirmwareMatrixTests.swift+++ b/tests/VPhoneCoreTests/FirmwareMatrixTests.swift@@ -13,7 +13,7 @@//// Colour was compared in three conditions, each running both implementations// through the identical wrapper: a pipe, a real pty via script(1), and NO_COLOR-// set. Those runs also covered the repository's own README.md against a live+// set. Those runs also covered the repository's compatibility guide against a live// `ipsw download ipsw --device iPhone17,3 --urls` capture.//// Trailing spaces are written as `\u{20}` on purpose: the Python padded the@@ -289,14 +289,14 @@ struct FirmwareMatrixParsingTests {#expect(found.first?.url == Fixture.url263)}- @Test func parsesTheRepositoryReadme() throws {+ @Test func parsesTheRepositoryCompatibilityGuide() throws {let tested = VPhoneFirmwareMatrix.testedBuilds(- readme: try RealData.repositoryReadme(),+ readme: try RealData.repositoryCompatibilityGuide(),device: Fixture.d)- // The live table is edited often, so this asserts the shape, not a count.- #expect(tested.count >= 15)- #expect(tested.contains(VPhoneFirmwareBuildID(version: "26.1", build: "23B85")))+ #expect(tested.count == 2)+ #expect(tested.contains(VPhoneFirmwareBuildID(version: "26.6.2", build: "23G90")))+ #expect(tested.contains(VPhoneFirmwareBuildID(version: "27.0", build: "24A435")))#expect(tested.allSatisfy { !$0.version.isEmpty && !$0.build.isEmpty })#expect(tested.allSatisfy { !$0.version.contains("`") && !$0.build.contains("`") })}@@ -304,22 +304,22 @@ struct FirmwareMatrixParsingTests {// MARK: - Real data-/// The repository's own README table joined against a real `ipsw download ipsw+/// The repository's compatibility table joined against a real `ipsw download ipsw/// --device iPhone17,3 --urls` capture — the two inputs the shell actually fed/// the Python, rather than anything shaped to suit the parser.///-/// The README is read live, so these assert invariants rather than a golden: a+/// The guide is read live, so these assert invariants rather than a golden: a/// row added to the table must not turn the suite red for the agent who added/// it. The cross-check is against a second parser written here on purpose in a/// different style — column splitting instead of a regex — so a regex that/// drifts has something independent to disagree with.private enum RealData {- static func repositoryReadme() throws -> String {+ static func repositoryCompatibilityGuide() throws -> String {let url = URL(fileURLWithPath: #filePath).deletingLastPathComponent().deletingLastPathComponent().deletingLastPathComponent()- .appendingPathComponent("README.md")+ .appendingPathComponent("docs/guides/compatibility.md")return try String(contentsOf: url, encoding: .utf8)}@@ -387,15 +387,15 @@ private enum RealData {}struct FirmwareMatrixRealDataTests {- @Test func theReadmeParserAgreesWithAnIndependentColumnSplitter() throws {- let readme = try RealData.repositoryReadme()+ @Test func theCompatibilityParserAgreesWithAnIndependentColumnSplitter() throws {+ let readme = try RealData.repositoryCompatibilityGuide()let byRegex = VPhoneFirmwareMatrix.testedBuilds(readme: readme, device: Fixture.d)let bySplitting = RealData.testedBuildsByColumnSplitting(in: readme, deviceSuffix: "17,3")- #expect(!bySplitting.isEmpty, "the README table moved — fix the test, not the parser")+ #expect(!bySplitting.isEmpty, "the compatibility table moved — fix the test, not the parser")#expect(byRegex == bySplitting)}- @Test func aLiveDownloadCaptureParsesWholeAndJoinsAgainstTheReadme() throws {+ @Test func aLiveDownloadCaptureParsesWholeAndJoinsAgainstTheGuide() throws {let releases = VPhoneFirmwareMatrix.releases(downloadURLs: RealData.liveURLs,device: Fixture.d@@ -407,7 +407,7 @@ struct FirmwareMatrixRealDataTests {#expect(releases.count == 31)#expect(Set(releases.map(\.build)).count == 31)- let tested = VPhoneFirmwareMatrix.testedBuilds(readme: try RealData.repositoryReadme(), device: Fixture.d)+ let tested = VPhoneFirmwareMatrix.testedBuilds(readme: try RealData.repositoryCompatibilityGuide(), device: Fixture.d)var supported = 0, notTested = 0for release in releases {let id = VPhoneFirmwareBuildID(version: release.version, build: release.build)