MineProxy

MineProxy is an experimental TCP SOCKS5 relay carried inside a Minecraft Java Edition-shaped session. It contains a command-line client, a Linux-compatible server, authenticated key exchange, bounded relay buffering, and protocol-level tests.

This repository now contains only the Java/TCP transport. The previous Windows GUI, server panel, configuration package, and RakNet transport were removed. RakNet/UDP development continues in bedrockproxy.

MineProxy is intended for protocol research and private networking. It is not a complete Minecraft server, has not received an independent security audit, and does not guarantee indistinguishability, censorship resistance, or compatibility with every Minecraft implementation.

Architecture

application
    -> SOCKS5 CONNECT at 127.0.0.1:1080
    -> mineproxy-client
    -> Minecraft Java-shaped encrypted TCP session
    -> mineproxy-server on 25565/tcp
    -> destination TCP service

The transport performs:

1. Minecraft handshake and login-start packets.
2. A 1024-bit RSA login encryption exchange followed by real AES-128/CFB8 stream encryption.
3. Login success and Play-state world/chunk packets.
4. An authenticated X25519 handshake using an Argon2id-derived pre-shared key.
5. ChaCha20-Poly1305 tunnel frames with counter-based nonces and replay rejection.
6. Bounded timing jitter, keep-alives, movement-like traffic, and coherent chunk coordinates.

Current Scope

• TCP CONNECT through a local SOCKS5 listener
• IPv4, IPv6, and domain destinations
• Linux server and Windows/Linux command-line client
• Maximum packet, frame, connection, and jitter-buffer limits
• Minecraft status response for ordinary status requests
• No UDP relay, TUN mode, GUI, web panel, or CDN transport

Compatibility Notice

The current transport enables the AES/CFB8 layer required after the Minecraft encryption response. Older MineProxy/MCProxy builds skipped that layer. Upgrade the client and server together; old and current binaries are not wire-compatible.

Build

Requirements: Go 1.21 or newer.

git clone https://github.com/spr334-a/MineProxy.git
cd mineproxy
go test ./...
go build -o mineproxy-client ./cmd/client
go build -o mineproxy-server ./cmd/server

Cross-compile the Linux server from Windows or another Go environment:

GOOS=linux GOARCH=amd64 CGO_ENABLED=0 \
  go build -trimpath -ldflags="-s -w" \
  -o mineproxy-server-linux-amd64 ./cmd/server

Server

Run manually:

export MINEPROXY_PASSWORD='replace-with-a-long-random-secret'
./mineproxy-server -listen 0.0.0.0:25565 -max-conns 128

The password can also be supplied with -password, but an environment variable avoids placing it directly in shell history and the process argument list.

systemd installer

Place mineproxy-server (or bin/mineproxy-server-linux-amd64) beside install-server.sh, then run:

sudo bash install-server.sh 'replace-with-a-long-random-secret' 25565 128

The installer:

• installs to /opt/mineproxy
• stores the password in /etc/mineproxy/mineproxy.env with mode 0600
• creates a dedicated mineproxy system user
• creates and starts mineproxy.service
• adds a TCP firewall rule when UFW or firewalld is available

Useful commands:

systemctl status mineproxy
journalctl -u mineproxy -f
systemctl restart mineproxy

Client

export MINEPROXY_PASSWORD='the-same-secret-as-the-server'
./mineproxy-client \
  -server your-server.example:25565 \
  -listen 127.0.0.1:1080 \
  -mc-host play.example.net \
  -max-conns 256

Configure an application to use SOCKS5 at 127.0.0.1:1080. The listener supports SOCKS5 TCP CONNECT; it does not implement UDP ASSOCIATE.

Do not expose the local SOCKS5 listener on 0.0.0.0 without adding access control at the host firewall. This command-line client intentionally defaults to loopback only.

Resource Limits

Defaults and hard limits are designed to avoid unbounded growth under slow peers or malformed input:

• server connections: 128 by default
• client SOCKS5 connections: 256 by default
• outer packet: 512 KiB maximum
• tunnel frame payload: 64 KiB maximum
• timing-jitter queue: 512 KiB with backpressure
• handshake deadlines: 30 seconds; tunnel authentication: 10 seconds

The server-side initial Play packet sequence is prebuilt and reused instead of being regenerated for every connection.

Security Notes

• Use a unique, randomly generated password.
• Keep the client listener on loopback unless LAN access is explicitly protected.
• Treat traffic-shaping and protocol resemblance as experimental, not as a security boundary.
• Review logs and connection limits before exposing the server publicly.
• Report security issues privately rather than publishing credentials, packet captures containing secrets, or live server addresses.

Repository Layout

cmd/client/       command-line SOCKS5 client
cmd/server/       Linux-compatible TCP server
pkg/crypto/       Argon2id, X25519, HKDF, and AEAD helpers
pkg/protocol/     Minecraft prelude, CFB8, framing, camouflage, and relay
pkg/socks5/       minimal TCP CONNECT listener

License

GNU Affero General Public License v3.0. See LICENSE.