Server Guardian

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:

Spoiler

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:

Spoiler

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

Spoiler

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

Spoiler

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.x-1.21.8

Permissions

Spoiler

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

Spoiler

Command	Description
/sg	Opens the Server Guardian main menu
/sg help	Displays command help
/sg ban <player> [reason]	Ban a player
/sg mute <player> [duration]	Mute a player
/sg warn <player> [reason]	Issue a warning
/sg freeze <player>	Freeze a player for investigation
/sg info <player>	Show player correlation and risk data
/sg snapshot <player>	Take a full player data snapshot
/sg staff	Toggle staff mode
/sg vanish	Toggle invisibility
/sg spy	Toggle command/social spy
/sg geoip <player>	Show GeoIP info for player
/sg logger	Manage or view logs
/sg reload	Reload configuration files
/sg playtime <player>	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

Server Guardian

Compatibility

Minecraft: Java Edition

Platforms

Links

Creators

Details

Server Guardian

⚙️ Key Features

Config.yml:

Webhookconfig.yml:

Folder Directory

Installation & Setup

Permissions

Commands

Configuration