F --> G1[Passive scanners]
F --> G2[Active scanners]

I[template-tool] --> H[CVE templates]
H --> G2

G1 --> J[Findings]
G2 --> J
J --> K[Reporter]
K --> L[Auto Reports]
K --> M[CI/CD Controls]

## لماذا ApiHunter؟

### المزايا الأساسية

- **معمارية تركز على واجهات برمجة التطبيقات أولاً**: مصممة خصيصًا لواجهات REST/GraphQL، وليست مكيفة من ماسحات تطبيقات الويب
- **تقليل النتائج الإيجابية الخاطئة بذكاء**:
  - كشف الصفحات أحادية التطبيق (SPA) مع استكشاف إشارات التحذير
  - التحقق من الأسرار حسب السياق (الواجهة الأمامية مقابل الخلفية)
  - التحقق من محتوى النص الأساسي والتحقق من المُحيل (Referer)
  - بصمة الرد لتخطي النتائج المكررة
- **آمنة للإنتاج حسب التصميم**:
  - التوافقية التكيفية (AIMD) التي تتراجع عند حدوث أخطاء
  - تحديد معدل لكل مضيف مع تأخيرات قابلة للتكوين
  - ضوابط الأدب (إعادة المحاولة، المهلات، تجنب جدار الحماية لتطبيقات الويب WAF)
  - وضع التشغيل الجاف للفحوصات النشطة
- **التخفي والتهرب**:
  - تدوير وكيل المستخدم (User-Agent) في وقت التشغيل من مجموعة منسقة (assets/user_agents.txt)
  - تأخيرات عشوائية مع تشويش (jitter)
  - فرض تأخير لكل مضيف (يتجنب أنماط الاندفاع)
  - منطق إعادة المحاولة مع التراجع الأسي (exponential backoff)
  - حقن رؤوس مخصصة للاندماج مع حركة المرور المشروعة
  - توقيت تكيفي بناءً على استجابات الخادم
  - لا توجد بصمات ماسح ضوئي ثابتة في الوضع الافتراضي

### نظرة متعمقة في تقنيات التخفي

يستخدم ApiHunter العديد من تقنيات التخفي لتجنب الكشف بواسطة جدران حماية تطبيقات الويب (WAF) وأنظمة الحماية من البوتات:

#### 1. تدوير وكيل المستخدم
**ما يفعله:** يقوم بالتدوير العشوائي بين أكثر من 100 سلسلة وكيل مستخدم حقيقية للمتصفحات من ملف (`assets/user_agents.txt`)

**لماذا يعمل:** عادةً ما تستخدم البوتات نفس وكيل المستخدم (مثل `curl/7.68.0`). بالتظاهر بأنك Chrome أو Firefox أو Safari وما إلى ذلك، تندمج مع حركة المرور المشروعة

**تشبيه بسيط:** مثل ارتداء تنكرات مختلفة بدلاً من ارتداء نفس الزي دائمًا

#### 2. التوقيت العشوائي والتشويش
**ما يفعله:** يضيف تأخيرات عشوائية بين الطلبات (يتم التحكم فيها بواسطة `--delay-ms`) مع تشويش (اختلافات عشوائية صغيرة)

**لماذا يعمل:** ترسل البوتات الطلبات على فترات زمنية مثالية (بالضبط 100 مللي ثانية بين كل منها). البشر غير متوقعين. التوقيت العشوائي يجعل حركة المرور تبدو عضوية

**تشبيه بسيط:** المشي بخطوات غير منتظمة بدلاً من السير كالروبوت

#### 3. فرض التأخير لكل مضيف
**ما يفعله:** يتتبع التأخير بشكل منفصل لكل نطاق، وليس بشكل عام

**لماذا يعمل:** يمنع أنماط الاندفاع حيث تصل إلى مضيف واحد 50 مرة بشكل فوري. يرى كل مضيف طلبات مهذبة ومتباعدة

**تشبيه بسيط:** التناوب في محادثات مختلفة بدلاً من الصراخ في شخص واحد مرارًا وتكرارًا

#### 4. التوافقية التكيفية (AIMD)
**ما يفعله:** يبطئ تلقائيًا عند الحصول على أخطاء 429 (تحديد معدل) أو 503 (خادم مشغول)، ويسرع عند النجاح

**لماذا يعمل:** يتراجع عند الكشف، يحاكي كيفية إعادة محاولة المتصفحات. ترى جدران الحماية لتطبيقات الويب "هذا العميل يحترم حدودنا"

**تشبيه بسيط:** التباطؤ عند ازدحام المرور، والإسراع على الطرق المفتوحة

#### 5. إعادة المحاولة مع التراجع الأسي
**ما يفعله:** عند فشل طلب، ينتظر 1 ثانية، ثم 2 ثانية، ثم 4 ثوانٍ قبل إعادة المحاولة

**لماذا يعمل:** يعيد العملاء الشرعيون المحاولة بلطف. غالبًا ما تقوم البوتات بالضرب فورًا أو تستسلم

**تشبيه بسيط:** طرق باب، والانتظار لفترة أطول في كل مرة بدلاً من الدق بشكل مستمر

#### 6. لا توجد بصمات ماسح ضوئي
**ما يفعله:** لا يرسل رؤوسًا مثل `X-Scanner: ApiHunter` أو أنماطًا يمكن التنبؤ بها

**لماذا يعمل:** تترك العديد من الأدوات توقيعات (قوالب Nuclei، أنماط sqlmap). يتجنب ApiHunter العلامات الواضحة

**تشبيه بسيط:** عدم ارتداء بطاقة اسم تقول "مختبر أمني"

