SwarmScan

SwarmScan is a distributed masscan orchestration platform for authorized security research, asset inventory, and internal network measurement.

SwarmScan is intended for authorized security research, asset inventory, and internal network measurement. Only scan networks you own or have explicit permission to test.

Architecture

Dashboard ─┐
           ├── Controller API ─── PostgreSQL
Workers  ─┘          │
                     └── chunks scan jobs into CIDRs

Worker node ─── safe masscan wrapper ─── masscan binary

The controller runs with Docker Compose. Workers can run as Docker containers or native Go binaries on Linux hosts.

Controller Setup

cd controller
cp .env.example .env
docker compose up -d

API: http://localhost:3000 Dashboard: http://localhost:3001

Worker Setup

Docker from the repository root:

docker build -f worker/Dockerfile -t swarmscan-worker .
docker run --rm \
  -e CONTROLLER_URL=http://your-controller:3000 \
  -e WORKER_NAME=home-node-01 \
  -e API_KEY=change-me-please \
  -e MAX_RATE=10000 \
  swarmscan-worker

Native Linux build:

cd worker
go build -o swarm-worker ./cmd/swarm-worker
API_KEY=change-me-please ./swarm-worker

Native workers need a working masscan binary. Set MASSCAN_PATH if it is not at /usr/bin/masscan.

Example Scan Job

curl -X POST http://localhost:3000/api/jobs \
  -H 'content-type: application/json' \
  -d @shared/examples/job.json

Security Model

Workers register with an API key. The controller stores only a bcrypt hash and workers authenticate future requests with x-worker-id and x-api-key.

SwarmScan never accepts arbitrary commands. Jobs validate CIDRs, port lists, chunk size, and rate. Workers invoke masscan through an argument array:

masscan <cidr> -p<ports> --rate <rate> -oJ -

Each worker has a maximum rate, and the controller assigns the lower value of the job global rate and worker max rate. Jobs support pause, resume, and cancel. Chunks are retried up to three attempts before failing. Logs include worker, chunk, and job activity for audit-friendly operation.

Network Notes

Tailscale is the recommended way to connect worker machines to the controller without exposing the API publicly. If you expose the dashboard, prefer a protected route such as Cloudflare Tunnel with access controls.

Development Commands

Controller API:

cd controller/api
npm install
npm run migrate
npm run dev

Dashboard:

cd controller/dashboard
npm install
npm run dev

Worker:

cd worker
go test ./...
go build -o swarm-worker ./cmd/swarm-worker

Submodules:

git submodule update --init --recursive