# Rampart **Универсальная платформа сетевой защиты: L3/L4/L7-фильтрация DDoS для VDS, веб-сервисов и игровых серверов.** ![Rust](https://img.shields.io/badge/Rust-000000?style=flat-square&logo=rust&logoColor=white) ![eBPF](https://img.shields.io/badge/C%2FeBPF%20XDP-FF6C37?style=flat-square&logo=linux&logoColor=white) ![License](https://img.shields.io/badge/license-GPLv3-blue?style=flat-square&logo=gnu&logoColor=white) ![Version](https://img.shields.io/badge/version-0.3.0--dev-green?style=flat-square) ![Status](https://img.shields.io/badge/status-development-yellow?style=flat-square) [Русский](#русский) · [English](#english)
> [!WARNING] > Проект в активной разработке. Числа производительности и API могут меняться. --- ## Русский ### Содержание - [Что это](#что-это) - [Как это работает](#как-это-работает) - [Возможности](#возможности) - [Требования](#требования) - [Быстрый старт](#быстрый-старт) - [Конфигурация](#конфигурация) - [Протокол-плагины](#протокол-плагины) - [Производительность](#производительность) - [Документация](#документация) - [Разработка](#разработка) - [Лицензия](#лицензия) ### Что это 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). --- ## 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).