feat(xdp): IPv6 UDP rate limit, working loader; English comments and docs
XDP behaviour: - udp_rate_limit6 (LRU, full 128-bit source key) plus throttle_hit6, so udp_policy = "rate-limit" 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). Loader (XDP could never load before this): - .rodata is one struct rampart_config with frozen offsets enforced by _Static_assert; XdpGlobals is #[repr(C)] and the image is built with offset_of!. Before, 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 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 checks map names and .rodata size without root. Docs and style: - Code comments are English, JavaDoc/Rustdoc style, without emoji or banners (new project rule, TODO §0.8). - README rewritten bilingual: Russian first, English below, nav buttons, compact 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 covers the real-kernel smoke; stale links removed.
This commit is contained in:
parent
b64c329125
commit
a8a3057719
104 changed files with 2155 additions and 1030 deletions
66
docs/README.md
Normal file
66
docs/README.md
Normal file
|
|
@ -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` и проверь,
|
||||
что цели существуют.
|
||||
|
|
@ -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*
|
||||
|
|
|
|||
|
|
@ -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) | Обновление версий |
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue