Honeypot — MineScan

What It Is

MCHoneypot mimics a real Minecraft server to detect and log automated scanners and bots probing port 25565.

When a scanner connects, the honeypot responds with a valid Minecraft status packet — version, MOTD, and a fake player list — so it looks like a real server. The connecting IP is looked up for country and ISP info, written to local log files, and optionally reported to AbuseIPDB and alerted via Discord webhook.

If the scanner proceeds to send a login packet, the username is captured and the connection is kicked with a configurable message. No real Minecraft session is ever established.

AbuseIPDB Contributor

Scanning IPs are automatically reported to AbuseIPDB under category 14 (Port Scan).

Reports are deduplicated per IP using the report_ttl setting to avoid submitting the same IP multiple times within a short window.

How It Works

Status ping

Scanner connects and sends a Minecraft handshake. The honeypot replies with a valid status JSON including version, MOTD, and a shuffled player list.

IP logging

The connecting IP is looked up via ip-api.com for country and ISP info, then written to the log file with a timestamp.

Login capture

If a login-start packet is sent, the username is extracted and logged. The connection is then kicked with a configurable message after a short delay.

AbuseIPDB reporting

When enabled, each new IP is reported to AbuseIPDB with category 14. Repeated reports for the same IP are suppressed by report_ttl.

Discord webhook

Optionally fires a Discord message on each hit and login attempt, including IP, country, ISP, and captured username.

Rate limiting

Per-IP connection tracking drops requests over the max_pings threshold within the configured time window.

Configuration

All settings are controlled via config.json. No code changes needed.

Core Settings

bind_host / port

string / integer

Interface and port to listen on. Defaults to 0.0.0.0:25565.

max_pings

integer

Max connections allowed from a single IP within the time_window before further connections are dropped.

time_window

integer — seconds

Rolling window used for per-IP rate limiting.

cleanup_interval

integer — seconds

How often expired rate limit and cache entries are pruned from memory.

cache_ttl

integer — seconds

How long IP geolocation lookups are cached to avoid redundant api-api.com calls.

report_ttl

integer — seconds

Minimum time before the same IP can be reported to AbuseIPDB again.

logs_directory

string

Directory where log files are written. Created automatically if it doesn't exist.

AbuseIPDB

enable_reports

boolean

Set to true to enable automatic AbuseIPDB reporting.

abuseip_api_key

string

Your AbuseIPDB v2 API key.

abuseip_reason_message

string

Comment attached to each report submission.

Discord Webhook

enable_webhook

boolean

Set to true to send Discord alerts on hits and login attempts.

webhook_url

string

Your Discord channel webhook URL.

Fake Server Response

"response": {
  "version": { "name": "1.21.11", "protocol": 774 },
  "players": { "max": 20, "online": 4, "sample": [...] },
  "description": { "text": "we love honey ;)" },
  "favicon": "data:image/png;base64,..."
}

The online player count is randomised ±1 on each response and the player sample list is shuffled.

Kick Message

"kick_message": {
  "text": "minescan.xyz honeypot caught your scanner ;)",
  "color": "yellow"
}

Log Files

Two files are written to the directory set by logs_directory.

logs

Detailed hit log with timestamps, IP:port, country, ISP, and any captured login usernames.

pureiplogs

Plain list of IPs one per line, suitable for piping into other tools. Login attempts are annotated inline.

Example output

[2025-01-14 03:12:44] Ping from: `192.0.2.47:49823`
Country: China
ISP: Shenzhen Tencent Computer Systems Company Limited

[2025-01-14 03:17:29] Login attempt from: scannerguy 203.0.113.88

Open Source & Usage

MCHoneypot is fully open-sourced. You can audit the code or contribute on GitHub.

Source Code

View on GitHub

Install dependencies

pip install -r requirements.txt

Run

python honeypot.py

Listening on port 25565 may require root on Linux. Use sudo python honeypot.py or set up an iptables redirect.

Support & Opt-Out

For questions, support, or to request opt-out from honeypot reporting, join the Discord server:

discord.gg/AYbDNEWgHE

MineScan Honeypot

Caught in the Jar

What It Is

AbuseIPDB Contributor

How It Works

Configuration

Log Files

Open Source & Usage

Support & Opt-Out