ReconSwarm

ReconSwarm은 분산 보안 테스트를 위해 설계된 모듈식 정찰 자동화 프레임워크입니다. 최소한의 구성 오버헤드로 클라우드 인프라를 프로비저닝하고, 병렬 정찰 파이프라인을 실행하며, 결과를 수집합니다.

ReconSwarm은 수동 인프라 관리 없이 확장 가능하고 자동화된 정찰 워크플로우가 필요한 버그 바운티 헌터, 침투 테스터, DevSecOps 엔지니어 및 보안 연구자에게 적합합니다.

기능

• 병렬 실행을 위한 대상 분할 — 최종 컴파일된 대상 목록이 정찰 작업의 병렬 실행을 위해 워커들 간에 분할됩니다
• 다중 대상 유형 — 대상 목록은 여러 요소 유형으로 구성됩니다: crt.sh 응답의 도메인, 외부 목록(HTTP/HTTPS URL), 단순 목록(인라인 YAML 배열), 셸 명령 출력으로, 어떤 도구(cook, shodan, gau, katana 등)와도 매우 유연하게 사용할 수 있습니다.
• 클라우드 중립적 아키텍처 — 여러 클라우드 제공업체와의 손쉬운 통합 지원(현재 AWS, GCP, Yandex Cloud 및 Digital Ocean 지원)
• 유연한 파이프라인 스테이지 — 현재 exec(명령 실행) 및 sync(파일 및 디렉터리 동기화) 작업을 지원하는 확장 가능한 스테이지 시스템
• 단계 내 템플릿 컨텍스트 — 실행 컨텍스트의 메타데이터를 단계로 전달하는 유연한 방법

구현해야 할 필수 기능

• 웹 UI — 빠른 상호작용을 위한 간단한 웹 기반 사용자 친화적 UI
• 스테이지 실시간 로그 — stdout/stderr를 캡처하여 gRPC 스트리밍을 통해 클라이언트로 전송
• 워커 원격 셸 — rs 서버를 통해 클라이언트에서 워커로 SSH 연결 열기
• Findings 스테이지 — 이전 스테이지에서 수신한 데이터(예: nuclei JSON 결과)를 처리하고 etcd에 저장하며 알림을 생성하는 스테이지

아키텍처

ReconSwarm은 클라우드 프로비저닝, 원격 시스템 제어, 파이프라인 실행 및 구성 관리 간의 관심사를 명확히 분리하는 모듈식 아키텍처를 따릅니다.

클라우드 공급자 추상화

ReconSwarm은 클라우드 프로비저너에 **판별 유니온 패턴(discriminated union pattern)**을 사용합니다. 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 인터페이스를 구현하고 팩토리에 새 유형을 추가하여 통합할 수 있습니다.

파이프라인 스테이지 시스템

스테이지는 워커 VM에서 작업을 실행하는 확장 가능한 구성 요소입니다:

• exec — 템플릿 지원으로 셸 명령 실행
• sync — SFTP를 통해 원격 VM에서 로컬 머신으로 파일 또는 디렉터리 복사(파일/디렉터리 자동 감지)

모든 스테이지 필드는 템플릿 렌더링을 지원합니다. 기능을 확장하기 위해 새 스테이지 유형을 추가할 수 있습니다.

무상태 서버 및 내결함성

ReconSwarm 서버는 **완전히 무상태(stateless)**입니다 — 모든 상태는 etcd에 저장됩니다:

• 파이프라인 상태 — 각 파이프라인의 상태, 진행률, 오류
• 워커 상태 — VM 정보, 현재 작업, 상태
• SSH 키 — VM 접근을 위해 생성된 키 쌍

이 아키텍처는 다음을 가능하게 합니다:

고가용성 구성:

                    ┌─────────────┐
                    │   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 — 리소스 관리를 위한 폴더 ID
   • YC_CLOUD_ID — 클라우드 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 콘솔 > IAM 및 관리자 > 서비스 계정으로 이동
   • "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 콘솔 > IAM > 사용자로 이동
   • "AmazonEC2FullAccess" 권한으로 사용자 생성
   • 액세스 키 ID와 시크릿 액세스 키 생성

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 제어판 > API로 이동
   • "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 스테이지 — 템플릿 지원으로 셸 명령 실행:

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 구성에 따라 워커 VM 생성
4. 워커들 간에 대상 분배
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"

다중 스테이지를 사용한 사용자 지정 도구 체인:

서버 구성(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에서 확인 가능한 하위 도메인을 가져와 필터링합니다.

디버그 명령(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

TODO

추가 대상 소스

• 셸 실행 결과에서 대상 전달 추가(cook, radamsa 또는 사실상 모든 사용 가능한 도구를 사용하기 위해):
  • 클라이언트에서 대상 평가 후 gRPC 호출로 전달(대량 입력 시 네트워크 오버헤드)
  • 서버에서 평가(서버 환경에서 의존성 사용 필요)
• DNSDumpster 대상 소스 추가
• Censys 대상 소스 추가
• Shodan 대상 소스 추가

상태 저장 실행

• 실행 상태 저장 추가
  • 확인된 대상 목록
  • 실행 중 및 종료된 워커

멀티 클라우드 공급자 지원

• AWS(EC2) 프로비저너 추가
• Google Cloud Platform(Compute Engine) 프로비저너 추가
• Azure(Virtual Machines) 프로비저너 추가
• DigitalOcean 프로비저너 추가

확장 파이프라인 스테이지 유형

• notify 스테이지 추가 — 알림 또는 경고 전송(웹훅, 이메일, Slack)
• conditional 스테이지 추가 — 이전 스테이지 결과에 따라 스테이지 실행
• parallel 스테이지 추가 — 동일한 워커에서 여러 작업 동시 실행
• retry 스테이지 추가 — 구성 가능한 백오프로 실패한 작업 자동 재시도
• timeout 스테이지 추가 — 스테이지별 실행 시간 초과 설정
• validate 스테이지 추가 — 진행 전 결과 또는 조건 검증

예약 실행이 포함된 데몬 모드

• cron 유사 표현식을 사용한 예약 실행 구현
• 장기 실행 프로세스를 위한 지속적 모니터링 모드 추가
• 이벤트 기반 트리거 추가(웹훅, 외부 이벤트)
• 결과 영속화 및 실행 기록 추적 구현
• 내장 상태 확인 및 자동 복구 추가

대체 결과 저장 유형

• 객체 스토리지 지원 추가(S3, GCS, Azure Blob Storage)
• 데이터베이스 스토리지 지원 추가(PostgreSQL, MySQL, MongoDB)
• 메시지 큐 지원 추가(RabbitMQ, Kafka, Redis streams)
• API 엔드포인트 통합 추가(사용자 지정 HTTP POST)
• 첨부 파일이 포함된 이메일 알림 지원 추가
• 클라우드 로깅 통합 추가(CloudWatch, Stackdriver 등)

라이선스

MIT 라이선스. 자세한 내용은 LICENSE 파일을 참조하세요.