Rampart: universal network protection platform, an L3/L4/L7 DDoS filtering framework in Rust
Find a file
loki5512344 15f3fcb895
refactor(subnet): split verdict enforcement out of the monitor
monitor.rs reached 257 lines after the trusted-network suppression (limit is
250). BanPolicy, enforce_tracker_verdicts, ban_xdp_verdicts and prefix_len move
to src/engine/subnet/enforce.rs; the monitor keeps the task, source selection
and verdict logging, re-exporting enforce_tracker_verdicts so existing paths
stay valid.

Also documents the new tests/edge_e2e.rs scenarios in docs/testing.md.
2026-11-16 13:11:31 +01:00
.github/workflows fix(core): close auth bypass, hangs and memory leaks found by review 2026-11-16 12:06:23 +01:00
benches perf: criterion benchmarks for the per-connection hot path 2026-11-16 12:55:51 +01:00
deploy fix(edge): IPv6 bind, configurable relay idle, per-gateway budget, PROXY identity 2026-11-16 12:36:19 +01:00
docs refactor(subnet): split verdict enforcement out of the monitor 2026-11-16 13:11:31 +01:00
fuzz test: fuzz the HTTP and PROXY v2 parsers, make PROXY parsing pure 2026-11-16 12:47:25 +01:00
scripts fix(core): close auth bypass, hangs and memory leaks found by review 2026-11-16 12:06:23 +01:00
src refactor(subnet): split verdict enforcement out of the monitor 2026-11-16 13:11:31 +01:00
tests test(edge): end-to-end connection path over loopback 2026-11-16 13:08:34 +01:00
xdp feat(xdp): estimate distinct sources in prefix stats, fix the detection window 2026-11-16 12:36:19 +01:00
.dockerignore fix: clippy byte_char_slices lint, Docker java artifact path 2026-07-21 16:34:30 +02:00
.gitignore test: fuzz the HTTP and PROXY v2 parsers, make PROXY parsing pure 2026-11-16 12:47:25 +01:00
.module_size_baseline fix: XDP unsafe loader + Redis sync; enforce 250-line/4-file layout limits 2026-09-15 23:55:17 +02:00
build.rs feat(xdp): IPv6 UDP rate limit, working loader; English comments and docs 2026-11-15 23:50:52 +01:00
Cargo.lock perf: criterion benchmarks for the per-connection hot path 2026-11-16 12:55:51 +01:00
Cargo.toml perf: criterion benchmarks for the per-connection hot path 2026-11-16 12:55:51 +01:00
clippy.toml feat: velocity routing, server registry and RampartVelocity tests 2026-08-03 10:54:28 +02:00
deny.toml fix(ci): use aws-lc-rs provider and install XDP build deps for tests 2026-10-26 11:56:18 +01:00
docker-compose.yml fix(core): close auth bypass, hangs and memory leaks found by review 2026-11-16 12:06:23 +01:00
Dockerfile v0.3: 6-layer architecture complete 2026-07-21 15:47:36 +02:00
LICENSE Initial commit: Rampart v0.2.0 2026-07-20 20:53:32 +02:00
Makefile perf: criterion benchmarks for the per-connection hot path 2026-11-16 12:55:51 +01:00
README.md feat(xdp): IPv6 UDP rate limit, working loader; English comments and docs 2026-11-15 23:50:52 +01:00
rustfmt.toml style: switch rustfmt to hard tabs; document tests-separate rule in TODO 2026-11-15 22:34:29 +01:00
TODO.md fix: never ban a trusted proxy network from any ban source 2026-11-16 13:03:50 +01:00

Rampart

Универсальная платформа сетевой защиты: L3/L4/L7-фильтрация DDoS для VDS, веб-сервисов и игровых серверов.

Rust eBPF License Version Status

Docs Quick start Configuration API License

Русский · English

Статус: проект в активной разработке — 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 обрабатывается ядром

Полный набор бенчмарков — в работе.

Документация

Раздел Где
Индекс всей документации docs/README.md
Деплой docs/deployment.md
Конфигурация docs/configuration.md
Эксплуатация (runbook) docs/runbook.md
Диагностика docs/troubleshooting.md
Тестирование docs/testing.md
API manager'а docs/api.md
База знаний (атаки, защита, практика) docs/kb/
Research: архитектура, eBPF, DDoS docs/research/

Разработка

  • Правила кода и Definition of Done — TODO.md (§0).
  • Комментарии в коде — только по-английски, JavaDoc/Rustdoc-стиль (§0.8).
  • Тесты живут в tests/, без #[cfg(test)] в файлах с кодом.
  • Перед PR: cargo fmt, cargo clippy -D warnings, cargo test --all-features.

Трекер идей и статус задач — TODO.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: /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

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 full benchmark suite is in progress.

Documentation

Topic Where
Documentation index docs/README.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
Knowledge base docs/kb/
Research notes docs/research/

Development

  • Coding rules and Definition of Done: 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; issues and PRs are in the repository tabs.

License

GNU General Public License v3.0 — LICENSE.