ReconSwarm

ReconSwarm 是一个模块化侦察自动化框架，专为分布式安全测试而设计。它能够部署云基础设施、执行并行侦察流水线，并以极低的配置开销收集结果。

ReconSwarm 适用于漏洞赏金猎人、渗透测试人员、DevSecOps 工程师和安全研究人员，他们需要可扩展的自动化侦察工作流，而无需手动管理基础设施。

Features

• 划分目标以并行执行 — 最终编译完成的目标列表会被划分给多个 worker，以并行执行侦察任务
• 多种目标类型 — 目标列表由多种元素类型组成：来自 crt.sh 响应的域名、外部列表（HTTP/HTTPS URL）、简单列表（内联 YAML 数组）以及 shell 命令输出，可非常灵活地与任何工具配合使用（cook、shodan、gau、katana 等）。
• 云无关架构 — 可轻松集成多个云提供商（目前支持 AWS、GCP、Yandex Cloud 和 Digital Ocean）
• 灵活的流水线阶段 — 可扩展的阶段系统，目前支持 exec（命令执行）和 sync（文件和目录同步）操作
• 步骤中的模板上下文 — 一种灵活的方式，可将元数据从执行上下文传递给各个步骤

待实现的必要功能

• Web UI - 一个基于 Web 的简单易用界面，用于快速交互
• 阶段的实时日志 - 捕获 stdout/stderr 并通过 grpc 流式传输发送给客户端
• 远程 shell 到 worker - 客户端通过 rs server 与 worker 建立 ssh 连接
• Findings 阶段 - 用于处理上一阶段（例如 nuclei json 结果）接收到的数据、将其存入 etcd 并发送通知的阶段

Architecture

ReconSwarm 采用模块化架构，在云资源部署、远程系统控制、流水线执行和配置管理之间实现了清晰的关注点分离。

Cloud Provider Abstraction

ReconSwarm 对云 provisioner 使用可判别联合模式。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 接口并向工厂添加新类型，即可集成其他云提供商。

Pipeline Stage System

阶段是在 worker VM 上执行操作的可扩展组件：

• exec — 执行支持模板的 shell 命令
• sync — 通过 SFTP 将文件或目录从远程 VM 复制到本地机器（自动识别文件或目录）

所有阶段字段都支持模板渲染。可以添加新的阶段类型来扩展功能。

Stateless Server & Fault Tolerance

ReconSwarm server 是完全无状态的——所有状态都持久化在 etcd 中：

• 流水线状态 — 每个流水线的状态、进度、错误
• Worker 状态 — VM 信息、当前任务、状态
• SSH 密钥 — 用于 VM 访问的已生成密钥对

该架构支持：

高可用性设置：

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

所有 server 共享同一个 etcd 集群，可以处理任何请求。如果某个 server 在流水线执行中途崩溃，另一个 server 可以在从 etcd 读取状态后继续执行。

注意： 当前实现会在从 etcd 加载后于内存中执行流水线。支持流水线恢复的完整崩溃恢复功能计划在未来的版本中实现。

Installation

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

Configuration

ReconSwarm 将 server 配置和流水线配置分开：

Server Configuration

Server 配置存储在 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"

Pipeline Configuration

流水线配置存储在单独的 YAML 文件中，并通过 -f 标志传入。支持包装（wrapped）和非包装（unwrapped）两种格式：

包装格式（推荐）：

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

Environment Variables

配置值支持两种格式的环境变量替换：

• ${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 token
   • YC_FOLDER_ID — 用于资源管理的 Folder ID
   • YC_CLOUD_ID — 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 token，确保安全认证，无需在代码中硬编码凭据。

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. 生成 Token：

   • 转到 DigitalOcean Control Panel > API
   • 生成具有 "Write" 范围的 Personal Access Token

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 阶段会自动检测源路径是文件还是目录，并进行相应处理。

用法

Server 模式

启动 gRPC server 以接收流水线提交：

reconswarm server

server 从 reconswarm.yaml 读取配置，并在配置的端口（默认：50051）上监听。

通过 gRPC 提交流水线

向正在运行的 server 提交流水线：

reconswarm run -f examples/pipelines/nuclei.yaml

选项：

• -f, --pipeline — 流水线 YAML 文件的路径（必需）
• -s, --server — Server 地址（默认：localhost:50051）

检查流水线状态

reconswarm status <pipeline-id>

手动执行流水线

不通过 gRPC server 直接执行流水线（对测试很有用）：

reconswarm manual -f examples/pipelines/nuclei.yaml

该命令：

1. 从 reconswarm.yaml 读取 server 配置
2. 准备目标（如有需要，通过 crt.sh 枚举子域名）
3. 根据 workers.max_workers 配置创建 worker VM
4. 在 worker 之间分发目标
5. 在每个 VM 上执行设置命令
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"

具有多个阶段的自定义工具链：

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"

流水线配置（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 命令（用于测试 VM 配置）：

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

待办事项

其他目标源

• 添加通过执行 shell 来传递目标的功能（用于使用 cook、radamsa 或其他任何可用工具）：
  • 在客户端评估目标并通过 grpc 调用传递（大数据输入时网络开销大）
  • 在服务器端评估（需要在服务器环境中使用依赖项）
• 添加 DNSDumpster 目标源
• 添加 Censys 目标源
• 添加 Shodan 目标源

有状态运行

• 添加运行状态的保存
  • 已解析的目标列表
  • 正在运行和已结束的 worker

多云提供商支持

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

扩展流水线阶段类型

• 添加 notify 阶段 — 发送通知或警报（webhooks、电子邮件、Slack）
• 添加 conditional 阶段 — 根据上一阶段的结果执行阶段
• 添加 parallel 阶段 — 在同一 worker 上并发执行多个操作
• 添加 retry 阶段 — 自动重试失败的操作，并支持可配置的回退
• 添加 timeout 阶段 — 为每个阶段设置执行超时
• 添加 validate 阶段 — 在继续之前验证结果或条件

带计划执行的守护进程模式

• 实现使用类似 cron 表达式的计划执行
• 添加适用于长时间运行进程的持续监控模式
• 添加事件驱动触发器（webhooks、外部事件）
• 实现结果持久化和执行历史跟踪
• 添加内置健康检查和自动恢复

其他结果存储类型

• 添加对象存储支持（S3、GCS、Azure Blob Storage）
• 添加数据库存储支持（PostgreSQL、MySQL、MongoDB）
• 添加消息队列支持（RabbitMQ、Kafka、Redis streams）
• 添加 API 端点集成（自定义 HTTP POST）
• 添加带附件的电子邮件通知支持
• 添加云日志集成（CloudWatch、Stackdriver 等）

许可证

MIT 许可证。有关详细信息，请参阅 LICENSE 文件。