Overview

Guardian is a powerful alt account detection system for Minecraft servers. It tracks player connections using IP hash matching to identify accounts that share the same IP address.

Key Features

• IP Hash Matching — Securely links accounts using SHA-256 hashed IP addresses
• Name History Tracking — Tracks all username changes for each player
• Real-time Search — Instant autocomplete suggestions while typing
• Graph Visualization — Visual network of connected accounts
• Analytics Dashboard — Registration patterns and statistics
• Live Online Tracking — Real-time display of online players via Redis

Authentication

Access to the Guardian Panel requires a valid session key generated in-game by a player with appropriate permissions.

Generating a Session Key

Run the following command in-game:

This generates a unique 16-character session key in the format XXXX-XXXX-XXXX-XXXX. Click on the key in chat to copy it.

Session Properties

Dashboard

The main dashboard displays real-time statistics about the Guardian database.

Statistics Cards

Session Bar

After logging in, a session bar appears below the header showing:

• • Avatar — Your Minecraft player head
• • Username — The player who created the session
• • Expiry Timer — Countdown until session expires
• • Active Badge — Indicates the session is valid

Logout

Click the "Logout" button in the header to end your session. This invalidates the session key on the server and clears it from your browser. You'll need to generate a new session key in-game to log back in.

Connection Status

The header displays the current connection status to the Guardian API:

• Online — Connected to API successfully
• Offline — Unable to reach the API

Rate Limiting

Guardian implements rate limiting to prevent abuse. When you exceed the limit:

• • A full-screen overlay appears with a countdown timer
• • You must wait until the timer reaches zero before continuing
• • The countdown persists even if you refresh the page

Date Format

All dates in Guardian are displayed in US English format: MM/DD/YYYY HH:MM (24-hour time). For example: 01/15/2025 14:30.

Online Status

Guardian provides real-time online player tracking through Redis. The Minecraft server plugin periodically sends the list of online players to the backend, which is then displayed in the web interface.

Online Player Count

The dashboard header displays a live count of currently online players with a players icon. This count updates automatically every 15 seconds along with other dashboard statistics.

Online Players List

Below the statistics cards, a dedicated section shows all currently online players. The list includes:

• Player Avatar — 3D head rendering from Crafatar
• Username — Current player name
• Online Badge — Green indicator showing live status
• Search Button — Click to search for the player's alt accounts

Search & Filter

Use the search box to filter online players by username. The search is case-insensitive and matches partial names. Press Enter or wait 300ms after typing to apply the filter.

Pagination

When many players are online, the list is paginated with 20 players per page. Use the Previous/Next buttons to navigate between pages. The current page position is displayed between the buttons.

Auto-Refresh

The online players list automatically refreshes every 10 seconds. A countdown timer shows the time until the next refresh. This ensures you always see the most current player status.

How It Works

The online status system works as follows:

1. The Minecraft server plugin collects all online players every 30 seconds
2. Player data (UUID and username) is sent to the Guardian backend API
3. The backend stores this data in Redis with a 40-second TTL (time-to-live)
4. If no update is received within 40 seconds, players are automatically marked as offline
5. The web interface queries the backend for online status and displays results

Remote Commands

Guardian allows administrators to execute commands on players remotely through the web panel. Commands are sent to the specific Minecraft server where the player is currently online.

Kill Command

The Kill button appears next to online players in search results. Clicking it will kill the player on their current server by setting their health to 0.

How It Works

1. The Kill button is only visible for online players
2. Clicking the button opens a confirmation modal with blur effect
3. After confirmation, the command is sent to the Guardian backend
4. The backend determines which server the player is on (via Redis)
5. The command is queued for that specific server
6. The Minecraft plugin polls every 5 seconds for pending commands
7. The plugin executes player.setHealth(0) on the target player

Confirmation Modal

When you click the Kill button, a modal appears with:

• Warning icon indicating a dangerous action
• Target player's avatar and username
• Action badge showing KILL
• Description: "Player will be killed on their current server"
• Cancel button to abort
• Execute button to confirm

Technical Details

• Commands expire after 5 minutes if not retrieved by the plugin
• Server identification is automatic (IP + API Key hash)
• All command executions are logged with COMMAND_KILL action type
• Failed commands (player offline) are also logged for auditing

Search

Guardian provides multiple ways to search for alt accounts. The search interface includes three modes: Single, Bulk, and Graph.

Keyboard Shortcuts

Single Search

Search for a single player by username, UUID, or IP hash.

Search Types

Autocomplete

When searching by username, autocomplete suggestions appear after typing 2 or more characters. Results are split into two categories:

• Current Names — Players whose current username matches
• Previous Names — Players who previously used a matching username

Bulk Search

Search for multiple players at once by entering one username or UUID per line.

Usage

1. Select the search type (Usernames or UUIDs)
2. Enter each search term on a new line
3. Click "Search All" to process all entries
4. Results show found/not found status with alt counts
5. Click any result to view full details

Result Indicators

Graph View

Visualize the network of connected accounts in an interactive graph.

Node Types

Interactions

• • Drag — Move nodes around the canvas
• • Double-click — Search for the clicked player
• • Scroll — Zoom in/out
• • Clear — Remove all nodes from the graph

Adding to Graph

After searching for a player, use the "Add to Graph" button in the Actions panel to add all linked accounts to the visualization.

Results

