How Frida Stalker Kernel Relaxations Work in vphone-cli: iOS CloudOS Patching Explained

Frida Stalker kernel relaxations in vphone-cli are two optional kernel patches—patchThreadSetStateEntitlementFlag and patchVmMapDeleteImmutableCode—that enable Frida's dynamic instrumentation on iOS cloudOS by disabling entitlement checks and allowing repeated code mapping overwrites, activated exclusively via the --frida CLI flag.

vphone-cli is an open-source virtualization tool for managing iOS cloudOS instances. The implementation of Frida Stalker kernel relaxations within this repository demonstrates a sophisticated approach to kernel modification, allowing security researchers to utilize Frida's advanced tracing capabilities on virtualized iOS kernels by selectively disabling specific hardening mechanisms.

What Are Frida Stalker Kernel Relaxations?

Frida Stalker is Frida's code tracing engine, which requires low-level kernel cooperation to modify thread states and remap executable memory regions. Standard iOS cloudOS kernels enforce strict entitlement checks and immutable code mappings that prevent Stalker from functioning properly.

The vphone-cli project addresses these limitations through conditional kernel patching. When enabled, the system applies two specific binary patches to the kernel image before boot. These modifications are not applied by default; they require explicit user opt-in through the command-line interface and are only compatible with cloudOS kernel versions 26.4 and later.

The Two Kernel Patches Explained

patchThreadSetStateEntitlementFlag (Thread State Control)

Located in sources/FirmwarePatcher/Kernel/JBPatches/KernelJBPatchThreadSetState.swift, this patch modifies how the kernel handles thread_set_state_from_user calls.

The standard kernel requires the TSSF_CHECK_ENTITLEMENT flag (bit 0x200) to be set, which forces a code-signing entitlement check before a debugger can modify thread registers. The patch alters the ARM64 instruction from mov w6, #0x201 to mov w6, #0x1, effectively clearing the 0x200 bit.

This change allows Frida Stalker to update existing thread registers without possessing the restricted com.apple.private.thread-set-state entitlement, which is unavailable to third-party developers on standard iOS configurations.

patchVmMapDeleteImmutableCode (Memory Mapping Protection)

Found in sources/FirmwarePatcher/Kernel/JBPatches/KernelJBPatchVmMapDelete.swift, this patch enables Frida's "write-then-flip" re-instrumentation strategy.

The standard _vm_map_delete implementation guards against immutable code by checking the current execution protection bit (bit 9). This prevents rewriting memory pages marked as executable. The patch retargets this guard to check the maximum protection bit (bit 13) instead.

By checking max protection rather than current protection, the kernel allows Frida to allocate memory as readable/writable initially, write instrumentation code, then flip permissions to executable repeatedly—a pattern essential for Stalker's dynamic code generation.

How to Enable Frida Support in vphone-cli

Using the --frida Command-Line Flag

The primary interface for activating these kernel relaxations is the --frida flag, defined across multiple CLI entry points:

• VPhoneVMCreateCLI.swift: Defines @Flag(name: .customLong("frida")) for new VM creation
• VPhoneFWCLI.swift: Provides the flag for firmware patching operations
• VPhoneCLI.swift: Forwards the flag to the top-level orchestrator

To create a new VM with Frida support:

# JB variant with Stalker support

vphone-cli vm create MyResearchVM --variant jb --frida

# EXP variant with Stalker support  

vphone-cli vm create MyResearchVM --variant exp --frida

To patch an existing VM's firmware:

vphone-cli fw patch MyExistingVM -V jb --frida

The Internal Flag Propagation Flow

When --frida is specified, the value propagates through several architectural layers before reaching the kernel patcher:

1. Orchestrator Assignment: VPhoneCreateOrchestrator.swift receives the flag as enableFrida and exports it as the environment variable VPHONE_FRIDA=1 for subsequent build scripts.

2. Capability Check: FirmwarePipeline.swift validates whether the target cloudOS kernel version supports Frida patches. It stores this in cloudOSIsFridaCapable and computes the final boolean applyFrida = enableFrida && cloudOSIsFridaCapable. This check ensures patches are only applied to compatible kernels (version 26.4+).

3. Patch Application: KernelJBPatcher.swift contains the applyFrida property. When true, it executes:

if applyFrida {
    patchThreadSetStateEntitlementFlag()
    patchVmMapDeleteImmutableCode()
}

Automatic Frida Server Installation

Beyond kernel patching, the --frida flag triggers the automated installation of the Frida iOS server. The orchestrator sets VPHONE_FRIDA=1 in the environment, which signals scripts/fetch_debs.sh to download the latest re.frida.server deb package from the official repositories.

During the VM's first boot sequence, the provisioning scripts cfw_install_jb.sh or cfw_install_exp.sh detect this environment variable and install the Frida server deb during the "extra-debs" installation stage, ensuring the userspace components match the relaxed kernel environment.

Summary

• Frida Stalker kernel relaxations consist of two specific patches: one clearing the thread_set_state entitlement check and another retargeting the immutable code guard in _vm_map_delete.
• These patches are implemented in KernelJBPatchThreadSetState.swift and KernelJBPatchVmMapDelete.swift respectively.
• Activation requires the --frida CLI flag, available in VPhoneVMCreateCLI.swift and VPhoneFWCLI.swift.
• The system applies a version check in FirmwarePipeline.swift to ensure compatibility with cloudOS kernels 26.4 and newer.
• The flag also triggers automatic download and installation of the Frida iOS server via fetch_debs.sh and the installation orchestrators.

Frequently Asked Questions

What kernel versions support Frida Stalker relaxations in vphone-cli?

Only cloudOS kernel versions 26.4 and later support Frida Stalker relaxations. The FirmwarePipeline.swift file explicitly checks the kernel version and sets cloudOSIsFridaCapable accordingly; attempting to use --frida on older kernels will not apply the patches even if the flag is specified.

Can I apply Frida patches to an existing VM without recreating it?

Yes. Use the vphone-cli fw patch command with the --frida flag on your existing VM. The VPhoneFWCLI.swift interface supports this operation, allowing you to re-patch the firmware image without destroying the virtual machine's data or configuration.

Why does the thread_set_state patch specifically target the 0x200 bit?

The 0x200 value corresponds to TSSF_CHECK_ENTITLEMENT. By clearing this specific bit in the flags register (w6), the patch forces the kernel to skip the code-signing entitlement verification normally required for thread_set_state_from_user. This is the minimum modification necessary to grant Frida Stalker register access without possessing Apple's private entitlements.

How does the vm_map_delete patch enable Stalker's "write-then-flip" pattern?

Frida Stalker repeatedly writes new instrumentation code to memory and then changes its permissions to executable. The standard kernel prevents this by checking if a page is currently executable (bit 9) before allowing deletion or remapping. The patch changes this to check the maximum protection (bit 13), which remains RW-max-RWX, allowing the memory to be rewritten and re-protected indefinitely during instrumentation sessions.

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