It uses masscan and dramatiq to scan for public minecraft servers on default port 25556.

iprange.py provides a class with utility functions to generate a file of ip ranges with either an /8 or /16 CIDR range.
The scanner script chooses a random ip address range from this file and calls masscan with it, on scan end, it queues a server list ping that on success caches the response to a redis backend, then a script periodically writes the bundled responses to a MongoDB database.

Install docker compose: Ubuntu, CentOs / Oracle linux

Clone the repo

git clone https://github.com/rezonmain/mc-server-scanner.git
cd mc-server-scanner

To enable saving found servers to a db, copy the .env.example file to .env in the root directory

 cp .env.example .env

Edit the MONGO_URI environment variable to your connection string. You can create a free MongoDB cluster with Atlas

Running masscan on a home network unlimited will melt your router, in my case, I run it at 35,000 kp/s which scans a x.x.x.x/16 range (65,536 hosts) in ~2 seconds, and at 100,000 kp/s when scanner is running on a vm.

To edit the rate at which masscan runs, edit the RATE environment variable in .env

MONGO_URI=MONGO_URI='mongodb+srv://<username>:<password>@<mongourl>/?retryWrites=true&w=majority'
RATE=100000 <- set to your liking
IDENT=SERVER_NAME

Run docker compose up

sudo docker compose up

You can browse my scanned entries on this website.

The source code for it can be found in the web/ directory.

Goals completed 🎉🎉🎉🎉

• Containerize application
• Write found servers to db (Mongo)
• Create front-end to browse servers