#### 7. إعادة استخدام الاتصال وتجميعه
**ما يفعله:** يستخدم تجمعات عميل HTTP لكل مضيف، ويبقي الاتصالات حية

**لماذا يعمل:** تعيد المتصفحات استخدام الاتصالات. فتح/إغلاق لكل طلب يبدو مريبًا

**تشبيه بسيط:** إبقاء الباب مفتوحًا بدلاً من إغلاقه ورن الجرس مرة أخرى

#### 8. حقن رؤوس مخصصة
**ما يفعله:** يمكن إضافة رؤوس مثل `Referer`، `X-Forwarded-For`، ملفات تعريف ارتباط مخصصة

**لماذا يعمل:** يجعل الطلبات تبدو وكأنها جاءت من تدفق تطبيق مشروع (نقر على رابط، لديه ملفات تعريف ارتباط جلسة)

**تشبيه بسيط:** إظهار تذكرة دخول عند دخول المكان بدلاً من القفز فوق السياج

#### مقارنة الكشف

| التقنية | بدون تهرب | مع تهرب |
|-----------|----------------|-------------|
| **وكيل المستخدم** | `python-requests/2.28.0` (بوت واضح) | `Mozilla/5.0 (Windows NT 10.0; Win64; x64)...` (يشبه Chrome) |
| **التوقيت** | فترات مثالية 100 مللي ثانية → حظر من WAF | 120 مللي ثانية، 95 مللي ثانية، 180 مللي ثانية → يبدو بشريًا |
| **إعادة المحاولة** | إعادة محاولة فورية → حظر | انتظر 1 ثانية→2 ثانية→4 ثوانٍ → "عميل صبور" |
| **التوافقية** | 100 ضربة متوازية → إنذار | تكيفي 5→10→3 بناءً على الاستجابة → "متصفح مهذب" |

#### متى تستخدم `--waf-evasion`

- اختبار واجهات برمجة التطبيقات الإنتاجية مع Cloudflare/Akamai/AWS WAF
- تجنب حظر عناوين IP أثناء الفحوصات الكبيرة
- اختبارات الاختراق حيث تحتاج إلى البقاء تحت الرادار

- **أصلي لـ CI/CD**:
  - فرق خط الأساس (الإبلاغ عن النتائج الجديدة فقط)
  - إخراج NDJSON المتدفق للمراقبة في الوقت الفعلي
  - SARIF 2.1.0 لفحص كود GitHub/GitLab
  - قناع رمز الخروج للتحكم في خط الأنابيب
  - التصفية على أساس الشدة وعتبات الفشل
- **الأداء على نطاق واسع**:
  - وقت تشغيل Rust غير المتزامن (tokio) مع تجريدات بدون تكلفة
  - فحص متزامن مع تعدد موازٍ محدود بإشارة (semaphore-bounded parallelism)
  - تجمعات عميل HTTP لكل مضيف لتجنب اختناقات الاتصال
  - استخدام ذاكرة فعال (بدون توقف GC)
- **دعم شامل للمصادقة**:
  - تدفقات مصادقة قائمة على JSON مع استخراج ملف تعريف الارتباط/الرأس
  - اختبار IDOR/BOLA ثنائي الهوية
  - استيراد ملف الجلسة (تكامل مع Excalibur)
  - مصادقة Bearer و Basic والرأس المخصص
  - عميل غير مصادق تلقائي لفحوصات تصعيد الامتيازات

## وحدات الماسح الضوئي

