ReconSwarm

ReconSwarm est un framework modulaire d'automatisation de reconnaissance conçu pour les tests de sécurité distribués. Il provisionne une infrastructure cloud, exécute des pipelines de reconnaissance parallèles et collecte les résultats avec un minimum de configuration.

ReconSwarm est adapté aux chasseurs de bug bounty, testeurs d'intrusion, ingénieurs DevSecOps et chercheurs en sécurité qui ont besoin de workflows de reconnaissance automatisés et évolutifs sans gestion manuelle de l'infrastructure.

Fonctionnalités

• Division des cibles pour exécution parallèle — La liste finale des cibles compilées est divisée entre les workers pour une exécution parallèle des tâches de reconnaissance
• Types de cibles multiples — La liste de cibles se compose de plusieurs types d'éléments : domaines issus de la réponse crt.sh, liste externe (URLs HTTP/HTTPS), liste simple (tableaux YAML en ligne) et sortie de commande shell, ce qui est très flexible pour une utilisation avec n'importe quel outil (cook, shodan, gau, katana, etc.)
• Architecture agnostique au cloud — Permet une intégration facile avec plusieurs fournisseurs cloud (prend actuellement en charge AWS, GCP, Yandex Cloud et Digital Ocean)
• Étapes de pipeline flexibles — Système d'étapes extensible prenant actuellement en charge les opérations exec (exécution de commandes) et sync (synchronisation de fichiers et répertoires)
• Contexte de template dans les étapes — Manière flexible de passer des métadonnées du contexte d'exécution aux étapes

Fonctionnalités indispensables à réaliser

• Web UI — Une interface utilisateur web simple et conviviale pour une itération rapide
• Logs en temps réel des étapes — Capturer stdout/stderr et les envoyer au client via streaming gRPC
• Shell distant vers les workers — Ouverture d'une connexion SSH du client aux workers via le serveur rs
• Étape Findings — Une étape pour traiter les données reçues de l'étape précédente (par exemple, résultat JSON de nuclei), les stocker dans etcd et envoyer des notifications

Architecture

ReconSwarm suit une architecture modulaire avec une séparation claire des responsabilités entre le provisionnement cloud, le contrôle à distance du système, l'exécution des pipelines et la gestion de la configuration.

Abstraction du fournisseur cloud

ReconSwarm utilise un modèle d'union discriminée pour les provisionneurs cloud. Le champ provisioner.type détermine quelle configuration de fournisseur est active :

provisioner:
  type: yandex_cloud  # Champ discriminant
  yandex_cloud:       # Actif lorsque type: yandex_cloud
    iam_token: "${YC_TOKEN}"
    # key_path: "./sa_auth_key.json"
    folder_id: "${YC_FOLDER_ID}"
    # ... paramètres spécifiques au fournisseur

Des fournisseurs cloud supplémentaires peuvent être intégrés en implémentant l'interface Provisioner et en ajoutant un nouveau type à la fabrique.

Système d'étapes de pipeline

Les étapes sont des composants extensibles qui exécutent des opérations sur les machines virtuelles des workers :

• exec — Exécute des commandes shell avec support des templates
• sync — Copie des fichiers ou répertoires des machines virtuelles distantes vers la machine locale via SFTP (détecte automatiquement fichier ou répertoire)

Tous les champs des étapes prennent en charge le rendu des templates. De nouveaux types d'étapes peuvent être ajoutés pour étendre les fonctionnalités.

Serveur sans état & Tolérance aux pannes

Le serveur ReconSwarm est complètement sans état — tout l'état est persistant dans etcd :

• État du pipeline — Statut, progression, erreurs pour chaque pipeline
• État des workers — Informations sur la machine virtuelle, tâche en cours, statut
• Clés SSH — Paires de clés générées pour l'accès aux machines virtuelles

Cette architecture permet :

Configuration haute disponibilité :

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

Tous les serveurs partagent le même cluster etcd et peuvent traiter n'importe quelle requête. Si un serveur tombe en panne au milieu d'un pipeline, un autre serveur peut continuer l'exécution après avoir lu l'état depuis etcd.

Remarque : L'implémentation actuelle exécute les pipelines en mémoire après les avoir chargés depuis etcd. La récupération complète après crash avec reprise du pipeline est prévue pour les prochaines versions.

Installation

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

Configuration

ReconSwarm sépare la configuration du serveur de la configuration du pipeline :

Configuration du serveur

