What Are the fw_patch_jb, fw_patch_dev, and fw_patch_exp Make Targets in vphone-cli?

The fw_patch_jb, fw_patch_dev, and fw_patch_exp targets in the Lakr233/vphone-cli Makefile invoke the Swift-based firmware patcher with distinct --variant flags (jb, dev, and exp) to generate jailbreak, development, or experimental custom firmware images for virtual iPhone environments.

These three make targets provide a reproducible build pipeline for modifying iPhone firmware components (iBSS, iBEC, LLB, kernel, and TrustZone modules) before installation. According to the vphone-cli source code, each target applies a specific combination of binary patches to the boot chain, allowing researchers to choose between debugging features, jailbreak utilities, or anti-detection experimental modifications.

Understanding the Firmware Patch Variants

The vphone-cli tool supports four patch variants (regular, dev, jb, and exp), but the Makefile exposes three primary targets that cover the most common research scenarios. The patcher binary—defined as $(PATCHER_BINARY) in the Makefile—executes the patch-firmware subcommand with the appropriate --variant argument to determine which modules are loaded from sources/vphone-cli/VPhoneFWCLI.swift.

fw_patch_jb (Jailbreak Variant)

The fw_patch_jb target generates a jailbroken custom firmware by passing --variant jb to the patcher. This variant starts from the regular boot chain, applies the development TXM (Test-Execution-Mode) patches, and then adds jailbreak-specific extensions including:

• Jetsam memory limit fixes to prevent process termination in constrained VM environments
• Procursus package manager integration and base binaries
• Optional --force-exc-guard to bypass EXC_GUARD protections
• Optional --frida flag to enable Frida-based kernel relaxations for dynamic instrumentation

Use this target when you need a functional jailbreak environment with standard debugging hooks.

fw_patch_dev (Development Variant)

The fw_patch_dev target applies only the development TXM patches by using --variant dev. Unlike the jailbreak variant, this mode excludes all jailbreak-related modifications (no Procursus, no jetsam bypasses, no base binary injections).

This target is intended for security researchers who require the extra debugging hooks and research-oriented TXM patches without altering the system’s runtime integrity with jailbreak artifacts. The resulting firmware boots in a development mode suitable for low-level analysis.

fw_patch_exp (Experimental Variant)

The fw_patch_exp target builds upon the jailbreak foundation and adds anti-virtualization patches designed to make the VM appear as physical hardware to Apple services. Invoked with --variant exp, this pipeline executes the jb patch set first, then applies experimental modifications defined in the patching engine:

• hv_vmm rename to mask hypervisor signatures
• DSC byte-5 mangling to alter dyld shared cache identifiers
• Surgical watchdogd patches to prevent VM detection via watchdog timers
• Device-tree identity tweaks and post-restore DT rewrites to spoof hardware identifiers
• SPOOF_BUILD support for faking iOS build versions during firmware generation

Like the jb variant, fw_patch_exp supports --force-exc-guard and --frida flags for additional runtime control.

How the Make Targets Work

In the repository’s root Makefile, all three targets share an identical command structure but substitute the variant name into the --variant parameter. The Makefile invokes the Swift CLI binary located at $(CURDIR)/$(PATCHER_BINARY):

"$(CURDIR)/$(PATCHER_BINARY)" patch-firmware \
    --vm-directory "$(VM_DIR_ABS)" \
    --variant <variant> \
    $(optional-flags)

The patch-firmware subcommand is implemented in scripts/patchers/cfw.py, which handles the low-level binary modification logic, while sources/vphone-cli/VPhoneFWCLI.swift manages argument parsing and dispatches to the appropriate patch modules. The variant string determines which patch groups are loaded and applied to firmware components like the kernelcache and Secure Enclave firmware.

Usage Examples

Building Firmware with Make

Execute the targets directly from the repository root, optionally overriding VM_DIR or passing feature flags:

# Generate jailbreak firmware

make fw_patch_jb VM_DIR=./my_vm FRIDA=1

# Generate development firmware without jailbreak

make fw_patch_dev VM_DIR=./research_vm

# Generate experimental firmware with build spoofing

make fw_patch_exp VM_DIR=./stealth_vm SPOOF_BUILD=23F77 FORCE_EXC_GUARD=1

Direct CLI Invocation

You can bypass the Makefile and call the patcher directly, as implemented in sources/vphone-cli/VPhoneFWCLI.swift:

# Jailbreak variant with Frida support

vphone-cli patch-firmware --vm-directory ./vm --variant jb \
    --force-exc-guard --frida

# Development variant (TXM only)

vphone-cli patch-firmware --vm-directory ./dev_vm --variant dev

# Experimental variant with build spoof

vphone-cli patch-firmware --vm-directory ./exp_vm --variant exp \
    --force-exc-guard --frida

Installing the Generated CFW

After patching, install the custom firmware using the matching installation targets defined in scripts/cfw_install_host.sh:

# Install jailbreak CFW

make cfw_install_jb VM_DIR=./my_vm

# Install experimental CFW (passes SPOOF_BUILD to installer)

make cfw_install_exp VM_DIR=./stealth_vm SPOOF_BUILD=23F77

Summary

• fw_patch_jb creates a jailbroken firmware image with TXM patches, jetsam fixes, Procursus integration, and optional Frida/EXC_GUARD support via --variant jb.
• fw_patch_dev generates a research-oriented firmware with TXM debugging hooks but without jailbreak modifications, using --variant dev.
• fw_patch_exp produces a stealth firmware that combines jailbreak patches with anti-VM detection features (hv_vmm masking, DSC manipulation, and build spoofing) via --variant exp.
• All targets invoke the same Swift patcher binary defined in the Makefile, delegating variant-specific logic to scripts/patchers/cfw.py and sources/vphone-cli/VPhoneFWCLI.swift.

Frequently Asked Questions

What is the difference between the dev and jb variants?

The dev variant (fw_patch_dev) applies only Test-Execution-Mode (TXM) patches useful for debugging and research, while the jb variant (fw_patch_jb) adds those same TXM patches plus full jailbreak extensions including Procursus packages and jetsam workarounds. Use fw_patch_dev when you need debugging capabilities without modifying the system’s package management or runtime environment.

What does the exp variant add beyond standard jailbreak?

The exp variant (fw_patch_exp) includes everything from the jb variant plus experimental anti-detection patches documented in research/0_binary_patch_comparison.md. These patches rename hypervisor identifiers (hv_vmm), mangle DSC bytes, modify watchdogd, and rewrite device-tree properties to make the virtual machine appear as physical hardware to Apple’s attestation services.

Can I use these targets without the Makefile?

Yes. The Make targets are wrappers around the vphone-cli patch-firmware command. You can call the patcher directly from sources/vphone-cli/VPhoneFWCLI.swift with the --variant flag set to jb, dev, or exp, though you must manually specify the --vm-directory path and any optional flags like --frida or --force-exc-guard.

Where are the patch definitions located?

The patch modules are implemented in scripts/patchers/cfw.py, which contains the firmware modification logic for each variant. The command-line interface that parses --variant and dispatches to these modules resides in sources/vphone-cli/VPhoneFWCLI.swift. Additional documentation comparing the binary differences between variants is available in research/0_binary_patch_comparison.md.

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