Protectcord

ProtectCord — Advanced IP Protection & Moderation

Block VPNs, proxies, bots, and malicious connections with real-time IP intelligence. Built-in moderation, AutoMod chat filtering, alt detection, and MySQL multi-server sync — all in one lightweight plugin.

ProtectCord connects every joining player against a live threat intelligence database before they ever reach your server. Combined with a full moderation suite, it's the only tool you need to keep your server clean and your community safe.

✨ Milestones

• 2,300+ downloads on Modrinth
• 100,000+ ProtectCord API requests served
• 46 unique Minecraft servers running ProtectCord concurrently
• 203 concurrent protected players
• 1,000+ unique Discord users verified
• 3,000+ unique API requests per day
• 555 Discord Guilds using @ProtectCord#0253
• Watching over 100,000+ Discord users

bStats: https://bstats.org/plugin/bukkit/Protectcord/24623

---

✨ Key Features

IP Protection

• Real-Time IP Verification — Every connection checked against live threat intelligence
• VPN, Proxy & Tor Blocking — Stop ban evaders and alt accounts instantly
• Datacenter IP Detection — Flag and block hosting provider IPs used for bots
• Risk-Based Blocking — Configurable threat levels: UNKNOWN → LOW → MEDIUM → HIGH → CRITICAL
• Geo-Blocking — Block or whitelist entire countries using ISO codes
• Accounts-Per-IP Limiting — Cap simultaneous connections from a single IP
• Smart Whitelist System — Bypass protection by player name, UUID, or IP

Moderation Suite

• Progressive Warning System — Configurable auto-escalation from warn → kick → ban
• Temp Bans & Temp Mutes — Time-limited punishments with human-readable durations (1h, 7d, 30d)
• Mute System — Persistent mutes with reasons, issuer tracking, and auto-expiry
• Alt Account Detection — Find alts by shared IP (/pc alts <player>) — names only, never raw IPs
• Warning History — Full timestamped warning logs for any player, online or offline
• Clear & Remove Warnings — Remove individual warnings by index or clear all at once
• Audit Log — Automatic log of all moderation actions
• Offline Player Support — Warn, ban, mute, or check players who aren't online

AutoMod (Chat Filtering)

• Anti-Link — Block URLs with domain whitelist support
• Anti-Advertising — Block server IPs and Discord invites
• Anti-Spam — Rate limiting with configurable message window and duplicate detection
• Anti-Swear — Custom word blacklist with regex support and per-word exceptions
• Anti-Caps — Configurable caps threshold by percentage
• Anti-Flood — Block repeated character flooding
• Anti-Unicode/Zalgo — Block invisible text and character abuse
• Per-Rule Actions — Each rule independently set to: BLOCK, WARN, KICK, MUTE, or TEMPMUTE

Storage & Multi-Server

• YAML Flatfile Storage — Zero setup, works out of the box
• MySQL Storage — Full MySQL backend with HikariCP connection pooling
• Multi-Server Sync — Share one MySQL database across your entire network; bans and mutes are enforced on every server
• Live Migration — Migrate between YAML and MySQL at any time with /pc migrate
• Data Purge — Clean up old warnings, bans, mutes, IP logs, audit entries, and inactive players with /pc purge

Staff Tools

• In-Game Staff Alerts — Real-time notifications for kicks, bans, warns, mutes, automod actions, and more
• IP Masking — Show staff masked IPs (192.168.1.*) until they earn the protectcord.ip.full permission
• Player Reports — Players submit reports with /report; staff are notified in-game and via Discord
• API Stats — Check usage, rate limits, and API health with /pc stats
• Manual IP Check — /pc check <player|ip> for on-demand threat analysis

Platform & Integration

• 6-Platform Support — Paper, Spigot, Folia, BungeeCord, Velocity, and Forge
• Discord Webhooks — Rich embeds with country flag, city, VPN/proxy/tor/risk fields, per-event control, rate limiting, and retry logic
• Moderation Alert Webhooks — Separate webhook channel for ban/warn/mute/kick staff events
• 100% Async — All IP checks are non-blocking; no main-thread impact

---

🎮 Supported Platforms

Network tip: Install only on your proxy (Velocity/BungeeCord) to protect all backend servers with a single API key.

---

📥 Quick Setup

1️⃣ Get Your Free API Key

1. Visit protectcord.com
2. Create a free account
3. Generate an API key from Dashboard → API Keys
4. Free tier includes 32 requests/minute — enough for most servers

2️⃣ Install the Plugin

1. Download the correct JAR for your platform from Modrinth
2. Drop it into your plugins/ folder (or mods/ for Forge)
3. Start your server — config generates automatically
4. Add your API key to plugins/ProtectCord/config.yml
5. Run /protectcord reload or restart
6. Your server is now protected

---

⚙️ Full Configuration Reference

The config file is auto-generated at plugins/ProtectCord/config.yml on first run. Every option is explained below.

Velocity uses config.toml (same structure, TOML syntax). Forge uses config/protectcord-forge.toml.

---

API Settings

# Your ProtectCord API key — get one free at https://protectcord.com/dashboard/api-keys
api-key: "YOUR_API_KEY_HERE"

# How long to wait (ms) for the API to respond before giving up
api-timeout:
  connect: 15000   # Time to establish the connection (default: 15s)
  read: 15000      # Time to wait for a response after connecting (default: 15s)

# Automatic retry for failed/timed-out API requests
api-retry:
  max-attempts: 3      # Max number of retries before allowing/denying the player (1–5)
  initial-delay: 1000  # Wait this long before the first retry (ms)
  max-delay: 5000      # Never wait longer than this between retries (ms)
  multiplier: 2.0      # Multiply delay by this factor each retry (exponential backoff)

---

Server Identity

# Used for player tracking and multi-server MySQL identification
server:
  name: "My Server"   # Friendly name — stored in MySQL as server_id on every row
  ip: ""              # Your public IP — leave blank to auto-detect
  port: 25565         # Your server port
  type: "spigot"      # Platform: paper / spigot / bungeecord / velocity / forge / folia

---

Player Tracking

# UUID-based tracking via the ProtectCord API
player-tracking:
  enabled: true
  block-flagged-players: true    # Block players flagged as malicious by the API
  block-inactive-players: false  # Block players whose accounts are marked inactive

---

IP Protection

# Master switch — set to false to disable all IP checking (not recommended)
enable-ip-check: true

# Choose which connection types to block
block-vpn: true         # Virtual private networks (ban evaders, alt accounts)
block-proxy: true       # HTTP/SOCKS proxies and anonymizers
block-tor: true         # Tor exit nodes
block-datacenter: true  # Hosting provider IPs (common source of bots)
block-bogon: true       # Invalid, reserved, or unroutable IP ranges

# Risk-based blocking (optional, runs in addition to the flags above)
# Enable this to block by overall threat score instead of (or as well as) individual flags
enable-risk-level-blocking: false
blocked-risk-level: "HIGH"
# Levels (each blocks itself and everything above it):
#   LOW      — blocks LOW, MEDIUM, HIGH, CRITICAL  (very strict)
#   MEDIUM   — blocks MEDIUM, HIGH, CRITICAL
#   HIGH     — blocks HIGH, CRITICAL               (recommended if enabling)
#   CRITICAL — blocks CRITICAL only               (very lenient)

---

Geographic Blocking

geo-blocking:
  enabled: false
  mode: "blacklist"   # "blacklist" = block listed countries
                      # "whitelist" = ONLY allow listed countries (everyone else blocked)
  countries:          # ISO 3166-1 alpha-2 country codes
    - "CN"
    - "RU"

---

Accounts Per IP

# Limit how many Minecraft accounts can connect simultaneously from the same IP
account-per-ip-limit:
  enabled: false
  max-accounts: 3          # Maximum simultaneous connections from one IP
  enforcement: "BLOCK"     # "BLOCK"       — deny the new connection
                           # "KICK_OLDEST" — kick the oldest session to make room

---

Discord Webhook (Connection Events)

discord-webhook:
  enabled: false
  url: ""             # Paste your Discord webhook URL here
  timeout: 10000      # HTTP timeout for sending the webhook (ms)

  # Retry failed webhook deliveries
  retry:
    enabled: true
    max-attempts: 3       # How many times to retry a failed delivery (1–10)
    initial-delay: 1000   # Wait before first retry (ms)
    max-delay: 10000      # Maximum wait between retries (ms)
    multiplier: 2.0       # Exponential backoff multiplier

  # Rate limiting — Discord allows ~5 requests per 2 seconds per webhook
  rate-limit:
    max-per-second: 2   # Requests sent per second (1–5)
    burst-limit: 5      # Maximum burst before throttling kicks in

  # Which events send a webhook message
  events:
    denied: true          # Player was blocked by ProtectCord
    accepted: false       # Player passed all checks and joined (high volume — off by default)
    whitelisted: true     # A whitelisted player joined
    error: true           # An API error occurred during a check

  # Which data fields appear in the embed
  data-fields:
    show-country: true
    show-country-flag: true   # 🇺🇸 flag emoji next to country name
    show-city: true
    show-vpn: true
    show-proxy: true
    show-datacenter: true
    show-tor: true
    show-mobile: true
    show-satellite: true
    show-crawler: true
    show-bogon: true
    show-risk-level: true
    show-abuser: true
    show-blacklisted: true
    show-company: true        # ISP / hosting provider name
    show-company-risk: true

  # Customise the appearance of each embed type
  embeds:
    denied:
      title: "Connection Denied"
      emoji: "x"
      color: 15158332      # Decimal RGB — red
      footer: ""           # Optional footer text
      thumbnail-url: ""    # Optional image in top-right corner
    accepted:
      title: "Connection Accepted"
      emoji: "white_check_mark"
      color: 3066993       # Green
      footer: ""
      thumbnail-url: ""
    whitelisted:
      title: "Whitelisted Player Joined"
      emoji: "white_circle"
      color: 16776960      # Yellow
      footer: ""
      thumbnail-url: ""
    error:
      title: "API Error"
      emoji: "warning"
      color: 15105570      # Orange
      footer: ""
      thumbnail-url: ""

  # Advanced webhook behaviour
  advanced:
    validate-url-on-startup: true   # Send a test ping when the plugin loads
    log-failures: true              # Print failed deliveries to console
    log-retries: true               # Print retry attempts to console
    queue-size: 100                 # Max webhooks queued before dropping oldest

---

Staff Alerts

# In-game and Discord notifications for moderation actions
alerts:
  enabled: true

  # Broadcast to online staff with the protectcord.alerts permission
  in-game:
    enabled: true

  # Separate webhook channel just for mod-team events
  discord-webhook:
    enabled: false
    url: ""

  # Fine-tune exactly which actions trigger an alert
  events:
    kick: true
    ban: true
    unban: true
    warn: true
    clear-warnings: true
    remove-warning: true
    automod: true
    mute: true
    unmute: true
    tempmute: true
    tempban: true

---

Warning System

warnings:

  # Automatically take action when a player accumulates enough warnings
  auto-action:
    enabled: true
    action: "BAN"      # "BAN" — permanent ban | "KICK" — kick only
    threshold: 3       # Number of warnings before auto-action fires

  # Kick the player with a "final warning" message at a lower threshold
  kick-on-warn:
    enabled: true
    threshold: 2       # Kick at this warning count (before the ban threshold)

  # Warnings older than this are not counted toward thresholds
  expiry:
    duration: "0"      # "0" = warnings never expire
                       # Examples: "7d", "30d", "90d"

  # Escalation tiers — overrides auto-action when enabled
  # Each tier fires when warning count reaches `count`
  escalation:
    enabled: false
    tiers:
      - count: 1
        action: "WARN"
      - count: 2
        action: "TEMPMUTE"
        duration: "1h"
      - count: 3
        action: "TEMPBAN"
        duration: "1d"
      - count: 4
        action: "TEMPBAN"
        duration: "7d"
      - count: 5
        action: "BAN"
# Available actions: WARN, KICK, MUTE, TEMPMUTE, TEMPBAN, BAN
# Duration format: 30s, 10m, 1h, 7d, 30d

---

AutoMod (Chat Filtering)

automod:
  enabled: false           # Master switch — must be true for any rules to run

  # Blocked actions apply to the message that triggered the rule.
  # Available actions for all rules: BLOCK, WARN, KICK, MUTE, TEMPMUTE
  # TEMPMUTE duration is set by tempmute-duration below.
  tempmute-duration: "10m"

  # Block links in chat
  anti-link:
    enabled: true
    action: "BLOCK"
    whitelisted-domains:   # These domains are allowed through
      - "yourdomain.com"
      - "discord.gg/yourserver"

  # Block spam (too many messages too fast, or too many duplicates)
  anti-spam:
    enabled: true
    action: "BLOCK"
    max-messages: 5          # Max messages allowed within the time window
    time-window-seconds: 10  # Rolling window size in seconds
    max-duplicates: 3        # Max identical messages allowed in the window

  # Block server IPs and Discord invite links
  anti-advertising:
    enabled: true
    action: "BLOCK"
    block-server-ips: true       # Blocks patterns like "play.someserver.net"
    block-discord-invites: true  # Blocks discord.gg/... links
    whitelisted-domains:
      - "yourdomain.com"
      - "discord.gg/yourserver"

  # Block profanity and custom banned words
  anti-swear:
    enabled: false
    action: "BLOCK"
    use-regex: false          # Set true to treat blocked-words entries as regex patterns
    blocked-words:
      - "badword1"
      - "badword2"
    whitelisted-words:        # These words are never blocked even if they match a pattern
      - "scrapbook"

  # Block excessive CAPS LOCK
  anti-caps:
    enabled: false
    action: "BLOCK"
    min-message-length: 5      # Ignore short messages (e.g. "OK", "YES")
    threshold-percent: 70.0    # Block if more than this % of letters are uppercase

  # Block character flooding (aaaaaaaaaa, !!!!!!!!!)
  anti-flood:
    enabled: false
    action: "BLOCK"
    max-repeated-chars: 5   # Consecutive identical characters before blocking
    min-message-length: 3   # Ignore very short messages

  # Block Unicode abuse and Zalgo text
  anti-unicode:
    enabled: false
    action: "BLOCK"
    block-zalgo: true           # Block combining diacritical mark stacking (z͎̤̙̘̭͇͠a̵͔͓l̡͔͍̦͚͙g̢͕̲͔͔͕ö̥́)
    max-unicode-percent: 50.0   # Block if more than this % of chars are non-ASCII

---

Player Reports

reports:
  enabled: true
  cooldown-seconds: 60       # How long a player must wait between reports

  # Post reports to a Discord channel
  discord-webhook:
    enabled: false
    url: ""
    mention-role-id: ""      # Optional — ping a role when a report comes in (e.g. "123456789")

  notify-staff: true         # Broadcast reports to online staff with protectcord.alerts

  predefined-reasons: []     # Optional list of reasons shown in tab-complete
                             # Example: ["Hacking", "Spam", "Harassment", "Inappropriate name"]

---

Database Storage

database:
  type: "YAML"   # "YAML" — flatfile storage (default, no setup needed)
                 # "MYSQL" — MySQL/MariaDB (required for multi-server sync)
  mysql:
    host: "localhost"
    port: 3306
    database: "protectcord"   # Database name (must exist before starting)
    username: "root"
    password: ""
    table-prefix: "pc_"       # All tables prefixed with this (e.g. pc_warnings, pc_bans)

    # HikariCP connection pool settings
    pool:
      max-pool-size: 10         # Maximum simultaneous database connections
      min-idle: 2               # Minimum idle connections kept open
      connection-timeout: 30000 # Max wait for a connection from the pool (ms)
      idle-timeout: 600000      # Close idle connections after this long (ms)
      max-lifetime: 1800000     # Recycle connections after this long (ms)

---

IP Masking

# Control how IP addresses appear to staff in command output
# Staff with the protectcord.ip.full permission always see the full IP
ip-masking:
  enabled: false
  mask-format: "last-octet"
  # "last-octet"      → 192.168.1.*       (hides last segment)
  # "last-two-octets" → 192.168.*.*       (hides last two segments)
  # "full-mask"       → *.*.*.*           (hides everything)

---

Custom Messages

# All messages support & colour codes. Placeholders listed per message.
messages:

  # Shown to players blocked by IP check — {reason}, {risk}
  connection-denied: |
    &c&lConnection Denied
    &7Your connection has been blocked by ProtectCord.
    &7Reason: &c{reason}
    &7Risk Level: &c{risk}

    &7If you believe this is an error, please contact server staff.

  # Shown when the API is unreachable during a check
  api-error: |
    &c&lTemporary Connection Issue
    &7We're unable to verify your connection at the moment.
    &7Please try again later.

  # Shown to a player blocked by the accounts-per-IP limit — {max}, {current}
  account-limit-reached: |
    &c&lConnection Limit Reached
    &7Maximum accounts per IP: &c{max}
    &7Current connections from your IP: &c{current}

    &7Please disconnect another account before connecting.

  # Shown to the oldest session kicked by KICK_OLDEST enforcement — {max}
  account-limit-kicked: |
    &c&lYou have been disconnected
    &7A new account connected from your IP address.
    &7Maximum accounts per IP: &c{max}

  # Shown when player-tracking blocks a flagged player — {flags}
  player-flagged: |
    &c&lConnection Denied
    &7Your account has been flagged.
    &7Flags: &c{flags}
    &7If you believe this is an error, please contact server staff.

  # Shown when player-tracking blocks an inactive player
  player-inactive: |
    &c&lConnection Denied
    &7Your account has been deactivated.
    &7Please contact server staff.

  # Shown in chat to whitelisted players who bypass the IP check
  whitelist-bypass: "&aYou have bypassed IP verification."

---

🎯 Commands & Permissions

Aliases: /pc, /protect

Core Commands

Whitelist Commands