ReconSwarm

ReconSwarm é um framework modular de automação de reconhecimento projetado para testes de segurança distribuídos. Ele provisiona infraestrutura em nuvem, executa pipelines de reconhecimento em paralelo e coleta resultados com sobrecarga mínima de configuração.

ReconSwarm é adequado para caçadores de recompensas de bugs, testadores de penetração, engenheiros DevSecOps e pesquisadores de segurança que precisam de fluxos de trabalho de reconhecimento escaláveis e automatizados, sem gerenciamento manual de infraestrutura.

Funcionalidades

• Divisão de alvos para execução paralela — A lista final de alvos compilados é dividida entre os workers para execução paralela das tarefas de reconhecimento
• Múltiplos tipos de alvo — A lista de alvos consiste em vários tipos de elementos: domínios da resposta do crt.sh, lista externa (URLs HTTP/HTTPS), lista simples (arrays YAML inline) e saída de comandos shell, sendo muito flexível para uso com qualquer ferramenta (cook, shodan, gau, katana, etc.)
• Arquitetura agnóstica de nuvem — Permite integração fácil com múltiplos provedores de nuvem (atualmente suporta AWS, GCP, Yandex Cloud e Digital Ocean)
• Estágios de pipeline flexíveis — Sistema de estágios extensível que atualmente suporta operações exec (execução de comandos) e sync (sincronização de arquivos e diretórios)
• Contexto de template nos passos — Forma flexível de passar metadados do contexto de execução para os passos

Funcionalidades obrigatórias a implementar

• Web UI — Uma interface web simples e amigável para interação rápida
• Logs em tempo real dos estágios — Capturar stdout/stderr e enviar ao cliente via streaming gRPC
• Shell remoto para os workers — Abrir conexão SSH do cliente para os workers através do servidor rs
• Estágio de descobertas — Um estágio para processar dados recebidos de estágios anteriores (ex.: resultado JSON do nuclei), armazená-los no etcd e gerar notificações

Arquitetura

ReconSwarm segue uma arquitetura modular com separação clara de responsabilidades entre provisionamento em nuvem, controle remoto de sistemas, execução de pipelines e gerenciamento de configuração.

Abstração de Provedor de Nuvem

ReconSwarm usa um padrão de união discriminada para provisionadores de nuvem. O campo provisioner.type determina qual configuração de provedor está ativa:

provisioner:
  type: yandex_cloud  # Campo discriminador
  yandex_cloud:       # Ativo quando type: yandex_cloud
    iam_token: "${YC_TOKEN}"
    # key_path: "./sa_auth_key.json"
    folder_id: "${YC_FOLDER_ID}"
    # ... configurações específicas do provedor

Provedores de nuvem adicionais podem ser integrados implementando a interface Provisioner e adicionando um novo tipo à fábrica.

Sistema de Estágios do Pipeline

Estágios são componentes extensíveis que executam operações nas VMs workers:

• exec — Executa comandos shell com suporte a templates
• sync — Copia arquivos ou diretórios das VMs remotas para a máquina local via SFTP (detecta automaticamente se é arquivo ou diretório)

Todos os campos dos estágios suportam renderização de templates. Novos tipos de estágio podem ser adicionados para estender a funcionalidade.

Servidor Stateless & Tolerância a Falhas

O servidor ReconSwarm é completamente stateless — todo o estado é persistido no etcd:

• Estado do pipeline — Status, progresso, erros de cada pipeline
• Estado do worker — Informações da VM, tarefa atual, status
• Chaves SSH — Pares de chaves gerados para acesso às VMs

Esta arquitetura permite:

Configuração de Alta Disponibilidade:

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

Todos os servidores compartilham o mesmo cluster etcd e podem lidar com qualquer requisição. Se um servidor falhar no meio de um pipeline, outro servidor pode continuar a execução após ler o estado do etcd.

Nota: A implementação atual executa pipelines em memória após carregar do etcd. A recuperação completa de falhas com retomada de pipeline está planejada para versões futuras.

Instalação

git clone <repositório>
cd reconswarm
go mod download
task build

Configuração

ReconSwarm separa a configuração do servidor da configuração do pipeline:

Configuração do Servidor

A configuração do servidor é armazenada em reconswarm.yaml (configurável via variável de ambiente CONFIG_PATH). Todos os valores de string suportam expansão de variáveis de ambiente usando a sintaxe ${VAR} ou $VAR.

# Configurações do servidor
server:
  port: 50051

# Conexão etcd para gerenciamento de estado
etcd:
  endpoints:
    - "localhost:2379"
  dial_timeout: 5  # segundos
  username: ""     # opcional, suporta ${ETCD_USER}
  password: ""     # opcional, suporta ${ETCD_PASSWORD}

# Provisionador de nuvem (união discriminada)
provisioner:
  type: yandex_cloud  # Seletor de provedor

  # Configuração Yandex Cloud (ativa 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

# Configurações do pool de workers
workers:
  max_workers: 5
  setup_commands:
    - "apt update"
    - "apt install -y docker.io"

