Server Guardian
ServerGuardian offers great security for your servers. Having IP lookup/tracking, alt detection, highly configurable Proxy/VPN detection and more!
Server Guardian
This project has been archived, may still work depending on version.
Server Guardian is an all-in-one security and moderation framework for servers, complete with protection, monitoring, and administration streamlining. For Paper and Purpur servers, Server Guardian has powerful moderation, real-time risk analysis, and machine-learning-style correlation systems to detect, maintain order, and ensure a fair player environment-all while maintaining peak server performance through fully asynchronous operations.
In its essence, Server Guardian offers intelligent, high-end alt-account and identity correlation systems that far exceed mere IP checks. Using a scoring-based correlation engine, it intelligently clusters accounts, identifies patterns of suspicious behavior, and cross-links player infractions across related users. Complemented by an integrated VPN/Proxy detection, dynamic IP range banning, and GeoIP services, Server Guardian acts as a vigilant security layer that keeps your playerbase clean and your staff informed. All security events can be broadcast to Discord webhooks for instant visibility.
Server Guardian provides moderation teams with a comprehensive toolset for investigations and staff management-including staff mode, vanish, command spy, and social spy. It has a freeze system that allows for investigations; it can take snapshots of players, data, and evidence; and it fully integrates with CoreProtect block logging. Its risk and stress detection systems run continuously, evaluating players' behaviors and trust levels to help staff in proactively dealing with problematic users before situations get out of hand. Backed by MySQL, SQLite, or local JSON storage, your data is secure and adaptable to any server scale.
⚙️ Key Features
- Advanced alt-account & correlation detection engine
- VPN/Proxy blocking with configurable automated actions
- Dynamic IP tracking and CIDR range banning
- GeoIP connection lookup for player locations
- Advanced moderation system (bans, mutes, warnings, kicks)
- Staff tools: vanish, social spy, command spy and freeze
- Player snapshot and investigation evidence system
- Integrated risk and trust assessment metrics
- Chat filtering with configurable rules and punishments
- CoreProtect integration for detailed logging
- Discord webhook notifications for real-time security alerts
- Playtime and performance tracking - TPS
- Multiple storage providers: MySQL, SQLite, JSON
- Fully asynchronous and performance-optimized operations
Config.yml
plugin:
name: ServerGuardian
version: x.x.x
features:
ipTracking: true
logging: true
geoip: true
altDetection: true
moderation: true
playtime: true
storage:
type: LOCAL
failOnDbError: false
local:
saveIntervalSecs: 60
mysql:
host: localhost
port: 3306
database: serverguardian
user: username
password: password
poolSize: 5
useSSL: false
sqlite:
fileName: serverguardian.db
performance:
threadPoolSize: 4
asyncQueueCapacity: 1000
autoSaveOnShutdown: true
enabled: true
ip:
ipHistorySize: 10
ban:
enabled: true
kickMessage: '&cYou are banned by IP: &f%reason%'
autoCheckOnJoin: true
broadcastToStaff: true
silentKick: false
altDetection:
enabled: true
sharedIpThreshold: 2
timeWindowDays: 30
autoTempban: false
tempbanDurationSecs: 86400
ignoreWhitelist: true
geoip:
enabled: true
providerUrl: http://ip-api.com/json/{ip}?fields=status,country,countryCode,region,city,isp,org,as,query
cacheTTLMinutes: 1440
cooldownMs: 500
lookupOnJoin: true
vpn:
enabled: true
checkOnJoin: true
kickOnDetection: false
apiType: PROXYCHECK
cacheDurationMs: 86400000
rateLimitMs: 1000
proxycheck:
apiKey: ''
ipqualityscore:
apiKey: ''
vpnapi:
apiKey: ''
iphub:
apiKey: ''
stress:
enabled: true
packetThreshold: 1000
commandThreshold: 50
playerPacketThreshold: 100
playerCommandThreshold: 10
autoKickPacketSpam: false
autoKickCommandSpam: false
cluster:
enabled: true
suspiciousThreshold: 3
chatFilter:
enabled: true
muteDuration: 300
violationThreshold: 5
thresholdAction: MUTE
rules:
swears:
enabled: true
pattern: (*Your Word*|*Your Word*|*Your Word*|*Your Word*)
action: WARN
message: '&cPlease watch your language!'
ip_addresses:
enabled: true
pattern: \b(?:\d{1,3}\.){3}\d{1,3}\b
action: BLOCK
message: '&cDo not share IP addresses!'
discord_invites:
enabled: true
pattern: (discord\.gg|discordapp\.com/invite)/[a-zA-Z0-9]+
action: BLOCK
message: '&cDo not advertise Discord servers!'
spam:
enabled: true
pattern: (.)\1{5,}
action: BLOCK
message: '&cDo not spam!'
spy:
enabled: true
snapshot:
enabled: true
trust:
enabled: true
rewardHighTrust: true
positiveActions:
COMMAND_USE: 1
BLOCK_PLACE: 1
BLOCK_BREAK: 1
CHAT: 1
PLAYTIME_HOUR: 5
negativeActions:
CHAT_VIOLATION: -5
COMMAND_SPAM: -10
KICK: -15
BAN: -50
risk:
enabled: true
autoKickCritical: false
highRiskCountries:
- CN
- RU
correlation:
enabled: true
debug:
enabled: false
vanish:
enabled: true
nightVision: true
silentChest: true
noPickup: true
staff:
enabled: true
freeze:
banOnLogout: true
blockLogging:
enabled: true
logging:
logsToFiles: true
logsToDatabase: false
fileRetentionDays: 7
categories:
chat: true
commands: true
join: true
leave: true
kick: true
death: true
teleport: true
blockPlace: true
blockBreak: true
bucketFill: true
bucketEmpty: true
signText: true
anvilRename: true
itemPickup: true
itemDrop: true
gamemodeChange: true
loginIP: true
metrics:
enabled: true
samplingIntervalSecs: 300
blacklist:
enabled: true
commands:
- /login
- /register
whitelist:
enabled: true
players:
- AdminPlayer
playtime:
enabled: true
trackAFK: false
afkThresholdSeconds: 300
saveIntervalSecs: 120
moderation:
enabled: true
syncWithBukkit: true
defaultBanReason: Violated server rules
defaultMuteReason: Chat violation
silentBans: false
privacy:
obfuscateIPs: false
logIPs: true
dataRetentionDays: 90
ip-whitelist:
Webhookconfig.yml
webhooks:
altDetect:
enabled: false
url: "https://discord.com/api/webhooks/YOUR_WEBHOOK_ID/YOUR_WEBHOOK_TOKEN"
mentionRole: ""
retryAttempts: 3
retryDelayMs: 1000
bans:
enabled: false
url: "https://discord.com/api/webhooks/YOUR_WEBHOOK_ID/YOUR_WEBHOOK_TOKEN"
mentionRole: ""
retryAttempts: 3
retryDelayMs: 1000
unbans:
enabled: false
url: "https://discord.com/api/webhooks/YOUR_WEBHOOK_ID/YOUR_WEBHOOK_TOKEN"
mentionRole: ""
retryAttempts: 3
retryDelayMs: 1000
whitelist:
enabled: false
url: "https://discord.com/api/webhooks/YOUR_WEBHOOK_ID/YOUR_WEBHOOK_TOKEN"
mentionRole: ""
retryAttempts: 3
retryDelayMs: 1000
logs:
enabled: false
url: "https://discord.com/api/webhooks/YOUR_WEBHOOK_ID/YOUR_WEBHOOK_TOKEN"
mentionRole: ""
retryAttempts: 3
retryDelayMs: 1000
categories:
- "kick"
- "ban"
global:
username: "UnifiedSecureMgr"
avatarUrl: ""
timeout: 5000
Folder Directory
ServerGuardian/
├── config.yml
├── data
│ ├── alt
│ ├── backups
│ ├── bans
│ ├── block_logs.json
│ ├── blocks
│ ├── ip
│ │ └── playerdata
│ ├── log_entries.json
│ ├── logs
│ ├── player_ip_data.json
│ ├── playtime
│ ├── playtime_data.json
│ ├── punishments.json
│ ├── snapshots
│ └── webhooks
├── lang
│ └── english.yml
├── logs
│ └── security-YYYY-MM-DD.log
└── webhook-config.yml
Installation & Setup
1. Download the latest release.
2. Place the .jar file into your server’s plugins directory.
3. Start your server to generate default configuration files.
4. Configure:
- config.yml for core and detection settings
- webhook-config.yml for Discord notifications
- lang/english.yml for message customization
5. Reload or restart the server to apply the changes.
Working Platforms: Paper & Purpur
Working Versions: 1.20-1.21.11
Permissions
| Permission | Description | Default |
|---|---|---|
| serverguardian.admin | Full administrative access | OP |
| serverguardian.moderate | Use moderation commands (ban, mute, warn, kick) | OP |
| serverguardian.spy | Enable command spy, social spy, and vanish | OP |
| serverguardian.freeze | Freeze players for investigations | OP |
| serverguardian.notify | Receive detection and alert notifications | OP |
| serverguardian.staff | Access staff mode and investigation tools | OP |
Commands
| Command | Description |
|---|---|
| /sg | Opens the Server Guardian main menu |
| /sg help | Displays command help |
| /sg ban | Ban a player |
| /sg mute | Mute a player |
| /sg warn | Issue a warning |
| /sg freeze | Freeze a player for investigation |
| /sg info | Show player correlation and risk data |
| /sg snapshot | Take a full player data snapshot |
| /sg staff | Toggle staff mode |
| /sg vanish | Toggle invisibility |
| /sg spy | Toggle command/social spy |
| /sg geoip | Show GeoIP info for player |
| /sg logger | Manage or view logs |
| /sg reload | Reload configuration files |
| /sg playtime | Check player playtime |
| /sg tps | Display TPS and performance metrics |
Configuration
| File | Purpose |
|---|---|
| config.yml | Core settings, moderation, detection thresholds, database settings |
| webhook-config.yml | Discord webhooks and alert channel configuration |
| lang/english.yml | Message templates and localization |
| data/ | Player data, alt clusters, punishment records, and tracking |
| logs/ | Rotating server guardian logs for security and performance events |
