boba/guard

fix: XDP unsafe loader + Redis sync; enforce 250-line/4-file layout limits

- xdp: CString for if_nametoindex (was UB), real detach via prog fd
  (fabricated borrow_raw(-1) silently never detached), SAFETY comments,
  saturating expiry math; +5 unit tests
- redis: real pubsub reconnect with exponential backoff (was sleep+return);
  KEYS -> SCAN in heartbeat sweep
- ci: cargo test --all-features, repo-gates job — module size gate
  (scripts/check_module_size.sh, ratchet baseline) + default-secrets grep
- refactor src/ to <=250 LOC/file, <=4 .rs/dir without behavior change;
  thin bins (rampart.rs 330 -> 6 LOC), new app/, subnet/, intel/,
  profile/, prefix/, challenge/, filter/, probe/, inventory/, metrics/, node/
- docs: TODO v5.0 (status refresh, new rules, findings backlog),
  README quickstart now matches real binaries
- verify: fmt/clippy -D warnings/test --all-features (164 tests)/clang XDP green

2026-09-15 23:55:17 +02:00

12 KiB

Raw Blame History

⚠️ UNDER DEVELOPMENT — All performance data, benchmarks, and specifications shown are approximate and subject to change.

⚠️ В РАЗРАБОТКЕ — Все показатели производительности, тесты и характеристики являются примерными и могут измениться.

Rampart

Universal network protection platform (L3/L4/L7 DDoS filtering framework)

English | Русский

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 (feature protocol-http) · 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
↳ `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), 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

# Build (the HTTP protocol handler is a feature)
cargo build --release --features protocol-http

# Install the default config
sudo mkdir -p /etc/rampart
sudo cp deploy/config/edge.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

Documentation

Path	Description
docs/kb/	Knowledge base: attack anatomy, defense levels, practice guides
docs/research/architecture.md	Layered architecture, ADRs, migration notes
docs/research/load-test-report.md	VDS stress test report (2026-08-04)
docs/research/	Research notes: eBPF, anti-bot, DDoS vectors, networking
docs/deployment.md	Deployment guide
docs/configuration.md	Configuration reference
docs/runbook.md	Operations runbook

Roadmap

Stabilize the protocol plugin API
BPF hook modules for deep protocol parsing in XDP

Русский

Обзор

Rampart фильтрует трафик на трёх уровнях до того, как он дойдёт до вашего сервиса:

Уровень ядра — XDP/eBPF отбрасывает нежелательные пакеты до того, как они попадут в TCP-стек Linux;
Сетевой уровень — PoW-challenge повышает стоимость флуда соединений для любого TCP-протокола;
Прикладной уровень — userspace-ядро на Rust выполняет анализ L7-handshake, rate limiting и проверку репутации.

Логика, специфичная для протоколов, вынесена в модульные протокол-плагины — одна платформа защищает VDS, веб-сервисы и игровые серверы.

Архитектура

┌────────────────────────────────────────────────────────────────────┐
│  Слой 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 (feature protocol-http) · grpc (в планах)                  │
└────────────────────────────────────────────────────────────────────┘
     Traffic Intel (EWMA thresholds, профилирование, репутация)
                 работает поперёк всех слоёв

Атакующий → [XDP/eBPF] → [PoW] → [Userspace Core] → [Плагин] → Ваш сервис
                1           2             3             4

Компоненты

Компонент	Роль	Технологии
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
↳ `grpc`	В планах	Rust
docs/kb	Двуязычная база знаний: анатомия атак, уровни защиты, практические руководства	Markdown

Производительность

Только подтверждённые числа — VDS stress test (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 влияния — обрабатывается ядром

Полный набор бенчмарков в процессе подготовки.

Быстрый старт

# Сборка (HTTP-обработчик собирается фичей)
cargo build --release --features protocol-http

# Установка дефолтного конфига
sudo mkdir -p /etc/rampart
sudo cp deploy/config/edge.toml /etc/rampart/config.toml

# Запуск edge ноды (путь конфига берётся из $RAMPART_CONFIG, по умолчанию /etc/rampart/config.toml)
RAMPART_CONFIG=/etc/rampart/config.toml ./target/release/rampart

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

Путь	Описание
docs/kb/	База знаний: анатомия атак, уровни защиты, практические руководства
docs/research/architecture.md	Слоистая архитектура, ADR, миграционные заметки
docs/research/load-test-report.md	Отчёт по VDS stress test (2026-08-04)
docs/research/	Research-заметки: eBPF, антибот, векторы DDoS, сети
docs/deployment.md	Руководство по деплою
docs/configuration.md	Справочник конфигурации
docs/runbook.md	Операционный runbook

Roadmap

Стабилизация API протокол-плагинов
BPF hook модули для глубокого парсинга протоколов в XDP

License

GNU General Public License v3.0

12 KiB Raw Blame History Unescape Escape

Rampart

English

Overview

Architecture

Components

Performance

Quick Start

Documentation

Roadmap

Русский

Обзор

Архитектура

Компоненты

Производительность

Быстрый старт

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

Roadmap

Links

License

12 KiB

Raw Blame History