ReconSwarm

ReconSwarm es un framework modular de automatización de reconocimiento diseñado para pruebas de seguridad distribuidas. Aprovisiona infraestructura en la nube, ejecuta pipelines de reconocimiento en paralelo y recopila resultados con una configuración mínima.

ReconSwarm es adecuado para cazadores de recompensas, testers de penetración, ingenieros DevSecOps e investigadores de seguridad que necesitan flujos de trabajo de reconocimiento escalables y automatizados sin gestión manual de infraestructura.

Características

• Dividir objetivos para ejecución paralela — La lista final de objetivos compilados se divide entre los workers para la ejecución paralela de tareas de reconocimiento.
• Múltiples tipos de objetivo — La lista de objetivos consta de varios tipos de elementos: dominios de la respuesta de crt.sh, lista externa (URLs HTTP/HTTPS), lista simple (arrays YAML en línea) y salida de comandos de shell, lo cual es muy flexible para usar con cualquier herramienta (cook, shodan, gau, katana, etc.).
• Arquitectura agnóstica de la nube — Permite una fácil integración con múltiples proveedores de nube (actualmente compatible con AWS, GCP, Yandex Cloud y DigitalOcean).
• Etapas de pipeline flexibles — Sistema de etapas extensible que actualmente soporta operaciones exec (ejecución de comandos) y sync (sincronización de archivos y directorios).
• Contexto de plantilla en los pasos — Forma flexible de pasar metadatos del contexto de ejecución a los pasos.

Características imprescindibles por implementar

• Interfaz web — Una interfaz web simple y fácil de usar para una iteración rápida.
• Registros en tiempo real desde las etapas — Capturar stdout/stderr y enviarlos al cliente mediante streaming gRPC.
• Shell remoto a los workers — Abrir conexión SSH desde el cliente a los workers a través del servidor RS.
• Etapa de hallazgos — Una etapa para procesar datos recibidos de la etapa anterior (ej. resultado JSON de nuclei), almacenarlos en etcd y generar notificaciones.

Arquitectura

ReconSwarm sigue una arquitectura modular con una clara separación de responsabilidades entre el aprovisionamiento en la nube, el control remoto del sistema, la ejecución del pipeline y la gestión de la configuración.

Abstracción del Proveedor de Nube

ReconSwarm utiliza un patrón de unión discriminada para los aprovisionadores de nube. El campo provisioner.type determina qué configuración de proveedor está activa:

provisioner:
  type: yandex_cloud  # Campo discriminador
  yandex_cloud:       # Activo cuando type: yandex_cloud
    iam_token: "${YC_TOKEN}"
    # key_path: "./sa_auth_key.json"
    folder_id: "${YC_FOLDER_ID}"
    # ... configuraciones específicas del proveedor

Se pueden integrar proveedores de nube adicionales implementando la interfaz Provisioner y agregando un nuevo tipo a la fábrica.

Sistema de Etapas del Pipeline

Las etapas son componentes extensibles que ejecutan operaciones en las máquinas virtuales worker:

• exec — Ejecuta comandos de shell con soporte de plantillas.
• sync — Copia archivos o directorios desde máquinas virtuales remotas a la máquina local mediante SFTP (detecta automáticamente si es archivo o directorio).

Todos los campos de las etapas admiten renderizado de plantillas. Se pueden agregar nuevos tipos de etapas para extender la funcionalidad.

Servidor sin Estado y Tolerancia a Fallos

El servidor de ReconSwarm es completamente stateless — todo el estado se persiste en etcd:

• Estado del pipeline — Estado, progreso, errores de cada pipeline.
• Estado del worker — Información de la VM, tarea actual, estado.
• Claves SSH — Pares de claves generados para acceso a las VMs.

Esta arquitectura permite:

