vphone-cli

قم بتشغيل iPhone افتراضي عبر إطار عمل Virtualization من Apple باستخدام البنية التحتية لجهاز PCC البحثي.

المتطلبات الأساسية

المضيف:

• Apple Silicon
• macOS 15+ (Sequoia)
• Xcode + iOS SDK (يُجمّع البرنامج الخفي الضيف بشكل متقاطع)
• تخفيف قيود SIP/AMFI للسماح بتراخيص PV=3 الخاصة مع ثنائي غير موقّع

التبعيات:

brew install [email protected] aria2 wget gnu-tar openssl@3 ldid-procursus sshpass keystone cmake libusb ipsw zstd

التثبيت

brew install zqxwce/tap/vphone-cli

البناء

git clone --recurse-submodules https://github.com/Lakr233/vphone-cli.git

./scripts/setup_tools.sh      # تثبيت التبعيات، بناء وحدات الأدوات الفرعية، إنشاء بيئة Python الافتراضية
./scripts/build.sh            # بناء وتوقيع vphone-cli، تجميع حزمة .app، التجميع المتقاطع لـ vphoned

cd .build/vphone-cli.app/Contents/MacOS/
vphone-cli --help

البدء السريع

أمر واحد ينشئ جهاز VM من البداية إلى النهاية (تنزيل ← تصحيح ← استعادة DFU ← تثبيت CFW ← أول إقلاع):

vphone-cli vm create myphone -V jb        # -V / --variant

vphone-cli vm launch myphone

الأوامر

vphone-cli vm create يشغّل خط الأنابيب بالكامل؛ الخطوات الفردية أدناه تتيح لك تشغيله يدويًا أو إعادة تشغيل مرحلة واحدة.

الإدارة

vphone-cli vm list                         # قائمة الأجهزة الافتراضية (--json للبرمجة النصية)
vphone-cli vm info myphone                  # عرض جهاز افتراضي واحد
vphone-cli vm new myphone                   # إنشاء حزمة فارغة (خيارات cpu/mem/disk)
vphone-cli vm config myphone --cpu 8 --memory 8192
vphone-cli vm clone myphone myphone-2       # استنساخ APFS سريع، هوية جهاز جديدة
vphone-cli vm export myphone --out myphone.tzst   # ضغط zstd سريع افتراضيًا (--max = xz -9)؛ قد يكون --out دليلًا (يُسمّى تلقائيًا <vm>.tzst/.txz)؛ يتخطى دليل الاستعادة وملفات التدريج
vphone-cli vm import myphone.tzst --name restored
vphone-cli vm rename myphone iphone16
vphone-cli vm delete iphone16

بناء جهاز افتراضي يدويًا (ما تقوم به vm create تلقائيًا)

vphone-cli vm new myphone                              # 1. حزمة فارغة
vphone-cli fw prepare myphone --iphone-version 26.1     # 2. تنزيل ودمج ملفات IPSW
vphone-cli fw patch myphone --variant jb                # 3. تصحيح سلسلة الإقلاع

vphone-cli vm launch myphone --dfu &                    # 4. الإقلاع إلى DFU (في الخلفية)
vphone-cli restore myphone --get-shsh                   #    جلب SHSH
vphone-cli restore myphone                              #    استعادة DFU
vphone-cli vm stop myphone                              #    إيقاف إقلاع DFU

vphone-cli cfw install myphone --variant jb             # 5. تثبيت CFW (تركيب المضيف؛ يطلب صلاحيات sudo)
vphone-cli vm launch myphone                            # 6. أول إقلاع

قم بالتحديث إلى إصدار iOS أحدث بتوجيه fw prepare إلى ملف IPSW: --iphone-source /path/to.ipsw --cloudos-source /path/to.ipsw.

متغيرات البرنامج الثابت

خمسة متغيرات تصحيح مع تجاوز أمني متزايد — مرّر واحدًا إلى --variant:

راجع research/0_binary_patch_comparison.md للتفصيل حسب المكوّن.

التشغيل والاتصال

• SSH (كسر الحماية): ssh -p 22222 mobile@<vm-ip> (كلمة المرور alpine)
• SSH (regular/dev): ssh -p 22222 root@<vm-ip>
• VNC: vnc://<vm-ip>:5901

المواقع

كل ما ينشئه vphone-cli يقع تحت ~/.vphone/ — خارج المستودع وحزمة .app ليبقى الحزمة الموقّعة قابلة للنقل. أعد توجيه الشجرة بالكامل باستخدام $VPHONE_ROOT:

