HeezGuard

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)​

1. 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