La configuration du serveur est stockée dans reconswarm.yaml (configurable via la variable d'environnement CONFIG_PATH). Toutes les valeurs de chaîne prennent en charge le développement des variables d'environnement en utilisant la syntaxe ${VAR} ou $VAR.

# Paramètres du serveur
server:
  port: 50051

# Connexion etcd pour la gestion d'état
etcd:
  endpoints:
    - "localhost:2379"
  dial_timeout: 5  # secondes
  username: ""     # optionnel, supporte ${ETCD_USER}
  password: ""     # optionnel, supporte ${ETCD_PASSWORD}

# Provisionneur cloud (union discriminée)
provisioner:
  type: yandex_cloud  # Sélecteur de fournisseur

  # Configuration Yandex Cloud (active quand 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

# Paramètres du pool de workers
workers:
  max_workers: 5
  setup_commands:
    - "apt update"
    - "apt install -y docker.io"

Configuration du pipeline

La configuration du pipeline est stockée dans un fichier YAML séparé et passée via le flag -f. Les formats avec et sans enveloppe sont pris en charge :

Format avec enveloppe (recommandé) :

# pipeline.yaml
pipeline:
  targets:
    - value: "example.com"
      type: crtsh
    - value: ["sub1.example.com", "sub2.example.com"]
      type: list
  stages:
    - name: "Exécuter le scanner"
      type: exec
      steps:
        - "nmap -sC -sV -iL {{.Targets.filepath}} -oN /opt/recon/scan.txt"
    - name: "Récupérer les résultats"
      type: sync
      src: "/opt/recon/scan.txt"
      dest: "./results/{{.Worker.Name}}.txt"

Format sans enveloppe (également pris en charge) :

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

Variables d'environnement

Les valeurs de configuration prennent en charge la substitution de variables d'environnement dans deux formats :

• ${VAR} — Nom complet de la variable entre accolades
• $VAR — Nom simple de la variable

Si une variable d'environnement n'est pas définie, la chaîne littérale (y compris ${VAR} ou $VAR) sera utilisée.

Configuration Yandex Cloud

Pour l'intégration à Yandex Cloud, utilisez le script de configuration fourni :

1. Installez Yandex Cloud CLI (si ce n'est pas déjà fait) :

   root@kitploit:~

   # Suivez la documentation officielle de Yandex Cloud pour l'installation de CLI
   

2. Configurez Yandex Cloud CLI :

   root@kitploit:~

   yc config profile create <nom-profil>
   yc config set cloud-id <votre-cloud-id>
   yc config set folder-id <votre-folder-id>
   

3. Exportez les identifiants :

   root@kitploit:~

   source ./secrets-setup.sh
   

   Ce script exporte :

   • YC_TOKEN — Jeton IAM pour l'authentification
   • YC_FOLDER_ID — ID du dossier pour la gestion des ressources
   • YC_CLOUD_ID — ID du cloud (si nécessaire)

4. Référencez dans la configuration :

   root@kitploit:~

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

Le script secrets-setup.sh génère automatiquement un nouveau jeton IAM à chaque exécution, garantissant une authentification sécurisée sans codage en dur des identifiants.

Configuration Google Cloud Platform

1. Créez un compte de service :

   • Allez dans GCP Console > IAM & Admin > Service Accounts
   • Créez un compte de service avec le rôle "Compute Admin"
   • Créez une clé JSON et téléchargez-la

2. Configurez l'environnement :

   root@kitploit:~

   export GCP_PROJECT_ID="votre-id-projet"
   export GCP_CREDENTIALS_PATH="/chemin/vers/key.json"
   

3. Référencez dans la configuration :

   root@kitploit:~

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

Configuration AWS

1. Créez un utilisateur IAM :

   • Allez dans AWS Console > IAM > Users
   • Créez un utilisateur avec les permissions "AmazonEC2FullAccess"
   • Générez un ID de clé d'accès et une clé d'accès secrète

2. Configurez l'environnement :

   root@kitploit:~

   export AWS_ACCESS_KEY_ID="votre-cle-acces"
   export AWS_SECRET_ACCESS_KEY="votre-cle-secrete"
   

3. Référencez dans la configuration :

   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"
   

Configuration DigitalOcean

1. Générez un jeton :

   • Allez dans DigitalOcean Control Panel > API
   • Générez un jeton d'accès personnel avec la portée "Write"

2. Configurez l'environnement :

   root@kitploit:~

   export DO_TOKEN="votre-jeton"
   

3. Référencez dans la configuration :

   root@kitploit:~

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

Types de cibles

Énumération crt.sh :

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

Liste manuelle :

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

Configuration des étapes

Tous les champs de configuration des étapes prennent en charge la syntaxe Go template pour la génération dynamique de valeurs. Les variables template sont rendues au moment de l'exécution avec les données de contexte fournies automatiquement.

Contexte du template

Les données suivantes sont disponibles dans tous les templates d'étapes :

Étape exec — Exécute des commandes shell avec support des templates :

stages:
  - name: "Exécuter l'outil"
    type: exec
    steps:
      - "docker run --rm -v /opt/recon:/data scanner:latest {{.Targets.filepath}}"
      - "cat /opt/recon/results.json"

Toutes les commandes dans le tableau steps sont rendues via template avant exécution.

Étape sync — Copie des fichiers ou répertoires du distant vers le local via SFTP. Détecte automatiquement si le chemin est un fichier ou un répertoire :

stages:
  - name: "Récupérer les résultats"
    type: sync
    src: "/opt/recon/results.json"
    dest: "./results/{{.Worker.Name}}.json"
  
  # Synchroniser tout un répertoire récursivement
  - name: "Récupérer tous les résultats"
    type: sync
    src: "/opt/recon"
    dest: "./results/{{.Worker.Name}}"

src (chemin distant) et dest (chemin local) prennent en charge le rendu template pour des chemins de fichiers dynamiques. L'étape sync détecte automatiquement si le chemin source est un fichier ou un répertoire et le traite en conséquence.

Utilisation

Mode serveur

Démarrez le serveur gRPC pour accepter les soumissions de pipelines :

reconswarm server

Le serveur lit la configuration depuis reconswarm.yaml et écoute sur le port configuré (par défaut : 50051).

Soumettre un pipeline via gRPC

Soumettez un pipeline à un serveur en cours d'exécution :

reconswarm run -f examples/pipelines/nuclei.yaml

Options :

• -f, --pipeline — Chemin vers le fichier YAML du pipeline (obligatoire)
• -s, --server — Adresse du serveur (par défaut : localhost:50051)

Vérifier l'état d'un pipeline

reconswarm status <id-pipeline>

Exécution manuelle d'un pipeline

Exécutez un pipeline directement sans le serveur gRPC (utile pour les tests) :

reconswarm manual -f examples/pipelines/nuclei.yaml

Cette commande :

1. Lit la configuration du serveur depuis reconswarm.yaml
2. Prépare les cibles (énumère les sous-domaines via crt.sh si nécessaire)
3. Crée des machines virtuelles de workers selon la configuration workers.max_workers
4. Distribue les cibles entre les workers
5. Exécute les commandes de configuration sur chaque machine virtuelle
6. Lance les étapes du pipeline séquentiellement
7. Collecte les résultats via les étapes sync
8. Désalloue automatiquement toute l'infrastructure une fois terminée

La désallocation automatique de l'infrastructure garantit une autonomie complète — toutes les ressources cloud sont provisionnées, utilisées et détruites sans intervention manuelle, permettant des workflows de reconnaissance entièrement automatisés.

Exemples de configurations

Pour des exemples complets de pipelines, voir le répertoire examples/pipelines.

Énumération et analyse de base des sous-domaines :

# pipeline.yaml
pipeline:
  targets:
    - value: "example.com"
      type: crtsh
  stages:
    - name: "Scanner les cibles"
      type: exec
      steps:
        - "nmap -sC -sV -iL {{.Targets.filepath}} -oN /opt/recon/nmap-{{.Worker.Name}}.txt"
    - name: "Récupérer les résultats"
      type: sync
      src: "/opt/recon/nmap-{{.Worker.Name}}.txt"
      dest: "./results/nmap-{{.Worker.Name}}.txt"

Exécutez avec :

reconswarm manual -f pipeline.yaml
# ou soumettre au serveur :
reconswarm run -f pipeline.yaml

Cibles multiples avec analyse basée sur Docker :

pipeline:
  targets:
    - value: "example.com"
      type: crtsh
    - value: ["api.example.com", "www.example.com"]
      type: list
  stages:
    - name: "Exécuter le scan nuclei"
      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: "Copier les résultats nuclei"
      type: sync
      src: "/opt/recon/nuclei-{{.Worker.Name}}.json"
      dest: "./results/nuclei-{{.Worker.Name}}.json"

Chaîne d'outils personnalisée avec plusieurs étapes :

Configuration du serveur (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"

Configuration du pipeline (pipeline.yaml) :

pipeline:
  targets:
    - value: "example.com"
      type: crtsh
  stages:
    - name: "Énumération supplémentaire"
      type: exec
      steps:
        - "cd subfinder && ./subfinder -dL {{.Targets.filepath}} -o /opt/recon/subfinder-{{.Worker.Name}}.txt"
    - name: "Fusionner les cibles"
      type: exec
      steps:
        - "cat {{.Targets.filepath}} /opt/recon/subfinder-{{.Worker.Name}}.txt | sort -u > /opt/recon/all-targets-{{.Worker.Name}}.txt"
    - name: "Scanner les cibles fusionnées"
      type: exec
      steps:
        - "nmap -sC -sV -iL /opt/recon/all-targets-{{.Worker.Name}}.txt -oN /opt/recon/scan-{{.Worker.Name}}.txt"
    - name: "Collecter tous les résultats"
      type: sync
      src: "/opt/recon"
      dest: "./results/{{.Worker.Name}}"

Remarque : L'étape sync détecte automatiquement que /opt/recon est un répertoire et copie récursivement tous les fichiers et sous-répertoires vers la destination locale.

Autres commandes

Énumération de sous-domaines :

reconswarm crtsh-dump example.com

Récupère et filtre les sous-domaines résolvables depuis crt.sh pour un domaine donné.

Commande de débogage (pour tester le provisionnement des machines virtuelles) :

reconswarm debug

Développement

Construisez et testez en utilisant Task :

task build      # Construire le binaire
task test       # Exécuter les tests
task lint       # Exécuter le linter
task vet        # Exécuter go vet
task ci         # Exécuter toutes les vérifications CI

TODO

Sources de cibles supplémentaires

• Ajouter la possibilité de passer des cibles via l'évaluation d'une commande shell (pour utiliser cook, radamsa ou tous les outils disponibles) :
  • Évaluer les cibles côté client et les transmettre via l'appel gRPC (surcharge réseau pour les grandes entrées)
  • Évaluer côté serveur (nécessite l'utilisation de dépendances dans l'environnement serveur)
• Ajouter la source de cibles DNSDumpster
• Ajouter la source de cibles Censys
• Ajouter la source de cibles Shodan

Exécutions avec état

• Ajouter la sauvegarde de l'état d'exécution
  • Liste de cibles résolues
  • Workers en cours et terminés

Support multi-fournisseur cloud

• Ajouter un provisionneur AWS (EC2)
• Ajouter un provisionneur Google Cloud Platform (Compute Engine)
• Ajouter un provisionneur Azure (Virtual Machines)
• Ajouter un provisionneur DigitalOcean

Types d'étapes de pipeline étendus

• Ajouter une étape notify — Envoyer des notifications ou alertes (webhooks, email, Slack)
• Ajouter une étape conditional — Exécuter des étapes en fonction des résultats d'étapes précédentes
• Ajouter une étape parallel — Exécuter plusieurs opérations simultanément sur le même worker
• Ajouter une étape retry — Réessayer automatiquement les opérations échouées avec backoff configurable
• Ajouter une étape timeout — Définir des délais d'expiration par étape
• Ajouter une étape validate — Valider les résultats ou conditions avant de continuer

Mode démon avec exécution planifiée

• Implémenter l'exécution planifiée avec des expressions de type cron
• Ajouter un mode de surveillance continue pour les processus de longue durée
• Ajouter des déclencheurs basés sur des événements (webhooks, événements externes)
• Implémenter la persistance des résultats et le suivi de l'historique d'exécution
• Ajouter des vérifications de santé intégrées et une récupération automatique

Types de stockage de résultats alternatifs

• Ajouter le support du stockage objet (S3, GCS, Azure Blob Storage)
• Ajouter le support du stockage en base de données (PostgreSQL, MySQL, MongoDB)
• Ajouter le support des files de messages (RabbitMQ, Kafka, Redis streams)
• Ajouter l'intégration d'API (POST HTTP personnalisé)
• Ajouter le support des notifications par email avec pièces jointes
• Ajouter l'intégration de logs cloud (CloudWatch, Stackdriver, etc.)

Licence

Licence MIT. Voir le fichier LICENSE pour plus de détails.