SpooNMAP

المتطلبات

هذا السكربت عبارة عن غلاف (wrapper) لـ masscan و nmap. يتولى nmap اكتشاف المضيفين و(للعمليات الأصغر) اكتشاف المنافذ، والتقاط بانرات الخدمات، وسكربتات NSE. يُستخدم Masscan لاكتشاف المنافذ على نطاق واسع حيث تكون السرعة الخام مهمة. قم بتثبيت كليهما من مدير الحزم المفضل لديك أو من المصدر.

يتطلب Python 3.8+ (requires-python في pyproject.toml؛ الحد الأدنى في CI هو 3.8).

التثبيت

يمكن تشغيل SpooNMAP مباشرة من نسخة مستخرجة (checkout) — دون الحاجة إلى خطوة تثبيت، انظر "الاستخدام" أدناه — أو تثبيته كأمر مستقل باستخدام uv:

uv tool install git+https://github.com/trustedsec/spoonmap

هذا يضع ملفًا تنفيذيًا باسم spoonmap على PATH الخاص بك، بحيث يمكنك استدعاؤه باسم spoonmap من أي دليل بدلاً من استنساخ المستودع وتشغيل ./spoonmap.py. لا توجد حزمة PyPI — لم ينشر هذا المشروع أبدًا إلى pypi.org، والأمر أعلاه يثبّت مباشرة من مستودع git بدلاً من ذلك. استخدم الصيغة الكاملة git+https://... أعلاه، وليس uv tool install spoonmap المجرّد؛ فأيًا كان ما يشير إليه هذا الاسم على PyPI، الآن أو في المستقبل، فهو ليس هذا المشروع.

للتحديث إلى أحدث commit:

uv tool upgrade spoonmap

تثبيت SpooNMAP بهذه الطريقة لا يجعله ماسحًا مكتفيًا بذاته: لا يزال masscan و nmap أداتين نظاميتين منفصلتين يجب تثبيتهما بشكل مستقل (انظر "الاعتماديات" أعلاه)، تمامًا كما هو الحال عند التشغيل من نسخة مستنسخة — فـ uv tool install لا يحزم سوى كود Python الخاص بـ SpooNMAP وسكربتات NSE المضمّنة معه، وليس الملفات التنفيذية الخارجية التي يستدعيها.

الشيء الوحيد الجدير بالفهم قبل التثبيت بهذه الطريقة: أن وحدة Python الخاصة بـ spoonmap المثبَّتة تقع حيثما وضع uv بيئة الأدوات المُدارة الخاصة به — وليس في مجلد قد يخطر لك البحث فيه عن ملف إعدادات أو مخرجات فحص. وهذا بالضبط هو السيناريو الذي يتناوله قسم "أين تعيش الملفات" أدناه — اقرأ ذلك القسم لمعرفة ما يُحلّ نسبةً إلى مجلدك الحالي ولماذا؛ فالتثبيت عبر uv tool install لا يغيّر القاعدة، بل يجعلها ذات أهمية، إذ لم يعد هناك مجلد نسخة مستنسخة يمكن لمسار الإعدادات أو المخرجات أن يعود إليه بحكم العادة.

الاستخدام

مجرد تنفيذ السكربت سيطالبك بجميع الخيارات المطلوبة.

يُحلّ config.json وملفات الأهداف/الاستبعاد ومخرجات الفحص جميعًا نسبةً إلى المجلد الذي تشغّل الأمر منه — راجع "أين تعيش الملفات" أدناه إذا لم تكن مخرجاتك حيث تتوقعها، خاصةً إن كنت معتادًا على استدعاء SpooNMAP بالمسار من خارج مجلده الخاص.

إذا كنت تستخدم uv، يمكنك التشغيل دون بيئة افتراضية منفصلة:

uv run spoonmap.py

أو استدعِه مباشرةً إذا كان السكربت قابلاً للتنفيذ:

# ./spoonmap.py

________                   _____   _______  _________________
__  ___/______________________  | / /__   |/  /__    |__  __ \
_____ \___  __ \  __ \  __ \_   |/ /__  /|_/ /__  /| |_  /_/ /
____/ /__  /_/ / /_/ / /_/ /  /|  / _  /  / / _  ___ |  ____/
/____/ _  .___/\____/\____//_/ |_/  /_/  /_/  /_/  |_/_/
       /_/


Service Categories (comma-separated numbers, default: All)
	(1) Web          [80, 443, 7001, 7002, 8000, 8080, 8081, 8443, 8888, 9090, 10443]
	(2) Database     [1433, U:1434, 1521, 3306, 5432, 6379, 9200, 27017]
	(3) Remote Management  [22, 23, 3389, 5900, 5901, 6129, 1723, 5985, 5986]
	(4) Email        [25, 110, 143, 465, 587, 993, 995]
	(5) LDAP         [389, 636]
	(6) Network Infrastructure  [53, 179, U:500, U:161, U:623, U:631, U:1194, 1194]
	(7) File Transfer      [21, 111]
	(8) SMB          [445, 135, 139, U:137]
	(9) Specialized  [1090, 3300, 4786, 6970, 2375, 4243, 9100, 8530, 8531]
	(10) Containers & Debuggers  [2377, 10250, 8001, 9229, 2345, 5005, 61616, 8009, 6000]
	(11) Local LLM  [11434, 1234, 7860, 5000, 5001, 1337, 3000, 8000, 8080]
	(12) Full Port Scan  [1-65535, TCP only — no UDP]
	(c) Custom Port Scan  [enter your own comma-separated ports]

