Kernel Patches Applied by vphone-cli: Complete Layered Security Breakdown

vphone-cli applies three distinct layers of kernel patches—base security hardening, jailbreak-specific AMFI bypasses, and experimental hypervisor spoofing—depending on the selected firmware build target.

This guide documents every kernel modification shipped with Lakr233/vphone-cli, the open-source tool for building virtualized iPhone firmware. The patches range from fundamental security fixes to full jailbreak enablement and are applied programmatically through a Python-based patching framework located in scripts/patchers/.

---

How Kernel Patches Are Applied in vphone-cli

The patching system uses semantic matching rather than hardcoded offsets. Each patch declares an anchor point—identified by instruction patterns, call-graph context, or string references—and a payload generated on-the-fly using Keystone for ARM64 assembly encoding.

The central orchestration happens in scripts/patchers/cfw.py, which loads target-specific patch modules based on your build command. Post-application, the framework re-disassembles modified regions to verify byte-level accuracy against expected patterns.

Build Targets and Patch Layers

Build Command	Patches Applied
make fw_patch	Base security patches only
make fw_patch_jb	Base + jailbreak-specific patches
make fw_patch_exp	Base + jailbreak + experimental patches

---

Base Security Patches (All Variants)

These 22+ kernel hardening patches are unconditionally applied to every firmware variant. They stabilize virtualized execution, close kernel-level attack vectors, and prepare the system for further customization.

VM and Memory Protections

• patch_vm_map_protect — Protects the VM map structure from illegal writes. Prevents kernel corruption through malformed memory operations. See research/kernel_patch_jb/patch_vm_map_protect.md.

• patch_vm_map_delete_immutable_code — Blocks deletion of immutable code pages, preserving code integrity during execution.

• patch_vm_fault_enter_prepare — Stabilizes page fault handling pathways, reducing kernel panics under virtualization.

• patch_convert_port_to_map — Corrects port-to-map conversion logic in Mach IPC paths.

Thread and Task Management

• patch_thread_set_state — Resolves edge cases in thread_set_state that cause instability in virtualized thread contexts.

• patch_task_for_pid — Improves task lookup safety, hardening the interface used for process inspection.

• patch_task_conversion_eval_internal — Fixes internal conversion evaluation logic in task port operations.

Security Policy and Sandbox

• patch_proc_security_policy — Strengthens process security policy enforcement.

• patch_proc_pidinfo — Repairs PID-info retrieval paths that break under virtualization.

• patch_sandbox_hooks_extended — Expands sandbox hook coverage for comprehensive policy enforcement.

• patch_hook_cred_label_update_execve — Refines credential label updates during execve transitions.

• patch_cred_label_update_execve — Secondary credential-label fix for corner cases.

System Call and Spawn Handling

• patch_syscallmask_apply_to_proc — Tightens syscall mask application to process structures.

• patch_spawn_validate_persona — Validates spawn personas before process creation.

• patch_bsd_init_auth — Authenticates BSD init procedures, preventing early-boot compromise.

I/O and Filesystem

• patch_shared_region_map — Secures shared region mapping used by dynamic libraries.

• patch_dounmount — Corrects unmount handling to prevent filesystem corruption.

• patch_mac_mount — Patches MAC (Mandatory Access Control) mount validation.

• patch_io_secure_bsd_root — Secures BSD root I/O paths against unauthorized access.

• patch_iouc_failed_macf — Mitigates I/OUC (I/O User Client) MAC framework failures.

Miscellaneous Hardening

• patch_nvram_verify_permission — Hardens NVRAM permission checks against bypass attempts.

• patch_load_dylinker — Fixes dynamic linker load path validation.

• patch_kcall10 — Patches KCALL helper used for kernel function invocation.

Each base patch is documented in research/kernel_patch_base_*.md files with validation reports covering batches of patches (first 5, 11–15, 16–20, etc.).

---

Jailbreak-Specific Patches (jb and exp Variants)

When building with make fw_patch_jb or make fw_patch_exp, vphone-cli applies 6 additional patches that bypass Apple's code signing and entitlement enforcement. These enable execution of unsigned binaries and expose kernel hooks required by jailbreak runtimes.

AMFI Trust Cache Bypasses

patch_amfi_cdhash_in_trustcache (A1) — The cornerstone jailbreak patch. Forces every CDHash trust-cache query to succeed unconditionally, allowing non-Apple binaries to pass AMFI (Apple Mobile File Integrity) code-signing verification. Implemented in scripts/patchers/kernel_jb_patch_amfi_trustcache.py. See research/kernel_patch_jb/patch_amfi_cdhash_in_trustcache.md.

patch_amfi_trustcache (A1 entry stub) — Returns success unconditionally for trust-cache membership checks, neutralizing the primary code-signing enforcement point.

patch_amfi_execve_kill_path — Neutralizes the "kill" path of execve, preventing process termination when unsigned code is detected.

Process Security Relaxations