الأولوية: التجاوزات لكل عنصر ($VPHONE_LIBRARY_ROOT، $VPHONE_VENV_DIR) تفوز على $VPHONE_ROOT، الذي يفوز على الافتراضي ~/.vphone. مخابئ ipsws/ وtools/ وdebs/ تقع دائمًا مباشرة تحت الجذر النشط أيهما كان.

تخفيف قيود SIP/AMFI

الخيار أ — تعطيل SIP بالكامل، ثم تعطيل AMFI عبر وسيط الإقلاع (الأكثر تساهلًا).

في وضع الاسترداد (الضغط المطول على زر الطاقة ← الطرفية):

csrutil disable
csrutil allow-research-guests enable

ثم أعد التشغيل إلى macOS واضبط وسيط إقلاع AMFI (يتطلب تعطيل SIP بالكامل ليعمل):

sudo nvram boot-args="amfi_get_out_of_my_way=1 -v"   # أعد التشغيل بعد ذلك

الخيار ب — إبقاء SIP مفعّلًا (تخفيف وضع التصحيح فقط)، ثم السماح للثنائي عبر amfidont (يُبقي AMFI مفعّلًا على مستوى النظام).

في وضع الاسترداد:

csrutil enable --without debug
csrutil allow-research-guests enable

ثم أعد التشغيل إلى macOS وقم بما يلي:

vphone-amfidont         # .build/vphone-cli.app/Contents/Resources/vphone-amfidont للبناءات المحلية

البيئات المختبرة

الأسئلة الشائعة

zsh: killed ./vphone-cli — قيود AMFI/التصحيح لم يتم تجاوزها؛ راجع المتطلبات الأساسية (amfi_get_out_of_my_way=1 أو amfidont).

Virtualization is not available on this hardware — جهاز Mac الخاص بك هو نفسه جهاز افتراضي؛ لا يمكن تداخل إقلاع ضيف PV=3. استخدم مضيف macOS 15+ غير متداخل.

عالق عند "Press home to continue" — اتصل عبر VNC وانقر بزر الماوس الأيمن (نقرة بإصبعين) لمحاكاة زر الصفحة الرئيسية.

تطبيقات النظام لا تُثبّت — أثناء إعداد iOS، لا تختار اليابان أو الاتحاد الأوروبي كمنطقتك (فحوصات تنظيمية إضافية لا يمكن للجهاز الافتراضي تلبيتها)؛ اختر مثلًا الولايات المتحدة.

تطبيق يتعطل عند الإطلاق مع EXC_GUARD / GUARD_TYPE_MACH_PORT — أعد التصحيح باستخدام vphone-cli fw patch <name> --variant <v> --force-exc-guard، ثم أعد الاستعادة/التثبيت (#291). مفعّل دائمًا لقواعد iOS 18.

تثبيت ملف .ipa/.tipa — استخدم قائمة التثبيت في الجهاز الافتراضي قيد التشغيل (سحب وإفلات أو منتقي الملفات).

cfw install يعلق عند إعادة توقيع ثنائي نظام (مثل Campo)، والذاكرة ترتفع بلا حدود — خطأ معروف في ldid-procursus حتى 2.1.5-procursus7 (إصدار Homebrew stable الحالي): bytes(uint64_t) يستدعي __builtin_clzll(0) بدون حماية صفر، وهو سلوك غير محدد، وفي هذا البناء يتحول إلى طول 0 يسبب تجاوزًا سفليًا لعداد حلقة غير موقّع — يدور ldid بكتابة بايت واحد في كل مرة في مخزن مؤقت متنامٍ بدلًا من إنهاء العملية. يُطلق بواسطة أي قائمة تراخيص تحتوي على قيمة عدد صحيح تساوي 0 تمامًا (بعض ثنائيات نظام Apple الحقيقية تحتوي عليها). تم إصلاحه في المصدر لكن لم يُصدر بعد في إصدار موسوم؛ أعد البناء من المصدر: brew install --HEAD ldid-procursus && brew link --overwrite ldid-procursus. اقتل عملية ldid المعلقة أولًا (sudo kill -9 <pid>) إذا واجهتها بالفعل.

الأتمتة

يكشف vphone-cli عن مقبس تحكم للمضيف (<bundle>/vphone.sock) للتحكم البرمجي — لقطات شاشة، لمس، تمرير، مفاتيح أجهزة، حافظة — كل إجراء يعيد لقطة شاشة مضمّنة لاختبار E2E مدفوع بالذكاء الاصطناعي. راجع vphone-mcp لخادم MCP يغلّفه.

الشكر والتقدير

• wh1te4ever/super-tart-vphone-writeup