ReconSwarm

ReconSwarm è un framework di automazione per ricognizioni modulare progettato per test di sicurezza distribuiti. Effettua il provisioning dell'infrastruttura cloud, esegue pipeline di ricognizione in parallelo e raccoglie risultati con un overhead di configurazione minimo.

ReconSwarm è adatto per cacciatori di bug, penetration tester, ingegneri DevSecOps e ricercatori di sicurezza che necessitano di flussi di lavoro di ricognizione scalabili e automatizzati senza gestione manuale dell'infrastruttura.

Caratteristiche

• Divisione dei target per esecuzione parallela — L'elenco finale dei target compilati viene suddiviso tra i worker per l'esecuzione parallela delle attività di ricognizione
• Tipi di target multipli — L'elenco dei target è composto da diversi tipi di elementi: domini dalla risposta di crt.sh, elenco esterno (URL HTTP/HTTPS), elenco semplice (array YAML inline) e output di comandi shell, molto flessibile da usare con qualsiasi strumento (cook, shodan, gau, katana e così via).
• Architettura agnostica rispetto al cloud — Consente una facile integrazione con più provider cloud (attualmente supporta AWS, GCP, Yandex Cloud e Digital Ocean)
• Fasi pipeline flessibili — Sistema di fasi estensibile che attualmente supporta operazioni exec (esecuzione di comandi) e sync (sincronizzazione di file e directory)
• Contesto dei template nei passaggi — Modo flessibile per passare metadati dal contesto di esecuzione ai passaggi

Funzionalità essenziali da implementare

• Web UI - una semplice interfaccia utente web per iterazione veloce
• Log in tempo reale dalle fasi - catturare stdout/stderr e inviare al client tramite streaming grpc
• Shell remota verso i worker - apertura di connessioni ssh dal client ai worker tramite il server rs
• Fase Findings - una fase per elaborare i dati ricevuti dalla fase precedente (es. risultato json di nuclei), memorizzarli in etcd e inviare notifiche

Architettura

ReconSwarm segue un'architettura modulare con una chiara separazione delle responsabilità tra provisioning cloud, controllo remoto del sistema, esecuzione della pipeline e gestione della configurazione.

Astrazione del provider cloud

ReconSwarm utilizza un pattern a unione discriminata per i provisioner cloud. Il campo provisioner.type determina quale configurazione del provider è attiva:

provisioner:
  type: yandex_cloud  # Campo discriminante
  yandex_cloud:       # Attivo quando type: yandex_cloud
    iam_token: "${YC_TOKEN}"
    # key_path: "./sa_auth_key.json"
    folder_id: "${YC_FOLDER_ID}"
    # ... impostazioni specifiche del provider

È possibile integrare ulteriori provider cloud implementando l'interfaccia Provisioner e aggiungendo un nuovo tipo alla factory.

Sistema di fasi della pipeline

Le fasi sono componenti estensibili che eseguono operazioni sulle VM worker:

• exec — Esegue comandi shell con supporto per template
• sync — Copia file o directory dalle VM remote alla macchina locale tramite SFTP (rileva automaticamente se è un file o una directory)

Tutti i campi delle fasi supportano il rendering dei template. È possibile aggiungere nuovi tipi di fase per estendere le funzionalità.

Server stateless e tolleranza ai guasti

Il server ReconSwarm è completamente stateless — tutto lo stato è persistito in etcd:

• Stato della pipeline — Stato, avanzamento, errori per ogni pipeline
• Stato dei worker — Informazioni VM, attività corrente, stato
• Chiavi SSH — Coppie di chiavi generate per l'accesso alle VM

Questa architettura consente:

Setup per alta disponibilità:

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

Tutti i server condividono lo stesso cluster etcd e possono gestire qualsiasi richiesta. Se un server si arresta durante una pipeline, un altro server può continuare l'esecuzione dopo aver letto lo stato da etcd.

