ReconSwarm

ReconSwarm هو إطار عمل نمطي لأتمتة الاستطلاع مصمم للاختبارات الأمنية الموزعة. يقوم بتوفير البنية التحتية السحابية، وتنفيذ خطوط استطلاع متوازية، وجمع النتائج بأقل عبء إعدادات.

يعد ReconSwarm مناسبًا لصيادي برامج مكافآت الثغرات، ومختبري الاختراق، ومهندسي DevSecOps، والباحثين الأمنيين الذين يحتاجون إلى سير عمل استطلاع قابلة للتوسع وآلية دون إدارة يدوية للبنية التحتية.

الميزات

• تقسيم الأهداف للتنفيذ المتوازي — يتم تقسيم قائمة الأهداف المجمّعة النهائية بين العمال لتنفيذ مهام الاستطلاع بشكل متوازٍ
• أنواع أهداف متعددة — تتكون قائمة الأهداف من عدة أنواع من العناصر: نطاقات من استجابة crt.sh، قائمة خارجية (روابط HTTP/HTTPS)، قائمة بسيطة (مصفوفات YAML مضمّنة)، ومخرجات أوامر الصدفة، وهي مرنة جدًا للاستخدام مع أي أدوات (مثل cook وshodan وgau وkatana وغيرها)
• بنية مستقلة عن مزود السحابة — تسمح بالتكامل السهل مع عدة مزودي خدمات سحابية (تدعم حاليًا AWS وGCP وYandex Cloud وDigital Ocean)
• مراحل خط أنابيب مرنة — نظام مراحل قابل للتوسع يدعم حاليًا عمليات exec (تنفيذ الأوامر) وsync (مزامنة الملفات والدلائل)
• سياق القوالب في الخطوات — طريقة مرنة لتمرير البيانات الوصفية من سياق التنفيذ إلى الخطوات

ميزات يجب إنجازها

• واجهة ويب - واجهة مستخدم بسيطة وسهلة الاستخدام للتفاعل السريع
• سجلات لحظية من المراحل - التقاط stdout/stderr وإرسالها إلى العميل عبر grpc streaming
• صدفة عن بُعد للعمال - فتح اتصال ssh من العميل إلى العمال عبر خادم rs
• مرحلة النتائج - مرحلة لمعالجة البيانات المستلمة من المرحلة السابقة (مثل نتيجة nuclei بصيغة json)، وتخزينها في etcd وإنشاء الإشعارات

البنية المعمارية

يتبع ReconSwarm بنية معمارية نمطية مع فصل واضح للمسؤوليات بين توفير موارد السحابة، والتحكم في الأنظمة البعيدة، وتنفيذ خط الأنابيب، وإدارة الإعدادات.

تجريد مزود السحابة

يستخدم ReconSwarm نمط الاتحاد المُتمايز لمزوّدي الموارد السحابية. يحدد حقل provisioner.type أي إعدادات المزود تكون نشطة:

provisioner:
  type: yandex_cloud  # Discriminator field
  yandex_cloud:       # Active when type: yandex_cloud
    iam_token: "${YC_TOKEN}"
    # key_path: "./sa_auth_key.json"
    folder_id: "${YC_FOLDER_ID}"
    # ... provider-specific settings

يمكن دمج مزودي سحابة إضافيين من خلال تنفيذ واجهة Provisioner وإضافة نوع جديد إلى المصنع (factory).

نظام مراحل خط الأنابيب

المراحل مكونات قابلة للتوسع تنفذ عمليات على الأجهزة الافتراضية للعمال:

• exec — تنفيذ أوامر الصدفة مع دعم القوالب
• sync — نسخ الملفات أو الدلائل من الأجهزة الافتراضية البعيدة إلى الجهاز المحلي عبر SFTP (يكتشف تلقائيًا ما إذا كان الملف أو الدليل)

جميع حقول المراحل تدعم عرض القوالب. يمكن إضافة أنواع مراحل جديدة لتوسيع الوظائف.

خادم عديم الحالة وتحمل الأخطاء

خادم ReconSwarm عديم الحالة تمامًا — كل الحالة محفوظة في etcd:

• حالة خط الأنابيب — الحالة والتقدم والأخطاء لكل خط أنابيب
• حالة العامل — معلومات الجهاز الافتراضي والمهمة الحالية والحالة
• مفاتيح SSH — أزواج مفاتيح مولّدة للوصول إلى الأجهزة الافتراضية

