TCGuard — Universal Crash, Exploit, Packet & Anti-Bot Protection for Minecraft

TCGuard is a high-performance, lightweight, all-in-one security and anti-exploit engine engineered for Minecraft servers (Spigot, Paper, Purpur, Folia across 1.8.8 to 1.21+). It neutralizes crashes, malicious packets, NBT exploits, botnet waves, and unauthorized permission escalations with zero TPS impact.

📌 Features Overview

1. 🛡️ Exploit & Crash Prevention

• Log4J / JNDI Protection: Blocks malicious JNDI lookups (CVE-2021-44228) in chat, commands, and signs.
• NBT & Item Validation: Drops illegal items, nested shulker boxes (shulker bombs), oversized books, and high-particle fireworks.
• Movement & Position Checks: Filters out NaN or Infinity coordinates and invalid pitch/yaw values that could crash chunks or clients.
• Window & Inventory Protection: Prevents invalid window click packets and illegal creative-mode item creation.

2. 🤖 Anti-Bot & Connection Shield

• Handshake Timing Analysis: Identifies automated bot software by measuring the time between connection handshake and login packets.
• Subnet (/24) Rate Limiting: Limits rapid joins originating from the same IP range.
• Dynamic Attack Mode: Temporarily tightens connection rules automatically when a join flood is detected.

3. ⚡ Packet & Combat Checks

• Netty Exception Handling: Traps corrupt network frames and closes broken sockets cleanly to prevent server tick hangs.
• Auto-Clicker & Macro Detection: Analyzes click standard deviation and CPS thresholds to block rapid macros (22+ CPS).
• FastBreak & FastPlace: Drops impossible block breaking and placement speeds.

4. 🔐 Admin Security, 2FA GuardCode & Auto-Deop Sync

• Mandatory Admin GuardCode: All OP and admin players must define and enter a secret GuardCode pin upon joining. Unverified admins are completely frozen and cannot move, run commands, or interact with blocks/inventories.
• Console-Only Code Reset: GuardCode PINs can strictly and exclusively be reset from the server console via guardcode-reset <username> or guard resetcode <username>. All in-game reset attempts are blocked.
• Automatic Deop Synchronization: Whenever an administrator is deopped (/deop, console deop, or server operator snapshot update), TCGuard instantly strips their authorized status and removes them from admins.yml.
• Console-Only Whitelist (Zero-OP): Having server OP does not grant access to TCGuard commands or bypass security checks. Administrators must be explicitly approved from the server console.
• Staff IP Lock: Optional restriction ensuring administrator accounts can only log in from approved IP addresses.
• Brute-Force & Leaked Password Filter: Limits repeated failed /login attempts and blocks common/weak passwords during registration.

5. 🗄️ Forensics & Database Logging

• SQLite & MySQL Support: Automatically logs security events asynchronously (zero TPS impact).
• In-Game Audit Commands: Check recent violations or a specific player's incident history with /guard history <player>.

6. 📊 In-Game GUI & Multi-Language Support

• Interactive Dashboard: Run /guard gui to see live TPS, RAM usage, and toggle individual protection modules.
• Built-In Languages: Supports English (en), Turkish (tr), and Spanish (es). Switch languages directly in the GUI or via config.yml.

🎮 Commands & Permissions

Console-Only Commands

These commands can only be executed directly from the server console:

In-Game Commands (Authorized Admins Only)

⚙️ Configuration (config.yml)

language: en

admin-guardcode:
  enabled: true
  max-failed-attempts: 5

auth-security:
  enabled: true
  brute-force:
    enabled: true
    max-attempts: 3
    lockout-minutes: 10
  password-strength:
    enabled: true
    min-length: 6
  admin-ip-lock:
    enabled: false
    trusted-ips:
      - 127.0.0.1

force-op-protection:
  enabled: true
  whitelisted-ops:
    - console

packet-protection:
  max-packets-per-second: 300
  max-custom-payload-size: 32767
  block-tab-complete: true
  block-creative-packets: true
  check-invalid-positions: true
  check-vehicle-movement: true
  check-window-clicks: true
  netty-pipeline-shield: true
  auto-clicker:
    enabled: true
    max-cps: 22
    min-standard-deviation: 2.2

anti-bot:
  enabled: true
  max-joins-per-ip-per-minute: 3
  max-global-joins-per-second: 5
  timing-protection:
    enabled: true
    min-handshake-duration-ms: 25
  subnet-protection:
    enabled: true
    max-joins-per-subnet-per-minute: 6

📦 Installation

1. Place TCGuard.jar (or TCGuard-2.0-ENTERPRISE.jar) in your server's plugins/ directory.
2. (Optional) Install ProtocolLib for deeper packet inspection.
3. Start the server.
4. From your server console, add yourself as an authorized admin:

   guard-add YourUsername
   

5. Join the server and set your 2FA GuardCode PIN:

   /guardcode set 1234
   

6. Type /guard gui in-game to configure your modules!

📄 License

This project is open-source and available under the MIT License.