guard/README.md
loki5512344 918e561a61
feat(xdp): IPv6 UDP rate limit, working loader; English JavaDoc comments
XDP behaviour:
- udp_rate_limit6 (LRU, 128-bit source key) + throttle_hit6, so
  udp_policy = "rate-limit" now applies to native IPv6 as well.
- scripts/xdp_ipv6_smoke.sh: phase 4 patches .rodata before load and
  verifies policy=2 on a real kernel (3 pass / 3 rate-limited).

XDP loader (was completely broken, never reached the verifier):
- .rodata is now one struct rampart_config with frozen offsets enforced by
  _Static_assert; XdpGlobals is #[repr(C)] and the image is built with
  offset_of!. Previously a 96-byte image was written into a 76-byte map at
  offsets clang had reordered, so load() failed with EINVAL.
- patch_rodata fails loudly when the map size and the image size diverge.
- build.rs tracks xdp/core and xdp/hooks, not just universal_filter.c.
- build_ringbuf looked for "events_map"; the map is "events_ringbuf".
- tests/xdp_object_maps.rs: verifies map names and .rodata size without root;
  the real binary was confirmed to attach in a netns.

Docs and style:
- Code comments are English, JavaDoc/Rustdoc style, without emoji or
  decorative banners (new project rule, TODO §0.8).
- README rewritten bilingual: Russian first, English below, TOC and
  copy-paste quick start.
- docs/README.md: documentation index and maintenance rules;
  configuration.md documents the whole [xdp] section and IPv4/IPv6 coverage;
  testing.md describes the real-kernel smoke; stale research links removed.
2026-11-15 23:44:07 +01:00

321 lines
14 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<div align="center">
# 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)
</div>
> [!WARNING]
> Проект в активной разработке. Числа производительности и API могут меняться.
---
<a id="русский"></a>
## Русский
### Содержание
- [Что это](#что-это)
- [Как это работает](#как-это-работает)
- [Возможности](#возможности)
- [Требования](#требования)
- [Быстрый старт](#быстрый-старт)
- [Конфигурация](#конфигурация)
- [Протокол-плагины](#протокол-плагины)
- [Производительность](#производительность)
- [Документация](#документация)
- [Разработка](#разработка)
- [Лицензия](#лицензия)
### Что это
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).
---
<a id="english"></a>
## 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).