(The Full Port Scan number increments automatically with the number of categories.)

**Full Port Scan is TCP only.** It sweeps TCP 1-65535 and runs no UDP discovery at
all, so every `U:` port listed in the categories above — SNMP (U:161), IKE (U:500),
IPMI (U:623), IPP (U:631), OpenVPN (U:1194), NetBIOS (U:137), SQL Browser (U:1434) —
is skipped, along with the NSE scripts and findings that depend on them. It is
*wider* than All on TCP and *narrower* on UDP. For both, run All and Full as two
passes, or use the Custom option with the UDP ports appended
(e.g. `1-65535,U:161,U:500,U:623`).

Which categories would you like to scan (e.g. 1,3 — default: All)?

Would you like to enumerate service banners for any identified services (default: Yes)?

Would you like to run NSE security scripts on identified services (default: No)?

Target Scan
	(1) External
	(2) Internal

Is this an internal or external scan (default: External)?

How fast would you like to scan (default: 20000 packets/second)?

Please enter the full path for the file containing target hosts (default: /opt/spoonmap/ranges.txt):

Would you like to exclude any hosts? (default: No)

Run host discovery before port scanning (default: Yes)?

Tune advanced settings (nmap threads, masscan batch size, nmap work-unit threshold)? (default: No)

يمكنك أيضًا إنشاء ملف config.json (استنادًا إلى config.json.sample) لتخطي جميع المطالبات:

{
    "scan_categories": ["Web", "Database", "Remote Management"],
    "banner_scan": "True",
    "script_scan": "False",
    "host_discovery": "True",
    "target_scan": "Internal",
    "max_rate": "2000",
    "target_file": "ranges.txt",
    "output_path": "./",
    "exclusions_file": "exclusions.txt",
    "nmap_threads": 5,
    "masscan_batch_size": 5,
    "nmap_threshold": 5000000
}

لمسح جميع الفئات، اضبط "scan_categories": "All". لمسح جميع منافذ TCP البالغ عددها 65535، اضبط "scan_categories": "Full" — لاحظ أن هذا TCP فقط ولا يقوم بأي اكتشاف UDP. لقائمة منافذ مخصصة بالكامل، احذف scan_categories واستخدم "dest_ports": ["80","443","U:53"] بدلاً من ذلك. تُحدَّد منافذ UDP ببادئة U: (مثل "U:53").

عند الإجابة على المطالبات التفاعلية، تُكتب الخيارات المحددة إلى config.json قبل بدء المسح. يوثّق الملف المُنشأ كل حقل قابل للتعديل بالطريقة نفسها التي يفعلها config.json.sample، ويحمل مفتاح علامة __generated_by_prompts__. هذا يعني أنه يمكن استئناف مسح تفاعلي متوقف بالطريقة نفسها التي يُستأنف بها مسح مدفوع بالإعدادات — ما عليك سوى إعادة التشغيل مع --resume، وسيتم تخطي جميع المطالبات.

إذا اكتُشف ناتج مسح سابق في output_path، يقدّم الأداة ثلاثة خيارات: [d]elete (إزالة الناتج السابق والبدء من جديد)، أو [a]ppend (الاحتفاظ بالناتج السابق لكن إعادة تشغيل جميع المراحل)، أو [r]esume (الاحتفاظ بالناتج السابق وتخطي العمل المكتمل بالفعل، تمامًا كما يفعل علم --resume).

تغيير الخيارات عند إعادة التشغيل. اختيار [d]elete أو [a]ppend يعيد طرح كل خيار، مع تعبئة قيم config.json المحفوظة مسبقًا كإعدادات افتراضية — لذا فإن الضغط على Enter عبر المطالبات يعيد إنتاج المسح السابق، ويمكنك تغيير المنافذ أو المعدل أو الأهداف التي تهمك فقط. [r]esume يتخطى المطالبات، لأنه يواصل المسح نفسه. تنطبق إعادة المطالبة فقط على config.json أنشأته الأداة (ملف يحمل __generated_by_prompts__)؛ أما الإعدادات التي كتبتها يدويًا فتحتفظ بسلوك تخطي جميع المطالبات الصارم الموصوف أعلاه. أزل هذا المفتاح لإلغاء الاشتراك، أو احذف config.json بالكامل للبدء من الصفر.

إعادة الإجابة على المطالبات تعيد كتابة config.json، بالدمج بدلاً من الاستبدال: أي مفاتيح أضفتها إلى الملف يدويًا يتم الحفاظ عليها.

مسح هدف بدون ملف

لمسح عنوان واحد (أو قائمة قصيرة) دون تحرير ملف أهداف، استخدم --target:

./spoonmap.py --target 10.0.0.5
./spoonmap.py --target 10.0.0.0/24
./spoonmap.py --target 10.0.0.5,10.0.1.0/24,10.0.2.1-10.0.2.9

تقبل القيمة أي شيء يقبله سطر ملف الهدف — عنوان IP مجرد، أو CIDR، أو نطاق A-B، أو address netmask — مفصولة بفواصل. يتم التحقق منها قبل بدء الفحص: عنوان مشوّه أو عنوان IPv6 يُجهض العملية بخروج غير صفري مع تسمية الإدخال المخالف، بدلاً من التشغيل بسلاسة على مجموعة أهداف فارغة.