HeezGuard protects Minecraft servers from: Bot attacks and automated connections DDoS attempts and connection spikes VPN/Proxy abuse and suspicious IPs Exploit attempts and crash attacks Spam and flooding in chat/commands Session hijacking and unauthorized access

🏗️ Architecture

Main Components (7 Core Systems)

BotDetectionEngine - Multi-layered bot detection with scoring system BehavioralAnalyzer - Real-time behavior profiling and pattern analysis RateLimiter - Connection and action rate limiting IPProtectionSystem - IP reputation, VPN/proxy detection, GeoIP filtering VerificationManager - 4 different verification methods ServerSecurityManager - Central security coordination AlertSystem - Multi-channel notification system Supporting Systems

ConfigManager - 100+ configuration options with hot reload DataManager - JSON-based data persistence with cleanup GUIManager - Interactive web-based management interface DiscordLogger - Rich Discord webhook integration

🤖 Advanced Bot Detection (15+ Methods)

Scoring-Based Detection System

HeezGuard uses a sophisticated scoring system (threshold: 75 points) that combines:Client Analysis (15 points) Suspicious client brands ("unknown", "vanilla", empty) Modified or fake client detection Known bot client signatures Ping Analysis (10-20 points) Unnaturally low ping detection (<10ms = 20 points) Very high ping detection (>500ms = 10 points) Perfect consistency detection (15 points) Name Pattern Recognition (25 points) Random character sequences Repeated character patterns Bot naming conventions Invalid name formats Connection Analysis (20 points) Multiple accounts from same IP Rapid connection sequences Connection timing patterns Behavioral Analysis (Real-time) Movement pattern detection Interaction timing analysis Chat pattern recognition Command pattern monitoring

✅ Verification System (4 Methods)

SIMPLE

Basic code entry Fast verification for trusted users 2. ADVANCED (Recommended)

Code entry via chat Movement requirement Timeout system (60 seconds) Multiple attempt tracking 3. CAPTCHA

Visual code presentation Manual code transcription Highest security for human verification 4. BEHAVIORAL

Natural movement patterns required Extended observation period Combines movement + code verification

🔒 Security Features

Rate Limiting

Connection Rate Limiting: Max 3 connections per IP per 30 seconds Action Rate Limiting: Commands (5/sec), Chat (3/sec), Interactions (10/sec) Automatic Blocking: Temporary IP blocks when limits exceeded Connection Spike Detection

Real-time Monitoring: Tracks connections per second Configurable Threshold: 10 connections per 5 seconds Response Actions: Block new connections, lockdown mode, or admin alerts IP Protection System

Proxy/VPN Detection: Multi-method detection with 24-hour caching GeoIP Filtering: Whitelist/blacklist by country IP Reputation System: Automatic scoring with decay over time Datacenter Detection: Identifies and blocks datacenter IPs Exploit Protection

Name Validation: Length limits, special character filtering Crash Packet Prevention: Blocks known exploit packets Session Protection: IP change detection during sessions Hijacking Detection: Session takeover attempt monitoring

📊 Behavioral Analysis

Movement Pattern Analysis

Straight Line Detection: Identifies robotic movement Timing Consistency: Detects unnaturally consistent intervals Physics Validation: Checks for realistic movement physics Pattern History: Tracks last 100 movements per player Chat Pattern Analysis

Repetition Detection: Identifies repeated messages Similarity Analysis: Uses Levenshtein distance algorithm Spam Detection: 80% similarity threshold Anti-Flood: Message cooldown system Interaction Analysis

Timing Windows: Tracks interaction intervals Speed Detection: Flags interactions faster than 2000ms Type Tracking: Different interaction types monitored History: Keeps last 50 interactions per player

📢 Alert System

Multi-Level Alerts

INFO: Successful verifications, normal events WARNING: Bot detection, rate limit violations, proxy detection CRITICAL: Connection spikes, lockdown activations, exploit attempts Alert Channels

In-Game Notifications: Real-time messages to admins Console Logging: Detailed log entries with timestamps Discord Webhooks: Rich embed messages with role mentions

⚙️ Configuration (100+ Options)

Major Configuration Sections

General Settings: Debug mode, language, auto-save Anti-Bot Protection: 25+ options for detection tuning IP Protection: 15+ options for IP management Security Features: 20+ options for protection levels Alerts & Notifications: 10+ options for alert management Actions & Punishments: 8+ options for response actions Performance: 5+ options for optimization

🎮 Commands & Management

Admin Commands

/heezguard - Open GUI menu (players) or show help /heezguard stats - View security statistics /heezguard check - Check player information /heezguard whitelist <add|remove> - Manage whitelist /heezguard blacklist <add|remove> - Manage IP blacklist /heezguard lockdown - Enable lockdown mode /heezguard unlock - Disable lockdown mode /heezguard reload - Reload configuration Player Commands

/verify - Complete verification process Permissions

heezguard.admin - Full access to all commands heezguard.bypass - Bypass all protection checks heezguard.notify - Receive security notifications heezguard.whitelist - Bypass verification (whitelisted)

📈 Statistics & Monitoring

Real-Time Statistics

Total players tracked IP addresses monitored Suspicious players flagged Blocked IPs count Lockdown status Online player count Per-Player Data

UUID tracking First/last seen timestamps Total joins count Suspicion score Verification status Failed verification count Known IP addresses Per-IP Data

First/last seen timestamps Total connections Failed attempts Reputation score Blacklist status Proxy/VPN status Country code Connection timestamps

🎯 Unique Features

What Makes HeezGuard Special

Comprehensive Scoring System: Unlike simple yes/no checks, uses weighted scoring for accurate detection Behavioral AI: Real-time analysis of player behavior patterns Multi-Method Verification: Four different verification methods Intelligent Rate Limiting: Context-aware rate limiting for different action types Reputation System: Long-term tracking of IP reputation with automatic decay Connection Spike Protection: Automatic server protection during attacks Modular Design: Easy to extend and customize Performance Optimized: Async operations, caching, and efficient algorithms Extensive Logging: Complete audit trail of all security events Admin-Friendly: Comprehensive commands and statistics