phantom-frida

# phantom-frida

`phantom-frida` يبني خادم Frida وGadget لنظام Android من المصدر مع تغيير مجموعة محددة من معرّفات وقت التشغيل القابلة للملاحظة. إنه أداة بناء وتحقّق، وليس وعدًا بهزيمة كل طريقة كشف خاصة بتطبيق معين.

هدف التوافق الحالي هو **Frida 17.16.4** على Android. الإصدارات الأخرى من Frida تُعامَل عمدًا على أنها غير موثّقة حتى تتكرر عقود المصدر والبناء الكامل وقبول الجهاز الجذر الخاص بها.

استخدم هذا المشروع فقط على التطبيقات والأجهزة التي تملكها أو مخوّل لاختبارها.

## ما الذي تم التحقق منه

يفصل المستودع ثلاثة أنواع من الأدلة:

1. تتحقق اختبارات الوحدات والاختبارات التجريبية (fixture) من معالجة المدخلات، وعقود تصحيح المصدر الدقيقة لـ Frida 17.16.4، وإعادة بناء DEX، وترقية القطع الأثرية، والبيانات الوصفية، وسير العمل، وسلوك الفشل.
2. يتطلب `build.py --verify` كلاً من الخادم وGadget، ويجرّد Gadget المرحّل، ثم يرفض علامات وقت التشغيل المحظورة المعروفة قبل نشر أي من القطعتين.
3. يشغّل `scripts/android_smoke.py` قطعة أثرية مبنية على جهاز واحد متجذر: نقل abstract-UNIX مصادَق، وRPC لعميل قياسي، وspawn، وattach، وتأكيدات جسر Java، وفحوصات `/proc`، وفحص ذاكرة خارجي بصلاحيات الجذر، وGadget محمّل بشكل منفصل.

اجتياز اختبار المصدر أو فحص البايتات ليس مكافئًا للتمويه في وقت التشغيل. يجب أن تتضمن الادعاءات حول سلوك Android تقرير اختبار الدخان المُنشأ والمُحرَّر.

## البناء باستخدام GitHub Actions

شغّل **Build Custom Frida** من تبويب Actions. سير عمل البناء القابل لإعادة الاستخدام:

- يتحقق من كل مدخلات البناء التي يتحكم بها المستخدم؛
- ينزّل Android NDK r29 من Google ويتحقق من المجموع الاختباري المنشور له؛
- يستنسخ شجرة مصدر جديدة من المنبع بدلاً من تخزين المصدر المعدَّل مؤقتًا؛
- يزيل رموز Gadget ولا يرفع إلا بعد اجتياز بوابات القطع الأثرية والعلامات الصارمة؛
- يتضمن `build-info.json` و`SHA256SUMS` في قطعة أثرية واحدة.

يحل سير العمل الأسبوعي أحدث إصدار عبر GitHub API المصادَق، ويستدعي سير عمل البناء نفسه للقراءة فقط، ويتحقق من القطعة الأثرية التي تم تنزيلها، ويصادق عليها، ويمنح إذن كتابة الإصدار فقط للمهمة النهائية.

## البناء المحلي

المتطلبات:

- Ubuntu 22.04 أو أحدث (يُدعم WSL)؛
- Python 3.10 أو أحدث؛
- Git، وcurl، وunzip، وسلسلة أدوات C/C++، وJDK 17، وNode.js 18 أو أحدث (يستخدم CI الإصدار Node.js 24.13.1)؛
- منصة Android SDK وأدوات البناء التي تحتوي على `android.jar` وD8؛
- حوالي 20 جيجابايت من مساحة القرص الحرة.

إذا تم حذف `--ndk-path`، يقوم البنّاء بتنزيل Android NDK r29 داخل `build/`. بناء arm64 متحقق منه بمدخلات مثبتة هو:

```bash
export ANDROID_SDK_ROOT=/path/to/Android/Sdk
python3 build.py \
  --version 17.16.4 \
  --name oemcodec \
  --arch android-arm64 \
  --port 27142 \
  --extended \
  --strict-wx \
  --verify
```

خيارات مفيدة:

```text
--version, -v    Exact Frida semantic version (required)
--name, -n       Lowercase replacement name, 3-20 characters
--arch, -a       One or more supported Android architectures
--port, -p       Listening port; omitted keeps 27042
--extended, -e   Apply the optional extended identifier transformations
--strict-wx      Harden Frida-owned persistent anonymous RWX mappings on Android
--temp-fixes     Apply opt-in, device-specific stability changes
--verify         Reject known forbidden markers in final artifacts
--skip-build     Patch source without compiling
--skip-clone     Use an existing source tree in the work directory
--ndk-path       Use an existing Android NDK r29 directory
```

