How iOS 27 Specific Kernel Patches Are Gated in vphone-cli

vphone-cli gates iOS 27-specific kernel patches through a three-layer system involving automatic base version detection, CLI flag propagation, and conditional execution blocks in the kernel patcher.

The vphone-cli repository provides a virtualization toolchain for running iOS on Apple Silicon Macs, supporting multiple iOS base versions including 18.x, 26.x, and 27.x. Because certain jailbreak-oriented kernel patches only remain compatible when the guest userland runs iOS 27 atop the 26.4 vphone600 host kernel, the codebase implements a strict gate mechanism to prevent these patches from breaking older iOS 26.x VMs. Understanding how iOS 27 specific kernel patches are gated in vphone-cli ensures safe firmware modification across different iOS generations.

Base Version Detection in FirmwarePipeline

The gating process begins with automatic version identification during the firmware pipeline initialization. In sources/FirmwarePatcher/Pipeline/FirmwarePipeline.swift, the FirmwarePipeline class reads the product version directly from the restore directory using Self.readBaseProductVersion to determine the target iOS version.

The pipeline sets a Boolean flag iosBaseIs27 by checking if the base version string starts with "27":

iosBaseIs27 = baseVersion?.hasPrefix("27.")

This detection occurs at lines 34-40 in FirmwarePipeline.swift. When the pipeline executes patchAll(), it propagates this Boolean through to each KernelJBPatcher instance via a factory closure, ensuring the iOS 27-specific patches only activate when the base image actually requires them.

CLI Flag Propagation via --target-os

For standalone patch operations outside the full pipeline, vphone-cli exposes a command-line interface that allows explicit version targeting. In sources/vphone-cli/VPhoneCLI.swift, the parser handles the --target-os argument to manually set the iOS version context.

The CLI logic maps the --target-os value to the internal applyIOS27 property using a prefix check:

targetOS.map { $0.hasPrefix("27.") } ?? true

This implementation appears at lines 63-68 in VPhoneCLI.swift. If the user omits the --target-os flag, the default value evaluates to true, applying the full patch set including iOS 27 modifications—a behavior optimized for development and testing scenarios. Explicitly passing --target-os 26.5 forces the parser to return false, effectively disabling the iOS 27-specific gates.

KernelJBPatcher Gate Implementation

The actual enforcement of iOS 27 specific kernel patches occurs in sources/FirmwarePatcher/Kernel/KernelJBPatcher.swift, where the KernelJBPatcher class implements the final execution barrier.

The applyIOS27 Property

The patcher exposes a public applyIOS27 property that defaults to false (lines 24-25), creating a secure-by-default posture that prevents accidental application of incompatible patches. This property acts as the master switch for all version-specific modifications.

Conditional Patch Methods

All iOS 27-exclusive patches reside within conditional blocks checking if applyIOS27 { … }. These protected patches include critical system modifications such as:

• patchIoucFailedSandbox() – Modifies sandbox policy enforcement
• patchDiskImages2ClientAbi() – Adjusts disk image client ABI handling
• patchExecSecurityPolicyKill() – Alters executable security policy termination

The specific implementation at lines 43-55 and 89-108 demonstrates how each method first validates the gate before executing binary patches. For example, patchExecSecurityPolicyKill() only modifies the kernel's security policy structures when applyIOS27 evaluates to true, preventing execution kills on incompatible iOS 26.x bases where such patches would corrupt the VM's stability.

Programmatic Pipeline Usage

When integrating vphone-cli as a library rather than a command-line tool, developers interact with the gate mechanism through the FirmwarePipeline constructor:

let pipeline = FirmwarePipeline(
    vmDirectory: vmDir,
    restoreDirectory: restoreDir,
    variant: .jb,
    forceExcGuard: false,
    enableFrida: false
)
pipeline.patchAll()   // applyIOS27 is set automatically from base version

During patchAll() execution (lines 36-38 in FirmwarePipeline.swift), the pipeline captures the applyIOS27 value and injects it into each KernelJBPatcher instance through the factory closure: p.applyIOS27 = applyIOS27.

To execute standalone kernel patching with explicit version control:

# Apply iOS 27 patches (default behavior)

vphone-cli patch-component kernel-jb \
    --input /path/to/kernelcache \
    --output /path/to/patched_kernelcache

# Skip iOS 27 patches for iOS 26 compatibility

vphone-cli patch-component kernel-jb \
    --input /path/to/kernelcache \
    --output /path/to/patched_kernelcache \
    --target-os 26.5

Summary

• Version Detection: FirmwarePipeline.swift automatically detects iOS 27 bases via readBaseProductVersion and the hasPrefix("27.") check.
• CLI Override: The --target-os flag in VPhoneCLI.swift allows manual control over the applyIOS27 Boolean when running patch-component commands.
• Safe Defaults: KernelJBPatcher.swift initializes applyIOS27 to false, preventing accidental application of incompatible patches.
• Conditional Execution: All iOS 27-specific modifications, including sandbox patches and security policy alterations, execute only within if applyIOS27 gated blocks.
• Automatic Propagation: The full pipeline automatically synchronizes the gate value across all patcher instances during patchAll() execution.

Frequently Asked Questions

What happens if I apply iOS 27 patches to an iOS 26 base?

Applying iOS 27 specific patches such as patchIoucFailedSandbox() or patchExecSecurityPolicyKill() to an iOS 26.x base will break the VM. These patches modify kernel structures like IOMFB SwapEnd size checks and sandbox gates that differ between iOS versions, causing kernel panics or security policy violations when the binary layout does not match the expected iOS 27 format.

How does vphone-cli detect the iOS version automatically?

The tool detects the version through FirmwarePipeline.readBaseProductVersion, which extracts the product version string from the restore directory metadata. It then sets iosBaseIs27 using a prefix match against "27.", propagating this Boolean through the pipeline to each KernelJBPatcher instance during initialization.

Can I force iOS 27 patches to run on a different version?

Yes, though not recommended for production VMs. When using the CLI, omitting --target-os defaults applyIOS27 to true, applying all patches regardless of base version. For programmatic control, manually instantiate KernelJBPatcher and set applyIOS27 = true before calling patch methods, but expect compatibility issues when running on non-27 bases.

Which specific kernel patches are gated by applyIOS27?

The gated patches include patchIoucFailedSandbox() for modifying sandbox failure handling, patchDiskImages2ClientAbi() for disk image client adjustments, and patchExecSecurityPolicyKill() for altering executable security termination policies. All reside in KernelJBPatcher.swift and execute only when the applyIOS27 property evaluates to true.

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