Add iPhone17,3 iOS 27.0 beta 8 (24A5430a) paired with cloudOS 26.4 to the
firmware catalog so it appears in the `fw prepare` picker, `fw catalog`,
and the `--json` report. Document it in the Tested Environments table
across README.md and the ja/ko/zh translations. Bump the hardcoded
pairing/menu count in FirmwarePickerTests 22 -> 23.
Co-Authored-By: Claude Fable 5 <[email protected]>
Add iPhone17,3 iOS 27.0 beta 7 (24A5424a) paired with cloudOS 26.4 to the
firmware catalog so it appears in the `fw prepare` picker, `fw catalog`,
and the `--json` report. Document it in the Tested Environments table
across README.md and the ja/ko/zh translations. Bump the hardcoded
pairing/menu count in FirmwarePickerTests 21 -> 22.
Co-Authored-By: Claude Fable 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01Ej64m761KR33KaNYh3BuTo
The bundled 26.6.1 IPSW pointed at the 23G82 release candidate, which
differs from the shipped release. Point it at the 23G83 final restore
and update the tested-environment tables accordingly.
Co-Authored-By: Claude Opus 4.8 <[email protected]>
Add iPhone17,3 iOS 27.0 beta 6 (24A5418b) paired with cloudOS 26.4 to the
firmware catalog so it appears in the `fw prepare` picker, `fw catalog`,
and the `--json` report. Document it in the Tested Environments table
across README.md and the ja/ko/zh translations. Bump the hardcoded
pairing/menu count in FirmwarePickerTests 20 -> 21.
Co-Authored-By: Claude Fable 5 <[email protected]>
Add iPhone17,3 iOS 26.6.1 (23G82) paired with cloudOS 26.4 to the
firmware catalog so it appears in the `fw prepare` picker, `fw catalog`,
and the `--json` report. Document it in the Tested Environments table
across README.md and the ja/ko/zh translations. Bump the hardcoded
pairing/menu count in FirmwarePickerTests 19 -> 20.
Co-Authored-By: Claude Fable 5 <[email protected]>
Export/import UX overhaul, wiring in the counting-pipe and progress-bar
primitives:
- Compression: replace `--compress {fast,balanced,max}` with a fast
(zstd -3) default and a single `--max` (xz -9) flag; drop balanced.
- `vm export --out DIR`: when the destination is an existing directory,
auto-name the archive `<vm>.tzst`/`.txz` and print the resolved path.
- `vm import ARCHIVE`: take the archive as a positional argument instead
of `--in`.
- Progress bars: export runs a two-stage tar pipeline (uncompressed
gnutar producer -> compressing consumer via bsdtar `@-`) so the bar is
driven off the known uncompressed total; import extracts once (was
decompressing twice) and counts the archive as it is fed into `tar -x`.
gnutar avoids the pax-header `@-` mtree misbid on large members and,
unlike ustar, carries files >8 GB.
Import validates the single top-level bundle after extracting into a
private staging dir, still failing fast on an explicit --name collision.
Tests: default is fast zstd; --max is xz; directory auto-naming yields
the right extensions; export/import invoke progress with monotonic,
correctly-totalled callbacks.
Co-Authored-By: Claude Fable 5 <[email protected]>
Two building blocks for streaming progress on vm export/import, unused
until the export/import rework wires them in:
- VPhoneProcessRunner.runCountingTarPipe: drives a /usr/bin/tar consumer
that reads its archive on stdin, invoking a callback with the running
byte total. The source is either a producer tar (export) or a file read
directly (import). SIGPIPE is ignored so a consumer that dies early
surfaces as its exit status instead of killing this process.
- VPhoneProgressBar: a single-line redrawing byte bar that renders to
stderr only when it is a TTY, so piped/--json/GUI-subprocess runs stay
clean and it simply no-ops.
Co-Authored-By: Claude Fable 5 <[email protected]>
Export previously hardcoded xz -9 (the densest but slowest libarchive
compressor), forcing a multi-GB Disk.img through the most aggressive
setting on every export.
Add a `--compress {fast,balanced,max}` preset on `vphone vm export`,
default `balanced`:
fast zstd -3
balanced zstd -19 (new default)
max xz -9 (previous behavior)
All presets go through the same system /usr/bin/tar (libarchive) already
used for xz, so no new dependency and no raised platform floor. Import is
unchanged: it already auto-detects the compressor via `tar -tf`/`-xf`, so
zstd and xz archives both import.
Tests assert each preset's magic bytes (zstd vs xz), that fast/max
round-trip, and the default is zstd. README examples updated.
Co-Authored-By: Claude Fable 5 <[email protected]>
Expose --frida on patch-firmware, patch-component, fw patch, and vm create
(plus `make fw_patch_jb/exp FRIDA=1`), threading it into
KernelJBPatcher.applyFrida via FirmwarePipeline.
The kernel patches apply only when the cloudOS kernel is 26.4+ (the versions
where the shapes were validated); older kernels are left untouched. Baseline
JB/EXP output is byte-identical without --frida (26.4 emits 83 records, 87 with).
Co-Authored-By: Claude Fable 5 <[email protected]>
Two narrowly-scoped patches, emitted only under the Frida opt-in:
- thread_set_state: clear TSSF_CHECK_ENTITLEMENT in the thread_set_state user
setters (mov w6,#0x201 -> #0x1) so Frida can follow an existing thread without
a GUARD_TYPE_MACH_PORT kill, while preserving TSSF_TRANSLATE_TO_USER and the
TH_IN_MACH_EXCEPTION guard.
- vm_map_delete: retarget the immutable-code exception from current-protection
execute (bit 9) to max-protection execute (bit 13) so a debugger-created
RW/max-RWX permanent mapping survives repeated VM_PROT_COPY re-instrumentation
instead of returning KERN_PROTECTION_FAILURE.
Both matchers are semantic (entitlement-string / developer-mode / call-flow
anchored, no hardcoded offsets/VAs/registers/bytes) and fail closed; replacement
bytes come from ARM64Encoder and are Capstone-verified.
Co-Authored-By: Claude Fable 5 <[email protected]>
Add the iPhone17,3 27.0 24A5408d + cloudOS 26.4 pairing to the firmware
catalog so it is selectable in `fw prepare` / `vm create`, and bump the two
hardcoded pairing counts in the picker tests (18 -> 19).
Co-Authored-By: Claude Opus 4.8 <[email protected]>
Claude-Session: https://claude.ai/code/session_01N2bwKrGJWY7o2ArdxibVPe
The unified tool provisions ~/.vphone/venv itself and never runs
setup_venv.sh, so it lost that script's libkeystone handling. It
pip-installs and then verifies with pythonIsUsable, which only probes
ipsw_parser — a venv with keystone bindings and no native library
passes, gets cached as good, and fails much later inside fw patch.
That state is reachable and silent. PyPI has no arm64 macOS wheel
(only macosx_10_14_x86_64), so pip builds keystone-engine from its
sdist, and the sdist's darwin path ignores the build's exit status
(subprocess.call plus a glob that matches nothing) — a failed native
build still installs bindings alone and pip reports success.
Probe that keystone can assemble rather than merely import, and on
failure install a loadable dylib next to the bindings: copy one from
Homebrew if the bottle ships it, else link one from libkeystone.a,
matching setup_venv.sh. The managed venv is repaired in place before
being rebuilt, since a missing dylib is not worth a full re-install.
Verified: repairs a venv whose dylibs were removed, and recovers a
fresh bootstrap that produced bindings-only (pip cache cleared, cmake
off PATH) — pip exits 0, the guard catches it, the venv is accepted.
Co-Authored-By: Claude Fable 5 <[email protected]>
`do shell script … with administrator privileges` runs the command under a
helper process that inherits none of our fds, so AppleScript can only hand
back its output once the command has EXITED — and it rewrites every \n to
\r on the way, which a reader applying terminal semantics (the GUI's log
view) takes for progress-bar overwrites, keeping only the final line. The
CFW install stage therefore sat silent for minutes and then showed one line.
Name our own terminal in the command instead: ttyname(stdout) is an absolute
device path the privileged shell can open, and under the GUI it is already
the pty the app is reading. Output then arrives as produced, with newlines
intact, on a tty the script's children line-buffer to. Gated on `echo` so
quiet verbosity still suppresses it, and skipped when stdout is not a tty.
Co-Authored-By: Claude Fable 5 <[email protected]>
The fw prepare step sent the script's entire stdout/stderr to
/dev/null unless -v was passed, so the aria2c/curl/wget progress bar
was discarded with it. That left the longest phase of the pipeline —
a multi-GB IPSW download — printing nothing for minutes, which reads
as a hang.
Stream it unconditionally. Standalone `fw prepare` already does this
by flooring its verbosity at .info; this brings `vm create` in line.
The script itself is status-line based (~40 echoes, unzip -oq, no
per-file loops), so this adds progress rather than noise.
Co-Authored-By: Claude Fable 5 <[email protected]>
Boots without a VM window or menu bar. The guest keeps its display
device, so the boot chain is unchanged — only the AppKit window, menu
bar and Dock presence are skipped.
Available on `boot` and `vm launch`. `vm create` now uses it for both
setup boots (first boot and boot analysis); --interactive keeps the
window, since it asks the operator to press Enter once the VM has
booted and the window is their only progress cue.
Note: the vphone.sock host control socket does not start in headless
mode — its handler needs the VZVirtualMachineView capture view.
Co-Authored-By: Claude Fable 5 <[email protected]>
`vm create` built the orchestrator Options without setting diskSizeGB, so
the disk was pinned to the 64 GB default no matter what. The downstream
plumbing (Options.diskSizeGB -> NewBundleSpec -> sparse Disk.img truncate)
already existed; this just exposes `-d/--disk-size` on the command and
threads it through, matching the existing `vm new` convention.
Co-Authored-By: Claude Fable 5 <[email protected]>
Show the known iOS ↔ cloudOS firmware pairings, one recommended cloudOS
per iOS build, projected from VPhoneFirmwareCatalog.pairings. Human
output is an aligned table; `--json`/`-j` emits an object carrying the
device plus each pairing's download URLs.
Co-Authored-By: Claude Fable 5 <[email protected]>
`vm info --json` and `vm list --json` encode VPhoneBundleReport, which
carried no network field — so the network mode was absent from JSON even
though the human-readable output prints `net:`. Consumers parsing JSON had
no way to read a VM's network config.
Project the manifest's NetworkConfig into VPhoneBundleReport as `network`,
so both `info` and `list` emit it as structured JSON (mode, macAddress,
bridgeInterface). NetworkConfig gains Equatable (VPhoneBundleReport is
Equatable). The text `net:` line now reads from the same report projection.
Co-Authored-By: Claude Fable 5 <[email protected]>
`vm info` now reports the CFW variant the VM was last restored to, its
predicted UDID, and the product type the guest identifies as.
- udid: read from the bundle's udid-prediction.txt (VPhoneRestoreOps.resolveUDID)
- variant + device: recorded into restore-info.json at CFW-install time, in
both the standalone `cfw install` and the `vm create` orchestrator. device is
iPhone99,11 for every variant except exp, whose DeviceTree rewrite -> iPhone17,3.
- both new restore-info.json fields are optional, so pre-existing bundles decode
unchanged and pick up variant/device on their next install.
Co-Authored-By: Claude Fable 5 <[email protected]>
Adds `--network nat|bridged|none` and `--bridge-interface` to `vm config`,
and wires the boot path to honor the stored networkConfig (it previously
hardcoded NAT and ignored the manifest). `vm info` now shows the mode.
- New VPhoneNetworking: validates the mode, resolves/auto-picks the bridge
interface, and builds the VZ network device — shared by config-time
editing and boot.
- bridged uses VZBridgedNetworkDeviceAttachment (com.apple.vm.networking
entitlement already present); hostOnly is rejected (no native VZ
attachment); none yields no NIC.
- Rename NetworkMode.none -> .off (raw value kept "none") so a NetworkMode?
literal `.none` can't silently bind to Optional.none.
The MAC is left framework-assigned; forcing a custom MAC breaks guest
networking, so no MAC override is exposed.
Co-Authored-By: Claude Fable 5 <[email protected]>
* feat: add --root-popup to elevate CFW host-mount via macOS auth dialog
Adds --root-popup to `cfw install` and `vm create`, elevating the CFW host-mount through macOS's native authentication dialog (osascript -> do shell script with administrator privileges) instead of the script's sudo re-exec. do shell script runs under a bare env, so the vars the bundled scripts read are forwarded inline, plus SUDO_USER so the script's chown-back still returns artifacts to the invoking user. On `vm create`, --sudo-password takes precedence.
Co-Authored-By: Claude Opus 4.8 <[email protected]>
* cfw: remove entire .cfw_temp on install cleanup
Replaces the selective `rm -f` of individual temp binaries with `rm -rf "$TEMP_DIR"`, dropping the cached Cryptex DMGs along with the temp files.
Co-Authored-By: Claude Opus 4.8 <[email protected]>
---------
Co-authored-by: Claude Opus 4.8 <[email protected]>
Delete the three large regenerable intermediates once their consumers
finish, keeping the source archives so nothing needs re-downloading:
- built restore firmware (iPhone*_Restore/) after CFW install (its last
consumer — it copies the SystemOS/AppOS cryptexes onto Disk.img)
- extracted base-IPSW dirs (iOS + cloudOS) at end of fw prepare; the
downloaded .ipsw files are kept, so a re-run re-extracts, no re-download
- extracted CFW input dirs (cfw_input/, cfw_jb_input/) after cfw install;
the resources .tar.zst archives are kept
Opt out with --keep-artifacts on `vm create` / `cfw install`, which
threads VPHONE_KEEP_ARTIFACTS to fw_prepare.sh and cfw_install_host.sh.
Co-authored-by: Claude Fable 5 <[email protected]>
Snapshot the restored iOS userland and cloudOS kernel versions to
restore-info.json at the bundle root so they are readable without booting
the VM, rewritten after every successful restore (vm create and vm restore).
Versions are read host-side from the bundle's iPhone*_Restore plists
(iPhone-BuildManifest.plist for iOS, the hybrid BuildManifest.plist for
cloudOS). vm list / vm info / --json surface them; the file lives at the
bundle root so vm export carries it even when the IPSW dir is excluded.
Co-authored-by: Claude Fable 5 <[email protected]>
`vm create` on an interactive terminal now prompts for whichever firmware
component wasn't passed on the command line, choosing from a known-good
iPhone/cloudOS catalog by friendly name (e.g. "iOS 26.4", "cloudOS 26.4")
rather than raw URLs. Supply one of --iphone-source/--cloudos-source and
only the other is asked for; supply neither and a full pairing is chosen.
Non-interactive runs (or both flags set) pass through unchanged, so
fw_prepare's defaults still fill any gap and scripted use is unaffected.
- VPhoneFirmwareCatalog: 18 iPhone17,3 pairings + 4 distinct cloudOS images.
- VPhoneFirmwarePicker: pure, injectable-I/O resolver (13 unit tests).
- VPhoneFirmwareSelection: TTY adapter (isatty + readLine → stderr prompts).
- Wired into `vm create` before the orchestrator runs; READMEs (+ ja/ko/zh)
document the prompt behavior.
Co-Authored-By: Claude Opus 4.8 <[email protected]>
Claude-Session: https://claude.ai/code/session_01Y4VDqWf5pVakcFLqB23CKe
A whole-codebase audit surfaced path bugs that only bite the bundled .app —
especially when brew puts vphone-cli on $PATH via a symlink, so the process
launches by a bare name from an arbitrary CWD:
- HIGH (crash): CommandLine.arguments[0] was used to locate the running binary
and the resource base (VPhoneResources.resolve default, vm launch bootBinary,
vm create selfExe). Under a bare-name PATH launch argv[0] is just
"vphone-cli", which URL(fileURLWithPath:) resolves against the CWD (e.g.
$HOME/vphone-cli) — so `vm launch` errored "not found" and `vm create` couldn't
respawn to boot. Add VPhoneResources.runningExecutable() using
Bundle.main.executableURL (the kernel-provided path, correct regardless of
argv[0]/CWD/symlink) and route all three through it. One helper fixes every
.resolve() consumer.
- MEDIUM (silent): the extra-deb feature resolved its cache + manifest under the
read-only bundle (Resources/debs, Resources/debs.list). Honor VPHONE_DEBS_DIR
(a writable ~/.vphone/debs the app now sets, mirroring IPSW_DIR/VPHONE_SEAL_DIR)
and bundle debs.list.
- LOW (cosmetic): fw_prepare read ../README.md (absent in the bundle → firmwares
labeled "Not Tested"). Bundle README.md.
Verified: Bundle.main.executableURL yields the real binary under a bare-name
symlink launch (argv[0] → $HOME); build clean; 79 VPhoneCore tests pass.
boot_host_preflight.sh hardcoded RELEASE_BIN=$PROJECT_ROOT/.build/release/
vphone-cli. Inside the bundled .app, PROJECT_ROOT resolves to Contents/
Resources, so it looked for Contents/Resources/.build/release/vphone-cli —
which doesn't exist (the binary is at Contents/MacOS/vphone-cli). Under
--assert-bootable that made the preflight fail with "missing release binary",
blocking `vm launch` from a brew-installed or copied .app.
`vm launch` now passes the running executable (CommandLine.arguments[0]) to the
preflight via VPHONE_CLI_BIN and the script checks that binary; it still falls
back to the dev .build/release path for standalone/`make` invocation.
Co-Authored-By: Claude Opus 4.8 <[email protected]>
Foundation `Process` starts children in a NEW process group, so a sudo it
spawns is a *background* member of the controlling terminal — it can't disable
echo or read the tty, so the typed password showed and wasn't delivered. No
stdio wiring fixes that (confirmed: a Process child's pgid != the parent's).
Add VPhoneProcessRunner.runForeground: hand the terminal to the child's process
group via tcsetpgrp (SIGTTOU/SIGTTIN ignored during the swap), restore ours
after. The CFW-install step uses it when no --sudo-password is given, so sudo
owns the tty and reads the password DIRECTLY — vphone-cli never sees it. Its
`echo` flag still honors verbosity: quiet suppresses the install's own output
(stdout/stderr → /dev/null) while sudo's /dev/tty prompt keeps working. With
--sudo-password the unattended askpass path is unchanged; a non-interactive run
with no password fails fast.
Verified under a PTY: without tcsetpgrp the child is background (the bug); with
it the child is foreground; and echo=false hides the child's output while it
stays foreground.
Also serialize LibraryTests: its two VPHONE_LIBRARY_ROOT env tests mutate a
process-global and raced under Swift Testing's parallelism (intermittent
failures) — mark the suite @Suite(.serialized).
Co-Authored-By: Claude Opus 4.8 <[email protected]>
Claude-Session: https://claude.ai/code/session_01Y4VDqWf5pVakcFLqB23CKe
- scripts/build.sh builds+signs the binary, bundles a self-contained .app
(mirrors scripts/patchers/resources/tools/vphoned + requirements.txt into
Contents/Resources) and re-signs; the signed guest daemon stages under
.build (not the repo root)
- CryptexFilesystemPatcher resolves assets via VPhoneResources instead of
CWD-relative paths
- Makefile space-safety; .gitignore updates
Co-Authored-By: Claude Opus 4.8 <[email protected]>
Claude-Session: https://claude.ai/code/session_01Y4VDqWf5pVakcFLqB23CKe
Full command surface so create → patch → restore → install → boot → manage all
run through vphone-cli, no make required:
- vm list/info/new/config/rename/delete/clone/export/import, launch/stop
(--kernel-debug-port forwarded to the boot binary)
- native end-to-end `vm create` (VPhoneCreateOrchestrator)
- fw prepare/patch, restore + cfw install
- `setup` to provision the Python env up front (also automatic on first use)
- interactive VM selection when a name is omitted, short option aliases, and
-v/-vv/-vvv verbosity
Wire the subcommands in main.swift/VPhoneCLI.swift; adjust VPhoneControl/
VPhoneError/VPhoneVirtualMachine for the config-driven boot path.
Co-Authored-By: Claude Opus 4.8 <[email protected]>
Claude-Session: https://claude.ai/code/session_01Y4VDqWf5pVakcFLqB23CKe
The library the consolidated CLI is built on:
- bundle/library model (VPhoneBundle, VPhoneLibrary, VPhoneVirtualMachineManifest),
bundle ops + reporting, restore helpers (VPhoneRestoreOps)
- host process primitives: VPhoneProcessRunner, VPhoneManagedProcess (spawn +
stdout pattern-match + SIGKILL-escalating terminate), VPhoneLaunchLayout,
VPhoneBootPatterns
- VPhoneResources: bundled-.app vs dev asset resolution, and Python resolution
that provisions a per-user venv (~/.vphone/venv) on demand so the app is
portable — never depends on the repo's .venv
- VPhoneVerbosity (quiet/info/debug/trace) and VPhoneVMPicker
Manifest moves out of the executable target into VPhoneCore. Full unit-test
suite under tests/VPhoneCoreTests.
Co-Authored-By: Claude Opus 4.8 <[email protected]>
Claude-Session: https://claude.ai/code/session_01Y4VDqWf5pVakcFLqB23CKe
* fix AVPBooter DGST patch: restrict search to movz/movk instructions
The DGST constant search matched any instruction string containing
"0x4447", including branch targets like `bl #0x4447c`. On macOS 27
beta 3+ firmware, such a branch appeared before the real DGST movk,
causing a false match and subsequent "x0 setter not found" failure.
Restrict the search to movz/movk/mov mnemonics only, which are the
actual constant-loading instructions.
Fixes#373
* fix iBSS JB nonce patch: use tolerance-based ADRP+ADD search
findRefsToOffset required exact match between ADRP+ADD computed address
and the "boot-nonce" string file offset. On macOS 27 beta 3 firmware,
code references a structure header 2 bytes before the string, causing
the exact match to fail.
Add findRefsNear() which allows up to 16 bytes of negative delta,
matching references to the containing structure rather than the string
itself. This makes the patch resilient to minor layout changes across
firmware versions.
On 26.x bases the EXC_GUARD (Mach port guard) disable patch is not required
to boot, so it is no longer applied unconditionally on regular/jb/exp.
Production apps shipping crash-reporting/RASP SDKs (Bugly, Crashlytics,
KSCrash) call task_swap_exception_ports(), which the research kernel enforces
as a fatal GUARD_TYPE_MACH_PORT violation on launch; a --force-exc-guard flag
(FORCE_EXC_GUARD=1 in the Makefile) re-enables the patch for those cases.
iOS 18 bases and the dev variant keep the patch always-on, since both need it
to boot. The documented violation is corrected from SET_EXCEPTION_BEHAVIOR to
KOBJECT_REPLY_PORT_SEMANTICS, matching the actual reproduction crash logs.
Also add /vm-*/ to .gitignore for multi-VM directories.
Co-authored-by: Paulo Sarrin <[email protected]>
Co-authored-by: zqxwce <[email protected]>
Co-Authored-By: Claude Fable 5 <[email protected]>
The JB blanket-neuters Sandbox mpo_vnode_check_open (ops[267] -> allow) so
processes can read /var/jb. FileProvider's fpfs parent-walk relies on the stock
check's EACCES at the domain-container boundary as its terminus; with it
neutered the walk climbs unbounded and ResolverService balloons (~12 GB) ->
vm-compressor-space-shortage jetsam -> backboardd killed -> respring
(27b4/24A5390f).
Keep the global bypass, enforce the real check for the FileProvider daemons
only. On iOS 27, ops[267] is left un-neutered (removed from the JB-09 blanket
list) and retargeted to a code-cave trampoline: inline current_proc
(tpidr_el1 -> uthread+0x3F0 -> proc+0x18), read p_comm (+0x56C), and for
ResolverService/fileproviderd branch to the real vnode_check_open, else return
allow. Register-only, no frame/call. Gated to a 27.x base via applyIOS27; other
bases keep the blanket neuter.
Verified: cave disasm + branch targets correct (final b -> real
vnode_check_open); 26.5 kernelcache byte-identical pre-vs-post (ops[267] stays
neutered there). Documented as JB-29 in research/0_binary_patch_comparison.md.
Co-Authored-By: Claude Opus 4.8 <[email protected]>
Claude-Session: https://claude.ai/code/session_01YNySXhjsxhFG9yZMBHJUqY
Productionize the 3-part fix that makes `pymobiledevice3 mounter auto-mount`
land the personalized DDI at /System/Developer on the iOS-27-userland /
26.4-vphone600-kernel (c0ecdb4b) JB hybrid.
- KernelJBPatchDiskImages2.swift (new; wired into KernelJBPatcher.findAll):
DiskImages2 ABI acceptance. GATE1/GATE2b NOP the CreateDevice/Connect
cmp#9/b.ne ABI-version rejects (kernel driver v9 vs iOS-27 controller/daemon
v11). GATE2 widens the RegisterNotificationPort backing array + both
bound-check field loads (all-or-nothing) to clear the `type < getMaxPorts`
off-by-one that otherwise fails the attach ("Can't register notification
port").
- KernelJBPatchSandboxExtended: retarget mac_policy_ops[124]
(mpo_proc_check_syscall_unix) to the allow stub so MobileStorageMounter's
mount_apfs can make the mount(2) syscall (unix 167) — else the kernel
Sandbox denies it ("Protobox: mount_apfs deny(1) syscall-unix 167").
- cfw_patch_diskimagesiod.py + cfw.py + cfw_install.sh (gated to 27.*):
force -[DIDiskArb isMountCompleteWithExpectedCount:diskTracker:] -> YES so
MobileStorageMounter's waitForDAMount returns and it performs the real
nobrowse mount.
GATE2a anchor fix (the critical one): Capstone on this toolchain decodes the
AllocPortsArray size-shift lsl-immediate (a UBFM alias) as 2 operands, not the
xd,xn,#imm 3-operand shape. The original 3-operand + imm==3 match found 0, so
the all-or-nothing silently skipped GATE2 on every build (only manual dd pokes
ever worked). Now matched on mnemonic + destination x1 — the unique
size-writing lsl in AllocPortsArray; the replacement is a fixed mov x1,#0x4000
so the shift amount is irrelevant. Verified from a clean build on c0ecdb4b via
`patch-component --component kernel-jb --records-out`: all five di2 records
emit (createdevice, connect, allocports_size, notif_boundcheck_d8/e8), and
`pmd3 mounter auto-mount` -> rc=0 with the DDI mounted, no poke.
Documented in research/0_binary_patch_comparison.md (JB-09, JB-28, CFW
binary-patch #13).
Co-Authored-By: Claude Opus 4.8 <[email protected]>
Claude-Session: https://claude.ai/code/session_013pk5tsoBeuu3jhkmnRFtic
The 26.4 vphone600 kernel resolves each process's containers at exec via a
synchronous MIG upcall to containermanagerd over the container-manager host
special port (HOST_CONTAINERD_PORT). iOS 27 DELETED this kernel-side upcall (the
stock 27 kernel has no HOST_CONTAINERD_PORT / CM_KERN_* protocol — container
resolution moved out of the kernel), so 27's containermanagerd no longer
implements the reply server. On the 26.4 kernel running a 27.0 userland the
upcall therefore fails (MACH_SEND_INVALID_DEST) for every platform app -> they
are autoboxed into the restrictive `temporary-sandbox` profile, which denies
mach-lookup com.apple.backboard.display.services -> Campo (the wallpaper
renderer) crash-loops (no wallpaper), plus intelligencetasksd / feedbackd.
Re-registering the host special port is a confirmed dead end: the 26.4 kernel
then SENDS the MIG request and BLOCKS for a reply 27 cannot produce -> early-boot
deadlock (SpringBoard never comes up).
Fix (patchContainerManagerUpcall): flip the `cbz w0,<success>` guard in
_hook_cred_label_update_execve (taken when the upcall returns 0) to an
unconditional `b <success>`, so a failed upcall takes the success path instead
of autobox/kill. Anchored structurally on the "failed to upcall to
containermanagerd" string xref (-> the cbz immediately before the string-load
adrp, preceded by the upcall bl, unique backward branch); replacement b from the
Keystone-backed ARM64Encoder. No-op-in-effect for version-matched userlands
(there the upcall succeeds, so the original cbz already branches to <success>).
- new: sources/FirmwarePatcher/Kernel/JBPatches/KernelJBPatchContainerUpcall.swift
- KernelJBPatcher.findAll: call patchContainerManagerUpcall after
patchExecSecurityPolicyKill
- cfw_install.sh: document the port-25 launchd-cache approach as a dead end
(no active code)
- research/0_binary_patch_comparison.md: add row JB-02d
Validated on-device (iPhone17,3 27.0 24A5380h + cloudOS 26.4 c0ecdb4b, JB):
iOS 27 wallpaper renders, Campo/SpringBoard/backboardd stable, clean boot (no
freeze, no panic). Patcher-level (patch-component --component kernel-jb on the
pristine 26.4 kernelcache): finds 0x1AB0654 cbz w0 -> b 0x1ab0564, emits record
container_manager_upcall_force_success, byte-identical to the on-device-validated
host-poke.
Co-Authored-By: Claude Opus 4.8 <[email protected]>
Claude-Session: https://claude.ai/code/session_013pk5tsoBeuu3jhkmnRFtic
iOS 27 userland on the 26.4 vphone600 kernel booted with a working GUI over the
in-guest TrollVNC capturer, but the normal vphone-cli window (the host VZ view)
stayed black. Root cause, proven at the instruction level in the 27.0 DSC
IOMobileFramebuffer: the host VZVirtualMachineView is fed by the guest
AppleParavirtGPU scanout, which the 26.4 kernel drives ONLY from the IOMFB
userclient SwapEnd (external method 5) -- the `_kern_Swap*` path that 26.x used
(and that the SwapEnd size patch fixed on 26.0/18.x). iOS 27 defaults the
paravirt display's present to IOMFB's parallel `_virt_Swap*` path: `_virt_SwapEnd`
performs no userclient call -- it invokes an in-process callback and hands the
composited IOSurface to a virtual-display consumer -- so frames never enter the
kernel userclient and the paravirt GPU never scans out (live AppleParavirtGPU
scheduler sat idle). TrollVNC still saw frames because it captures the composited
surface in-guest, independent of the paravirt scanout.
Fix = force the display's present back onto the kern/method-5 path, in two halves:
Userland (DSC), new patcher cfw_patch_iomfb_force_kern.py (cfw.py +
cfw_install.sh, 27-gated): the public `_IOMobileFramebufferSwap*` entrypoints are
thin dispatch trampolines (`cbz x0; ldr xN,[x0,#slot]; cbz xN; braaz xN`) that
tail-call a per-connection swap fp (kern or virt impl). Rewrite each trampoline's
first instruction to `b _kern_Swap<Name>` -- args untouched, so this is
behaviourally identical to the connection having selected the kern fp. Fully
dynamic: public + `_kern_` addrs resolved by name via `ipsw dyld symaddr`,
trampoline shape verified by Capstone, branch bytes from the Keystone `asm_at()`
helper, modified DSC code pages re-attested. Runtime: 31 entrypoints retargeted,
4 non-trampoline setters left on virt, required {SwapBegin,SwapEnd,SwapSetLayer}
present.
Kernel (KernelJBPatchIomfbSwap, re-enabled in KernelJBPatcher.findAll): iOS 27's
native SwapEnd struct is 0x6e0 bytes (26.x sent 0x588) and the 26.4 userclient
exact-checks 0x588 in two places, so method 5 would return kIOReturnBadArgument.
patchIomfbSwapEndVariableSize flips the dispatch-table checkStructureInputSize
0x588 -> kIOUCVariableStructureSize; patchIomfbSwapEndHandlerSize retargets the
handler's internal `cmp w2,#0x588` -> #0x6e0. 27's IOMFBSwapRec prefix matches
26.x, so the paravirt swap handler reads valid fields. patchParavirtDisplayPrimary
stays disabled (wrong theory, harmful -- see JB-02c).
Validated on-device (17,3_27.0_24A5380h + cloudOS 26.4 c0ecdb4b, JB): clean boot,
no kIOReturnBadArgument / SwapEnd rejection / SECURITY_POLICY kill / panic, and
the iOS 27 userland now renders AND is interactive in the native VZ view.
research/0_binary_patch_comparison.md: DSC-patch item 9 corrected (27 no longer
size-truncated), new item 11 (force-kern), JB-26/27 rows added, all marked
validated.
Co-Authored-By: Claude Opus 4.8 <[email protected]>
Claude-Session: https://claude.ai/code/session_013pk5tsoBeuu3jhkmnRFtic
iOS 27 userland on the 26.4 vphone600 kernel had SpringBoard crash-looping
with no display. Root cause: the IOKit user-client open path runs TWO
independent MAC gates -- a MACF-aggregator check (already patched by
patchIoucFailedMacf) and a separate Sandbox check -- and the Sandbox gate
spuriously DENIES the render server (backboardd) its opens of
IOMobileFramebufferUserClient / IOSurfaceRootUserClient / IOHIDEventService.
27-specific: absent on a native 26.4 userland. Denied the framebuffer,
backboardd can't present (no Apple logo) and vends no main display, so
FBSDisplayMonitor asserts on a nil mainDisplay -> crash-loop.
Add patchIoucFailedSandbox (KernelJBPatchIoucSandbox.swift), mirroring
patchIoucFailedMacf: anchor on the "IOUC %s failed sandbox in process %s"
string, find the deny block (the CBNZ target enclosing the fail-log ADRP),
and rewrite its first instruction with an unconditional B to the
NotPermitted allow-proceed target. Structural anchors only, no hardcoded
offsets. No-op where the gate already allows (native 26.x userlands).
Verified: backboardd opens the framebuffer, SpringBoard runs (0 crashes),
display enumerates (LCD/primary), [CADisplay mainDisplay] resolves, and the
guest GUI renders (confirmed visible over VNC).
Disable three earlier wrong-theory display patches (kept in-tree, off in
findAll, for the record):
- patchParavirtDisplayPrimary: setting primary=1 is actively HARMFUL on 27
-- it becomes the display NAME suffix ("primary-1") and breaks the render
server's exact-name match.
- patchIomfbSwapEnd{VariableSize,HandlerSize}: iOS 27 never uses IOMFB
method 5 (SwapEnd) for present -- confirmed by kernel trace of the real
handler (cmp w2,#0x588) with SpringBoard actively presenting -- so these
are irrelevant on 27 and would break 26.x's native 0x588 SwapEnd.
SwapEnd userland DSC size patch made per-base (cfw_install*, cfw.py,
cfw_patch_iomfb_swapend.py): 26.x validated, harmless on 27.
research/0_binary_patch_comparison.md updated (JB-10b added for the sandbox
gate; JB-02c corrected to disabled/wrong-theory).
Still open: the normal (VZ) render path stays black even though the guest
presents (VNC works) -- 27 uses a present mechanism the 26.4 paravirt-GPU
path doesn't receive. Tracked separately for follow-up.
Co-Authored-By: Claude Opus 4.8 <[email protected]>
Running iOS 27.0 userland on the 26.4 vphone600 kernel, every core platform
daemon (backboardd, cfprefsd, containermanagerd, locationd, CommCenter, ...)
died 3-5ms after xpcproxy spawn with exit reason namespace 9 / code 0x8
(OS_REASON_EXEC / EXEC_EXIT_REASON_SECURITY_POLICY). launchd throttled the
respawns and the boot deadlocked (all CPUs idle) before SpringBoard — no UI,
no networking. Root cause: AMFI's exec MAC hooks reject the 27.0 binaries'
code-sign validation category on the 26.4 kernel, setting imgp->ip_mac_return,
and XNU's exec path (kern_exec.c) SIGKILLs on `if (imgp->ip_mac_return != 0)`.
patch_exec_security_policy_kill flips the `cbz wN, <skip>` guard preceding the
os_reason_create(9,8) call to an unconditional `b <skip>`, making the kill block
unreachable — downstream of AMFI/TXM, so it covers the validation-category
reject regardless of which hook set the verdict. Anchored structurally (movz
w0,#9 ; movz w1,#8 preceded by ldr wN,[xM,#imm] ; cbz wN,<fwd>; W-register cbz
distinguishes the ip_mac_return site from the subsystem-root sibling). No-op in
effect for version-matched userlands (ip_mac_return == 0, so the cbz already
skips). Wired into the JB Group C dispatcher.
Validated on iPhone17,3_27.0_24A5380h + cloudOS 26.4 (c0ecdb4b): 0 SECURITY_POLICY
kills, core daemons launch, networking + SSH (dropbear :22222) come up. Remaining
gate: sandbox denies backboardd the IOMobileFramebuffer/IOSurface user clients,
so SpringBoard traps in FBSDisplayMonitor init (no display) -> UI not up yet.
Co-Authored-By: Claude Opus 4.8 <[email protected]>
Claude-Session: https://claude.ai/code/session_013pk5tsoBeuu3jhkmnRFtic
iOS 18.6.2 userland on the 26.1 vphone600 kernel has no working DNS: the
guest gets a correct resolver config (DHCP hands out 192.168.64.1, which
configd propagates to State:/Network/Global/DNS) and the path works (raw
UDP DNS to the gateway succeeds), but getaddrinfo fails EAI_NONAME because
mDNSResponder crash-loops. Every crash is identical: EXC_BREAKPOINT in
os_channel_create_extended, hit from Network.framework flow setup
(nw_channel_create_with_attributes). That is a skywalk userspace-channel
trap: the 26.1 kernel advertises skywalk, Network.framework tries to create
a flowswitch channel for its DNS flow, the channel-create syscall trips a
fatal trap in the 18.6.2 libsystem_kernel, and the resolver daemon dies.
26.x userland handles this path; 18.6.2 does not.
Fix: set boot-arg if_attach_nx=0x3 (SKYWALK_NETWORKING_BSD_ONLY =
IF_ATTACH_NX_NETIF_COMPAT | IF_ATTACH_NX_FLOWSWITCH) on iOS 18 bases. This
keeps the netif + flowswitch nexus (interface/host stack unaffected) but
leaves the FSW_TRANSPORT/IP netagents unset, so Network.framework uses the
BSD-socket path and mDNSResponder never creates the crashing channel. The
kernel boot-args come from the patched iBoot (kern.bootargs matches
IBootPatcher.bootArgs), so the arg is baked into the iBEC/LLB boot-args
patch, not the host NVRAM (which iBoot overrides).
- IBootPatcher gains `extraBootArgs`, inserted before the trailing %s in
the patched boot-args string (ibec/llb).
- FirmwarePipeline sets extraBootArgs="if_attach_nx=0x3" for iOS 18 bases
(iosBaseIs18), empty otherwise, on the iBEC and LLB factories.
Gated to iOS 18 bases: 26.x keeps the stock boot-args and is untouched.
Validated at runtime first (setting net.link.generic.system.enable_netagent
=0 makes DNS resolve reliably), then confirmed end-to-end on a fresh
17,3_18.6.2_22G100 jb restore: kern.bootargs shows if_attach_nx=0x3 and
DNS/networking works.
Documented in research/0_binary_patch_comparison.md (iBEC/LLB boot-args row).
Co-Authored-By: Claude Opus 4.8 <[email protected]>
Claude-Session: https://claude.ai/code/session_01Q7gbWrtKLu8rFGmpXHmu9t
iOS 18.x userland on the 26.1 vphone600 kernel has no working touch: the
VZ USB touchscreen dext receives input reports (InputReportCount climbs)
but emits zero digitizer events on the 26.1 kernel, so backboardd's event
queue stays empty and the UI never sees touches. The identical device on
a 26.x base produces digitizer events normally, so it is a guest-side
dext<->kernel report->event ABI break, not a host or descriptor issue.
Fix: inject digitizer events guest-side via vphoned, bypassing the broken
dext -- the same IOHIDEventSystemClientDispatchEvent path vphoned already
uses for the Home key. vp_hid_touch() builds a Hand parent + digitizer
finger child event (display-integrated) and dispatches it.
- vphoned_hid.{h,m}: vp_hid_touch(phase,x,y) + digitizer dlsyms.
- vphoned.m: "touch" command; hello now reports the guest iOS version and
a "touch" capability.
- VPhoneControl: sendTouch(), guestIOSVersion, and useGuestTouchInjection
(connected && caps has "touch" && iOS major < 26).
- VPhoneVirtualMachineView.sendTouchEvent: routes to vphoned when
useGuestTouchInjection, else the native VZ USB multitouch path.
Gated to iOS 18 bases: 26.x guests report major >= 26, so the gate is
false and touch uses the unchanged native USB path (no regression). The
new vphoned code is compiled into all builds but stays inert on 26.x.
Ships via the existing vphoned hash-mismatch auto-update; no re-restore.
Verified on 17,3_18.6.2_22G100: socket tap -> correct digitizer event
(coordinates match), swipe unlocks to home, tap on the Settings icon
launches Settings.
Co-Authored-By: Claude Opus 4.8 <[email protected]>
Claude-Session: https://claude.ai/code/session_01Q7gbWrtKLu8rFGmpXHmu9t
iOS 18.6.2 userland on the 26.1 vphone600 kernel crash-loops
runningboardd and SpringBoard, so the UI never takes over from the boot
logo. Crash reports show EXC_GUARD / GUARD_TYPE_MACH_PORT "flavor 10":
the 26.1 kernel fatally enforces a Mach port guard that iOS 18's older
userland trips (hardening the 18.x daemons predate).
The existing patchExcGuardBehavior() (kernel patch 27,
thread_guard_violation -> RET) fixes exactly this but was gated to the
dev variant only. Wire it to also apply on regular/jb/exp when the
iPhone base is iOS 18:
- FirmwarePipeline reads the base ProductVersion from
iPhone-BuildManifest.plist (fw_prepare preserves it; the live
BuildManifest reads the cloudOS 26.1 version, not the base) and sets
applyExcGuard for 18.* bases.
- KernelPatcher gains an applyExcGuard flag; patch 27 now runs when
isDev || applyExcGuard.
Scoped to iOS 18 bases only — 26.x bases boot without it, never set
applyExcGuard, and are unaffected. Validated on 17,3_18.6.2_22G100:
fw_patch_jb logs "iPhone base iOS: 18.6.2 (enabling ...)" and applies
thread_guard_violation -> RET at foff 0xB4FFCC. With this plus the
display SwapEnd fix, 18.6.2 boots to the Setup Assistant UI with
runningboardd and SpringBoard stable.
The keystore AppleSEPKeyStore sel-135 UnsupportedMode seen during
bring-up turned out to be non-fatal (tolerated by the CredentialManager)
and is not needed for boot, so no keystore patch is included.
Co-Authored-By: Claude Fable 5 <[email protected]>
The ramdisk-based install (build/send an SSH ramdisk, iproxy-forward, then
push CFW files over SSH and flip the boot snapshot with snaputil in-VM) has
been fully replaced by the host-mount path: cfw_install_host.sh mounts the
VM's Disk.img on the host, places every file locally, and flips the boot
snapshot offline via tools/apfs_snap_rename.py. This removes all remaining
ramdisk generation, delivery, and usage — no legacy fallback.
Deleted:
- scripts/ramdisk_build.py, scripts/ramdisk_send.sh
Renamed:
- scripts/cfw_host_mode.sh -> scripts/cfw_transport.sh (was a conditional
"host-mode override"; now the sole, unconditionally-sourced transport)
setup_machine.sh: drop the USE_RAMDISK_CFW=1 branch and every iproxy/ramdisk
helper (usbmux UDID resolution, port picking, start/stop iproxy, wait-for-
ramdisk-ssh), all RAMDISK_*/IPROXY_* vars, the cleanup() iproxy handling, and
the orphaned cfw_install_target var. Only the host-mount cfw_install_host call
remains.
cfw_install{,_dev,_jb,_exp}.sh: delete the SSH transport (SSH_* vars, SSH_OPTS,
sshpass prereq/_sshpass/_ssh_retry, ssh_cmd/scp_to/scp_from/remote_file_exists/
remote_mount, wait_for_device_ssh_ready) and the dead ramdisk-mechanism body
blocks (snaputil snapshot flip, dropbearkey host-key pre-generation, halt-over-
SSH, CFW_SKIP_HALT). The transport is now sourced unconditionally from
cfw_transport.sh. dropbear -R generates host keys at first boot; the offline
apfs_snap_rename.py does the boot-source flip. Dropped the vestigial
CFW_HOST_MODE gate.
Also: pymobiledevice3_bridge.py (ramdisk-send command already gone), Makefile
(ramdisk targets/help/IRECOVERY_ECID removed), README + ja/ko/zh (install flow
rewritten to host-mount), AGENTS.md/CLAUDE.md architecture tree, and stale
comments in vphone_jb_setup.sh, VPhoneCLI.swift, apfs_snap_rename.py,
cfw_patch_post_restore_dt.py.
Verified booting via make setup_machine.
Co-Authored-By: Claude Opus 4.8 <[email protected]>
Claude-Session: https://claude.ai/code/session_01XZVS9oqVNmHJzpb8mFtKJx
The 26.5 Shape B W^X matcher (mov #5 -> #7) mis-targets vm_map.c:6202
`prot &= ~VM_PROT_WRITE` -- the copy-on-write-preservation write-strip --
instead of the RWX/ALLEXEC gate at vm_map.c:5997. Widening it keeps write on
code-page protections, so a debugger's breakpoint write lands a writable PTE on
the code frame; SPTM rejects that (VIOLATION_ILLEGAL_MAP, page_fte->type=0xf),
killing any debugged process on 26.4+.
Isolation confirmed: with cs_bypass (patch_vm_fault_enter_prepare) left enabled
and Shape B disabled, the debugger works -- Shape B was the sole cause.
Retired on 26.5+ (not retargeted): on SPTM, code modification uses write-then-flip
via vm_protect(VM_PROT_COPY) -> XNU_USER_DEBUG. The debugger, MobileSubstrate
tweaks, and the JB's own plugins (vcc_patch_two_nops in libvcamcaptured.m) all use
this path; none need non-MAP_JIT RWX. Shape A (26.1-26.4, the real ALLEXEC gate)
is unaffected.
Co-Authored-By: Claude Fable 5 <[email protected]>
The patch-16 entitlement-gate matcher keyed on source line IDs
(`mov w8, #0x332D / #0x333B`); on 26.4 both the value and the register drifted,
so it found nothing and silently skipped (worked on 26.1/26.3).
Re-anchor the deny blocks on their stable panic strings ("This operation needs
entitlement" and "lookup takes place out of a volume group, but the source
volume is in one"), scoped to the routine by also requiring the
`handle_get_dev_by_role` function-name string — this excludes the adjacent
`handle_volume_class_keybag_op`, which shares the entitlement message. Yields the
same 3 gates on 26.1/26.3 (parity) and now 3 on 26.4.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
Two pre-existing iBoot patches silently skipped on some cloudOS versions
(verified by cross-version disassembly of the vresearch101 iBEC/LLB payloads):
- bootx precondition (iBEC): the `BL <bit-getter>; TBZ w0,#0 -> panic` construct
is a 26.4+ iBoot addition and is genuinely absent on 26.1/26.3 (which boot fine
without it). Treat "construct not present" as an informational skip, not a
failure; ambiguity (>1 gate) still hard-fails.
- LLB rootfs size gate: the bare `cmp x8, #0x400` is not unique — 26.4 LLB has
three (only one is the size gate, the other two are followed by `b.hi`). Anchor
on the `cmp x8,#0x400 ; b.hs` pair, unique on 26.1/26.3/26.4.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
