feat(xdp): IPv6 UDP rate limit, working loader; English JavaDoc comments
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.
This commit is contained in:
parent
295ab81fb4
commit
918e561a61
104 changed files with 2129 additions and 1021 deletions
463
README.md
463
README.md
|
|
@ -1,256 +1,321 @@
|
|||
<div align="center">
|
||||
|
||||
> **⚠️ UNDER DEVELOPMENT** — All performance data, benchmarks, and specifications shown are approximate and subject to change.
|
||||
>
|
||||
> **⚠️ В РАЗРАБОТКЕ** — Все показатели производительности, тесты и характеристики являются примерными и могут измениться.
|
||||
|
||||
</div>
|
||||
|
||||
<div align="center">
|
||||
|
||||
# Rampart
|
||||
|
||||
Universal network protection platform (L3/L4/L7 DDoS filtering framework)
|
||||
**Универсальная платформа сетевой защиты: L3/L4/L7-фильтрация DDoS для VDS, веб-сервисов и игровых серверов.**
|
||||
|
||||

|
||||

|
||||

|
||||

|
||||

|
||||

|
||||
|
||||
[English](#english) | [Русский](#russian)
|
||||
[Русский](#русский) · [English](#english)
|
||||
|
||||
</div>
|
||||
|
||||
---
|
||||
|
||||
<a name="english"></a>
|
||||
|
||||
## English
|
||||
|
||||
### Overview
|
||||
|
||||
Rampart filters traffic at three levels before it reaches your service:
|
||||
|
||||
- **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: 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) │
|
||||
│ http (protocol-http) · Minecraft Java (protocol-minecraft) · grpc (planned) │
|
||||
└────────────────────────────────────────────────────────────────────┘
|
||||
Traffic Intel (EWMA thresholds, profiling, reputation)
|
||||
runs across all layers
|
||||
```
|
||||
|
||||
```
|
||||
Attacker → [XDP/eBPF] → [PoW] → [Userspace Core] → [Plugin] → Your Service
|
||||
1 2 3 4
|
||||
```
|
||||
|
||||
### Components
|
||||
|
||||
| Component | Role | Stack |
|
||||
|-----------|------|-------|
|
||||
| **rampart** | 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) |
|
||||
| **rampart-tui** | Live metrics terminal dashboard, polls the Prometheus `/metrics` endpoint | Rust (ratatui) |
|
||||
| **protocol plugins** | Protocol-aware filtering as feature crates | Rust |
|
||||
| ↳ `http` | HTTP/1.1 handler, compiled with the `protocol-http` feature | Rust |
|
||||
| ↳ `minecraft` | Minecraft Java TCP handshake and tunnel, compiled with `protocol-minecraft` | Rust |
|
||||
| ↳ `grpc` | Planned | Rust |
|
||||
| **docs/kb** | Bilingual knowledge base: attack anatomy, defense levels, practice guides | Markdown |
|
||||
|
||||
### Performance
|
||||
|
||||
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 | ~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 the HTTP edge handler
|
||||
cargo build --release --features protocol-http
|
||||
|
||||
# Install the default config
|
||||
sudo mkdir -p /etc/rampart
|
||||
sudo cp deploy/config/edge-http.toml /etc/rampart/config.toml
|
||||
|
||||
# Run edge node (config path comes from $RAMPART_CONFIG, default /etc/rampart/config.toml)
|
||||
RAMPART_CONFIG=/etc/rampart/config.toml ./target/release/rampart
|
||||
```
|
||||
|
||||
### Minecraft Java Edge
|
||||
|
||||
Rampart also has an early Minecraft Java TCP handler. Build it with
|
||||
`cargo build --release --features protocol-minecraft --bin rampart`, copy
|
||||
`deploy/config/edge.toml` as its config, and follow
|
||||
[docs/minecraft-java.md](docs/minecraft-java.md) for Paper PROXY-protocol and
|
||||
private-backend setup. This handler does not protect an already-saturated home
|
||||
uplink; use a DDoS-filtering game proxy/provider in front of the edge.
|
||||
|
||||
### Documentation
|
||||
|
||||
| Path | Description |
|
||||
|------|-------------|
|
||||
| [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/minecraft-java.md](docs/minecraft-java.md) | Minecraft Java edge and Paper setup |
|
||||
| [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
|
||||
> [!WARNING]
|
||||
> Проект в активной разработке. Числа производительности и API могут меняться.
|
||||
|
||||
---
|
||||
|
||||
<a name="russian"></a>
|
||||
<a id="русский"></a>
|
||||
|
||||
## Русский
|
||||
|
||||
### Обзор
|
||||
### Содержание
|
||||
|
||||
Rampart фильтрует трафик на трёх уровнях до того, как он дойдёт до вашего сервиса:
|
||||
- [Что это](#что-это)
|
||||
- [Как это работает](#как-это-работает)
|
||||
- [Возможности](#возможности)
|
||||
- [Требования](#требования)
|
||||
- [Быстрый старт](#быстрый-старт)
|
||||
- [Конфигурация](#конфигурация)
|
||||
- [Протокол-плагины](#протокол-плагины)
|
||||
- [Производительность](#производительность)
|
||||
- [Документация](#документация)
|
||||
- [Разработка](#разработка)
|
||||
- [Лицензия](#лицензия)
|
||||
|
||||
- **Уровень ядра** — XDP/eBPF отбрасывает нежелательные пакеты до того, как они попадут в TCP-стек Linux;
|
||||
- **Сетевой уровень** — PoW-challenge повышает стоимость флуда соединений для любого TCP-протокола;
|
||||
- **Прикладной уровень** — userspace-ядро на Rust выполняет анализ L7-handshake, rate limiting и проверку репутации.
|
||||
### Что это
|
||||
|
||||
Логика, специфичная для протоколов, вынесена в **модульные протокол-плагины** — одна платформа защищает VDS, веб-сервисы и игровые серверы.
|
||||
Rampart отбрасывает атакующий трафик до того, как он дойдёт до вашего сервиса.
|
||||
Фильтрация идёт в три уровня: XDP/eBPF в ядре, PoW-challenge в userspace и
|
||||
L7-анализ протокола. Логика конкретного протокола вынесена в плагины, поэтому
|
||||
одна и та же платформа защищает и веб-сервис, и игровой сервер.
|
||||
|
||||
### Архитектура
|
||||
|
||||
```
|
||||
┌────────────────────────────────────────────────────────────────────┐
|
||||
│ Слой 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) │
|
||||
│ http (protocol-http) · Minecraft Java (protocol-minecraft) · grpc (в планах) │
|
||||
└────────────────────────────────────────────────────────────────────┘
|
||||
Traffic Intel (EWMA thresholds, профилирование, репутация)
|
||||
работает поперёк всех слоёв
|
||||
```
|
||||
### Как это работает
|
||||
|
||||
```
|
||||
Атакующий → [XDP/eBPF] → [PoW] → [Userspace Core] → [Плагин] → Ваш сервис
|
||||
1 2 3 4
|
||||
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) |
|
||||
|
||||
| Компонент | Роль | Технологии |
|
||||
|-----------|------|------------|
|
||||
| **rampart** | 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) |
|
||||
| **rampart-tui** | Терминальный дашборд live-метрик, опрашивает Prometheus `/metrics` | Rust (ratatui) |
|
||||
| **Протокол-плагины** | Протоколозависимая фильтрация в виде feature crates | Rust |
|
||||
| ↳ `http` | HTTP/1.1-обработчик, собирается с фичей `protocol-http` | Rust |
|
||||
| ↳ `minecraft` | TCP-handshake и туннель Minecraft Java, фича `protocol-minecraft` | Rust |
|
||||
| ↳ `grpc` | В планах | Rust |
|
||||
| **docs/kb** | Двуязычная база знаний: анатомия атак, уровни защиты, практические руководства | Markdown |
|
||||
### Возможности
|
||||
|
||||
### Производительность
|
||||
- **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-пороги, профилирование и репутация поверх всех уровней.
|
||||
|
||||
Только подтверждённые числа — VDS stress test ([load-test-report.md](docs/research/load-test-report.md)), edge-only на loopback, 2 vCPU:
|
||||
### Требования
|
||||
|
||||
| Сценарий | Результат |
|
||||
|----------|-----------|
|
||||
| Raw L7 пропускная способность | ~4k conn/s проксировано |
|
||||
| Маскированный flood с 100 IP (default 5 pps/IP) | **99.6% заблокировано**, легитимные клиенты в порядке |
|
||||
| SYN flood без XDP | 0 влияния — обрабатывается ядром |
|
||||
|
||||
Полный набор бенчмарков в процессе подготовки.
|
||||
| Компонент | Требование |
|
||||
|-----------|------------|
|
||||
| Rust | 1.85+ (edition 2024) |
|
||||
| XDP | Linux 5.10+, `clang` с `-target bpf`, `libbpf`/`libelf` |
|
||||
| Опционально | Redis (синхронизация блэклиста), ClickHouse (события), GeoIP-база |
|
||||
|
||||
### Быстрый старт
|
||||
|
||||
```bash
|
||||
# Сборка HTTP-обработчика
|
||||
# 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
|
||||
|
||||
# Запуск edge ноды (путь конфига берётся из $RAMPART_CONFIG, по умолчанию /etc/rampart/config.toml)
|
||||
# 3. Запуск
|
||||
RAMPART_CONFIG=/etc/rampart/config.toml ./target/release/rampart
|
||||
```
|
||||
|
||||
### Minecraft Java Edge
|
||||
С XDP (нужен root либо `CAP_BPF` + `CAP_NET_ADMIN`):
|
||||
|
||||
В проекте появился ранний TCP-обработчик Minecraft Java. Соберите его командой
|
||||
`cargo build --release --features protocol-minecraft --bin rampart`, скопируйте
|
||||
`deploy/config/edge.toml` как конфиг и настройте
|
||||
Paper и закрытый backend по инструкции
|
||||
[docs/minecraft-java.md](docs/minecraft-java.md). Сам Rampart не спасёт домашний
|
||||
канал, если атака уже забила его: перед edge нужен игровой прокси или провайдер
|
||||
с фильтрацией DDoS.
|
||||
```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/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/minecraft-java.md](docs/minecraft-java.md) | Minecraft Java edge и настройка Paper |
|
||||
| [docs/configuration.md](docs/configuration.md) | Справочник конфигурации |
|
||||
| [docs/runbook.md](docs/runbook.md) | Операционный runbook |
|
||||
| Раздел | Где |
|
||||
|--------|-----|
|
||||
| Индекс всей документации | [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/) |
|
||||
|
||||
### Roadmap
|
||||
### Разработка
|
||||
|
||||
- Стабилизация API протокол-плагинов
|
||||
- BPF hook модули для глубокого парсинга протоколов в XDP
|
||||
- Правила кода и 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).
|
||||
|
||||
---
|
||||
|
||||
### Links
|
||||
<a id="english"></a>
|
||||
|
||||
- [Releases](../../releases)
|
||||
- [Issues](../../issues)
|
||||
- [License](LICENSE)
|
||||
## 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
|
||||
GNU General Public License v3.0 — [LICENSE](LICENSE).
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue