OPShield

<div align="center"> # 🛡️ OPShield **Advanced security & command protection plugin for Paper 1.21+** (https://img.shields.io/badge/Version-2.0.0-blue)]() (https://img.shields.io/badge/Paper-1.21%2B-blue?logo=papermc)]() (https://img.shields.io/badge/Java-21%2B-orange?logo=openjdk)]() (https://img.shields.io/badge/License-Apache%202.0-green)]() *Protect your server from abuse — secure OP access, track every action, stop attackers instantly.* </div> --- ## 📖 Table of Contents - ✨ Features - 🔐 Security System - 📊 Audit & Logging - 📦 Requirements - 🚀 Installation - ⌨️ Commands & Permissions - 🔧 Configuration - 🔍 Troubleshooting - ❓ FAQ - 📄 Credits --- # ✨ Features ## 🔒 OP Protection - Password-gated `/op` and `/deop` — no password, no privilege changes - **Async PBKDF2 verification** — password hashing runs off the main thread; zero TPS impact even under brute-force attack - **Authenticated session tokens** — after one successful login, a configurable session window lets admins skip re-entering the password (`security.session_timeout_minutes`, default 30 min) - **Session cleared on disconnect** — sessions are never carried across reconnections - **Global auth concurrency cap** — server-wide PBKDF2 operations capped at 4 concurrent verifications to prevent CPU saturation under mass attack - PBKDF2-HMAC-SHA256 hashed storage — plaintext never kept in config - Configurable PBKDF2 iteration count (`security.password.pbkdf2_iterations`) - Automatic migration from legacy plaintext and SHA-256 hashes - **Auto-upgrade legacy hashes** — on next successful login, SHA-256 is silently replaced with PBKDF2 (`security.password.auto_upgrade_legacy_hash`) - Console warning if a legacy SHA-256 hash is detected on startup - OP whitelist — restrict `/op` to a predefined set of player names --- ## 🚫 Sensitive Command Protection - Block dangerous commands for non-OP players (`blocked_commands`) - Optionally block commands even for OP players (`blocked_op_commands`) - Block entire command namespaces via prefix list (`blocked_command_prefixes`) - Alias and namespace resolution — bypass attempts via `minecraft:op` or plugin aliases are caught - Per-player bypass permission (`opshield.bypass`) for trusted staff --- ## 🧠 Brute-force Detection & Lockout - Configurable failed-attempt limit before lockout (`security.lockout.max-attempts`) - Exponential backoff — each offence doubles the lockout duration - Optional IP-mirrored lockout (`security.lockout.track_ip`) - Lockout count decay after a cooling-off period (`security.lockout.count_decay_hours`) - Persistent tracking — lockout state survives server restarts - Manual unlock via `/opshield unlock <player|ip>` --- ## 🕵️ Shadow Ban System - Sensitive blocked commands send a fake success message instead of an error - Each trigger increments the player's hidden shadow-ban level - Level persists across restarts - Auto-escalates to real punishment when `shadow_ban.auto_punish_level` is reached - Set `auto_punish_level: 99` to keep decoy behaviour without escalation - Fake messages come from language files — fully customisable per locale --- ## ⚠️ Auto Punishment System - Punishment modes: `kick`, `ban`, `ban-ip`, `firewall`, `custom` - Persistent rolling-window threshold — survives restarts and crashes - Firewall mode runs an OS script asynchronously via `ProcessBuilder` with configurable timeout - Custom mode supports `{player}` and `{ip}` placeholders - IP-limit auto-punishment for accounts detected sharing the same IP --- ## 🌍 Multi-Language Support - Bundled language files: **English** (`en`), **Vietnamese** (`vn`), **Russian** (`ru`) - Automatic fallback to English for any missing key - Switch language via `language: "en"` in `config.yml` --- # 📊 Audit & Logging - Every privilege change, password failure, command block, and punishment is logged - Async queue — log writes never touch the main thread - **Queue capacity limit** — `audit.max_queue_size` prevents OOM if disk writes fail for extended periods - **Dual output format** — `audit.format: plain` (default human-readable) or `audit.format: json` (machine-readable, one JSON object per line) - **UTF-8 safe** — uses NIO `Files.write()` with explicit charset - **Retry on failure** — failed writes are re-queued instead of silently discarded - Configurable rotation: `audit.max_file_size_mb` and `audit.log_retention` (up to N backup files) - Optional console mirror: `audit.console_output: true` - Log files: `plugins/OPShield/audit.log`, `audit.log.1` … `audit.log.N` --- # 📦 Requirements | Component | Version | |-----------|---------| | Java | 21+ | | Paper | 1.21+ | | Folia | ❌ Not supported | --- # 🚀 Installation 1. Download the plugin `.jar` 2. Drop it into your server's `plugins/` folder 3. Start the server — OPShield will generate a random password and print it **once** in the console 4. Save the password somewhere safe (it is on