تتيح هذه البنية:

إعداد التوافر العالي:

                    ┌─────────────┐
                    │   Client    │
                    └──────┬──────┘
                           │
                    ┌──────▼──────┐
                    │Load Balancer│
                    └──────┬──────┘
              ┌────────────┼────────────┐
              │            │            │
       ┌──────▼──────┐ ┌───▼───┐ ┌──────▼──────┐
       │  Server 1   │ │Server2│ │  Server 3   │
       └──────┬──────┘ └───┬───┘ └──────┬──────┘
              │            │            │
              └────────────┼────────────┘
                           │
                    ┌──────▼──────┐
                    │ etcd cluster│
                    └─────────────┘

تتشارك جميع الخوادم نفس مجموعة etcd ويمكنها التعامل مع أي طلب. إذا تعطل خادم أثناء تنفيذ خط الأنابيب، يمكن لخادم آخر مواصلة التنفيذ بعد قراءة الحالة من etcd.

ملاحظة: التنفيذ الحالي يشغّل خطوط الأنابيب في الذاكرة بعد التحميل من etcd. التعافي الكامل من الأعطال مع استئناف خط الأنابيب مخطط له في الإصدارات المستقبلية.

التثبيت

git clone <repository>
cd reconswarm
go mod download
task build

الإعدادات

يفصل ReconSwarm بين إعدادات الخادم و إعدادات خط الأنابيب:

إعدادات الخادم

يتم تخزين إعدادات الخادم في reconswarm.yaml (يمكن ضبطها عبر متغير البيئة CONFIG_PATH). جميع القيم النصية تدعم توسيع متغيرات البيئة باستخدام صيغة ${VAR} أو $VAR.

# Server settings
server:
  port: 50051

# Etcd connection for state management
etcd:
  endpoints:
    - "localhost:2379"
  dial_timeout: 5  # seconds
  username: ""     # optional, supports ${ETCD_USER}
  password: ""     # optional, supports ${ETCD_PASSWORD}

# Cloud provisioner (discriminated union)
provisioner:
  type: yandex_cloud  # Provider selector

  # Yandex Cloud configuration (active when type: yandex_cloud)
  yandex_cloud:
    iam_token: "${YC_TOKEN}"
    # key_path: "./sa_auth_key.json"
    folder_id: "${YC_FOLDER_ID}"
    default_zone: "ru-central1-b"
    default_image: "fd8b1cmhmncn7lt4tqn4"
    default_username: "root"
    default_cores: 2
    default_memory: 2      # GB
    default_disk_size: 20  # GB

# Worker pool settings
workers:
  max_workers: 5
  setup_commands:
    - "apt update"
    - "apt install -y docker.io"

إعدادات خط الأنابيب

يتم تخزين إعدادات خط الأنابيب في ملف YAML منفصل ويُمرَّر عبر الخيار -f. كلا الصيغتين المغلّفة وغير المغلّفة مدعومتان:

الصيغة المغلّفة (موصى بها):

# pipeline.yaml
pipeline:
  targets:
    - value: "example.com"
      type: crtsh
    - value: ["sub1.example.com", "sub2.example.com"]
      type: list
  stages:
    - name: "Run scanner"
      type: exec
      steps:
        - "nmap -sC -sV -iL {{.Targets.filepath}} -oN /opt/recon/scan.txt"
    - name: "Collect results"
      type: sync
      src: "/opt/recon/scan.txt"
      dest: "./results/{{.Worker.Name}}.txt"

الصيغة غير المغلّفة (مدعومة أيضًا):

# pipeline.yaml
targets:
  - value: "example.com"
    type: crtsh
stages:
  - name: "Run scanner"
    type: exec
    steps:
      - "nmap -iL {{.Targets.filepath}} -oN /opt/recon/scan.txt"

متغيرات البيئة

تدعم قيم الإعدادات استبدال متغيرات البيئة بصيغتين:

• ${VAR} — اسم المتغير الكامل بين أقواس
• $VAR — اسم المتغير البسيط

إذا لم يتم تعيين متغير بيئة، سيُستخدم النص الحرفي (بما في ذلك ${VAR} أو $VAR).

إعداد Yandex Cloud

للتكامل مع Yandex Cloud، استخدم سكربت الإعداد المرفق:

1. تثبيت Yandex Cloud CLI (إذا لم يكن مثبتًا بالفعل):

   root@kitploit:~

   # Follow official Yandex Cloud documentation for CLI installation
   