Nota: L'implementazione corrente esegue le pipeline in memoria dopo il caricamento da etcd. Il recupero completo da crash con ripresa della pipeline è previsto per release future.

Installazione

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

Configurazione

ReconSwarm separa la configurazione del server dalla configurazione della pipeline:

Configurazione del server

La configurazione del server è memorizzata in reconswarm.yaml (configurabile tramite la variabile d'ambiente CONFIG_PATH). Tutti i valori stringa supportano l'espansione delle variabili d'ambiente usando la sintassi ${VAR} o $VAR.

# Impostazioni server
server:
  port: 50051

# Connessione etcd per la gestione dello stato
etcd:
  endpoints:
    - "localhost:2379"
  dial_timeout: 5  # secondi
  username: ""     # opzionale, supporta ${ETCD_USER}
  password: ""     # opzionale, supporta ${ETCD_PASSWORD}

# Provisioner cloud (unione discriminata)
provisioner:
  type: yandex_cloud  # Selettore del provider

  # Configurazione Yandex Cloud (attiva quando 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

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

Configurazione della pipeline

La configurazione della pipeline è memorizzata in un file YAML separato e passata tramite il flag -f. Sono supportati sia il formato wrapped che unwrapped:

Formato wrapped (consigliato):

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

Formato unwrapped (anch'esso supportato):

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

Variabili d'ambiente

I valori di configurazione supportano la sostituzione delle variabili d'ambiente in due formati:

• ${VAR} — Nome completo della variabile tra graffe
• $VAR — Nome semplice della variabile

Se una variabile d'ambiente non è impostata, verrà utilizzata la stringa letterale (inclusi ${VAR} o $VAR).

Setup Yandex Cloud

Per l'integrazione con Yandex Cloud, utilizzare lo script di setup fornito:

1. Installa Yandex Cloud CLI (se non già installato):

   root@kitploit:~

   # Segui la documentazione ufficiale di Yandex Cloud per l'installazione della CLI
   

2. Configura Yandex Cloud CLI:

   root@kitploit:~

   yc config profile create <nome-profilo>
   yc config set cloud-id <id-cloud>
   yc config set folder-id <id-folder>
   

3. Esporta le credenziali:

   root@kitploit:~

   source ./secrets-setup.sh
   

   Questo script esporta:

   • YC_TOKEN — Token IAM per l'autenticazione
   • YC_FOLDER_ID — ID folder per la gestione delle risorse
   • YC_CLOUD_ID — ID cloud (se necessario)

4. Riferimento nella configurazione:

   root@kitploit:~

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

Lo script secrets-setup.sh genera automaticamente un nuovo token IAM ogni volta che viene eseguito, garantendo un'autenticazione sicura senza scrivere le credenziali in chiaro.

Setup Google Cloud Platform

1. Crea un Service Account:

   • Vai alla console GCP > IAM & Admin > Service Accounts
   • Crea un service account con il ruolo "Compute Admin"
   • Crea una chiave JSON e scaricala

2. Configura l'ambiente:

   root@kitploit:~

   export GCP_PROJECT_ID="id-tuo-progetto"
   export GCP_CREDENTIALS_PATH="/percorso/della/chiave.json"
   

3. Riferimento nella configurazione:

   root@kitploit:~

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

Setup AWS

1. Crea un utente IAM:

   • Vai alla console AWS > IAM > Users
   • Crea un utente con autorizzazioni "AmazonEC2FullAccess"
   • Genera Access Key ID e Secret Access Key

2. Configura l'ambiente:

   root@kitploit:~

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

3. Riferimento nella configurazione:

   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"
   

Setup DigitalOcean

1. Genera un token:

   • Vai al pannello di controllo DigitalOcean > API
   • Genera un Personal Access Token con ambito "Write"

2. Configura l'ambiente:

   root@kitploit:~

   export DO_TOKEN="tuo-token"
   

3. Riferimento nella configurazione:

   root@kitploit:~

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

Tipi di target

Enumerazione da crt.sh:

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

Elenco manuale:

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

Configurazione delle fasi

Tutti i campi di configurazione delle fasi supportano la sintassi Go template per la generazione dinamica dei valori. Le variabili del template vengono renderizzate al momento dell'esecuzione con i dati di contesto forniti automaticamente.

Contesto del template

I seguenti dati sono disponibili in tutti i template delle fasi:

Fase exec — Esegue comandi shell con supporto template:

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

Tutti i comandi nell'array steps vengono renderizzati con il template prima dell'esecuzione.

Fase sync — Copia file o directory dal remoto al locale usando SFTP. Rileva automaticamente se il percorso è un file o una directory:

stages:
  - name: "Raccogli risultati"
    type: sync
    src: "/opt/recon/results.json"
    dest: "./results/{{.Worker.Name}}.json"
  
  # Sincronizza l'intera directory in modo ricorsivo
  - name: "Raccogli tutti i risultati"
    type: sync
    src: "/opt/recon"
    dest: "./results/{{.Worker.Name}}"

Sia src (percorso remoto) che dest (percorso locale) supportano il rendering dei template per percorsi dinamici. La fase sync rileva automaticamente se il percorso di origine è un file o una directory e lo gestisce di conseguenza.

Utilizzo

Modalità server

Avvia il server gRPC per accettare l'invio di pipeline:

reconswarm server

Il server legge la configurazione da reconswarm.yaml e rimane in ascolto sulla porta configurata (default: 50051).

Invia pipeline tramite gRPC

Invia una pipeline a un server in esecuzione:

reconswarm run -f examples/pipelines/nuclei.yaml

Opzioni:

• -f, --pipeline — Percorso del file YAML della pipeline (obbligatorio)
• -s, --server — Indirizzo del server (default: localhost:50051)

Controlla lo stato della pipeline

reconswarm status <pipeline-id>

Esecuzione manuale della pipeline

Esegue una pipeline direttamente senza il server gRPC (utile per test):

reconswarm manual -f examples/pipelines/nuclei.yaml

Questo comando:

1. Legge la configurazione del server da reconswarm.yaml
2. Prepara i target (enumera i sottodomini tramite crt.sh se necessario)
3. Crea le VM worker in base alla configurazione workers.max_workers
4. Distribuisce i target tra i worker
5. Esegue i comandi di setup su ogni VM
6. Esegue le fasi della pipeline in sequenza
7. Raccoglie i risultati tramite le fasi sync
8. Dealloca automaticamente tutta l'infrastruttura al completamento

La deallocazione automatica dell'infrastruttura garantisce completa autonomia — tutte le risorse cloud vengono provisionate, utilizzate e distrutte senza intervento manuale, consentendo flussi di lavoro di ricognizione completamente automatizzati.

Esempi di configurazione

Per esempi completi di pipeline, consulta la directory examples/pipelines.

Enumerazione di base dei sottodomini e scansione:

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

Esegui con:

reconswarm manual -f pipeline.yaml
# oppure invia al server:
reconswarm run -f pipeline.yaml

Target multipli con scansione basata su Docker:

pipeline:
  targets:
    - value: "example.com"
      type: crtsh
    - value: ["api.example.com", "www.example.com"]
      type: list
  stages:
    - name: "Esegui scansione 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: "Copia risultati nuclei"
      type: sync
      src: "/opt/recon/nuclei-{{.Worker.Name}}.json"
      dest: "./results/nuclei-{{.Worker.Name}}.json"

Toolchain personalizzata con più fasi:

Configurazione server (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"

Configurazione pipeline (pipeline.yaml):

pipeline:
  targets:
    - value: "example.com"
      type: crtsh
  stages:
    - name: "Enumerazione aggiuntiva"
      type: exec
      steps:
        - "cd subfinder && ./subfinder -dL {{.Targets.filepath}} -o /opt/recon/subfinder-{{.Worker.Name}}.txt"
    - name: "Unisci target"
      type: exec
      steps:
        - "cat {{.Targets.filepath}} /opt/recon/subfinder-{{.Worker.Name}}.txt | sort -u > /opt/recon/all-targets-{{.Worker.Name}}.txt"
    - name: "Scansiona target uniti"
      type: exec
      steps:
        - "nmap -sC -sV -iL /opt/recon/all-targets-{{.Worker.Name}}.txt -oN /opt/recon/scan-{{.Worker.Name}}.txt"
    - name: "Raccogli tutti i risultati"
      type: sync
      src: "/opt/recon"
      dest: "./results/{{.Worker.Name}}"

Nota: La fase sync rileva automaticamente che /opt/recon è una directory e copia ricorsivamente tutti i file e le sottodirectory nella destinazione locale.

Altri comandi

Enumerazione sottodomini:

reconswarm crtsh-dump example.com

Recupera e filtra i sottodomini risolvibili da crt.sh per un dato dominio.

Comando di debug (per testare il provisioning delle VM):

reconswarm debug

Sviluppo

Compila e testa usando Task:

task build      # Compila il binario
task test       # Esegue i test
task lint       # Esegue il linter
task vet        # Esegue go vet
task ci         # Esegue tutti i controlli CI

TODO

Fonti di target aggiuntive

• Aggiungere passaggio di target dalla valutazione della shell (per usare cook, radamsa o tutti gli strumenti disponibili):
  • valutazione target sul client e passaggio tramite chiamata grpc (overhead di rete per input grandi)
  • valutazione sul server (necessario usare dipendenze nell'ambiente del server)
• Aggiungere fonte target DNSDumpster
• Aggiungere fonte target Censys
• Aggiungere fonte target Shodan

Esecuzioni stateful

• Aggiungere salvataggio dello stato dell'esecuzione
  • Elenco target risolto
  • Worker in esecuzione e terminati

Supporto multi-provider cloud

• Aggiungere provisioner AWS (EC2)
• Aggiungere provisioner Google Cloud Platform (Compute Engine)
• Aggiungere provisioner Azure (Virtual Machines)
• Aggiungere provisioner DigitalOcean

Tipi di fase pipeline estesi

• Aggiungere fase notify — Inviare notifiche o avvisi (webhook, email, Slack)
• Aggiungere fase conditional — Eseguire fasi in base ai risultati di fasi precedenti
• Aggiungere fase parallel — Eseguire più operazioni contemporaneamente sullo stesso worker
• Aggiungere fase retry — Ripetere automaticamente operazioni fallite con backoff configurabile
• Aggiungere fase timeout — Impostare timeout di esecuzione per fase
• Aggiungere fase validate — Validare risultati o condizioni prima di procedere

Modalità demone con esecuzione programmata

• Implementare esecuzione programmata con espressioni simili a cron
• Aggiungere modalità di monitoraggio continuo per processi a lunga esecuzione
• Aggiungere trigger basati su eventi (webhook, eventi esterni)
• Implementare persistenza dei risultati e tracciamento della cronologia delle esecuzioni
• Aggiungere health check integrati e recupero automatico

Tipi di archiviazione risultati alternativi

• Aggiungere supporto object storage (S3, GCS, Azure Blob Storage)
• Aggiungere supporto database (PostgreSQL, MySQL, MongoDB)
• Aggiungere supporto code di messaggi (RabbitMQ, Kafka, Redis streams)
• Aggiungere integrazione endpoint API (HTTP POST personalizzato)
• Aggiungere supporto notifiche email con allegati
• Aggiungere integrazione logging cloud (CloudWatch, Stackdriver, ecc.)

Licenza

Licenza MIT. Vedi il file LICENSE per i dettagli.