If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/Lakr233/vphone-cli shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 3d ago
• 28+ active contributors
• Distributed ownership (top contributor 18% of recent commits)
• MIT licensed
• Tests present
• ⚠ No CI workflows detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live Lakr233/vphone-cli repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/Lakr233/vphone-cli.

What it runs against: a local clone of Lakr233/vphone-cli — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in Lakr233/vphone-cli | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 33 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of Lakr233/vphone-cli. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/Lakr233/vphone-cli.git
#   cd vphone-cli
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of Lakr233/vphone-cli and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "Lakr233/vphone-cli(\\.git)?\\b" \\
  && ok "origin remote is Lakr233/vphone-cli" \\
  || miss "origin remote is not Lakr233/vphone-cli (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "Package.swift" \\
  && ok "Package.swift" \\
  || miss "missing critical file: Package.swift"
test -f "scripts/patchers/cfw.py" \\
  && ok "scripts/patchers/cfw.py" \\
  || miss "missing critical file: scripts/patchers/cfw.py"
test -f "scripts/fw_manifest.py" \\
  && ok "scripts/fw_manifest.py" \\
  || miss "missing critical file: scripts/fw_manifest.py"
test -f "scripts/vm_manifest.py" \\
  && ok "scripts/vm_manifest.py" \\
  || miss "missing critical file: scripts/vm_manifest.py"
test -f "research/kernel_patch_jb/PATCH_DOC_FRAMEWORK.md" \\
  && ok "research/kernel_patch_jb/PATCH_DOC_FRAMEWORK.md" \\
  || miss "missing critical file: research/kernel_patch_jb/PATCH_DOC_FRAMEWORK.md"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 33 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~3d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/Lakr233/vphone-cli"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

vphone-cli boots a virtualized iOS 26 environment on macOS using Apple's Virtualization.framework, with four firmware patch variants (Patchless, Regular, Development, Jailbreak) that progressively bypass iOS security. It automates kernel patching, bootloader modification, and Custom Firmware (CFW) installation through a Make-based build pipeline. Monolithic Swift CLI tool (Package.swift) with Python/Shell support scripts. Core structure: research/ contains patch documentation and kernel symbol databases (kernel_info/kernel_symbols.db, kernel_patch_jb/ with 20+ specific kernel modification docs), Makefile orchestrates fw_patch variants and CFW installation phases, docs/ holds localized guides (English, Japanese, Korean, Chinese).

Security researchers, iOS kernel engineers, and reverse engineers who need a controlled iOS virtual machine for firmware analysis, exploit development, and jailbreak testing without physical hardware constraints.

Experimental and highly specialized. The repo shows recent activity (tested on macOS 26.3 with iOS 26.3.1) and extensive research documentation, but lacks traditional CI/CD, unit test coverage, and public issue tracking. This is research-grade code, not production software.

High risk: single maintainer (Lakr233), tightly coupled to specific macOS/iOS version pairs (macOS 15+ Sequoia required), heavy dependency on proprietary Apple frameworks and undocumented kernel internals documented only in research/. SIP/AMFI disable requirement is a significant host system modification. Dependencies like ipsw-parser and pymobiledevice3 are external and their maintenance status is unclear.

Active development on jailbreak infrastructure: kernel_patch_jb/ contains detailed patch chains for 112 total patches across AMFI, sandbox, fairplay, and task/port conversion subsystems. Recent testing confirms iOS 26.3.1 compatibility. LaunchDaemon-based JB finalization (vphone_jb_setup.sh) with automatic Sileo/apt/TrollStore installation on first boot.

Clone and install: git clone https://github.com/Lakr233/vphone-cli && cd vphone-cli && pip3 install -r requirements.txt && make fw_patch_jb && make cfw_install_jb. Requires macOS 15+ with SIP/AMFI configured (see README prerequisites). Monitor jailbreak finalization via tail -f /var/log/vphone_jb_setup.log.

Daily commands: Build and boot: make fw_patch_jb (apply 112 kernel patches), then make cfw_install_jb (install 14-phase CFW), then swift build && .build/debug/vphone-cli to boot. Monitor first boot JB setup: tail -f /var/log/vphone_jb_setup.log. Requires macOS 15+, SIP partially or fully disabled, and ~30GB free space for IPSW extraction.

