DOCSEARCHbyAlgolia
Submit Docs

vphone-cli Documentation

repository·main·Indexed 27 days ago

https://github.com/lakr233/vphone-cli

A command-line tool for booting virtual iPhones on macOS using Apple's Virtualization.framework. It provides a pipeline for creating, patching, and managing virtualized iOS environments with various security bypass levels (variants), including jailbreak (jb), regular, dev, and experimental (exp). The tool supports VM lifecycle management, firmware patching, DFU restoration, and includes components like Lean TweakLoader for managing user tweak injection.

Tokens
53.1K
Snippets
60
Records
276
Agent score
93%

What's inside vphone-cli

  1. Overview of Lean TweakLoader

    main

    Lean TweakLoader is a component designed to support the vphone JB basebin runtime (systemhook.dylib). Its primary functions are:

    1. Providing the TweakLoader component: It supplies the /var/jb/usr/lib/TweakLoader.dylib file required by the runtime.
    2. Loading Tweaks: It automatically loads user tweak .dylib files from /var/jb/Library/MobileSubstrate/DynamicLibraries into processes that match the criteria defined in their corresponding .plist files.

    Logging: All activity is logged to /var/jb/var/mobile/Library/TweakLoader/tweakloader.log.

  2. Understand the vphone-cli firmware architecture

    main

    The vphone-cli firmware uses a hybrid approach to create a functional virtual device. It combines components from three distinct sources to achieve a keybag-less boot and a functional userland:

    1. Boot Chain (vresearch101): Handles DFU and TSS signing to match the hardware.
    2. Runtime Environment (vphone600): Provides the DeviceTree, SEP, and Kernel.
    3. Userland (iPhone): Provides the OS and filesystem, which are patched post-install for activation bypass and remote access (SSH/VNC).

  3. Understand Patch Variants: Regular, Development, Jailbreak, and Experimental

    main

    The project uses four distinct patch variants for the boot chain and kernel. Understanding the relationship between them is critical for choosing the right environment:

    • Regular: The baseline variant with minimal patches.
    • Development (Dev): Includes Regular patches plus developer-specific bypasses (e.g., TXM Selector24, get-task-allow).
    • Jailbreak (JB): Includes Regular patches plus specific jailbreak requirements (e.g., iBSS generate_nonce skip).
    • Experimental (EXP): A superset of the Jailbreak variant. It includes everything in JB plus advanced features like KernelEXPPatcher, DeviceTree identity-rewrites, and Camera.app accessibility patches.

    Use EXP if you require advanced spoofing (e.g., identity-rewriting toward iPhone17,3) or camera functionality in a virtualized environment.

  4. Understand the `patch_shared_region_map` jailbreak patch

    main

    The patch_shared_region_map patch is designed to bypass the mount-comparison gate in the shared_region_map_and_slide_setup() function. This allows the shared-cache vnode to be treated as if it were already on the process root mount, effectively bypassing the fallback preboot lookup path.

    Patch Mechanism

    The patch targets the first policy gate (the direct root-mount comparison) and rewrites the assembly to force a match. Specifically, it changes a comparison instruction (e.g., cmp mount_reg, root_mount_reg) to a self-comparison (e.g., cmp x0, x0).

    Implementation Details

    • Target Function: shared_region_map_and_slide_setup()
    • Logic: By patching the first cmp to cmp x0, x0, the code immediately executes the b.eq (branch if equal) instruction, skipping the str xzr, [state,...] and the subsequent vnode_lookup for /private/preboot/Cryptexes.

  5. Understand the Hybrid Firmware Architecture

    main

    The vphone-cli erase install firmware uses a hybrid approach, combining components from three distinct sources to ensure a functional boot environment while maintaining correct hardware identity. This allows the VM to boot without a system keybag and pass TSS/SHSH signing.

    Source Components

    • PCC vresearch101ap: Provides the boot chain (LLB, iBSS, iBEC, iBoot) and security monitors (SPTM, TXM).
    • PCC vphone600ap: Provides runtime components including DeviceTree, SEP, KernelCache, and RecoveryMode.
    • iPhone 17,3: Provides the OS image, trust caches, and filesystem.

    Build Process

    1. Run fw_prepare.sh to download both required IPSWs and merge CloudOS firmware into the iPhone restore directory.
    2. Run fw_manifest.py to generate the hybrid BuildManifest.

  6. Understand the B20 `patch_thid_should_crash` kernel patch

    main

    The patch_thid_should_crash patch is designed to bypass a kernel policy gate that rejects exception-port registration. By default, the kernel uses a flag (thid_should_crash) that, when set, causes set_exception_port operations to return KERN_NOT_SUPPORTED (53). This blocks unsigned bootstrap and launchd-dylib flows. The patch zeros this flag, forcing the gate to return KERN_SUCCESS (0) instead.

    Warning: This patch globally changes exception-port policy behavior and may weaken kernel security assumptions or reduce diagnostic fidelity.

  7. Understand the C22 `patch_syscallmask_apply_to_proc` mechanism

    main

    The C22 mechanism is a kernel patch designed to install per-process syscall filter masks. It targets the syscall mask application layer used by Unix syscall dispatch, Mach trap dispatch, and Kernel MIG/kobject dispatch.

    In XNU terms, this mechanism is semantically equivalent to calling proc_set_syscall_filter_mask(proc_t p, int which, unsigned char *maskptr, size_t masklen).

    Key Behavioral Distinction:

    • All-ones mask (Historical C22): Mutates the mask bytes to 0xFF and continues through the normal setter path. This forces an 'allow all' state.
    • NULL mask (Modern simplification): Sets the mask pointer to NULL. While this also bypasses mask-based interception, it is behaviorally different from the historical C22, especially regarding KOBJ/MIG enforcement when KOBJ_IDX_NOT_SET is present.

  8. Understand the TXM Execution Model

    main

    TXM (Trusted Execution Monitor) operates at a guested exception level (GL1) under the supervision of SPTM (Secure Page Table Monitor) at GL2.

    Key constraints:

    • SPTM dispatches selector calls into TXM via svc #0.
    • TXM cannot execute SPTM code due to instruction fetch permission faults.
    • TXM must return to SPTM exclusively via the svc #0 trap mechanism.

  9. Enable Camera Icon Visibility (Experimental Only)

    main

    To make the Camera.app icon visible on the home screen and in Spotlight without breaking screen rendering, apply the following three tiers of DeviceTree patches. These are applied via identityPropertyPatches, experimentalNodeAdditions, and AddChildNodePatch entries.

    Tier B: /product cam-offset rewrites

    Rewrites 12-byte cstring placeholders to 20-byte little-endian geometry blobs used by Camera.app, ARKit, and FaceTime.

    • /product::front-cam-offset-from-center
    • /product::rear-cam-offset-from-center

    Tier C: New /product/* child nodes

    Adds sibling nodes to /product/camera to provide configuration for FaceTime, Audio, and Always-On Technology (IOPM).

    • /product/facetime
    • /product/audio
    • /product/iopm

    Tier F: /arm-io/* minimal camera-flag stubs

    Adds minimal stub nodes to prevent IOKit from probing non-existent hardware while providing necessary camera flags. These nodes omit compatible, device_type, reg, and interrupts to avoid driver probing.

    • /arm-io/smc/iop-smc-nub/smc-ext-charger (property: camera-driver = 'AppleH16CamIn')
    • /arm-io/isp (properties: camera-front, camera-rear = int32:1)
    • /arm-io/ispRtb (properties: camera-front, camera-rear = int32:1)
    | Property | Old length | New length | New value (hex) |
|----------:|:----------:|:----------:|:----------------|
| `/product::front-cam-offset-from-center` | 12 | 20 | `61000100921c0000d8130000e803000000000000` |
| `/product::rear-cam-offset-from-center` | 12 | 20 | `eda50000b256000059080000e803000000000000` |

  10. Implement HV VMM presence patching (Dev + Jailbreak)

    main

    The kern.hv_vmm_present sysctl can be patched to hide VM presence by mangling the cstring in user-mode call sites. This is implemented via the cfw_install_dev.sh or cfw_install_jb.sh installation flows.

    Patch Mechanism: Every call site is patched by changing the first byte of the cstring from 'k' (0x6B) to 'X' (0x58), resulting in "Xern.hv_vmm_present\0". This causes the kernel to return ENOENT, effectively making the caller believe the sysctl does not exist, which keeps the is_vmm state at 0.

    Scope of Patching:

    • DSC dylibs: Patched within the SystemOS Cryptex DMG while mounted on the host.
    • Standalone binaries: (e.g., appstored, storekitd) Pulled via SSH, patched, signed with ldid, and pushed back.
    • Compute/Accel (Not Patched): Libraries like CoreML, Espresso, and WebGPU are intentionally left unpatched to preserve VM-aware fast-path bypasses.

  11. Implement the `patch_nvram_verify_permission` patch using a dynamic strategy

    main

    The patch_nvram_verify_permission patch aims to NOP a memmove call within the verifyPermission function of the IONVRAMController class. Because the kernel is fully stripped (0 symbols), a static offset approach is unreliable.

    Use the following dynamic search strategy to locate the correct patch site:

    1. Locate the IONVRAMController vtable: Search __DATA_CONST for chained fixup pointer entries that meet these criteria:
      • The entry is preceded by exactly 3 NULL entries (indicating the start of a vtable).
      • The decoded target is a function located in kern_text.
      • The function contains the instruction movk x17, #0xcda1, lsl #48 (the IONVRAMController PAC discriminator).
      • The function contains a BL call to a target with >2000 callers (specifically memmove).
    2. Apply the patch: Once the function is identified, find the specific BL instruction to memmove and NOP it.

  12. Apply the `patch_task_conversion_eval_internal` kernel patch

    main

    This patch neutralizes a task-conversion compare guard in the kernel by replacing a conditional comparison (cmp Xn, x0) with a comparison that always evaluates to true (cmp xzr, xzr). This allows task port and privilege escalation paths that are otherwise blocked by task conversion checks.

    Implementation Details

    • Primary Patcher Module: scripts/patchers/kernel_jb_patch_task_conversion.py
    • Patch Goal: Replace CMP X9, X0 with CMP XZR, XZR at the validated guard site.
    • Byte-Level Change:
      • Before: 3F 01 00 EB (CMP X9, X0)
      • After: FF 03 1F EB (CMP XZR, XZR)

    Usage and Configuration

    The patcher uses site resolution based on anchors, opcode shapes, and control-flow context. It is designed to fail closed (reject ambiguous candidates). If you need to use the slow fallback mechanism for matching, set the following environment variable:

    VPHONE_TASK_CONV_ALLOW_SLOW_FALLBACK=1

    Risks and Side Effects

    • Security: This patch weakens a kernel policy gate by design and broadens the privileged surface.
    • Diagnostics: May result in reduced diagnostics fidelity.
    • Stability: If unpatched, task conversion checks will reject conversions, blocking intended workflows.