magic-extractor

# مستخرج السحر (Magic Extractor)

<p align="center">
  <img src="https://assets.kitploit.com/production/public/readmes/7022/1ecc2fe011937465abd72031b0aa914c85a941290702969520086741770b5bea.png" alt="Magic Extractor" width="250" height="250">
</p>

## الوصف
مستخرج السحر هو أداة استخراج شاملة لنظام ويندوز تتحقّق من هوية ملف عبر عدة كاشفات وتوجّهه إلى برنامج الاستخراج المرفق الصحيح. يهدف إلى تغطية صيغ الضغط السائدة، وبرامج التثبيت التي تراها فعليًا اليوم، ومجموعة من أدوات الأرشفة الأقل شيوعًا.

يكتشف تلقائيًا أكثر من **80 صيغة** — الأرشيفات، وبرامج التثبيت، وصور الأقراص، وصور الطب الشرعي (EWF/AFF/AD1)، وصور الأقراص الضوئية، ومخازن البريد، وبرامج الترميز الحديثة. راجع [`formats.md`](https://github.com/xchwarze/magic-extractor/blob/master/docs/formats.md) للقائمة الكاملة.

## بدء سريع
نزّل [الإصدار الأحدث](../../releases/latest)، فكّ ضغطه، ثم شغّل:
```text
magic-extractor.exe extract mystery.bin
```
راجع [أمثلة](#أمثلة) لأوامر `identify` و`list` و`carve` و`--recursive` و`--bruteforce`.

## هيكل المشروع
- `cli`: الكود المصدري.
  - `bin`: ملفات الكاشفات والمستخرجات المرفقة.
    - `detectors`: DIE وMagika وbinwalk (يتم تحويل قواعد TrID إلى `data/signatures.json`).
    - `extractors`: 7z وunrar وunace وunshield وlessmsi وdark (WiX) وغيرها.
  - `data`: إعدادات وقت التشغيل، تُحمَّل ديناميكيًا (انظر أدناه).
  - `formats`: وحدة معالجة واحدة لكل عائلة صيغ.
- `gui`: واجهة أمامية اختيارية مبنية على tkinter تغلّف CLI (انظر [الواجهة الرسومية](#الواجهة-الرسومية)).
- `test`: ملفات نموذجية لكل صيغة (معدّات لاختبارات الاستخراج/الكشف).
- `tools`: أدوات المطوّرين (`generate_data.py` — يبني ملفات البيانات من وحدات المعالجة).

يبقي البناء المُجمَّع ملفات `bin/` و`data/` و`config.ini` خارج ملف exe بحيث يمكن تحديثها باستبدال الملفات؛ ويجدها محلّل المسار في `main.py` بجانب الملف التنفيذي (عند التجميد) أو داخل `cli/` (في بيئة التطوير).

## كيف يعمل الكشف
للاستخراج العادي، تعمل الكاشفات بهذا الترتيب مع **خروج مبكر** — أول كاشف يعثر على معالج معروف يفوز (الأرخص أولًا، لذلك عادةً ما يتم تخطّي نموذج التعلّم الآلي):

1. **puremagic** — بايثون نقي، بدون عمليات فرعية؛ فحص MIME رخيص للأرشيفات جيدة البنية.
2. **التواقيع المدمجة** — أنماط magic-byte في `data/signatures.json`؛ تسمّي أدوات أرشفة تفوتها المحركات (bcm وdgca وkgb وuharc وalzip وfreearc وغيرها) دون أي عملية خارجية.
3. **DIE** (Detect It Easy) — محرك تواقيع؛ المتخصص في برامج التثبيت وPE وSFX.
4. **binwalk** — مفاتيح أنواع قصيرة (cpio وlzma وغيرها) والمحتوى المضمّن.
5. **Magika** — كاشف نوع المحتوى بالذكاء الاصطناعي من Google، كشبكة أمان شاملة.

يساهم كل كاشف بشكل فريد (إنها متكاملة وليست زائدة عن الحاجة): قاعدة التواقيع تسمّي أدوات الأرشفة التي تفوتها المحركات، ويتعامل DIE مع برامج التثبيت/PE، ويلتقط binwalk بعض الأنواع التي تفوتها البقية، بينما يغطي puremagic/Magika أنواع MIME.

يقوم PureMagic 2.x أيضًا بفحص عميق مدرك للمحتوى عندما يستلم الملف كاملًا. تحليل الملف الكامل هو الإعداد الافتراضي؛ ويقوم معدِّل `--fast-check` الاختياري بتمرير أول 64 كيلوبايت فقط عندما تكون سرعة الإقلاع أهم من الفحص العميق.

تعلن كل وحدة معالجة عن مؤشراتها الخاصة عبر `detection_mimes()` / `detection_names()` / `detection_signatures()`؛ ويقوم `tools/generate_data.py` بتجميعها في `data/handlers.json` و`data/signatures.json` (مع إمكانية دمج `data/extra_detections.json` اختياري في الأعلى). لا يُستخدم TrID.

> ملاحظة: أي صيغة تفتقد تواقيعها في
> [`magic_data.json`](https://github.com/cdgriffith/puremagic/blob/master/puremagic/magic_data.json)
> الخاص بـ puremagic (أو التي يبلّغ عنها puremagic فقط كنوع عام `application/octet-stream`)،
> يجب أن تعلن عن إدخال `detection_signatures()` مخصص في معالجها — وإلا
> فلن يتم اكتشافها عبر المحتوى.

- `--bruteforce` يعطّل الخروج المبكر: يعمل كل كاشف ويتم تجربة كل معالج تم اكتشافه بدوره (مفيد عندما تكون التخمينة الأولى خاطئة).
- الملفات التنفيذية التي لا يتعرّف عليها أي كاشف تُوجَّه إلى معالجات برامج التثبيت المغلفة (BitRock وClickteam وInno وغيرها)، والتي تتحقق من نفسها بنفسها.
- يستخدم الأمر الفرعي `carve` أيضًا خريطة الإزاحات من binwalk لاستخراج الأرشيفات المضمّنة عند إزاحات عشوائية (مثلًا داخل صور البرامج الثابتة).

توجد خريطة التوجيه من الكشف إلى المعالج في `data/handlers.json` (منسّقة يدويًا، تُحمَّل وقت التشغيل)؛ وتوجد قائمة حظر للرموز العامة في `data/detection_blacklist.json`.

## الصيغ المدعومة
راجع [formats.md](https://github.com/xchwarze/magic-extractor/blob/master/docs/formats.md) للقائمة الكاملة للصيغ ومعالجاتها.

## إضافة صيغة
لإضافة دعم لصيغة جديدة، راجع
[docs/adding-a-handler.md](https://github.com/xchwarze/magic-extractor/blob/master/docs/adding-a-handler.md) — الدليل الشامل من البداية إلى النهاية
(صنف المعالج، إعلان الكشف، البحث في DIE/TrID، تواقيع magic،
إعادة توليد بيانات التوجيه، تجميع الأداة، والاختبار).

## التثبيت (من المصدر)
معظم المستخدمين يكتفون بتنزيل الإصدار الجاهز (راجع [بدء سريع](#بدء-سريع)). للتشغيل من المصدر:
مطلوب بايثون 3.12 أو أحدث.

```bash
git clone <repo-url>
cd magic-extractor
pip install -r cli/requirements.txt
```

## الاستخدام
يستخدم مستخرج السحر أوامر فرعية:
```bash
python cli/main.py extract  <path> [output_dir] [options]   # كشف واستخراج
python cli/main.py identify <path>                          # تقرير النوع + المعالجات المرشحة
python cli/main.py list     <path>                          # سرد محتويات الأرشيف
python cli/main.py carve    <path> [output_dir] [options]   # اقتطاع الأرشيفات المضمّنة (إزاحات binwalk)
```
المسار المجرّد دون أمر فرعي يُفترض أنه `extract` (متوافق مع الإصدارات السابقة):
```bash
python cli/main.py <path> <output_dir> [options]
```

خيارات `extract`:
- `--password <password>`: كلمة المرور للأرشيفات المشفرة.
- `-r`, `--recursive`: استخراج الأرشيفات الموجودة داخل مجلد الإخراج (محدود بـ `--max-depth`، الافتراضي 5).
- `-b`, `--bruteforce`: تجربة كل معالج تم اكتشافه بدل التوقف عند الأول.
- `--open-output-folder <true|false>`: فتح مجلد الإخراج عند الانتهاء.
- `--check-free-space <true|false>`: التحذير إذا كان قرص الإخراج قد لا يتسع.
- `--check-unicode <true|false>`: التحذير بشأن أسماء الملفات المستخرجة غير ASCII.
- `--fix-file-extensions <true|false>`: منح الملفات المستخرجة دون امتداد امتدادًا بناءً على المحتوى (لا يستبدل أي امتداد موجود أبدًا).
- `--create-log-files <true|false>`: كتابة سجل لكل تشغيل في مجلد الإخراج.

  (كل خيار يأخذ قيمته من `config.ini` عند حذفه؛ يمكن دمجه مع
  `--update-defaults` لحفظ القيمة المعطاة — مثلًا `--open-output-folder false
  --update-defaults` يطفئ افتراضيًا محفوظًا سابقًا.)
- `--fast-check`: فحص أول 64 كيلوبايت فقط بدل تشغيل كشف الملف الكامل.
- `--update-defaults`: حفظ الإعدادات المعطاة كافتراضيات في `config.ini`.

خيارات `carve`: `--list` (طباعة جدول أجزاء binwalk)، `--fragment N` (اقتطاع جزء واحد
حسب الفهرس)، `--raw` (اقتطاع كل الأجزاء، وليس فقط المعروفة للمعالجات).

> في الأمثلة أدناه، `magic-extractor` هو ملف `.exe` المُجمَّع. من المصدر، استبدله
> بـ `python cli/main.py` — الوسائط متطابقة.

## أمثلة

**استخراج أرشيف** — لا تحتاج إلى معرفة نوعه؛ يتم اكتشافه تلقائيًا:
```text
magic-extractor extract mystery.bin
# يستخرج إلى mystery_extracted/ بجانب الملف
```

**تعرّف** على ملف دون لمسه — يعرض ما رآه كل كاشف وأي معالج سيتم تشغيله:
```text
magic-extractor identify setup.exe
File: setup.exe
  [DIE] detect   inno setup installer
Candidate handlers (in order):
  - FormatInnoSetupHandler
```

**سرد** محتويات أرشيف (بدون استخراج):
```text
magic-extractor list backup.7z
```

**استخراج تكراري** — استخراج الأرشيفات الموجودة داخل مجلد الإخراج (مثلًا ملف .tar.gz، أو
برنامج تثبيت يحتوي على مزيد من الأرشيفات)، حتى `--max-depth` مستويات:
```text
magic-extractor extract app-1.0.tar.gz --recursive
```

**Bruteforce** — عندما يكون الكشف غير مؤكد، جرّب كل معالج طابق بدل التوقف عند الأول:
```text
magic-extractor extract weird-archive.dat --bruteforce
```

**اقتطاع** — سحب الأرشيفات المضمّنة عند إزاحة ما داخل ملف أكبر
(أمر كلاسيكي لصور البرامج الثابتة). افحص أولًا، ثم اقتطع:
```text
magic-extractor carve router-firmware.bin --list
IDX      OFFSET          SIZE  NAME       DESCRIPTION
  0  0x00000000       793,720  pe         Windows PE binary
  1  0x000c1c78     2,495,983  lzma       LZMA compressed data

magic-extractor carve router-firmware.bin              # اقتطاع + استخراج الكتل المعروفة
magic-extractor carve router-firmware.bin --fragment 1 # اقتطاع الجزء رقم 1 فقط
```

## الواجهة الرسومية
واجهة أمامية اختيارية مبنية على tkinter (في `gui/`) تغلّف CLI — نافذة بأسلوب Universal-Extractor
تحتوي أوضاع `extract` و`scan` و`carve`، وسحب وإفلات، وطابور معالجة بالدفعات، وسجل تشغيل،
وحوار تفضيلات. خيار Bruteforce متاح ضمن خيارات التشغيل. تستدعي نفس `main.py`،
لذا يكون الكشف والاستخراج متطابقين تمامًا.
```bash
python gui/main.py                 # تشغيل النافذة
python gui/main.py <file> [outdir] # تعبئة المصدر مسبقًا (والوجهة)
python gui/main.py <file> /scan    # تعبئة المصدر والبدء في وضع التعرف
```
يتطلب السحب والإفلات الحزمة الاختيارية `tkinterdnd2` (`pip install -r gui/requirements.txt`)؛
بدونها تعمل النافذة لكن بدون دعم الإفلات. يمكنها أيضًا تسجيل إدخال في قائمة السياق
لمستكشف ويندوز من حوار التفضيلات.

## البناء (ويندوز)
```bash
cd cli
pyinstaller --onefile main.py --name magic-extractor --collect-data puremagic
```
ثم انسخ `bin/` و`data/` و`config.ini` بجانب `dist/magic-extractor.exe`.
يقوم CI بذلك تلقائيًا — راجع `.github/workflows/release.yml`.

## الترخيص
MIT — راجع `LICENSE.txt`. ملاحظة: الملفات الثنائية الخارجية المرفقة للمستخرجات/الكاشفات
داخل `cli/bin/` تخضع لتراخيصها الخاصة (بعضها برمجيات مجانية مملوكة)
ولا يغطيها ترخيص MIT؛ تحقق من شروط إعادة توزيعها قبل الشحن.

## المؤلفون
- المطوّر الرئيسي: DSR! — [email protected]
- شكرًا لجميع المساهمين.