
Better IP Filter
Lightweight and fast IP whitelist filter for Paper 1.21.x.
- Загрузки
- 117
- Подписчики
- 7
- Обновлён
- 22 июня 2026 г.
- Лицензия
- MIT
Опубликован 15 января 2026 г.
Better IP Filter
Better IP Filter is a lightweight and efficient IP whitelist plugin designed for Minecraft Paper servers. It performs early IP validation during the login process and blocks connections from non-whitelisted IP addresses with minimal performance impact.
The plugin is intentionally minimalistic and focused on reliability, performance, and ease of use.
✨ Features
- IP whitelist filtering on player join
- Early connection check using
AsyncPlayerPreLoginEvent - Extremely lightweight and fast
- Toggleable filtering without server restart
- IPv4 validation
- Persistent storage (
ips.yml) - No external dependencies
- Fully compatible with LuckPerms (Bukkit permissions)
⚙️ How It Works
- Player IP is checked before the player fully joins the server
- Allowed IPs are stored in memory for O(1) lookup
- If the IP is not whitelisted, the connection is denied immediately
- Designed to add no noticeable overhead even on busy servers
🧾 Commands
| Command | Description |
|---|---|
/ipf add <ip> |
Add an IP to the whitelist |
/ipf remove <ip> |
Remove an IP from the whitelist |
/ipf list |
Show all whitelisted IPs |
/ipf on |
Enable IP filtering |
/ipf off |
Disable IP filtering |
🔐 Permissions
| Permission | Description |
|---|---|
betteripfilter.admin |
Full access |
betteripfilter.add |
Add IPs |
betteripfilter.remove |
Remove IPs |
betteripfilter.list |
View whitelist |
betteripfilter.toggle |
Enable / disable filter |
Permissions are standard Bukkit permissions and work seamlessly with LuckPerms.
Ченджлог
1.4.4Релиз1.21.9, 1.21.10, 1.21.11 · 22 июня 2026 г.
Added
- Added
/ipf check <ip>to show whether an IP is allowed and which whitelist entry matches it. - Added
/ipf addtemp <entry> <duration> [note]for temporary in-memory whitelist entries. - Added optional notes for permanent whitelist entries via
/ipf add <entry> [note]. - Added deny counters to
/ipf statusfor not-whitelisted, proxy, rate-limit, and failsafe denies. - Added tab completion for new commands and temporary durations.
- Added README proxy setup examples for standalone Paper, trusted proxy, Velocity, and invalid empty
PROXY_GATE.
Changed
/ipf addand/ipf removenow report normalized whitelist entries in command responses./ipf listnow shows one entry per line with optional note and temporary expiration details.- Updated plugin metadata and documentation for the new commands.
- Bumped version to
1.4.4.
Security
- Hardened webhook destination validation by resolving webhook hosts before sending and blocking local/private DNS results when
webhook.allow-local-addressesisfalse.
Compatibility
- No IPv6 support added in this release.
- Existing
ips.ymllist format remains compatible. - Temporary entries are memory-only and do not survive server restarts.
1.4.3Релиз1.21.9, 1.21.10, 1.21.11 · 22 мая 2026 г.
Security
- Hardened webhook URL validation.
- Localhost and private literal IPv4 webhook targets are now blocked by default.
- Added
webhook.allow-local-addressesfor trusted local webhook relays. - Sanitized denied log fields to prevent unsafe control characters in log output.
- Improved JSON escaping for webhook payloads.
Config
- Reworked
config.ymlcomments to make proxy, failsafe, rate limit, logging, and webhook settings easier to understand. - Added clearer safety notes for
DENY_ALL,PROXY_GATE, denied logs, and webhook payloads. - Added a warning when
PROXY_GATEis enabled with an empty trusted proxy list.
Optimization
- Cached the global filtering enabled flag during config load instead of reading config on every login check.
Full Changelog: https://github.com/AREKKUZZERA/Better-IP-Filter/compare/1.4.2...1.4.3
1.4.2Релиз1.21.9, 1.21.10, 1.21.11 · 20 мая 2026 г.
Fixed
- Added validation for unsafe config values.
- Invalid
failsafe.modenow falls back toDENY_ALL. - Invalid
proxy.modenow falls back toDIRECT. - Restricted denied log file names to safe plain file names.
- Webhook URLs now reject user-info and fragments.
1.4.1Релиз1.21.9, 1.21.10, 1.21.11 · 27 апреля 2026 г.
Fixed
- Fixed IPv4 parsing edge case where
128.0.0.0could be treated as invalid because it collided with the internal invalid sentinel. - Fixed IP checks for signed Java
intboundary values, including addresses in the128.0.0.0+range. - Fixed webhook handling so invalid webhook URLs no longer risk breaking the async notifier worker.
Improved
- Added safer IPv4 parsing API internally.
- Improved CIDR validation coverage for
/0,/16,/32, and high-range IPv4 addresses. - Improved default
config.ymlreadability with clearer sections, examples, and security warnings. - Prevented binary resources such as PNG files from being Maven-filtered during builds.
Added
- Added JUnit 5 test setup.
- Added regression tests for IPv4 parsing, CIDR math, rate limiting with edge IPs, and webhook URL validation.
Security
- Documented sensitive denied-log behavior in config comments.
- Clarified
PROXY_GATE, Velocity forwarding, andALLOW_ALLfailsafe risks.
Full Changelog: https://github.com/AREKKUZZERA/Better-IP-Filter/compare/1.4.0...1.4.1
1.4.0Релиз1.21.9, 1.21.10, 1.21.11 · 28 марта 2026 г.
🔧 Modrinth & CI/CD
- Добавлена полноценная интеграция с Modrinth (Minotaur plugin 2.8.7)
- Явно указаны поддерживаемые версии Minecraft: 1.21 – 1.21.11
- Добавлены лоадеры: Paper, Folia
- Настроена автоматическая публикация через GitHub Actions (
mvn modrinth:publish) - Версия плагина теперь синхронизируется через
${project.version}(Maven filtering)
🐛 Исправления ошибок
⚙️ Core / Concurrency
RateLimiter
- Исправлен data race в
AttemptBucket - Потокобезопасность теперь гарантируется через
ConcurrentHashMap.compute - Исправлена логика для невалидных IP (больше не блокируются навсегда)
- Исправлен data race в
WebhookNotifier
- Устранён race condition в
maybeLogDropStats - Поле
lastStatLogMillisтеперь используется корректно из worker-потока
- Устранён race condition в
🌐 Network / Proxy
IpFilterListener
Исправлена логика proxy gate
- Недоверенные прокси теперь всегда блокируются
- Ранее при
ALLOW_ALLмогли проходить без логирования
Удалена ошибка, при которой пустой список trusted proxies = доверие всем
🧪 Tests
IpMathSelfCheck
- Исправлена сортировка диапазонов IP
- Используется
Integer.compareUnsignedвместо signed сравнения
🧾 Logging
BetterIpFilterPlugin
- Устранено дублирование
formatDeniedLine
- Устранено дублирование
🚀 Улучшения производительности и кода
Ленивая генерация строки deny-лога (если логирование отключено — строка не создаётся)
Упрощена логика
onEnable(inline executor setup)WebhookNotifierswitchвместо if-chain вescapeJson- Оптимизирован
buildPayload(использует String concat → JDK 21 оптимизирует)
🧹 Рефакторинг
IpStore
Убрано дублирование через:
commitResult(...)setUnavailable(...)ensureDataFolder()
parseEntryсделанstatic
IpfCommand
- Исправлен порядок валидации аргументов (сначала корректность IP)
- Упрощена логика (меньше вложенности, ранние return)
- Оптимизирован
reloadhandler
IpfTabCompleter
- Используется
List.of(...)вместоArrays.asList(...) filterPrefixсделанstatic
🧠 Поведенческие изменения (важно)
- Недоверенные прокси теперь никогда не пропускаются, независимо от failsafe режима
- Пустой список trusted proxies = никто не доверен (раньше — все доверены)
- Невалидные IP больше не попадают под rate limit
⚠️ Breaking Changes
- Из API удалён метод
hasTrustedForwardedIps - Изменено поведение proxy trust (может потребовать обновления конфигурации)
1.3.0Бета1.21.9, 1.21.10, 1.21.11 · 27 марта 2026 г.
Better IP Filter 1.21.X (1.3.0)
🚀 Improvements
- Обновлён
plugin.ymlдля Paper1.21.11 - Упрощён парсинг IPv4
- Улучшена логика
IpStore - Добавлен rollback при неудачных
add()/remove() - Улучшены сообщения конфигурации и валидации
- Невалидные
trusted-forwarded-ipsтеперь пропускаются с предупреждением - Команды и kick-сообщения переведены на Adventure
Component
🐛 Fixes
- Исправлен критический баг
Ipv4.INVALID = -1 INVALIDзаменён наInteger.MIN_VALUE- Исправлена обработка IP с отрицательным
int-представлением - Исправлен edge-case для
255.255.255.255 - Исправлена работа
IntHashSetпри удалении элементов из probe-chain - Убран deprecated
ChatColor - Убран
@SuppressWarnings("deprecation") ipStrв listener теперь всегда без порта- Исправлен
canMergeдля0xFFFFFFFF
🧪 Tests
- Добавлен
testBroadcastIpNotInvalid - Добавлен
testIntHashSetTombstone
⚠️ Requirements
- Paper 1.21+
🧠 Internal
isValidIpпереименован вisValidEntryswitchобновлён до expression switchCollectors.toList()заменён на.toList()
1.2.0Бета1.21.9, 1.21.10, 1.21.11 · 27 января 2026 г.
1.2.0 – Correctness & QoL Update
🔐 Security & Correctness
- Fixed and hardened proxy mode behavior
- Enforced trusted proxy validation for Bungee / Velocity setups
- Added explicit deny reason for untrusted proxy connections
- Clarified proxy handling (relies on Paper / proxy forwarding)
⚙️ QoL & Control
- Added
/ipf status— live plugin diagnostics - Added
/ipf reload— reload config and whitelist without restart - Improved command feedback for add/remove operations
- Safer, readable output for
/ipf list
⚡ Performance
- Reduced rate-limiter cleanup overhead under high load
- Preserved fully async, non-blocking login checks
📦 Compatibility
- Fully compatible with 1.1.x
- No config changes required (new options have safe defaults)
- Paper 1.21.x · Java 21+
1.1.0Бета1.21.9, 1.21.10, 1.21.11 · 18 января 2026 г.
1.1.0
Security & Reliability Update
- Added proxy-aware IP handling (Bungee / Velocity)
- Implemented connection rate limiting (anti-bruteforce)
- Added fail-safe mode for whitelist loading failures
- Added support for CIDR blocks and IP ranges
- Added audit logging for denied connections
- Added optional webhook notifications for security events
Compatibility: Paper 1.21–1.21.11 · Java 21+
Комментарии
Загружаем…