Illegal Scanner
A powerful anti-cheat utility for Paper servers — detect illegal, overpowered, and suspicious items that cannot be obtained in vanilla survival.
一款强大的 Paper 服务器反作弊工具 — 检测原版生存无法获得的超模/非法/可疑物品。
Features / 功能
| Feature | 功能 |
|---|---|
| 7 validation engines covering enchantments, attributes, components, potions, books, fireworks & containers | 7 个校验引擎：附魔、属性修饰、数据组件、药水、书册、烟花、容器 |
| Progressive full-server scan — low TPS impact, resumable sessions | 渐进式全服扫描 — 低 TPS 影响，支持暂停/恢复 |
| Real-time monitor engine — event-driven detection of newly placed items | 实时监测引擎 — 事件驱动，自动检测新放置的物品 |
| Interactive GUI viewer — browse violations, teleport to locations, grab item snapshots | 交互式 GUI 查看器 — 浏览违规、传送定位、提取物品快照 |
| Text reports — chat-based paginated reports for every scan scope | 文本报告 — 聊天框分页报告，覆盖所有扫描范围 |
| 6 whitelist types — player, item, chunk, area, residence, world | 6 种白名单 — 玩家、物品、区块、区域、领地、世界 |
| Watch list — flag items by Material ID regardless of NBT | 监控列表 — 按 Material ID 标记物品，无视 NBT |
| Hot-reloadable config & messages — no restart needed | 配置/消息热重载 — 无需重启服务器 |
| Restricted item copying — GUI copy requires authorization | 受限物品复制 — GUI 复制物品需授权 |
| WorldGuard & Residence support — scan protected regions directly | WorldGuard / Residence 支持 — 直接扫描领地 |
Quick Start / 快速开始
# 1. Drop the jar into plugins/ and restart
# 将 jar 放入 plugins/ 并重启
# 2. Check the item in your hand
# 检查手中物品
/is check item
# 3. Scan the chunk you're standing in
# 扫描当前所在区块
/is scan chunk
# 4. Start a full-server scan
# 启动全服扫描
/is scan full
# 5. View results in GUI
# 在 GUI 中查看结果
/is view fullRequirements / 环境要求
| Requirement | 要求 |
|---|---|
| Paper 1.20.6+ | Server / 服务端 |
| Java 21+ | Java |
| SQLite (bundled, no setup needed / 内置，无需配置) | Storage / 存储 |
| WorldGuard, Residence (optional soft-depend / 可选软依赖) | Optional / 可选 |
Installation / 安装
- Download
illegal-scanner-1.2.4.jarfrom Releases. 从 Releases 下载illegal-scanner-1.2.4.jar。 - Place it in your server's
plugins/folder. 放入服务器的plugins/文件夹。 - Restart the server (or run
/reload confirm). 重启服务器（或执行/reload confirm）。 - Configuration and database auto-generate at
plugins/illegal-scanner/. 配置文件和数据库自动生成于plugins/illegal-scanner/。
Commands / 命令
All commands use /is (alias: /illegalscanner).
所有命令使用 /is（别名：/illegalscanner）。
Scan / 扫描 — illegalscanner.scan
| Command | Description |
|---|---|
/is scan chunk |
Scan current chunk / 扫描当前区块 |
/is scan player [-online|-offline|-all] [name] |
Scan player inventory / 扫描玩家背包 |
/is scan area <x1> <z1> <x2> <z2> [world] |
Scan rectangular area / 扫描矩形区域 |
/is scan res <region> |
Scan WorldGuard/Residence region / 扫描领地 |
/is scan world [world|all_world] [loaded|unloaded|all] |
Scan world chunks / 扫描世界区块 |
/is scan full |
Progressive full-server scan / 渐进式全服扫描 |
/is scan pause|resume|stop|restart <sessionId> |
Manage scan sessions / 管理扫描会话 |
Check / 快速检测 — illegalscanner.inspect
| Command | Description |
|---|---|
/is check item |
Validate held item (not recorded to DB) / 校验手中物品（不记录） |
/is check player [name] |
Check player inventory + ender chest / 检查玩家背包+末影箱 |
/is check chunk |
Quick chunk check (not recorded to DB) / 快速区块检查（不记录） |
View (GUI) / 查看（GUI） — illegalscanner.report
| Command | Description |
|---|---|
/is view chunk |
Current chunk violations / 当前区块违规 |
/is view player [name] |
Player violation list / 玩家违规列表 |
/is view world [world] |
World violation overview / 世界违规概览 |
/is view area <x1> <z1> <x2> <z2> [world] |
Area violation overview / 区域违规概览 |
/is view res <plugin> <region> [world] |
Region violation overview / 领地违规概览 |
/is view full |
Server-wide violation overview / 全服违规概览 |
/is view scan [sessionId] |
Scan session list/details / 扫描会话列表/详情 |
/is view record <SCAN|MONITOR> <id> |
Single violation record / 单条违规详情 |
/is view item [itemHash] |
Violation by item type / 按物品类型查看 |
Inventory (GUI) / 背包查看（GUI） — illegalscanner.report
| Command | Description |
|---|---|
/is inventory player [name] |
View player backpack, armor & ender chest (3-page GUI, offline supported) / 查看玩家背包、装备、末影箱（3页GUI，支持离线） |
/is inventory chunk [x z] [world] |
View all containers in a chunk (offline/unloaded supported via MCA) / 查看区块内所有容器（支持离线/未加载区块） |
/is inventory world [world] |
Browse all containers in loaded chunks of a world / 浏览世界已加载区块的所有容器 |
/is inventory container <x> <y> <z> |
Read-only view of a block container (chest, furnace, hopper, etc.) / 只读查看方块容器（箱子、熔炉、漏斗等） |
/is inventory entity <selector> |
Read-only view of entity inventory/equipment (supports @e selector & UUID) / 只读查看实体背包/装备（支持@e选择器及UUID） |
Report (Text) / 报告（文本） — illegalscanner.report
| Command | Description |
|---|---|
/is report chunk |
Chunk text report / 区块文本报告 |
/is report player <name> [page] |
Player text report / 玩家文本报告 |
/is report item [hash] [page] |
Item type report / 物品类型报告 |
/is report scan [sessionId] [page] |
Scan session report / 扫描会话报告 |
/is report record <SCAN|MONITOR> <id> |
Full violation details / 完整违规详情 |
/is report area <x1> <z1> <x2> <z2> [world] [page] |
Area text report / 区域文本报告 |
/is report res <plugin> <region> [world] [page] |
Region text report / 领地文本报告 |
/is report world [world] [page] |
World text report / 世界文本报告 |
Monitor / 实时监测 — illegalscanner.admin
| Command | Description |
|---|---|
/is monitor enable|disable|status |
Toggle monitor engine / 开关监测引擎 |
Config / 配置管理 — illegalscanner.admin
| Command | Description |
|---|---|
/is config reload |
Reload config, messages & monitor / 重载配置、消息和监测 |
/is config list |
List all config key-values / 列出所有配置项 |
/is config rules ... |
Tune validation rules / 动态调整检测规则 |
/is config monitor ... |
Configure monitor engine / 配置监测引擎参数 |
/is config scan ... |
Configure scan behavior / 配置扫描行为 |
Whitelist / 白名单 — illegalscanner.admin
| Type | Description |
|---|---|
player |
Whitelist players / 白名单玩家 |
item |
Whitelist specific items (by hash) / 白名单特定物品（按 hash） |
chunk |
Whitelist chunks / 白名单区块 |
area |
Whitelist coordinate areas / 白名单坐标区域 |
res |
Whitelist WorldGuard/Residence regions / 白名单领地 |
world |
Whitelist entire worlds / 白名单整个世界 |
Watch List / 监控列表 — illegalscanner.admin
| Command | Description |
|---|---|
/is watchlist add <materialID> |
Add material to watch list / 添加 Material 到监控 |
/is watchlist remove <materialID> |
Remove material / 移除 Material |
/is watchlist list|clear |
List or clear / 列表或清空 |
Misc / 其他
| Command | Description |
|---|---|
/is give <item_hash> |
Generate item from hash (debugging) / 根据 hash 生成物品（调试） |
/is reload |
Reload config & messages / 重载配置和消息 |
/is status |
Service status overview / 服务状态概览 |
/is history chunk|player ... |
Historical violation records / 历史违规记录 |
Permissions / 权限
| Permission | Scope | Default |
|---|---|---|
illegalscanner.admin |
All commands (parent node) / 所有命令 | OP |
illegalscanner.scan |
/is scan ... |
OP |
illegalscanner.report |
/is report, /is view, /is history |
OP |
illegalscanner.inspect |
/is check ... |
OP |
illegalscanner.notify |
Receive admin alerts / 接收管理员通知 | OP |
Validation Rules / 检测规则
The plugin uses a whitelist philosophy: if it can't be obtained in vanilla survival, it's flagged. 插件采用白名单原则：只要原版生存无法获得，就判定为非法。
1. Enchantment Validator / 附魔校验器
- Level exceeds vanilla maximum (e.g. Sharpness VI) 等级超过原版上限（如锋利 VI）
- Conflicting enchantments coexist (e.g. Silk Touch + Fortune) 互斥附魔共存（如精准采集 + 时运）
- Incompatible item type (e.g. Efficiency on a sword) 附魔不兼容物品类型（如剑上的效率）
- Duplicate enchantment IDs 重复附魔 ID
2. Attribute Validator / 属性修饰校验器
- Attribute not in vanilla whitelist for that item type 属性不在该物品类型的原版白名单中
- Attribute value differs from vanilla 属性值与原版不一致
- Wrong slot, UUID, or operation type 槽位、UUID 或操作类型异常
3. Component Validator / 数据组件校验器
| Component | Severity | Reason |
|---|---|---|
unbreakable |
ILLEGAL | Creative/commands only / 仅创造/命令 |
lore |
ILLEGAL | No vanilla survival source / 原版生存无来源 |
item_name |
ILLEGAL | Commands only / 仅命令可覆写 |
custom_name > 50 chars |
ILLEGAL | Anvil limit / 铁砧限制 |
custom_name non-italic |
ILLEGAL | Anvil always italic / 铁砧命名永久斜体 |
custom_name JSON injection |
ILLEGAL | Contains {"text":"..."} patterns |
custom_name zero-width chars |
SUSPICIOUS | Unicode control characters / 零宽空格等 |
can_place_on / can_destroy |
ILLEGAL | Adventure mode only / 冒险模式专属 |
max_stack_size overflow |
ILLEGAL | Exceeds vanilla stack limit / 超过原版堆叠上限 |
max_damage mismatch |
ILLEGAL | Doesn't match item type / 与物品类型耐久不一致 |
custom_model_data |
SUSPICIOUS | Custom model present / 存在自定义模型数据 |
hide_tooltip |
SUSPICIOUS | May hide illegal attributes / 可能掩盖非法属性 |
4. Potion Validator / 药水校验器
- Amplifier exceeds max (default: level II / amplifier=1) 效果等级超标（默认最大 II 级）
- Duration exceeds max (default: 8 minutes) 持续时间超标（默认最大 8 分钟）
- Impossible effect combinations (Instant Damage + Instant Health, etc.) 不可能的药水效果组合（瞬间伤害 + 瞬间治疗等）
- Unknown effect IDs / 未知效果 ID
- Custom color without effects / 自定义颜色但无对应效果
5. Book Validator / 书册校验器
- Pages > 100 / 页数超标
- Single page > 1000 chars / 单页过长
- Author > 16 chars / 作者名过长
- Title > 32 chars / 标题过长
6. Firework Validator / 烟花校验器
- Flight duration > 3 / 飞行时间超标
- Explosions > 10 / 爆炸效果超标
7. Container Validator / 容器校验器
- Recursively validates contents of shulker boxes & bundles 递归检查潜影盒和收纳袋内容物
- Flags
container_lootcomponent (loot tables don't survive block break) 标记container_loot组件（方块破坏后战利品表不保留）
Severity / 严重级别
| Level | Meaning |
|---|---|
| ILLEGAL | Definitely unobtainable in survival — action required / 确定生存无法获得 — 需处理 |
| SUSPICIOUS | Unusual characteristics — manual review recommended / 可疑特征 — 建议人工审查 |
| PASS | Item is clean / 物品合法 |
Configuration / 配置
Config file: plugins/illegal-scanner/config.yml. All settings can be changed via /is config without restart.
配置文件位于 plugins/illegal-scanner/config.yml，所有参数可通过 /is config 命令动态修改。
Key Settings / 关键配置项
scan:
full_scan_enabled: true # Auto-start full scan on boot / 启动时自动全扫
full_scan_chunks_per_tick: 1 # Chunks per tick (increase = faster, higher TPS cost)
# 每 tick 区块数（增加 = 更快，更高 TPS 开销）
thread_pool_size: 4 # Thread pool for parallel processing / 线程池大小
scan_player_inventories: true # Scan player inventories / 扫描玩家背包
scan_player_enderchests: true # Scan player ender chests / 扫描末影箱
scan_shulker_boxes: true # Scan shulker box contents / 扫描潜影盒
scan_item_frames: true # Scan item frames / 扫描物品展示框
scan_armor_stands: true # Scan armor stands / 扫描盔甲架
validation:
enforce_max_levels: true # Enforce enchant max levels / 附魔等级限制
enforce_conflicts: true # Enforce enchant conflicts / 附魔冲突检测
enforce_item_compatibility: true # Enforce enchant compatibility / 附魔兼容性检测
flag_unbreakable: true # Flag unbreakable items / 标记不可破坏物品
flag_lore_presence: true # Flag lore-bearing items / 标记含 lore 物品
flag_item_name_presence: true # Flag renamed items / 标记被覆写名称的物品
custom_name_max_length: 50 # Max custom name length / 铁砧命名最大长度
enforce_stack_limits: true # Enforce stack limits / 堆叠限制检测
enforce_attribute_limits: true # Enforce attribute limits / 属性修饰限制
potion_max_amplifier: 1 # Max potion amplifier / 药水最大效果等级
potion_max_duration_ticks: 9600 # Max potion duration / 药水最大持续时间
potion_max_effects: 5 # Max effects per potion / 单药水最大效果数
book_max_pages: 100 # Max book pages / 书册最大页数
firework_max_flight: 3 # Max firework flight / 烟花最大飞行时间
firework_max_explosions: 10 # Max firework explosions / 烟花最大爆炸数
monitor:
enabled: false # Enable real-time monitor / 实时监测开关
interval_seconds: 5 # Scan interval / 扫描间隔
flush_seconds: 300 # Dedup window / 去重窗口
retention_days: 7 # Data retention / 数据保留天数
alerts:
console_log: true # Log violations to console / 控制台输出违规
console_log_severity: "ILLEGAL" # ILLEGAL | SUSPICIOUS | ALL
admin_notify: false # Notify online admins / 通知在线管理员Database / 数据库
SQLite database at plugins/illegal-scanner/items.db. Useful queries:
数据库位于 plugins/illegal-scanner/items.db，常用查询：
-- Active illegal items / 活跃非法物品
SELECT id, item_type, player_name, severity
FROM illegal_items WHERE resolved = 0 ORDER BY last_detected DESC;
-- Count by player / 按玩家统计
SELECT player_name, COUNT(*) as cnt
FROM illegal_items WHERE resolved = 0 AND location_type = 'PLAYER'
GROUP BY player_name ORDER BY cnt DESC;
-- Item snapshot for restoration / 物品快照（用于还原）
SELECT item_snapshot FROM illegal_items WHERE id = 1;FAQ / 常见问题
Q: Does this affect server TPS? / 会影响 TPS 吗？
A: Default scan rate (1 chunk/tick) has <5% TPS impact. Single-item validation in event listeners takes <1ms. Adjust full_scan_chunks_per_tick and thread_pool_size for your hardware.
默认扫描速率（1 区块/tick）TPS 影响 <5%。事件监听的单物品校验 <1ms。可根据硬件调整配置。
Q: How are offline players scanned? / 离线玩家如何扫描？
A: The plugin reads world/playerdata/<uuid>.dat NBT files. Use /is scan player -offline <name> for on-demand scanning.
插件读取 world/playerdata/<uuid>.dat 文件。使用 /is scan player -offline <name> 按需扫描。
Q: Can I restore items from the snapshot? / 能从快照恢复物品吗？
A: Yes! Use /is give <item_hash> to recreate the exact item from its stored snapshot.
可以！使用 /is give <item_hash> 从存储的快照完整还原物品。
Q: How do I prevent false positives from legitimate plugin items? / 如何避免合法插件物品误报？ A: Four options / 四种方式：
- Tune rules dynamically:
/is config rules .../ 动态调整规则 - Whitelist specific items:
/is whitelist item add/ 白名单特定物品 - Whitelist players:
/is whitelist player add <name>/ 白名单玩家 - Use watch list to only monitor specific materials / 用监控列表仅追踪特定物品
Q: Watch list vs item whitelist? / 监控列表和物品白名单的区别？ A: Whitelist skips a specific hash entirely. Watch list flags all items of a Material regardless of NBT — use it to track distribution of specific item types. 白名单让特定 hash 完全跳过检查。监控列表标记所有匹配 Material 的物品（无视 NBT），用于追踪特定物品类型的分布。
Q: Does it support BungeeCord/Velocity? / 支持 BungeeCord/Velocity 吗？ A: This is a Bukkit/Paper plugin — install on each backend server. Not supported on proxy. 这是 Bukkit/Paper 插件，安装于每个子服即可，不支持代理端。
Q: Supported Minecraft versions? / 支持的 Minecraft 版本？ A: Built targeting Paper 1.20.6. May work on newer versions but is untested. 编译目标为 Paper 1.20.6，更新版本可能可用但未测试。
Links / 链接
- Source Code / 源码: GitHub
- Issues / 问题反馈: GitHub Issues
- Releases / 下载: GitHub Releases
License / 许可证
All rights reserved. See the repository for license details. 保留所有权利。详见仓库许可证。
The Illegal Scanner Team