patch_proc_security_policy — Relaxes security policy enforcement specifically for jailbroken processes, enabling necessary permissions without full entitlement validation.

patch_proc_pidinfo — Adapts PID-info retrieval to handle unsigned processes correctly.

patch_task_for_pid — Opens task lookup interfaces for jailbroken tasks, allowing debugging and inspection tools to function.

All jailbreak patches are catalogued in research/kernel_patch_jb/*.md with detailed behavioral analysis and security implications.

---

Experimental Patches (exp Variant Only)

The experimental firmware variant (make fw_patch_exp) adds three hypervisor-level patches that make the virtual machine appear less synthetic to Apple services while preserving VM-specific performance optimizations.

Hypervisor and Device Identity

patch_hv_vmm_rootfs — Remaps the root filesystem for hypervisor contexts, spoofing physical device layout. Documented in research/kernel_patch_jb/patch_hv_vmm_rootfs.md.

patch_hv_vmm_dsc — Patches the DSC (Device Support Component) to spoof device identity characteristics, reducing service-side flagging of virtualized environments.

patch_hv_vmm — Broad hypervisor-level modifications that adjust VMM behavior to mimic bare-metal execution patterns.

These patches target scenarios requiring interaction with Apple services that employ VM-detection heuristics.

---

Patching Framework Implementation

The vphone-cli patch system combines multiple open-source components for robust, version-agnostic kernel modification.

Core Files and Responsibilities

File	Purpose
scripts/patchers/cfw.py	Central orchestration: discovers patch modules, validates anchors, writes patches, verifies results
scripts/patchers/cfw_asm.py	Keystone wrapper for ARM64 instruction generation via asm() helper
scripts/patchers/kernel_jb_patch_amfi_trustcache.py	A1 trust-cache bypass implementation
scripts/patchers/kernel_jb_patch_base.py	Base security patch definitions
research/0_binary_patch_comparison.md	Cross-variant patch matrix

Semantic Matching Process

1. Anchor Discovery: Each patch module defines byte patterns, instruction sequences, or string references that uniquely identify the target location.

2. Capstone Validation: The framework disassembles candidate regions using Capstone to confirm semantic equivalence across kernel versions.

3. Keystone Assembly: Patch payloads are generated dynamically for the target architecture, ensuring correct encoding.

4. Runtime Verification: Modified regions are re-disassembled and checked against expected patterns. See research/kernel_patch_jb/runtime_verification/README.md.

---

Verifying Applied Patches

After booting a patched kernel, confirm patch activation via kernel logging:

# Check for AMFI trust-cache patch activation

log show --predicate 'eventMessage contains "patched_amfi_is_cdhash_in_trustcache"'

# General patch verification

dmesg | grep -i "patch"

Build artifacts include a patched kernelcache file consumed by the VM bootloader. Patch application logs are emitted during the make process, showing each matched anchor and verification status.

---

Summary

• vphone-cli kernel patches operate in three layers: base security (all builds), jailbreak bypasses (jb/exp builds), and experimental hypervisor spoofing (exp only)

• Base patches harden VM execution through 22+ fixes for memory protection, task management, sandboxing, and I/O security

• Jailbreak patches neutralize AMFI code-signing via forced trust-cache success, enabling unsigned binary execution

• Experimental patches spoof device identity to reduce VM detection by Apple services

• Implementation relies on semantic matching with Capstone, Keystone assembly generation, and runtime verification—all orchestrated through scripts/patchers/cfw.py

• Documentation for each patch exists in research/kernel_patch_jb/*.md with validation reports in research/kernel_patch_base_*.md

---

Frequently Asked Questions

What kernel versions are compatible with vphone-cli patches?

vphone-cli uses semantic matching rather than hardcoded offsets, making patches resilient across kernel versions. The Capstone-based anchor discovery analyzes instruction shapes and call-graph context to locate targets regardless of minor version shifts. Specific kernelcache samples used for validation are noted in individual research/ documentation files.

How does the A1 trust-cache patch bypass code signing?

The patch_amfi_cdhash_in_trustcache modification forces every CDHash query to return success unconditionally. Normally, AMFI checks whether a binary's cryptographic hash exists in Apple's trust cache or is signed with a valid Apple certificate. By short-circuiting this check at kernel_jb_patch_amfi_trustcache.py, any binary—regardless of signature—appears trusted to the kernel's enforcement layer.

Can I apply patches manually without using the Makefile targets?

Yes. Import the patching framework directly from scripts/patchers/cfw.py and invoke the patch orchestration with a custom target configuration. The cfw.py module accepts patch module paths and kernelcache locations as parameters, enabling programmatic use outside the standard build flow. See inline documentation in cfw.py for the apply_patches() interface.

Where are the security implications of each patch documented?

Every patch has a dedicated markdown file in research/kernel_patch_jb/ describing its purpose, implementation mechanism, and security trade-offs. Additionally, research/0_binary_patch_comparison.md provides a matrix comparing patch sets across the four build variants (regular, development, jailbreak, experimental).

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}