• Package.swift — Swift package manifest defining the CLI tool's dependencies (typer, capstone, keystone-engine, pyimg4, pymobiledevice3, ipsw-parser) and build configuration—essential for understanding build system and external integrations.
• scripts/patchers/cfw.py — Core firmware patcher orchestrating CFW (Custom Firmware) installation phases; primary entry point for security bypass and patch application logic.
• scripts/fw_manifest.py — Firmware manifest parser and builder that manages iOS image variants, patch configurations, and firmware version mappings across different iOS versions.
• scripts/vm_manifest.py — Virtual machine manifest handler coordinating VM lifecycle, state persistence, and integration with Virtualization.framework; critical for VM instantiation and management.
• research/kernel_patch_jb/PATCH_DOC_FRAMEWORK.md — Comprehensive documentation of the kernel patching framework explaining patch methodology, offset calculations, and validation—required reading for understanding security bypass architecture.
• Makefile — Build automation defining targets for firmware variants (patchless, regular, jailbreak) and boot configurations—shows the complete release pipeline and build strategy.
• requirements.txt — Python dependency manifest specifying exact versions for pymobiledevice3, pyimg4, capstone, and keystone-engine—critical for reproducible environment setup.

Add a new kernel patch variant

1. Create a new patch documentation file in research/kernel_patch_jb/ following the PATCH_DOC_FRAMEWORK.md structure (research/kernel_patch_jb/patch_your_feature.md)
2. Implement the patch logic in scripts/patchers/cfw.py, registering it in the appropriate phase sequence (scripts/patchers/cfw.py)
3. Add validation test in research/kernel_patch_jb/runtime_verification/ (research/kernel_patch_jb/runtime_verification/ida_patch_chain_report.md)
4. Update fw_manifest.py to include the new patch in the firmware variant configuration (scripts/fw_manifest.py)

Add support for a new iOS version

1. Extract IPSW and analyze kernel offsets, adding entries to research/kernel_info/kernel_index.tsv (research/kernel_info/kernel_index.tsv)
2. Update scripts/fw_manifest.py with new version mappings and patch offsets (scripts/fw_manifest.py)
3. Add validation baseline to research/ with kernel patch verification report (research/kernel_patch_base_X_Y_validation.md)
4. Test with Makefile targets (fw_patch, cfw_install) and update tested environments in README.md (README.md)

Extend CFW daemon patching (mobileactivationd, jetsam, etc.)

1. Create new daemon patcher in scripts/patchers/cfw_patch_your_daemon.py following cfw_patch_mobileactivationd.py structure (scripts/patchers/cfw_patch_your_daemon.py)
2. Register the new patcher as a phase in scripts/patchers/cfw.py (scripts/patchers/cfw.py)
3. Document the binary modifications and security implications in research/cfw_patch_*.md (research/cfw_patch_your_feature.md)
4. Add test coverage and update Makefile if new build targets are needed (Makefile)

• Apple Virtualization.framework — Provides native hypervisor support for arm64 virtual machines on Apple Silicon; eliminates licensing overhead vs. QEMU/UTM while offering tight macOS integration.
• Python (typer, capstone, keystone-engine) — Rapid prototyping of complex binary patching logic; capstone/keystone provide CPU instruction disassembly/assembly, critical for kernel exploit offset calculation.
• pymobiledevice3 — Mature library for iOS device communication over USB/network; avoids reimplementing Apple's proprietary lockdownd/usbmuxd protocols.
• ipsw-parser & pyimg4 — Standardized IPSW extraction and IMG4 firmware decryption; required for extracting and re-signing patched kernel/ramdisk images.
• Makefile + bash scripts — Orchestrates multi-stage build pipeline (fw_patch → cfw_install → boot) with clear dependency ordering and idempotent targets.

• Multi-phase CFW patching (10+ phases) vs. single-pass patching
  • Why: Enables incremental validation
  • Consequence: undefined

Mandatory SIP/AMFI disable on host macOS (csrutil disable + amfi_get_out_of_my_way=1 nvram boot-arg) required; this persists across reboots. iOS version must match tested matrix (17,3_26.3_23D127 or 17,3_26.3.1_23D8133); mismatches cause patch offset failures. Kernel symbol database (kernel_symbols.db) must be present and in sync with target firmware or patches will silently apply at wrong offsets. CloudOS version requirement (26.1-23B85 or 26.3-23D128) is not clearly documented in usage docs. First boot JB finalization via LaunchDaemon runs asynchronously; logs are in /var/log/vphone_jb_setup.log, not console.

