feat!: universal redesign — drop Minecraft stack, single-crate architecture
- remove Java plugins (velocity/paper), dashboard, all MC-specific code
(handshake, death_code, varint, hostname-HMAC); available in history pre-v0.2
- merge crates/* into one package with src/bin/{rampart,rampart-manager,rampart-cli}
- ProtocolHandler trait + registry (no implementations yet), universal PoW kept
- XDP: universal L3/L4 filter (xdp/core/) + pluggable hook API (xdp/hooks/),
fix IPv6 saddr bug; clang build verified
- docs: bilingual knowledge base (docs/kb/: attacks x4, defense-levels,
practice x3), rewrite README/architecture for universal concept
- TODO.md v4.0: <=300-line module limit, competitor benchmark section (ref/)
- deploy/CI/docs cleanup: no MC references, new binary names
cargo build/clippy(-D warnings)/test green (55 tests)
This commit is contained in:
parent
0b53ed720b
commit
15f474486a
GPG key ID:
253067914055423B
179 changed files with 5044 additions and 11519 deletions
224
README.md
224
README.md
|
|
@ -10,13 +10,12 @@
|
|||
|
||||
# Rampart
|
||||
|
||||
6-layer DDoS protection for Minecraft servers.
|
||||
Universal network protection platform (L3/L4/L7 DDoS filtering framework)
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
[English](#english) | [Русский](#russian)
|
||||
|
|
@ -31,95 +30,96 @@
|
|||
|
||||
### Overview
|
||||
|
||||
Rampart filters traffic at kernel level (XDP/eBPF), network level (PoW challenge), and application level (Rust + Java) before it reaches game servers.
|
||||
Rampart filters traffic at three levels before it reaches your service:
|
||||
|
||||
### 6-Layer Architecture
|
||||
- **Kernel level** — XDP/eBPF drops unwanted packets before they reach the Linux TCP stack;
|
||||
- **Network level** — PoW challenge raises the cost of connection floods for any TCP protocol;
|
||||
- **Application level** — Rust userspace core performs L7 handshake analysis, rate limiting and reputation checks.
|
||||
|
||||
Protocol-specific logic lives in **modular protocol plugins**, so the same platform protects VDS, web services, and game servers alike.
|
||||
|
||||
### Architecture
|
||||
|
||||
```
|
||||
Layer 1: XDP/eBPF (C) TCP state machine, SYN throttle, blacklist, UDP drop
|
||||
Layer 2: PoW Challenge (Rust) SHA256 hashcash, dynamic difficulty, anti-handshake-flood
|
||||
⚠️ OFF by default: the current text-challenge protocol is incompatible with
|
||||
vanilla clients, which cannot solve it — enable only with a client mod.
|
||||
Layer 3: Rust Core MC handshake parse, HMAC sign, rate limit, death code
|
||||
Layer 4: Velocity (Java) Domain whitelist, HMAC verify, physics check, CAPTCHA
|
||||
Layer 5: Paper Agent (Java) Redis heartbeat, auto-registration
|
||||
Layer 6: Traffic Intel EWMA thresholds, 168h profiling, reputation
|
||||
┌────────────────────────────────────────────────────────────────────┐
|
||||
│ Layer 1: Kernel / XDP (C) │
|
||||
│ universal TCP state machine · SYN throttle · CIDR black/white │
|
||||
│ lists · UDP policy · pluggable BPF protocol hooks │
|
||||
├────────────────────────────────────────────────────────────────────┤
|
||||
│ Layer 2: Universal PoW Challenge (Rust) │
|
||||
│ SHA256 hashcash · dynamic difficulty │
|
||||
│ works over any TCP protocol ⚠️ OFF by default │
|
||||
├────────────────────────────────────────────────────────────────────┤
|
||||
│ Layer 3: Userspace Core (Rust) │
|
||||
│ L7 handshake analysis · rate limit · HMAC · death-code patterns │
|
||||
├────────────────────────────────────────────────────────────────────┤
|
||||
│ Layer 4: Protocol Plugins (feature crates) │
|
||||
│ minecraft (first plugin) · http (planned) · grpc (planned) │
|
||||
└────────────────────────────────────────────────────────────────────┘
|
||||
Traffic Intel (EWMA thresholds, profiling, reputation)
|
||||
runs across all layers
|
||||
```
|
||||
|
||||
```
|
||||
Атакующий → [XDP/eBPF] → [PoW] → [Rust Core] → [Velocity] → Game Server
|
||||
1 2 3 4
|
||||
Attacker → [XDP/eBPF] → [PoW] → [Userspace Core] → [Plugin] → Your Service
|
||||
1 2 3 4
|
||||
```
|
||||
|
||||
### Components
|
||||
|
||||
| Component | Role | Stack |
|
||||
|-----------|------|-------|
|
||||
| **rampart-core** | Edge node - layers 2+3 | Rust (tokio, socket2, prometheus) |
|
||||
| **rampart-manager** | Management API + Redis sync | Rust (axum, jsonwebtoken, redis) |
|
||||
| **rampart-core** | Edge engine: XDP loader, PoW challenge, L7 filtering, traffic intel | Rust (tokio, libbpf) + C (XDP) |
|
||||
| **rampart-manager** | Management API + Redis sync | Rust (axum, redis) |
|
||||
| **rampart-cli** | CLI tool for operators | Rust (clap) |
|
||||
| **velocity-plugin** | Layer 4 - domain, HMAC, physics, router | Java 21 (Velocity API) |
|
||||
| **paper-plugin** | Layer 5 - Redis heartbeat, auto-reg | Java 21 (Paper API) |
|
||||
| **dashboard** | Web UI - servers, blacklist, nodes | React + Vite + TypeScript |
|
||||
| **protocol plugins** | Protocol-aware filtering as feature crates | Rust |
|
||||
| ↳ `minecraft` | First plugin (MC handshake analysis) | Rust |
|
||||
| ↳ `http`, `grpc` | Planned | Rust |
|
||||
| **docs/kb** | Bilingual knowledge base: attack anatomy, defense levels, practice guides | Markdown |
|
||||
|
||||
### Performance
|
||||
|
||||
Tested on Hetzner CX31 (4 vCPU, 8GB, KVM), Ubuntu 22.04, kernel 5.15
|
||||
|
||||
| Mode | New conn/s | Active conn | CPU |
|
||||
|------|-----------|-------------|-----|
|
||||
| 4 core, epoll | 80k | 200k | ~65% |
|
||||
| 4 core, io_uring | 110k | 260k | ~48% |
|
||||
| XDP drop (generic) | 3-5M pps | - | ~25% |
|
||||
| XDP drop (native) | 15-20M pps | - | ~15% |
|
||||
|
||||
Note: Real L7 throughput (handshake + HMAC + rate limit): ~60-70k conn/s (epoll), ~85-95k (io_uring).
|
||||
|
||||
#### VDS stress test (2026-08-04) — edge-only, loopback
|
||||
|
||||
VDS 2 vCPU / 3.8GB / Ubuntu 22.04, Docker bridge. Edge-only (слои 1–3), без Redis/Velocity/Paper.
|
||||
Атака маскировалась под обычный трафик: 100 source IP, валидные Minecraft handshake.
|
||||
Подробности: [load-test-report.md](docs/research/load-test-report.md), скрипты: [deploy/test/stress](deploy/test/stress).
|
||||
Confirmed numbers only — VDS stress test ([load-test-report.md](docs/research/load-test-report.md)), edge-only setup on loopback, 2 vCPU:
|
||||
|
||||
| Scenario | Result |
|
||||
|----------|--------|
|
||||
| Raw L7 throughput (valid handshake → HMAC → backend) | ~4k conn/s proxied, 100% (121.5k/30s; edge CPU ~179%, 2 cores) |
|
||||
| Defense vs masked 100-IP flood (default 5 pps/IP) | **99.6% blocked** (528 allowed vs 119,376 blocked), CPU ~32% |
|
||||
| Legit clients during attack | 5/5 OK, RTT 2.2–5.8ms |
|
||||
| SYN flood (no XDP) | 0 impact — handled by kernel |
|
||||
| Active connections | 300 held trivially (CPU ~0%, 7MB); limit is backend/fd, not edge |
|
||||
| Raw L7 throughput | ~4k conn/s proxied |
|
||||
| Masked 100-IP handshake flood (default 5 pps/IP) | **99.6% blocked**, legit clients OK |
|
||||
| SYN flood without XDP | 0 impact — handled by the kernel |
|
||||
|
||||
Full benchmark suite in progress.
|
||||
|
||||
### Quick Start
|
||||
|
||||
```bash
|
||||
# Build Rust components
|
||||
# Build
|
||||
cargo build --release
|
||||
|
||||
# Create config
|
||||
mkdir -p /etc/rampart
|
||||
rampart config init > /etc/rampart/config.toml
|
||||
|
||||
# Run edge node
|
||||
./target/release/rampart-core --config /etc/rampart/config.toml
|
||||
|
||||
# Java plugins
|
||||
cd plugins && ./gradlew build
|
||||
```
|
||||
|
||||
### Documentation
|
||||
|
||||
| File | Description |
|
||||
| Path | Description |
|
||||
|------|-------------|
|
||||
| [architecture](docs/research/architecture.md) | 6-layer architecture, components, ADRs |
|
||||
| [anti-bot](docs/research/anti-bot.md) | Bot detection, PoW, fingerprinting, known issues |
|
||||
| [ebpf](docs/research/ebpf.md) | XDP/eBPF: TCP state machine, maps, fixes |
|
||||
| [ddos](docs/research/ddos.md) | Attack vectors, L3/L4/L7, AI bots |
|
||||
| [deployment](docs/deployment.md) | Step-by-step deployment guide |
|
||||
| [configuration](docs/configuration.md) | Configuration examples |
|
||||
| [networking](docs/research/networking.md) | WireGuard, BGP Anycast, QUIC |
|
||||
| [runbook](docs/runbook.md) | Operations runbook |
|
||||
| [disaster_recovery](docs/disaster_recovery.md) | Failover scenarios |
|
||||
| [troubleshooting](docs/troubleshooting.md) | FAQ and diagnostics |
|
||||
| [docs/kb/](docs/kb/) | Knowledge base: attack anatomy, defense levels, practice guides |
|
||||
| [docs/research/architecture.md](docs/research/architecture.md) | Layered architecture, ADRs, migration notes |
|
||||
| [docs/research/load-test-report.md](docs/research/load-test-report.md) | VDS stress test report (2026-08-04) |
|
||||
| [docs/research/](docs/research/) | Research notes: eBPF, anti-bot, DDoS vectors, networking |
|
||||
| [docs/deployment.md](docs/deployment.md) | Deployment guide |
|
||||
| [docs/configuration.md](docs/configuration.md) | Configuration reference |
|
||||
| [docs/runbook.md](docs/runbook.md) | Operations runbook |
|
||||
|
||||
### Roadmap
|
||||
|
||||
- Stabilize the protocol plugin API
|
||||
- BPF hook modules for deep protocol parsing in XDP
|
||||
- Terminal UI (ratatui TUI)
|
||||
- HTTP protocol plugin
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -129,86 +129,96 @@ cd plugins && ./gradlew build
|
|||
|
||||
### Обзор
|
||||
|
||||
Rampart — 6-слойная система DDoS-защиты для Minecraft. Фильтрует трафик на уровне ядра (XDP/eBPF), уровне сети (PoW), уровне приложений (Rust) и уровне прокси (Velocity).
|
||||
Rampart фильтрует трафик на трёх уровнях до того, как он дойдёт до вашего сервиса:
|
||||
|
||||
### 6 слоёв защиты
|
||||
- **Уровень ядра** — XDP/eBPF отбрасывает нежелательные пакеты до того, как они попадут в TCP-стек Linux;
|
||||
- **Сетевой уровень** — PoW-challenge повышает стоимость флуда соединений для любого TCP-протокола;
|
||||
- **Прикладной уровень** — userspace-ядро на Rust выполняет анализ L7-handshake, rate limiting и проверку репутации.
|
||||
|
||||
Логика, специфичная для протоколов, вынесена в **модульные протокол-плагины** — одна платформа защищает VDS, веб-сервисы и игровые серверы.
|
||||
|
||||
### Архитектура
|
||||
|
||||
```
|
||||
Слой 1: XDP/eBPF (C) TCP state machine, SYN throttle, blacklist, UDP drop
|
||||
Слой 2: PoW Challenge (Rust) SHA256 hashcash, dynamic difficulty
|
||||
⚠️ ВЫКЛЮЧЕН по умолчанию: текущий text-challenge несовместим с ванильными
|
||||
клиентами (они не умеют его решать) — включать только с клиентским модом.
|
||||
Слой 3: Rust Core MC handshake, HMAC sign, rate limit, death code
|
||||
Слой 4: Velocity (Java) Domain whitelist, HMAC verify, physics, CAPTCHA
|
||||
Слой 5: Paper Agent (Java) Redis heartbeat, auto-registration
|
||||
Слой 6: Traffic Intel EWMA thresholds, 168h profiling, reputation
|
||||
┌────────────────────────────────────────────────────────────────────┐
|
||||
│ Слой 1: Ядро / XDP (C) │
|
||||
│ универсальный TCP state machine · SYN throttle · CIDR black/ │
|
||||
│ white списки · UDP policy · подключаемые BPF протокол-хуки │
|
||||
├────────────────────────────────────────────────────────────────────┤
|
||||
│ Слой 2: Универсальный PoW Challenge (Rust) │
|
||||
│ SHA256 hashcash · dynamic difficulty │
|
||||
│ работает поверх любого TCP-протокола ⚠️ ВЫКЛЮЧЕН по умолчанию │
|
||||
├────────────────────────────────────────────────────────────────────┤
|
||||
│ Слой 3: Userspace Core (Rust) │
|
||||
│ L7 handshake analysis · rate limit · HMAC · death-code паттерны │
|
||||
├────────────────────────────────────────────────────────────────────┤
|
||||
│ Слой 4: Протокол-плагины (feature crates) │
|
||||
│ minecraft (первый плагин) · http (в планах) · grpc (в планах) │
|
||||
└────────────────────────────────────────────────────────────────────┘
|
||||
Traffic Intel (EWMA thresholds, профилирование, репутация)
|
||||
работает поперёк всех слоёв
|
||||
```
|
||||
|
||||
```
|
||||
Атакующий → [XDP] → [PoW] → [Rust] → [Velocity] → Game Server
|
||||
1 2 3 4
|
||||
Атакующий → [XDP/eBPF] → [PoW] → [Userspace Core] → [Плагин] → Ваш сервис
|
||||
1 2 3 4
|
||||
```
|
||||
|
||||
### Компоненты
|
||||
|
||||
| Компонент | Роль | Технологии |
|
||||
|-----------|------|------------|
|
||||
| **Edge нода** | Слои 1-3: XDP + PoW + фильтрация | Rust + XDP/eBPF |
|
||||
| **Manager** | Слой 6: API + мониторинг | Rust (Axum) |
|
||||
| **Velocity** | Слой 4: прокси, верификация | Java 21 |
|
||||
| **Paper Agent** | Слой 5: регистрация сервера | Java 21 |
|
||||
| **Dashboard** | Web UI | React + TypeScript |
|
||||
| **rampart-core** | Edge-движок: XDP loader, PoW challenge, L7-фильтрация, traffic intel | Rust (tokio, libbpf) + C (XDP) |
|
||||
| **rampart-manager** | Management API + Redis sync | Rust (axum, redis) |
|
||||
| **rampart-cli** | CLI для операторов | Rust (clap) |
|
||||
| **Протокол-плагины** | Протоколозависимая фильтрация в виде feature crates | Rust |
|
||||
| ↳ `minecraft` | Первый плагин (анализ MC-handshake) | Rust |
|
||||
| ↳ `http`, `grpc` | В планах | Rust |
|
||||
| **docs/kb** | Двуязычная база знаний: анатомия атак, уровни защиты, практические руководства | Markdown |
|
||||
|
||||
### Защита от атак
|
||||
### Производительность
|
||||
|
||||
| Атака | Метод защиты | Слой |
|
||||
|-------|-------------|------|
|
||||
| SYN flood | XDP дроп + SYN throttle | 1 |
|
||||
| Handshake flood | PoW challenge + rate limit | 2+3 |
|
||||
| Slow Loris | Timeout 5 сек | 3 |
|
||||
| VarInt overflow | Строгий bounds check | 3 |
|
||||
| Death code | Auto-ban по малициозным пакетам | 3 |
|
||||
| Direct IP | Domain whitelist | 4 |
|
||||
| Подмена hostname | HMAC-SHA256 подпись | 3+4 |
|
||||
| Боты (физика) | Falling check + Vehicle check | 4 |
|
||||
| AI-боты | PoW (CPU cost) + reputation | 2+6 |
|
||||
Только подтверждённые числа — VDS stress test ([load-test-report.md](docs/research/load-test-report.md)), edge-only на loopback, 2 vCPU:
|
||||
|
||||
> **Примечание:** Layer 2 (PoW) **выключен по умолчанию** (`pow.enabled = false`) из-за
|
||||
> несовместимости с ванильными клиентами: текстовый challenge отправляется до handshake,
|
||||
> и ванильный клиент не умеет его решать — при включении никто не сможет зайти.
|
||||
> Включать только после появления клиентского мода или PoW, совместимого с протоколом Minecraft.
|
||||
| Сценарий | Результат |
|
||||
|----------|-----------|
|
||||
| Raw L7 пропускная способность | ~4k conn/s проксировано |
|
||||
| Маскированный flood с 100 IP (default 5 pps/IP) | **99.6% заблокировано**, легитимные клиенты в порядке |
|
||||
| SYN flood без XDP | 0 влияния — обрабатывается ядром |
|
||||
|
||||
Полный набор бенчмарков в процессе подготовки.
|
||||
|
||||
### Быстрый старт
|
||||
|
||||
```bash
|
||||
# Сборка Rust компонентов
|
||||
# Сборка
|
||||
cargo build --release
|
||||
|
||||
# Создание конфига
|
||||
mkdir -p /etc/rampart
|
||||
rampart config init > /etc/rampart/config.toml
|
||||
|
||||
# Запуск edge ноды
|
||||
./target/release/rampart-core --config /etc/rampart/config.toml
|
||||
|
||||
# Сборка Java плагинов
|
||||
cd plugins && ./gradlew build
|
||||
```
|
||||
|
||||
### Документация
|
||||
|
||||
| Файл | Описание |
|
||||
| Путь | Описание |
|
||||
|------|----------|
|
||||
| [architecture](docs/research/architecture.md) | 6-слойная архитектура, компоненты, ADR |
|
||||
| [anti-bot](docs/research/anti-bot.md) | Антибот: PoW, fingerprinting, известные проблемы |
|
||||
| [ebpf](docs/research/ebpf.md) | XDP/eBPF: TCP state machine, карты, исправления |
|
||||
| [ddos](docs/research/ddos.md) | Векторы атак, L3/L4/L7, AI-боты |
|
||||
| [deployment](docs/deployment.md) | Пошаговый деплой |
|
||||
| [configuration](docs/configuration.md) | Примеры конфигов |
|
||||
| [networking](docs/research/networking.md) | WireGuard, BGP, QUIC |
|
||||
| [runbook](docs/runbook.md) | Инструкции для админа |
|
||||
| [disaster_recovery](docs/disaster_recovery.md) | Failover сценарии |
|
||||
| [troubleshooting](docs/troubleshooting.md) | FAQ и диагностика |
|
||||
| [docs/kb/](docs/kb/) | База знаний: анатомия атак, уровни защиты, практические руководства |
|
||||
| [docs/research/architecture.md](docs/research/architecture.md) | Слоистая архитектура, ADR, миграционные заметки |
|
||||
| [docs/research/load-test-report.md](docs/research/load-test-report.md) | Отчёт по VDS stress test (2026-08-04) |
|
||||
| [docs/research/](docs/research/) | Research-заметки: eBPF, антибот, векторы DDoS, сети |
|
||||
| [docs/deployment.md](docs/deployment.md) | Руководство по деплою |
|
||||
| [docs/configuration.md](docs/configuration.md) | Справочник конфигурации |
|
||||
| [docs/runbook.md](docs/runbook.md) | Операционный runbook |
|
||||
|
||||
### Roadmap
|
||||
|
||||
- Стабилизация API протокол-плагинов
|
||||
- BPF hook модули для глубокого парсинга протоколов в XDP
|
||||
- Терминальный интерфейс (ratatui TUI)
|
||||
- HTTP протокол-плагин
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue