SunshineCommandGuard
隐藏命令补全、阻止命令执行,并保护你的插件列表不被泄露——所有设置均基于 LuckPerms 用户组 进行独立作用域控制,并提供一个管理工具,让你在开启或关闭任何功能之前,就能确切知道为何某个特定命令会被允许或拦截。
大多数服务器都运行着数十个插件,每个插件都会注册命令、子命令以及命名空间别名,而普通玩家本不该看到这些内容。/plugins 会将你的整个插件栈暴露给任何询问者;命令补全(Tab-complete)则会泄露你所有的管理员工具。SunshineCommandGuard 在不触碰你 LuckPerms 中已有权限节点的前提下,同时关闭了这两条信息泄露渠道。
目录
功能特性
- Tab 补全过滤:通过
PlayerCommandSendEvent 实现——玩家只能看到他们有权使用的命令。
命令不仅从建议列表中消失;客户端甚至不会得知其存在。
- 执行拦截:玩家无权执行的命令会表现为未知命令,并显示完全自定义的消息。
- 服务器隐私:隐藏
/plugins、/pl、/ver、/version、/about 以及 ?
帮助别名,替换为你编写的消息(保留原样的 /help:被阻止的玩家会被引导至该命令)。
- 防枚举保护:移除带命名空间的命令标签,阻止直接执行带命名空间的命令,并过滤由客户端插件扫描器使用的直接
/version//plugins 补全探测。提供显式的命名空间例外以兼容其他插件。
- 按组配置文件:基于 LuckPerms 权限解析的组(
sunshine.cmdguard.group.<name>),支持 inherit(继承)和 priority(优先级),因此一个 staff 组可以扩展 vip,而 vip 又扩展 default,无需重复任何一行配置。
- 灵活匹配:支持字面名称、
regex: 正则表达式模式、否定 !entries(拒绝优先)、以及 plugin:<Name> 展开语法,可在单行内获取某插件注册的所有命令。
- 隐藏别名:保持命令完全可运行,但使其从 Tab 补全中消失,适用于你不希望公开宣传但仍需正常工作的别名。
- 参数级规则:每个命令的
args 允许/拒绝列表,例如允许玩家使用 /gamemode survival 但不允许 /gamemode creative。在 Tab 补全 和 执行时均强制生效(2.0.0+),包括带命名空间的形式及 /execute ... run。
- 实时验证:
/cmdguard test <player> <command> 会在你启用任何设置之前,打印出已解析的组、匹配的规则,以及该命令可见或被拦截的原因。
- 一键生成配置:
/cmdguard generate 扫描你的在线服务器,并生成一份经过审查的初始配置文件(config.generated.yml):无需权限即可使用的命令归入 default,受权限限制的命令归入 staff。将需要的内容复制到 config.yml 即可。
- 交互式安装向导:
/cmdguard setup 会在聊天栏引导你回答三个可点击的问题(初始列表、隐私设置、权限同步),并自动为你写入 config.yml。
- 精确的配置验证:每次
/cmdguard reload 都会将你的列表与在线服务器的实际状态进行交叉检查,并指出具体条目中的问题:拼写错误、未知的插件、错误的正则表达式、未知的组或未加载的世界(groups.default.commands[1]: 'spwan' matches no registered command)。
- 自我诊断:
/cmdguard diagnose [player] 捕捉常见错误:过滤器未开启、使用 OP 账号测试、零可见命令、配置警告等——并附带实时统计(“可见:340 个命令中的 12 个”)。
- 权限同步模式:可选地要求每个命令都拥有独立的 Bukkit 权限节点,这样当玩家的等级无法执行某些命令时,这些命令会自动从他们的可用列表中移除,无需手动维护列表。
- 临时授权:
/cmdguard grant <player> <command> <10m|2h|1d> 可为特定命令开放有限时间(用于活动或客服案例),/cmdguard ungrant 可收回权限。无需编辑配置文件。授权匹配精确的命令令牌:对 plugins 的授权并不涵盖 bukkit:plugins。
- 按世界分组:可将任意组限制在特定世界中(
worlds: [arena]),并在切换世界时自动刷新配置文件。
- 拦截监控:记录所有被拦截的尝试,并/或在限流的情况下通知在线工作人员,确保侦察行为不会被忽视。
- Discord 警报 (2.0.0):通过 Webhook 将被拦截的尝试发布到 Discord 频道,具有速率限制,默认禁用 @提及,并可配置仅报告
/pl、/ver 和带命名空间的探测请求。
- 一键迁移 (2.0.0):
/cmdguard import commandwhitelist 将 CommandWhitelist 的配置转换为可供审查的 config.imported.yml。
- PlaceholderAPI 支持 (2.0.0):提供
%cmdguard_group%、%cmdguard_visible%、%cmdguard_filter%,可用于计分板、Tab 列表和全息图。
- Folia 支持 (2.0.0):同一个 jar 包即可在 Paper 和 Folia 上运行。
- 实时网页编辑器 (2.0.0):运行
/cmdguard editor 可在 Sunshine Live Web Studio 中打开你服务器真实的命令列表,通过一次点击切换命令状态(Allow、Hide in Tab、Block),并通过 /cmdguard apply <code> 实时推送更改(每个服务器均可享受 3天免费试用,之后可通过 SunshineCommandGuard Pro 永久解锁)。你的 pro-key 和 Discord Webhook URL 永远不会上传(2.0.1+)。
- Velocity 网络支持 (Pro):代理级别的命令过滤(
/server、/glist、/send 等)仅在 SunshineCommandGuard Pro 中提供(参见 Velocity networks (Pro))。
- 更新通知:当 GitHub 上有新版本发布时,控制台和管理员上线时会收到通知(仅通知功能;详见下文)。
- 包含 bStats 指标:已重新定位,确保不会与其他插件的副本发生冲突。
截图
以下四张截图均来自真实的生产服务器,而非演示实例——其中的拦截和隐私消息均为该服务器自身的文本,可在 config.yml 中完全自定义。
|
|
允许 — 白名单内的命令可正常进行 Tab 补全。 |
隐藏 — 不在建议列表中,甚至不被客户端自身的命令树识别——但如果完整输入仍可运行。 |
拦截 — 不在该组成员列表中的命令对客户端不可见,并被拒绝为未知命令。 |
服务器隐私 — /plugins 返回自定义消息,而非真实的插件列表。 |
依赖
- Paper、Folia 或基于 Paper 的分支 1.21.x 至 26.x,Java 21 或更高版本(26.x 服务器运行 Java 25)
- 可选:PlaceholderAPI 用于占位符
- LuckPerms 为可选(
softdepend):若未安装,所有玩家将回退至 default 组。
- 拥有 bypass 权限或 OP 状态的玩家将跳过所有过滤——务必使用非 OP 账号进行测试。
安装
- 将
SunshineCommandGuard-2.0.1.jar 放入你的 plugins/ 文件夹并启动服务器一次
(这将创建默认的 config.yml)。
- 在游戏中运行
/cmdguard setup 并回答三个问题,然后运行 /cmdguard generate
以扫描你的服务器配置至 config.generated.yml,或在浏览器中使用
在线配置构建器 构建初始配置文件。
- 在启用之前验证:使用非 OP 测试账号执行
/cmdguard test <player> <command>(或 /cmdguard diagnose)。
- 设置
enabled: true,然后运行 /cmdguard reload。
从 CommandWhitelist 迁移?保留其文件夹于 plugins/ 中,运行
/cmdguard import commandwhitelist,并在覆盖前审查 config.imported.yml。
⚠️ 警告
配置错误的过滤器可能导致玩家完全看不到任何命令。因此该插件默认附带 enabled: false。在设置 enabled: true 之前,请务必检查你的用户组并为默认组玩家运行 /cmdguard test。
配置示例
极简模式 —— 隐藏除少数命令外的所有内容:
enabled: true
bypass-permission: "sunshine.cmdguard.bypass"
groups:
default:
priority: 0
blocked-message: "<red>Unknown command."
commands:
- help
- spawn
- msg
- "regex:^(msg|tell|w|r|reply)$"
- "!op"
- "!stop"
hidden: []
args: {}
基于用户组的访问控制与继承:
groups:
default:
priority: 0
blocked-message: "<red>Unknown command."
commands: [help, spawn, msg]
hidden: []
args: {}
vip:
priority: 10
inherit: [default]
commands: [hat, nick, workbench]
hidden: [ecraft, ehat]
args:
gamemode:
allow: [survival, creative]
deny: []
staff:
priority: 50
inherit: [vip]
commands: ["plugin:WorldEdit"]
hidden: []
args: {}
服务器隐私保护 —— 替换 /plugins、/ver 和帮助别名(纯 /help 故意保持可见:它是被拦截消息引导玩家使用的后备选项):
privacy:
plugins-command:
enabled: true
message: "<gold>My Server <grey>| <white>Server information is private."
aliases: [plugins, pl, "bukkit:pl", "bukkit:plugins", ver, version, about, icanhasbukkit]
help-command:
enabled: true
message: "<yellow>Type <white>/help <yellow>for a list of commands."
aliases: ["?", "bukkit:help", "minecraft:help"]
客户端插件扫描防护 —— 隐藏带命名空间的别名并阻止直接补全探测。此部分仅在全局过滤器启用时生效:
anti-enumeration:
enabled: true
hide-namespaced-commands: true
block-namespaced-execution: true
block-completion-probes: true
namespace-allowlist: []
为了实现纵深防御,请在 spigot.yml 中也设置 commands.send-namespaced: false。
该插件会在 /cmdguard diagnose 中报告此项服务器设置。
复制粘贴配方
EssentialsX 生存服 —— 仅限常用玩家命令,无其他内容:
enabled: true
groups:
default:
priority: 0
blocked-message: "<red>Unknown command."
commands:
- help
- spawn
- home
- sethome
- delhome
- tpa
- tpaccept
- tpdeny
- msg
- mail
- pay
- balance
- kit
- warp
- afk
- rules
- "regex:^(msg|tell|w|r|reply)$"
- "!op"
- "!stop"
hidden: []
args: {}
worlds: []
小游戏大厅 + 生存世界 —— 大厅命令仅在其所属世界中存在:
enabled: true
groups:
default:
priority: 0
blocked-message: "<red>Unknown command."
commands: [help, spawn, msg]
hidden: []
args: {}
worlds: []
minigames:
priority: 20
inherit: [default]
commands: [queue, leave, spectate, party]
hidden: []
args: {}
worlds: [arena, lobby]
严格模式 —— 极短的列表加上权限同步,使得命令还需要其对应的 Bukkit 权限节点,且新安装的插件在未获允许前保持隐藏:
enabled: true
permission-sync: true
groups:
default:
priority: 0
blocked-message: "<red>Unknown command."
commands: [help, rules]
hidden: []
args: {}
worlds: []
匹配规则: 条目匹配不区分大小写,可带或不带前导 /,带命名空间的标签(如 essentials:heal)也能匹配其基础名称(heal)。!entry 表示拒绝(拒绝始终优先于任何允许),regex:<pattern> 允许完整匹配的模式,plugin:<Name> 会展开为该插件注册的所有命令。hidden 条目可运行但不会在 Tab 补全中显示建议——用于你不希望推广的别名。当启用 anti-enumeration.hide-namespaced-commands 时,带命名空间的标签将从命令树和 Tab 补全中隐藏。当启用 anti-enumeration.block-namespaced-execution 时,除非命名空间列在 namespace-allowlist 中,否则直接执行也会被阻止。
可选的全局模式(旧配置可安全加载;缺失 anti-enumeration 部分的配置将获得安全的默认值):
# 同时要求每个命令拥有独立的 Bukkit 权限节点。
permission-sync: false
monitoring:
log-blocked: false # 记录控制台上的每次拦截尝试
notify-staff: false # 在被拦截尝试时向在线工作人员发送消息
notify-permission: "sunshine.cmdguard.notify"
notify-cooldown-seconds: 5 # 每位玩家的冷却时间
updates:
enabled: true # GitHub Releases 检查(仅通知)
notify-console: true
notify-admins: true
按世界分组的组 — 带有 worlds 的组仅在该世界生效(为空表示所有世界)。
如果 default 本身限制了世界,则会收到配置警告,因为那些世界之外的玩家将不会被过滤:
groups:
minigames:
priority: 20
inherit: [default]
commands: [queue, leave, spectate]
hidden: []
args: {}
worlds: [arena, lobby]
命令与权限
| 命令 |
权限 |
描述 |
/cmdguard reload |
sunshine.cmdguard.admin |
重新加载配置、重建索引、清除缓存 |
/cmdguard refresh <player> |
sunshine.cmdguard.admin |
清除单个玩家的缓存并重新发送命令树 |
/cmdguard test <player> <command> [args] |
sunshine.cmdguard.admin |
显示命令所属的组、可见性、原因(及参数规则) |
/cmdguard debug |
sunshine.cmdguard.admin |
在运行时暂停/恢复过滤(不写入配置) |
/cmdguard dump |
sunshine.cmdguard.admin |
将所有注册的命令写入 commands_dump.yml |
/cmdguard generate |
sunshine.cmdguard.admin |
生成一份可供审查的检查就绪的初始配置到 config.generated.yml |
/cmdguard import commandwhitelist |
sunshine.cmdguard.admin |
将 CommandWhitelist 配置转换为 config.imported.yml |
/cmdguard grant <player> <command> <30s|10m|2h|1d> |
sunshine.cmdguard.admin |
临时允许执行某个命令(仅内存保留,重启后丢失) |
/cmdguard ungrant <player> [command] |
sunshine.cmdguard.admin |
撤销一个或所有临时授权 |
/cmdguard setup |
sunshine.cmdguard.admin |
交互式聊天设置(仅限玩家):初始列表、隐私、同步、防枚举 |
/cmdguard diagnose [player] |
sunshine.cmdguard.admin |
检查常见错误,显示实时计数和防枚举状态 |
/cmdguard editor |
sunshine.cmdguard.admin |
上传已注册的命令及 config.yml 至 Live Web Studio(3天免费试用 + Pro) |
/cmdguard apply <code> |
sunshine.cmdguard.admin |
备份 config.yml 并应用保存在 Live Web Studio 中的更改 |
| 权限 |
默认值 |
描述 |
sunshine.cmdguard.bypass |
op |
绕过所有命令过滤 |
sunshine.cmdguard.admin |
op |
允许使用 /cmdguard |
sunshine.cmdguard.notify |
op |
接收被拦截命令的管理员通知 |
sunshine.cmdguard.group.<name> |
— |
将玩家分配到 <name> 组(通过 LuckPerms) |
Discord 警报
monitoring:
discord:
enabled: true
webhook-url: "https://discord.com/api/webhooks/..."
cooldown-seconds: 10 # 每位玩家
max-per-minute: 20 # 整个 webhook
only-reconnaissance: false # true = 仅 /pl, /ver 和命名空间探测
每条警报格式如下:? **Steve** tried `/plugins` — privacy (group: default)。@提及功能已禁用,请求是异步进行的,且 webhook URL 绝不会记录到日志中。
PlaceholderAPI
| 占位符 |
值 |
%cmdguard_group% |
玩家优先级最高的组 |
%cmdguard_visible% |
玩家可见的命令数量 |
%cmdguard_filter% |
enabled 或 disabled |
Velocity 网络(Pro)
Velocity 自身的代理命令(如 /server、/glist、/send 等)由代理处理,
永远不会到达后端 Paper 服务器,因此后端插件无法隐藏或阻止它们。
SunshineCommandGuard Pro 添加了具有相同分组规则的配套 Velocity 代理插件
(字面量、regex:、!deny、inherit、priority)、sunshine.cmdguard.group.<name>
LuckPerms 权限以及 /cmdguardv reload|test 诊断工具,同时将所有后端命令传递给 Paper 插件。
常见问题
这能替代 LuckPerms 吗? 不能。LuckPerms 仍然控制玩家有权运行什么。
SunshineCommandGuard 控制玩家看到什么,以及当他们尝试超出其组范围的操作时会发生什么——
权限系统和可见性过滤器解决的是两个不同的问题,本插件仅解决后者。
OP 和管理员会受到影响吗? 不会,这是设计使然——sunshine.cmdguard.bypass 默认为
op,因此操作员始终可以看到并运行所有内容。请使用真实的非 OP 账号进行测试,否则
当你实际上并未被应用过滤器时,它看起来像是坏了。
如果一个玩家已经知道某个被隐藏的命令会发生什么? 它仍然可以运行。hidden
仅从自动补全建议中移除命令;它与 commands 是不同的列表,后者控制命令是否真正运行。
对于不想宣传的别名请使用 hidden,而对于真正想禁止的命令请使用普通的阻断列表。
客户端仍能否枚举插件? 防枚举盾牌移除了命名空间的命令标签并阻止了常见的直接补全探测。
但这并不能保证插件行为永远无法被推断出来;公开命令、消息、资源包数据和其他服务器行为
仍可能泄露信息。不要依赖客户端品牌检测,因为修改过的客户端可以伪造其品牌。
这会影响服务器性能吗? 过滤仅在加入服务器和 /cmdguard reload 时运行,而不是在每次按键时——
每个玩家的命令树只重建一次,而不是为每次 Tab 键按下重新计算。
我可以不使用 LuckPerms 吗? 可以。LuckPerms 是软依赖;如果没有它,所有玩家都会解析为
default 组。
兼容性
基于 Paper 1.21.4 API (Java 21) 构建。已在干净的 Paper 26.2 服务器上测试。
支持 Paper、Folia (2.0.0+,通过每玩家实体调度) 及兼容的 Paper 分支。
未测试较旧或较新的服务器版本——请在您的设置下遇到问题或成功时提交 Issue。
开发者 API (1.4.0+)
CommandGuard 为 Sunshine Sentinel 等集成触发公共监控事件:
com.sunshine.commandguard.api.event.CommandGuardBlockedEvent — 在命令尝试被确切地阻止一次后触发,包含 getPlayerId()、getPlayerName()、getCommandToken()、getReason()(类型为 com.sunshine.commandguard.api.BlockReason)、getTimestamp() 和 getWorld()。BlockReason 为以下之一:PRIVACY、NAMESPACE_PROTECTION、PERMISSION_SYNC、GROUP_LIST 以及(2.0.0+)ARGUMENT_RULE。
- 不可取消 —— 监听器仅观察决策结果,永远无法解除对命令的阻止。
- Token 是标准化后的根命令,所有参数均被剥离且命名空间保留:
/plugins → plugins,/BUKKIT:Plugins → bukkit:plugins,/minecraft:help foo bar → minecraft:help。
- 隐私保护: 事件中永远不会出现任何命令参数、聊天内容、IP 地址或凭据。
从源代码构建
.\gradlew.bat build # 需要 JDK 21,输出文件位于 build/libs/SunshineCommandGuard-2.0.1.jar
.\gradlew.bat test # 单元测试 (JUnit 5)
上传的 jar 包必须是 shadowJar 的输出结果(build/libs/...),其中捆绑了 bStats(已重定位至 com.sunshine.cmdguard.bstats,以确保与其他插件无冲突)。build.ps1 仍作为原作者机器上的快速本地编译脚本保留。
指标统计
本插件通过 bStats 收集匿名使用统计数据。服务器管理员可以在 plugins/bStats/config.yml 中选择退出。
更新通知
CommandGuard 可在每次服务器启动时检查 GitHub Releases 是否有新版本。SunshineCommandGuard 绝不会自动下载或安装更新。
updates:
enabled: true
notify-console: true
notify-admins: true
设置 updates.enabled: false 将完全禁用外部更新请求——不会发起任何 HTTP 调用,也不会显示任何消息。持有 sunshine.cmdguard.admin 权限的管理员在加入服务器时会在每个服务器会话期间收到一次通知,并附带指向发布页面的可点击链接。该检查仅为通知性质:不下载、不重启、无遥测数据。
关键词
command hide, tab complete, plugin hide, pl hide, command blocker, permissions, luckperms
许可证
GPL-3.0 — 请参阅 LICENSE。衍生作品必须保持开源。
欢迎提交问题报告 (Issues) 和拉取请求 (Pull requests)。
SunshineCommandGuard
Hide commands from tab-complete, block their execution, and keep your plugin list private —
all scoped per LuckPerms group, with an admin tool that tells you exactly why any given
command is allowed or blocked before you ever flip the switch.
Most servers run dozens of plugins, and every one of them registers commands, sub-commands,
and namespaced aliases that regular players were never meant to see. /plugins hands out your
whole stack to anyone who asks. Tab-complete leaks every admin tool you have. SunshineCommandGuard
closes both doors without touching a single permission node you already have in LuckPerms.
Table of contents
Features
- Tab-complete filtering via
PlayerCommandSendEvent — players only see what they may use.
The command doesn't just disappear from suggestions; the client never learns it exists.
- Execution blocking — a command the player may not run behaves as an unknown command,
with a fully customizable message.
- Server privacy — hides
/plugins, /pl, /ver, /version, /about and the ?
help aliases behind a message you write (plain /help stays: blocked players are sent
there).
- Anti-enumeration shield — removes namespaced command labels, blocks direct namespaced
execution, and filters direct
/version//plugins completion probes used by client-side
plugin scanners. Explicit namespace exceptions are available for compatibility.
- Per-group profiles — groups resolved from LuckPerms permissions
(
sunshine.cmdguard.group.<name>), with inherit and priority so a staff group can
extend vip, which extends default, without repeating a single line.
- Flexible matching — literal names,
regex: patterns, negative !entries (deny always
wins), and plugin:<Name> expansion to grab every command a plugin registers in one line.
- Hidden aliases — commands that stay fully runnable but disappear from tab-complete, for
the aliases you don't want advertised but still need to work.
- Argument-level rules — per-command
args allow/deny lists, e.g. let players use
/gamemode survival but not /gamemode creative. Enforced in tab-complete and on
execution (2.0.0+), including namespaced forms and /execute ... run.
- Live verification —
/cmdguard test <player> <command> prints the resolved group, the
matching rule, and the reason a command is visible or blocked, before you enable anything.
- One-command setup —
/cmdguard generate scans your live server and writes a reviewed
starter config (config.generated.yml): commands nobody needs a permission for go to
default, permission-gated ones to staff. Copy what you want into config.yml.
- Interactive setup wizard —
/cmdguard setup walks you through three clickable questions
in chat (starter list, privacy, permission-sync) and writes config.yml for you.
- Precise config validation — every
/cmdguard reload cross-checks your lists against the
live server and points at exact entries: typos, unknown plugins, bad regex, unknown groups
and unloaded worlds (groups.default.commands[1]: 'spwan' matches no registered command).
- Self-diagnosis —
/cmdguard diagnose [player] catches the classic mistakes: filter off,
testing with an OP account, zero visible commands, config warnings — with live counts
("Visible: 12 of 340 commands").
- Permission-sync mode — optionally also require each command's own Bukkit permission node,
so players automatically lose commands their rank can't run, with zero list maintenance.
- Temporary grants —
/cmdguard grant <player> <command> <10m|2h|1d> opens one command for
a limited time (events, support cases), /cmdguard ungrant takes it back. No config edits.
Grants match the exact command token: a grant for plugins does not cover bukkit:plugins.
- Per-world groups — restrict any group to specific worlds (
worlds: [arena]), with the
profile refreshing automatically on world change.
- Block monitoring — log every blocked attempt and/or ping online staff (throttled), so
reconnaissance attempts don't go unnoticed.
- Discord alerts (2.0.0) — post blocked attempts to a Discord channel through a webhook,
rate-limited, with pings disabled and an option to report only
/pl, /ver and namespaced
probes.
- Migrate in one command (2.0.0) —
/cmdguard import commandwhitelist converts a
CommandWhitelist config into a reviewable config.imported.yml.
- PlaceholderAPI (2.0.0) —
%cmdguard_group%, %cmdguard_visible%, %cmdguard_filter%
for scoreboards, tab lists and holograms.
- Folia support (2.0.0) — runs on Paper and Folia from the same jar.
- Live Web Editor (2.0.0) — run
/cmdguard editor to open your server's real command list in the Sunshine Live Web Studio, toggle commands with one click (Allow, Hide in Tab, Block), and push changes live with /cmdguard apply <code> (includes a 3-day free trial for every server, then unlocked indefinitely with SunshineCommandGuard Pro). Your pro-key and Discord webhook URL are never uploaded (2.0.1+).
- Velocity networks (Pro) — proxy-level command filtering (
/server, /glist, /send, …)
is available in SunshineCommandGuard Pro (see Velocity networks (Pro)).
- Update notifications — console and admin-join notice when a newer GitHub release
exists (notify-only; see below).
- bStats metrics included, relocated so it never conflicts with another plugin's copy.
Screenshots
All four below are taken on a live production server, not a demo instance — the block and
privacy messages are that server's own text, fully customizable in config.yml.
|
|
Allowed — a whitelisted command completes normally. |
Hidden — not suggested, not even recognized by the client's own command tree — but still runs if typed out in full. |
Blocked — a command outside the group's list is invisible to the client and rejected as unknown. |
Server privacy — /plugins returns a custom message instead of the real plugin list. |
Requirements
- Paper, Folia or a Paper fork 1.21.x through 26.x, Java 21 or newer (26.x servers run Java 25)
- Optional: PlaceholderAPI for placeholders
- LuckPerms is optional (
softdepend): without it, every player falls back to the
default group.
- Players with the bypass permission or OP status skip all filtering — always test with a
non-OP account.
Installation
- Drop
SunshineCommandGuard-2.0.1.jar into your plugins/ folder and start the server once
(this creates the default config.yml).
- Run
/cmdguard setup in-game and answer three questions, run /cmdguard generate
to scan your server into config.generated.yml, or build a starter config in your browser with
the Online Config Builder.
- Verify before enabling:
/cmdguard test <player> <command> (or /cmdguard diagnose),
with a non-OP test account.
- Set
enabled: true, then /cmdguard reload.
Coming from CommandWhitelist? Keep its folder in plugins/, run
/cmdguard import commandwhitelist, and review config.imported.yml before copying it over.
⚠️ Warning
A misconfigured filter can leave players with no visible commands at all. The plugin
therefore ships with enabled: false. Always review your groups and run /cmdguard test for
a default-group player before setting enabled: true.
Configuration examples
Minimal — hide everything except a few commands:
enabled: true
bypass-permission: "sunshine.cmdguard.bypass"
groups:
default:
priority: 0
blocked-message: "<red>Unknown command."
commands:
- help
- spawn
- msg
- "regex:^(msg|tell|w|r|reply)$"
- "!op"
- "!stop"
hidden: []
args: {}
Group-based access with inheritance:
groups:
default:
priority: 0
blocked-message: "<red>Unknown command."
commands: [help, spawn, msg]
hidden: []
args: {}
vip:
priority: 10
inherit: [default]
commands: [hat, nick, workbench]
hidden: [ecraft, ehat]
args:
gamemode:
allow: [survival, creative]
deny: []
staff:
priority: 50
inherit: [vip]
commands: ["plugin:WorldEdit"]
hidden: []
args: {}
Server privacy — replace /plugins, /ver and help aliases (plain /help stays
visible on purpose: it is the fallback the blocked message points players to):
privacy:
plugins-command:
enabled: true
message: "<gold>My Server <grey>| <white>Server information is private."
aliases: [plugins, pl, "bukkit:pl", "bukkit:plugins", ver, version, about, icanhasbukkit]
help-command:
enabled: true
message: "<yellow>Type <white>/help <yellow>for a list of commands."
aliases: ["?", "bukkit:help", "minecraft:help"]
Client-side plugin scanner protection — hide namespaced aliases and block direct completion
probes. This section is active only when the top-level filter is enabled:
anti-enumeration:
enabled: true
hide-namespaced-commands: true
block-namespaced-execution: true
block-completion-probes: true
namespace-allowlist: []
For defense in depth, set commands.send-namespaced: false in spigot.yml as well. The
plugin reports this server setting in /cmdguard diagnose.
Copy-paste recipes
EssentialsX survival server — the usual player commands, nothing else:
enabled: true
groups:
default:
priority: 0
blocked-message: "<red>Unknown command."
commands:
- help
- spawn
- home
- sethome
- delhome
- tpa
- tpaccept
- tpdeny
- msg
- mail
- pay
- balance
- kit
- warp
- afk
- rules
- "regex:^(msg|tell|w|r|reply)$"
- "!op"
- "!stop"
hidden: []
args: {}
worlds: []
Minigame lobby + survival worlds — lobby commands only exist in their worlds:
enabled: true
groups:
default:
priority: 0
blocked-message: "<red>Unknown command."
commands: [help, spawn, msg]
hidden: []
args: {}
worlds: []
minigames:
priority: 20
inherit: [default]
commands: [queue, leave, spectate, party]
hidden: []
args: {}
worlds: [arena, lobby]
Strict mode — tiny lists plus permission-sync, so a command also needs its own
Bukkit permission node and new plugins stay hidden until you allow them:
enabled: true
permission-sync: true
groups:
default:
priority: 0
blocked-message: "<red>Unknown command."
commands: [help, rules]
hidden: []
args: {}
worlds: []
Matching rules: entries are matched case-insensitively, with or without a leading /, and
namespaced labels (essentials:heal) also match their base name (heal). !entry denies (deny
always wins over any allow), regex:<pattern> allows full-match patterns, plugin:<Name>
expands to every command that plugin registers. hidden entries are runnable but never
suggested in tab-complete — use them for aliases you don't want advertised. When
anti-enumeration.hide-namespaced-commands is enabled, namespaced labels are hidden from
the command tree and tab completion. When anti-enumeration.block-namespaced-execution is
enabled, direct execution is also blocked unless the namespace is listed in namespace-allowlist.
Optional top-level modes (old configs load safely; a missing anti-enumeration section receives
secure defaults):
# Also require each command's own Bukkit permission node.
permission-sync: false
monitoring:
log-blocked: false # log every blocked attempt to console
notify-staff: false # message online staff on blocked attempts
notify-permission: "sunshine.cmdguard.notify"
notify-cooldown-seconds: 5 # per-player throttle
updates:
enabled: true # GitHub Releases check (notify-only)
notify-console: true
notify-admins: true
Per-world groups — a group with worlds only matches there (empty = everywhere).
If default itself is world-restricted you get a config warning, because players outside
those worlds would be unfiltered:
groups:
minigames:
priority: 20
inherit: [default]
commands: [queue, leave, spectate]
hidden: []
args: {}
worlds: [arena, lobby]
Commands and permissions
| Command |
Permission |
Description |
/cmdguard reload |
sunshine.cmdguard.admin |
Reload config, rebuild index, clear caches |
/cmdguard refresh <player> |
sunshine.cmdguard.admin |
Drop one player's cache, resend command tree |
/cmdguard test <player> <command> [args] |
sunshine.cmdguard.admin |
Show groups, visibility, reason (and argument rule) for a command |
/cmdguard debug |
sunshine.cmdguard.admin |
Suspend/resume filtering at runtime (no config write) |
/cmdguard dump |
sunshine.cmdguard.admin |
Write all registered commands to commands_dump.yml |
/cmdguard generate |
sunshine.cmdguard.admin |
Write a review-ready starter config to config.generated.yml |
/cmdguard import commandwhitelist |
sunshine.cmdguard.admin |
Convert a CommandWhitelist config into config.imported.yml |
/cmdguard grant <player> <command> <30s|10m|2h|1d> |
sunshine.cmdguard.admin |
Temporarily allow one command (memory-only, lost on restart) |
/cmdguard ungrant <player> [command] |
sunshine.cmdguard.admin |
Revoke one or all temporary grants |
/cmdguard setup |
sunshine.cmdguard.admin |
Interactive chat setup (players only): starter list, privacy, sync, anti-enumeration |
/cmdguard diagnose [player] |
sunshine.cmdguard.admin |
Common-mistake check with live counts and anti-enumeration status |
/cmdguard editor |
sunshine.cmdguard.admin |
Upload registered commands & config.yml to the Live Web Studio (3-day free trial + Pro) |
/cmdguard apply <code> |
sunshine.cmdguard.admin |
Back up config.yml and apply changes saved in the Live Web Studio |
| Permission |
Default |
Description |
sunshine.cmdguard.bypass |
op |
Bypasses all command filtering |
sunshine.cmdguard.admin |
op |
Allows use of /cmdguard |
sunshine.cmdguard.notify |
op |
Receives blocked-command staff notifications |
sunshine.cmdguard.group.<name> |
— |
Assigns a player to group <name> (via LuckPerms) |
Discord alerts
monitoring:
discord:
enabled: true
webhook-url: "https://discord.com/api/webhooks/..."
cooldown-seconds: 10 # per player
max-per-minute: 20 # whole webhook
only-reconnaissance: false # true = only /pl, /ver and namespaced probes
Each alert looks like ? **Steve** tried `/plugins` — privacy (group: default). Mentions
are disabled, requests are asynchronous, and the webhook URL is never written to the log.
PlaceholderAPI
| Placeholder |
Value |
%cmdguard_group% |
The player's highest-priority group |
%cmdguard_visible% |
Number of commands the player can see |
%cmdguard_filter% |
enabled or disabled |
Velocity networks (Pro)
Velocity's own proxy commands (/server, /glist, /send, …) are handled on the proxy and
never reach the backend Paper server, so a backend plugin cannot hide or block them.
SunshineCommandGuard Pro adds the companion Velocity proxy plugin with the same group
rules (literals, regex:, !deny, inherit, priority), sunshine.cmdguard.group.<name>
LuckPerms permissions, and /cmdguardv reload|test diagnostics, while passing all backend
commands through to the Paper plugin.
Frequently asked questions
Does this replace LuckPerms? No. LuckPerms still controls what a player is allowed to
run. SunshineCommandGuard controls what a player sees and what happens when they try
something outside their group — a permission system and a visibility filter are different
problems, and this plugin only solves the second one.
Will OPs and admins be affected? No, by design — sunshine.cmdguard.bypass defaults to
op, so operators always see and can run everything. Test with a real non-OP account, or the
filter will look broken when it's actually just not being applied to you.
What happens to a hidden command if a player already knows it? It still runs. hidden
only removes a command from tab-complete suggestions; it's a different list from commands,
which controls whether the command runs at all. Use hidden for aliases you don't want to
advertise, and the plain block list for commands you actually want to deny.
Can a client still enumerate plugins? The anti-enumeration shield removes namespaced
command labels and blocks the common direct completion probes. It is not a guarantee that
plugin behavior can never be inferred; public commands, messages, resource-pack data and
other server behavior can still reveal information. Do not rely on client-brand detection,
because modified clients can spoof their brand.
Does this affect server performance? Filtering runs on join and on /cmdguard reload, not
on every keystroke — the client's command tree is rebuilt once per player, not recomputed for
every tab press.
Can I use this without LuckPerms? Yes. LuckPerms is a soft dependency; without it every
player resolves to the default group.
Compatibility
Built against the Paper 1.21.4 API (Java 21). Tested on a clean Paper 26.2 server.
Paper, Folia (2.0.0+, via per-player entity scheduling) and compatible Paper forks are
supported. Older/newer server versions are untested — please open an issue with what works or
doesn't on your setup.
Developer API (1.4.0+)
CommandGuard fires a public monitoring event for integrations such as
Sunshine Sentinel:
com.sunshine.commandguard.api.event.CommandGuardBlockedEvent — fired exactly once after a
command attempt is definitively blocked, with getPlayerId(), getPlayerName(),
getCommandToken(), getReason() (com.sunshine.commandguard.api.BlockReason),
getTimestamp() and getWorld(). BlockReason is one of PRIVACY,
NAMESPACE_PROTECTION, PERMISSION_SYNC, GROUP_LIST and (2.0.0+) ARGUMENT_RULE.
- Non-cancellable — listeners observe the decision, they can never unblock a command.
- The token is the normalized root command with all arguments stripped and the namespace
preserved:
/plugins → plugins, /BUKKIT:Plugins → bukkit:plugins,
/minecraft:help foo bar → minecraft:help.
- Privacy: no command arguments, chat content, IPs or credentials ever appear in the event.
Building from source
.\gradlew.bat build # needs JDK 21, output: build/libs/SunshineCommandGuard-2.0.1.jar
.\gradlew.bat test # unit tests (JUnit 5)
The uploaded jar must be the shadowJar output (build/libs/...), which bundles bStats
(relocated to com.sunshine.cmdguard.bstats so it never conflicts with other plugins).
build.ps1 remains as a fast local-compile script for the original author's machine.
Metrics
This plugin collects anonymous usage statistics via bStats.
Server owners can opt out in plugins/bStats/config.yml.
Update notifications
CommandGuard can check GitHub Releases for a newer version, once per server
start. SunshineCommandGuard never automatically downloads or installs updates.
updates:
enabled: true
notify-console: true
notify-admins: true
Setting updates.enabled: false disables the external update request entirely —
no HTTP call is made and no message is shown. Admins holding
sunshine.cmdguard.admin are notified once per server session on join, with a
clickable link to the release page. The check is notify-only: no downloads, no
restarts, no telemetry.
Keywords
command hide, tab complete, plugin hide, pl hide, command blocker, permissions, luckperms
License
GPL-3.0 — see LICENSE. Derivative works must stay open source.
Issues and pull requests are welcome.
评论 0
登录后参与评分
还没有评论,来抢沙发吧