- Split TODO into a thin status index plus docs/roadmap/ with one file per task (v0.4 reliability, v0.5 product, v0.6 research, icebox). - Add docs/architecture.md (current processes, packet/data path, layers, storage, metrics) and docs/development.md (rules, gates, DoD). - Add CHANGELOG.md reconstructed from history; move round details out of TODO. - Align docs with the code: config defaults and missing [detect]/ [protocol.http] sections, XDP metric names, ClickHouse table and TTL, Redis RDB restore, multiarch clang include, CLI binary name. - Add scripts/check_docs_links.sh and run it in CI. - release profile: thin LTO + one codegen unit. Binary 12.3 MB -> 9.7 MB, http parser bench 314 ns -> 278 ns; panic=abort stays off for catch_unwind in the Redis subscriber. - Drop the unused JWT role claim; fix 'rampart doctor' hints in the CLI.
16 KiB
Rampart
Универсальная платформа сетевой защиты: L3/L4/L7-фильтрация DDoS для VDS, веб-сервисов и игровых серверов.
Статус: проект в активной разработке — API и числа производительности могут меняться.
Русский
Обзор · Возможности · Требования · Установка · Быстрый старт · Конфигурация · Плагины · Производительность · Документация · Разработка · Лицензия
Обзор
Rampart отбрасывает атакующий трафик до того, как он дойдёт до вашего сервиса. Фильтрация идёт в три уровня: XDP/eBPF в ядре, PoW-challenge в userspace и L7-анализ протокола. Логика конкретного протокола вынесена в плагины, поэтому одна платформа защищает и веб-сервис, и игровой сервер.
Подходит, если нужен свой edge-фильтр на VDS: без покупки «коробки», с конфигом в TOML и метриками в Prometheus.
Как это работает
Атакующий → [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-база |
Установка
# Сборка edge-ноды с HTTP-обработчиком
cargo build --release --features protocol-http
# Конфиг: путь по умолчанию /etc/rampart/config.toml,
# переопределяется переменной $RAMPART_CONFIG
sudo mkdir -p /etc/rampart
sudo cp deploy/config/edge-http.toml /etc/rampart/config.toml
С XDP-фильтром (нужен root либо CAP_BPF + CAP_NET_ADMIN):
cargo build --release --features protocol-http,xdp
Быстрый старт
RAMPART_CONFIG=/etc/rampart/config.toml ./target/release/rampart
В конфиге для XDP: [xdp] enabled = true, interface = "eth0". Метрики —
http://127.0.0.1:9090/metrics.
Проверить чекаут перед изменениями:
cargo fmt --all --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all-features
Конфигурация
[bind]
address = "0.0.0.0"
port = 25565
[backend]
upstreams = ["127.0.0.1:25566"]
[xdp]
enabled = false # требует сборки с feature `xdp`
interface = "eth0"
udp_policy = "pass" # pass | drop | rate-limit
Все поля и значения по умолчанию — docs/configuration.md.
Протокол-плагины
| Плагин | 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.
Rampart не спасёт уже забитый домашний канал: перед edge нужен игровой прокси или
провайдер с фильтрацией DDoS.
Производительность
Только подтверждённые замеры — VDS stress test, edge-only на loopback, 2 vCPU (отчёт):
| Сценарий | Результат |
|---|---|
| Пропускная способность L7 | ~4k conn/s |
| Маскированный flood с 100 IP (5 pps/IP) | 99.6% заблокировано, легитимные клиенты работают |
| SYN flood без XDP | обрабатывается ядром |
Полный набор микробенчмарков горячего пути (criterion) — cargo bench --all-features --bench hot_paths; медианы и методология — docs/testing.md §4.
Документация
| Раздел | Где |
|---|---|
| Индекс всей документации | docs/README.md |
| Архитектура системы | docs/architecture.md |
| Деплой | docs/deployment.md |
| Конфигурация | docs/configuration.md |
| Эксплуатация (runbook) | docs/runbook.md |
| Диагностика | docs/troubleshooting.md |
| Тестирование | docs/testing.md |
| API manager'а | docs/api.md |
| Roadmap и планы задач | docs/roadmap/ |
| История изменений | CHANGELOG.md |
| База знаний (атаки, защита, практика) | docs/kb/ |
| Research: архитектура, eBPF, DDoS | docs/research/ |
Разработка
- Правила кода, гейты и Definition of Done — docs/development.md.
- Комментарии в коде — только по-английски, Rustdoc/Javadoc-стиль.
- Тесты живут в
tests/, без#[cfg(test)]в файлах с кодом. - Перед PR:
cargo fmt,cargo clippy -D warnings,cargo test --all-features.
Текущий статус — TODO.md, планы задач — docs/roadmap/, история — CHANGELOG.md. Issues и PR — во вкладках репозитория.
Лицензия
GNU General Public License v3.0 — LICENSE.
English
Overview · Features · Requirements · Installation · Quick start · Configuration · Plugins · Performance · Documentation · Development · License
Overview
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.
It fits teams that need their own edge filter on a VDS: no appliance to buy, a TOML config, and Prometheus metrics out of the box.
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:
/32and/128bans, UDP rate limiting keyed by the full 128-bit address, TCP bypass detection,/24and/64prefix 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 |
Installation
# Build the edge node with the HTTP handler
cargo build --release --features protocol-http
# Config: default path is /etc/rampart/config.toml,
# override it with $RAMPART_CONFIG
sudo mkdir -p /etc/rampart
sudo cp deploy/config/edge-http.toml /etc/rampart/config.toml
With the XDP filter (root or CAP_BPF + CAP_NET_ADMIN):
cargo build --release --features protocol-http,xdp
Quick start
RAMPART_CONFIG=/etc/rampart/config.toml ./target/release/rampart
For XDP set [xdp] enabled = true and interface = "eth0". Metrics are served
at http://127.0.0.1:9090/metrics.
Verify the checkout before making changes:
cargo fmt --all --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all-features
Configuration
[bind]
address = "0.0.0.0"
port = 25565
[backend]
upstreams = ["127.0.0.1:25566"]
[xdp]
enabled = false # requires the `xdp` feature
interface = "eth0"
udp_policy = "pass" # pass | drop | rate-limit
Every field and its default: docs/configuration.md.
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. 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):
| 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 hot-path microbenchmarks (criterion) run with cargo bench --all-features --bench hot_paths; medians and methodology live in docs/testing.md §4.
Documentation
| Topic | Where |
|---|---|
| Documentation index | docs/README.md |
| System architecture | docs/architecture.md |
| Deployment | docs/deployment.md |
| Configuration | docs/configuration.md |
| Operations runbook | docs/runbook.md |
| Troubleshooting | docs/troubleshooting.md |
| Testing | docs/testing.md |
| Manager API | docs/api.md |
| Roadmap and task plans | docs/roadmap/ |
| Changelog | CHANGELOG.md |
| Knowledge base | docs/kb/ |
| Research notes | docs/research/ |
Development
- Coding rules, gates and Definition of Done: docs/development.md.
- Code comments are English only, Rustdoc/Javadoc style.
- Tests live in
tests/; no#[cfg(test)]modules in code files. - Before a PR:
cargo fmt,cargo clippy -D warnings,cargo test --all-features.
Current status lives in TODO.md, task plans in docs/roadmap/, history in CHANGELOG.md. Issues and PRs are in the repository tabs.
License
GNU General Public License v3.0 — LICENSE.