Configuración de Alta Disponibilidad:

                    ┌─────────────┐
                    │   Cliente   │
                    └──────┬──────┘
                           │
                    ┌──────▼──────┐
                    │Balanceador  │
                    │   de Carga  │
                    └──────┬──────┘
              ┌────────────┼────────────┐
              │            │            │
       ┌──────▼──────┐ ┌───▼───┐ ┌──────▼──────┐
       │  Servidor 1 │ │ Serv2 │ │  Servidor 3 │
       └──────┬──────┘ └───┬───┘ └──────┬──────┘
              │            │            │
              └────────────┼────────────┘
                           │
                    ┌──────▼──────┐
                    │ etcd cluster│
                    └─────────────┘

Todos los servidores comparten el mismo clúster etcd y pueden manejar cualquier solicitud. Si un servidor falla en medio de un pipeline, otro servidor puede continuar la ejecución después de leer el estado desde etcd.

Nota: La implementación actual ejecuta los pipelines en memoria después de cargarlos desde etcd. La recuperación completa ante fallos con reanudación del pipeline está planificada para versiones futuras.

Instalación

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

Configuración

ReconSwarm separa la configuración del servidor de la configuración del pipeline:

Configuración del Servidor

La configuración del servidor se almacena en reconswarm.yaml (configurable mediante la variable de entorno CONFIG_PATH). Todos los valores de cadena admiten expansión de variables de entorno utilizando la sintaxis ${VAR} o $VAR.

# Configuración del servidor
server:
  port: 50051

# Conexión a etcd para gestión de estado
etcd:
  endpoints:
    - "localhost:2379"
  dial_timeout: 5  # segundos
  username: ""     # opcional, soporta ${ETCD_USER}
  password: ""     # opcional, soporta ${ETCD_PASSWORD}

# Aprovisionador de nube (unión discriminada)
provisioner:
  type: yandex_cloud  # Selector de proveedor

  # Configuración de Yandex Cloud (activa cuando 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

# Configuración del pool de workers
workers:
  max_workers: 5
  setup_commands:
    - "apt update"
    - "apt install -y docker.io"

Configuración del Pipeline

La configuración del pipeline se almacena en un archivo YAML separado y se pasa mediante la bandera -f. Se admiten tanto el formato envuelto como el no envuelto:

Formato envuelto (recomendado):

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

Formato no envuelto (también compatible):

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

Variables de Entorno

Los valores de configuración admiten sustitución de variables de entorno en dos formatos:

• ${VAR} — Nombre completo de la variable entre llaves.
• $VAR — Nombre simple de la variable.

Si una variable de entorno no está definida, se utilizará la cadena literal (incluyendo ${VAR} o $VAR).

Configuración de Yandex Cloud

Para la integración con Yandex Cloud, use el script de configuración proporcionado:

1. Instalar Yandex Cloud CLI (si aún no está instalado):

   root@kitploit:~

   # Siga la documentación oficial de Yandex Cloud para la instalación de la CLI
   

2. Configurar Yandex Cloud CLI:

   root@kitploit:~

   yc config profile create <nombre-perfil>
   yc config set cloud-id <su-cloud-id>
   yc config set folder-id <su-folder-id>
   

3. Exportar credenciales:

   root@kitploit:~

   source ./secrets-setup.sh
   

   Este script exporta:

   • YC_TOKEN — Token IAM para autenticación.
   • YC_FOLDER_ID — ID de la carpeta para la gestión de recursos.
   • YC_CLOUD_ID — ID de la nube (si es necesario).

4. Referencia en la configuración:

   root@kitploit:~

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

El script secrets-setup.sh genera automáticamente un nuevo token IAM cada vez que se ejecuta, garantizando una autenticación segura sin codificar las credenciales.

Configuración de Google Cloud Platform

1. Crear una Cuenta de Servicio:

   • Vaya a la consola de GCP > IAM y Administración > Cuentas de servicio.
   • Cree una cuenta de servicio con el rol "Administrador de Compute".
   • Cree una clave JSON y descárguela.

2. Configurar el Entorno:

   root@kitploit:~

   export GCP_PROJECT_ID="su-project-id"
   export GCP_CREDENTIALS_PATH="/ruta/a/key.json"
   

3. Referencia en la configuración:

   root@kitploit:~

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

Configuración de AWS