• Binary Patching via Offset Tables — vphone-cli applies 112 kernel patches by searching/replacing binary sequences at hardcoded offsets; understanding offset extraction and CFG-blind patching is critical to extend the patch set to new iOS versions
• Kernel Symbol Resolution Across Versions — The kernel_symbols.db maps function names to addresses across iOS versions; learners must understand how symbol databases enable cross-version patch porting without recompiling the kernel
• XPC Protocol Reverse Engineering — research/devmode_xpc_protocol.md documents inter-process communication used by iOS development mode; understanding XPC is essential for privilege escalation and custom firmware deployment
• Virtualization.framework Private Entitlements — vphone-cli requires undocumented private entitlements (com.apple.private.virtualization) not in public SDK; learners must understand entitlement-based capability gating in Apple frameworks
• AMFI Code Signature Validation Bypass — AMFI patches disable code signature checks (cdhash_in_trustcache, execve_kill_path); understanding AMFI's role in iOS security validates why these are the first targets in the patch chain
• LaunchDaemon-based Post-Boot Automation — vphone_jb_setup.sh runs automatically via LaunchDaemon; learners must understand how macOS/iOS system daemons enable unattended initialization and jailbreak finalization (Sileo, apt, TrollStore installation)
• Firmware Manifest Parsing (IPSW format) — research/firmware_manifest_and_origins.md and ipsw-parser dependency handle IPSW decryption and component extraction; learners must understand firmware image structure to locate kernel/bootloader/ramdisk for patching

• tihmstar/bfdecrypt — Utility for decrypting encrypted firmware images; used upstream in vphone-cli's IPSW parsing pipeline
• checkra1n/checkra1n — Reference jailbreak with checkm8 exploit; similar kernel patch orchestration and Custom Firmware installation philosophy
• Lakr233/Rayon — Related project from same author; likely shares infrastructure or complementary iOS automation tooling
• OWASP/oatmeal_interop — iOS interop security testing framework; users of vphone-cli would use this for vulnerability validation in virtual environment
• corellium/arm-qemu — QEMU-based iOS virtualization alternative; competing approach to Apple Virtualization.framework for iOS emulation

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add Python unit tests for scripts/patchers/ modules

The repo contains complex binary patching logic in scripts/patchers/cfw.py and likely other patcher modules, but there are no visible test files. Given the critical nature of firmware patching (evident from research/kernel_patch_jb/ documentation), unit tests would catch regressions and validate patch application logic across different iOS versions (17.3, 26.1, 26.3, etc.).

• [ ] Create tests/patchers/ directory with test_cfw.py
• [ ] Add unit tests for patch validation logic referenced in research/kernel_patch_jb/ docs
• [ ] Test version compatibility matrix from scripts/fw_manifest.py against documented firmware variants
• [ ] Integrate pytest into Makefile and requirements.txt

Create GitHub Actions CI workflow for multi-version firmware validation

The README documents a test matrix across 4 firmware variants and multiple host/iPhone/CloudOS combinations, but there's no visible CI automation. A workflow would validate patch application, boot chain integrity, and compatibility matrix changes before merging, reducing manual testing burden.

• [ ] Create .github/workflows/firmware-validation.yml
• [ ] Add validation steps for cfw.py and jb patcher scripts from scripts/patchers/
• [ ] Test against kernel patch research docs in research/kernel_patch_jb/ for regression detection
• [ ] Add status badge to README.md

Document and extract binary patching framework from research/ into reusable SDK

The research/kernel_patch_jb/PATCH_DOC_FRAMEWORK.md exists but patch logic appears scattered across 20+ research docs and cfw.py. Contributors struggle to understand the patching pipeline. Consolidating this into a structured module (e.g., scripts/patch_framework.py) with clear APIs would make the codebase more maintainable and lower the barrier for new contributors.

• [ ] Create scripts/patch_framework.py with unified patch descriptor classes
• [ ] Refactor scripts/patchers/cfw.py to use the new framework
• [ ] Create docs/PATCHING_GUIDE.md linking to research/kernel_patch_jb/ docs with worked examples
• [ ] Add type hints and docstrings following the framework structure in PATCH_DOC_FRAMEWORK.md

