HWID-Tracker (Notification/Listing/Kick/Ban) by Area

HWID Tracker (Notification / Listing / Kick / Ban)

HWID Tracker is a lightweight utility mod for NeoForge that silently tracks the hardware ID (HWID) of players connecting to your server — enabling reliable HWID-based bans, multi-account detection, and instant operator alerts.

Unlike name or IP bans, a HWID ban is tied to the player's physical hardware, making it significantly harder to evade by simply creating a new account or switching networks.

🧩 Multiple Minecraft versions supported: 1.21.1–1.21.5 (one file) · 1.21.8 · 1.21.10 · 1.21.11 · 26.1. Download the file matching your server's Minecraft version from the Files tab.

⚠️ Note: This mod requires installation on both server and client. Add it as a required mod in your modpack. Players without the mod cannot connect.

🔒 Privacy: The HWID is hashed client-side with SHA-256 before being sent to the server. No raw hardware data ever leaves the client. This mod makes zero external network connections — all data is stored locally on your server, and multi-account detection is exposed as a local event for other mods to react to if needed.

---

✨ Features

• 🔍 Silent HWID tracking — hardware data is collected automatically on login, with no prompt or notification shown to the player
• 🔨 HWID + UUID + IP ban in one command — /hban covers all three ban layers simultaneously
• ⏳ Temporary bans — ban players for a specific duration (t:30m, t:12h, t:1d, t:2w), auto-lifted when expired, with the correct expiry date shown on the ban screen
• 🚫 Multi-account detection — detects when two accounts share the same hardware and kicks the second account instantly
• ✅ Bypass list — exempt trusted players from the multi-account kick with /hbypass, e.g. siblings sharing one PC or approved second accounts
• ⚙️ Configurable — multi-account kicking can be turned off entirely via config, while HWID tracking and manual ban commands keep working
• 📢 Operator alerts — all online operators (admin permission) receive an immediate in-game notification on multi-account attempts
• 📁 Per-player HWID files — each player gets their own config/user-hwids/<uuid>.txt with name, UUID, HWID hash, IP, first seen and last seen
• 📋 Ban list file — all bans are stored in config/user-hwids/bans.json with reason, banner name, timestamp and optional expiry
• 🔁 Vanilla ban integration — automatically writes to banned-players.json and banned-ips.json on ban, removes on unban/expiry
• ♻️ Full unban support — /hunban removes the player from all three ban lists at once
• 🔎 HWID lookup command — /hwid shows all stored data for any player, online or offline
• 🔌 Event API — fires a public HwidMultiAccountEvent on the NeoForge event bus, so other mods can react to multi-account detections locally without any dependency on this mod's internals
• ⚡ Lightweight — no database, no external connections, pure file-based storage

---

📋 Commands

All commands require operator/admin permission.

Command	Description
/hwid <name>	Show HWID data for a player (online or offline) — UUID, IP, HWID hash, first/last seen, ban status
/hban <name> permanent	Permanent ban by HWID + UUID + IP (works for online and offline players)
/hban <name> permanent <reason>	Permanent ban with a custom reason
/hban <name> t:<duration>	Temporary ban for the given duration
/hban <name> t:<duration> <reason>	Temporary ban with a custom reason
/hunban <name>	Remove all bans for a player (HWID, UUID and IP)
/hbanlist	List all active HWID bans with type (permanent/temporary), expiry, reason, banner and timestamp
/hbypass add <name>	Exempt a player from the multi-account kick (online or offline players)
/hbypass remove <name>	Remove a player from the bypass list
/hbypass list	List all bypass entries with who added them and when

Supported duration units: m (minutes) · h (hours) · d (days) · w (weeks)

Examples:

/hban Steve permanent Cheating
/hban Steve t:1d Griefing
/hban Steve t:30m

---

⚙️ Configuration

After the first server start, config/hwidtracker-server.toml is created automatically:

[general]
    # If true, a joining player is kicked when their hardware ID (HWID) already
    # belongs to another player currently online (multi-account detection).
    # Set to false to disable this check entirely – HWID tracking and manual
    # /hban, /hunban, /hbanlist and /hwid commands keep working either way.
    multi_account_kick_enabled = true

---

🔄 How It Works

Step	What happens
1. Player joins	Client mod silently reads Mainboard Serial + CPU ID + total RAM
2. Hash	Values are combined and hashed with SHA-256 — no raw hardware data ever leaves the client
3. Packet sent	The hash is sent to the server in a silent custom packet
4. Ban check	Server checks the hash against bans.json — if banned (and not expired), player is disconnected and added to vanilla ban lists, including the correct expiry date for temporary bans
5. Multi-account check	If enabled in config, the server checks if the same HWID hash is already active in the current session — if so, the second account is kicked, operators are alerted in-game, and HwidMultiAccountEvent is fired for other mods. Accounts on the /hbypass list are allowed through silently
6. File saved	Player data (name, UUID, HWID, IP, timestamps) is written to config/user-hwids/<uuid>.txt
7. Expiry check	Background task runs every 60s — expired temporary bans are automatically removed from all ban lists

---

🎯 Example Use Case

A player gets caught cheating. You run /hban PlayerName t:7d Cheating. The mod instantly:

• Kicks them from the server
• Writes their HWID, UUID and IP to bans.json with a 7-day expiry
• Adds them to vanilla banned-players.json and banned-ips.json, including the exact unban date and time
• After 7 days, the ban is automatically lifted across all lists

They create a new account and try to rejoin during the ban. The moment their client connects, the HWID hash matches → they are disconnected before they can even move, with the ban's reason and expiry date shown, and you receive an in-game alert.

---

📦 Technical Details

Minecraft Versions	1.21.1–1.21.5 (one file) · 1.21.8 · 1.21.10 · 1.21.11 · 26.1 — pick the matching file from the Files tab
Mod Loader	NeoForge (required version matches the Minecraft version — see file listing)
Java Version	21 (Minecraft 1.21.x files) · 25 (Minecraft 26.1 file)
Side	Client + Server (required on both)
External connections	None — all data stays on your server
Dependencies	None (OSHI is bundled with the game)
Mod ID	hwidtracker
Config	config/hwidtracker-server.toml
Storage	config/user-hwids/
HWID Components	Mainboard Serial · CPU Identifier · Total RAM

---

© 2area | Discord: 2area | CurseForge: https://www.curseforge.com/members/2area/projects | All rights reserved.