{"id":24125639,"url":"https://github.com/alex2276564/permguard","last_synced_at":"2026-05-20T14:36:01.474Z","repository":{"id":260342843,"uuid":"870875122","full_name":"alex2276564/PermGuard","owner":"alex2276564","description":"A Minecraft plugin designed to enhance server security by temporarily revoking admin permissions upon joining and sending security alerts to Telegram. It helps prevent unauthorized access and potential security breaches, ensuring that only authorized personnel can grant elevated privileges.","archived":false,"fork":false,"pushed_at":"2025-02-23T11:15:03.000Z","size":115,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-23T12:20:37.886Z","etag":null,"topics":["access-control","antiexploit","audit-logging","bukkit","compliance","java","least-privilege","minecraft","minecraft-plugin","minecraft-security","minecraft-server","notifications","paper","paper-mc","paper-plugin","plugin","security","server-protection","spigot","telegram"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/alex2276564.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-10-10T20:31:35.000Z","updated_at":"2025-02-23T11:15:07.000Z","dependencies_parsed_at":"2025-01-09T09:45:11.155Z","dependency_job_id":"e8f6ce9a-3aa0-4a46-bec7-9be322750ed8","html_url":"https://github.com/alex2276564/PermGuard","commit_stats":null,"previous_names":["alex2276564/permguard"],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alex2276564%2FPermGuard","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alex2276564%2FPermGuard/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alex2276564%2FPermGuard/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alex2276564%2FPermGuard/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alex2276564","download_url":"https://codeload.github.com/alex2276564/PermGuard/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241272619,"owners_count":19937091,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["access-control","antiexploit","audit-logging","bukkit","compliance","java","least-privilege","minecraft","minecraft-plugin","minecraft-security","minecraft-server","notifications","paper","paper-mc","paper-plugin","plugin","security","server-protection","spigot","telegram"],"created_at":"2025-01-11T15:25:49.160Z","updated_at":"2026-05-20T14:36:01.465Z","avatar_url":"https://github.com/alex2276564.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PermGuard 🔒\n\n[![Minecraft Version](https://img.shields.io/badge/Minecraft-1.16.5+-brightgreen)](https://papermc.io/software/paper)\n[![Java Version](https://img.shields.io/badge/java-17+-orange)](https://adoptium.net/installation/linux/)\n[![GitHub Release](https://img.shields.io/github/v/release/alex2276564/PermGuard?color=blue)](https://github.com/alex2276564/PermGuard/releases/latest)\n[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)\n[![ISO/IEC 27001](https://img.shields.io/badge/ISO/IEC%2027001-Compliant-brightgreen)](https://www.iso.org/standard/27001)\n[![Zero Trust Architecture](https://img.shields.io/badge/Zero%20Trust-Architecture-blue)](https://www.nist.gov/publications/zero-trust-architecture)\n[![CIS Controls](https://img.shields.io/badge/CIS%20Controls-Compliant-brightgreen)](https://www.cisecurity.org/)\n[![Least Privilege Principle](https://img.shields.io/badge/Least%20Privilege%20Principle-Implemented-brightgreen)](https://en.wikipedia.org/wiki/Principle_of_least_privilege)\n[![Audit Logging](https://img.shields.io/badge/Audit%20Logging-Enabled-yellow)](https://en.wikipedia.org/wiki/Information_security)\n[![Telegram Notifications](https://img.shields.io/badge/Telegram-Notifications-blue)](https://core.telegram.org/bots/api)\n[![Text Formatting](https://img.shields.io/badge/Text%20Formatting-🌈%20MiniMessage-ff69b4)](https://docs.advntr.dev/minimessage/)\n\n**PermGuard** is a Minecraft plugin designed to enhance server security by temporarily revoking admin permissions upon\njoining the server and sending security alerts to Telegram. Unlike traditional admin password plugins, which can often\nbe bypassed through various exploits, PermGuard implements a fundamentally more secure approach by completely removing\nelevated permissions on join. This helps to prevent unauthorized access and potential security breaches, even if other\nsecurity measures are compromised. When an admin with elevated permissions joins the server, their permissions are\nremoved, and they are kicked from the server. The permissions can only be restored after the admin rejoins without the\nelevated permissions and manually re-grants them via the console using commands like\n`lp user playernick permission set *`.\n\n## ✨ Features\n\n* **Automatic Permission Revoke:** Revokes specified permissions when an admin joins.\n* **Kick on Elevated Permissions:** Kicks the admin and logs the event if elevated permissions are detected.\n* **Telegram Alerts:** Sends detailed security notifications to Telegram, including information about the player, their\n  IP address, and country.\n* **Manual Permission Restoration:** Admins must rejoin without elevated permissions and restore them manually via\n  console commands.\n* **Customizable Kick Messages:** You can personalize the message shown to admins when they are kicked.\n* **Logging:** Logs all permission revocation events to both the console and a file for auditing.\n* **Reload Command:** Allows reloading the configuration without restarting the server.\n* **Lightweight and Efficient:** Designed to have minimal impact on server performance.\n* **Shutdown Protection:** If the plugin is disabled (e.g., through Plugman), the server will automatically shut down to\n  ensure no security gaps are left open.\n* **Auto-Update Check:** On server start, the plugin checks for updates. If a new version is available, a notification\n  is displayed in the console.\n* **Modern Text Rendering:** Uses Adventure MiniMessage for sleek formatting on supported servers (Paper 1.18+), with\n  automatic fallback on older versions.\n\n## 🛡️ Security Benefits\n\n### How PermGuard Protects Against Advanced Attacks\n\n1. **Brute Force Attacks:** By removing permissions upon login, it prevents unauthorized access even if someone gains\n   temporary access to an admin account.\n2. **Account Compromise:** If an admin's account is compromised, the attacker won't be able to abuse their permissions\n   as they will be revoked upon joining.\n3. **Session Hijacking:** Mitigates the risk of session hijacking by ensuring that permissions are not persistently\n   available during a hijacked session.\n4. **Social Engineering:** Reduces the risk of admins being tricked into giving away their permissions.\n5. **Unknown Vulnerabilities:** Helps mitigate the risks associated with unknown vulnerabilities by limiting the\n   potential damage an attacker can do, even if they find a way to bypass other security measures.\n6. **Port Exploitation / BungeeCord Hacks:** By revoking admin permissions on entry, PermGuard minimizes the potential\n   for attackers to exploit server ports or use BungeeCord-related hacks to gain elevated privileges.\n7. **AuthMe Bypass:** Even if an attacker finds a way to bypass AuthMe authentication, they won't gain immediate access\n   to admin permissions as PermGuard will revoke them upon entry.\n8. **Zero-Day Exploits:** Provides a safety net against zero-day exploits by ensuring that even if a vulnerability is\n   exploited, the attacker will not have sustained access to admin permissions.\n9. **Telegram Alerts:** If a suspicious activity is detected, detailed notifications are sent to Telegram, including the\n   player's IP and country, so you can take immediate action.\n10. **Shutdown Protection:** Ensures that if the plugin is disabled , the server shuts down to prevent any security gaps\n    from being exploited.\n\n### Compliance with Security Standards\n\n**Note:** The following compliance features are implemented within the PermGuard plugin itself. Your server's overall\nsecurity compliance depends on your complete infrastructure setup, proper configuration of all components, and following\nsecurity best practices across your entire system.\n\n* **Least Privilege Principle (ISO/IEC 15408):** Ensures that users have only the minimum permissions necessary to\n  perform their tasks, reducing the risk of privilege abuse.\n* **Audit Logging (ISO/IEC 27001):** Provides detailed logs of all permission-related activities, facilitating\n  compliance audits and forensic analysis.\n* **ISO/IEC 27001 Compliance:** PermGuard helps servers adhere to information security management best practices by\n  enforcing strict permission controls and audit logging.\n* **CIS Controls:** Aligns with the Center for Internet Security (CIS) Controls for effective cyber defense by\n  implementing strong access control measures.\n* **Secure Access Control:** By requiring manual permission restoration via the console, PermGuard ensures that only\n  authorized personnel can grant elevated privileges.\n* **Zero Trust Architecture (NIST SP 800-207):**  Applies a deny-by-default philosophy to administrative privileges.\n  Elevated access is never implicitly trusted and must be explicitly restored via the console after join.\n\n## 🛡️ Zero Trust Security Model\n\n**PermGuard** implements a **Zero Trust Architecture** for Minecraft server security - instead of relying on\nauthentication checks, passwords, or trust assumptions, it **unconditionally revokes elevated permissions** upon every\nlogin.\n\n### Why Zero Trust?\n\nTraditional security plugins rely on **verification mechanisms** (passwords, 2FA, IP checks) which can be:\n\n* 🔓 **Bypassed** through exploits (AuthMe vulnerabilities, session hijacking)\n* 🔓 **Compromised** via social engineering or credential theft\n* 🔓 **Circumvented** by unknown zero-day vulnerabilities\n\n**PermGuard's approach is fundamentally different:**\n\n\u003e **\"Never trust, always revoke\"** - Permissions are removed *before* any verification, making the security model *\n*attack-method agnostic**. Even if an attacker bypasses all authentication layers, they gain **no elevated privileges**\n\u003e because those privileges simply don't exist until manually restored via console.\n\nThis makes PermGuard effective against:\n\n* ✅ **Known attack vectors** (brute force, AuthMe bypass, BungeeCord exploits)\n* ✅ **Unknown future exploits** (zero-day vulnerabilities)\n* ✅ **Advanced persistent threats** (compromised accounts, session hijacking)\n* ✅ **Insider threats** (unauthorized access by trusted users)\n\n### TL;DR\n\n`PermGuard implements the principle of “zero trust” — instead of relying on checks and passwords, it simply revokes permissions upon any login. This makes it effective even against unknown types of attacks, as the basic security principle works regardless of the attack method.`\n\n## 📥 Installation\n\n1. **Download:** Download the latest version of PermGuard from the [Releases](https://github.com/alex2276564/PermGuard/releases) page.\n2. **Install:** Place the `.jar` file into your server's `plugins` folder.\n3. **Restart:** Restart your server to load the plugin.\n\n## 📜 Commands\n\nPermGuard supports both the full command `/permguard` and the shorter alias `/pg` for all commands (requires\n`permguard.command` permission).\n\n* `/pg help` - Show help information (requires `permguard.command`)\n* `/pg reload` - Reloads the plugin configuration (requires `permguard.reload` permission)\n\n## 🛠️ Compatibility\n\n* **Minecraft Versions:** 1.16.5 to the latest release\n* **Server Software:**\n  * ✅ [Paper](https://papermc.io/) (1.16.5 and newer) - **Fully Supported**\n  * ✅ [Folia](https://papermc.io/software/folia) - **Fully Supported** with optimized region-aware scheduling\n  * ❌ Spigot - Not supported\n* **Java Version:** Java 17 or higher\n\n## 📝 Note\n\n**Security Implementation Design:** PermGuard uses `PlayerJoinEvent` instead of `PlayerLoginEvent` by design. This\nensures that no other plugin can accidentally or intentionally override our security checks. With `PlayerJoinEvent`,\nonce we detect restricted permissions and kick the player, the action cannot be cancelled or overridden by other\nplugins, providing maximum security guarantee.\n\n**Why not PlayerLoginEvent?** Although `PlayerLoginEvent` would prevent the\nplayer from appearing in the tab list, other plugins with higher priority could potentially `allow()` the connection\nafter our `disallow()`, creating a security vulnerability.\n\n**AxiomPaper Compatibility:** This plugin may interfere with the AxiomPaper plugin's functionality. AxiomPaper only\nchecks permissions when a player joins the server, so if you remove all permissions and then restore them while in-game,\nthe Axiom mod will not work properly. To make PermGuard and Axiom work together, you can grant yourself the `axiom.*`\npermission on your account (and configure PermGuard not to remove it) to ensure both plugins function correctly.\n\n**Performance Optimization:** PermGuard checks permissions synchronously during the player join event. For optimal\nperformance, avoid adding unnecessary permissions to the configuration file. Remove any permissions that you don't\nactually need to monitor. For most admin accounts, you can simply use the wildcard permission `*` instead of listing\nmultiple individual permissions, as this provides comprehensive protection while maintaining efficiency.\n\nPermGuard uses an optimized permission cache built on reload. On join it performs a single fast‑path check for the\nwildcard (*) and then scans a deduplicated, immutable list of regular permissions. No parsing or reordering happens on\njoin.\n\n**Native MiniMessage Support:** Plugin uses only native Kyori Adventure MiniMessage implementation without any\nbackporting or compatibility layers:\n\n* **Paper 1.18+:** Full native MiniMessage support with all features including gradients, hover effects, click events,\n  and advanced formatting\n* **Paper 1.16-1.17:** Partial support with automatic conversion to legacy ChatColor codes. Supported features include\n  basic colors (`\u003cred\u003e`, `\u003cblue\u003e`, etc.), text styles (`\u003cbold\u003e`, `\u003citalic\u003e`, `\u003cunderlined\u003e`, `\u003cstrikethrough\u003e`,\n  `\u003cobfuscated\u003e`), and reset tags (`\u003creset\u003e`). Advanced features like gradients and hover effects are automatically\n  stripped without causing errors.\n\nYou can use the [MiniMessage Web Editor](https://webui.advntr.dev/) to test and preview your formatting. The plugin will\nautomatically adapt the formatting to your server's capabilities, so you can use the same configuration across different\nserver versions.\n\n\u003e Note: On Paper 1.16–1.17 there is no perfect way to get every MiniMessage feature without adding extra,\n\u003e version‑sensitive libraries. This plugin intentionally does **not** use full Adventure backports such as\n`BukkitAudiences` (they require constant updates and can conflict with complex plugins like ViaVersion). Instead, legacy\n\u003e servers get a simple MiniMessage‑like formatter (colors/styles only), while modern servers use the native Paper\n\u003e Adventure stack with full features.\n\n## 📦 Other Plugins\n\nAlso check out my other plugins for protecting your Minecraft server:\n\n* [**LeverLock**](https://github.com/alex2276564/LeverLock)  \n  *LeverLock* - a plugin to prevent rapid lever interactions, which can cause lag or be exploited for unintended game\n  mechanics. Works in conjunction with **AntiRedstoneClock-Remastered**, providing comprehensive protection from\n  redstone-based lag and exploits.\n\n* [**NoMoreTNTChainCrash**](https://github.com/alex2276564/NoMoreTNTChainCrash)  \n  *NoMoreTNTChainCrash* is a Minecraft plugin designed to prevent server crashes and lag caused by excessive TNT\n  explosions. It achieves this by ignoring TNT before automated chain explosions can occur, while still allowing players\n  to manually detonate TNT as desired.\n\n\u003e 🔍 **You can find more of my Minecraft plugins here:**  \n\u003e [https://github.com/alex2276564?tab=repositories](https://github.com/alex2276564?tab=repositories)\n\n## 🆘 Support\n\nIf you encounter any issues or have suggestions for improving the plugin, please create\nan [issue](https://github.com/alex2276564/PermGuard/issues) in this repository.\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 👨‍💻 Author\n\n[Alex] - [https://github.com/alex2276564]\n\nWe appreciate your contribution to the project! If you like this plugin, please give it a star on GitHub.\n\n## 🤝 Contributing\n\nContributions, issues, and feature requests are welcome! Feel free to check\nthe [issues page](https://github.com/alex2276564/PermGuard/issues).\n\n### How to Contribute\n\n1. Fork the repository.\n2. Create a new branch (`git checkout -b feature/YourFeature`).\n3. Commit your changes (`git commit -m 'Add some feature'`).\n4. Push to the branch (`git push origin feature/YourFeature`).\n5. Open a Pull Request.\n\n---\n\nThank you for using **PermGuard**! We hope it enhances the security of your Minecraft server significantly, making\nunauthorized access and privilege abuse a thing of the past. 🎮🔒\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falex2276564%2Fpermguard","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falex2276564%2Fpermguard","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falex2276564%2Fpermguard/lists"}