ReconSwarm

ReconSwarm ist ein modulares Reconnaissance-Automatisierungs-Framework für verteilte Sicherheitstests. Es stellt Cloud-Infrastruktur bereit, führt parallele Reconnaissance-Pipelines aus und sammelt Ergebnisse mit minimalem Konfigurationsaufwand.

ReconSwarm eignet sich für Bug-Bounty-Jäger, Penetrationstester, DevSecOps-Ingenieure und Sicherheitsforscher, die skalierbare, automatisierte Reconnaissance-Workflows ohne manuelles Infrastrukturmanagement benötigen.

Features

• Aufteilung der Ziele für parallele Ausführung — Die endgültige Liste der zusammengestellten Ziele wird auf Worker aufgeteilt, um Reconnaissance-Aufgaben parallel auszuführen.
• Mehrere Zieltypen — Die Zielliste besteht aus mehreren Elementtypen: Domänen aus crt.sh-Antworten, externen Listen (HTTP/HTTPS-URLs), einfachen Listen (Inline-YAML-Arrays) und Shell-Befehlsausgabe, was sehr flexibel für den Einsatz mit beliebigen Tools (cook, shodan, gau, katana usw.) ist.
• Cloud-unabhängige Architektur — Ermöglicht einfache Integration mit mehreren Cloud-Anbietern (unterstützt derzeit AWS, GCP, Yandex Cloud und Digital Ocean).
• Flexible Pipeline-Stufen — Erweiterbares Stufensystem, das derzeit exec (Befehlsausführung) und sync (Datei- und Verzeichnissynchronisation) unterstützt.
• Vorlagenkontext in Schritten — Flexible Möglichkeit, Metadaten vom Ausführungskontext an Schritte zu übergeben.

Noch zu implementierende Muss-Funktionen

• Web-UI – eine einfache webbasierte benutzerfreundliche Oberfläche für schnelle Interaktion
• Echtzeitprotokolle von Stufen – Erfassen von stdout/stderr und Senden an den Client per gRPC-Streaming
• Remote-Shell zu Workern – Öffnen einer SSH-Verbindung vom Client zu Workern über den RS-Server
• Findings-Stufe – eine Stufe zur Verarbeitung von Daten aus vorherigen Stufen (z. B. nuclei-JSON-Ergebnisse), Speicherung in etcd und Erstellung von Benachrichtigungen

Architektur

ReconSwarm folgt einer modularen Architektur mit klarer Trennung der Zuständigkeiten zwischen Cloud-Bereitstellung, Fernsteuerung von Systemen, Pipeline-Ausführung und Konfigurationsmanagement.

Abstraktion der Cloud-Anbieter

ReconSwarm verwendet ein diskriminiertes Union-Muster für Cloud-Provisioner. Das Feld provisioner.type bestimmt, welche Anbieterkonfiguration aktiv ist:

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

Zusätzliche Cloud-Anbieter können durch Implementierung des Provisioner-Interfaces und Hinzufügen eines neuen Typs zur Factory integriert werden.

Pipeline-Stufensystem

Stufen sind erweiterbare Komponenten, die Operationen auf Worker-VMs ausführen:

• exec – Führt Shell-Befehle mit Vorlagenunterstützung aus
• sync – Kopiert Dateien oder Verzeichnisse von entfernten VMs auf den lokalen Rechner per SFTP (erkennt automatisch Datei oder Verzeichnis)

Alle Stufenfelder unterstützen die Vorlagenrendering. Neue Stufentypen können hinzugefügt werden, um die Funktionalität zu erweitern.

Zustandsloser Server & Fehlertoleranz

Der ReconSwarm-Server ist vollständig zustandslos – der gesamte Zustand wird in etcd persistiert:

• Pipeline-Zustand – Status, Fortschritt, Fehler für jede Pipeline
• Worker-Zustand – VM-Informationen, aktuelle Aufgabe, Status
• SSH-Schlüssel – Generierte Schlüsselpaare für VM-Zugriff

Diese Architektur ermöglicht:

Hochverfügbarkeits-Setup:

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

Alle Server nutzen denselben etcd-Cluster und können jede Anfrage bearbeiten. Wenn ein Server mitten in einer Pipeline abstürzt, kann ein anderer Server nach dem Auslesen des Zustands aus etcd die Ausführung fortsetzen.

Hinweis: Die aktuelle Implementierung führt Pipelines nach dem Laden aus etcd im Arbeitsspeicher aus. Eine vollständige Absturzwiederherstellung mit Pipeline-Fortsetzung ist für zukünftige Versionen geplant.

Installation

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

Konfiguration

ReconSwarm trennt die Serverkonfiguration von der Pipelinekonfiguration:

Server-Konfiguration

Die Serverkonfiguration wird in reconswarm.yaml gespeichert (konfigurierbar über die Umgebungsvariable CONFIG_PATH). Alle Zeichenfolgenwerte unterstützen die Umgebungsvariablen-Expansion mit ${VAR} oder $VAR-Syntax.

# 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"

Pipeline-Konfiguration

