MinePot

MinePot is a Minecraft Server Honeypot made in Golang. Its goal is to catch Minecraft Server Scanners by listening for Handshake and Ping packets.

See the changelog for the latest updates.

Table of content

• Features
• Installation
• Compiling from source
• Configuring MinePot
• Config details
• FAQ
• Credits
• Copyright

Features

• Listen on any TCP port for incoming Minecraft packets
• Answer Handshake packets
• Answer Ping packets
• Artificial random ping
• Custom Status Response :
  • Custom version or version mirroring (send the received protocol/version)
  • Fake players
  • Custom MOTD
  • Custom favicon
  • Random protocol/version
• IP reporting to Abuse IP DB
• IP reporting to a Discord Webhook
• History as a CSV formatted .history file

Installation

You can use Docker or install MinePot manually. Here's how:

• Download go (go 1.20 required).
• Download or clone the project.
• Download the binary from the Releases or build it yourself.
• Configure MinePot.
• Edit the ExecStart line in minepot.service to the MinePot binary location.
  e.g.: ExecStart=/home/YOUR_USERNAME/MinePot/MinePot
• Install MinePot by using install.sh. It will setup the tool and start it as a service for you.

Compiling from source

• Use build.sh or use go build

Configuring MinePot

If you already used install.sh, the config can be found in /etc/minepot/config.json.

• Open the config in your favorite editor.
• Enable the features you want to use. See Config details for in-depth explanations.
• Edit the Status Response as you want. You can use mctools MOTD creator for the MOTD.
• Change the faviconPath to any PNG image you want to use.

Config details

Item	Values	Meaning
debug	boolean	Enable debug logs
writeLogs	boolean	Enable logs file
logFile	text	Path to the logs file
writeHistory	boolean	Enable history file
historyFile	text	Path to the history file
port	number	TCP port to listen on
pingDelayMinMs	number	Minimum artificial server ping (in milliseconds)
pingDelayMaxMs	number	Maximum artificial server ping (in milliseconds)
idleTimeoutS	number	Time to wait before the connection times out
reportThreshold	number	Amount of packets before being reported
abuseIPDBReport	boolean	Enable Abuse IP DB reports
abuseIPDBKey	text	Abuse IP DB API key
abuseIPDBCooldownH	number	Cooldown between each reports (in hours)
webhookReport	boolean	Enable Discord webhook reports
webhookUrl	text	Discord webhook URL
webhookCooldownH	number	Cooldown between each reports (in hours)
webhookEmbedColor	text	Embed hex color
randomVersion	boolean	Enable random Minecraft version and protocol in the status response
statusResponse	boolean	Enable Status Response
statusResponseData	JSON	Minecraft Status Reponse data
faviconPath	text	Path to the favicon PNG image

FAQ

• Q: Do you plan to release a Windows version?
  A: No.

Credits

• Wiki.vg Minecraft protocol documentation
• go-mc Minecraft protocol implementation

Copyright

See the license.