Recon-Scan

ReconScan هو ماسح استطلاع سلبي مفتوح المصدر، بواجهة خلفية مبنية على FastAPI، وخط أنابيب عامل غير متزامن، وواجهة أمامية من صفحة واحدة. يمكنك الاطّلاع على الموقع المنشور على https://recon-scan.vercel.app/

الفكرة هي إشارة سريعة: شغّل فحصًا، واحصل على النتائج وحدةً بوحدة، واحصل على ملخص ذكاء اصطناعي يمكنك الآن تصديره كتقرير PDF احترافي.

ما هو هذا المشروع (وما ليس هو)

• إنه استطلاع سلبي. لا يقوم بالهجوم العنيف (brute force) على نقاط النهاية، ولا بالتشويش (fuzzing)، ولا بتشغيل منطق استغلال نشط.
• إنه مفيد لأخذ لقطات للوضع الأمني (posture snapshots)، والفرز (triage)، وإعداد التقارير.
• إنه ليس بديلًا عن اختبار الاختراق الكامل.

الميزات

• 13 وحدة سلبية:
  • ترويسات الأمان (Security headers)
  • SSL/TLS
  • DNS + مصادقة البريد الإلكتروني (SPF/DMARC/MX)
  • WHOIS
  • Robots/خريطة الموقع
  • تعداد النطاقات الفرعية (Subdomain enumeration)
  • بصمة التقنيات (Tech fingerprinting)
  • كشف WAF
  • فحوصات CORS
  • فحوصات أمان ملفات تعريف الارتباط (Cookies)
  • فحوصات تعرّض JS
  • فحوصات تعرّض الأدلة
  • فحوصات السمعة
• تنفيذ غير متزامن مع عامل ARQ + Redis.
• الرجوع إلى تنفيذ الخلفية داخل العملية (in-process) في حال فشل إدراج المهمة في الطابور.
• ملخص ذكاء اصطناعي اختياري عبر OpenRouter / Anthropic / OpenAI.
• توليد تقرير PDF من الفحص + ملخص الذكاء الاصطناعي.
• واجهة أمامية تُقدَّم مباشرةً عبر FastAPI (عنوان URL واحد، تطبيق واحد).

بدء التشغيل بأمر واحد (التطوير المحلي)

إذا كنت ترغب فقط في تشغيله بسرعة:

./start.sh

ما الذي يفعله هذا:

• ينشئ .env من .env.example إذا كان مفقودًا.
• ينشئ .venv إذا لزم الأمر.
• يثبّت التبعيات من requirements.txt.
• يشغّل FastAPI مع إعادة التحميل التلقائي (hot reload) على http://localhost:8000.
• يفرض USE_ARQ_QUEUE=false لتسهيل بدء التشغيل المحلي بدون Redis.

أوقف التشغيل بالضغط على Ctrl+C.

بدء التشغيل بأمر واحد (Docker)

./start-docker.sh

ما الذي يفعله هذا:

• ينشئ .env من .env.example إذا كان مفقودًا.
• يشغّل API + العامل + Redis باستخدام Docker Compose.

بدء تشغيل Docker (يدوي)

cp .env.example .env
docker compose up --build

التطوير المحلي (بدون Docker)

1. ثبّت التبعيات:

pip install -r requirements.txt

2. أنشئ ملف البيئة:

cp .env.example .env

3. شغّل API:

uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

4. شغّل العامل (worker) في طرفية أخرى (موصى به):

arq app.worker.WorkerSettings

5. افتح:

http://localhost:8000

تشغيل الاختبارات

ثبّت تبعيات الاختبار:

pip install -r requirements-dev.txt

شغّل مجموعة الاختبارات الكاملة:

pytest -q

تقارير PDF

بعد اكتمال الفحص، انقر فوق Download PDF في الواجهة.

نقطة نهاية الواجهة الخلفية:

• GET /scans/{scan_id}/report.pdf

يتضمن التقرير:

• بيانات وصفية (metadata) للهدف والفحص
• ملخص تنفيذي بالذكاء الاصطناعي (قصير + سرد كامل عند توفره)
• جدول لقطة مستويات الخطورة
• نتائج مفصّلة وحدةً بوحدة

API

• GET /health
• POST /scans
  • مثال على جسم الطلب (body):
    • { "target": "example.com" }
    • { "target": "example.com", "byoapi_key": "...", "byoapi_provider": "your_provider" }
  • ملاحظات:
    • يُرفض byoapi_key ما لم يكن ALLOW_BYO_API_KEY=true
    • الأهداف الخاصة / الحلقية (loopback) / المحجوزة محظورة
    • user_id اختياري ويُحتفظ به للتوافق
• GET /scans/{scan_id}
• GET /scans/{scan_id}/report.pdf

الإعدادات

من .env.example:

• DATABASE_URL (الافتراضي: sqlite:///./reconscan.db)
• REDIS_URL (الافتراضي: redis://localhost:6379)
• USE_ARQ_QUEUE (الافتراضي: true)
• RATE_LIMIT_PER_MINUTE (الافتراضي: 10)
• RATE_LIMIT_PER_DAY (الافتراضي: 200)
• ALLOWED_HOSTS (الافتراضي: localhost,127.0.0.1)
• CORS_ALLOWED_ORIGINS (الافتراضي: أصول التطوير المحلية)
• ALLOW_BYO_API_KEY (الافتراضي: )

المساهمة

المساهمات مرحّب بها، خاصةً في وحدات الاستطلاع السلبي، وإعداد التقارير، وتجربة المستخدم للواجهة الأمامية، وتغطية الاختبارات.

يرجى قراءة إرشادات المساهمة الكاملة قبل فتح طلب سحب (pull request):

دليل المساهمة

ملاحظات

• إذا لم يتم تكوين أي مفتاح ذكاء اصطناعي خارجي، يخزّن ReconScan ملخصًا احتياطيًا محليًا.
• تُعد SQLite محرك التخزين الافتراضي لسهولة الاستخدام المحلي.
• تم تصميم هذا المستودع ليكون خفيف الوزن وصديقًا للاستضافة الذاتية عن قصد.

الترخيص

MIT. انظر LICENSE.