# What Disassembly and Assembly Tools Does vPhone-CLI Use?

> Discover the disassembly and assembly tools vphone-cli employs. Learn how Capstone and Keystone Engine enable ARM64 instruction decoding and firmware patching.

- Repository: [Lakr/vphone-cli](https://github.com/Lakr233/vphone-cli)
- Tags: internals
- Published: 2026-09-05

---

**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`](https://github.com/Lakr233/vphone-cli/blob/main/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`](https://github.com/Lakr233/vphone-cli/blob/main/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.

```swift
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`](https://github.com/Lakr233/vphone-cli/blob/main/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`](https://github.com/Lakr233/vphone-cli/blob/main/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.

```swift
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`](https://github.com/Lakr233/vphone-cli/blob/main/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`](https://github.com/Lakr233/vphone-cli/blob/main/Package.swift)** – Declares the Capstone SwiftPM dependency (`libcapstone-spm`).
- **[`sources/FirmwarePatcher/ARM64/ARM64Disassembler.swift`](https://github.com/Lakr233/vphone-cli/blob/main/sources/FirmwarePatcher/ARM64/ARM64Disassembler.swift)** – Wraps Capstone with the `disassemble(_:at:)` method.
- **[`sources/FirmwarePatcher/ARM64/ARM64Encoder.swift`](https://github.com/Lakr233/vphone-cli/blob/main/sources/FirmwarePatcher/ARM64/ARM64Encoder.swift)** – Wraps Keystone for ARM64 instruction encoding.
- **[`sources/FirmwarePatcher/Kernel/KernelPatcherBase.swift`](https://github.com/Lakr233/vphone-cli/blob/main/sources/FirmwarePatcher/Kernel/KernelPatcherBase.swift)** – Base class importing Capstone and demonstrating typical disassembly usage patterns.
- **[`sources/VPhoneCore/VPhoneResources.swift`](https://github.com/Lakr233/vphone-cli/blob/main/sources/VPhoneCore/VPhoneResources.swift)** – Handles runtime Python interpreter checks and `libkeystone.dylib` resolution.
- **[`tests/FirmwarePatcherTests/FirmwarePatcherTests.swift`](https://github.com/Lakr233/vphone-cli/blob/main/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`](https://github.com/Lakr233/vphone-cli/blob/main/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`](https://github.com/Lakr233/vphone-cli/blob/main/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`](https://github.com/Lakr233/vphone-cli/blob/main/KernelPatchBsdInitAuth.swift).