Die Pipeline-Konfiguration wird in einer separaten YAML-Datei gespeichert und über das Flag -f übergeben. Es werden sowohl das umschlossene als auch das nicht umschlossene Format unterstützt:

Umschlossenes Format (empfohlen):

# 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"

Nicht umschlossenes Format (ebenfalls unterstützt):

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

Umgebungsvariablen

Konfigurationswerte unterstützen die Ersetzung von Umgebungsvariablen in zwei Formaten:

• ${VAR} — Vollständiger Variablenname in geschweiften Klammern
• $VAR — Einfacher Variablenname

Wenn eine Umgebungsvariable nicht gesetzt ist, wird der Literal-String (einschließlich ${VAR} oder $VAR) verwendet.

Yandex Cloud Einrichtung

Für die Yandex-Cloud-Integration verwenden Sie das mitgelieferte Setup-Skript:

1. Yandex Cloud CLI installieren (falls noch nicht geschehen):

   root@kitploit:~

   # Follow official Yandex Cloud documentation for CLI installation
   

2. Yandex Cloud CLI konfigurieren:

   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. Anmeldedaten exportieren:

   root@kitploit:~

   source ./secrets-setup.sh
   

   Dieses Skript exportiert:

   • YC_TOKEN — IAM-Token zur Authentifizierung
   • YC_FOLDER_ID — Ordner-ID für die Ressourcenverwaltung
   • YC_CLOUD_ID — Cloud-ID (falls benötigt)

4. In der Konfiguration referenzieren:

   root@kitploit:~

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

Das Skript secrets-setup.sh generiert bei jeder Ausführung automatisch ein neues IAM-Token und gewährleistet so eine sichere Authentifizierung ohne hartcodierte Anmeldedaten.

Google Cloud Platform Einrichtung

1. Service Account erstellen:

   • Gehen Sie zur GCP-Konsole > IAM & Verwaltung > Dienstkonten
   • Erstellen Sie ein Dienstkonto mit der Rolle "Compute-Administrator"
   • Erstellen Sie einen JSON-Schlüssel und laden Sie ihn herunter

2. Umgebung konfigurieren:

   root@kitploit:~

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

3. In der Konfiguration referenzieren:

   root@kitploit:~

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

AWS Einrichtung

1. IAM-Benutzer erstellen:

   • Gehen Sie zur AWS-Konsole > IAM > Benutzer
   • Erstellen Sie einen Benutzer mit den Berechtigungen "AmazonEC2FullAccess"
   • Generieren Sie einen Zugriffsschlüssel-ID und einen geheimen Zugriffsschlüssel

2. Umgebung konfigurieren:

   root@kitploit:~

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

3. In der Konfiguration referenzieren:

   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 Einrichtung

1. Token generieren:

   • Gehen Sie zum DigitalOcean-Kontrollfeld > API
   • Generieren Sie ein persönliches Zugriffstoken mit dem Bereich "Write"

2. Umgebung konfigurieren:

   root@kitploit:~

   export DO_TOKEN="your-token"
   

3. In der Konfiguration referenzieren:

   root@kitploit:~

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

Zieltypen

crt.sh-Enumeration:

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

Manuelle Liste:

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

Stufenkonfiguration

Alle Felder der Stufenkonfiguration unterstützen die Go-Template-Syntax zur dynamischen Wertegenerierung. Vorlagenvariablen werden zur Ausführungszeit mit automatisch bereitgestellten Kontextdaten gerendert.

Vorlagenkontext

Die folgenden Daten sind in allen Stufenvorlagen verfügbar:

Exec-Stufe – Führt Shell-Befehle mit Vorlagenunterstützung aus:

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

Alle Befehle im Array steps werden vor der Ausführung mit Vorlagen gerendert.

Sync-Stufe – Kopiert Dateien oder Verzeichnisse per SFTP von entfernten Rechnern auf den lokalen Rechner. Erkennt automatisch, ob der Pfad eine Datei oder ein Verzeichnis ist:

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}}"

Sowohl src (entfernter Pfad) als auch dest (lokaler Pfad) unterstützen die Vorlagenrendering für dynamische Dateipfade. Die Sync-Stufe erkennt automatisch, ob der Quellpfad eine Datei oder ein Verzeichnis ist, und behandelt ihn entsprechend.

Verwendung

Server-Modus

Starten Sie den gRPC-Server, um Pipeline-Übermittlungen zu akzeptieren:

reconswarm server

Der Server liest die Konfiguration aus reconswarm.yaml und lauscht auf dem konfigurierten Port (Standard: 50051).

Pipeline per gRPC übermitteln

Übermitteln Sie eine Pipeline an einen laufenden Server:

reconswarm run -f examples/pipelines/nuclei.yaml

Optionen:

• -f, --pipeline – Pfad zur Pipeline-YAML-Datei (erforderlich)
• -s, --server – Serveradresse (Standard: localhost:50051)

Pipeline-Status überprüfen

reconswarm status <pipeline-id>

Manuelle Pipeline-Ausführung

Führen Sie eine Pipeline direkt ohne den gRPC-Server aus (nützlich zum Testen):

reconswarm manual -f examples/pipelines/nuclei.yaml

