> For the complete documentation index, see [llms.txt](https://cozy-1.gitbook.io/dev-example2/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cozy-1.gitbook.io/dev-example2/protector/protector.md).

# Protector

<div align="left"><figure><img src="/files/ClP5zSALdsNIVl7m8SNB" alt=""><figcaption></figcaption></figure></div>

🛒 [mantic.dev/product/manticprotector](http://mantic.dev/product/manticprotector) - $10.00 \
🔐 Requires ManticLib (free) and supports from 1.8 upwards

#### Protector Plugin Overview

Introducing **ManticProtector**, a plugin made to help server owners keep control of their Minecraft servers. It prevents anyone from gaining OP or other high-level permissions without your approval, and helps protect your server from hackers or griefers attempting to cause disruption. If you want a simple, reliable way to keep your server safe, ManticProtector has you covered.

#### Key features of ManticProtector

* **Full Server Protection**
  * *Automatically blocks unauthorised attempts to gain OP, administrator permissions, or dangerous permission nodes.*
* **Protected Users System**
  * *Specify trusted players (developers, owners, admins) who are exempt from OP and permission checks.*
* **Operator Checker**
  * *A background task that scans for unauthorised OPs and takes action instantly.*
* **Command Monitoring**
  * *Detects suspicious or blocked commands used by players and executes custom punishment commands.*
* **Console OP Protection**
  * *Prevents even the console from opping untrusted players—fully configurable.*
* **Permission & Group Blacklists**
  * *Automatically detects and removes blacklisted permissions or groups when a player joins or triggers an event.*
* **Discord Integration**
  * *Multiple configurable Discord webhook templates for:*
    * *Unauthorized OP detection*
    * *Blocked command alerts*
    * *Blacklisted permission logs*
    * *IP / Geo mismatches*
    * *Mass punishment alerts*
    * *LuckPerms-related changes*

#### Developer Section (ProtectorAPI#)

```
» ProtectorAPI#isListedUser(UUID) - Checks whether the specified UUID has a whitelist entry inside config.yml.
» ProtectorAPI#isAuthorizedUser(Player|UUID) - Returns true if the player/UUID is registered and allowed to have OP status according to their configuration entry.
» ProtectorAPI#getUser(Player|UUID|OfflinePlayer) - Fetches the corresponding User object from the configuration. (Returns null if the player is not listed.)
» ProtectorAPI#hasElevatedPermissions(Player) - Checks if the listed user is allowed OP or has any whitelisted groups assigned.
» ProtectorAPI#getAuthorizedUsers() - Returns a list of all users defined in the config.
» ProtectorAPI#getAuthorizedOppedUsers() - Returns all configured users who are marked as allowedOp = true.
» ProtectorAPI#getOnlineAuthorizedUsers() - Returns a list of currently online players that have allowedOp = true
» ProtectorAPI#getAuthorizedUsernames() - Returns the usernames of all authorized OP users.
» ProtectorAPI#hasWhitelistedGroup(Player, String) - Checks if the user has a specific whitelisted group.
» ProtectorAPI#hasAnyWhitelistedGroup(Player) - Returns true if the user has any whitelisted group.
» ProtectorAPI#getAddressHistory(Player) - Gets the stored (hashed) IP history for the user.
» ProtectorAPI#getGeoHistory(Player) - Gets the stored geolocation history for the user.
» ProtectorAPI#getOnlineAuthorizedUsersMap() - Returns a map of authorized online players: { playerName -> playerUUID }.
» ProtectorAPI#getUsersInGroup(String) - Returns all configured users assigned to a given whitelisted group.
» ProtectorAPI#isItemIllegal(ItemStack) - Evaluates an item against the NBT and enchantment security limits, returning true if it violates the configuration.
» ProtectorAPI#isWordBlocked(String) - Checks if the provided text triggers the plugin's blocked-word regex filter.
» ProtectorAPI#isCommandBlocked(String) - Checks if the specified command is entirely blacklisted by the configuration.
» ProtectorAPI#isIpWhitelistedForStaff(UUID, String) - Validates if a staff member's current IP address matches their strict IP lock.
» ProtectorAPI#addAuthorizedUser(User) - Adds a new authorized user to the configuration (or overwrites an existing one) and automatically saves the config.
» ProtectorAPI#removeAuthorizedUser(UUID) - Removes an authorized user from the configuration by UUID and automatically saves the config.
```

#### 🗓️Events

| Event Class                     | Fired When...                                                        | Cancelling the event will...                                       |
| ------------------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------ |
| UnauthorizedOpEvent             | A player tries to run `/op` on someone who isn't whitelisted.        | Allow the command to go through and prevent punishments.           |
| UnauthorizedOpCheckEvent        | The background task detects an unauthorized OP.                      | Temporarily allow the user to keep their OP status for that cycle. |
| IllegalItemInterceptEvent       | A chunk-ban item, crash book, or illegal enchant is interacted with. | Allow the player to keep and use the item.                         |
| StaffCommandWatchEvent          | A staff member uses a monitored command.                             | Prevent the discord webhook alert from being sent.                 |
| UnauthorizedGamemodeChangeEvent | An unauthorized player enters Creative mode.                         | Allow the player to remain in Creative mode.                       |
| TextFilterInterceptEvent        | A player types a blocked word in chat, on a sign, or in a book.      | Allow the text to be sent/placed without alerting staff.           |
| BlacklistedPermissionJoinEvent  | A player joins with a forbidden permission node (like `*`).          | Prevent the plugin from punishing the player.                      |
|                                 |                                                                      |                                                                    |

#### ❓Plugin Example

```
package <your package>

import dev.mantic.protector.api.ProtectorAPI;
import dev.mantic.protector.api.events.TextFilterInterceptEvent;
import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;
import org.bukkit.inventory.ItemStack;
import org.bukkit.entity.Player;

public class ProtectorIntegrationListener implements Listener {

    @EventHandler
    public void onBlockedWord(TextFilterInterceptEvent event) {
        Player player = event.getPlayer();
        
        // Let admins bypass the chat filter entirely
        if (player.hasPermission("myplugin.filter.bypass")) {
            event.setCancelled(true); 
        }
    }
    
    public void giveItemSafely(Player player, ItemStack item) {
        // Use the API to check if Protector thinks the item is malicious
        if (ProtectorAPI.isItemIllegal(item)) {
            player.sendMessage("We tried to give you a reward, but it was flagged as unsafe!");
            return;
        }
        
        player.getInventory().addItem(item);
    }
}
```

#### :camera\_with\_flash: Media