loki5512344
aa615a1141
- 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
233 lines
12 KiB
Markdown
233 lines
12 KiB
Markdown
<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)
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
[English](#english) | [Русский](#russian)
|
||
|
||
</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 (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](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 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/](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/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
|
||
|
||
---
|
||
|
||
<a name="russian"></a>
|
||
|
||
## Русский
|
||
|
||
### Обзор
|
||
|
||
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](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 влияния — обрабатывается ядром |
|
||
|
||
Полный набор бенчмарков в процессе подготовки.
|
||
|
||
### Быстрый старт
|
||
|
||
```bash
|
||
# Сборка (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/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/configuration.md](docs/configuration.md) | Справочник конфигурации |
|
||
| [docs/runbook.md](docs/runbook.md) | Операционный runbook |
|
||
|
||
### Roadmap
|
||
|
||
- Стабилизация API протокол-плагинов
|
||
- BPF hook модули для глубокого парсинга протоколов в XDP
|
||
|
||
---
|
||
|
||
### Links
|
||
|
||
- [Releases](../../releases)
|
||
- [Issues](../../issues)
|
||
- [License](LICENSE)
|
||
|
||
### License
|
||
|
||
GNU General Public License v3.0
|