Search results display the primary account and all linked alt accounts.

Result Card

Each account card shows:

• • Player head (from mc-heads.net)
• • Current username
• • Account age badge
• • Alt count (for primary account)
• • Registration/link date

Context Menu

Right-click any account card to access:

• • Copy UUID — Copy the player's UUID to clipboard
• • Copy Name — Copy the username to clipboard
• • Search Alts — Search for this player's alts
• • Add to Graph — Add all linked accounts to the graph

Sorting

Sort results using the dropdown:

• Newest — Most recently registered first
• Oldest — Oldest accounts first
• A-Z — Alphabetical by username

Actions Panel

• • Add to Graph — Add all results to the graph visualization
• • Export JSON — Download results as a JSON file
• • Clear — Clear all results

Export JSON Format

The exported JSON file contains:

{
  "exported": "2025-01-15T14:30:00.000Z",
  "count": 3,
  "results": [
    {
      "uuid": "069a79f4-44e9-4726-a5be-fca90e38aaf5",
      "username": "Notch",
      "ipHash": "a1b2c3d4...",
      "registeredAt": 1705312200000
    },
    ...
  ]
}

Player Details

Click on any account card to view detailed information in the sidebar.

Information Displayed

Activity Chart

The 24-hour activity chart shows when the player was last active. Bars indicate login times within the past 24 hours.

Name History

The Name History panel shows all recorded usernames for the player, with the current name highlighted at the top.

Linked Accounts Panel

When viewing a player with linked accounts, a separate panel appears showing all associated alts:

• • Player head and username for each alt
• • Link date showing when the account was connected
• • Account age badge for quick identification
• • Click any alt to search for its connections
• • Right-click for context menu options

Analytics

The Analytics Tab provides comprehensive insights into registration patterns, network analysis, risk assessment, and anomaly detection. All analytics data spans up to 90 days.

Period Comparisons

Time-Based Analytics

Network Analytics

Risk Assessment

Anomaly Detection

Sidebar Charts

Data Tables

Recent Registrations

Shows the 6 most recently registered accounts. Each row displays the player name, account age badge, and registration date. Click any row to search for that player.

Top Chains

Lists the 6 accounts with the most linked alt accounts. The alt count badge shows how many accounts share the same IP hash. Click any row to view the full alt chain.

Both tables can be refreshed manually using the "Refresh" button.

Tools

Guardian includes several utility tools accessible from the footer.

IP Hasher

Convert an IPv4 address to its SHA-256 hash for searching in Guardian.

Usage

1. Click "Hasher" in the footer
2. Enter a valid IPv4 address (e.g., 192.168.1.1)
3. Click "Generate Hash"
4. Use "Copy Hash" to copy the 64-character SHA-256 hash
5. Use "Search" to directly search for accounts with this IP hash

Sessions

View all active sessions for the Guardian Panel.

Session Information

• • Player Avatar — The Minecraft head of the session owner
• • Username — The player who created the session
• • Expiry Time — Remaining time until the session expires
• • Bound Status — Whether the session is bound to an IP

Status Badges

Database Stats

View detailed statistics about the Guardian database tables.

Information Displayed

• • Table Name — The database table identifier
• • Size — Storage space used by the table
• • Row Count — Number of records in the table
• • Size Bar — Visual representation of relative size

Tables Tracked

The database includes the following tables:

• • player_records — Main player records (UUID, username, IP hash, registration date)
• • players_by_iphash — IP hash to player mapping
• • players_by_username — Username lookup index
• • iphashes_by_player — Player to IP hashes mapping
• • username_history — Name change history
• • username_lookup — Current name lookup table
• • sessions — Active dashboard sessions
• • sessions_by_player — Sessions per player
• • audit_logs — Staff action logging

Audit Log

The Audit Log tracks all staff actions performed in the Guardian Panel for security and accountability.

Accessing the Audit Log

Click the "Audit Log" button in the footer to open the audit log modal.

Logged Actions

Search and Filter

• • Search — Search by username, target, or IP address
• • Action Filter — Filter by specific action type
• • Load More — Pagination for large result sets

Statistics

The audit log modal shows summary statistics at the top:

Security

Guardian implements multiple security layers to protect sensitive player data.

Authentication Security

• Session-based Auth — Login via Minecraft plugin with unique session keys
• IP Binding — Sessions are locked to the first IP that uses them
• Rate Limiting — 5 login attempts per minute, 60-second cooldown
• Whitelist Support — Optional UUID-based access control

Data Protection

• IP Hashing — IP addresses are stored as SHA-256 hashes, not plain text
• Audit Logging — All staff actions are logged for accountability
• IP Masking — IP addresses in audit logs are partially masked
• Request Timeout — 30-second timeout prevents hanging requests

Frontend Security

• XSS Protection — All user inputs are escaped before display
• URL Validation — External URLs are validated before use
• Session Storage — Sensitive keys stored in sessionStorage (cleared on tab close)
• Memory Cleanup — Proper cleanup of graph instances and intervals

Backend Security

• Input Validation — All inputs are validated server-side
• Secure Headers — CSP, X-Frame-Options, X-Content-Type-Options
• CORS Protection — Configurable cross-origin request filtering
• API Key Protection — Plugin endpoints secured with API key

Badges Reference

Guardian uses colored badges to quickly convey account status and information.

Account Age Badges

Status Badges

Activity Badges