2. إعداد Yandex Cloud CLI:

   root@kitploit:~

   yc config profile create <profile-name>
   yc config set cloud-id <your-cloud-id>
   yc config set folder-id <your-folder-id>
   

3. تصدير بيانات الاعتماد:

   root@kitploit:~

   source ./secrets-setup.sh
   

   يقوم هذا السكربت بتصدير:

   • YC_TOKEN — رمز IAM للمصادقة
   • YC_FOLDER_ID — معرف المجلد لإدارة الموارد
   • YC_CLOUD_ID — معرف السحابة (إذا لزم الأمر)

4. المرجع في الإعدادات:

   root@kitploit:~

   provisioner:
     type: yandex_cloud
     yandex_cloud:
       iam_token: "${YC_TOKEN}"
       # key_path: "./sa_auth_key.json"
       folder_id: "${YC_FOLDER_ID}"
   

يقوم سكربت secrets-setup.sh تلقائيًا بتوليد رمز IAM جديد في كل مرة يتم تشغيله، مما يضمن مصادقة آمنة دون ترميز بيانات الاعتماد في الكود.

إعداد Google Cloud Platform

1. إنشاء حساب خدمة:

   • انتقل إلى GCP Console > IAM & Admin > Service Accounts
   • أنشئ حساب خدمة بدور "Compute Admin"
   • أنشئ مفتاح JSON وقم بتنزيله

2. إعداد البيئة:

   root@kitploit:~

   export GCP_PROJECT_ID="your-project-id"
   export GCP_CREDENTIALS_PATH="/path/to/key.json"
   

3. المرجع في الإعدادات:

   root@kitploit:~

   provisioner:
     type: gcp
     gcp:
       project_id: "${GCP_PROJECT_ID}"
       credentials_path: "${GCP_CREDENTIALS_PATH}"
       default_zone: "us-central1-a"
   

إعداد AWS

1. إنشاء مستخدم IAM:

   • انتقل إلى AWS Console > IAM > Users
   • أنشئ مستخدمًا بصلاحيات "AmazonEC2FullAccess"
   • أنشئ Access Key ID و Secret Access Key

2. إعداد البيئة:

   root@kitploit:~

   export AWS_ACCESS_KEY_ID="your-access-key"
   export AWS_SECRET_ACCESS_KEY="your-secret-key"
   

3. المرجع في الإعدادات:

   root@kitploit:~

   provisioner:
     type: aws
     aws:
       region: "us-east-1"
       access_key_id: "${AWS_ACCESS_KEY_ID}"
       secret_access_key: "${AWS_SECRET_ACCESS_KEY}"
       default_zone: "us-east-1a"
   

إعداد DigitalOcean

1. توليد رمز وصول:

   • انتقل إلى DigitalOcean Control Panel > API
   • أنشئ Personal Access Token بنطاق "Write"

2. إعداد البيئة:

   root@kitploit:~

   export DO_TOKEN="your-token"
   

3. المرجع في الإعدادات:

   root@kitploit:~

   provisioner:
     type: digitalocean
     digitalocean:
       token: "${DO_TOKEN}"
       default_region: "nyc1"
   

أنواع الأهداف

تعداد crt.sh:

targets:
  - value: "example.com"
    type: crtsh

قائمة يدوية:

targets:
  - value: ["sub1.example.com", "sub2.example.com"]
    type: list

إعدادات المراحل

جميع حقول إعدادات المراحل تدعم صيغة قوالب Go لتوليد القيم ديناميكيًا. يتم عرض متغيرات القوالب وقت التنفيذ مع بيانات سياق مقدمة تلقائيًا.

سياق القالب

البيانات التالية متاحة في جميع قوالب المراحل:

مرحلة exec — تنفذ أوامر الصدفة مع دعم القوالب:

stages:
  - name: "Run tool"
    type: exec
    steps:
      - "docker run --rm -v /opt/recon:/data scanner:latest {{.Targets.filepath}}"
      - "cat /opt/recon/results.json"

جميع الأوامر في مصفوفة steps تتم معالجتها عبر القوالب قبل التنفيذ.

مرحلة sync — تنسخ الملفات أو الدلائل من البعيد إلى المحلي باستخدام SFTP. تكتشف تلقائيًا ما إذا كان المسار ملفًا أو دليلًا:

