diff --git a/README.md b/README.md
index e45d149..6ee69fe 100644
--- a/README.md
+++ b/README.md
@@ -1,256 +1,337 @@
-
-
-> **⚠️ 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)
+**Универсальная платформа сетевой защиты: L3/L4/L7-фильтрация DDoS для VDS, веб-сервисов и игровых серверов.**

-
+



-[English](#english) | [Русский](#russian)
+[](docs/README.md)
+[](#быстрый-старт)
+[](docs/configuration.md)
+[](docs/api.md)
+[](LICENSE)
-
+[Русский](#русский) · [English](#english)
+
+> **Статус:** проект в активной разработке — API и числа производительности могут меняться.
---
-
-
-## 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 (protocol-http) · Minecraft Java (protocol-minecraft) · 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 |
-| ↳ `minecraft` | Minecraft Java TCP handshake and tunnel, compiled with `protocol-minecraft` | 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 edge handler
-cargo build --release --features protocol-http
-
-# Install the default config
-sudo mkdir -p /etc/rampart
-sudo cp deploy/config/edge-http.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
-```
-
-### Minecraft Java Edge
-
-Rampart also has an early Minecraft Java TCP handler. Build it with
-`cargo build --release --features protocol-minecraft --bin rampart`, copy
-`deploy/config/edge.toml` as its config, and follow
-[docs/minecraft-java.md](docs/minecraft-java.md) for Paper PROXY-protocol and
-private-backend setup. This handler does not protect an already-saturated home
-uplink; use a DDoS-filtering game proxy/provider in front of the edge.
-
-### 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/minecraft-java.md](docs/minecraft-java.md) | Minecraft Java edge and Paper setup |
-| [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
-
----
-
-
-
## Русский
+[Обзор](#обзор) · [Возможности](#возможности) · [Требования](#требования) · [Установка](#установка) · [Быстрый старт](#быстрый-старт) · [Конфигурация](#конфигурация) · [Плагины](#протокол-плагины) · [Производительность](#производительность) · [Документация](#документация) · [Разработка](#разработка) · [Лицензия](#лицензия)
+
### Обзор
-Rampart фильтрует трафик на трёх уровнях до того, как он дойдёт до вашего сервиса:
+Rampart отбрасывает атакующий трафик до того, как он дойдёт до вашего сервиса.
+Фильтрация идёт в три уровня: XDP/eBPF в ядре, PoW-challenge в userspace и
+L7-анализ протокола. Логика конкретного протокола вынесена в плагины, поэтому
+одна платформа защищает и веб-сервис, и игровой сервер.
-- **Уровень ядра** — XDP/eBPF отбрасывает нежелательные пакеты до того, как они попадут в TCP-стек Linux;
-- **Сетевой уровень** — PoW-challenge повышает стоимость флуда соединений для любого TCP-протокола;
-- **Прикладной уровень** — userspace-ядро на Rust выполняет анализ L7-handshake, rate limiting и проверку репутации.
+Подходит, если нужен свой edge-фильтр на VDS: без покупки «коробки», с
+конфигом в TOML и метриками в Prometheus.
-Логика, специфичная для протоколов, вынесена в **модульные протокол-плагины** — одна платформа защищает 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 (protocol-http) · Minecraft Java (protocol-minecraft) · grpc (в планах) │
-└────────────────────────────────────────────────────────────────────┘
- Traffic Intel (EWMA thresholds, профилирование, репутация)
- работает поперёк всех слоёв
-```
+**Как это работает**
```
Атакующий → [XDP/eBPF] → [PoW] → [Userspace Core] → [Плагин] → Ваш сервис
- 1 2 3 4
+ 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) |
-| Компонент | Роль | Технологии |
-|-----------|------|------------|
-| **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 |
-| ↳ `minecraft` | TCP-handshake и туннель Minecraft Java, фича `protocol-minecraft` | Rust |
-| ↳ `grpc` | В планах | Rust |
-| **docs/kb** | Двуязычная база знаний: анатомия атак, уровни защиты, практические руководства | Markdown |
+### Возможности
-### Производительность
+- **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-пороги, профилирование и репутация поверх всех уровней.
-Только подтверждённые числа — 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 влияния — обрабатывается ядром |
+| Компонент | Требование |
+|-----------|------------|
+| Rust | 1.85+ (edition 2024) |
+| XDP | Linux 5.10+, `clang` с `-target bpf`, `libbpf`/`libelf` |
+| Опционально | Redis (синхронизация блэклиста), ClickHouse (события), GeoIP-база |
-Полный набор бенчмарков в процессе подготовки.
+### Установка
+
+```bash
+# Сборка 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`):
+
+```bash
+cargo build --release --features protocol-http,xdp
+```
### Быстрый старт
```bash
-# Сборка HTTP-обработчика
-cargo build --release --features protocol-http
-
-# Установка дефолтного конфига
-sudo mkdir -p /etc/rampart
-sudo cp deploy/config/edge-http.toml /etc/rampart/config.toml
-
-# Запуск edge ноды (путь конфига берётся из $RAMPART_CONFIG, по умолчанию /etc/rampart/config.toml)
RAMPART_CONFIG=/etc/rampart/config.toml ./target/release/rampart
```
-### Minecraft Java Edge
+В конфиге для XDP: `[xdp] enabled = true`, `interface = "eth0"`. Метрики —
+`http://127.0.0.1:9090/metrics`.
-В проекте появился ранний TCP-обработчик Minecraft Java. Соберите его командой
-`cargo build --release --features protocol-minecraft --bin rampart`, скопируйте
-`deploy/config/edge.toml` как конфиг и настройте
-Paper и закрытый backend по инструкции
-[docs/minecraft-java.md](docs/minecraft-java.md). Сам Rampart не спасёт домашний
-канал, если атака уже забила его: перед edge нужен игровой прокси или провайдер
-с фильтрацией DDoS.
+Проверить чекаут перед изменениями:
+
+```bash
+cargo fmt --all --check
+cargo clippy --all-targets --all-features -- -D warnings
+cargo test --all-features
+```
+
+### Конфигурация
+
+```toml
+[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](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](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/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/minecraft-java.md](docs/minecraft-java.md) | Minecraft Java edge и настройка Paper |
-| [docs/configuration.md](docs/configuration.md) | Справочник конфигурации |
-| [docs/runbook.md](docs/runbook.md) | Операционный runbook |
+| Раздел | Где |
+|--------|-----|
+| Индекс всей документации | [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/) |
-### Roadmap
+### Разработка
-- Стабилизация API протокол-плагинов
-- BPF hook модули для глубокого парсинга протоколов в XDP
+- Правила кода и 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).
---
-### Links
+## English
-- [Releases](../../releases)
-- [Issues](../../issues)
-- [License](LICENSE)
+[Overview](#overview) · [Features](#features) · [Requirements](#requirements) · [Installation](#installation) · [Quick start](#quick-start) · [Configuration](#configuration) · [Plugins](#protocol-plugins) · [Performance](#performance) · [Documentation](#documentation) · [Development](#development) · [License](#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
+
+```bash
+# 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`):
+
+```bash
+cargo build --release --features protocol-http,xdp
+```
+
+### Quick start
+
+```bash
+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:
+
+```bash
+cargo fmt --all --check
+cargo clippy --all-targets --all-features -- -D warnings
+cargo test --all-features
+```
+
+### Configuration
+
+```toml
+[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](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](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
+GNU General Public License v3.0 — [LICENSE](LICENSE).
diff --git a/TODO.md b/TODO.md
index e139b5f..bd0d12f 100644
--- a/TODO.md
+++ b/TODO.md
@@ -43,6 +43,19 @@
тесты живут в `tests/` (нужный хелпер делай `pub` с реальным вызовом-потребителем).
Существующие инлайн-тесты — легаси, мигрировать постепенно (см. бэклог).
+### §0.8 Комментарии в коде (все языки)
+- **Все комментарии и doc-комментарии — на английском.** Русский остаётся только в
+ пользовательских текстах: `docs/`, README, TODO, логи (`tracing::*!`), сообщения CLI/ошибок.
+- **JavaDoc/Rustdoc-стиль.** C: `/** ... */` над функцией/структурой/картой/глобалом с
+ `@param`/`@return`, когда они есть. Rust: `//!` для модуля (что он владеет), `///` для
+ элемента; сохраняй секции `# Errors` / `# Panics` / `# Safety`.
+- **Без эмодзи, ASCII-баннеров (`═══`, `───`), CAPS-акцентов** и декоративных разделителей.
+ Для группировки — обычный короткий комментарий.
+- Инлайн-комментарий объясняет **почему**, а не пересказывает код. Комментарий-шум удаляй.
+- Правишь файл — переводи комментарии в нём целиком (смесь языков запрещена), но **не трогай
+ строковые литералы, идентификаторы и логику**.
+- `// SAFETY:` — префикс обязателен, текст по-английски.
+
---
## 1. Целевая структура (v0.3)
@@ -136,6 +149,16 @@ guard/
### Документация
- [x] docs/deployment.md, configuration.md, runbook.md — старых крейтов/MC не упоминают (grep чисто).
- [x] docs/kb/README.md — индекс KB со ссылками.
+- [x] `docs/README.md` — единый индекс документации (начало работы, how-to, reference,
+ протоколы, теория/research) + правила ведения: русский язык, один документ = одна
+ задача, reference правится в том же PR, что и код, плоская структура, kebab-case.
+- [x] `README.md` — двуязычный: русская часть сверху, английская снизу, общая шапка/бейджи/
+ переключатель языка, ряд кнопок-навигации (docs, quick start, config, API, license);
+ секции по конвенции (обзор → возможности → требования → установка → быстрый старт →
+ конфигурация → плагины → производительность → документация → разработка → лицензия),
+ компактный TOC строкой, копируемые команды, ссылки на docs/README.md.
+- [x] `docs/configuration.md` — полная таблица `[xdp]` (включая `udp_policy`) и покрытие IPv4/IPv6;
+ `docs/testing.md` — реальные XDP-smoke'и, а не только clang-проверка.
- [x] TUI (ratatui): live-метрики из Prometheus endpoint — готово (src/tui/, 564613b).
## 2a. Раунд 2026-09-15 — исправлено по итогам ревью
@@ -180,7 +203,14 @@ guard/
- [x] **Тесты**: `tests/xdp_ban_v6.rs` (layout ключа `/64` и `/128`, network order);
`scripts/xdp_ipv6_smoke.sh` — реальный netns+verifier smoke (без бана pass → с баном
blacklist+drop → после снятия снова pass), проверен на ядре 7.3.4.
- - Non-goals (позже): conntrack/throttle/UDP rate-limit (`policy==2`)/RST-challenge для нативного v6
+ - [x] **UDP rate-limit (`policy==2`) для native v6** (2026-11-15): `udp_rate_limit6` (LRU_HASH,
+ 16-байтный ключ `struct in6_addr`, value `struct throttle_entry`) + `throttle_hit6` в
+ `universal_filter.c` (та же семантика окна/порога, что у v4); ветка UDP в `native_v6`
+ теперь `switch (G_UDP_POLICY)`: 1 → DROP, 2 → `throttle_hit6` → DROP при превышении,
+ иначе PASS. Ringbuf-события для v6 по-прежнему не шлём (ABI `src_ip` u32) — только счётчики.
+ Проверка: фаза 4 в `scripts/xdp_ipv6_smoke.sh` (патч `.rodata` до загрузки: policy=2,
+ hits=3 → 3 pass, 3 rate-limit).
+ - Non-goals (позже): conntrack/throttle/RST-challenge для нативного v6
(нужны 128-битные flow/throttle-ключи); whitelist6 (у `whitelist_map` нет писателя даже для v4);
ringbuf-события для v6; unban v6.
- [x] **Expiry бана из userspace не работал в ядре** (найден и починен 2026-11-15, касался v4 и v6):
@@ -194,6 +224,22 @@ guard/
Теперь минимум считается по протоколу (`sizeof(struct udphdr)` для UDP); регрессия —
«короткая датаграмма» в `scripts/xdp_ipv6_smoke.sh`. TCP-путь не изменился: там по-прежнему
требуется полный `struct tcphdr`.
+- [x] **XDP-загрузчик не мог загрузить программу вообще** (найден и починен 2026-11-15).
+ Три независимых бага, каждый из которых валил `load()` до verifier'а:
+ 1. `.rodata`-раскладка: `build_rodata_image` писал 96-байтный образ в 76-байтную карту
+ (`EINVAL`) и по неверным смещениям — clang переставляет отдельные `static volatile const`
+ глобалы (UDP-политика лежала в 4, а не в 49). Теперь в `config.h` один
+ `struct rampart_config` (layout фиксирован C-структурой + `_Static_assert` на каждый
+ offset и размер), `XdpGlobals` получил `#[repr(C)]`, образ строится через `offset_of!`,
+ а `patch_rodata` падает с внятным сообщением при расхождении размера.
+ 2. `build.rs` отслеживал только `universal_filter.c` — правка `config.h`/`common.h` оставляла
+ стухший объект в `OUT_DIR` (и старое `.rodata`). Теперь `rerun-if-changed` на `xdp/core`
+ и `xdp/hooks`.
+ 3. `build_ringbuf` искал карту `events_map`, а в C она `events_ringbuf` —
+ `load()` падал после успешного verifier'а.
+ Регрессии: `tests/xdp_object_maps.rs` (имена всех карт, которые ищет загрузчик, и
+ `value_size` `.rodata` == `RODATA_SIZE`, без root) + перезапуск реального бинаря в netns
+ (attach подтверждён), плюс весь `scripts/xdp_ipv6_smoke.sh`.
## 3. Backlog
diff --git a/build.rs b/build.rs
index cb20306..d254c1b 100644
--- a/build.rs
+++ b/build.rs
@@ -15,6 +15,10 @@ fn main() -> Result<(), Box> {
let dst = out_dir.join("universal_filter.o");
println!("cargo:rerun-if-changed={}", src.display());
+ // config.h/common.h/etc. live in these dirs: without tracking them a header
+ // edit silently keeps a stale object (and a stale .rodata layout).
+ println!("cargo:rerun-if-changed={}", xdp_dir.join("core").display());
+ println!("cargo:rerun-if-changed={}", xdp_dir.join("hooks").display());
let host_triple = std::env::var("HOST").unwrap_or_default();
let arch = host_triple.split('-').next().unwrap_or(&host_triple);
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 0000000..73af69c
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,66 @@
+# Документация Rampart
+
+> Индекс всей документации проекта и правила её ведения.
+> Точка входа — [README.md](../README.md); текущий статус и планы — [TODO.md](../TODO.md).
+
+---
+
+## 1. С чего начать
+
+| Документ | Когда читать |
+|----------|--------------|
+| [deployment.md](deployment.md) | Первый деплой edge-ноды и manager'а |
+| [configuration.md](configuration.md) | Настройка `config.toml`, секция `[xdp]`, переменные manager'а |
+| [runbook.md](runbook.md) | Ежедневная эксплуатация и типовые операции |
+
+## 2. Эксплуатация (how-to)
+
+| Документ | О чём |
+|----------|-------|
+| [runbook.md](runbook.md) | Метрики, рестарты, снятие банов, аварийные процедуры |
+| [troubleshooting.md](troubleshooting.md) | Диагностика типовых проблем |
+| [disaster_recovery.md](disaster_recovery.md) | Восстановление после отказа Redis/ноды |
+| [testing.md](testing.md) | Гейты, тесты, XDP-smoke на реальном ядре |
+
+## 3. Справочник (reference)
+
+| Документ | О чём |
+|----------|-------|
+| [configuration.md](configuration.md) | Все поля конфига и значения по умолчанию |
+| [api.md](api.md) | HTTP API manager'а: аутентификация, эндпоинты |
+| [vds_compatibility.md](vds_compatibility.md) | Ограничения окружений и ядер |
+
+## 4. Протоколы
+
+| Документ | О чём |
+|----------|-------|
+| [minecraft-java.md](minecraft-java.md) | Minecraft-edge: Paper, PROXY protocol, закрытый backend |
+
+## 5. Теория и исследования
+
+| Раздел | О чём |
+|--------|-------|
+| [kb/](kb/README.md) | База знаний: анатомия атак, уровни защиты, практика (двуязычная) |
+| [research/](research/README.md) | Глубокие разборы: архитектура, eBPF, DDoS, Rust-производительность, конкуренты |
+
+`kb/` отвечает на вопрос «как это работает и как защищаться», `research/` — на вопрос
+«какое решение выбрать и почему». Статус проекта не живёт ни там, ни там — только в
+[TODO.md](../TODO.md).
+
+---
+
+## 6. Как вести документацию
+
+1. **Язык.** `docs/` — русский. Исключение: [docs/kb/](kb/README.md), где статьи
+ двуязычные (`## English` / `## Русский`). Комментарии в коде — английский (TODO §0.8).
+2. **Один документ = одна задача.** How-to начинается с цели («что получится в конце»),
+ содержит копируемые команды и заканчивается проверкой результата.
+3. **Reference синхронизируется с кодом в том же PR.** Меняешь поле конфига, флаг CLI
+ или эндпоинт — правишь `configuration.md` / `api.md` там же. Расхождение = баг.
+4. **Новый документ** кладётся в подходящую категорию (2–4) и сразу добавляется в эту
+ таблицу; если он является точкой входа — ссылка добавляется и в корневой README.
+5. **Не размножай папки.** Плоская структура `docs/*.md` — норма; подпапка нужна только
+ для серии документов (`kb/`, `research/`).
+6. **Имена файлов** — kebab-case, `.md`, без дат в имени; дата и версия — внутри документа.
+7. **Никаких битых ссылок.** Перед коммитом: `grep -o '](\.\?[^)]*)' docs/*.md` и проверь,
+ что цели существуют.
diff --git a/docs/configuration.md b/docs/configuration.md
index f3a623d..23f9aa3 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -43,6 +43,18 @@ clickhouse_url = "" # пусто = запись событий вы
[xdp]
enabled = false # требует сборки --features xdp, kernel 5.10+
interface = "eth0"
+protected_port_start = 1 # пакеты вне диапазона уходят в XDP_PASS до фильтра
+protected_port_end = 65535
+udp_policy = "pass" # pass | drop | rate-limit (для IPv4 и IPv6)
+udp_rate_hit_count = 100 # порог пакетов в окне при rate-limit
+udp_rate_window_ms = 1000 # окно rate-limit
+throttle_enabled = true # SYN-throttle (только IPv4)
+events_enabled = true # ringbuf-события в userspace (только IPv4)
+auto_ban_enabled = false # OPT-IN: баны по событиям ringbuf
+auto_ban_duration_secs = 300
+auto_ban_conn_drop_fails = 3
+syn_challenge_enabled = false # RST-challenge (только IPv4)
+challenge_timeout_ms = 3000
[logging]
level = "info" # trace, debug, info, warn, error
@@ -109,6 +121,33 @@ Manager всегда слушает `0.0.0.0:8080`.
clang -O2 -g -target bpf -c xdp/core/universal_filter.c -o /tmp/universal_filter.o
```
+Параметры `[xdp]` (значения по умолчанию — в `src/config/sections/platform.rs`):
+
+| Поле | По умолчанию | Что делает |
+|------|--------------|------------|
+| `enabled` | `false` | Загрузить и приаттачить XDP-программу при старте |
+| `interface` | `eth0` | Интерфейс; native XDP, при отказе драйвера — generic (skb) |
+| `protected_port_start` / `_end` | `1` / `65535` | Порт-гейт: трафик вне диапазона не фильтруется |
+| `udp_policy` | `pass` | `drop` — дропать весь UDP; `rate-limit` — окно на source-IP |
+| `udp_rate_hit_count` / `udp_rate_window_ms` | `100` / `1000` | Порог и окно для `rate-limit` |
+| `throttle_enabled` | `true` | SYN-throttle + авто-бан по `connection_throttle` |
+| `events_enabled` | `true` | Ringbuf-события (rate-limit/conn-drop) в userspace |
+| `auto_ban_enabled` | `false` | OPT-IN: баны по событиям ringbuf |
+| `auto_ban_duration_secs` | `300` | Длительность авто-бана |
+| `auto_ban_conn_drop_fails` | `3` | Порог `conn->fails` для бана по `EVENT_CONN_DROP` |
+| `syn_challenge_enabled` | `false` | RST-challenge (Oubliette liveness proof) |
+| `challenge_secret_hex` | плейсхолдер | 128-битный hex-секрет challenge |
+| `challenge_timeout_ms` | `3000` | TTL pending-challenge |
+
+Покрытие семейств адресов:
+
+- **IPv4**: blacklist, SYN-throttle, conntrack, RST-challenge, ringbuf-события, `udp_policy`
+ (включая `rate-limit`), prefix-статистика.
+- **IPv6**: blacklist (`blacklist6_map`, LPM по `/128` и префиксам), `udp_policy`
+ (включая `rate-limit` с 128-битным ключом), детект TCP-bypass, prefix-статистика.
+ Пока нет: conntrack, SYN-throttle, RST-challenge, ringbuf-события и unban для v6 —
+ для v6 события видны только в счётчиках `stats_map`.
+
---
*Версия: 2.1 | Октябрь 2026*
diff --git a/docs/research/README.md b/docs/research/README.md
index 5282727..157dca6 100644
--- a/docs/research/README.md
+++ b/docs/research/README.md
@@ -19,7 +19,6 @@
| [haproxy.md](./haproxy.md) | HAProxy конфиг, mTLS, замена на Rust LB | v0.2 |
| [envoy.md](./envoy.md) | EWMA балансировка, Circuit Breaker, xDS API | v0.5 |
| [observability.md](./observability.md) | Prometheus, OpenTelemetry, ClickHouse, Parca | v0.3 |
-| [minecraft-protocol.md](./minecraft-protocol.md) | Handshake парсинг, VarInt, Forge, fingerprinting | v0.1 |
| [anti-bot.md](./anti-bot.md) | Sonar, challenge системы, AI-обходы, fingerprint | v0.2 |
| [benchmark.md](./benchmark.md) | Инструменты, методология, ожидаемые результаты | v0.3 |
| [security.md](./security.md) | STRIDE, mTLS, Zero Trust, supply chain | v0.2 |
@@ -32,8 +31,7 @@
```
Хочу написать первую версию (v0.1)
- → architecture.md + minecraft-protocol.md + ddos.md
-
+ → architecture.md + ddos.md
Хочу добавить защиту от ботов
→ anti-bot.md
@@ -61,7 +59,6 @@
| [api.md](../api.md) | REST API спецификация |
| [testing.md](../testing.md) | Методология тестирования |
| [troubleshooting.md](../troubleshooting.md) | FAQ |
-| [migration.md](../migration.md) | Обновление версий |
---
diff --git a/docs/testing.md b/docs/testing.md
index d080950..b08a62c 100644
--- a/docs/testing.md
+++ b/docs/testing.md
@@ -37,6 +37,19 @@ XDP: smoke-check компиляции BPF-программы:
clang -O2 -g -target bpf -c xdp/core/universal_filter.c -o /tmp/universal_filter.o
```
+Функциональные проверки на реальном ядре (нужен root: CAP_BPF + CAP_NET_ADMIN,
+`bpftool`, `clang`, `python3`):
+
+```bash
+sudo bash scripts/xdp_ipv6_smoke.sh
+```
+
+Поднимает netns + veth, грузит программу через verifier и проверяет: бан IPv6 и IPv4
+(включая короткие UDP-датаграммы), снятие бана, истечение TTL по монотонным часам и
+`udp_policy = "rate-limit"` для IPv6 (политика патчится в `.rodata` до загрузки).
+`scripts/xdp_netns_smoke.sh` дополнительно гоняет реальный бинарь `rampart` end-to-end
+(требует `hping3`).
+
---
## 3. Локальный integration-стенд (Docker)
diff --git a/scripts/xdp_ipv6_smoke.sh b/scripts/xdp_ipv6_smoke.sh
index 1492014..eb0ce6e 100755
--- a/scripts/xdp_ipv6_smoke.sh
+++ b/scripts/xdp_ipv6_smoke.sh
@@ -1,17 +1,20 @@
#!/usr/bin/env bash
-# Функциональный smoke XDP-банов на РЕАЛЬНОМ ядре (netns + veth + verifier).
+# Functional smoke test of XDP bans on a real kernel (netns + veth + verifier).
#
-# Что проверяет:
-# 1. verifier принимает universal_filter.o;
-# 2. native-IPv6 без бана проходит, с записью /128 в blacklist6_map — дропается;
-# 3. короткая UDP-датаграмма (<20 байт L4) тоже дропается — раньше она уходила
-# в XDP_PASS мимо blacklist (проверка длины была рассчитана на TCP);
-# 4. то же для IPv4 (общий L4-гейт);
-# 5. expiry: бан с монотонным TTL реально истекает в ядре (раньше userspace
-# писал epoch-ns, а C сравнивал с bpf_ktime_get_ns() — бан жил вечно).
+# What it verifies:
+# 1. the verifier accepts universal_filter.o;
+# 2. native IPv6 traffic passes without a ban and is dropped once a /128
+# entry exists in blacklist6_map;
+# 3. a short UDP datagram (under 20 bytes of L4) is dropped as well; it used
+# to fall through to XDP_PASS past the blacklist because the length check
+# was sized for TCP;
+# 4. the same holds for IPv4, through the shared L4 gate;
+# 5. expiry: a ban with a monotonic TTL really expires in the kernel; it
+# used to live forever because userspace wrote epoch-ns while the C side
+# compared against bpf_ktime_get_ns().
#
-# Требует root/CAP_BPF+CAP_NET_ADMIN, bpftool, clang, python3.
-# Запуск: sudo bash scripts/xdp_ipv6_smoke.sh
+# Requires root/CAP_BPF+CAP_NET_ADMIN, bpftool, clang, python3.
+# Run: sudo bash scripts/xdp_ipv6_smoke.sh
set -u
@@ -30,6 +33,7 @@ PASS=1
fail() { echo "FAIL: $1"; PASS=0; }
ok() { echo "ok: $1"; }
+# Detach and remove every artefact, so a rerun starts from a clean state.
cleanup() {
bpftool net detach xdp dev "$DEV0" 2>/dev/null
rm -f "$PIN" "$OBJ"
@@ -41,11 +45,13 @@ trap cleanup EXIT
[ "$(id -u)" = 0 ] || { echo "нужен root (CAP_BPF+CAP_NET_ADMIN)"; exit 2; }
cd "$(dirname "$0")/.." || exit 2
+# Build the object once; the same binary is reused for every phase below.
clang -O2 -g -target bpf -mcpu=v3 -c xdp/core/universal_filter.c -o "$OBJ" \
-Ixdp -Ixdp/core -Ixdp/hooks -I/usr/include/x86_64-linux-gnu \
|| { echo "clang: не собралось"; exit 1; }
ok "clang: universal_filter.c собран"
+# Isolated namespace with one veth pair: host side is DEV0, peer is DEV1.
ip netns add "$NS" || { echo "не удалось создать netns"; exit 2; }
ip link add "$DEV0" type veth peer name "$DEV1" || exit 2
ip link set "$DEV1" netns "$NS"
@@ -58,36 +64,43 @@ ip -n "$NS" link set "$DEV1" up
ip -n "$NS" link set lo up
ok "netns $NS + veth ($HOST6/$HOST4 <-> $NS6/$NS4)"
+# Loading through the verifier is itself a check: a rejected program exits here.
bpftool prog load "$OBJ" "$PIN" type xdp || { echo "verifier отверг программу"; exit 1; }
bpftool net attach xdp pinned "$PIN" dev "$DEV0" || exit 1
ok "verifier принял программу, attach на $DEV0"
-IDS=$(bpftool prog show pinned "$PIN" | grep -o 'map_ids [0-9,]*' | cut -d' ' -f2 | tr ',' ' ')
-B4=""
-B6=""
-ST=""
-for id in $IDS; do
- desc=$(bpftool map show id "$id" 2>/dev/null)
- case "$desc" in
- *"name blacklist6_map"*) B6=$id ;;
- *"name blacklist_map"*) B4=$id ;;
- *"name stats_map"*) ST=$id ;;
- esac
-done
-[ -n "$B4" ] && [ -n "$B6" ] && [ -n "$ST" ] || { echo "карты не найдены"; exit 1; }
+# Resolve map ids from the pinned program; ids change on every load.
+discover_maps() {
+ IDS=$(bpftool prog show pinned "$PIN" | grep -o 'map_ids [0-9,]*' | cut -d' ' -f2 | tr ',' ' ')
+ B4=""
+ B6=""
+ ST=""
+ for id in $IDS; do
+ desc=$(bpftool map show id "$id" 2>/dev/null)
+ case "$desc" in
+ *"name blacklist6_map"*) B6=$id ;;
+ *"name blacklist_map"*) B4=$id ;;
+ *"name stats_map"*) ST=$id ;;
+ esac
+ done
+ [ -n "$B4" ] && [ -n "$B6" ] && [ -n "$ST" ]
+}
+discover_maps || { echo "карты не найдены"; exit 1; }
ok "blacklist_map id=$B4, blacklist6_map id=$B6, stats_map id=$ST"
-# Ключи LPM: prefixlen (u32 LE) + адрес в network order.
+# LPM keys: prefixlen (u32 LE) followed by the address in network order.
KEY6="80 00 00 00 fd 00 00 00 00 00 00 00 00 00 00 00 00 00 00 02"
KEY4="20 00 00 00 0a 63 00 02"
-send6() { # $1 = размер payload
+# Send one IPv6 UDP datagram of $1 payload bytes from inside the namespace.
+send6() {
ip netns exec "$NS" python3 -c "
import socket
s = socket.socket(socket.AF_INET6, socket.SOCK_DGRAM)
s.sendto(b'x' * $1, ('$HOST6', $PORT))
"
}
+# Same for IPv4.
send4() {
ip netns exec "$NS" python3 -c "
import socket
@@ -96,7 +109,7 @@ s.sendto(b'x' * $1, ('$HOST4', $PORT))
"
}
-# Суммы per-CPU счётчиков (только ненулевые).
+# Sum the per-CPU counters and print only the non-zero ones.
stats() {
bpftool -j map dump id "$ST" | python3 -c "
import json, sys
@@ -110,9 +123,11 @@ for e in json.load(sys.stdin):
print(' '.join(f'{k}={v}' for k, v in out.items() if v) or 'все нули')
"
}
+# Read a single counter value; empty output means the counter is zero.
metric() { stats | tr ' ' '\n' | sed -n "s/^$1=//p" | head -1; }
-mono_ns_hex() { # монотонные ns + $1 секунд, 8 байт little-endian
+# Monotonic now + $1 seconds as 8 little-endian bytes, the kernel's ban TTL format.
+mono_ns_hex() {
python3 -c "
import time
ns = time.clock_gettime_ns(time.CLOCK_MONOTONIC) + $1 * 1_000_000_000
@@ -120,7 +135,7 @@ print(' '.join(f'{b:02x}' for b in ns.to_bytes(8, 'little')))
"
}
-# ── Фаза 1: IPv6 ──
+# Phase 1: IPv6 — traffic passes, a ban drops it, removing the ban restores it.
pass0=$(metric pass)
for _ in 1 2 3; do send6 100; done
sleep 0.5
@@ -132,7 +147,7 @@ pass1=$(metric pass)
drop0=$(metric drop)
bpftool map update id "$B6" key hex $KEY6 value hex ff ff ff ff ff ff ff ff || fail "v6 map update"
for _ in 1 2 3; do send6 100; done
-for _ in 1 2 3; do send6 1; done # короткая датаграмма
+for _ in 1 2 3; do send6 1; done # short datagram
sleep 0.5
drop1=$(metric drop)
[ "${drop1:-0}" -ge $((${drop0:-0} + 6)) ] \
@@ -148,10 +163,11 @@ pass3=$(metric pass)
&& ok "v6 после снятия бана проходит (pass $pass2 -> $pass3)" \
|| fail "v6 после снятия бана не проходит ($(stats))"
-# ── Фаза 2: IPv4 (общий L4-гейт) ──
+# Phase 2: IPv4 through the shared L4 gate — only short datagrams, which is
+# the min_l4 regression.
drop0=$(metric drop)
bpftool map update id "$B4" key hex $KEY4 value hex ff ff ff ff ff ff ff ff || fail "v4 map update"
-for _ in 1 2 3; do send4 1; done # только короткие — регрессия на min_l4
+for _ in 1 2 3; do send4 1; done # short datagrams only — the min_l4 regression
sleep 0.5
drop1=$(metric drop)
[ "${drop1:-0}" -ge $((${drop0:-0} + 3)) ] \
@@ -159,7 +175,8 @@ drop1=$(metric drop)
|| fail "v4 короткая датаграмма прошла мимо бана ($(stats))"
bpftool map delete id "$B4" key hex $KEY4 || fail "v4 map delete"
-# ── Фаза 3: expiry бана (монотонные часы) ──
+# Phase 3: ban expiry on the monotonic clock. A TTL written in epoch-ns would
+# never expire against bpf_ktime_get_ns(), so this phase pins the clock choice.
TTL=2
bpftool map update id "$B6" key hex $KEY6 value hex $(mono_ns_hex $TTL) || fail "expiry update"
drop0=$(metric drop)
@@ -179,5 +196,47 @@ drop3=$(metric drop); pass3=$(metric pass)
&& ok "бан истёк по монотонным часам (pass $pass2 -> $pass3, drop $drop2 -> $drop3)" \
|| fail "бан не истёк (pass $pass2 -> $pass3, drop $drop2 -> $drop3)"
-[ "$PASS" = 1 ] && echo "PASS: XDP-баны (v4/v6, короткий L4, expiry) работают на живом ядре" || echo "FAIL"
-[ "$PASS" = 1 ]
+# Phase 4: UDP rate-limit (policy=2) for native IPv6.
+# Policy is a .rodata global and libbpf freezes .rodata after load, so the
+# object section is patched before loading. The offsets are pinned by the
+# _Static_asserts in xdp/core/config.h: udp_policy @49, udp_hit_count @52.
+POBJ="$OBJ.rl"
+cp "$OBJ" "$POBJ"
+if llvm-objcopy --dump-section .rodata="$POBJ.rodata" "$POBJ" \
+ && python3 - "$POBJ.rodata" <<'PY' \
+ && llvm-objcopy --update-section .rodata="$POBJ.rodata" "$POBJ"
+import sys
+path = sys.argv[1]
+img = bytearray(open(path, "rb").read())
+assert len(img) >= 56, f"unexpected .rodata size {len(img)}"
+img[49] = 2 # G_UDP_POLICY = rate-limit
+img[52:56] = (3).to_bytes(4, "little") # G_UDP_HIT_COUNT = 3 (fast trigger)
+open(path, "wb").write(img)
+PY
+then
+ # Reload with the patched policy; map ids are invalidated by the reload.
+ ip link set "$DEV0" xdp off 2>/dev/null
+ rm -f "$PIN"
+ if bpftool prog load "$POBJ" "$PIN" type xdp \
+ && bpftool net attach xdp pinned "$PIN" dev "$DEV0"; then
+ if discover_maps; then
+ rl0=$(metric rate); pass0=$(metric pass)
+ for _ in 1 2 3 4 5 6; do send6 100; done
+ sleep 0.3
+ rl1=$(metric rate); pass1=$(metric pass)
+ [ "${rl1:-0}" -gt "${rl0:-0}" ] && [ "${pass1:-0}" -gt "${pass0:-0}" ] \
+ && ok "v6 UDP rate-limit policy=2 (rate $rl0 -> $rl1, pass $pass0 -> $pass1)" \
+ || fail "v6 UDP rate-limit не срабатывает ($(stats))"
+ else
+ fail "карты не найдены после перезагрузки с policy=2"
+ fi
+ else
+ fail "объект с policy=2 не загрузился"
+ fi
+ rm -f "$POBJ" "$POBJ.rodata"
+else
+ fail "не удалось пропатчить .rodata (policy=2)"
+fi
+
+[ "$PASS" = 1 ] && echo "PASS: XDP-баны и UDP rate-limit (v4/v6) работают на живом ядре" || echo "FAIL"
+[ "$PASS" = 1 ]
\ No newline at end of file
diff --git a/scripts/xdp_netns_smoke.sh b/scripts/xdp_netns_smoke.sh
index 557aa10..3c786a0 100755
--- a/scripts/xdp_netns_smoke.sh
+++ b/scripts/xdp_netns_smoke.sh
@@ -1,18 +1,20 @@
#!/usr/bin/env bash
-# netns+veth smoke-тест XDP-пути на РЕАЛЬНОМ ядре (вывод №7 конкурентного анализа).
+# netns + veth smoke test of the XDP path on a real kernel (finding #7 of the
+# concurrency analysis).
#
-# Проверяет то, что невозможно проверить в контейнере CI без CAP_BPF:
-# 1. verifier принимает universal_filter.o (загрузка через libbpf);
-# 2. attach на живом интерфейсе в netns, native-режим;
-# 3. легитимный HTTP проксируется;
-# 4. SYN-флуд порождает ringbuf-события -> opt-in auto-ban работает;
-# 5. по завершении бана трафик восстанавливается (expiry);
-# 6. после SIGTERM XDP-ПРОГРАММА РЕАЛЬНО ОТВЯЗАНА (регрессия на bug fd=-1).
+# Covers what cannot be checked in a CI container without CAP_BPF:
+# 1. the verifier accepts universal_filter.o (loaded through libbpf);
+# 2. attach on a live interface inside a netns, native mode;
+# 3. legitimate HTTP is proxied;
+# 4. a SYN flood produces ringbuf events, so opt-in auto-ban works;
+# 5. traffic recovers once the ban expires;
+# 6. after SIGTERM the XDP program is really detached (regression on the
+# fd=-1 bug).
#
-# Запуск: на хосте с root/CAP_BPF (VDS или VM-раннер CI), не в контейнере:
+# Run: on a host with root/CAP_BPF (VDS or a VM CI runner), not in a container:
# BIN=./target/release/rampart bash scripts/xdp_netns_smoke.sh
#
-# Требования: iproute2, bpftool, hping3, python3 (http.server), curl.
+# Requires: iproute2, bpftool, hping3, python3 (http.server), curl.
set -u
@@ -32,6 +34,7 @@ PASS=1
fail() { echo "FAIL: $1"; PASS=0; }
ok() { echo "ok: $1"; }
+# Kill both processes and drop the namespace, whatever the exit path was.
cleanup() {
[ -n "$RAMPID" ] && kill -9 "$RAMPID" 2>/dev/null
[ -n "$SRVPID" ] && kill -9 "$SRVPID" 2>/dev/null
@@ -43,7 +46,8 @@ trap cleanup EXIT
[ "$(id -u)" = 0 ] || { echo "нужен root (CAP_BPF+CAP_NET_ADMIN)"; exit 2; }
[ -x "$BIN" ] || { echo "бинарь не найден: $BIN"; exit 2; }
-# --- 1. netns + veth: весь тест изолирован, прод-трафик не затрагивается ---
+# Phase 1: netns plus veth, so the whole test is isolated and production
+# traffic is never touched.
ip netns del "$NS" 2>/dev/null
ip netns add "$NS" || { echo "не удалось создать netns"; exit 2; }
ip link add rth0 type veth peer name rtap
@@ -54,7 +58,8 @@ ip -n "$NS" link set rtap up
ip -n "$NS" link set lo up
ok "netns $NS + veth подняты"
-# --- 2. конфиг edge: узкий защищённый диапазон, автобан включён (иначе нечего тестить) ---
+# Phase 2: edge config. The protected range is a single port and auto-ban is
+# on, otherwise there is nothing to observe.
cat > "$WORK/edge.toml" <rampart-smoke-origin