Dieser Befehl:

1. Liest die Serverkonfiguration aus reconswarm.yaml
2. Bereitet Ziele vor (zählt Subdomains über crt.sh auf, falls erforderlich)
3. Erstellt Worker-VMs basierend auf der Konfiguration workers.max_workers
4. Verteilt Ziele auf die Worker
5. Führt Setup-Befehle auf jeder VM aus
6. Führt Pipeline-Stufen sequenziell aus
7. Sammelt Ergebnisse über Sync-Stufen
8. Gibt automatisch die gesamte Infrastruktur nach Abschluss frei

Die automatische Freigabe der Infrastruktur gewährleistet vollständige Autonomie – alle Cloud-Ressourcen werden ohne manuelles Eingreifen bereitgestellt, genutzt und zerstört, was vollständig automatisierte Reconnaissance-Workflows ermöglicht.

Beispielkonfigurationen

Vollständige Pipeline-Beispiele finden Sie im Verzeichnis examples/pipelines.

Grundlegende Subdomain-Enumeration und -Scan:

# 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"

Ausführen mit:

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

Mehrere Ziele mit Docker-basiertem Scanning:

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"

Benutzerdefinierte Toolchain mit mehreren Stufen:

Server-Konfiguration (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-Konfiguration (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}}"

Hinweis: Die Sync-Stufe erkennt automatisch, dass /opt/recon ein Verzeichnis ist, und kopiert rekursiv alle Dateien und Unterverzeichnisse an das lokale Ziel.

Weitere Befehle

Subdomain-Enumeration:

reconswarm crtsh-dump example.com

Ruft auflösbare Subdomains aus crt.sh für eine bestimmte Domain ab und filtert sie.

Debug-Befehl (zum Testen der VM-Bereitstellung):

reconswarm debug

Entwicklung

Erstellen und testen Sie mit Task:

task build      # Binary erstellen
task test       # Tests ausführen
task lint       # Linter ausführen
task vet        # go vet ausführen
task ci         # Alle CI-Prüfungen ausführen

TODO

Zusätzliche Zielquellen

• Hinzufügen der Übergabe von Zielen aus der Shell-Auswertung (zur Verwendung von cook, radamsa oder praktisch allen verfügbaren Tools):
  • Auswertung von Zielen auf dem Client und Übergabe per gRPC-Aufruf (durch Netzwerk bei großen Eingaben aufwändig)
  • Auswertung auf dem Server (erfordert die Verwendung von Abhängigkeiten in der Serverumgebung)
• DNSDumpster-Zielquelle hinzufügen
• Censys-Zielquelle hinzufügen
• Shodan-Zielquelle hinzufügen

Statusbehaftete Ausführungen

• Speichern des Ausführungsstatus hinzugefügt
  • Aufgelöste Zielliste
  • Arbeitende und beendete Worker

Unterstützung mehrerer Cloud-Anbieter

• AWS (EC2)-Provisioner hinzugefügt
• Google Cloud Platform (Compute Engine)-Provisioner hinzugefügt
• Azure (Virtual Machines)-Provisioner hinzugefügt
• DigitalOcean-Provisoner hinzugefügt

Erweiterte Pipeline-Stufentypen

• notify-Stufe hinzufügen – Senden von Benachrichtigungen oder Warnungen (Webhooks, E-Mail, Slack)
• conditional-Stufe hinzufügen – Stufen basierend auf Ergebnissen vorheriger Stufen ausführen
• parallel-Stufe hinzufügen – Mehrere Operationen gleichzeitig auf demselben Worker ausführen
• retry-Stufe hinzufügen – Automatische Wiederholung fehlgeschlagener Operationen mit konfigurierbarem Backoff
• timeout-Stufe hinzufügen – Ausführungszeitlimits pro Stufe festlegen
• validate-Stufe hinzufügen – Ergebnisse oder Bedingungen vor dem Fortfahren validieren

Daemon-Modus mit geplanter Ausführung

• Geplante Ausführung mit Cron-ähnlichen Ausdrücken implementieren
• Kontinuierlichen Überwachungsmodus für langlebige Prozesse hinzufügen
• Ereignisgesteuerte Trigger hinzufügen (Webhooks, externe Ereignisse)
• Ergebnis-Persistenz und Ausführungsverlauf verfolgen
• Integrierte Health-Checks und automatische Wiederherstellung hinzufügen

Alternative Ergebnis-Speichertypen

• Objektspeicher-Unterstützung hinzufügen (S3, GCS, Azure Blob Storage)
• Datenbank-Speicher-Unterstützung hinzufügen (PostgreSQL, MySQL, MongoDB)
• Nachrichtenwarteschlangen-Unterstützung hinzufügen (RabbitMQ, Kafka, Redis-Streams)
• API-Endpunkt-Integration hinzufügen (benutzerdefinierte HTTP-POST-Anfragen)
• E-Mail-Benachrichtigungsunterstützung mit Anhängen hinzufügen
• Cloud-Logging-Integration hinzufügen (CloudWatch, Stackdriver usw.)

Lizenz

MIT-Lizenz. Siehe die Datei LICENSE für Details.