stages:
  - name: "Collect results"
    type: sync
    src: "/opt/recon/results.json"
    dest: "./results/{{.Worker.Name}}.json"
  
  # Sync entire directory recursively
  - name: "Collect all results"
    type: sync
    src: "/opt/recon"
    dest: "./results/{{.Worker.Name}}"

يدعم كل من src (المسار البعيد) و dest (المسار المحلي) عرض القوالب لمسارات ملفات ديناميكية. تكتشف مرحلة sync تلقائيًا ما إذا كان مسار المصدر ملفًا أو دليلًا وتتعامل معه وفقًا لذلك.

الاستخدام

وضع الخادم

شغّل خادم gRPC لقبول إرسالات خطوط الأنابيب:

reconswarm server

يقرأ الخادم الإعدادات من reconswarm.yaml ويستمع على المنفذ المكوّن (الافتراضي: 50051).

إرسال خط أنابيب عبر gRPC

أرسل خط أنابيب إلى خادم قيد التشغيل:

reconswarm run -f examples/pipelines/nuclei.yaml

الخيارات:

• -f, --pipeline — مسار ملف YAML الخاص بخط الأنابيب (مطلوب)
• -s, --server — عنوان الخادم (الافتراضي: localhost:50051)

التحقق من حالة خط الأنابيب

reconswarm status <pipeline-id>

تنفيذ خط الأنابيب يدويًا

نفّذ خط أنابيب مباشرة دون خادم gRPC (مفيد للاختبار):

reconswarm manual -f examples/pipelines/nuclei.yaml

يقوم هذا الأمر بـ:

1. قراءة إعدادات الخادم من reconswarm.yaml
2. تجهيز الأهداف (تعداد النطاقات الفرعية عبر crt.sh إذا لزم الأمر)
3. إنشاء أجهزة افتراضية للعمال بناءً على إعداد workers.max_workers
4. توزيع الأهداف على العمال
5. تنفيذ أوامر الإعداد على كل جهاز افتراضي
6. تشغيل مراحل خط الأنابيب بالتسلسل
7. جمع النتائج عبر مراحل sync
8. تحرير جميع البنية التحتية تلقائيًا بعد الاكتمال

يضمن التحرير التلقائي للبنية التحتية استقلالية كاملة — يتم توفير جميع الموارد السحابية واستخدامها وتدميرها دون تدخل يدوي، مما يتيح سير عمل استطلاع مؤتمت بالكامل.

أمثلة على الإعدادات

للحصول على أمثلة كاملة لخطوط الأنابيب، راجع دليل examples/pipelines.

تعداد النطاقات الفرعية الأساسي والفحص:

# pipeline.yaml
pipeline:
  targets:
    - value: "example.com"
      type: crtsh
  stages:
    - name: "Scan targets"
      type: exec
      steps:
        - "nmap -sC -sV -iL {{.Targets.filepath}} -oN /opt/recon/nmap-{{.Worker.Name}}.txt"
    - name: "Collect results"
      type: sync
      src: "/opt/recon/nmap-{{.Worker.Name}}.txt"
      dest: "./results/nmap-{{.Worker.Name}}.txt"

شغّل باستخدام:

reconswarm manual -f pipeline.yaml
# or submit to server:
reconswarm run -f pipeline.yaml

أهداف متعددة مع فحص قائم على Docker:

pipeline:
  targets:
    - value: "example.com"
      type: crtsh
    - value: ["api.example.com", "www.example.com"]
      type: list
  stages:
    - name: "Run nuclei scan"
      type: exec
      steps:
        - "docker run --rm -v /opt/recon:/data projectdiscovery/nuclei:latest -l {{.Targets.filepath}} -json -o /opt/recon/nuclei-{{.Worker.Name}}.json"
    - name: "Copy nuclei results"
      type: sync
      src: "/opt/recon/nuclei-{{.Worker.Name}}.json"
      dest: "./results/nuclei-{{.Worker.Name}}.json"

أدوات مخصصة مع مراحل متعددة:

إعداد الخادم (reconswarm.yaml):

workers:
  max_workers: 5
  setup_commands:
    - "apt update"
    - "apt install -y git golang"
    - "git clone https://github.com/projectdiscovery/subfinder.git"
    - "cd subfinder && go build"

إعداد خط الأنابيب (pipeline.yaml):

