What Disassembly and Assembly Tools Does vPhone-CLI Use?

vPhone-CLI uses the Capstone disassembly framework for decoding ARM64 instructions and the Keystone Engine for assembling new machine code during iOS firmware patching.

vPhone-CLI is an open-source tool for modifying iOS firmware images, and its ability to safely patch kernel binaries relies on robust disassembly and assembly tools. The project integrates industry-standard engines directly into its Swift codebase to handle ARM64 machine code transformation. According to the Lakr233/vphone-cli source code, these toolchains enable a complete round-trip workflow from raw bytes to human-readable instructions and back to modified binaries.

Capstone: The Disassembly Engine for ARM64 Firmware Analysis

vPhone-CLI leverages Capstone via the Swift Package Manager dependency libcapstone-spm to decode ARM64 machine code. The Package.swift manifest declares this dependency, which compiles Capstone as a native SwiftPM product named Capstone and links it into the firmware patcher modules.

In sources/FirmwarePatcher/ARM64/ARM64Disassembler.swift, the tool implements a thin wrapper class ARM64Disassembler around the Capstone engine. This class exposes a disassemble(_:at:) method that transforms raw instruction bytes into Capstone.Instruction objects. The disassembler validates existing firmware instructions, performs pattern matching, and extracts branch targets before any modifications occur.

import Capstone

let disasm = try ARM64Disassembler()
let bytes: [UInt8] = [0x00, 0x00, 0x80, 0x52]   // example: `mov x0, #0`
let insns = try disasm.disassemble(bytes, at: 0x1000)
print(insns.first?.mnemonic ?? "none")   // → "mov"

Keystone Engine: Runtime Assembly for Instruction Generation

For assembling new instructions, vPhone-CLI utilizes the Keystone Engine through its Python bindings rather than a native Swift package. The ARM64Encoder class in sources/FirmwarePatcher/ARM64/ARM64Encoder.swift provides a Swift wrapper that delegates encoding tasks to the Python keystone library loaded at runtime.

The Swift code checks for a usable Python interpreter and attempts to repair or locate libkeystone.dylib during initialization, as implemented in sources/VPhoneCore/VPhoneResources.swift. This runtime dependency allows vPhone-CLI to generate binary-encoded instructions—such as branch operations or ADRP/ADD sequences—while guaranteeing that generated bytes conform to ARM64 architecture encoding rules.

let keystone = try Keystone()
let asm = "b #0x2000"               // branch to address 0x2000
let bytes = try keystone.assemble(asm, .arm64, .littleEndian)
print(bytes.map { String(format: "%02x", $0) }.joined())  // → "00 00 00 14"

The Round-Trip Firmware Patching Workflow

Together, these disassembly and assembly tools enable a reliable four-step patching process:

1. Disassemble existing firmware bytes with Capstone to verify instruction semantics and identify patch points.
2. Compute the required modification, such as changing a conditional branch to an unconditional jump.
3. Assemble the new instruction(s) with Keystone to obtain exact binary encoding.
4. Patch the binary using the generated bytes, storing both original and modified disassembly for auditability.

This workflow appears in concrete implementations like KernelPatchBsdInitAuth.swift, where the tool decodes a conditional cbz instruction using Capstone, extracts the branch target, and assembles a replacement unconditional branch using Keystone.

Key Source Files for Disassembly and Assembly Integration

The following files define how vPhone-CLI integrates these engines:

• Package.swift – Declares the Capstone SwiftPM dependency (libcapstone-spm).
• sources/FirmwarePatcher/ARM64/ARM64Disassembler.swift – Wraps Capstone with the disassemble(_:at:) method.
• sources/FirmwarePatcher/ARM64/ARM64Encoder.swift – Wraps Keystone for ARM64 instruction encoding.
• sources/FirmwarePatcher/Kernel/KernelPatcherBase.swift – Base class importing Capstone and demonstrating typical disassembly usage patterns.
• sources/VPhoneCore/VPhoneResources.swift – Handles runtime Python interpreter checks and libkeystone.dylib resolution.
• tests/FirmwarePatcherTests/FirmwarePatcherTests.swift – Validates the disassembly-assembly round-trip.

Summary

• Capstone provides static disassembly capabilities through the ARM64Disassembler class, parsing raw ARM64 bytes into structured instruction objects.
• Keystone Engine supplies dynamic assembly through the ARM64Encoder class, generating machine code from assembly strings via Python bindings.
• The tools operate sequentially: Capstone validates existing code, while Keystone generates replacement instructions for firmware patches.
• Runtime dependencies for Keystone are managed through VPhoneResources.swift, ensuring the Python environment is properly configured before assembly operations.

Frequently Asked Questions

Why does vPhone-CLI use two different libraries instead of a single tool?

vPhone-CLI separates concerns by using Capstone for disassembly and Keystone for assembly because each engine specializes in opposite transformation directions. Capstone excels at decoding complex instruction sets with detailed semantic analysis, while Keystone focuses on accurate binary encoding from assembly syntax. This separation allows the firmware patcher to validate original instructions independently before generating new machine code.

How does vPhone-CLI handle Keystone's Python dependency at runtime?

The Swift code in VPhoneResources.swift checks for a usable Python interpreter at launch and attempts to repair or locate the libkeystone.dylib shared library if it is missing or damaged. This runtime linking strategy allows vPhone-CLI to assemble instructions only when needed, deferring the Python environment requirement until the assembly phase of the patching workflow.

What architecture does vPhone-CLI target with these disassembly and assembly tools?

vPhone-CLI specifically targets ARM64 (AArch64) architecture, as evidenced by the ARM64Disassembler and ARM64Encoder class names and the use of ARM64-specific Capstone and Keystone modes. The tools handle ARM64-specific instruction patterns including ADRP/ADD sequences and PC-relative branching operations common in iOS kernel firmware.

Can vPhone-CLI disassemble and assemble instructions in real-time during patching?

Yes, the tool performs disassembly and assembly operations dynamically during the patching process. It disassembles existing firmware bytes with Capstone to verify semantics, computes necessary modifications, and immediately assembles replacement instructions with Keystone before writing them back to the binary image, as demonstrated in KernelPatchBsdInitAuth.swift.

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