ReconSwarm

ReconSwarm — это модульная среда автоматизации разведки, предназначенная для распределённого тестирования безопасности. Она предоставляет облачную инфраструктуру, выполняет параллельные конвейеры разведки и собирает результаты с минимальными затратами на настройку.

ReconSwarm подходит для охотников за багами (bug bounty), пентестеров, DevSecOps-инженеров и исследователей безопасности, которым нужны масштабируемые автоматизированные рабочие процессы разведки без ручного управления инфраструктурой.

Возможности

• Разделение целей для параллельного выполнения — итоговый скомпилированный список целей распределяется между воркерами для параллельного выполнения задач разведки
• Несколько типов целей — список целей состоит из нескольких типов элементов: домены из ответа crt.sh, внешний список (HTTP/HTTPS URL), простой список (встроенные YAML-массивы) и вывод shell-команд, что очень гибко для использования с любыми инструментами (cook, shodan, gau, katana и т. д.).
• Облачно-агностическая архитектура — позволяет легко интегрироваться с несколькими облачными провайдерами (в настоящее время поддерживаются AWS, GCP, Yandex Cloud и Digital Ocean)
• Гибкие стадии конвейера — расширяемая система стадий, поддерживающая операции exec (выполнение команд) и sync (синхронизация файлов и каталогов)
• Шаблонный контекст в шагах — гибкий способ передачи метаданных из контекста выполнения в шаги

Ключевые функции, которые предстоит реализовать

• Веб-интерфейс — простой веб-интерфейс, удобный для быстрого взаимодействия
• Логи стадий в реальном времени — захват stdout/stderr и отправка клиенту через gRPC-стриминг
• Удалённый shell до воркеров — открытие SSH-подключения от клиента к воркерам через rs-сервер
• Стадия находок (findings) — стадия для обработки данных, полученных с предыдущей стадии (например, JSON-результат nuclei), сохранения их в etcd и отправки уведомлений

Архитектура

ReconSwarm следует модульной архитектуре с чётким разделением ответственности между предоставлением облачных ресурсов, удалённым управлением системой, выполнением конвейера и управлением конфигурацией.

Абстракция облачного провайдера

ReconSwarm использует шаблон дискриминируемого объединения для облачных провижинеров. Поле provisioner.type определяет, какая конфигурация провайдера активна:

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

Дополнительные облачные провайдеры можно интегрировать, реализовав интерфейс Provisioner и добавив новый тип в фабрику.

Система стадий конвейера

Стадии — это расширяемые компоненты, выполняющие операции на виртуальных машинах воркеров:

• exec — выполняет shell-команды с поддержкой шаблонов
• sync — копирует файлы или каталоги с удалённых ВМ на локальную машину через SFTP (автоматически определяет, файл это или каталог)

Все поля стадий поддерживают рендеринг шаблонов. Для расширения функциональности можно добавлять новые типы стадий.

Сервер без состояния и отказоустойчивость

Сервер ReconSwarm полностью не хранит состояние (stateless) — всё состояние сохраняется в etcd:

• Состояние конвейера — статус, прогресс, ошибки для каждого конвейера
• Состояние воркера — информация о ВМ, текущая задача, статус
• SSH-ключи — сгенерированные пары ключей для доступа к ВМ

Эта архитектура обеспечивает:

Настройка высокой доступности:

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

Все серверы используют один и тот же кластер etcd и могут обрабатывать любой запрос. Если сервер упадёт в середине конвейера, другой сервер сможет продолжить выполнение после чтения состояния из etcd.

Примечание: В текущей реализации конвейеры выполняются в памяти после загрузки из etcd. Полное восстановление после сбоя с возобновлением конвейера запланировано в будущих релизах.

Установка

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

Конфигурация

ReconSwarm разделяет конфигурацию сервера и конфигурацию конвейера:

Конфигурация сервера

Конфигурация сервера хранится в reconswarm.yaml (настраивается через переменную окружения CONFIG_PATH). Все строковые значения поддерживают подстановку переменных окружения в синтаксисе ${VAR} или $VAR.

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

Конфигурация конвейера

Конфигурация конвейера хранится в отдельном YAML-файле и передаётся через флаг -f. Поддерживаются оба формата — с обёрткой и без:

Формат с обёрткой (рекомендуется):

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

Формат без обёртки (тоже поддерживается):

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

Переменные окружения

Значения конфигурации поддерживают подстановку переменных окружения в двух форматах:

• ${VAR} — полное имя переменной в фигурных скобках
• $VAR — простое имя переменной

Если переменная окружения не установлена, будет использована буквальная строка (включая ${VAR} или $VAR).

Настройка Yandex Cloud

Для интеграции с Yandex Cloud используйте предоставленный скрипт настройки:

1. Установите Yandex Cloud CLI (если ещё не установлен):

   root@kitploit:~

   # Follow official Yandex Cloud documentation for CLI installation
   

2. Настройте Yandex Cloud CLI:

   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. Экспортируйте учётные данные:

   root@kitploit:~

   source ./secrets-setup.sh
   

   Этот скрипт экспортирует:

   • YC_TOKEN — IAM-токен для аутентификации
   • YC_FOLDER_ID — идентификатор каталога для управления ресурсами
   • YC_CLOUD_ID — идентификатор облака (при необходимости)

4. Укажите в конфигурации:

   root@kitploit:~

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

Скрипт secrets-setup.sh автоматически генерирует свежий IAM-токен при каждом запуске, обеспечивая безопасную аутентификацию без захардкоженных учётных данных.

Настройка Google Cloud Platform

1. Создайте сервисный аккаунт:

   • Перейдите в GCP Console > IAM & Admin > Service Accounts
   • Создайте сервисный аккаунт с ролью "Compute Admin"
   • Создайте JSON-ключ и скачайте его

2. Настройте окружение:

   root@kitploit:~

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

3. Укажите в конфигурации:

   root@kitploit:~

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

Настройка AWS

1. Создайте IAM-пользователя:

   • Перейдите в AWS Console > IAM > Users
   • Создайте пользователя с разрешениями "AmazonEC2FullAccess"
   • Сгенерируйте Access Key ID и Secret Access Key

2. Настройте окружение:

   root@kitploit:~

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

3. Укажите в конфигурации:

   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

1. Сгенерируйте токен:

   • Перейдите в DigitalOcean Control Panel > API
   • Сгенерируйте Personal Access Token с областью "Write"

2. Настройте окружение:

   root@kitploit:~

   export DO_TOKEN="your-token"
   

3. Укажите в конфигурации:

   root@kitploit:~

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

Типы целей

Перечисление через crt.sh:

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

Ручной список:

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

Конфигурация стадий

Все поля конфигурации стадий поддерживают синтаксис Go-шаблонов для динамической генерации значений. Переменные шаблонов рендерятся во время выполнения с автоматически предоставляемыми данными контекста.

Контекст шаблона

В шаблонах всех стадий доступны следующие данные:

Стадия exec — выполняет shell-команды с поддержкой шаблонов:

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

Все команды в массиве steps перед выполнением проходят рендеринг шаблонов.

Стадия sync — копирует файлы или каталоги с удалённой машины на локальную через SFTP. Автоматически определяет, является ли путь файлом или каталогом:

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

И src (удалённый путь), и dest (локальный путь) поддерживают рендеринг шаблонов для динамических путей к файлам. Стадия sync автоматически определяет, является ли исходный путь файлом или каталогом, и обрабатывает его соответствующим образом.

Использование

Режим сервера

Запустите gRPC-сервер для приёма конвейеров:

reconswarm server

Сервер читает конфигурацию из reconswarm.yaml и слушает настроенный порт (по умолчанию: 50051).

Отправка конвейера через gRPC

Отправьте конвейер на запущенный сервер:

reconswarm run -f examples/pipelines/nuclei.yaml

Параметры:

• -f, --pipeline — путь к YAML-файлу конвейера (обязательно)
• -s, --server — адрес сервера (по умолчанию: localhost:50051)

Проверка статуса конвейера

reconswarm status <pipeline-id>

Ручное выполнение конвейера

Выполните конвейер напрямую без gRPC-сервера (полезно для тестирования):

reconswarm manual -f examples/pipelines/nuclei.yaml

Эта команда:

1. Читает конфигурацию сервера из reconswarm.yaml
2. Подготавливает цели (при необходимости перечисляет поддомены через crt.sh)
3. Создаёт ВМ воркеров на основе конфигурации workers.max_workers
4. Распределяет цели между воркерами
5. Выполняет команды настройки на каждой ВМ
6. Запускает стадии конвейера последовательно
7. Собирает результаты через стадии sync
8. Автоматически освобождает всю инфраструктуру после завершения

Автоматическое освобождение инфраструктуры обеспечивает полную автономность — все облачные ресурсы предоставляются, используются и уничтожаются без ручного вмешательства, что позволяет полностью автоматизировать рабочие процессы разведки.

Примеры конфигураций

Полные примеры конвейеров см. в каталоге examples/pipelines.

Базовое перечисление поддоменов и сканирование:

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

Запуск:

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

Несколько целей со сканированием на основе Docker:

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"

Пользовательский инструментарий с несколькими стадиями:

Конфигурация сервера (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.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}}"

Примечание: стадия sync автоматически определяет, что /opt/recon является каталогом, и рекурсивно копирует все файлы и подкаталоги в локальный каталог назначения.

Прочие команды

Перечисление поддоменов:

reconswarm crtsh-dump example.com

Получает и фильтрует резолвящиеся поддомены из crt.sh для заданного домена.

Команда debug (для тестирования предоставления ВМ):

reconswarm debug

Разработка

Сборка и тестирование с помощью Task:

task build      # Build binary
task test       # Run tests
task lint       # Run linter
task vet        # Run go vet
task ci         # Run all CI checks

TODO

Дополнительные источники целей

• Добавить передачу целей из результата выполнения shell (для использования cook, radamsa или вообще всех доступных инструментов):
  • вычисление целей на клиенте и передача через gRPC-вызов (создаёт сетевые накладные расходы на больших входных данных)
  • вычисление на сервере (требует использования зависимостей в окружении сервера)
• Добавить источник целей DNSDumpster
• Добавить источник целей Censys
• Добавить источник целей Shodan

Выполнения с сохранением состояния

• Добавить сохранение состояния выполнения
  • Итоговый список целей
  • Работающие и завершившиеся воркеры

Поддержка нескольких облачных провайдеров

• Добавить провижинер AWS (EC2)
• Добавить провижинер Google Cloud Platform (Compute Engine)
• Добавить провижинер Azure (Virtual Machines)
• Добавить провижинер DigitalOcean

Расширенные типы стадий конвейера

• Добавить стадию notify — отправка уведомлений или оповещений (webhooks, email, Slack)
• Добавить стадию conditional — выполнение стадий на основе результатов предыдущих стадий
• Добавить стадию parallel — параллельное выполнение нескольких операций на одном воркере
• Добавить стадию retry — автоматический повтор неудачных операций с настраиваемой задержкой (backoff)
• Добавить стадию timeout — установка таймаутов выполнения для каждой стадии
• Добавить стадию validate — проверка результатов или условий перед продолжением

Режим демона с запланированным выполнением

• Реализовать запланированное выполнение с cron-подобными выражениями
• Добавить режим непрерывного мониторинга для длительных процессов
• Добавить событийные триггеры (webhooks, внешние события)
• Реализовать сохранение результатов и отслеживание истории выполнения
• Добавить встроенные проверки работоспособности и автоматическое восстановление

Альтернативные типы хранения результатов

• Добавить поддержку объектного хранилища (S3, GCS, Azure Blob Storage)
• Добавить поддержку хранения в базах данных (PostgreSQL, MySQL, MongoDB)
• Добавить поддержку очередей сообщений (RabbitMQ, Kafka, Redis streams)
• Добавить интеграцию с API-эндпоинтом (кастомный HTTP POST)
• Добавить поддержку email-уведомлений с вложениями
• Добавить интеграцию с облачным логированием (CloudWatch, Stackdriver и т. д.)

Лицензия

Лицензия MIT. Подробности см. в файле LICENSE.