pipeline:
  targets:
    - value: "example.com"
      type: crtsh
  stages:
    - name: "Additional enumeration"
      type: exec
      steps:
        - "cd subfinder && ./subfinder -dL {{.Targets.filepath}} -o /opt/recon/subfinder-{{.Worker.Name}}.txt"
    - name: "Merge targets"
      type: exec
      steps:
        - "cat {{.Targets.filepath}} /opt/recon/subfinder-{{.Worker.Name}}.txt | sort -u > /opt/recon/all-targets-{{.Worker.Name}}.txt"
    - name: "Scan merged targets"
      type: exec
      steps:
        - "nmap -sC -sV -iL /opt/recon/all-targets-{{.Worker.Name}}.txt -oN /opt/recon/scan-{{.Worker.Name}}.txt"
    - name: "Collect all results"
      type: sync
      src: "/opt/recon"
      dest: "./results/{{.Worker.Name}}"

ملاحظة: تكتشف مرحلة sync تلقائيًا أن /opt/recon دليل وتنسخ جميع الملفات والدلائل الفرعية بشكل متكرر إلى الوجهة المحلية.

أوامر أخرى

تعداد النطاقات الفرعية:

reconswarm crtsh-dump example.com

يجلب ويصفّي النطاقات الفرعية القابلة للحل من crt.sh لنطاق معين.

أمر التصحيح (لاختبار توفير الأجهزة الافتراضية):

reconswarm debug

التطوير

قم بالبناء والاختبار باستخدام Task:

task build      # Build binary
task test       # Run tests
task lint       # Run linter
task vet        # Run go vet
task ci         # Run all CI checks

قائمة المهام

مصادر أهداف إضافية

• إضافة تمرير الأهداف من تقييم أوامر الصدفة (لاستخدام cook أو radamsa أو حرفيًا جميع الأدوات المتاحة):
  • تقييم الأهداف على العميل وتمريرها عبر استدعاء grpc (يحمّل الشبكة على المدخلات الكبيرة)
  • التقييم على الخادم (يحتاج إلى استخدام التبعيات في بيئة الخادم)
• إضافة مصدر أهداف DNSDumpster
• إضافة مصدر أهداف Censys
• إضافة مصدر أهداف Shodan

تشغيلات ذات حالة

• إضافة حفظ حالة التشغيل
  • قائمة الأهداف المحلولة
  • العمال النشطون والمنتهون

دعم مزودي السحابة المتعددين

• إضافة مزود AWS (EC2)
• إضافة مزود Google Cloud Platform (Compute Engine)
• إضافة مزود Azure (Virtual Machines)
• إضافة مزود DigitalOcean

أنواع مراحل خط أنابيب موسعة

• إضافة مرحلة notify — إرسال الإشعارات أو التنبيهات (webhooks أو البريد الإلكتروني أو Slack)
• إضافة مرحلة conditional — تنفيذ المراحل بناءً على نتائج المرحلة السابقة
• إضافة مرحلة parallel — تنفيذ عمليات متعددة بشكل متزامن على نفس العامل
• إضافة مرحلة retry — إعادة محاولة العمليات الفاشلة تلقائيًا مع تأخير قابل للضبط
• إضافة مرحلة timeout — ضبط مهلات تنفيذ لكل مرحلة
• إضافة مرحلة validate — التحقق من النتائج أو الشروط قبل المتابعة

وضع الخفي مع التنفيذ المجدول

• تنفيذ الجدولة الزمنية بتعبيرات شبيهة بـ cron
• إضافة وضع المراقبة المستمرة للعمليات طويلة الأمد
• إضافة مشغلات تعتمد على الأحداث (webhooks، أحداث خارجية)
• تنفيذ حفظ النتائج وتتبع سجل التنفيذ
• إضافة فحوصات صحة مدمجة واسترداد تلقائي

أنواع بديلة لتخزين النتائج

• إضافة دعم تخزين الكائنات (S3 وGCS وAzure Blob Storage)
• إضافة دعم التخزين في قواعد البيانات (PostgreSQL وMySQL وMongoDB)
• إضافة دعم قوائم انتظار الرسائل (RabbitMQ وKafka وRedis streams)
• إضافة تكامل نقاط نهاية API (HTTP POST مخصص)
• إضافة دعم إشعارات البريد الإلكتروني مع المرفقات
• إضافة تكامل السجلات السحابية (CloudWatch وStackdriver وغيرها)

الترخيص

رخصة MIT. راجع ملف LICENSE للتفاصيل.