Kernel Patch Verification Workflow under Runtime Verification in vphone-cli

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, validates that the dynamic patch discovery mechanism in 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) 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 – The comprehensive verification report documenting methodology, patch tables, and SHA-256 checksums of all intermediate artifacts.
• scripts/patchers/kernel.py – Implements the KernelPatcher class with find_all() and apply_all() methods for dynamic patch discovery.
• scripts/fw_patch.py – Contains the legacy hard-coded patch list used for the vphone600 kernel baseline.
• scripts/fw_prepare.sh and 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.

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

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.

# 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, 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 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 located at research/kernel_patcher_verification.md in the repository.

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