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

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 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, 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, 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, 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, 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, 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:

• 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, 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, 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, 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, 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 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:

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:

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

For debugging individual patches:

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

Summary

• KernelPatcher in 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, 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.

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