XDP behaviour: - udp_rate_limit6 (LRU, 128-bit source key) + throttle_hit6, so udp_policy = "rate-limit" now applies to native IPv6 as well. - scripts/xdp_ipv6_smoke.sh: phase 4 patches .rodata before load and verifies policy=2 on a real kernel (3 pass / 3 rate-limited). XDP loader (was completely broken, never reached the verifier): - .rodata is now one struct rampart_config with frozen offsets enforced by _Static_assert; XdpGlobals is #[repr(C)] and the image is built with offset_of!. Previously a 96-byte image was written into a 76-byte map at offsets clang had reordered, so load() failed with EINVAL. - patch_rodata fails loudly when the map size and the image size diverge. - build.rs tracks xdp/core and xdp/hooks, not just universal_filter.c. - build_ringbuf looked for "events_map"; the map is "events_ringbuf". - tests/xdp_object_maps.rs: verifies map names and .rodata size without root; the real binary was confirmed to attach in a netns. Docs and style: - Code comments are English, JavaDoc/Rustdoc style, without emoji or decorative banners (new project rule, TODO §0.8). - README rewritten bilingual: Russian first, English below, TOC and copy-paste quick start. - docs/README.md: documentation index and maintenance rules; configuration.md documents the whole [xdp] section and IPv4/IPv6 coverage; testing.md describes the real-kernel smoke; stale research links removed.
321 lines
14 KiB
Markdown
321 lines
14 KiB
Markdown
<div align="center">
|
||
|
||
# Rampart
|
||
|
||
**Универсальная платформа сетевой защиты: L3/L4/L7-фильтрация DDoS для VDS, веб-сервисов и игровых серверов.**
|
||
|
||

|
||

|
||

|
||

|
||

