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

> Explore the three kernel patch layers vphone-cli applies: base hardening, AMFI bypasses, and hypervisor spoofing. Understand layered security for your device.

- Repository: [Lakr/vphone-cli](https://github.com/Lakr233/vphone-cli)
- Tags: deep-dive
- Published: 2026-09-06

---

**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](https://github.com/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](https://www.keystone-engine.org/) for ARM64 assembly encoding.

The central orchestration happens in [`scripts/patchers/cfw.py`](https://github.com/Lakr233/vphone-cli/blob/main/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`](https://github.com/Lakr233/vphone-cli/blob/main/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`](https://github.com/Lakr233/vphone-cli/blob/main/scripts/patchers/kernel_jb_patch_amfi_trustcache.py). See [`research/kernel_patch_jb/patch_amfi_cdhash_in_trustcache.md`](https://github.com/Lakr233/vphone-cli/blob/main/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`](https://github.com/Lakr233/vphone-cli/blob/main/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`](https://github.com/Lakr233/vphone-cli/blob/main/scripts/patchers/cfw.py) | Central orchestration: discovers patch modules, validates anchors, writes patches, verifies results |
| [`scripts/patchers/cfw_asm.py`](https://github.com/Lakr233/vphone-cli/blob/main/scripts/patchers/cfw_asm.py) | Keystone wrapper for ARM64 instruction generation via `asm()` helper |
| [`scripts/patchers/kernel_jb_patch_amfi_trustcache.py`](https://github.com/Lakr233/vphone-cli/blob/main/scripts/patchers/kernel_jb_patch_amfi_trustcache.py) | A1 trust-cache bypass implementation |
| [`scripts/patchers/kernel_jb_patch_base.py`](https://github.com/Lakr233/vphone-cli/blob/main/scripts/patchers/kernel_jb_patch_base.py) | Base security patch definitions |
| [`research/0_binary_patch_comparison.md`](https://github.com/Lakr233/vphone-cli/blob/main/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](https://www.capstone-engine.org/) 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`](https://github.com/Lakr233/vphone-cli/blob/main/research/kernel_patch_jb/runtime_verification/README.md).

---

## Verifying Applied Patches

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

```bash

# 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`](https://github.com/Lakr233/vphone-cli/blob/main/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`](https://github.com/Lakr233/vphone-cli/blob/main/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`](https://github.com/Lakr233/vphone-cli/blob/main/scripts/patchers/cfw.py) and invoke the patch orchestration with a custom target configuration. The [`cfw.py`](https://github.com/Lakr233/vphone-cli/blob/main/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`](https://github.com/Lakr233/vphone-cli/blob/main/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`](https://github.com/Lakr233/vphone-cli/blob/main/research/0_binary_patch_comparison.md) provides a matrix comparing patch sets across the four build variants (regular, development, jailbreak, experimental).