Configuração do Pipeline

A configuração do pipeline é armazenada em um arquivo YAML separado e passada via flag -f. Ambos os formatos, encapsulado e não encapsulado, são suportados:

Formato encapsulado (recomendado):

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

Formato não encapsulado (também suportado):

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

Variáveis de Ambiente

Os valores de configuração suportam substituição de variáveis de ambiente em dois formatos:

• ${VAR} — Nome completo da variável entre chaves
• $VAR — Nome simples da variável

Se uma variável de ambiente não estiver definida, a string literal (incluindo ${VAR} ou $VAR) será utilizada.

Configuração do Yandex Cloud

Para integração com Yandex Cloud, use o script de configuração fornecido:

1. Instale a CLI do Yandex Cloud (se ainda não estiver instalada):

   root@kitploit:~

   # Siga a documentação oficial do Yandex Cloud para instalação da CLI
   

2. Configure a CLI do Yandex Cloud:

   root@kitploit:~

   yc config profile create <nome-do-perfil>
   yc config set cloud-id <seu-cloud-id>
   yc config set folder-id <seu-folder-id>
   

3. Exporte as credenciais:

   root@kitploit:~

   source ./secrets-setup.sh
   

   Este script exporta:

   • YC_TOKEN — Token IAM para autenticação
   • YC_FOLDER_ID — ID da pasta para gerenciamento de recursos
   • YC_CLOUD_ID — ID da nuvem (se necessário)

4. Referencie na configuração:

   root@kitploit:~

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

O script secrets-setup.sh gera automaticamente um novo token IAM a cada execução, garantindo autenticação segura sem codificar credenciais.

Configuração do Google Cloud Platform

1. Crie uma Conta de Serviço:

   • Vá para Console GCP > IAM & Admin > Service Accounts
   • Crie uma conta de serviço com papel "Compute Admin"
   • Crie uma chave JSON e faça o download

2. Configure o Ambiente:

   root@kitploit:~

   export GCP_PROJECT_ID="seu-project-id"
   export GCP_CREDENTIALS_PATH="/caminho/para/key.json"
   

3. Referencie na configuração:

   root@kitploit:~

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

Configuração da AWS

1. Crie um Usuário IAM:

   • Vá para Console AWS > IAM > Users
   • Crie um usuário com permissões "AmazonEC2FullAccess"
   • Gere uma Access Key ID e Secret Access Key

2. Configure o Ambiente:

   root@kitploit:~

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

3. Referencie na configuração:

   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"
   

Configuração do DigitalOcean

1. Gere um Token:

   • Vá para DigitalOcean Control Panel > API
   • Gere um Personal Access Token com escopo "Write"

2. Configure o Ambiente:

   root@kitploit:~

   export DO_TOKEN="seu-token"
   

3. Referencie na configuração:

   root@kitploit:~

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

Tipos de Alvo

Enumeração crt.sh:

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

Lista manual:

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

Configuração de Estágios

Todos os campos de configuração de estágios suportam sintaxe de template Go para geração dinâmica de valores. As variáveis do template são renderizadas no momento da execução com dados de contexto fornecidos automaticamente.

Contexto do Template

Os seguintes dados estão disponíveis em todos os templates de estágio:

Estágio exec — Executa comandos shell com suporte a templates:

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

Todos os comandos no array steps são renderizados com template antes da execução.

Estágio sync — Copia arquivos ou diretórios do remoto para o local usando SFTP. Detecta automaticamente se o caminho é arquivo ou diretório:

stages:
  - name: "Coletar resultados"
    type: sync
    src: "/opt/recon/results.json"
    dest: "./results/{{.Worker.Name}}.json"
  
  # Sincronizar diretório inteiro recursivamente
  - name: "Coletar todos os resultados"
    type: sync
    src: "/opt/recon"
    dest: "./results/{{.Worker.Name}}"

Tanto src (caminho remoto) quanto dest (caminho local) suportam renderização de template para caminhos de arquivos dinâmicos. O estágio sync detecta automaticamente se o caminho de origem é um arquivo ou diretório e lida adequadamente.

Uso

Modo Servidor

Inicie o servidor gRPC para aceitar submissões de pipeline:

reconswarm server

O servidor lê a configuração de reconswarm.yaml e escuta na porta configurada (padrão: 50051).

Submeter Pipeline via gRPC

Submeta um pipeline a um servidor em execução:

reconswarm run -f examples/pipelines/nuclei.yaml

Opções:

• -f, --pipeline — Caminho para o arquivo YAML do pipeline (obrigatório)
• -s, --server — Endereço do servidor (padrão: localhost:50051)

Verificar Status do Pipeline

reconswarm status <pipeline-id>

Execução Manual do Pipeline

Execute um pipeline diretamente sem o servidor gRPC (útil para testes):

reconswarm manual -f examples/pipelines/nuclei.yaml

Este comando:

1. Lê a configuração do servidor de reconswarm.yaml
2. Prepara os alvos (enumera subdomínios via crt.sh se necessário)
3. Cria VMs workers com base na configuração workers.max_workers
4. Distribui os alvos entre os workers
5. Executa comandos de configuração em cada VM
6. Executa os estágios do pipeline sequencialmente
7. Coleta os resultados através dos estágios sync
8. Desaloca automaticamente toda a infraestrutura após a conclusão

A desalocação automática de infraestrutura garante total autonomia — todos os recursos em nuvem são provisionados, usados e destruídos sem intervenção manual, permitindo fluxos de trabalho de reconhecimento totalmente automatizados.

Exemplos de Configuração

Para exemplos completos de pipeline, veja o diretório examples/pipelines.

Enumeração e varredura básica de subdomínios:

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

Execute com:

reconswarm manual -f pipeline.yaml
# ou submeta ao servidor:
reconswarm run -f pipeline.yaml

Múltiplos alvos com varredura baseada em Docker:

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

Toolchain personalizado com múltiplos estágios:

Config do 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"

Config do pipeline (pipeline.yaml):

pipeline:
  targets:
    - value: "example.com"
      type: crtsh
  stages:
    - name: "Enumeração adicional"
      type: exec
      steps:
        - "cd subfinder && ./subfinder -dL {{.Targets.filepath}} -o /opt/recon/subfinder-{{.Worker.Name}}.txt"
    - name: "Mesclar alvos"
      type: exec
      steps:
        - "cat {{.Targets.filepath}} /opt/recon/subfinder-{{.Worker.Name}}.txt | sort -u > /opt/recon/all-targets-{{.Worker.Name}}.txt"
    - name: "Escaneie alvos mesclados"
      type: exec
      steps:
        - "nmap -sC -sV -iL /opt/recon/all-targets-{{.Worker.Name}}.txt -oN /opt/recon/scan-{{.Worker.Name}}.txt"
    - name: "Coletar todos os resultados"
      type: sync
      src: "/opt/recon"
      dest: "./results/{{.Worker.Name}}"

Nota: O estágio sync detecta automaticamente que /opt/recon é um diretório e copia recursivamente todos os arquivos e subdiretórios para o destino local.

Outros Comandos

Enumeração de subdomínios:

reconswarm crtsh-dump example.com

Busca e filtra subdomínios resolvíveis do crt.sh para um domínio dado.

Comando de depuração (para testar provisionamento de VM):

reconswarm debug

Desenvolvimento

Compile e teste usando Task:

task build      # Compilar binário
task test       # Executar testes
task lint       # Executar linter
task vet        # Executar go vet
task ci         # Executar todas as verificações de CI

TODO

Fontes de Alvo Adicionais

• Adicionar passagem de alvos a partir da avaliação de shell (para usar cook, radamsa ou literalmente todas as ferramentas disponíveis):
  • Avaliar alvos no cliente e passar via chamada gRPC (sobrecarga de rede para entradas grandes)
  • Avaliar no servidor (necessário usar dependências no ambiente do servidor)
• Adicionar fonte de alvo DNSDumpster
• Adicionar fonte de alvo Censys
• Adicionar fonte de alvo Shodan

Execuções com Estado

• Adicionar salvamento do estado da execução
  • Lista de alvos resolvidos
  • Workers ativos e finalizados

Suporte a Múltiplos Provedores de Nuvem

• Adicionar provisionador AWS (EC2)
• Adicionar provisionador Google Cloud Platform (Compute Engine)
• Adicionar provisionador Azure (Virtual Machines)
• Adicionar provisionador DigitalOcean

Tipos de Estágio de Pipeline Estendidos

• Adicionar estágio notify — Enviar notificações ou alertas (webhooks, e-mail, Slack)
• Adicionar estágio conditional — Executar estágios com base nos resultados de estágios anteriores
• Adicionar estágio parallel — Executar múltiplas operações simultaneamente no mesmo worker
• Adicionar estágio retry — Reexecutar automaticamente operações com falha com backoff configurável
• Adicionar estágio timeout — Definir timeouts de execução por estágio
• Adicionar estágio validate — Validar resultados ou condições antes de prosseguir

Modo Daemon com Execução Agendada

• Implementar execução agendada com expressões estilo cron
• Adicionar modo de monitoramento contínuo para processos de longa duração
• Adicionar triggers orientados a eventos (webhooks, eventos externos)
• Implementar persistência de resultados e histórico de execução
• Adicionar verificações de saúde embutidas e recuperação automática

Tipos Alternativos de Armazenamento de Resultados

• Adicionar suporte a armazenamento de objetos (S3, GCS, Azure Blob Storage)
• Adicionar suporte a armazenamento em banco de dados (PostgreSQL, MySQL, MongoDB)
• Adicionar suporte a fila de mensagens (RabbitMQ, Kafka, Redis streams)
• Adicionar integração com endpoint de API (HTTP POST personalizado)
• Adicionar suporte a notificação por e-mail com anexos
• Adicionar integração com logs em nuvem (CloudWatch, Stackdriver, etc.)

Licença

Licença MIT. Consulte o arquivo LICENSE para detalhes.