Implement VM configuration manifest system compatible with security-pcc's
VMBundle.Config format, storing VM settings in config.plist.
**Manifest System:**
- Add VPhoneVirtualMachineManifest.swift with security-pcc compatible structure
- Add scripts/vm_manifest.py for manifest generation during vm_new
- Update VPhoneCLI to support --config option with CLI overrides
- Update vm_create.sh to generate config.plist with CPU/memory/screen settings
**Environment Variables:**
- CPU/MEMORY/DISK_SIZE now only used during vm_new (written to manifest)
- boot/boot_dfu automatically read from config.plist
- Remove unused CFW_INPUT variable (overridden by scripts internally)
- Document remaining variables with their usage scope
**Documentation:**
- Update README.md with VM configuration section
- Update docs/README_{zh,ja,ko}.md with translated VM configuration docs
- Update Makefile help output with vm_new options and config.plist usage
- Fix fw_patch_jb description: "dev + JB extensions"
- Fix restore_get_shsh description: "Dump SHSH response from Apple"
**Code Quality:**
- Add VPhoneVirtualMachineRefactored.swift demonstrating code-clarity principles
- Extract 200+ line init into focused configuration methods
- Improve naming: hardwareModel, graphicsConfiguration, soundDevice
- Add BatteryConnectivity enum for magic numbers
- Create research/manifest_and_refactoring_summary.md with full analysis
**Compatibility with security-pcc:**
- Platform type: Fixed vresearch101 (iPhone-only)
- Network: NAT only (no bridging/host-only needed)
- Added: ScreenConfig and SEP storage (iPhone-specific)
- Removed: VirtMesh plugin support (PCC-specific)
docs: add machineIdentifier storage analysis
Research and validate the integration of machineIdentifier into config.plist.
**Findings:**
- security-pcc stores machineIdentifier in config.plist (same approach)
- VZMacAuxiliaryStorage creation is independent of machineIdentifier
- VZMacMachineIdentifier only requires Data representation, not file source
- No binding or validation between components
**Conclusion:**
- ✅ No compatibility issues
- ✅ Matches security-pcc official implementation
- ✅ Proper handling of first-boot creation and data recovery
- ✅ Safe to use
Delete VPhoneVirtualMachineRefactored.swift
refactor: integrate machineIdentifier into config.plist
Move machineIdentifier storage from standalone machineIdentifier.bin file
into the central config.plist manifest for simpler VM configuration.
**Changes:**
- VPhoneVirtualMachineManifest: Remove machineIDFile field
- VPhoneVirtualMachine: Load/create machineIdentifier from manifest
- VPhoneCLI: Remove --machine-id parameter, require --config
- Makefile: Remove --machine-id from boot/boot_dfu targets
- vm_manifest.py: Remove machineIDFile from manifest structure
**Behavior:**
- First boot: Creates machineIdentifier and saves to config.plist
- Subsequent boots: Loads machineIdentifier from config.plist
- Invalid/empty machineIdentifier: Auto-regenerates and updates manifest
- All VM configuration now centralized in single config.plist file
**File cleanup:**
- Move VPhoneVirtualMachineRefactored.swift to research/ as reference
Co-Authored-By: Claude Sonnet 4.6 <[email protected]>
Convert README header to ATX style and add spacing/blank lines for improved Markdown readability in scripts/tweakloader/README.md. Also adjust spacing in a table row in research/0_binary_patch_comparison.md to correct alignment/formatting.
- Fix JB boot chain patch count: 66/78 → 112 (per research doc)
- Merge PR #148: remove cfw_install_jb_finalize, update SSH to openssh-server
- Keep dropbear instructions for Regular/Dev variants
- Add Option 2 (amfidont) to prerequisites and FAQ in all translations
- Add setup_machine options comment to all translations
- Add .tipa FAQ entry (from #142) to all translations
- Add openssh-server FAQ entries to all translations
- Run prettier on all docs
Create .bashrc and .bash_profile for /var/root so SSH sessions
(both login and non-login) source /var/jb/etc/profile for the
full JB PATH. Adapted from #144 to the new vphone_jb_setup.sh
architecture introduced in #141.
Co-authored-by: McNight <[email protected]>
After prep_bootstrap.sh changes the login shell to bash, `touch` is
not available in the remote PATH. Use `: >` (shell builtin) to create
empty marker files without depending on an external binary.
Add scripts/cfw_install_jb_post.sh — an idempotent SSH-based finalizer to complete JB bootstrap on a normally-booted vphone (creates /var/jb symlink, fixes ownership, runs prep_bootstrap, creates markers, installs Sileo, and runs apt; requires sshpass). Add Makefile help, .PHONY and target cfw_install_jb_finalize to invoke the script. Remove host-side IPA signing/installing and related UI: delete VPhoneSigner, VPhoneIPAInstaller, VPhoneMenuInstall and remove signer/ipaInstaller fields and menu items/callbacks from the vphone-cli UI (also removed the DevMode enable WIP flow). Misc: minor table/formatting tweaks in AGENTS.md and research docs.
- Replace Python cfw_inject_dylib.py with tyilo/insert_dylib (built by setup_tools)
- Use --weak flag for LC_LOAD_WEAK_DYLIB injection (avoids crash on missing dylib)
- Preserve original launchd entitlements on re-sign (fixes "operation not permitted")
- Deploy dylibs from pre-built basebin payload instead of building from source
- Remove launchdhook, systemhook, treblehook sources (no longer needed)
- Print GDB debug stub port after VM starts
- Cleanup: remove test scripts, rename patch comparison doc
Apply whitespace and formatting cleanups across research/kernel_patch_jb/*.md: add missing blank lines for readability, remove extraneous trailing blank lines, and adjust a small inline spacing/punctuation in patch_vm_map_protect.md. No semantic changes to content.
Included commits:
- f8a54b8 Update JB kernel patch research notes
Refresh and revalidate jailbreak kernel-patcher documentation and runtime-verification notes. Key updates: re-analyzed B13 (patch_bsd_init_auth) and retargeted recommended site to the FSIOC_KERNEL_ROOTAUTH return check in bsd_init rather than the old ldr/cbz/bl heuristic; clarified preferred NOP-of-CBNZ vs forcing ioctl return. Reworked C21 (patch_cred_label_update_execve) to preserve AMFI exec-time flow and instead clear restrictive csflags in a success-tail trampoline; disabled in default schedule until boot validation. Documented that C23 (patch_hook_cred_label_update_execve) was mis-targeting the wrapper (sub_FFFFFE00093D2CE4) instead of the real hook body (_hook_cred_label_update_execve), explaining boot failures and recommending retargeting. Noted syscallmask and vm_fault matcher problems (patch_syscallmask_apply_to_proc historical hit targeted _profile_syscallmask_destroy; patch_vm_fault_enter_prepare matcher resolves to pmap_lock_phys_page path), and updated the runtime-verification summary with follow-up findings and which methods are temporarily commented out/disabled in the default KernelJBPatcher schedule pending staged re-validation.
- 6ebac65 fix: patch_bsd_init_auth
- 5b224d3 fix: patch_io_secure_bsd_root
- e6806bf docs: update patch notes
- 0d89c5c Retarget vm_fault_enter_prepare jailbreak patch
- 6b9d79b Rework C21 late-exit cred_label patch
- ece8cc0 Clean C21 mov matcher encodings
- ad2ea7c enabled fixed patch_cred_label_update_execve
- c37b6b1 Rebuild syscallmask C22 patch
- 363dd7a Rebuild JB C23 as faithful upstream trampoline
- 129e648 Disable IOUC MACF; rebuild kcall10 & C22 docs
Re-evaluate and rework several JB kernel patches and docs: mark patch_iouc_failed_macf as reverted/disabled (repo-local, over-broad early-return) and replace its patcher with a no-op implementation to emit zero writes by default; update research notes to explain the reanalysis and rationale. Rebuild patch_kcall10: replace the historical 10-arg design with an ABI-correct syscall-439 cave (target + 7 args -> uint64 return), add a new cave builder and munge32 reuse logic in the kcall10 patcher, and enable the method in KernelJBPatcher group. Clarify syscallmask (C22) semantics in docs: upstream C22 is an all-ones-mask retarget (not a NULL install) and keep the rebuilt all-ones wrapper as the authoritative baseline. Misc: minor refactors and helper additions (chained-pointer helpers, cave size/constants, validation and dry-run safeguards) to improve correctness and alignment with IDA/runtime verification.
- e1b2365 Rebuild kcall10 as ABI-correct syscall cave
- 23090d0 fix patch_iouc_failed_macf
- 0056be2 Normalize formatting in research docs
Apply whitespace and formatting cleanup across research markdown files for consistency and readability. Adjust table alignment and spacing in 00_patch_comparison_all_variants.md, normalize list/indentation spacing in patch_bsd_init_auth.md and patch_syscallmask_apply_to_proc.md, and add/clean blank lines and minor spacing in patch_kcall10.md. These are non-functional documentation changes only.
Reflow and standardize research/00_patch_comparison_all_variants.md: reorganized and simplified tables, normalized headings, clarified Kernel vs JB patch lists, updated ramdisk and CFW matrices, and refreshed aggregate counts (e.g. grand totals and kernel/JB method summaries). Minor formatting and wording improvements throughout the document for readability and consistency. Also removed an unused import (os) from scripts/patchers/kernel_jb.py to clean up the code.
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
Lakr