|
||
|
||
[Русский](#русский) · [English](#english)
|
||
|
||
</div>
|
||
|
||
> [!WARNING]
|
||
> Проект в активной разработке. Числа производительности и API могут меняться.
|
||
|
||
---
|
||
|
||
<a id="русский"></a>
|
||
|
||
## Русский
|
||
|
||
### Содержание
|
||
|
||
- [Что это](#что-это)
|
||
- [Как это работает](#как-это-работает)
|
||
- [Возможности](#возможности)
|
||
- [Требования](#требования)
|
||
- [Быстрый старт](#быстрый-старт)
|
||
- [Конфигурация](#конфигурация)
|
||
- [Протокол-плагины](#протокол-плагины)
|
||
- [Производительность](#производительность)
|
||
- [Документация](#документация)
|
||
- [Разработка](#разработка)
|
||
- [Лицензия](#лицензия)
|
||
|
||
### Что это
|
||
|
||
Rampart отбрасывает атакующий трафик до того, как он дойдёт до вашего сервиса.
|
||
Фильтрация идёт в три уровня: XDP/eBPF в ядре, PoW-challenge в userspace и
|
||
L7-анализ протокола. Логика конкретного протокола вынесена в плагины, поэтому
|
||
одна и та же платформа защищает и веб-сервис, и игровой сервер.
|
||
|
||
### Как это работает
|
||
|
||
```
|
||
Атакующий → [XDP/eBPF] → [PoW] → [Userspace Core] → [Плагин] → Ваш сервис
|
||
1 2 3 4
|
||
```
|
||
|
||
| Уровень | Что делает | Стек |
|
||
|---------|------------|------|
|
||
| **1. Ядро / XDP** | Дроп пакетов до стека Linux: TCP state machine, SYN-throttle, CIDR blacklist/whitelist, UDP policy, IPv4 + IPv6 | C, eBPF |
|
||
| **2. PoW challenge** | Повышает цену флуда соединений для любого TCP-протокола (по умолчанию выключен) | Rust, SHA-256 hashcash |
|
||
| **3. Userspace core** | L7-handshake, rate limit, репутация, профилирование трафика | Rust, tokio |
|
||
| **4. Протокол-плагины** | Разбор и фильтрация конкретного протокола | Rust (feature crates) |
|
||
|
||
### Возможности
|
||
|
||
- **XDP-фильтр в ядре** — blacklist/whitelist CIDR, SYN-throttle, детект поддельных
|
||
TCP-флагов, UDP policy (`pass` / `drop` / `rate-limit`), prefix-статистика.
|
||
- **IPv4 и IPv6** — отдельные LPM-таблицы для обоих семейств: баны по `/32` и `/128`,
|
||
UDP rate-limit с 128-битным ключом, детект TCP-bypass, статистика по `/24` и `/64`.
|
||
- **PoW-challenge** — hashcash с динамической сложностью, работает поверх любого TCP.
|
||
- **Протокол-плагины** — HTTP/1.1 и Minecraft Java, API плагинов стабилизируется.
|
||
- **Ringbuf-события и авто-бан** — события из ядра в userspace, opt-in авто-бан по
|
||
rate-limit и обрывам соединений.
|
||
- **Управление и наблюдаемость** — Prometheus-метрики, management API + Redis-синхронизация,
|
||
CLI и TUI-дашборд.
|
||
- **Traffic Intel** — EWMA-пороги, профилирование и репутация поверх всех уровней.
|
||
|
||
### Требования
|
||
|
||
| Компонент | Требование |
|
||
|-----------|------------|
|
||
| Rust | 1.85+ (edition 2024) |
|
||
| XDP | Linux 5.10+, `clang` с `-target bpf`, `libbpf`/`libelf` |
|
||
| Опционально | Redis (синхронизация блэклиста), ClickHouse (события), GeoIP-база |
|
||
|
||
### Быстрый старт
|
||
|
||
```bash
|
||
# 1. Сборка edge-ноды с HTTP-обработчиком
|
||
cargo build --release --features protocol-http
|
||
|
||
# 2. Конфиг (путь по умолчанию /etc/rampart/config.toml, переопределяется $RAMPART_CONFIG)
|
||
sudo mkdir -p /etc/rampart
|
||
sudo cp deploy/config/edge-http.toml /etc/rampart/config.toml
|
||
|
||
# 3. Запуск
|
||
RAMPART_CONFIG=/etc/rampart/config.toml ./target/release/rampart
|
||
```
|
||
|
||
С XDP (нужен root либо `CAP_BPF` + `CAP_NET_ADMIN`):
|
||
|
||
```bash
|
||
cargo build --release --features protocol-http,xdp
|
||
# в конфиге: [xdp] enabled = true, interface = "eth0"
|
||
```
|
||
|
||
Проверить, что всё собрано и работает:
|
||
|
||
```bash
|
||
cargo fmt --all --check
|
||
cargo clippy --all-targets --all-features -- -D warnings
|
||
cargo test --all-features
|
||
```
|
||
|
||
### Конфигурация
|
||
|
||
Полный справочник — [docs/configuration.md](docs/configuration.md). Минимальный конфиг:
|
||
bind-адрес и порт, список upstream'ов, `[limits]`, опционально `[store]` и `[xdp]`.
|
||
|
||
### Протокол-плагины
|
||
|
||
| Плагин | Feature | Что даёт |
|
||
|--------|---------|----------|
|
||
| HTTP/1.1 | `protocol-http` | Парсинг request-head, вердикт Allow/Reject, туннель на upstream |
|
||
| Minecraft Java | `protocol-minecraft` | TCP-handshake, туннель на Paper (включая PROXY protocol) |
|
||
| gRPC | план | — |
|
||
|
||
Minecraft-edge: `cargo build --release --features protocol-minecraft --bin rampart`,
|
||
конфиг — `deploy/config/edge.toml`, инструкция — [docs/minecraft-java.md](docs/minecraft-java.md).
|
||
Rampart не спасёт уже забитый домашний канал: перед edge нужен игровой прокси или
|
||
провайдер с фильтрацией DDoS.
|
||
|
||
### Производительность
|
||
|
||
Только подтверждённые замеры — VDS stress test, edge-only на loopback, 2 vCPU
|
||
([отчёт](docs/research/load-test-report.md)):
|
||
|
||
| Сценарий | Результат |
|
||
|----------|-----------|
|
||
| Пропускная способность L7 | ~4k conn/s |
|
||
| Маскированный flood с 100 IP (5 pps/IP) | **99.6% заблокировано**, легитимные клиенты работают |
|
||
| SYN flood без XDP | обрабатывается ядром |
|
||
|
||
Полный набор бенчмарков — в работе.
|
||
|
||
### Документация
|
||
|
||
| Раздел | Где |
|
||
|--------|-----|
|
||
| Индекс всей документации | [docs/README.md](docs/README.md) |
|
||
| Деплой | [docs/deployment.md](docs/deployment.md) |
|
||
| Конфигурация | [docs/configuration.md](docs/configuration.md) |
|
||
| Эксплуатация (runbook) | [docs/runbook.md](docs/runbook.md) |
|
||
| Диагностика | [docs/troubleshooting.md](docs/troubleshooting.md) |
|
||
| Тестирование | [docs/testing.md](docs/testing.md) |
|
||
| API manager'а | [docs/api.md](docs/api.md) |
|
||
| База знаний (атаки, защита, практика) | [docs/kb/](docs/kb/) |
|
||
| Research: архитектура, eBPF, DDoS | [docs/research/](docs/research/) |
|
||
|
||
### Разработка
|
||
|
||
- Правила кода и Definition of Done — [TODO.md](TODO.md) (§0).
|
||
- Комментарии в коде — только по-английски, JavaDoc/Rustdoc-стиль (§0.8).
|
||
- Тесты живут в `tests/`, без `#[cfg(test)]` в файлах с кодом.
|
||
- Перед PR: `cargo fmt`, `cargo clippy -D warnings`, `cargo test --all-features`.
|
||
|
||
Трекер идей и статус задач — [TODO.md](TODO.md), issues и PR — во вкладках репозитория.
|
||
|
||
### Лицензия
|
||
|
||
GNU General Public License v3.0 — [LICENSE](LICENSE).
|
||
|
||
---
|
||
|
||
<a id="english"></a>
|
||
|
||
## English
|
||
|
||
### Contents
|
||
|
||
- [What it is](#what-it-is)
|
||
- [How it works](#how-it-works)
|
||
- [Features](#features)
|
||
- [Requirements](#requirements)
|
||
- [Quick start](#quick-start)
|
||
- [Configuration](#configuration)
|
||
- [Protocol plugins](#protocol-plugins)
|
||
- [Performance](#performance)
|
||
- [Documentation](#documentation)
|
||
- [Development](#development)
|
||
- [License](#license)
|
||
|
||
### What it is
|
||
|
||
Rampart drops malicious traffic before it reaches your service. Filtering happens
|
||
at three levels: XDP/eBPF in the kernel, a proof-of-work challenge in userspace,
|
||
and L7 protocol analysis. Protocol-specific logic lives in plugins, so the same
|
||
platform protects a web service and a game server alike.
|
||
|
||
### How it works
|
||
|
||
```
|
||
Attacker → [XDP/eBPF] → [PoW] → [Userspace Core] → [Plugin] → Your service
|
||
1 2 3 4
|
||
```
|
||
|
||
| Layer | Responsibility | Stack |
|
||
|-------|----------------|-------|
|
||
| **1. Kernel / XDP** | Drop packets before the Linux stack: TCP state machine, SYN throttle, CIDR black/white lists, UDP policy, IPv4 + IPv6 | C, eBPF |
|
||
| **2. PoW challenge** | Raises the cost of connection floods for any TCP protocol (off by default) | Rust, SHA-256 hashcash |
|
||
| **3. Userspace core** | L7 handshake analysis, rate limiting, reputation, traffic profiling | Rust, tokio |
|
||
| **4. Protocol plugins** | Protocol-aware parsing and filtering | Rust (feature crates) |
|
||
|
||
### Features
|
||
|
||
- **Kernel XDP filter** — CIDR blacklist/whitelist, SYN throttle, forged TCP flag
|
||
detection, UDP policy (`pass` / `drop` / `rate-limit`), per-prefix statistics.
|
||
- **IPv4 and IPv6** — separate LPM tables for both families: `/32` and `/128` bans,
|
||
UDP rate limiting keyed by the full 128-bit address, TCP bypass detection,
|
||
`/24` and `/64` prefix stats.
|
||
- **PoW challenge** — hashcash with dynamic difficulty over any TCP protocol.
|
||
- **Protocol plugins** — HTTP/1.1 and Minecraft Java; the plugin API is stabilizing.
|
||
- **Ringbuf events and auto-ban** — kernel events delivered to userspace, with
|
||
opt-in auto-ban on rate limits and connection drops.
|
||
- **Operations** — Prometheus metrics, management API with Redis sync, CLI and a
|
||
terminal dashboard.
|
||
- **Traffic Intel** — EWMA thresholds, profiling and reputation across all layers.
|
||
|
||
### Requirements
|
||
|
||
| Component | Requirement |
|
||
|-----------|-------------|
|
||
| Rust | 1.85+ (edition 2024) |
|
||
| XDP | Linux 5.10+, `clang` with `-target bpf`, `libbpf`/`libelf` |
|
||
| Optional | Redis (blacklist sync), ClickHouse (events), GeoIP database |
|
||
|
||
### Quick start
|
||
|
||
```bash
|
||
# 1. Build the edge node with the HTTP handler
|
||
cargo build --release --features protocol-http
|
||
|
||
# 2. Install the config (default is /etc/rampart/config.toml, override with $RAMPART_CONFIG)
|
||
sudo mkdir -p /etc/rampart
|
||
sudo cp deploy/config/edge-http.toml /etc/rampart/config.toml
|
||
|
||
# 3. Run
|
||
RAMPART_CONFIG=/etc/rampart/config.toml ./target/release/rampart
|
||
```
|
||
|
||
With XDP (root or `CAP_BPF` + `CAP_NET_ADMIN`):
|
||
|
||
```bash
|
||
cargo build --release --features protocol-http,xdp
|
||
# config: [xdp] enabled = true, interface = "eth0"
|
||
```
|
||
|
||
Verify the checkout:
|
||
|
||
```bash
|
||
cargo fmt --all --check
|
||
cargo clippy --all-targets --all-features -- -D warnings
|
||
cargo test --all-features
|
||
```
|
||
|
||
### Configuration
|
||
|
||
Full reference: [docs/configuration.md](docs/configuration.md). The minimal config
|
||
needs a bind address and port, upstreams, and `[limits]`; `[store]` and `[xdp]`
|
||
are optional.
|
||
|
||
### Protocol plugins
|
||
|
||
| Plugin | Feature | Provides |
|
||
|--------|---------|----------|
|
||
| HTTP/1.1 | `protocol-http` | Request-head parsing, Allow/Reject verdict, upstream tunnel |
|
||
| Minecraft Java | `protocol-minecraft` | TCP handshake, tunnel to Paper (PROXY protocol supported) |
|
||
| gRPC | planned | — |
|
||
|
||
Minecraft edge: `cargo build --release --features protocol-minecraft --bin rampart`,
|
||
config in `deploy/config/edge.toml`, guide in
|
||
[docs/minecraft-java.md](docs/minecraft-java.md). Rampart cannot rescue an already
|
||
saturated home uplink: put a game proxy or a DDoS-filtering provider in front.
|
||
|
||
### Performance
|
||
|
||
Confirmed numbers only — VDS stress test, edge-only on loopback, 2 vCPU
|
||
([report](docs/research/load-test-report.md)):
|
||
|
||
| Scenario | Result |
|
||
|----------|--------|
|
||
| L7 throughput | ~4k conn/s |
|
||
| Masked 100-IP handshake flood (5 pps/IP) | **99.6% blocked**, legitimate clients unaffected |
|
||
| SYN flood without XDP | handled by the kernel |
|
||
|
||
The full benchmark suite is in progress.
|
||
|
||
### Documentation
|
||
|
||
| Topic | Where |
|
||
|-------|-------|
|
||
| Documentation index | [docs/README.md](docs/README.md) |
|
||
| Deployment | [docs/deployment.md](docs/deployment.md) |
|
||
| Configuration | [docs/configuration.md](docs/configuration.md) |
|
||
| Operations runbook | [docs/runbook.md](docs/runbook.md) |
|
||
| Troubleshooting | [docs/troubleshooting.md](docs/troubleshooting.md) |
|
||
| Testing | [docs/testing.md](docs/testing.md) |
|
||
| Manager API | [docs/api.md](docs/api.md) |
|
||
| Knowledge base | [docs/kb/](docs/kb/) |
|
||
| Research notes | [docs/research/](docs/research/) |
|
||
|
||
### Development
|
||
|
||
- Coding rules and Definition of Done: [TODO.md](TODO.md) (§0).
|
||
- Code comments are English only, JavaDoc/Rustdoc style (§0.8).
|
||
- Tests live in `tests/`; no `#[cfg(test)]` modules in code files.
|
||
- Before a PR: `cargo fmt`, `cargo clippy -D warnings`, `cargo test --all-features`.
|
||
|
||
Roadmap and task status live in [TODO.md](TODO.md); issues and PRs are in the
|
||
repository tabs.
|
||
|
||
### License
|
||
|
||
GNU General Public License v3.0 — [LICENSE](LICENSE).
|