## المخرجات وسلسلة الإسناد

بخصوص المثال أعلاه، يحتوي `output/` على:

```text
oemcodec-server-17.16.4-android-arm64
oemcodec-server-17.16.4-android-arm64.gz
oemcodec-gadget-17.16.4-android-arm64.so
oemcodec-gadget-17.16.4-android-arm64.so.gz
build-info.json
SHA256SUMS
```

يسجّل `build-info.json` البنّاءَ الدقيق، وFrida، والالتزامات (commits) الخاصة بـ frida-core، وإصدار NDK، ووقت البناء وفق UTC، والبنى، والاسم، والمنفذ، ووضع تجمّع الكود الصارم W^X، ورابط سير العمل عند البناء عبر Actions. تحقق من ملفات الثنائية التي تم تنزيلها قبل الاستخدام:

```bash
cd output
sha256sum --check SHA256SUMS
python3 -m json.tool build-info.json >/dev/null
```

تحصل الإصدارات الأسبوعية العامة أيضًا على مصادقة إثبات بناء من GitHub. يُعرّف `SHA256SUMS` مجموعة مخرجات واحدة؛ ولا يُتوقع تطابق تجزئات الثنائيات عبر مضيفات البناء المختلفة.

## التوافق مع العميل القياسي

يحافظ البنّاء على واجهات بروتوكول D-Bus ضمن `re.frida.*`، ومسار `/re/frida/GadgetSession`، وسلاسل واجهة برمجة تطبيقات JavaScript العامة `Frida`، ورموز C ABI المُولّدة التي تتطلبها العملاء القياسيون. إعادة تسمية تلك القيم ستكسر العقد الطبيعي بين عميل Frida وخادمه.

معرّف خدمة D-Bus، وحزمة JNI المساعدة، وبادئة مقبس zymbiote، ومعرّفات العمليات/المكتبات/المسارات المحددة، وأسماء الخيوط المحددة، ومنفذ مخصص اختياري هي تفاصيل تنفيذ منفصلة يمكن للبنّاء تحويلها. يرفض مدقّق المخرجات مجموعة العلامات الصريحة التالية:

```text
frida\0
frida-zymbiote
re/frida/HelperBackend
frida-server
frida-helper
frida-agent
frida-gadget
frida-eternal-agent
frida-generate-certificate
frida-main-loop
frida:rpc
FridaScriptEngine
GLib-GIO
GDBusProxy
GumScript
Frida/
gum-js-loop
gmain\0
gdbus\0
pool-frida
pool-spawner
jit-cache\0
```

تبقى سلسلة واجهة برمجة التطبيقات العامة الدقيقة `Frida\0` ومعرّفات بروتوكول `re.frida.*` المسموح بها محفوظةً عمدًا. بادئة HTTP/Inspector `Frida/` تُعد فشلًا في المُدقِّق ويتم إعادة تسميتها بشكل مستقل.

## قبول Android الجذري

ثبّت الربط الدقيق للغة Python المسجّل في `build-info.json`، وثبّت تبعية جسر Java المثبتة، ووصّل جهاز Android جذريًا واحدًا فقط:

```bash
python3 -m pip install "frida==17.16.4" frida-tools
npm ci --ignore-scripts

python3 scripts/android_smoke.py \
  --server output/oemcodec-server-17.16.4-android-arm64 \
  --gadget output/oemcodec-gadget-17.16.4-android-arm64.so \
  --name oemcodec \
  --port 27142 \
  --package com.example.app \
  --ndk build/android-ndk-r29 \
  --report android-smoke-report.json
```

يجب أن يكون الحزمة تطبيق Java مثبتًا ومصرحًا لك باختباره. يترجم الحزام (harness) `test_comprehensive.js` باستخدام `frida-java-bridge` الصريح المطلوب من Frida 17. يستمع كل من الخادم وGadget على مقبس abstract-UNIX مصادَق وعشوائي؛ وتوجد منافذ TCP الخاصة بالمضيف فقط كعمليات إعادة توجيه ADB ولا يتم كشف أي مستمع TCP على الجهاز. يقوم الحزام أيضًا بتجميع مسبار جذر متوافق مع ABI يفحص صور العميل (agent) وGadget المعيّنة في الذاكرة عبر `/proc/<pid>/mem`، خارج رؤية عملية Frida نفسها. وينظف عملياته وعمليات إعادة التوجيه ودليل الاختبار البعيد عند الخروج. ترفض بوابة `/proc` أيضًا أسماء واصفات الملفات القديمة `linjector` وقيمة `TracerPid` غير الصفرية.