يتضمن ApiHunter 13 وحدة ماسح ضوئي مدمجة. راجع [docs/scanners.md](https://github.com/teycir/apihunter/blob/HEAD/docs/scanners.md) للحصول على منطق الكشف المفصل.

| الماسح الضوئي | النوع | ما يكتشفه |
|---------|------|----------------|
| **CORS** | سلبي | نطاقات المصدر wildcard، النطاقات المنعكسة مع بيانات الاعتماد، قبول نطاق المصدر null، ثغرات تجاوز التعبير المنتظم (هجمات اللاحقة/البادئة)، عدم وجود Vary: Origin، طرق ما قبل الطلب غير الآمنة |
| **CSP** | سلبي | عدم وجود Content-Security-Policy، توجيهات unsafe-inline/unsafe-eval، مصادر wildcard، مضيفات CDN قابلة للتجاوز (أدوات JSONP)، عدم وجود frame-ancestors |
| **GraphQL** | سلبي | تمكين الاستبطان (Introspection)، حقول مخطط حساسة (أنواع المستخدم/كلمة المرور/الرمز)، اقتراحات الحقول (تسريب المخطط)، تجميع الاستعلامات، تضخيم الأسماء المستعارة (DoS)، كشف GraphiQL/Playground |
| **JWT** | سلبي | رموز alg=none، أسرار HS256 ضعيفة (قائمة كلمات)، انتهاء صلاحية مفقود/مفرط، مطالبات حساسة في الحمولة، ثغرات الارتباك في الخوارزمية |
| **OpenAPI** | سلبي | مخططات أمان مفقودة، عمليات بدون متطلبات مصادقة، نقاط نهاية تحميل ملف، عمليات قديمة لا تزال موجودة، نقاط نهاية حساسة غير مؤمنة |
| **إصدارات API** | سلبي | كشف رأس الإصدار، إصدارات واجهة برمجة تطبيقات قديمة/جديدة متزامنة، رؤوس الإهمال، وانحراف الرد عبر متغيرات الاستعلام/الإصدار الحميدة (بالإضافة إلى الوضع العميق عبر `--response-diff-deep`) |
| **gRPC/Protobuf** | سلبي + نشط | إشارات نقل/نوع محتوى gRPC، تلميحات سطح protobuf، وإشارات اختيارية لاستقصاء الانعكاس/الصحة |
| **أمان API** | سلبي + نشط | رؤوس أمان مفقودة (X-Content-Type-Options، X-Frame-Options)، كشف إصدار الخادم، وصول غير مصادق إلى مسارات حساسة، تعداد طرق HTTP، نقاط نهاية التصحيح، أنماط كشف الأسرار، فحوصات IDOR/BOLA نشطة (مقارنة النص الأساسي + الرأس المحدد)، استقصاءات رد اتصال SSRF العمياء، وإشارات استقصاء البوابة/التجاوز |
| **التخصيص الجماعي (Mass Assignment)** | نشط | حقول حساسة منعكسة (is_admin، role، permissions)، تغييرات حالة مستمرة، تصعيد امتيازات عبر حقن الحقول |
| **OAuth/OIDC** | نشط | تجاوز التحقق من URI إعادة التوجيه، معلمة حالة مفقودة، مشكلات دعم PKCE (S256 مفقود، مسموح بـ plain)، تمكين التدفق الضمني، تمكين منح كلمة المرور |
| **تحديد المعدل** | نشط | تحديد معدل مفقود (استقصاءات اندفاعية)، رؤوس Retry-After مفقودة، تجاوز انتحال رأس IP (X-Forwarded-For) |
| **WebSocket** | نشط | قبول ترقية WebSocket على المسارات الشائعة، التحقق من صحة المصدر مفقود، اتصالات WebSocket غير مصادقة |
| **قوالب CVE** | نشط | كشف CVE مدفوع بالقوالب من `assets/cve_templates/*.toml` (168 قالبًا حاليًا)، مطابقة تفاضلية للخط الأساسي مقابل التجاوز |

**تعمل الماسحات السلبية** افتراضيًا وتحلل الاستجابات دون إرسال طلبات مخصصة.  
**تتطلب الفحوصات/الماسحات النشطة** `--active-checks` وترسل استقصاءات قد تكون اختراقية (IDOR/BOLA، طفرات، اختبارات تجاوز).  
يعيش IDOR/BOLA تحت ماسح `أمان API` (لا يوجد علم مخصص `--no-idor`؛ استخدم `--no-api-security` لتعطيله).

### ملاحظات إخراج الوحدة والإشارات

تلخص هذه الملاحظات كيفية إصدار النتائج وما الذي يسبب الضوضاء عادةً:

| الوحدة | بادئة النتيجة / الشكل | النتائج الإيجابية الخاطئة الشائعة | النتائج السلبية الخاطئة الشائعة |
|---------|-------------------------|-------------------------|-------------------------|
| CORS | `cors/*` مع حقول المصدر/الدليل | الانعكاس على مسارات غير حساسة | عمليات التحقق من المصدر المطبقة فقط على المسارات المصادق عليها |
| CSP | `csp/*` مع دليل التوجيه | CSP قديم مطبق عن قصد أثناء الترحيل | CSP يتم تسليمه فقط على مسار CDN الإنتاجي |
| GraphQL | `graphql/*` مع نقطة النهاية + إشارة القدرة | ملعب عام مخصص للمستأجرين الداخليين/الاختباريين | ضوابط المخطط ممكّنة فقط بعد المصادقة |
| JWT | `jwt/*` مع دليل مطالبة/رأس الرمز | رموز اختبار/عرض في استجابات اصطناعية | الرمز لا يظهر أبدًا في الاستجابات الممسوحة |
| OpenAPI | `openapi/*` مع سياق العملية/الأمان | المواصفات تتضمن عن قصد نقاط نهاية قديمة ولكن محظورة | المواصفات غير متوفرة أو مقسمة عبر وثائق خاصة |
| إصدارات API | `api_versioning/*` + `response_diff/*` | إصدارات متعددة مدعومة أثناء الترحيل المتحكم به | مسارات الإصدار غير قابلة للاكتشاف من مجموعة البذور الحالية |
| gRPC/Protobuf | `grpc_protobuf/*` مع دليل النقل/الانعكاس | بيانات وصفية تشبه gRPC على بروكسيات الحافة بدون سطح RPC مكشوف | نقاط نهاية gRPC خلف مضيف/مسار منفصل لا يتم الوصول إليها من مجموعة البذور |
| أمان API | `api_security/*` مع دليل الرأس/المسار/الطريقة | نقاط نهاية تصحيح/اختبار معرضة عن قصد في غير الإنتاج | الضوابط مطبقة خلف سياق المصادقة/الجلسة |
| التخصيص الجماعي | `mass_assignment/*` مع دلتا منعكسة/مستمرة | سلوك الصدى الذي لا يستمر في حالة الواجهة الخلفية | الطفرات مرفوضة بواسطة قواعد تحقق مخفية |
| OAuth/OIDC | `oauth/*` مع دليل إعادة التوجيه/البيانات الوصفية | تكوين IdP غير إنتاجي بسياسات متساهلة | السياسات الديناميكية غير مرئية في البيانات الوصفية |
| تحديد المعدل | `rate_limit/*` مع سلوك الاندفاع/429 | تشكيل حركة المرور العام يخفي سلوك المحدد على مستوى التطبيق | المحددات ذات النافذة الطويلة لا يتم تشغيلها بواسطة نافذة استقصاء قصيرة |
| WebSocket | `websocket/*` مع فحوصات الترقية/المصدر | نقاط نهاية WS عامة عن قصد مجهولة | المصادقة مطلوبة عبر رؤوس المصافحة غير المقدمة في الاستقصاء |
| قوالب CVE | `cve/<id>/<check>` مع دليل القالب | تصادم البصمة على نقاط النهاية العامة | المسار/السياق الضعيف لا يتم الوصول إليه من عناوين URL البذرة |

للحصول على تفاصيل الفحص الواحد تلو الآخر وإرشادات المعالجة، راجع [docs/scanners.md](https://github.com/teycir/apihunter/blob/HEAD/docs/scanners.md) و [docs/findings.md](https://github.com/teycir/apihunter/blob/HEAD/docs/findings.md).
تتضمن وثائق الماسح الآن [كتالوج فحص الوحدة](https://github.com/teycir/apihunter/blob/HEAD/docs/scanners.md#module-check-catalog) المتوافق مع المصدر و [نموذج توقع النتائج الإيجابية الخاطئة](https://github.com/teycir/apihunter/blob/HEAD/docs/scanners.md#false-positive-expectation-model).

## الميزات

### التحليل الأمني السلبي
- **كشف سوء تكوين CORS**:
  - إنشاء نطاق المصدر ديناميكيًا بناءً على المجال الهدف
  - اختبار تجاوز التعبير المنتظم (هجمات اللاحقة/البادئة)
  - تسجيل الشدة مع مراعاة بيانات الاعتماد
  - كشف المصدر wildcard والمصدر null
- **تحليل سياسة CSP**:
  - كشف سياسة أمان المحتوى المفقودة/الضعيفة
  - توجيهات unsafe inline/eval
  - كشف المصدر wildcard
  - أنماط تجاوز السياسة
- **أمان GraphQL**:
  - كشف استعلام الاستبطان
  - تحليل اسم النوع/الحقل الحساس
  - كشف دعم تجميع الاستعلامات
  - استقصاء تضخيم الأسماء المستعارة (DoS)
  - تجربة الطفرات النشطة (`--active-checks`، يدعم `--dry-run`)
  - كشف GraphiQL/Playground
- **تحليل رمز JWT**:
  - ارتباك الخوارزمية (alg=none، HS256→RS256)
  - كشف السر الضعيف (قائمة كلمات منسقة)
  - كشف الرمز طويل العمر (انتهاء صلاحية مفقود/مفرط)
  - كشف المطالبة الحساسة
  - استخراج الرمز من الرؤوس وملفات تعريف الارتباط
- **تحليل OpenAPI/Swagger**:
  - التحقق من مخطط الأمان
  - كشف نقطة نهاية تحميل الملف
  - وضع علامة على العمليات القديمة
  - تعريفات أمان مفقودة
  - تخزين المواصفات مؤقتًا للأداء
- **تغطية gRPC/Protobuf**:
  - كشف بيانات وصفية/نوع محتوى استجابة gRPC
  - كشف تلميحات سطح protobuf من بيانات وصفية لنقطة النهاية/شكل المسار
  - إشارات استقصاء انعكاس/صحة اختيارية على مسارات gRPC المعروفة
- **كشف تسريب الأسرار**:
  - مفاتيح AWS (AKIA*، مفاتيح سرية)
  - مفاتيح Google API (AIza*)
  - رموز GitHub (ghp_*، github_pat_*)
  - رموز Slack (xox*)
  - مفاتيح Stripe (sk_live_*، pk_live_*)
  - عناوين URL لقاعدة البيانات، مفاتيح خاصة، رموز Bearer
  - التحقق السياقي (يقلل النتائج الإيجابية الخاطئة)
- **فحوصات أمان API**:
  - تعداد طرق HTTP
  - كشف نقطة نهاية التصحيح
  - كشف قائمة الدليل
  - وجود Security.txt
  - تحليل رأس الاستجابة (HSTS، X-Frame-Options، إلخ.)
  - كشف رسالة الخطأ

### الاختبار الأمني النشط (--active-checks)
- **فحوصات IDOR/BOLA لأمان API** (نهج ثلاثي المستويات):
  - اختبار الوصول غير المصادق
  - مقارنة الاستجابة عبر بصمات النص الأساسي بالإضافة إلى لقطات رأس مستقرة
  - تعداد المعرف (±2 نطاق مشي)
  - تجاوز التفويض عبر المستخدمين (هوية مزدوجة)
  - استقصاء رد اتصال SSRF أعمى عبر معلمات استعلام من نمط رد الاتصال (`APIHUNTER_OAST_BASE`، يدعم `--dry-run`)
  - بصمة البوابة واستقصاء التجاوز (`api_security/gateway-*`)
- **ثغرات التخصيص الجماعي**:
  - حقن الحقل الحساس المنعكس
  - كشف تغيير الحالة المستمر
  - تحقق خط الأساس ← الطفرة ← التأكيد
  - تصعيد الامتيازات عبر حقن الحقل
- **أمان OAuth/OIDC**:
  - تجاوز التحقق من URI إعادة التوجيه
  - التعامل مع معلمة الحالة
  - كشف دعم PKCE
  - تشديد تكوين البيانات الوصفية
  - كشف التدفق الضمني ومنح كلمة المرور
- **تحديد المعدل**:
  - استقصاء الطلبات الاندفاعية
  - كشف تحديد المعدل المفقود
  - التحقق من صحة رأس Retry-After
  - اختبارات تجاوز انتحال رأس IP
- **أمان WebSocket**:
  - قبول الترقية على المسارات الشائعة
  - اختبار التحقق من المصدر
  - فحوصات المصادقة المفقودة
- **محرك قالب CVE**:
  - كتالوج قوائم TOML
  - دعم استيراد قوالب YAML الخاصة بـ Nuclei
  - مطابقة تفاضلية للخط الأساسي مقابل التجاوز
  - إزالة التكرار على مستوى المضيف+القالب
  - بوابات الجودة للمُحمِّل لتخطي قوالب الطلبات غير الصالحة/غير الآمنة (على سبيل المثال عناصر نائبة للطلبات غير محلولة)
  - مطابقة سياق مراعية للقطاع لتقليل التشغيل المفرط على السلاسل الفرعية للمسار الواسع
  - كتالوج محلي حالي: 168 قالبًا (يتضمن فحوصات مشددة منسقة مثل CVE-2022-22947، CVE-2021-29442، CVE-2021-29441، CVE-2020-13945، CVE-2021-45232، CVE-2022-24288)

### الاكتشاف والتعداد
- **اكتشاف نقاط النهاية**:
  - تحليل robots.txt
  - تحليل sitemap.xml
  - استيراد مواصفات OpenAPI/Swagger
  - استيراد ملف HAR (تكامل Excalibur)
  - استيراد مجموعة Postman/Insomnia (`--collection`)
  - استخراج نقاط نهاية JavaScript
  - التصفية حسب نفس المضيف
- **الترشيح المسبق لصلاحية عناوين URL**:
  - فحص مسبق سريع لتخطي نقاط النهاية الميتة
  - مهلة قابلة للتكوين
  - تجاوز اختياري مع --no-filter

### الأداء والموثوقية
- **التوافقية التكيفية (AIMD)**:
  - تعديل المعدل التلقائي بناءً على الأخطاء
  - زيادة إضافية (كل 5 ثوانٍ)
  - انخفاض مضاعف على 429/503/مهلات
- **التخفي والتهرب من WAF**:
  - تدوير وكيل المستخدم من مجموعة وقت التشغيل (assets/user_agents.txt مع أكثر من 100 وكيل مستخدم حقيقي)
  - وكلاء مستخدم احتياطيون مدمجون إذا كان الملف غير متوفر
  - تشويش تأخير عشوائي لتجنب أنماط الكشف
  - فرض توقيت لكل مضيف (ليس عالميًا)
  - منطق إعادة المحاولة مع التراجع الأسي
  - حقن رأس مخصص (X-Forwarded-For، Referer، إلخ.)
  - توقيت تكيفي بناءً على استجابات 429/503
  - وضع الأدب للاختبار التعاوني
  - لا توجد بصمات ماسح ضوئي في وكيل المستخدم أو الرؤوس افتراضيًا
- **إدارة الموارد**:
  - توازي محدود بإشارة (semaphore-bounded parallelism)
  - تجمعات عميل HTTP لكل مضيف
  - إعادة استخدام الاتصال وتجميعه
  - مهلات قابلة للتكوين وإعادة محاولة
- **معالجة الأخطاء**:
  - استرداد الذعر عبر JoinSet
  - الإبلاغ عن الأخطاء الملتقطة بشكل منفصل
  - تدهور أنيق عند فشل الماسح

### الإخراج وإعداد التقارير
- **تنسيقات إخراج متعددة**:
  - JSON جميل (قابل للقراءة البشرية)
  - NDJSON (متعدد التدفقات، قابل للتحليل)
  - SARIF 2.1.0 (فحص كود GitHub/GitLab)
- **فرق خط الأساس**:
  - إنشاء لقطات خط الأساس
  - مقارنة الفحوصات للإبلاغ عن النتائج الجديدة فقط
  - مثالي لاختبار الانحدار
- **الحفظ التلقائي للتقارير** (ممكن افتراضيًا، قم بتعطيله بـ `--no-auto-report`):
  - يُحفظ إلى ~/Documents/ApiHunterReports/<timestamp>/
  - findings.json (نتائج منظمة)
  - summary.md (تقرير Markdown)
  - scan.log (سجل التنفيذ)
- **التدفق في الوقت الفعلي**:
  - تدفق النتائج عند اكتشافها
  - تنسيق NDJSON للتحليل المباشر
  - تتبع التقدم
- **التصفية حسب الشدة**:
  - التصفية حسب الحد الأدنى للشدة (معلومات/منخفض/متوسط/مرتفع/حرج)
  - عتبة الفشل لـ CI/CD
  - قناع رمز الخروج (0x01 نتائج، 0x02 أخطاء)

### التكامل وقابلية التوسع
- **معمارية ماسح قابلة للتوصيل**:
  - تنفيذ Scanner trait لإضافة وحدات
  - تصميم غير متزامن أولاً
  - تنفيذ ماسح مستقل
  - عزل الذعر لكل ماسح
- **قابلية التوسع القائمة على TOML**:
  - كتالوج قوالب CVE في assets/cve_templates/*.toml
  - لا حاجة لتغيير الكود لإضافة فحوصات جديدة
  - كشف الثغرات المدفوع بالقوالب
  - تنسيق قالب قابل للمشاركة من قبل المجتمع
- **استيراد قالب Nuclei**:
  - أداة template-tool الثنائية لتحويل YAML → TOML
  - ترجمة المطابق التلقائي (الحالة، الكلمة، التعبير المنتظم، dsl)
  - استخراج سلسلة الطلب المسبق الآمن
  - يحافظ على منطق الكشف من القوالب العلوية
- **نموذج تمديد مزدوج**:
  - **قائم على الكود**: كتابة ماسحات Rust تنفذ Scanner trait للمنطق المعقد
  - **قائم على القالب**: كتابة قوالب TOML للفحوصات القائمة على التوقيع (CVEs، سوء التكوين)
  - أفضل ما في العالمين: أداء + مرونة
- **أدوات تكميلية**:
  - إضافة متصفح Excalibur (التقاط HAR)
  - BurpAPIsecuritysuite (الاختبار اليدوي)
  - سير العمل: التقاط ← أتمتة ← اختبار عميق

### التكوين والتحكم
- **إدخال مرن**:
  - قوائم عنوان URL قائمة على الملف
  - stdin (أنبوب من أدوات أخرى)
  - استيراد ملف HAR
  - استيراد مجموعة Postman/Insomnia
  - استيراد مواصفات OpenAPI
- **تحكم دقيق في الماسح**:
  - تمكين/تعطيل الماسحات الفردية
  - وضع نشط مقابل سلبي
  - وضع التشغيل الجاف للفحوصات النشطة
  - تكوين لكل ماسح
- **تكوين الشبكة**:
  - دعم بروكسي HTTP/HTTPS
  - التحكم في التحقق من صحة شهادة TLS
  - رؤوس وملفات تعريف ارتباط مخصصة
  - مهلات قابلة للتكوين وإعادة محاولة
- **ملفات تعريف الفحص**:
  - quickscan.sh (سريع، منخفض التأثير)
  - deepscan.sh (شامل، فحوصات نشطة)
  - inaccessiblescan.sh (إعادة فحص الأهداف التي كانت غير قابلة للوصول سابقًا بإعدادات أبطأ)
  - baselinescan.sh (إنشاء خط أساس)
  - diffscan.sh (مقارنة مع خط الأساس)
  - authscan.sh (فحص مصادق)
  - sarifscan.sh (تكامل CI/CD)
  - scan-and-report.sh (تشغيل الفحص + طباعة أحدث مسار تقرير)
  - split-by-host.sh (تقسيم الأهداف حسب المضيف وتوزيع الفحوصات اختياريًا)

## مقارنة مع الأدوات الأخرى| الميزة | ApiHunter | Nuclei | ZAP | Burp Suite | ffuf |
|---------|-----------|--------|-----|------------|------|
| **اللغة** | Rust | Go | Java | Java | Go |
| **الأداء** | ⚡⚡⚡ متزامن، تكيفي مع التزامن | ⚡⚡ سريع متوازي | ⚡ معتدل | ⚡ معتدل | ⚡⚡⚡ سريع جدًا |
| **تصميم موجه لواجهات API** | ✅ مبني لواجهات API | ❌ عام للويب | ⚠️ مختلط | ⚠️ مختلط | ❌ تركيز على الفازينغ |
| **تصفية الإيجابيات الكاذبة** | ✅ كشف SPA، التحقق من الجسم، فحوصات المُحيل | ⚠️ يعتمد على القوالب | ⚠️ إيجابيات كاذبة كثيرة | ✅ جيد | غير متاح |
| **تحليل CORS/CSP** | ✅ تحليل عميق للسياسات | ⚠️ قوالب أساسية | ✅ جيد | ✅ جيد | ❌ |
| **فحص GraphQL Introspection** | ✅ كشف التعرض للـ schema + فحص الحقول الحساسة | ⚠️ كشف أساسي | ⚠️ محدود | ✅ عبر الإضافات | ❌ |
| **OpenAPI/Swagger** | ✅ تحليل مخططات الأمان | ❌ | ✅ استيراد فقط | ✅ استيراد + فحص | ❌ |
| **تحليل JWT** | ✅ alg=none، أسرار ضعيفة، انتهاء الصلاحية | ⚠️ عبر القوالب | ⚠️ محدود | ✅ عبر الإضافات | ❌ |
| **كشف IDOR/BOLA** | ✅ ثلاثي المستويات (غير مصرح/نطاق/عبر المستخدمين) | ⚠️ قوالب يدوية | ⚠️ محدود | ✅ اختبار يدوي | ❌ |
| **كشف الأسرار** | ✅ واعي بالسياق (الواجهة الأمامية مقابل الخلفية) | ⚠️ يعتمد على التعبيرات العادية | ⚠️ أساسي | ⚠️ أساسي | ❌ |
| **الفحوصات النشطة** | ✅ اختياري (IDOR، تعيين جماعي، OAuth/OIDC، WebSocket، تحديد المعدل، قوالب CVE) | ✅ يعتمد على القوالب | ✅ فحص نشط | ✅ فحص نشط | ✅ فازينغ |
| **تجنب WAF** | ✅ تدوير User-Agent، تأخيرات، إعادة محاولات، توقيت تكيفي | ⚠️ أساسي | ⚠️ محدود | ✅ جيد | ⚠️ أساسي |
| **التكامل مع CI/CD** | ✅ NDJSON، SARIF، رموز خروج | ✅ JSON، SARIF | ⚠️ تقارير XML | ⚠️ XML/JSON | ✅ JSON |
| **مقارنة الأساس** | ✅ مدمجة | ❌ أدوات خارجية | ❌ | ❌ | ❌ |
| **تدفقات المصادقة** | ✅ تسجيل دخول قبل الفحص قائم على JSON | ⚠️ حقن رأس | ✅ إدارة الجلسات | ✅ إدارة الجلسات | ⚠️ حقن رأس |
| **الإخراج المتدفق** | ✅ NDJSON في الوقت الحقيقي | ❌ دفعة فقط | ❌ | ❌ | ✅ |
| **استخدام الموارد** | 🟢 منخفض (Rust) | 🟢 منخفض (Go) | 🟡 مرتفع (Java) | 🟡 مرتفع (Java) | 🟢 منخفض (Go) |
| **منحنى التعلم** | 🟢 واجهة CLI بسيطة | 🟢 صيغة القوالب | 🟡 تعقيد GUI | 🔴 حاد | 🟢 بسيط |
| **قابلية التوسع** | ✅ نظام الصفات (Trait) في Rust | ✅ قوالب YAML | ✅ إضافات | ✅ إضافات | ⚠️ محدود |
| **الترخيص** | MIT (مجاني) | MIT (مجاني) | Apache 2.0 (مجاني) | تجاري | MIT (مجاني) |
| **الأفضل لـ** | أمان واجهات API في CI/CD، اختبار الانحدار، تحليل CORS/GraphQL/JWT | الفحص العام للثغرات، كشف CVEs | اختبار الاختراق الكامل لتطبيقات الويب | اختبار الاختراق اليدوي، سير العمل المعقد | فازينغ الدلائل/المعلمات |

### الفروقات الرئيسية

**ApiHunter:** تصميم موجه لواجهات API، كشف SPA، مقارنة الأساس، IDOR/BOLA ثلاثي المستويات، أسرار واعية بالسياق، التزامن AIMD، **التخفي/تجنب WAF (تدوير UA، التذبذب، التوقيت التكيفي)**، **قابلية توسع مزدوجة (قوالب TOML + وحدات Rust)**  
**Nuclei:** تغطية أوسع لـ CVE، قوالب YAML فقط، تجنب أساسي  
**ZAP/Burp:** اختبار يدوي، سير عمل وكيل، إضافات قائمة على GUI، تخفي محدود  
**ffuf:** فازينغ خالص، اكتشاف المحتوى، قابلية توسع محدودة، تجنب أساسي

## بداية سريعة```bash
cargo build --release

# Scan URLs from a file (newline-delimited)
./target/release/apihunter --urls ./targets/cve-regression-real-public.txt --format ndjson --output ./results.ndjson

# Or scan URLs from stdin
cat ./targets/cve-regression-real-public.txt | ./target/release/apihunter --stdin --min-severity medium

يدعم إدخال الفحص لسطح المكتب ما يلي:
- إدخال أهداف متعددة يدويًا (عنوان URL واحد لكل سطر أو مفصول بفاصلة)
- استيراد CSV عبر `Load CSV` (حد أقصى 307,200 بايت / 300 كيلوبايت)
- إعدادات فحص موجهة: `Quick Passive` و `Deep Active`
- حد صارم: حتى 3,000 هدف لكل تشغيل (إزالة التكرار + التحقق من صحة عناوين URL المطلقة `http/https`)
- عناصر تحكم النطاق: تشغيل/إيقاف الاكتشاف، تصفية إمكانية الوصول + المهلة الزمنية، الحد الأقصى لنقاط النهاية لكل موقع
- عناصر تحكم إصدار API: تبديل اختياري للتحقق العميق من فروق الاستجابة
- عناصر تحكم متقدمة: وكيل، رؤوس، ملفات تعريف الارتباط، مصادقة bearer/basic، تبديل شهادة TLS غير الصالحة
- إدخال ارتباط رد الاتصال SSRF الأعمى (`OAST callback base`) للفحوصات النشطة
- عناصر تحكم الأداء: عملاء لكل مضيف، التزامن التكيفي، تجاوز WAF مع مجموعة وكيل مستخدم مخصصة
- تغطية تبديل الفحص الكامل بما في ذلك `API Versioning` و `gRPC/Protobuf`
- أقسام فحص قابلة للطي مع أسهم محاذاة لليمين؛ `Safety and Scan Behavior` و `Runtime Limits` و `Scanner toggles` مطوية افتراضيًا
- بطاقات تقدم التشغيل المتوازي مع لقطات إكمال/اكتشافات لكل هدف
- لوحة تحليلات النتائج: خريطة حرارية للشدة، بطاقة أسوأ هدف، كفاءة الفحص، تغطية الماسح الضوئي، المسارات الأكثر ضعفًا، تفصيل شدة التحقق
- استمرارية الجلسة: استعادة تلقائية لنتائج الفحص الأخير عند التشغيل التالي
- لوحة وضع التخصيب: تحميل نتائج NDJSON، تشغيل تخصيب معلومات التهديد، ترقية المضيفين ذوي الدرجات العالية مباشرة إلى فحص كامل مع إعداد Deep Active
- تجربة التصدير: تسميات الحجم + `Save All Reports` + أسماء ملفات بختم زمني لكل تشغيل؛ تشمل الصادرات حزم JSON لكل هدف، NDJSON، SARIF، مجموعة Insomnia، وبيانات مشغل Insomnia

انظر [HOWTO.md](https://github.com/teycir/apihunter/blob/HEAD/HOWTO.md) للاستخدام المفصل، و [docs/lab-setup.md](https://github.com/teycir/apihunter/blob/HEAD/docs/lab-setup.md) لمختبرات التحقق من صحة CVE المستندة إلى Vulhub، و [docs/](https://github.com/teycir/apihunter/blob/HEAD/docs/) للتفاصيل الداخلية.

إذا كنت ترغب في الحصول على إصدار ثنائي لسطح المكتب:```bash
cd apps/desktop
npm run tauri build
./src-tauri/target/release/apihunter-desktop

ملاحظة: بدء تشغيل سطح المكتب للمطور يستخدم الآن أصول الواجهة الأمامية المبنية مباشرة ولا يتطلب خادم `localhost:1420` منفصل.

انظر [HOWTO.md](https://github.com/teycir/apihunter/blob/HEAD/HOWTO.md) للحصول على تفاصيل الاستخدام، و [docs/lab-setup.md](https://github.com/teycir/apihunter/blob/HEAD/docs/lab-setup.md) لمختبرات التحقق من صحة CVE المستندة إلى Vulhub، و [docs/](https://github.com/teycir/apihunter/blob/HEAD/docs/) للتفاصيل الداخلية.

### مثال اكتشاف NDJSON```json
{
  "url": "https://api.example.com/graphql",
  "check": "graphql/introspection-enabled",
  "title": "GraphQL introspection is enabled",
  "severity": "MEDIUM",
  "detail": "Introspection query returned schema metadata from a public endpoint.",
  "evidence": "POST /graphql -> HTTP 200 with __schema fields in response body",
  "scanner": "graphql",
  "timestamp": "2026-03-19T14:02:11.824Z"
}

**التدفق:** CLI args → Config → Runner يقوم بتنسيق Discovery + Scanners → HTTP Client (مع Auth/WAF) → Reports

## أدوات القوالب

يدعم ApiHunter **التمديد المزدوج**: أضف فحوصات عبر **قوالب TOML** (بدون كود) أو **وحدات Rust** (تحكم كامل).

### تنسيق قالب TOML
أنشئ فحوصات مخصصة في `assets/cve_templates/*.toml`:```toml
id = "custom-api-check"
name = "Custom API Vulnerability"
severity = "high"

[[requests]]
method = "GET"
path = "/api/vulnerable"

[[requests.matchers]]
type = "status"
values = [200]

[[requests.matchers]]
type = "word"
part = "body"
words = ["sensitive_data", "exposed"]

### إضافة ماسحات Rust مخصصة
قم بتنفيذ خاصية `Scanner` للمنطق المعقد:```rust
#[async_trait]
impl Scanner for MyCustomScanner {
    async fn scan(
        &self,
        url: &str,
        client: &HttpClient,
        config: &Config,
    ) -> (Vec<Finding>, Vec<CapturedError>) {
        // Your custom scanning logic
    }
}

جميع النصوص البرمجية المغلفة باستثناء `split-by-host.sh` تدعم `--stdin` وأعلام ApiHunter اللاحقة.

## استراتيجية الاختبار

ينقسم اختبار ApiHunter حسب الهدف:

- **اختبارات الوحدة** (`tests/*_scanner.rs`، اختبارات المحلل/التكوين): منطق الماسح والحالات الحدودية.
- **اختبارات التكامل** (`tests/integration_runner.rs`، سلوك بدء التشغيل/واجهة الأوامر): التنسيق وربط وقت التشغيل.
- **اختبارات الانحدار الثابتة** (`tests/cve_templates_real_data.rs`، `tests/cve_templates_upstream_parity.rs`): إعادة تشغيل الحمولات الحقيقية والمقارنة مع القوالب المرجعية العلوية المثبتة.
- **اختبارات خادم المحاكاة** (مجموعات ماسحات متعددة): فحوصات السلوك الحتمي دون الاعتماد على أهداف الإنترنت.
- **فحوصات الهدف المباشر**: اختيارية/يدوية فقط (ليست جزءًا من `cargo test` الافتراضي).

راجع [دليل الاختبار](https://github.com/teycir/apihunter/blob/HEAD/docs/testing.md) المخصص لمصفوفة الاختبار الكاملة وخريطة التغطية.

تشغيل مجموعات مركزة:```bash
cargo test --test cors_scanner
cargo test --test graphql_scanner
cargo test --test cve_templates_runtime_ext
cargo test --test integration_runner

تشغيل بوابة تكامل البيانات الحقيقية (التركيبات + المجموعات الحية التي تم تجاهلها):```bash
# Fixture-backed real payload regression suites
cargo test --test cve_templates_real_data --test cve_templates_upstream_parity --test cve_templates_runtime_ext

# Manual live internet integration suites (ignored by default)
cargo test --test live_vulnerable_apis --test live_real_world_targets -- --ignored

### قطع الإصدار مُسبقة البناء

الإصدارات الموسومة (`v*`) تنشر ثنائيات `apihunter` مُسبقة البناء لـ:

- Linux (`x86_64-unknown-linux-gnu`, `aarch64-unknown-linux-gnu`)
- macOS (`x86_64-apple-darwin`)
- Windows (`x86_64-pc-windows-msvc`)

كل إصدار ينشر أيضًا قطع سلسلة التوريد:

- ملفات التجزئة SHA256 (`*.sha256`)
- مواد التوقيع غير ذات المفتاح من Sigstore (`*.sig`, `*.pem`, `*.sigstore.json`)
- SPDX JSON SBOM (`apihunter-release-assets-sbom.spdx.json`)
- شهادات إسناد القطع من GitHub (بيانات إثبات الأصل والشهادة SBOM)

قم بالتحميل من [GitHub Releases](https://github.com/Teycir/ApiHunter/releases).

### تثبيت سطح المكتب (Tauri + React)

مصدر تطبيق سطح المكتب موجود في `apps/desktop`.

قم ببناء وتشغيل ثنائي سطح المكتب للإنتاج:```bash
cd apps/desktop
npm install
npm run tauri build
./src-tauri/target/release/apihunter-desktop

تثبيت أيقونة مشغل لينكس قابلة للنقر:```bash
cd apps/desktop
npm run desktop:install-icon

تشغيل فحص من الملفات في الدليل الحالي:```bash
docker run --rm -v "$PWD:/work" apihunter:local \
  --urls /work/targets/cve-regression-real-public.txt \
  --format ndjson \
  --output /work/results.ndjson

**س: مقارنة الفروقات مع خط الأساس؟**```bash
./target/release/apihunter --urls targets/cve-regression-real-public.txt --format ndjson --output baseline.ndjson
./target/release/apihunter --urls targets/cve-regression-real-public.txt --baseline baseline.ndjson --format ndjson