feat: add Minecraft proxy and refresh dependencies

This commit is contained in:
Loki 2026-10-16 23:04:41 +02:00
parent a4d0880a0a
commit cfaad47948
Signed by: boba
GPG key ID: 6CDE87BC9A778D97
47 changed files with 2671 additions and 1005 deletions

View file

@ -56,7 +56,7 @@ Authorization: Bearer <token>
}
```
Redis недоступен → пустой список.
Если Redis недоступен, API возвращает `503 Service Unavailable`.
---
@ -68,13 +68,16 @@ Redis недоступен → пустой список.
{
"items": [
{"target": "1.2.3.4", "type": "ip", "reason": "manual_ban",
"created_at": "...", "expires_at": null}
"created_at": "2026-10-16T12:00:00+00:00", "expires_at": "2026-10-16T13:00:00+00:00"}
],
"total": 42
}
```
Источник: Redis set `rampart:blacklist`. Пагинации и фильтров нет.
Источник: Redis set `rampart:blacklist` и hash `rampart:blacklist:metadata`.
Метаданные содержат причину, время создания и абсолютный срок истечения; API
скрывает истёкшие записи. Старые set-записи без метаданных получают один
ограниченный срок в пять минут при первом чтении или восстановлении edge.
### `POST /api/v1/blacklist` 🔒
@ -82,10 +85,24 @@ Redis недоступен → пустой список.
// Request
{"target": "1.2.3.4", "type": "ip", "reason": "manual_ban", "duration_secs": 3600}
// Response 200/201 — запись добавлена в Redis set
// Response 200 — запись и метаданные атомарно сохранены в Redis, а событие
// с duration_secs и expires_at_unix опубликовано в rampart:blacklist:events.
```
Edge-ноды подхватывают ban при следующей синхронизации блэклиста.
Edge подписывается на Pub/Sub перед загрузкой снимка из Redis. Поэтому события,
пришедшие во время загрузки, будут применены после снимка. При старте и после
переподключения активные Redis-баны восстанавливаются с оставшимся TTL; новые
события используют абсолютный срок и игнорируются, если он уже прошёл. Старый
формат события только с `duration_secs` продолжает поддерживаться.
### `DELETE /api/v1/blacklist` 🔒
```json
{"target": "1.2.3.4"}
```
Удаляет только Redis-бан и его метаданные, затем публикует событие unban.
Локальные баны детекторов хранятся отдельно и этим запросом не снимаются.
---
@ -110,7 +127,6 @@ Edge-ноды подхватывают ban при следующей синхр
Честно, на текущий момент в API **нет**:
- удаления записей blacklist (только add/list);
- drain нод через API (есть только CLI `rampart-cli drain`);
- webhooks, metrics summary, challenge management;
- регистрации нод через `POST /api/v1/nodes`;

View file

@ -6,14 +6,23 @@
## 1. Edge (`config.toml`, путь задаётся `RAMPART_CONFIG`)
```toml
# Корневые поля должны стоять до первой TOML-секции.
whitelist = ["127.0.0.1", "::1"]
[bind]
address = "0.0.0.0"
port = 25565
[backend]
# Список TCP-бэкендов (addr:port). Обязателен непустой, адреса валидируются.
# Список TCP-бэкендов (addr:port). Для Minecraft нужен ровно один backend.
upstreams = ["127.0.0.1:25566"]
[protocol.minecraft]
enabled = true
max_frame_bytes = 8192
timeout_secs = 5
send_proxy_protocol = false
[workers]
count = 4
@ -47,10 +56,24 @@ port = 9090
enabled = false # PoW challenge, OFF по умолчанию
difficulty = 4
whitelist = ["127.0.0.1", "::1"] # только IP-адреса, валидируются при парсинге
# Входящий PROXY v2 от известного TCP DDoS-прокси; включай только если
# прокси действительно отправляет этот заголовок.
[proxy_protocol]
ingress_enabled = false
trusted_cidrs = []
ingress_timeout_ms = 750
max_header_bytes = 512
```
Этот пример выбирает Minecraft Java и требует сборки с `protocol-minecraft`.
Для HTTP используй сборку `protocol-http` и удали `[protocol.minecraft]`.
Все секции опциональны — при отсутствии используются дефолты из таблицы выше.
Для ingress PROXY v2 укажи сети именно прокси в `trusted_cidrs`; включение без
доверенной сети отклоняется при чтении конфига.
`send_proxy_protocol` отправляет заголовок на Paper backend; прежнее имя
`proxy_protocol` внутри `[protocol.minecraft]` остаётся допустимым alias.
## 2. Manager (переменные окружения)
@ -73,7 +96,8 @@ Manager всегда слушает `0.0.0.0:8080`.
| `geoip` | ❌ | GeoIP lookup (maxminddb) |
| `xdp` | ❌ | Загрузка XDP-программы через libbpf-rs |
| `io-uring` | ❌ | splice/io_uring I/O |
| `protocol-http` | ❌ | Резерв под HTTP-плагин (пока пустой) |
| `protocol-http` | ❌ | HTTP/1.1 handler; включай только для HTTP upstream |
| `protocol-minecraft` | ❌ | Minecraft Java TCP handshake и проксирование |
Пример: `cargo build --release --features xdp --bin rampart`.
@ -87,4 +111,4 @@ clang -O2 -g -target bpf -c xdp/core/universal_filter.c -o /tmp/universal_filter
---
*Версия: 2.0 | Август 2026*
*Версия: 2.1 | Октябрь 2026*

View file

@ -27,9 +27,9 @@
## 3. Быстрый старт — Edge
```bash
# Сборка
# Сборка edge для Minecraft Java
git clone https://github.com/loki5512344/rampart.git && cd rampart
cargo build --release --bin rampart
cargo build --release --features protocol-minecraft --bin rampart
# Установка
sudo cp target/release/rampart /usr/local/bin/
@ -64,10 +64,10 @@ systemctl enable --now rampart
journalctl -u rampart -f
```
> ⚠️ В ядре нет ни одной реализации протокольного обработчика: реестр протоколов
> пуст, и `rampart` при старте требует feature `protocol-http` или внешний
> ProtocolHandler (см. src/bin/rampart.rs). До появления плагинов edge-нода
> запускается только в исследовательских целях.
Minecraft-конфиг рассчитан на один Paper backend. Если включён
`protocol.minecraft.send_proxy_protocol`, включи `proxies.proxy-protocol: true` в
Paper и закрой backend-порт firewall-ом от всех, кроме Rampart. Для подробной
схемы с домашним сервером и защищённым VDS см. [Minecraft Java guide](minecraft-java.md).
## 4. Быстрый старт — Manager
@ -107,4 +107,4 @@ docker compose -f deploy/docker-compose.yml up -d
---
*Версия: 2.0 | Август 2026*
*Версия: 2.1 | Октябрь 2026*

95
docs/minecraft-java.md Normal file
View file

@ -0,0 +1,95 @@
# Rampart перед Minecraft Java
Rampart can proxy Minecraft Java Edition over TCP. It checks the bounded Java
handshake, forwards the original bytes unchanged, and then tunnels the
connection to one Paper backend. This is an early integration: it does not
replace an upstream DDoS scrubbing network.
## Build and configure
Build the edge binary with the Minecraft handler:
```sh
cargo build --release --features protocol-minecraft --bin rampart
```
Use one backend per edge node. For a Paper server on the same host, the sample
uses port `25566`; change it to the address reachable over your private network
or WireGuard tunnel.
```toml
whitelist = ["127.0.0.1", "::1"]
[bind]
address = "0.0.0.0"
port = 25565
[backend]
upstreams = ["10.20.0.5:25566"]
[protocol.minecraft]
enabled = true
max_frame_bytes = 8192
timeout_secs = 5
send_proxy_protocol = true
[pow]
enabled = false
```
PoW must stay disabled for Minecraft Java: the current PoW exchange is plain
text and is not part of the Minecraft protocol. Configure the edge firewall to
allow public TCP `25565`, and keep Prometheus `9090` and the Paper backend port
private.
## Preserve player IPs safely
When `send_proxy_protocol` is enabled, Rampart prepends a PROXY protocol v2 header
before the Minecraft handshake. On Paper, enable `proxies.proxy-protocol` in
`config/paper-global.yml`. Paper documents this option for HAProxy or similar
proxies: [global configuration](https://docs.papermc.io/paper/reference/global-configuration/).
The PROXY header is not authenticated. Put the edge-to-Paper connection on a
private network or WireGuard and firewall Paper's backend port to accept only
the trusted edge IPs. Never expose a PROXY-enabled Paper port to arbitrary
clients: they could forge the address in the header.
If Rampart runs in Docker, the container needs access to the configured backend
address. The included sample image builds `protocol-minecraft`; the sample
config keeps PROXY protocol disabled until Paper and the backend firewall are
configured together.
## DDoS boundary
Rampart can reject connections and apply local rate limits after packets reach
the edge host. It cannot keep a home uplink available when an attack saturates
that link. Put a Minecraft-aware DDoS proxy or a provider with game DDoS
filtering in front of the VDS, hide the home's public address, and carry
accepted traffic to the home server through a restricted tunnel. Two ordinary
VDS instances without upstream filtering do not provide that protection.
For a DDoS provider that sends PROXY protocol v2, enable inbound parsing only
for that provider's TCP source ranges:
```toml
[proxy_protocol]
ingress_enabled = true
# Replace these documentation ranges with the provider's actual ranges.
trusted_cidrs = ["198.51.100.0/24", "2001:db8:1234::/48"]
ingress_timeout_ms = 750
max_header_bytes = 512
```
Rampart rejects connections from unlisted peers when ingress mode is enabled,
and it applies per-IP limits and bans using the verified header source address.
Keep the allowlist current with the provider's published ranges. The header is
not cryptographically authenticated, so never trust arbitrary internet peers.
This MVP accepts PROXY v2 TCP4/TCP6 address headers without TLVs; confirm that
format with the provider before enabling ingress mode.
XDP operates on the network peer address and is not used to ban the claimed
player address on this path.
The Minecraft handler supports status and login handshake states and forwards
the connection as a TCP tunnel. It does not inspect encrypted login/game
packets or implement Velocity forwarding. Bedrock Edition uses UDP and is not
supported by this handler.