# Base Kernel Patches Applied by KernelPatcher in vphone-cli: Complete Technical Reference

> Discover the 26 base kernel patches applied by KernelPatcher in vphone-cli. Learn how it disables security gates for virtualization and jailbreak.

- Repository: [Lakr/vphone-cli](https://github.com/Lakr233/vphone-cli)
- Tags: api-reference
- Published: 2026-08-31

---

**The `KernelPatcher` in Lakr233/vphone-cli applies 26 deterministic binary-level patches to the pre-linked iOS kernelcache, systematically disabling security gates including APFS snapshot verification, AMFI launch constraints, sandbox policies, and debugger detection to unlock the kernel for virtualization and jailbreak scenarios.**

The `KernelPatcher` serves as the core orchestrator that migrated original Python firmware-patching logic into Swift for the vphone-cli project. Operating directly on the iOS kernelcache binary, it executes a fixed sequence of modifications that neutralize kernel-level protections without requiring runtime dependencies. This guide examines all base kernel patches applied by the `KernelPatcher` and their specific implementations within the codebase.

## KernelPatcher Architecture and Orchestration

The `KernelPatcher` class defined in [`sources/FirmwarePatcher/Kernel/KernelPatcher.swift`](https://github.com/Lakr233/vphone-cli/blob/main/sources/FirmwarePatcher/Kernel/KernelPatcher.swift) functions as the central dispatcher for binary modifications. Before applying patches, the orchestrator performs four initialization steps: parsing the Mach-O structure to build sections and symbols, constructing ADRP/BL instruction indexes for rapid lookup, locating the `_panic` symbol required by multiple patches, and sequentially executing each patch method in `findAll()`.

All patch implementations reside as extension methods under `sources/FirmwarePatcher/Kernel/Patches/`. Each patch returns a Boolean indicating success, with the orchestrator continuing execution unless encountering fatal errors. The modifications are strictly **NOP-based** or use simple instruction replacements like `mov w0, #0; ret`, ensuring they are idempotent and self-contained.

## The 26 Base Kernel Patches Applied by KernelPatcher

The `findAll()` method invokes the following patches in strict order:

### 1. APFS Root Snapshot Patch (`patchApfsRootSnapshot`)

Located in [`sources/FirmwarePatcher/Kernel/Patches/KernelPatchApfsSnapshot.swift`](https://github.com/Lakr233/vphone-cli/blob/main/sources/FirmwarePatcher/Kernel/Patches/KernelPatchApfsSnapshot.swift), this patch NOPs the `tbnz/tbz … #5` instruction that triggers a panic when mounting a sealed-volume root snapshot in `_apfs_vfsop_mount`.

### 2. APFS Seal Verification Patch (`patchApfsSealBroken`)

Implemented in [`sources/FirmwarePatcher/Kernel/Patches/KernelPatchApfsSeal.swift`](https://github.com/Lakr233/vphone-cli/blob/main/sources/FirmwarePatcher/Kernel/Patches/KernelPatchApfsSeal.swift), this neutralizes the conditional branch leading to the "root volume seal is broken" panic within `_authapfs_seal_is_broken`.

### 3. BSD Init Rootvp Patch (`patchBsdInitRootvp`)

Found in [`sources/FirmwarePatcher/Kernel/Patches/KernelPatchBsdInit.swift`](https://github.com/Lakr233/vphone-cli/blob/main/sources/FirmwarePatcher/Kernel/Patches/KernelPatchBsdInit.swift), this modification NOPs the branch guarding the "rootvp not authenticated after mounting" panic in `_bsd_init`.

### 4-5. Launch Constraints Patch (`patchLaunchConstraints`)

From [`sources/FirmwarePatcher/Kernel/Patches/KernelPatchLaunchConstraints.swift`](https://github.com/Lakr233/vphone-cli/blob/main/sources/FirmwarePatcher/Kernel/Patches/KernelPatchLaunchConstraints.swift), this stubs the AMFI helper `_proc_check_launch_constraints` with `mov w0, #0; ret`, forcing launch-constraint checks to always succeed.

### 6-7. Debugger Detection Patch (`patchDebugger`)

In [`sources/FirmwarePatcher/Kernel/Patches/KernelPatchDebugger.swift`](https://github.com/Lakr233/vphone-cli/blob/main/sources/FirmwarePatcher/Kernel/Patches/KernelPatchDebugger.swift), this disables the kernel-debugger gate by NOP-ing the branch that would abort boot if `debugger_enabled` is detected.

### 8-9. Post-Validation Patches (`patchPostValidationNOP` and `patchPostValidationCMP`)

Both located in [`sources/FirmwarePatcher/Kernel/Patches/KernelPatchPostValidation.swift`](https://github.com/Lakr233/vphone-cli/blob/main/sources/FirmwarePatcher/Kernel/Patches/KernelPatchPostValidation.swift):

- **Patch 8**: Replaces a gate in `_post_validation` with a plain `nop` to maintain function reachability.
- **Patch 9**: NOPs a `cmp`-based rejection that causes kernel panic on mismatched code signatures.

### 10-11. Dyld Policy Patch (`patchDyldPolicy`)

In [`sources/FirmwarePatcher/Kernel/Patches/KernelPatchDyldPolicy.swift`](https://github.com/Lakr233/vphone-cli/blob/main/sources/FirmwarePatcher/Kernel/Patches/KernelPatchDyldPolicy.swift), this forces the dyld policy check to always return success by NOP-ing the conditional branch in `_dyld_process_init`.

### 12. APFS Graft Patch (`patchApfsGraft`)

From [`sources/FirmwarePatcher/Kernel/Patches/KernelPatchApfsGraft.swift`](https://github.com/Lakr233/vphone-cli/blob/main/sources/FirmwarePatcher/Kernel/Patches/KernelPatchApfsGraft.swift), this rewrites the APFS "graft" stub to allow mounting hybrid cloudOS/iPhone filesystems.

### 13-15. APFS Mount Patches (`patchApfsMount`)

In [`sources/FirmwarePatcher/Kernel/Patches/KernelPatchApfsMount.swift`](https://github.com/Lakr233/vphone-cli/blob/main/sources/FirmwarePatcher/Kernel/Patches/KernelPatchApfsMount.swift), these adjustments add a missing `ldr` workaround to the APFS mount flow, preventing "mount failed" guards when loading hybrid filesystems.

### 16-25. Sandbox Policy Patches (`patchSandbox`)

Spanning [`sources/FirmwarePatcher/Kernel/Patches/KernelPatchSandbox.swift`](https://github.com/Lakr233/vphone-cli/blob/main/sources/FirmwarePatcher/Kernel/Patches/KernelPatchSandbox.swift), these ten patches neutralize MAC-policy checks including `sandbox_check` and `sandbox_check_by_audit_token`, unblocking privileged operations inside the virtual machine.

### 26. EXC Guard Behavior Patch (`patchExcGuardBehavior`)

Optional patch in [`sources/FirmwarePatcher/Kernel/Patches/KernelPatchExcGuard.swift`](https://github.com/Lakr233/vphone-cli/blob/main/sources/FirmwarePatcher/Kernel/Patches/KernelPatchExcGuard.swift) that disables the **EXC_GUARD** Mach-port guard on iOS 18 kernels. This executes only when the `isDev` parameter is `true` or when the pipeline explicitly sets `applyExcGuard`.

## Implementing KernelPatcher in Swift Code

The following examples demonstrate practical usage of the `KernelPatcher` class from the vphone-cli codebase.

To apply all base patches to a kernelcache:

```swift
import FirmwarePatcher

// Load pre-linked kernelcache from .kernelcache file
let kernelData = try Data(contentsOf: URL(fileURLWithPath: "kernelcache.release"))

// Initialize with verbose logging
let patcher = KernelPatcher(data: kernelData, verbose: true)

// Apply all 26 base patches in sequence
let appliedCount = try patcher.apply()
print("✅ Applied \(appliedCount) base kernel patches")

```

To force the optional EXC_GUARD patch without the development flag:

```swift
let patcher = KernelPatcher(
    data: kernelData,
    verbose: true,
    isDev: false,
    applyExcGuard: true  // Force EXC_GUARD disable
)
let count = try patcher.apply()

```

For debugging individual patches:

```swift
// Apply single patch and check success
let success = patcher.patchApfsRootSnapshot()

```

## Summary

- **KernelPatcher** in [`sources/FirmwarePatcher/Kernel/KernelPatcher.swift`](https://github.com/Lakr233/vphone-cli/blob/main/sources/FirmwarePatcher/Kernel/KernelPatcher.swift) orchestrates 26 binary-level base kernel patches to unlock iOS kernels for virtualization.
- **Patches 1-15** focus on APFS integrity, BSD initialization, AMFI launch constraints, and dyld policies, removing filesystem and boot authentication gates.
- **Patches 16-25** neutralize the Sandbox MAC framework via [`sources/FirmwarePatcher/Kernel/Patches/KernelPatchSandbox.swift`](https://github.com/Lakr233/vphone-cli/blob/main/sources/FirmwarePatcher/Kernel/Patches/KernelPatchSandbox.swift), eliminating privileged operation restrictions.
- **Patch 26** optionally disables EXC_GUARD on iOS 18 when development mode is enabled via `isDev` or `applyExcGuard` flags.
- All modifications use **NOP replacements** or register moves, ensuring zero runtime dependencies and safe reapplication via `PatchRecord` tracking.

## Frequently Asked Questions

### What is the purpose of KernelPatcher in vphone-cli?

The `KernelPatcher` converts legacy Python firmware-patching logic into Swift to modify pre-linked iOS kernelcache binaries. It removes security mechanisms that prevent the kernel from running inside Apple's Virtualization framework or accepting jailbreak modifications, effectively unlocking the base kernel patches required for virtualization.

### How many base patches does KernelPatcher apply by default?

By default, `KernelPatcher.apply()` executes 25 base patches. The 26th patch (`patchExcGuardBehavior`) is conditional and only applies when the `isDev` parameter is `true` or `applyExcGuard` is explicitly set to `true` during initialization.

### Are KernelPatcher modifications reversible?

Individual patch applications are tracked through `PatchRecord` objects within the framework, allowing verification of which modifications were applied. However, the patches themselves are destructive binary edits consisting of NOPs and instruction overwrites, so reversing requires maintaining a backup of the original kernelcache file prior to patching.

### What file format does KernelPatcher expect as input?

The `KernelPatcher` class accepts raw `Data` objects representing pre-linked Mach-O kernelcache files, typically extracted from IPSW firmware as `kernelcache.release` or similar variants. The binary must be decrypted and decompressed before initialization, as the patcher operates directly on the executable code sections.