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

> Understand Frida Stalker kernel relaxations in vphone-cli. Learn how these patches disable entitlement checks and enable dynamic instrumentation on iOS cloudOS via the --frida flag.

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

---

**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`](https://github.com/Lakr233/vphone-cli/blob/main/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`](https://github.com/Lakr233/vphone-cli/blob/main/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`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneVMCreateCLI.swift)**: Defines `@Flag(name: .customLong("frida"))` for new VM creation
- **[`VPhoneFWCLI.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneFWCLI.swift)**: Provides the flag for firmware patching operations
- **[`VPhoneCLI.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneCLI.swift)**: Forwards the flag to the top-level orchestrator

To create a new VM with Frida support:

```bash

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

```bash
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`](https://github.com/Lakr233/vphone-cli/blob/main/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`](https://github.com/Lakr233/vphone-cli/blob/main/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`](https://github.com/Lakr233/vphone-cli/blob/main/KernelJBPatcher.swift) contains the `applyFrida` property. When true, it executes:

```swift
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`](https://github.com/Lakr233/vphone-cli/blob/main/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`](https://github.com/Lakr233/vphone-cli/blob/main/cfw_install_jb.sh) or [`cfw_install_exp.sh`](https://github.com/Lakr233/vphone-cli/blob/main/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`](https://github.com/Lakr233/vphone-cli/blob/main/KernelJBPatchThreadSetState.swift) and [`KernelJBPatchVmMapDelete.swift`](https://github.com/Lakr233/vphone-cli/blob/main/KernelJBPatchVmMapDelete.swift) respectively.
- Activation requires the `--frida` CLI flag, available in [`VPhoneVMCreateCLI.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneVMCreateCLI.swift) and [`VPhoneFWCLI.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneFWCLI.swift).
- The system applies a version check in [`FirmwarePipeline.swift`](https://github.com/Lakr233/vphone-cli/blob/main/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`](https://github.com/Lakr233/vphone-cli/blob/main/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`](https://github.com/Lakr233/vphone-cli/blob/main/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`](https://github.com/Lakr233/vphone-cli/blob/main/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.