• Add unit tests for kernel patch offset validation (research/kernel_info/kernel_symbols.db parsing) to catch version incompatibilities before boot; currently no automated test suite exists.
• Write integration test documentation and Makefile target to validate all four firmware variants (Patchless, Regular, Development, Jailbreak) boot successfully on a test matrix; currently only manual testing is done.
• Create a TROUBLESHOOTING.md guide documenting the SIP/AMFI disable process (Option 1 vs Option 2 trade-offs), kernel symbol database sync procedures, and JB finalization failure recovery steps; currently scattered across README and research/.

• High · Unrestricted Binary Patching and Firmware Modification — scripts/patchers/, research/kernel_patch_jb/. The codebase contains extensive kernel patching capabilities targeting iOS firmware (iboot, kernel, CFW). Scripts like cfw_install.sh, cfw_patch_jetsam.py, and kernel patchers modify security-critical components. This could allow unauthorized security bypass if source or build artifacts are compromised. The research directory documents detailed patch points for AMFI, sandbox, and security policies. Fix: Implement strict code signing, integrity verification, and access controls. Require multi-signature approval for firmware modifications. Use secure build infrastructure with audit logging.
• High · Potential Arbitrary Code Execution via Binary Patching Tools — scripts/patchers/, requirements.txt (capstone, keystone-engine). The codebase uses capstone and keystone-engine for disassembly and assembly of binary code. Combined with pymobiledevice3 for device communication, there's risk of arbitrary instruction injection if input validation is insufficient. Patchers operate on kernel and system daemons without apparent sandboxing. Fix: Implement strict input validation on all binary patches. Use bounded code generation. Implement runtime verification of patches before deployment. Consider using attestation mechanisms.
• High · Unencrypted Device Communication — scripts/pymobiledevice3_bridge.py, scripts/patchers/. The codebase uses pymobiledevice3 for device communication. No evidence of encrypted transport security, certificate pinning, or mutual authentication is visible. Device communication for firmware patching and system manipulation lacks apparent security guarantees. Fix: Implement TLS 1.3 with certificate pinning. Require mutual authentication. Add message signing and integrity verification. Document security assumptions of pymobiledevice3 version >=9.5.0.
• High · Insufficient Input Validation in Firmware Manifest Processing — scripts/fw_manifest.py, requirements.txt (ipsw-parser). The fw_manifest.py script processes firmware manifests without apparent validation. The ipsw-parser dependency processes archive files. Malformed manifests could lead to path traversal, arbitrary file operations, or memory corruption during parsing. Fix: Implement strict schema validation for all manifest files. Use sandboxed parsing. Validate all paths against whitelist. Set size limits on parsed files.
• Medium · Dependency Vulnerability Management — requirements.txt, Package.swift. Multiple dependencies with potential security issues are used: pymobiledevice3 (>=9.5.0 with loose version pinning), pyimg4, ipsw-parser. No lock file evident, allowing unexpected version updates. Capstone and keystone-engine are used for binary manipulation without apparent verification. Fix: Use exact version pinning (e.g., ==9.5.0 instead of >=9.5.0). Maintain lock file (requirements-lock.txt). Regularly audit dependencies for CVEs. Consider using dependency scanning tools in CI/CD.
• Medium · Potential Race Conditions in VM Lifecycle Management — scripts/boot_host_preflight.sh, scripts/cfw_install*.sh. The vphone-cli manages virtual machine boot, patching, and communication. Boot scripts (boot_host_preflight.sh, cfw_install.sh) may have race conditions when managing system state, kernel loading, and device communication without apparent locking mechanisms. Fix: Implement explicit locking mechanisms using flock or similar. Add state verification between operations. Use atomic operations where possible. Add timeout handling.
• Medium · Insufficient Logging and Audit Trail for Security Operations — scripts/patchers/, scripts/cfw_install*.sh. Firmware patching and kernel modification operations lack apparent comprehensive logging. Security-critical operations (patch application, device communication, system modifications) should maintain detailed audit trails for forensics and compliance. Fix: Implement comprehensive audit logging for all security-sensitive operations. Log all patch applications with checksums. Include timestamp, user, device info. Implement tamper-evident logging.
• Medium · Shell Script Injection Risks — undefined. Multiple shell scripts in scripts/ directory use external tools and device communication without apparent input sanitization. Variables in boot_host_preflight.sh, ramdisk_send.sh, and other scripts may be vulnerable Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.