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
Add rpc-project rpcserver_ios LaunchDaemon to CFW install, update
cfw_input.tar.zst with the plist, and add iproxy 5910 + rpcclient
to README.
Co-authored-by: zqxwce <yyyyyy6yyyyyy6@gmail.com>
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
Update vphoned build step to compile all split source files instead of
just vphoned.m. Tracks all .m files for staleness checking and passes
them to clang with the correct -I include path.
Co-authored-by: zqxwce <yyyyyy6yyyyyy6@gmail.com>
Add a VM storage lock preflight in setup_machine.sh before both
`make boot` and `make boot_dfu`. Detects active lock holders for
nvram.bin, machineIdentifier.bin, Disk.img, and SEPStorage via lsof,
prints PID/PPID/command details, and supports optional automatic
recovery with AUTO_KILL_VM_LOCKS=1.
Fixes#55.
Co-authored-by: tastyheadphones <tastyheadphones@icloud.com>
- 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 <liang@unchartedworks.com>
Co-authored-by: tastyheadphones <tastyheadphones@icloud.com>
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.
