PacketWard checks a connection at the front door and quietly drops known hostile sources before Minecraft starts talking to them. It is a small, server-only mod for people who would rather spend their CPU and bandwidth on players.
No client install is needed. Modern versions use PolyLib on the server. The old Forge builds are standalone because those servers deserve nice things too.
PacketWard pauses a new TCP connection before Minecraft installs its packet decoder or handshake listener. It checks the source against the public radar, then either hands the channel back to Minecraft or closes it without a kick message. If that early hook is ever moved by a game update, PacketWard logs one warning and falls back to the earliest supported loader event instead of taking the server down with it.
The default block level is 4 out of 5. Set it to 0 if you want PacketWard installed but asleep.
| Minecraft | Loaders |
|---|---|
| 26.2 | Fabric, NeoForge |
| 26.1.2 | Fabric, NeoForge |
| 1.21.11 | Fabric, NeoForge |
| 1.21.1 | Fabric, NeoForge |
| 1.20.1 | Fabric, Forge |
| 1.12.2 | Forge |
| 1.7.10 | Forge |
Each Minecraft version lives on its own branch. This branch targets Minecraft 26.2.
PacketWard never sends a connecting IP address to the public API. It hashes the canonical address locally with domain-separated SHA-256 and sends the first five hexadecimal characters. Those five characters select a bucket containing possible matches.
The API returns the rest of every digest in that bucket. PacketWard rebuilds each full 256-bit digest and compares it locally. Sharing the same five-character prefix is not enough to block anyone.
local digest: abcde0123...
API candidate: abcde9f87...
decision: not the same address
There are 1,048,576 possible buckets, so the short prefix keeps responses practical without disclosing the complete digest. A false match would need to collide across the full SHA-256 value. The useful false-positive control is the risk level, because the radar's reputation judgement matters far more than the cryptographic collision chance.
PacketWard only performs the anonymous lookup described above. It does not send player joins, names, UUIDs, IP addresses or server activity.
The first start creates config/packetward.json5. JSON5 comments are supported.
{
// 0 disables lookups. 1 to 5 select the minimum risk level to block.
blockLevel: 4,
// If DNS, TLS, the API or its response fails, act like PacketWard is not there.
unavailablePolicy: "ALLOW",
// HTTP 429 and a full local lookup queue have their own policy.
rateLimitPolicy: "DENY",
connectTimeoutMillis: 1000,
requestTimeoutMillis: 2000,
// OFF or REQUIRED_FROM_TRUSTED.
proxyProtocol: "OFF",
trustedProxyCidrs: [],
bypassCidrs: []
}Configuration is read during startup. Restart the server after changing it.
An API outage allows connections by default. Rate limiting denies them by default, because repeatedly pushing past a public limit should not turn protection off. Both choices are yours.
Leave PROXY protocol off when players connect straight to the Minecraft port. If a trusted TCP proxy is in front, use REQUIRED_FROM_TRUSTED and list only that proxy's direct CIDR ranges.
Trusted proxies must send a valid PROXY v1 or v2 header. A missing or broken header is quietly closed. Connections that do not come from a trusted CIDR are checked using their socket address, so a player cannot claim a different source by sending a fake header.
Use the Gradle wrapper with the Java version declared by the branch:
./gradlew buildAll
Tests use a local fake HTTP engine. They do not contact the live radar.
Release tags use <minecraft-version>-<mod-version>, such as 26.2-1.0.0. The release workflow publishes the two loader jars to GitHub, CurseForge and Modrinth, then adds the verified modpacks.ch manifest.
The technical privacy contract is recorded in PRIVACY.md. Security-sensitive reports can use GitHub's private security advisory flow rather than a public issue.
PacketWard is available under the Apache License 2.0. Redistributed copies and derivatives must retain the licence and the CreeperHost notice. Third-party licences are included in the jars.
NOT AN OFFICIAL MINECRAFT MOD. NOT APPROVED BY OR ASSOCIATED WITH MOJANG OR MICROSOFT.