Introduce a kernel debug port option and wire it through the CLI and VM configuration. Adds a --kernelDebugPort CLI option (default 5909), a kernelDebugPort field in VPhoneVirtualMachine.Options, and validation (1..65535) that throws VPhoneError.invalidKernelDebugPort on invalid values. Configure the VM to use a fixed host GDB debug stub port when possible (with system-assigned fallback) and print the chosen stub info from the AppDelegate. Also include a small menu styling tweak (comma-style) in VPhoneMenuBattery.
Add ramdisk-specific kernel snapshot and build logic so the installer ramdisk can boot with a conservative kernel while the restore target keeps the fully JB-patched kernel. Changes:
- research/patch_comparison_all_variants.md: document the Ramdisk Kernel Split and intent.
- scripts/fw_patch_jb.py: snapshot the base/dev-patched kernel before applying JB extensions (new helper and constants).
- scripts/ramdisk_build.py: build krnl.ramdisk.img4 from the snapshot and krnl.img4 from the restore kernel when a snapshot exists; factor kernel IMG4 creation into build_kernel_img4.
- scripts/ramdisk_send.sh: prefer krnl.ramdisk.img4 when present, falling back to krnl.img4; fail early if no kernel image found.
This improves /dev/disk1s1 remount reliability during CFW/install by keeping the restore kernel JB-patched but booting the installer ramdisk with a more conservative kernel variant.
Ensure target mountpoint exists and verify mounts succeed in remote_mount across cfw_install scripts: create the directory with mkdir -p, short-circuit if already mounted, attempt mount_apfs, and fail with a clear error if the mount did not occur. Also replace the grep|head pipeline with an awk extraction to safely pick the first com.apple.os.update snapshot when renaming to orig-fs.
These were used for per-patch kernel JB debugging (C23 bisect,
single-patch boot test, batch testing). No longer needed now that
A2, C23, and C24 are all boot-tested and fixed.
Three bugs caused NOT_BOOT (timeout):
1. Wrong sysent table base: first _nosys match is entry 428, not entry 0.
Entry 0 is the indirect syscall handler. Fixed with backward scan.
2. Raw VA written to chained fixup pointer slot: struct.pack("<Q", cave_va)
corrupts the fixup chain from sysent[439] onward. Fixed with proper
auth rebase encoding (_encode_chained_auth_ptr).
3. Missing PAC parameters: dispatch uses BLRAA X8, X17 with X17=0xBCAD.
Chained fixup must encode diversity=0xBCAD, key=IA, addrDiv=0.
Chain 'next' field preserved from original entry.
Boot-tested OK via testing ramdisk.
Root cause: find_string("vnode_getattr") matched "%s: vnode_getattr: %d"
format string inside an AppleImage4 function. The old code then took that
function as vnode_getattr itself, causing BL to call into AppleImage4 with
wrong arguments → PAC failure on indirect branch at a2+48.
Fix: _find_vnode_getattr_via_string() now scans backward from the string
ref for a BL instruction and extracts its target — the real vnode_getattr
(sub_FFFFFE0007CCD1B4 at foff 0xCC91B4).
Bisection confirmed: variants A (stack frame) and B (+ tpidr_el1) boot OK,
variant C (+ BL vnode_getattr) panics with old resolution, boots OK with fix.
Boot-tested: full C23 patch with corrected vnode_getattr — BOOTS OK.
Ops table pointer modification breaks chained fixup integrity in the
fileset kernelcache, causing PAC failures in unrelated kexts (e.g.,
AppleImage4). The fixup diversity (0xEC79) also doesn't match the
dispatch discriminator.
New approach: replace PACIBSP at hook function entry with B cave.
Cave runs relocated PACIBSP, ownership propagation shellcode, then
B hook+4 to resume. Uses only PC-relative branches — no PAC, no
chained fixup modification. Also fixes branch offsets in shellcode
to ensure all registers are properly restored in error/skip paths.
Root cause: backward branch search found PAC validation B.EQ (target fell
within error region range) instead of the kernel_map guard B.NE. New approach
walks backward from panic string ADRP to find CMP+B.cond where the branch
goes forward past the panic, then makes it unconditional. Also enables B6
and B8 in find_all(). Boot-tested: PASS.
Old approach patched vnode-type assertion BLs (CBZ→panic). New approach
scans backward from function end for the shared MOV W0,#1 kill return
before the LDP x29,x30 epilogue and changes it to MOV W0,#0. Single
instruction converts all 5+ kill paths to success. Boot-tested OK.
Root cause: "most-called BL target" heuristic in _proc_info picked copyio
(4 calls, 0x28C bytes) over the real _proc_security_policy (2 calls,
0x134 bytes). Lowered size filter threshold from 0x300 to 0x200 to
correctly exclude utility functions like copyio. Boot-tested: PASS.
Old approach patched vnode-type assertion BLs (CBZ→panic). New approach
scans backward from function end for the shared MOV W0,#1 kill return
before the LDP x29,x30 epilogue and changes it to MOV W0,#0. Single
instruction converts all 5+ kill paths to success. Boot-tested OK.
Root cause: "most-called BL target" heuristic in _proc_info picked copyio
(4 calls, 0x28C bytes) over the real _proc_security_policy (2 calls,
0x134 bytes). Lowered size filter threshold from 0x300 to 0x200 to
correctly exclude utility functions like copyio. Boot-tested: PASS.
Introduce a set of tools for fast and batch testing of kernel JB patches: add testing_batch.sh, testing_do_patch.sh, testing_do_save.sh and testing_kernel_patch.py (plus a results _summary). Update the Makefile with new targets (testing_do_save, testing_kernel_patch, testing_do_patch, testing_batch) and PHONY entries to wire them into the build/test workflow. Modify kernel_jb.py to enable the amfi cdhash-in-trustcache patch (A1) and mark the amfi execve kill-path patch as causing PANIC (A2). These changes allow restoring a base kernel backup, applying single patches quickly, running per-patch DFU boots (with timeout/panic detection), and collecting logs for batch runs.
Introduce a new zsh helper script (scripts/testing_do.sh) and a Makefile target (testing_do) to automate the testing DFU workflow. The script sets strict error handling, kills any existing vphone-cli, runs fw_prepare, fw_patch_jb and testing_ramdisk_build, sends the ramdisk in the background, boots DFU, and tracks/cleans up child processes on exit. This simplifies and sequences the steps required to prepare, patch, send and boot the test ramdisk.
Uncomment the kernelcache (JB) component in JB_COMPONENTS so the kernelcache patcher is included. In KernelJBPatcher, comment out a large set of patch registration calls across Groups A, B and C and annotate them (A1..C24) to keep the original patch list for reference while preventing them from being applied. No functional patch logic was modified, only registration calls were disabled and formatting adjusted.
The original selector24 patches (NOP ldr + NOP bl) broke the hash flags
extraction, causing the consistency check to fail. The second attempt
(return 0x130A1) also failed because the return code semantics were
inverted — byte 1 != 0 means FAIL, not success.
Correct approach: insert `mov w0, #0xa1; b <epilogue>` after the prologue.
0xA1 has byte 1 = 0 which the caller checks via `tst w0, #0xff00` as PASS.
Update AGENTS.md
move selector24 bypass from txm_jb.py to txm_dev.py, delete TXMJBPatcher
Selector24 CS validation bypass now applies to both dev and JB variants
via txm_dev.py. The separate txm_jb.py patcher is removed since it had
no other patches. Dev boot chain: 47→49 patches.
Create txm_fullchain_analysis.md
Extract stock ramdisk from restore directory, mount it to build a real
trustcache from its Mach-O binaries, then sign both. Empty trustcache
would be rejected by the boot chain.
Boot chain requires all 8 steps (iBSS, iBEC, SPTM, TXM, trustcache,
ramdisk, DeviceTree, SEP, kernel). Ramdisk and trustcache are now
included as valid but empty artifacts.
Separate dev vs JB TXM patches and streamline fw_patch_jb. fw_patch_dev now calls patch_txm and uses TXMPatcher as TXMDevPatcher; txm_dev.py doc/comments clarify it is dev-only and removes the trustcache bypass from the dev finder. fw_patch_jb was reorganized: COMPONENTS and JB_COMPONENTS lists define base and JB-only patches, the previous subprocess call to run fw_patch.py was removed, and component discovery/patching is unified (with updated messages). txm_jb now only implements the JB-exclusive selector24 extension, relying on dev patches being applied separately.
Sign patched firmware components (iBSS/iBEC/SPTM/DeviceTree/SEP/TXM/
kernelcache) into IMG4 without ramdisk or trustcache. Useful for
verifying boot chain patches in isolation.
- Add git-lfs to brew deps and document git lfs install/pull steps
in both English and Chinese READMEs
- Fix continuation line alignment in make help (off by one)
- Add missing blank line before VM management section
iproxy 2222 22 is a blocking command, so it can't share a terminal
with make cfw_install. Clarify that a third terminal is needed and
note the "Running server" output as the cue to proceed.
Closes#58
- Add `unlock` tool: C program dispatching IOHIDEvent to wake/unlock screen
- Rework serial port to pipes for programmatic command injection
- Auto-unlock on non-DFU boot via serial console after 8s delay
- Add "Unlock" menu item, `make unlock`/`make unlock_deploy` targets
- Defer to native VZVirtualMachineView touch on macOS 16+
- Add sshpass resolver with bundled/host fallback and arch checks
- Add gtar resolver with bundled/host/tar fallback and arch checks
- Prevent host-arch mismatches from breaking cfw_install and ramdisk_build
Closes#45, closes#46Fixes#38, fixes#41
Co-authored-by: webcpu <[email protected]>
Co-authored-by: tastyheadphones <[email protected]>
Add jailbreak extension patchers and targets:
- kernel_jb.py: 22 dynamic kernel patches (trustcache, execve cs_flags,
sandbox ops, task/VM, kcall10 syscall hook, ~160 total modifications)
- txm_jb.py: 13 TXM patches (CS validation, get-task-allow, debugger
entitlement, dev mode bypass)
- iboot_jb.py: iBSS nonce generation skip
- cfw.py: launchd jetsam patch, dylib injection commands
- fw_patch_jb.py: orchestrator running base + JB extension patches
- cfw_install_jb.sh: JB install phases (launchd jetsam fix, procursus
bootstrap + Sileo deployment)
3 kernel patches still WIP (nvram_verify_permission, thid_should_crash,
hook_cred_label_update_execve) — strategies documented in
researchs/kernel_jb_remaining_patches.md.
All base (non-JB) code paths verified unaffected — kernel.py produces
identical 25 patches, cfw.py base commands unchanged.
Add Linux venv setup script; tweak Makefile help
Add scripts/setup_venv_linux.sh to create a Python virtualenv on Debian/Ubuntu (or dnf-based) systems, install system packages and Python requirements, and verify core imports (capstone, keystone, pyimg4). Also update Makefile help text to mark the fw_patch_jb target as WIP. This simplifies local development setup on Linux and clarifies that the JB extension patches are a work in progress.
Update AGENTS.md: mark cfw_install_jb.sh as complete
Update README.md
Add Simplified Chinese README and link
Add README_zh-Hans.md containing a full Simplified Chinese translation of the project README and update README.md to include a link/badge to the new Chinese README. This makes the documentation accessible to zh-Hans readers.
Introduce a new vphone virtual iPhone project:
- Add VPhoneObjC (.m/.h) providing Objective-C wrappers around private Virtualization.framework APIs (PV=3 hardware model creation, bootloader ROM setting, NVRAM helpers, PL011 serial port, SEP coprocessor, debug/panic devices, and production-mode toggle).
- Add Swift CLI and VM implementation (VPhoneCLI.swift, VPhoneVM.swift, VPhoneHardwareModel.swift) to configure and boot a PV=3 VM, capture serial console, start in DFU, and manage SEP/storage. Includes validation and minimal device config (graphics, storage, networking).
- Add helper scripts (build_and_sign.sh, boot.sh, boot_dfu.sh) to build, codesign with entitlements, and launch the VM.
- Add vphone.entitlements enabling the required private virtualization entitlements.
Notes: this targets macOS 15+ and requires appropriate entitlements and disabled SIP/AMFI to use private virtualization APIs.
Create .gitignore
Update README.md
Update README.md
Update README.md
README: add demo image and fix formatting
Add demo.png and embed it in the README; clean up markdown and code snippet formatting, remove stray backticks/bold markers, normalize list bullets, fix a resource path (vrevm), tidy whitespace/trailing chars, and add an Acknowledgements section. These changes improve readability and correctness of the setup instructions.
Create LICENSE
Create README.md
Add Package.swift; use interactive serial console
Add a Swift Package manifest for vphone-cli (macOS v14) with targets VPhoneObjC and vphone-cli, dependency on swift-argument-parser, and necessary linker/swift settings. Modify VPhoneVM to remove the intermediate Pipe-based serial capture: attach the PL011 serial port directly to FileHandle.standardInput/standardOutput for an interactive console, remove the readabilityHandler-based console capture and related plumbing, and update log/print messages accordingly.
Add CFW installer and patching tools
Add scripts and input archive to install a custom firmware (CFW) on vphone via an SSH ramdisk. Includes:
- Scripts/install_cfw.sh: zsh installer that extracts Cryptex DMGs from a restore, mounts device filesystems, copies Cryptexes, installs GPU driver and iosbinpack64, patches system binaries, injects LaunchDaemons and configures persistent SSH/VNC. Idempotent, caches decrypted DMGs and signs patched binaries with provided tools.
- Scripts/patch_cfw.py: Python tool using capstone/keystone to locate and patch binaries (seputil, launchd_cache_loader, mobileactivationd), parse BuildManifest for Cryptex paths, and inject daemon plists.
- Scripts/cfw_input.tar.zst: bundled input resources (Cryptexs, daemons, signing cert, and helper tools).
The installer requires ipsw, aea, python3 with capstone/keystone-engine and is designed to be safe to re-run. Intended to automate CFW deployment and runtime patches on the target device.
Add ramdisk build and deployment scripts
Add Scripts/build_ramdisk.py to build a signed SSH ramdisk for vphone600 from a patched restore set: it extracts firmware components, patches iBEC boot-args, repacks/signs IM4P/IMG4 artifacts (iBSS, iBEC, TXM, kernel, DeviceTree, SEP, trustcache, ramdisk) using an IM4M from an SHSH blob. Include a prepackaged ramdisk_input.tar.zst with tooling/resources and a helper Scripts/ramdisk_send.sh to load the generated IMG4 files to a device via irecovery in the correct order. The Python script expects firmware patched by patch_firmware.py and requires keystone-engine, capstone, pyimg4, and the pyimg4 CLI; usage and temp/output directories are documented at the top of the script.
Add firmware prepare and patch scripts
Add two tools for building and modifying a hybrid restore image for vphone600:
Scripts/prepare_firmware.sh
- Bash helper to download an iPhone IPSW and a cloudOS IPSW, extract them, merge cloudOS boot components into the iPhone restore directory, and generate hybrid BuildManifest.plist and Restore.plist tailored for vresearch101/vphone600 use-cases.
- Produces a ready Restore directory. Usage: ./prepare_firmware.sh [iphone_ipsw_url] [cloudos_url]
Scripts/patch_firmware.py
- Python tool that runs after prepare_firmware.sh to patch boot-chain components (AVPBooter, iBSS, iBEC, LLB, TXM, kernelcache).
- Auto-detects IM4P vs raw payloads, supports recompressing/repacking IM4P (preserving PAYP metadata when required), and applies a variety of binary patches (image4 callback bypass, serial labels, boot-args injection, trustcache/ DGST bypasses, many kernelcache fixes).
- Implements assembler/disassembler helpers (keystone/capstone) and multiple heuristics for locating patch sites.
- Usage: python3 patch_firmware.py [vm_directory]
- Dependencies: keystone-engine, capstone, pyimg4 (pip install keystone-engine capstone pyimg4)
These scripts automate preparing a hybrid restore and applying the required boot-chain patches for research devices.
Update demo.png
Create boot_sweet.sh
Add multi-touch support and VM window
Enable multi-touch input and a GUI VM window: add ObjC helpers to configure a _VZUSBTouchScreenConfiguration, create _VZTouch objects via KVC (workaround for init crash), build _VZMultiTouchEvent instances, and send/get multi-touch devices. Expose these APIs in the VPhoneObjC header and invoke VPhoneConfigureMultiTouch from VPhoneVM before VM start. Add a VPhoneVMWindow implementing a touch-enabled VZVirtualMachineView that maps mouse/right-click/drag events to multi-touch phases (with edge detection for swipe aim) and a window controller to show the VM. Also update the CLI to present the window in GUI mode.
Lakr