يجب تسمية ملف إعداد Frida Gadget بجوار المكتبة باسم `lib<name>-gadget.config.so`؛ ويقوم الحزام بإنشاء هذا الملف ونشره.

## فحوصات التطوير

```bash
python -m pip install --requirement requirements-dev.txt
npm ci --ignore-scripts
python -m pytest
ruff check .
ruff format --check .
mypy build.py patches.py namegen.py scripts
node --check test_comprehensive.js
bash -n build-wsl.sh
go run github.com/rhysd/actionlint/cmd/[email protected]
```

انظر [CONTRIBUTING.md](https://github.com/theqmaks/phantom-frida/blob/master/CONTRIBUTING.md) للحصول على متطلبات الأدلة الكاملة.

## هيكل المستودع

```text
build.py                 Clone, patch, compile, verify, and collect artifacts
patches.py               Source and same-length binary transformations
namegen.py               Seeded build-name and port generation
scripts/android_smoke.py Rooted Android Server/Gadget acceptance harness
test_comprehensive.js    Structured Frida 17 Java bridge assertions
tests/                   Unit, contract, fixture, and workflow tests
.github/workflows/       CI, CodeQL, reusable build, and release isolation
```

## الحدود المعروفة

- فقط Frida 17.16.4 هو هدف التحقق الحالي؛ ولا يُستنتج الدعم لجميع إصدارات 17.x أو 16.x.
- يغيّر `--temp-fixes` سلوك وقت التشغيل ويبقى اختياريًا.
- غياب العلامات لا يُثبت مقاومةً للكشف السلوكي، أو كشف السلامة، أو كشف التوقيت، أو الكشف الخاص بتطبيق معين.
- الحفاظ على التوافق مع العملاء القياسيين يحافظ على سلوك ABI/البروتوكول العام. قد يظل الفحص النشط للبروتوكول وفحوصات سلامة الكود قادرين على تحديد وجود الأداة.
- لا يخفي هذا البنّاء الجذرَ، أو إطلاق التطبيق الآلي، أو تغييرات كود Interceptor، أو سلاسل نصوص المستخدم، أو الإخفاقات التي يبلغ عنها التوثيق عن بُعد.
- يفصل `--strict-wx` الكود القابل للتنفيذ الخاص بحقن Android عن البيانات القابلة للكتابة وصفحات المكدس، ويعطّل تجمّعات كود Gum الدائمة RWX، ويضع كود إغلاق `NativeCallback` الخاص بـ GumJS على صفحات RX مخصصة مع إبقاء تخزين libffi للقراءة/الكتابة، ويُنهي الكود المُولّد حديثًا كـ RX. إذا لم يتوفر libc بعيد مطابق، يفشل حقن Android بشكل مغلق بدلاً من استخدام آلية RWX الاحتياطية من المنبع. يحافظ على الصفحات التي كانت بالفعل RWX ولا يرفض طلبًا صريحًا من نصوص المستخدم لذاكرة RWX. عينة `/proc/maps` وقت التشغيل لا تُثبت عدم حدوث تغيير مؤقت في صلاحيات RWX أثناء تصحيح الكود القابل للتنفيذ.
- تقوم بوابة الذاكرة الخارجية بفحص صور العميل/Gadget المعيّنة في الذاكرة بحثًا عن مجموعة العلامات الصريحة الخاصة بها؛ وهي ليست فحصًا عامًا لكل صفحة كومة مجهولة.
- يتطلب الوكلاء الخام في Frida 17 استيرادًا صريحًا للجسور أو تجميعها. يستخدم الحزام `frida.Compiler`؛ ويوفر Frida REPL والمتعقب جسورهما المدمجة الخاصة بهما.

## الاعتمادات والترخيص

- [Frida](https://frida.re/) من إعداد Ole André Ravnas والمساهمين
- [ajeossida](https://github.com/hackcatml/ajeossida) من إعداد hackcatml

كود البنّاء مرخّص بموجب MIT. تحتفظ الثنائيات المُولّدة بترخيص المنبع؛ انظر [THIRD_PARTY_NOTICES.md](https://github.com/theqmaks/phantom-frida/blob/master/THIRD_PARTY_NOTICES.md).