1. Crear un Usuario IAM:

   • Vaya a la consola de AWS > IAM > Usuarios.
   • Cree un usuario con permisos "AmazonEC2FullAccess".
   • Genere un Access Key ID y Secret Access Key.

2. Configurar el Entorno:

   root@kitploit:~

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

3. Referencia en la configuración:

   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"
   

Configuración de DigitalOcean

1. Generar un Token:

   • Vaya al Panel de Control de DigitalOcean > API.
   • Genere un Token de Acceso Personal con alcance de "Escritura".

2. Configurar el Entorno:

   root@kitploit:~

   export DO_TOKEN="su-token"
   

3. Referencia en la configuración:

   root@kitploit:~

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

Tipos de Objetivo

Enumeración de crt.sh:

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

Lista manual:

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

Configuración de Etapas

Todos los campos de configuración de las etapas admiten sintaxis de plantillas Go para la generación dinámica de valores. Las variables de plantilla se renderizan en el momento de la ejecución con datos de contexto proporcionados automáticamente.

Contexto de la Plantilla

Los siguientes datos están disponibles en todas las plantillas de etapa:

Etapa exec — Ejecuta comandos de shell con soporte de plantillas:

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

Todos los comandos en el array steps se renderizan mediante plantillas antes de la ejecución.

Etapa sync — Copia archivos o directorios desde remoto a local usando SFTP. Detecta automáticamente si la ruta es un archivo o directorio:

stages:
  - name: "Recopilar resultados"
    type: sync
    src: "/opt/recon/results.json"
    dest: "./results/{{.Worker.Name}}.json"
  
  # Sincronizar directorio completo recursivamente
  - name: "Recopilar todos los resultados"
    type: sync
    src: "/opt/recon"
    dest: "./results/{{.Worker.Name}}"

Tanto src (ruta remota) como dest (ruta local) admiten renderizado de plantillas para rutas de archivo dinámicas. La etapa sync detecta automáticamente si la ruta de origen es un archivo o directorio y lo maneja en consecuencia.

Uso

Modo Servidor

Inicie el servidor gRPC para aceptar envíos de pipelines:

reconswarm server

El servidor lee la configuración de reconswarm.yaml y escucha en el puerto configurado (por defecto: 50051).

Enviar Pipeline mediante gRPC

Envíe un pipeline a un servidor en ejecución:

reconswarm run -f examples/pipelines/nuclei.yaml

Opciones:

• -f, --pipeline — Ruta al archivo YAML del pipeline (obligatorio).
• -s, --server — Dirección del servidor (por defecto: localhost:50051).

Consultar Estado del Pipeline

reconswarm status <pipeline-id>

Ejecución Manual del Pipeline

Ejecute un pipeline directamente sin el servidor gRPC (útil para pruebas):

reconswarm manual -f examples/pipelines/nuclei.yaml

Este comando:

1. Lee la configuración del servidor desde reconswarm.yaml.
2. Prepara los objetivos (enumera subdominios mediante crt.sh si es necesario).
3. Crea VMs worker según la configuración workers.max_workers.
4. Distribuye los objetivos entre los workers.
5. Ejecuta los comandos de configuración en cada VM.
6. Ejecuta las etapas del pipeline secuencialmente.
7. Recopila los resultados mediante etapas sync.
8. Desasigna automáticamente toda la infraestructura al finalizar.

La desasignación automática de infraestructura garantiza una autonomía completa: todos los recursos en la nube se aprovisionan, utilizan y destruyen sin intervención manual, permitiendo flujos de trabajo de reconocimiento totalmente automatizados.

Ejemplos de Configuración

Para ejemplos completos de pipelines, consulte el directorio examples/pipelines.

Enumeración y escaneo básico de subdominios:

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

Ejecutar con:

reconswarm manual -f pipeline.yaml
# o enviar al servidor:
reconswarm run -f pipeline.yaml

Múltiples objetivos con escaneo basado en Docker:

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

Cadena de herramientas personalizada con múltiples etapas:

Configuración del servidor (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"

Configuración del pipeline (pipeline.yaml):

pipeline:
  targets:
    - value: "example.com"
      type: crtsh
  stages:
    - name: "Enumeración adicional"
      type: exec
      steps:
        - "cd subfinder && ./subfinder -dL {{.Targets.filepath}} -o /opt/recon/subfinder-{{.Worker.Name}}.txt"
    - name: "Fusionar objetivos"
      type: exec
      steps:
        - "cat {{.Targets.filepath}} /opt/recon/subfinder-{{.Worker.Name}}.txt | sort -u > /opt/recon/all-targets-{{.Worker.Name}}.txt"
    - name: "Escaneo de objetivos fusionados"
      type: exec
      steps:
        - "nmap -sC -sV -iL /opt/recon/all-targets-{{.Worker.Name}}.txt -oN /opt/recon/scan-{{.Worker.Name}}.txt"
    - name: "Recopilar todos los resultados"
      type: sync
      src: "/opt/recon"
      dest: "./results/{{.Worker.Name}}"

Nota: La etapa sync detecta automáticamente que /opt/recon es un directorio y copia recursivamente todos los archivos y subdirectorios al destino local.

Otros Comandos

Enumeración de subdominios:

reconswarm crtsh-dump example.com

Obtiene y filtra subdominios resolubles de crt.sh para un dominio dado.

Comando de depuración (para probar el aprovisionamiento de VMs):

reconswarm debug

Desarrollo

Compile y pruebe usando Task:

task build      # Compilar binario
task test       # Ejecutar pruebas
task lint       # Ejecutar linter
task vet        # Ejecutar go vet
task ci         # Ejecutar todas las comprobaciones de CI

TODO

Fuentes de Objetivos Adicionales

• Agregar paso de objetivos desde la evaluación de shell (para usar cook, radamsa o cualquier herramienta disponible):
  • Evaluar objetivos en el cliente y pasarlos mediante llamada gRPC (sobrecarga de red en entradas grandes)
  • Evaluar en el servidor (necesita usar dependencias en el entorno del servidor)
• Agregar fuente de objetivos DNSDumpster
• Agregar fuente de objetivos Censys
• Agregar fuente de objetivos Shodan

Ejecuciones con Estado

• Agregar guardado del estado de la ejecución
  • Lista de objetivos resueltos
  • Workers en funcionamiento y finalizados

Soporte de Múltiples Proveedores de Nube

• Agregar aprovisionador AWS (EC2)
• Agregar aprovisionador Google Cloud Platform (Compute Engine)
• Agregar aprovisionador Azure (Virtual Machines)
• Agregar aprovisionador DigitalOcean

Tipos de Etapas de Pipeline Extendidos

• Agregar etapa notify — Enviar notificaciones o alertas (webhooks, correo electrónico, Slack)
• Agregar etapa conditional — Ejecutar etapas según resultados de etapas anteriores
• Agregar etapa parallel — Ejecutar múltiples operaciones concurrentemente en el mismo worker
• Agregar etapa retry — Reintentar automáticamente operaciones fallidas con retroceso configurable
• Agregar etapa timeout — Establecer tiempos de espera de ejecución por etapa
• Agregar etapa validate — Validar resultados o condiciones antes de continuar

Modo Daemon con Ejecución Programada

• Implementar ejecución programada con expresiones similares a cron
• Agregar modo de monitoreo continuo para procesos de larga duración
• Agregar desencadenadores basados en eventos (webhooks, eventos externos)
• Implementar persistencia de resultados y seguimiento del historial de ejecución
• Agregar comprobaciones de salud integradas y recuperación automática

Tipos de Almacenamiento de Resultados Alternativos

• Agregar soporte de almacenamiento de objetos (S3, GCS, Azure Blob Storage)
• Agregar soporte de almacenamiento en base de datos (PostgreSQL, MySQL, MongoDB)
• Agregar soporte de cola de mensajes (RabbitMQ, Kafka, Redis streams)
• Agregar integración de endpoint API (HTTP POST personalizado)
• Agregar soporte de notificación por correo electrónico con archivos adjuntos
• Agregar integración de registro en la nube (CloudWatch, Stackdriver, etc.)

Licencia

Licencia MIT. Consulte el archivo LICENSE para más detalles.