# Kernel Patch Verification Workflow under Runtime Verification in vphone-cli

> Explore the vphone-cli kernel patch verification workflow. Learn how runtime verification ensures byte-identical results for dynamic patches compared to historical lists.

- Repository: [Lakr/vphone-cli](https://github.com/Lakr233/vphone-cli)
- Tags: how-to-guide
- Published: 2026-09-13

---

**The kernel patch verification workflow in vphone-cli validates that dynamic runtime patching produces byte-identical results to legacy hard-coded patches by comparing binary outputs of the `KernelPatcher` class against historical patch lists.**

The vphone-cli project employs a rigorous runtime verification system to ensure kernel modifications remain deterministic across firmware versions. This workflow, documented in the [Binary Kernelcache Patch Verification Report](https://github.com/Lakr233/vphone-cli/blob/main/research/kernel_patcher_verification.md), validates that the dynamic patch discovery mechanism in [`scripts/patchers/kernel.py`](https://github.com/Lakr233/vphone-cli/blob/main/scripts/patchers/kernel.py) achieves identical binary mutations to the legacy hard-coded approach.

## Core Components of the Verification Architecture

The verification system relies on two parallel patching methodologies to establish a trusted baseline. The **legacy hard-coded patch list** (historically maintained in [`scripts/fw_patch.py`](https://github.com/Lakr233/vphone-cli/blob/main/scripts/fw_patch.py)) provides the ground-truth reference, while the **dynamic `KernelPatcher`** automatically discovers and applies equivalent modifications.

### Key Source Files

The implementation spans several critical components:

- **[`research/kernel_patcher_verification.md`](https://github.com/Lakr233/vphone-cli/blob/main/research/kernel_patcher_verification.md)** – The comprehensive verification report documenting methodology, patch tables, and SHA-256 checksums of all intermediate artifacts.
- **[`scripts/patchers/kernel.py`](https://github.com/Lakr233/vphone-cli/blob/main/scripts/patchers/kernel.py)** – Implements the `KernelPatcher` class with `find_all()` and `apply_all()` methods for dynamic patch discovery.
- **[`scripts/fw_patch.py`](https://github.com/Lakr233/vphone-cli/blob/main/scripts/fw_patch.py)** – Contains the legacy hard-coded patch list used for the vphone600 kernel baseline.
- **[`scripts/fw_prepare.sh`](https://github.com/Lakr233/vphone-cli/blob/main/scripts/fw_prepare.sh)** and **[`scripts/fw_manifest.py`](https://github.com/Lakr233/vphone-cli/blob/main/scripts/fw_manifest.py)** – Supporting utilities for kernelcache extraction and preparation.

## Step-by-Step Kernel Patch Verification Workflow

The runtime verification process follows a deterministic pipeline that extracts kernels, applies both legacy and dynamic patches, and performs binary comparison to confirm equivalence.

### Step 1: Kernelcache Extraction and Preparation

The workflow begins by extracting raw kernelcache images from firmware files using `pyimg4`. The process captures both the target kernel (vphone600) and a clean research kernel (vresearch101) for cross-version validation.

```bash

# Extract clean kernelcache for research validation

pyimg4 im4p extract \
    -i VM/iPhone17,3_26.1_23B85_Restore/kernelcache.research.vresearch101 \
    -o /tmp/kc_vresearch1_orig.raw

```

This produces the unmodified binary `kc_vresearch1_orig.raw` that serves as the input for both patching paths.

### Step 2: Legacy Hard-Coded Patch Application

The baseline is established by applying the historic patch list from [`scripts/fw_patch.py`](https://github.com/Lakr233/vphone-cli/blob/main/scripts/fw_patch.py). This legacy approach uses direct 32-bit binary replacement operations to modify specific offsets in the original kernel, producing `kc_vphone600_upstream.raw`.

The hard-coded patches target critical security checks including `_PE_i_can_has_debugger` and the TXM post-validation routine.

### Step 3: Dynamic Patch Discovery via KernelPatcher

The dynamic path utilizes the `KernelPatcher` class to automatically discover patch locations without hard-coded offsets. The Python API invokes pattern matching and symbol resolution to identify the same 26 patch sites identified in the legacy method.

```python
from scripts.patchers.kernel import KernelPatcher

# Initialize patcher with original kernel

kp = KernelPatcher('/tmp/kc_vphone600_orig.raw')

# Discover all patch locations dynamically

kp.find_all()

# Apply mutations in-place

kp.apply_all()

# Save the dynamically patched binary

kp.save('/tmp/kc_vphone600_dynamic.raw')

```

The `find_all()` method locates critical hooks including the TXM NOP insertion point at `0xFA6B98` and the `_PE_i_can_has_debugger` modification site.

### Step 4: Binary Diff Verification

The core validation step performs a byte-wise comparison between the legacy and dynamically patched binaries using standard Unix comparison tools.

```bash

# Verify byte-identical output between legacy and dynamic patching

cmp -l /tmp/kc_vphone600_upstream.raw /tmp/kc_vphone600_dynamic.raw

```

According to the [verification report](https://github.com/Lakr233/vphone-cli/blob/main/research/kernel_patcher_verification.md), this comparison shows **no differences**, confirming that `KernelPatcher` produces functionally equivalent output to the hard-coded approach.

### Step 5: Cross-Version Validation

To ensure the dynamic patcher generalizes beyond the baseline kernel, the workflow repeats the process on a fresh `vresearch101` kernelcache. The patcher successfully identifies and applies all 26 patches to this newer kernel version, validating the runtime verification system's adaptability.

## Implementation Details and Patch Sites

The verification report documents 26 distinct patch locations across both test kernels. Key modifications include:

- **`_PE_i_can_has_debugger`** – Enables debugging capabilities by patching the debug enablement check.
- **TXM Post-Validation NOP** – Located at offset `0xFA6B98` in the vresearch101 kernel, this patch replaces validation logic with NOP instructions.
- **VM object initialization hooks** – Dynamic patching of virtual memory subsystem initialization routines.

Each patch entry in the report includes the original instruction bytes, modified bytes, and verification status marked as `OK`.

## Summary

The kernel patch verification workflow under runtime verification ensures deterministic, reproducible kernel modifications through the following mechanisms:

- **Baseline Comparison** – Legacy hard-coded patches establish a cryptographic baseline for validation.
- **Dynamic Discovery** – The `KernelPatcher.find_all()` method automatically locates 26 critical patch sites without manual offset specification.
- **Binary Equivalence** – Byte-wise comparison confirms that dynamic patching produces identical output to legacy methods.
- **Cross-Version Support** – Validation across vphone600 and vresearch101 kernels demonstrates adaptability to firmware updates.
- **Auditability** – SHA-256 checksums of all intermediate files provide complete provenance tracking.

## Frequently Asked Questions

### What is the purpose of the kernel patch verification workflow?

The workflow ensures that the dynamic patching logic in [`scripts/patchers/kernel.py`](https://github.com/Lakr233/vphone-cli/blob/main/scripts/patchers/kernel.py) produces binary-identical results to the legacy hard-coded patch list. This verification prevents regression bugs when the patch discovery algorithms are modified or when targeting new kernel versions.

### How does `KernelPatcher.find_all()` discover patch locations?

The method employs pattern matching and symbol resolution techniques to locate security-critical functions such as `_PE_i_can_has_debugger` and TXM validation routines. It identifies 26 specific patch sites by analyzing the kernel binary's structure rather than relying on hard-coded offsets, enabling adaptation across different kernel versions.

### What tools perform the binary comparison between patched kernels?

The verification workflow uses standard Unix utilities, specifically `cmp -l`, to perform byte-wise differencing between the legacy-patched binary (`kc_vphone600_upstream.raw`) and the dynamically patched output (`kc_vphone600_dynamic.raw`). This comparison confirms zero differences between the two patching methodologies.

### Where is the verification methodology documented?

The complete verification methodology, including patch tables, SHA-256 checksums, and step-by-step procedures, is documented in the [Binary Kernelcache Patch Verification Report](https://github.com/Lakr233/vphone-cli/blob/main/research/kernel_patcher_verification.md) located at [`research/kernel_patcher_verification.md`](https://github.com/Lakr233/vphone-cli/blob/main/research/kernel_patcher_verification.md) in the repository.