docs: per-task roadmap, architecture and changelog

- Split TODO into a thin status index plus docs/roadmap/ with one file per
  task (v0.4 reliability, v0.5 product, v0.6 research, icebox).
- Add docs/architecture.md (current processes, packet/data path, layers,
  storage, metrics) and docs/development.md (rules, gates, DoD).
- Add CHANGELOG.md reconstructed from history; move round details out of
  TODO.
- Align docs with the code: config defaults and missing [detect]/
  [protocol.http] sections, XDP metric names, ClickHouse table and TTL,
  Redis RDB restore, multiarch clang include, CLI binary name.
- Add scripts/check_docs_links.sh and run it in CI.
- release profile: thin LTO + one codegen unit. Binary 12.3 MB -> 9.7 MB,
  http parser bench 314 ns -> 278 ns; panic=abort stays off for
  catch_unwind in the Redis subscriber.
- Drop the unused JWT role claim; fix 'rampart doctor' hints in the CLI.
This commit is contained in:
Loki 2026-11-16 14:51:50 +01:00
parent 1b3ae5e546
commit 280284667f
Signed by: boba
GPG key ID: 6CDE87BC9A778D97
38 changed files with 1582 additions and 623 deletions

View file

@ -1,7 +1,8 @@
# Документация Rampart
> Индекс всей документации проекта и правила её ведения.
> Точка входа — [README.md](../README.md); текущий статус и планы — [TODO.md](../TODO.md).
> Точка входа — [README.md](../README.md); текущий статус — [TODO.md](../TODO.md);
> история — [CHANGELOG.md](../CHANGELOG.md).
---
@ -9,9 +10,10 @@
| Документ | Когда читать |
|----------|--------------|
| [architecture.md](architecture.md) | Понять устройство: процессы, путь трафика, слои, хранилища, метрики |
| [deployment.md](deployment.md) | Первый деплой edge-ноды и manager'а |
| [configuration.md](configuration.md) | Настройка `config.toml`, секция `[xdp]`, переменные manager'а |
| [runbook.md](runbook.md) | Ежедневная эксплуатация и типовые операции |
| [configuration.md](configuration.md) | Все поля `config.toml` и переменные окружения Manager |
| [development.md](development.md) | Правила кода, тестов, гейты и Definition of Done |
## 2. Эксплуатация (how-to)
@ -26,41 +28,63 @@
| Документ | О чём |
|----------|-------|
| [configuration.md](configuration.md) | Все поля конфига и значения по умолчанию |
| [api.md](api.md) | HTTP API manager'а: аутентификация, эндпоинты |
| [configuration.md](configuration.md) | Все поля конфига, границы и значения по умолчанию |
| [api.md](api.md) | HTTP API manager'а: аутентификация, эндпоинты, лимиты |
| [vds_compatibility.md](vds_compatibility.md) | Ограничения окружений и ядер |
## 4. Протоколы
## 4. Планы и процесс
| Документ | О чём |
|----------|-------|
| [roadmap/README.md](roadmap/README.md) | Индекс задач по версиям, статусы, правила ведения |
| [roadmap/](roadmap/) | По одному файлу на задачу (v0.4, v0.5, v0.6, icebox) |
| [development.md](development.md) | KISS/DRY/SOLID, лимиты файлов, гейты, anti-patterns |
| [../TODO.md](../TODO.md) | Только текущий статус и ссылки на планы |
| [../CHANGELOG.md](../CHANGELOG.md) | Что и когда изменилось |
## 5. Протоколы
| Документ | О чём |
|----------|-------|
| [minecraft-java.md](minecraft-java.md) | Minecraft-edge: Paper, PROXY protocol, закрытый backend |
## 5. Теория и исследования
## 6. Теория и исследования
| Раздел | О чём |
|--------|-------|
| [kb/](kb/README.md) | База знаний: анатомия атак, уровни защиты, практика (двуязычная) |
| [research/](research/README.md) | Глубокие разборы: архитектура, eBPF, DDoS, Rust-производительность, конкуренты |
`kb/` отвечает на вопрос «как это работает и как защищаться», `research/` — на вопрос
«какое решение выбрать и почему». Статус проекта не живёт ни там, ни там — только в
[TODO.md](../TODO.md).
`kb/` отвечает на вопрос «как это работает и как защищаться», `research/` — на
вопрос «какое решение выбрать и почему». Статус проекта не живёт ни там, ни там —
только в [TODO.md](../TODO.md) и [roadmap/](roadmap/README.md).
---
## 6. Как вести документацию
## 7. Как вести документацию
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` и проверь,
что цели существуют.
двуязычные (`## English` / `## Русский`). Комментарии в коде — английский
([development.md](development.md) §5).
2. **Один документ = одна задача.** How-to начинается с цели («что получится в
конце»), содержит копируемые команды и заканчивается проверкой результата.
3. **Reference синхронизируется с кодом в том же PR.** Меняешь поле конфига, флаг
CLI или эндпоинт — правишь `configuration.md` / `api.md` там же. Расхождение =
баг.
4. **Планы не растут в TODO.** Новая задача — новый файл в
[roadmap/](roadmap/README.md); в `TODO.md` добавляется только строка-ссылка.
5. **Новый документ** кладётся в подходящую категорию (1–6) и сразу добавляется в
эту таблицу; если он является точкой входа — ссылка добавляется и в корневой
README.
6. **Не размножай папки.** Плоская структура `docs/*.md` — норма; подпапка нужна
только для серии документов (`kb/`, `research/`, `roadmap/`).
7. **Имена файлов** — kebab-case, `.md`, без дат в имени; дата и версия — внутри
документа.
8. **Никаких битых ссылок.** Перед коммитом: `bash scripts/check_docs_links.sh`
(этот же скрипт работает в CI).
9. **Не дублируй архитектуру.** Схемы и описания слоёв живут в
[architecture.md](architecture.md); остальные документы ссылаются на него.
---
*Версия: 3.0 | Ноябрь 2026*

View file

@ -3,8 +3,9 @@
> REST API управления. Base URL: `http://MANAGER:8080`
> Авторизация: Bearer JWT (получить через `/api/v1/auth/login`).
Реализованные маршруты — см. src/bin/rampart-manager.rs. Это полный список:
ничего сверх перечисленного здесь API не предоставляет.
Реализованные маршруты — см. `src/manager/api/guard/router.rs` (единственное место
сборки роутера, включая тесты). Это полный список: ничего сверх перечисленного
здесь API не предоставляет.
---
@ -142,7 +143,8 @@ Edge подписывается на Pub/Sub перед загрузкой сн
Честно, на текущий момент в API **нет**:
- drain нод через API или CLI;
- drain нод через API (CLI-команда `rampart-cli drain <node>` существует, но
завершается явной ошибкой «not implemented»);
- webhooks, metrics summary, challenge management;
- регистрации нод через `POST /api/v1/nodes`.
@ -157,4 +159,4 @@ Edge подписывается на Pub/Sub перед загрузкой сн
---
*Версия: 2.0 | Август 2026*
*Версия: 2.1 | Ноябрь 2026*

212
docs/architecture.md Normal file
View file

@ -0,0 +1,212 @@
# Architecture — Rampart
> Текущее устройство системы: процессы, путь пакета и соединения, слои фильтрации,
> хранилища и наблюдаемость. Планы — в [roadmap/](roadmap/README.md); правила
> разработки — в [development.md](development.md); исследования и обоснования —
> в [research/](research/architecture.md).
---
## 1. Назначение
Rampart отбрасывает атакующий трафик до того, как он дойдёт до сервиса. Одна
платформа защищает TCP-сервис любого типа: веб-приложение, API, игровой сервер.
Логика конкретного протокола вынесена в compile-time плагины, поэтому ядро не
знает о Minecraft или HTTP ничего.
Модель угроз: распределённый флуд соединениями (SYN/connection flood), мусорные
L7-handshake, медленные клиенты (slowloris), ботнет с ротацией адресов внутри
подсети, повторные попытки с уже забаненных адресов. Rampart — stateless-фильтр
и не заменяет firewall или WAF: он не хранит тело запроса и не анализирует
шифрованный трафик.
## 2. Процессы
| Бинарь | Роль | Порты |
|--------|------|-------|
| `rampart` | edge-нода: XDP → PoW → userspace → плагин → upstream | `bind.port` (25565), metrics `[metrics].port` (9090) |
| `rampart-manager` | REST API и инвентарь | `0.0.0.0:8080` |
| `rampart-cli` | клиент manager API (`status`, `doctor`, `blacklist`, …) | — |
| `rampart-tui` | live-дашборд по Prometheus | — |
Edge и manager — независимые процессы. Связь только через Redis (баны, инвентарь,
heartbeat); без Redis edge продолжает работать автономно.
## 3. Путь трафика edge
```
client → eth0 → [XDP/eBPF] → kernel TCP → accept → Gateway → plugin → upstream
│ │
└─ ringbuf events → autoban └─ Redis/ClickHouse
```
### 3.1 XDP (C, `xdp/core/`)
Stateless-фильтр на входе интерфейса. Разбирает Ethernet (VLAN/QinQ), IPv4/IPv6,
L4; порт-гейт `[xdp] protected_port_start/end` отсекает нецелевой трафик до
фильтра.
| Механизм | IPv4 | IPv6 |
|----------|------|------|
| Blacklist LPM (`/32`, `/128`, префиксы) | да | да |
| Whitelist LPM | да | да |
| TCP conntrack, SYN-throttle | да | нет |
| RST-challenge (liveness proof) | да | нет |
| UDP policy: pass/drop/rate-limit | да | да |
| Prefix-статистика (`/24`, `/64`) | да | да |
| Ringbuf-события | да | нет (только счётчики) |
Карты (`xdp/core/maps.h`): `blacklist_map`, `blacklist6_map`, `whitelist_map`,
`whitelist6_map`, `connection_map`, `throttle_map`, `prefix_stats`, `stats_map`,
`events_ringbuf`, `syn_challenge`-карты. Значение бана — монотонное время
истечения (`bpf_ktime_get_ns`), просроченные записи чистит userspace-reaper.
### 3.2 Gateway (Rust, `src/engine/tunnel/gateway/`)
Порядок фильтров на одно соединение (важен для безопасности и стоимости):
1. Whitelist — доверенный адрес обходит все проверки и никогда не банится.
2. Blacklist (local + Redis).
3. Subnet tracker: запись источника для детектора подсетей.
4. Per-IP rate limit (token bucket) — до PoW, чтобы несолвенный клиент не занимал
задачу.
5. Глобальный бюджет соединений — защита от перегрузки accept-loop.
6. Per-IP лимит одновременных соединений.
7. PoW-гейт (опционально; несовместим с Minecraft).
8. Handshake плагина с таймаутом.
9. Connect к upstream, отправка preamble (например, PROXY v2), relay с idle-таймаутом.
Соединения принимает `src/engine/listener.rs`: несколько воркеров с
`SO_REUSEPORT`, backoff на `accept()` при `EMFILE`/`ENOMEM`, graceful shutdown
через `watch`-канал. Ingress PROXY v2 (`[proxy_protocol]`) принимается только от
`trusted_cidrs`; адрес из заголовка валидируется и не может быть loopback/
link-local/multicast/broadcast или адресом самого прокси.
### 3.3 Протокол-плагины (`src/protocol/`)
`ProtocolHandler` — трейт: разобрать handshake, вернуть upstream и байты,
которые нужно отправить в backend до relay. Плагины включаются feature-флагами:
- `protocol-http` — HTTP/1.1 request-head: allow/reject, лимит заголовков,
blocked paths, обязательный User-Agent.
- `protocol-minecraft` — Minecraft Java handshake/list/login, один upstream,
опциональный PROXY v2 к Paper.
Реестр (`ProtocolRegistry`) выбирает активный плагин; пустой реестр — fail-fast
при старте с подсказкой про фичи.
### 3.4 Detection и реакция (`src/traffic/`, `src/engine/subnet/`)
- `AttackDetector` — EWMA baseline по pps/cps, состояния normal → suspicious →
under_attack с гистерезисом.
- `IpReputation` — score источника; хорошие соединения повышают, плохие понижают.
- `SubnetDetector` — превышение порога префиксом при адресах под per-IP лимитом;
лестница вердиктов: strict limit → challenge → block префикса (через `ban_cidr`,
не слепой hard-ban).
- `TrafficHook` — единая точка авто-бана; сверяется с `trusted_cidrs` и
подавляет бан доверенной сети.
- `AlertDispatcher` — алерт только на переход состояния, опционально webhook.
## 4. Manager API
`src/manager/` — axum-роутер, JWT (HS256, audience, `JWT_SECRET` ≥ 32 байт),
per-IP лимиты (5 login/мин, 30 мутаций/мин), тело ≤ 8 КиБ, таймаут 10 с,
CORS только по явному `CORS_ORIGIN`.
| Маршрут | Доступ | Источник |
|---------|--------|----------|
| `GET /api/v1/health` | публичный | процесс |
| `POST /api/v1/auth/login` | публичный | `API_PASSWORD` |
| `GET /api/v1/servers` | JWT | Redis `rampart:servers:*` |
| `GET/POST/DELETE /api/v1/blacklist` | JWT | Redis set + metadata hash + pub/sub |
| `GET /api/v1/nodes` | JWT | Redis `rampart:nodes:*` (heartbeat) |
Мутации публикуют событие в `rampart:blacklist:events`; edge подписывается до
загрузки снимка, поэтому события во время загрузки не теряются. Полный контракт —
[api.md](api.md).
## 5. Хранилища
| Хранилище | Что хранит | Без него |
|-----------|------------|----------|
| Redis | blacklist set + metadata, pub/sub событий, инвентарь нод и серверов | edge автономен, кросс-нодовые баны не работают |
| ClickHouse | события атак и соединений (`rampart_events`) | запись событий выключена |
| Prometheus | метрики edge | дашборд/TUI без данных |
Redis-клиент работает через `ConnectionManager` с таймаутами и реконнектом;
снимок банов восстанавливается после переподключения с оставшимся TTL.
## 6. Наблюдаемость
`GET /metrics` на edge (Prometheus text format).
| Метрика | Тип | Смысл |
|---------|-----|-------|
| `rampart_connections_total{result}` | counter | allowed / blocked / overloaded |
| `rampart_rate_limit_hits{action}` | counter | срабатывания лимитов |
| `rampart_pow_challenges_total{result}` | counter | выдан/решён/отклонён |
| `rampart_pow_current_difficulty` | gauge | текущая сложность |
| `rampart_attack_status` | gauge | 0 normal, 1 suspicious, 2 under attack |
| `rampart_subnet_verdicts_total{verdict}` | counter | вердикты детектора подсетей |
| `rampart_auto_bans_total{reason}` | counter | авто-баны userspace |
| `rampart_intel_cps` | gauge | новые соединения/с в окне |
| `rampart_intel_rate_limit_drops_total` | counter | дропы по репутации |
| `rampart_intel_alerts_total` | counter | алерты на переход состояния |
| `rampart_xdp_*` | gauge | счётчики `stats_map`: `total`, `tcp`, `udp`, `whitelist`, `blacklist`, `syn_throttle`, `rate_limit`, `passed`, `dropped`, `challenge_sent`, `challenge_verified`, `challenge_failed`, `fragment_bypass` |
| `rampart_xdp_autobans_total` | counter | авто-баны из ringbuf |
| `rampart_clickhouse_dropped_total` | counter | потерянные события ClickHouse |
TUI (`src/tui/`) читает те же метрики через Prometheus HTTP.
## 7. Конфигурация
Единый `config.toml` для edge; manager настраивается переменными окружения.
Все секции опциональны, значения по умолчанию — в `src/config/sections/`;
семантическая валидация выполняется до bind. Полная таблица полей, границ и
дефолтов — [configuration.md](configuration.md).
Ключевые инварианты:
- `proxy_protocol.ingress_enabled` требует непустой `trusted_cidrs` и
`protocol.minecraft`.
- `xdp.syn_challenge_enabled` требует свой `challenge_secret_hex` (placeholder
отклоняется).
- `backend.upstreams` не пуст и валиден; для Minecraft — ровно один upstream.
- `ban.ban_duration_secs` ∈ `1..=31_536_000`, `pow.difficulty` ∈ `1..=10`,
`workers.count ≥ 1`.
- `limits.relay_idle_timeout_secs` ∈ `1..=86_400`.
## 8. Карта модулей
```
src/
├── app/ сборка рантайма, фоновые задачи, graceful shutdown
├── bin/ тонкие точки входа (логика в lib)
├── cli/ команды rampart-cli
├── config/ Config + sections/ + trusted CIDR
├── engine/ listener, tunnel/gateway|proxy, challenge, subnet
├── filter/ blacklist, rate_limit, connection_limit, geo
├── manager/ axum API, auth, sync/heartbeat
├── metrics.rs Prometheus registry и scrape endpoint
├── protocol/ трейт ProtocolHandler, реестр, http, minecraft
├── store/ redis (+sync), clickhouse
├── traffic/ hook, prefix, intel (ewma/detector/reputation), profile
├── tui/ ratatui-дашборд
└── xdp/ загрузчик, globals, probe/diagnostics, noop
xdp/
├── core/ universal_filter.c + maps/stats/config/common/prefix/syn_challenge
└── hooks/ hook_api.h — контракт BPF-хуков
```
## 9. Ограничения и деградация
- XDP выключен или недоступен → защита работает в userspace; логируется честный
режим (native/generic/none).
- Redis недоступен → edge автономен, manager отдаёт `503` на inventory/blacklist.
- ClickHouse недоступен → события теряются, защита работает; счётчик дропов растёт.
- Перегрузка → глобальный бюджет отклоняет соединения (`overloaded`), а не
копит задачи в памяти.
---
*Версия: 1.0 | Ноябрь 2026*

View file

@ -1,9 +1,19 @@
# Configuration - Rampart
# Configuration — Rampart
> Единый конфиг edge-ноды (`config.toml`) и переменные окружения Manager.
> Схема конфига: `src/config/sections.rs` — единственный источник правды.
> Источник правды: `src/config/mod.rs` и `src/config/sections/`. Меняешь поле —
> правь эту таблицу в том же PR.
## 1. Edge (`config.toml`, путь задаётся `RAMPART_CONFIG`)
---
## 1. Edge (`config.toml`)
Путь по умолчанию — `/etc/rampart/config.toml`, переопределяется переменной
`RAMPART_CONFIG`. Все секции опциональны; при отсутствии используются дефолты из
таблиц ниже. Валидация выполняется до bind сокета: неверное значение — отказ
старта с внятной ошибкой.
### 1.1 Корень и входящий трафик
```toml
# Корневые поля должны стоять до первой TOML-секции.
@ -14,88 +24,203 @@ address = "0.0.0.0"
port = 25565
[backend]
# Список TCP-бэкендов (addr:port). Для Minecraft нужен ровно один backend.
upstreams = ["127.0.0.1:25566"]
[workers]
count = 4
[limits]
handshake_timeout_secs = 5
max_connections_per_ip = 10
rate_limit_pps = 5.0
rate_limit_burst = 10.0
relay_idle_timeout_secs = 300
[ban]
ban_duration_secs = 3600
```
| Поле | По умолчанию | Ограничения и смысл |
|------|--------------|---------------------|
| `whitelist` | `[]` | Только IP-адреса (без CIDR). Обходят все фильтры, throttle и баны; адрес из whitelist никогда не банится |
| `bind.address` | `0.0.0.0` | Адрес прослушивания (IPv4 или IPv6) |
| `bind.port` | `25565` | Защищаемый TCP-порт |
| `backend.upstreams` | `["127.0.0.1:25566"]` | `addr:port`; список не пуст, каждый адрес валиден; Minecraft требует ровно один |
| `workers.count` | `4` | Accept-loop'ы с `SO_REUSEPORT`; ≥ 1 |
| `limits.handshake_timeout_secs` | `5` | Таймаут handshake/connect (slowloris-защита) |
| `limits.max_connections_per_ip` | `10` | Одновременные соединения с одного IP; > 0 |
| `limits.rate_limit_pps` | `5.0` | Новые соединения/с с одного IP; конечно и > 0 |
| `limits.rate_limit_burst` | `10.0` | Burst token bucket; ≥ 1 |
| `limits.relay_idle_timeout_secs` | `300` | Простой relay до разрыва; `1..=86400` |
| `ban.ban_duration_secs` | `3600` | Длительность бана; `1..=31_536_000` (год) |
### 1.2 PROXY protocol и PoW
```toml
[proxy_protocol]
ingress_enabled = false
trusted_cidrs = []
ingress_timeout_ms = 750
max_header_bytes = 512
[pow]
enabled = false
difficulty = 4
```
| Поле | По умолчанию | Ограничения и смысл |
|------|--------------|---------------------|
| `proxy_protocol.ingress_enabled` | `false` | Принимать PROXY v2 от внешнего TCP-прокси; требует непустой `trusted_cidrs` и `protocol.minecraft.enabled` |
| `proxy_protocol.trusted_cidrs` | `[]` | Точные адреса/CIDR самих прокси, не «весь DC» |
| `proxy_protocol.ingress_timeout_ms` | `750` | `1..=5000` |
| `proxy_protocol.max_header_bytes` | `512` | `52..=4096` |
| `pow.enabled` | `false` | Hashcash-challenge поверх любого TCP; несовместим с `protocol.minecraft.enabled` |
| `pow.difficulty` | `4` | Стартовая и минимальная сложность; `1..=10`, растёт под нагрузкой |
`trusted_cidrs` — это адреса самих прокси, а не клиентов: IP из заголовка
используется для per-IP лимитов, репутации и банов, поэтому любой хост внутри
`trusted_cidrs` может назвать себя кем угодно. Заголовок с адресом из
`trusted_cidrs`, а также unspecified/loopback/link-local/multicast/broadcast
отклоняется: клиентом считается transport peer (событие пишется в debug один раз
на соединение). Адреса из `trusted_cidrs` не банятся локально, в Redis и XDP.
### 1.3 XDP
```toml
[xdp]
enabled = false
interface = "eth0"
protected_port_start = 1
protected_port_end = 65535
udp_policy = "pass"
udp_rate_hit_count = 100
udp_rate_window_ms = 1000
throttle_enabled = true
events_enabled = true
auto_ban_enabled = false
auto_ban_duration_secs = 60
auto_ban_conn_drop_fails = 3
syn_challenge_enabled = false
challenge_secret_hex = "" # обязателен при syn_challenge_enabled
challenge_timeout_ms = 3000
```
| Поле | По умолчанию | Что делает |
|------|--------------|------------|
| `enabled` | `false` | Загрузить и приаттачить программу; требует сборки `--features xdp` |
| `interface` | `eth0` | Интерфейс; сначала native XDP, при отказе драйвера — generic (skb) |
| `protected_port_start` / `_end` | `1` / `65535` | Порт-гейт: трафик вне диапазона не фильтруется |
| `udp_policy` | `pass` | `pass`, `drop` или `rate-limit` (окно по source-IP) |
| `udp_rate_hit_count` / `udp_rate_window_ms` | `100` / `1000` | Порог и окно для `rate-limit` |
| `throttle_enabled` | `true` | SYN-throttle и авто-бан по `connection_throttle` (IPv4) |
| `events_enabled` | `true` | Ringbuf-события в userspace (IPv4) |
| `auto_ban_enabled` | `false` | OPT-IN: баны по событиям ringbuf |
| `auto_ban_duration_secs` | `60` | Длительность авто-бана |
| `auto_ban_conn_drop_fails` | `3` | Порог `conn->fails` для бана по `EVENT_CONN_DROP` |
| `syn_challenge_enabled` | `false` | RST-challenge (Oubliette-style liveness proof), IPv4 |
| `challenge_secret_hex` | — | 128-битный hex-секрет (`openssl rand -hex 8`); placeholder запрещён |
| `challenge_timeout_ms` | `3000` | TTL pending-challenge |
Поведение фильтра:
- **Stateless-фильтр, не firewall.** Conntrack ведётся только для TCP-соединений,
начатых с SYN; пакет без состояния (non-SYN) пропускается, чтобы фильтр не рвал
ответы на исходящие соединения демона и keep-alive health-check'ов.
- **VLAN/QinQ** (802.1Q и 802.1ad, до двух тегов) разбираются; **фрагменты**
проверяются по source-IP в blacklist и пропускаются, счётчик — `fragment_bypass`.
- **Whitelist** загружается в `whitelist_map`/`whitelist6_map` при attach и
обходит state machine, throttle и баны.
- **CIDR-баны** матчатся LPM-трией; userspace — диапазонами, поэтому `/24` и `/64`
покрывают всю подсеть.
- **Оценка числа источников** в префиксе: XDP ведёт 64-битный bitmap хешей
source-адресов, userspace считает popcount (spoof-gate работает и на XDP-пути).
Счётчики префиксов сбрасываются при чтении, окно = интервал опроса монитора.
Покрытие семейств:
- **IPv4**: blacklist, SYN-throttle, conntrack, RST-challenge, ringbuf-события,
`udp_policy` (включая `rate-limit`), prefix-статистика.
- **IPv6**: blacklist, whitelist, `udp_policy` (включая `rate-limit` с 128-битным
ключом), детект TCP-bypass, prefix-статистика. Пока нет: conntrack,
SYN-throttle, RST-challenge, ringbuf-события и unban — для v6 только счётчики.
### 1.4 Детекция и алерты
```toml
[detect.prefix]
enabled = false
syn_threshold = 500
window_secs = 10
min_unique_sources = 16
[detect.autoban]
enabled = false
reputation_threshold = -50
[detect.alert]
webhook_url = ""
```
| Поле | По умолчанию | Смысл |
|------|--------------|-------|
| `detect.prefix.enabled` | `false` | Детектор атак на уровне подсети (`/24`, `/64`) |
| `detect.prefix.syn_threshold` | `500` | Порог соединений на префикс в окне; при `enabled` обязан быть > 0 |
| `detect.prefix.window_secs` | `10` | Окно детектора |
| `detect.prefix.min_unique_sources` | `16` | Минимум уникальных источников (spoof-gate) |
| `detect.autoban.enabled` | `false` | Авто-бан по score репутации |
| `detect.autoban.reputation_threshold` | `-50` | Порог score; TTL — `ban.ban_duration_secs` |
| `detect.alert.webhook_url` | — | Webhook на переход состояния атаки |
### 1.5 Протоколы, логи, метрики, хранилища
```toml
[protocol.http]
max_header_bytes = 8192
timeout_secs = 5
blocked_paths = ["/wp-login.php"]
require_user_agent = false
[protocol.minecraft]
enabled = true
max_frame_bytes = 8192
timeout_secs = 5
send_proxy_protocol = false
[workers]
count = 4
[limits]
handshake_timeout_secs = 5 # таймаут чтения (slowloris-защита)
max_connections_per_ip = 10 # одновременные соединения с одного IP
rate_limit_pps = 5.0 # лимит коннектов/сек с одного IP
rate_limit_burst = 10.0 # burst
relay_idle_timeout_secs = 300 # простой relay до разрыва, 1..86400
[ban]
ban_duration_secs = 3600
[store]
redis_url = "" # пусто = синхронизация блэклиста выключена
blacklist_cache_ttl_secs = 300
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
format = "text" # text или json
level = "info"
format = "text"
[metrics]
enabled = true
port = 9090
[pow]
enabled = false # PoW challenge, OFF по умолчанию
difficulty = 4
# Входящий PROXY v2 от известного TCP DDoS-прокси; включай только если
# прокси действительно отправляет этот заголовок.
[proxy_protocol]
ingress_enabled = false
trusted_cidrs = []
ingress_timeout_ms = 750
max_header_bytes = 512
[store]
redis_url = ""
blacklist_cache_ttl_secs = 300
clickhouse_url = ""
```
Этот пример выбирает Minecraft Java и требует сборки с `protocol-minecraft`.
Для HTTP используй сборку `protocol-http` и удали `[protocol.minecraft]`.
| Поле | По умолчанию | Смысл |
|------|--------------|-------|
| `protocol.http.max_header_bytes` | `8192` | Лимит request-head; > 0 |
| `protocol.http.timeout_secs` | `5` | Таймаут чтения заголовков; > 0 |
| `protocol.http.blocked_paths` | `[]` | Точные пути, которые отклоняются |
| `protocol.http.require_user_agent` | `false` | Отклонять запросы без `User-Agent` |
| `protocol.minecraft.enabled` | `true` при сборке без `protocol-http` | Активный MC-handler |
| `protocol.minecraft.max_frame_bytes` | `8192` | Лимит кадра; > 0 |
| `protocol.minecraft.timeout_secs` | `5` | Таймаут handshake; > 0 |
| `protocol.minecraft.send_proxy_protocol` | `false` | Отправлять PROXY v2 на Paper; alias — `proxy_protocol` |
| `logging.level` | `info` | `trace`, `debug`, `info`, `warn`, `error` |
| `logging.format` | `text` | `text` или `json` |
| `metrics.enabled` | `true` | Prometheus endpoint |
| `metrics.port` | `9090` | Порт метрик |
| `store.redis_url` | — | Пусто = синхронизация банов выключена |
| `store.blacklist_cache_ttl_secs` | `300` | TTL локального кеша blacklist |
| `store.clickhouse_url` | — | Пусто = запись событий выключена |
Все секции опциональны — при отсутствии используются дефолты из таблицы выше.
Для ingress PROXY v2 укажи сети именно прокси в `trusted_cidrs`; включение без
доверенной сети отклоняется при чтении конфига.
`trusted_cidrs` — это точные адреса/CIDR самих прокси, а не «весь DC»: IP из
заголовка используется для per-IP лимитов, репутации и банов, поэтому любой хост
внутри `trusted_cidrs` может назвать себя кем угодно. Заголовок с адресом из
`trusted_cidrs` (прокси не может быть клиентом за самим собой) или с
unspecified/loopback/link-local/multicast/broadcast адресом отклоняется, и
клиентом считается transport peer — событие пишется в debug один раз на
соединение. Адреса из `trusted_cidrs` никогда не банятся локально, в Redis и XDP;
попытка бана подавляется с предупреждением в логе.
`send_proxy_protocol` отправляет заголовок на Paper backend; прежнее имя
`proxy_protocol` внутри `[protocol.minecraft]` остаётся допустимым alias.
`[protocol.http]` существует только при сборке с `protocol-http`,
`[protocol.minecraft]` — только с `protocol-minecraft`; секция без
соответствующей фичи игнорируется. Для HTTP удали `[protocol.minecraft]`.
## 2. Manager (переменные окружения)
@ -106,75 +231,40 @@ unspecified/loopback/link-local/multicast/broadcast адресом отклон
| `JWT_AUDIENCE` | нет | `rampart` | Audience JWT |
| `JWT_EXPIRATION_SECS` | нет | `86400` | Время жизни токена |
| `API_PASSWORD` | да | — | Пароль для `/api/v1/auth/login`, минимум 16 символов; `changeme` запрещён |
| `CORS_ORIGIN` | нет | — (CORS выключен) | `*` — разрешить все источники; список через запятую; пусто/не задано — запретить cross-origin |
| `MANAGER_TRUSTED_PROXIES` | нет | — (никому не доверяем) | Сети reverse-прокси через запятую (`10.0.0.0/8,2001:db8::/32`). `X-Forwarded-For` учитывается только для запросов, пришедших с адреса из этих сетей; иначе клиентом считается TCP peer. Пусто/не задано — заголовок игнорируется полностью. Опечатка или пустая запись в списке не даёт менеджеру стартовать |
| `CORS_ORIGIN` | нет | — | `*` — разрешить всё; список origin'ов через запятую; пусто — cross-origin запрещён |
| `MANAGER_TRUSTED_PROXIES` | нет | — | Сети reverse-прокси через запятую. `X-Forwarded-For` учитывается только для запросов из этих сетей; опечатка/пустая запись → отказ старта |
Manager всегда слушает `0.0.0.0:8080`.
## 3. Feature flags сборки (Cargo.toml)
## 3. Feature flags сборки
| Feature | По умолчанию | Что включает |
|---------|--------------|--------------|
| `store-redis` | ✅ | Redis-клиент и синхронизация блэклиста |
| `geoip` | ❌ | GeoIP lookup (maxminddb) |
| `store-redis` | ✅ | Redis-клиент и синхронизация blacklist |
| `geoip` | ❌ | GeoIP lookup (maxminddb; реализация — roadmap v0.5) |
| `xdp` | ❌ | Загрузка XDP-программы через libbpf-rs |
| `io-uring` | ❌ | splice/io_uring I/O |
| `protocol-http` | ❌ | HTTP/1.1 handler; включай только для HTTP upstream |
| `protocol-minecraft` | ❌ | Minecraft Java TCP handshake и проксирование |
| `io-uring` | ❌ | splice/io_uring I/O (реализация — roadmap v0.6) |
| `protocol-http` | ❌ | HTTP/1.1 handler |
| `protocol-minecraft` | ❌ | Minecraft Java handshake и проксирование |
Пример: `cargo build --release --features xdp --bin rampart`.
```bash
cargo build --release --features xdp,protocol-http --bin rampart
```
## 4. BPF/XDP программа
Исходник: `xdp/core/universal_filter.c`. Smoke-check компиляции:
Исходник — `xdp/core/universal_filter.c`. Smoke-check компиляции:
```bash
clang -O2 -g -target bpf -c xdp/core/universal_filter.c -o /tmp/universal_filter.o
mkdir -p target/xdp
clang -O2 -g -target bpf -I"/usr/include/$(gcc -print-multiarch)" \
-c xdp/core/universal_filter.c -o target/xdp/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` | — (обязателен при `syn_challenge_enabled`) | 128-битный hex-секрет, например `openssl rand -hex 8`; встроенный плейсхолдер запрещён |
| `challenge_timeout_ms` | `3000` | TTL pending-challenge |
Поведение XDP-фильтра:
- **Stateless-фильтр, не firewall.** Состояние conntrack ведётся только для TCP-соединений,
начатых с SYN. Пакет без состояния (non-SYN) пропускается: включение фильтра не рвёт
ответы на исходящие соединения самого демона и keep-alive от health-check'ов.
- **VLAN/QinQ** (802.1Q и 802.1ad, до двух тегов) разбираются; **фрагменты** проверяются по
source-IP в blacklist и пропускаются (не дропаются), счётчик — `frag` в `stats_map`.
- **Whitelist** из корневого `whitelist = [...]` загружается в XDP-карты (`whitelist_map`,
`whitelist6_map`) при attach и обходит state machine, throttle и баны.
- **CIDR-баны**: XDP матчит по LPM-трие, userspace — по диапазонам адресов, поэтому бан
`/24` или `/64` покрывает всю подсеть.
- **Оценка числа источников** в префиксе: XDP ведёт 64-битный bitmap хешей source-адресов,
userspace считает popcount. Благодаря этому spoof-gate (не банить `/24`, если в нём лишь
пара адресов) работает и на XDP-пути. Счётчики префиксов сбрасываются при каждом чтении,
то есть окно = интервал опроса монитора.
Покрытие семейств адресов:
- **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`.
`-I` с multiarch нужен, потому что `-target bpf` не ищет
`/usr/include/<triple>` по умолчанию. Полный прогон на реальном ядре —
`scripts/xdp_ci.sh` (см. [testing.md](testing.md)).
---
*Версия: 2.1 | Октябрь 2026*
*Версия: 3.0 | Ноябрь 2026*

View file

@ -145,4 +145,4 @@ redis_url = "redis://:PASSWORD@redis:6379/0"
---
*Версия: 2.1 | Октябрь 2026*
*Версия: 3.0 | Ноябрь 2026*

116
docs/development.md Normal file
View file

@ -0,0 +1,116 @@
# Development — правила разработки Rampart
> Как мы пишем код, тесты и коммиты. Планы задач — в [roadmap/](roadmap/README.md),
> устройство системы — в [architecture.md](architecture.md).
---
## 1. Принципы
**KISS → DRY → SOLID → YAGNI.**
- Не добавляй абстракцию до третьего повторения.
- Повтор > 2 раз выноси, но лучше копипаста, чем неправильная абстракция.
- S: один файл = одна ответственность. O: расширение через трейты (`ProtocolHandler`,
`Filter`). I: маленькие трейты вместо God-trait. D: core зависит от трейтов, не от
Redis/ClickHouse напрямую.
- Не пиши BGP до v0.6, WASM-плагины до стабилизации compile-time API. Feature flag
только для готовой фичи.
## 2. Ограничения размера
- **Функция ≤ 60 строк, файл ≤ 250 строк, ≤ 4 `.rs`-файлов на папку.**
- Больше — декомпозиция по доменам с реэкспортами в `mod.rs`.
- Гейт: `scripts/check_module_size.sh` + ratchet-базлайн `.module_size_baseline`
(легаси — WARN, новое нарушение — FAIL; после рефакторинга
`--update-baseline`).
- `tests/` вне лимита: Cargo требует один файл = один бинарь.
## 3. Rust-правила
1. `unwrap()` — только в `main()` и тестах; в коде — `?` или явная обработка.
2. `unsafe` — только в `xdp/`, обязателен комментарий `// SAFETY:` с предусловиями.
3. `clone()` осознанно: горячий путь профилируется, а не «на всякий случай».
4. Блокирующие операции — в `spawn_blocking`.
5. Логи — `tracing::{info,debug,warn,error}`; `print_*` запрещён clippy-линтом.
6. Метрика регистрируется один раз при старте, инкремент — в горячем пути.
7. `panic`, `dbg!`, `exit` запрещены линтами; выход процесса — только в `main`.
## 4. Тесты
- Тесты живут в `tests/`, не в `src/`: `#[cfg(test)]`-модулей в коде нет.
- Хелпер, нужный тесту, становится `pub` только при наличии реального потребителя.
- На новый слой — интеграционный тест на слой (config parse, filter logic,
registry fail-fast).
- Для бага сначала красный тест, потом фикс.
- Feature-gated код обязан собираться и тестироваться в CI
(`--all-features` и `--no-default-features`).
## 5. Комментарии
- **Все комментарии и doc-комментарии — на английском.** Русский остаётся в
`docs/`, README, TODO, логах (`tracing::*!`) и сообщениях CLI/ошибок.
- Rustdoc-стиль: `//!` для модуля (что он владеет), `///` для элемента; секции
`# Errors` / `# Panics` / `# Safety` сохраняются.
- C: `/** ... */` над функцией/структурой/картой/глобалом, с `@param`/`@return`,
когда они есть.
- Без эмодзи, ASCII-баннеров и декоративных разделителей.
- Инлайн-комментарий объясняет **почему**, а не пересказывает код.
- Правишь файл — переводи комментарии в нём целиком; не трогай строковые
литералы, идентификаторы и логику.
## 6. Рабочий процесс
1. Новая функциональность → сначала дизайн (что и зачем, альтернативы), потом план.
2. Баг → сначала корневая причина, потом фикс; симптомные заплатки запрещены.
3. Любая правка кода → тест (сначала падающий) → реализация.
4. Перед «готово» — свежий прогон гейтов и вывод, а не воспоминания.
## 7. Гейты
```bash
cargo fmt --all --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all-features
cargo test --no-default-features --features protocol-http
cargo deny check
bash scripts/check_module_size.sh
bash scripts/check_default_secrets.sh
bash scripts/check_docs_links.sh
```
Плюс `make ebpf` (clang BPF) и `make fuzz` (nightly, 60 с на цель).
XDP-путь на реальном ядре — `scripts/xdp_ci.sh` (задача v0.4).
## 8. Definition of Done
```
☐ cargo check / cargo test проходят
☐ clippy --all-targets --all-features -- -D warnings — 0 warnings
☐ cargo fmt --check проходит
☐ ни один файл > 250 строк; ни в одной папке src/ > 4 .rs-файлов
☐ тесты покрывают happy path + 2+ error case
☐ нет мёртвого кода: pub без вызовов, конфиг-поле без потребителя, метрика без writer
☐ нет дефолтных секретов
☐ README/docs соответствуют коду; план задачи обновлён
☐ CHANGELOG обновлён
☐ CI зелёный
```
## 9. Anti-patterns
```
❌ Тесты после кода.
❌ Файл > 250 строк или > 4 .rs в папке.
❌ TODO в коде без ссылки на план.
❌ Мёртвый код: pub без вызовов, конфиг-поле без потребителя, метрика без writer.
❌ «Бумажный слой»: фича описана, но не вызывается.
❌ Дефолтный секрет.
❌ Парсер за «один read» — TCP-поток приходит фрагментами.
❌ Feature flag, который не собирается в CI.
❌ Документ, описывающий несуществующую команду.
```
---
*Версия: 1.0 | Ноябрь 2026*

View file

@ -29,11 +29,11 @@ Edge нода упала:
### Симптомы
- Edge перестал синхронизировать блэклист
- Manager API отдаёт пустые списки nodes/servers/blacklist
- Manager API отвечает `503` на `/nodes`, `/servers` и `/blacklist`
### Влияние
- **Edge:** работает с локальным кэшем; новые баны не распространяются между нодами.
- **Manager:** данные из Redis недоступны.
- **Manager:** Redis-зависимые эндпоинты отвечают `503`.
### Действия
@ -92,7 +92,7 @@ journalctl -u rampart -n 50 --no-pager
dmesg | grep -i "oom\|rampart" # OOM kill?
systemctl restart rampart
# Не стартует — проверь конфиг и логи (см. runbook.md §2)
# Не стартует — проверь конфиг и логи (см. runbook.md §3)
```
### Предотвращение
@ -123,8 +123,13 @@ df -h /var/lib/clickhouse # диск полон?
# 1. Поднять Manager на новой VDS
docker compose up -d redis && cargo run --release --bin rampart-manager
# 2. Восстановить Redis из бэкапа
redis-cli --pipe < /backup/rampart-redis-$(date +%Y-%m-%d).rdb
# 2. Восстановить Redis из RDB-бэкапа. `redis-cli --pipe` для этого не подходит:
# он принимает RESP-команды, а не дамп. Порядок:
systemctl stop redis
sudo cp /backup/rampart-redis-$(date +%Y-%m-%d).rdb /var/lib/redis/dump.rdb
sudo chown redis:redis /var/lib/redis/dump.rdb
systemctl start redis
redis-cli DBSIZE # снимок загрузился?
# 3. Edge ноды переподключатся автоматически
@ -146,4 +151,8 @@ ss -s | grep TCP
---
*Версия: 2.0 | Август 2026*
Готовый список остальных проверок — в [troubleshooting.md](troubleshooting.md) и
[runbook.md](runbook.md); план развития диагностики — в
[roadmap/v0.4-startup-diagnostics.md](roadmap/v0.4-startup-diagnostics.md).
*Версия: 3.0 | Ноябрь 2026*

View file

@ -3,7 +3,8 @@
> Это исследовательская документация. Здесь живут глубокие разборы технологий,
> эксперименты и идеи для версий v0.4+.
>
> Для текущей архитектуры (v0.1-v0.3) смотри `ARCHITECTURE.md` в корне репо.
> Для текущей архитектуры смотри [../architecture.md](../architecture.md); здесь —
> исследования, эксперименты и обоснования решений.
---
@ -11,7 +12,7 @@
| Файл | Что внутри | Актуально с |
|---|---|---|
| [architecture.md](./architecture.md) | Общая архитектура, компоненты, схемы C4 | v0.1 |
| [architecture.md](./architecture.md) | Дизайн-обоснование универсального редизайна (историческое) | v0.3 |
| [ddos.md](./ddos.md) | Векторы атак L3/L4/L7, методы защиты, AI-боты | v0.1 |
| [ebpf.md](./ebpf.md) | XDP/eBPF фильтр, BPF maps, ringbuf, verifier | v0.4 |
| [rust-performance.md](./rust-performance.md) | Zero-copy, io_uring, SO_REUSEPORT, NUMA, profiling | v0.3 |
@ -30,7 +31,9 @@
## Как читать
```
Хочу написать первую версию (v0.1)
Хочу понять текущее устройство
→ ../architecture.md
Хочу понять, почему система такая
→ architecture.md + ddos.md
Хочу добавить защиту от ботов
→ anti-bot.md

View file

@ -1,7 +1,8 @@
# Architecture — Rampart
# Architecture — Rampart (design rationale, v0.3)
> Relevant for: v0.3+ (universal redesign)
> Status: primary design document
> Status: historical design rationale — the current system is described in
> [../architecture.md](../architecture.md)
> Language: English (research notes) — see [RU summary](#russian-summary) at the end
---

79
docs/roadmap/README.md Normal file
View file

@ -0,0 +1,79 @@
# Roadmap — Rampart
> Индекс планов по версиям. `TODO.md` в корне — только статус и ссылки сюда;
> детали каждой задачи живут в отдельном файле этой папки.
---
## 1. Правила
1. **Одна задача = один файл.** Имя: `<version>-<topic>.md`, kebab-case, без дат.
2. **Файл создаётся, когда задача попадает в план**, а не когда её начинают.
Пока задача не начата, достаточно цели, объёма и критериев приёмки.
3. **Статус меняется в двух местах одновременно:** в шапке файла задачи и в
таблице `TODO.md`. Расхождение = баг документации.
4. **Завершённая задача** получает `Status: done`, ссылку на коммит(ы) и остаётся
в папке до релиза; после релиза её содержимое переносится в
[CHANGELOG.md](../../CHANGELOG.md), а файл удаляется.
5. **Не плоди версии.** Если задача не влезает в текущий milestone, она едет в
`icebox-*.md`, а не в «v0.7».
6. **Планы не врут.** Команды и пути в плане проверяются по коду в том же PR.
## 2. Статусы
| Статус | Значение |
|--------|----------|
| `idea` | сформулирована, не оценена |
| `planned` | есть цель, объём и критерии приёмки, можно брать |
| `design` | идёт обсуждение дизайна (brainstorming) |
| `ready` | дизайн утверждён, есть пошаговый план |
| `in-progress` | реализуется |
| `blocked` | ждёт внешнего решения или зависимости |
| `done` | готова, влита, отражена в CHANGELOG |
| `dropped` | решено не делать; причина в файле |
## 3. Milestones
| Версия | Тема | Критерий выхода |
|--------|------|-----------------|
| v0.4 | Надёжность и воспроизводимость | XDP проверяется в CI, старт даёт честный вердикт об окружении, нет self-lockout |
| v0.5 | Продуктовые фичи | RST-challenge доведён до GA, внешние списки и API пригодны для интеграций, GeoIP/ASN, gRPC |
| v0.6 | Исследования | решения из backlog с доказанной пользой; каждая фича начинается с бенчмарка/прототипа |
| icebox | Отложено | без даты; берётся только при явном запросе |
## 4. v0.4 — надёжность
| Задача | Приоритет | Статус | План |
|--------|-----------|--------|------|
| XDP netns+veth harness в CI | P0 | planned | [v0.4-xdp-ci-harness.md](v0.4-xdp-ci-harness.md) |
| Startup-диагностика окружения | P1 | planned | [v0.4-startup-diagnostics.md](v0.4-startup-diagnostics.md) |
| Anti-lockout и баны по порту | P1 | planned | [v0.4-anti-lockout.md](v0.4-anti-lockout.md) |
## 5. v0.5 — продуктовые фичи
| Задача | Приоритет | Статус | План |
|--------|-----------|--------|------|
| RST-challenge: довести до GA | P0 | planned | [v0.5-rst-challenge-ga.md](v0.5-rst-challenge-ga.md) |
| Pinned maps + OpenAPI | P1 | idea | [v0.5-pinned-maps-openapi.md](v0.5-pinned-maps-openapi.md) |
| GeoIP/ASN reputation | P1 | idea | [v0.5-geoip-asn.md](v0.5-geoip-asn.md) |
| gRPC protocol plugin | P2 | idea | [v0.5-grpc-plugin.md](v0.5-grpc-plugin.md) |
## 6. v0.6 — исследования
| Задача | Приоритет | Статус | План |
|--------|-----------|--------|------|
| HTTP поверх XDP (BPF hook) | P1 | idea | [v0.6-http-over-xdp.md](v0.6-http-over-xdp.md) |
| Bloom filter для blacklist | P3 | idea | [v0.6-bloom-filter.md](v0.6-bloom-filter.md) |
| io_uring runtime | P3 | idea | [v0.6-io-uring.md](v0.6-io-uring.md) |
| ML anomaly detection | P3 | idea | [v0.6-ml-anomaly.md](v0.6-ml-anomaly.md) |
| BGP Anycast | P3 | idea | [v0.6-bgp-anycast.md](v0.6-bgp-anycast.md) |
## 7. Icebox
| Задача | Почему отложена | План |
|--------|-----------------|------|
| Minecraft Velocity forwarding | нужен только если MC-сегмент остаётся целевым | [icebox-minecraft-velocity.md](icebox-minecraft-velocity.md) |
---
*Версия: 1.0 | Ноябрь 2026*

View file

@ -0,0 +1,32 @@
# Icebox — Minecraft Velocity forwarding
| | |
|---|---|
| Milestone | icebox |
| Status | dropped |
| Priority | — |
| Depends on | решение о приоритете MC-сегмента |
## Цель
Поддержка Velocity modern forwarding в `protocol-minecraft`, чтобы edge мог
работать перед Velocity, а не только перед Paper.
## Почему отложено
v0.3 сознательно ушёл от Minecraft-специфичности к универсальной платформе.
Функция нужна только если MC-сегмент остаётся целевым; при этом современный
forwarding требует HMAC-секрета и меняет модель доверия между edge и прокси.
## Что нужно, если браться
- Разбор `login_start` с forwarding-полями и проверка HMAC.
- Конфиг с секретом (fail-fast, без дефолта) и ротацией.
- Игровые netns smoke-тесты и нагрузочная проверка (сейчас есть только
TCP-handshake тесты).
- Документация: схема edge → Velocity → Paper, кто кому доверяет.
## Критерии возврата из icebox
Явный запрос пользователя + подтверждение, что MC-трафик — приоритетнее v0.5/v0.6
задач.

View file

@ -0,0 +1,56 @@
# v0.4 — Anti-lockout и баны по порту
| | |
|---|---|
| Milestone | v0.4 |
| Status | planned |
| Priority | P1 |
| Depends on | — |
## Цель
Админ не может заблокировать сам себя, а бан применяется к конкретному
защищаемому порту, когда это возможно, вместо всего IP.
## Зачем
Слепой `XDP_DROP` по IP отрезает SSH и мониторинг вместе с атакой — это известная
проблема crab-shield и типовая причина отказов от XDP-фильтров. `whitelist` уже
есть и обходит фильтры, но он не защищает от ошибки в конфиге или от бана
динамически добавленного админа.
## Scope
- Защита от самоблокировки: при старте проверять, что текущие SSH-сессии и
админские сети не попадут под blacklist/ban; предупреждать и (по флагу)
добавлять их в whitelist.
- Per-port баны в userspace и, где позволяет формат, в XDP (сейчас ключ бана —
только IP/CIDR).
- Документированная процедура восстановления, если нода всё-таки заблокирована.
## Non-goals
- Полный port-knocking.
- Замена firewall: Rampart остаётся stateless-фильтром, а не заменой nftables.
## Approach
1. Сначала — дешёвая часть: startup-проверка `ss -tnp`/`/proc/net/tcp` на активные
SSH-сессии и предупреждение, если адрес не в whitelist.
2. Per-port бан: расширить внутренний тип бана (`IpOrCidr` + `Option<u16>`),
XDP-путь — только если ABI карты допускает без удвоения памяти; иначе
оставить userspace-путь и зафиксировать это в документации.
3. Тесты: `tests/connection_limits.rs`/`tests/filter_logic.rs` + новый тест на
сериализацию ключа бана.
## Критерии приёмки
- [ ] Edge при старте пишет `WARN`, если SSH-клиент не в whitelist.
- [ ] Бан по порту не блокирует остальные порты того же IP.
- [ ] Recovery-процедура проверена в netns и описана в runbook.
- [ ] Нет изменений ABI XDP без теста в `tests/xdp_ban_keys.rs`.
## Верификация
netns-стенд: забаненный источник теряет доступ к 25565, но сохраняет SSH-порт;
runbook-процедура воспроизводится с нуля.

View file

@ -0,0 +1,60 @@
# v0.4 — Startup-диагностика окружения
| | |
|---|---|
| Milestone | v0.4 |
| Status | planned |
| Priority | P1 |
| Depends on | — |
## Цель
Edge при старте сам говорит, что с окружением: kernel, BTF, драйвер NIC,
поддержка native/generic XDP, доступные capabilities — и падает с внятной
причиной, если XDP включён, но загрузиться не сможет.
## Зачем
Диагностика уже есть в `rampart-cli doctor` (`src/xdp/probe/`, `EnvironmentReport`),
но демон её не использует. У конкурентов ~80% issues про XDP — это attach на
неподдерживаемом окружении (OpenVZ/LXC, старый kernel, отсутствие BTF), при этом
сообщение появляется уже после неудачного `load()`.
## Scope
- Переиспользовать `EnvironmentReport`/`FilesystemProbe` при старте edge, а не
писать второй детектор.
- Один структурированный лог-вердикт: `kernel`, `virt`, `interface`, `driver`,
`native|generic|none`, причина отказа.
- Fail-fast только когда `[xdp] enabled = true` и загрузка невозможна; иначе —
предупреждение и работа без XDP (текущее поведение сохраняется).
- Код возврата/сообщение для systemd: человек читает `journalctl` и понимает, что
делать, без чтения исходников.
## Non-goals
- Автоматическое лечение окружения (загрузка модулей, смена драйвера).
- Полноценный `doctor` в демоне: интерактивные проверки остаются в CLI.
## Approach
1. Вынести общий «вердикт» в `src/xdp/probe/`, чтобы CLI и демон печатали одно и
то же.
2. В `app::runtime` перед `start_xdp` логировать отчёт; при ошибке attach —
приложить вердикт к ошибке.
3. Тесты: чистая функция форматирования отчёта (без root), плюс существующие
`tests/xdp_diagnostics.rs`.
4. Документация: раздел в `docs/troubleshooting.md` и `docs/runbook.md` со
ссылкой на тот же вердикт.
## Критерии приёмки
- [ ] На kernel без BTF/в LXC лог содержит причину и рекомендацию.
- [ ] В KVM с virtio вывод честно говорит `generic (skb)`, а не «XDP works».
- [ ] `rampart-cli doctor` и edge используют один код формирования отчёта.
- [ ] `cargo clippy --all-targets --all-features -- -D warnings` чистый.
## Верификация
Прогон в двух окружениях: обычный хост и контейнер без `CAP_BPF`; вывод
сравнивается с `docs/troubleshooting.md`.

View file

@ -0,0 +1,65 @@
# v0.4 — XDP netns+veth harness в CI
| | |
|---|---|
| Milestone | v0.4 |
| Status | planned |
| Priority | P0 |
| Depends on | — |
## Цель
Каждый PR проверяет XDP-программу на реальном ядре: загрузка через verifier,
attach в netns, баны, whitelist, expiry — без ручных шагов на живой ноде.
## Зачем
Сейчас `scripts/xdp_ipv6_smoke.sh`, `xdp_pkt_test.sh` и `xdp_netns_smoke.sh`
запускаются вручную. Регрессии ловятся только на реальном сервере, а раунд
2026-11 показал, что именно там ломается (UAF при чтении map, `.rodata`-раскладка,
имена карт в загрузчике). В конкурентном анализе (вывод №7) такой харнесс
отсутствует у всех — это наше преимущество в надёжности.
## Scope
- Единая точка входа `scripts/xdp_ci.sh`: поднимает netns+veth, собирает BPF через
`build.rs`, грузит программу, гоняет фазы v4/v6/ban/whitelist/expiry/udp.
- Формат вывода и код возврата, пригодные для CI (без интерактивных шагов).
- CI-job: либо self-hosted runner с `CAP_BPF`/`CAP_NET_ADMIN`, либо hosted
`ubuntu-24.04` с `sudo` и проверкой, что kernel ≥ 5.10 и программа реально
загрузилась (не только скомпилировалась).
- Документация: как запустить локально и что делать, если в окружении нет прав.
## Non-goals
- Нагрузочный тест на 1M pps: это `deploy/test/stress/`, отдельный стенд.
- Проверка на всех драйверах: native/generic режимы достаточно проверить на veth.
## Approach
1. Обернуть существующие скрипты общим хелпером (создание netns/veth, cleanup
через trap) — сейчас логика дублируется.
2. Добавить `--ci` режим: короткие таймауты, машиночитаемые PASS/FAIL строки.
3. Job в `.github/workflows/ci.yml`; при отсутствии прав — честный `SKIP`, а не
зелёный тест.
4. Регрессионный тест на загрузчик: `tests/xdp_object_maps.rs` уже проверяет имена
карт без root, оставить его обязательным.
## Критерии приёмки
- [ ] `sudo bash scripts/xdp_ci.sh` проходит на kernel ≥ 5.10 с `bpftool`.
- [ ] CI-job падает при регрессе в `universal_filter.c`, `config.h`, `maps.h`.
- [ ] Нет root-прав — job выдаёт `SKIP` с причиной, а не ложный успех.
- [ ] README/testing.md и docs/testing.md описывают один и тот же путь запуска.
## Верификация
`sudo bash scripts/xdp_ci.sh` на dev-машине + прогон job в PR с намеренно
сломанным заголовком `config.h` (должен упасть).
## Риски
- GitHub-hosted runner может не дать `CAP_BPF`; тогда нужен self-hosted runner.
Решение принимается на этапе дизайна, до реализации.
- veth не воспроизводит offload-поведение реального NIC; паддинг и VLAN
покрываются `xdp_pkt_test.sh` отдельно.

View file

@ -0,0 +1,47 @@
# v0.5 — GeoIP/ASN reputation
| | |
|---|---|
| Milestone | v0.5 |
| Status | idea |
| Priority | P1 |
| Depends on | — |
## Цель
Фильтрация и репутация по стране/ASN: блокировка нежелательных регионов,
понижение репутации хостинговых ASN, белый список «домашних» сетей.
## Зачем
Feature-флаг `geoip` и `maxminddb` в зависимостях есть, но реализации нет —
«мёртвый код = баг» по правилам проекта. Для VDS-ниши страна/ASN — базовый
фильтр, который конкуренты либо не дают, либо дают только в платной версии.
## Scope
- Загрузка MaxMind MMDB (страна, ASN) при старте; hot-reload файла по SIGHUP или
таймеру.
- Конфиг: список разрешённых/запрещённых стран и ASN, режим (`drop`/`challenge`).
- Метрики: вердикты по странам/ASN, ошибки чтения базы.
- XDP-путь не трогаем: GeoIP — userspace-фильтр на этапе `Gateway`.
## Non-goals
- Собственная GeoIP-база.
- Блокировка по городу/координатам.
## Approach
1. Абстракция `GeoLookup` (trait) + реализация на `maxminddb`, чтобы тесты не
требовали бинарной базы.
2. Интеграция в `Gateway::handle_client` после blacklist, до PoW.
3. Fail-fast: `geoip` включён, база не читается → отказ старта с понятной ошибкой.
4. Тесты: фикстура MMDB в `tests/fixtures/` (маленькая, с явной лицензией).
## Критерии приёмки
- [ ] Конфиг валидируется: неизвестная страна/ASN — ошибка, а не тихий пропуск.
- [ ] Нет базы — фича выключена, edge работает.
- [ ] Метрики покрыты тестами; docs/configuration.md обновлён.
- [ ] Лицензия базы и ограничения описаны в документации.

View file

@ -0,0 +1,45 @@
# v0.5 — gRPC protocol plugin
| | |
|---|---|
| Milestone | v0.5 |
| Status | idea |
| Priority | P2 |
| Depends on | стабильный `ProtocolHandler` API |
## Цель
Плагин, который понимает gRPC поверх HTTP/2: валидирует префикс запроса, умеет
отклонять мусор до upstream, поддерживает multiplexing без потери соединений.
## Зачем
После HTTP/1.1 логичный следующий протокол: gRPC — стандарт для внутренних API, а
его handshake (HTTP/2 preface + SETTINGS) дешёво проверяется в userspace. Даёт
кейс «защитить внутренний сервис», а не только публичный сайт.
## Scope
- Разбор HTTP/2 preface и первых фреймов (SETTINGS/HEADERS) с лимитами.
- Решение Allow/Reject и туннелирование на upstream без буферизации всего потока.
- Конфиг `[protocol.grpc]`: лимиты заголовков, таймауты, разрешённые пути.
- Тесты на фрагментацию (парсер обязан переживать «один read»).
## Non-goals
- Полноценный HTTP/2-прокси с приоритетами и flow control.
- gRPC-рефлексия и десериализация сообщений.
## Approach
1. Переиспользовать HTTP/1.1-парсер там, где применимо; HTTP/2 preface —
отдельная маленькая стейт-машина.
2. Новый feature `protocol-grpc`, регистрация в `ProtocolRegistry`.
3. Fuzz-цель `http2_preface` рядом с существующими.
4. Документация: `docs/configuration.md` + отдельный пример конфига.
## Критерии приёмки
- [ ] `--features protocol-grpc` собирается и покрыт тестами в CI.
- [ ] Парсер не выходит за буфер на произвольных байтах (fuzz 60 с в `make fuzz`).
- [ ] Нет регрессии латентности HTTP/1.1-пути (bench hot_paths).

View file

@ -0,0 +1,53 @@
# v0.5 — Pinned maps и OpenAPI
| | |
|---|---|
| Milestone | v0.5 |
| Status | idea |
| Priority | P1 |
| Depends on | — |
## Цель
Динамические списки и состояние XDP доступны снаружи без перекомпиляции и без
прямого доступа к памяти: pinned maps через bpffs + описанный OpenAPI контракт
manager API.
## Зачем
Самый частый запрос у XDP-фаерволов — управлять списками на лету; у gamemann это
issues #79/#77/#78, web-панель так и не сделана. Наш manager API уже умеет
blacklist, но контракт не описан машинно, а XDP-карты не pin-ятся.
## Scope
- `bpftool`-совместимые pinned maps (blacklist, whitelist, stats) с фиксированными
именами и документированной раскладкой ключей.
- OpenAPI 3.1 spec для существующих маршрутов (`/health`, `/auth/login`,
`/servers`, `/blacklist`, `/nodes`), генерация из одного источника или
ручной файл + тест соответствия роутеру.
- Swagger UI — опционально, отдельным бинарём/фичей, не в основном edge.
## Non-goals
- Web-панель (UI) — отдельный продукт.
- Изменение ABI существующих карт без теста совместимости.
## Approach
1. Выбрать: pin-ить карты в загрузчике (`libbpf-rs` pin path) или отдельной
утилитой. Проверить, что pin не мешает перезапуску/cleanup.
2. OpenAPI: начать с ручного `docs/openapi.yaml`, добавить тест, что каждый
маршрут из `router.rs` присутствует в спецификации.
3. Документация: как читать/писать карты, какие значения, какие ограничения.
## Критерии приёмки
- [ ] `bpftool map show pin` видит карты после старта edge.
- [ ] OpenAPI валидируется в CI и покрывает 100% маршрутов.
- [ ] README/api.md ссылаются на спецификацию, а не дублируют её.
## Риски
Pinned maps усложняют graceful detach и могут оставить «висящие» карты после
краша — нужен reaper и тест.

View file

@ -0,0 +1,58 @@
# v0.5 — RST-challenge: довести до GA
| | |
|---|---|
| Milestone | v0.5 |
| Status | planned |
| Priority | P0 |
| Depends on | v0.4-xdp-ci-harness (регрессии на реальном ядре) |
## Цель
RST-challenge (Oubliette-style liveness proof) работает для IPv4 и IPv6, включён
документированным способом и заменяет текстовый PoW там, где PoW несовместим с
протоколом.
## Зачем
В коде уже есть `xdp/core/syn_challenge.h` и `[xdp] syn_challenge_enabled`
(IPv4, SYN-ACK с неверным ACK → RST от живого клиента → verified). Это
универсальная проверка liveness, совместимая с любым TCP-клиентом, в отличие от
userspace PoW, который ломает протоколы с собственным handshake (Minecraft).
Осталось довести до продакшена и убрать расхождение «фича есть в C, но не в
документации/дефолтах».
## Scope
- IPv6-паритет: 128-битные flow-ключи для pending-challenge и verified-состояния.
- Метрики: выданные challenge, прошедшие/просроченные, доля verified-источников.
- Заменить/дополнить PoW: описать матрицу «протокол → PoW / RST-challenge / оба»,
обновить `[pow]` и `[xdp]` в configuration.md.
- Интеграционные тесты: живой клиент проходит, спуф не проходит; TTL challenge.
- Docs: отдельный раздел про challenge в architecture.md и runbook.
## Non-goals
- RST-challenge для UDP.
- Хранение verified-состояния в Redis между нодами (сейчас локально в XDP).
## Approach
1. Аудит текущего C-кода и ABI: ключи, таймауты, взаимодействие с conntrack.
2. v6: расширить `flow_key` или добавить `flow_key6`; проверить размер карт.
3. Userspace: метрики и переключатель; логировать причину отказа без секретов.
4. Тесты: `tests/xdp_ban_keys.rs` рядом, `scripts/xdp_ci.sh` из v0.4.
5. Документация и дефолты: решение «включать по умолчанию» принимается только
после нагрузочного стенда.
## Критерии приёмки
- [ ] IPv4 и IPv6: живой клиент проходит после одного RST, спуф — нет.
- [ ] Метрики challenge видны в `/metrics` и описаны в docs.
- [ ] Нет дефолтного секрета: placeholder отклоняется при старте (уже есть).
- [ ] PoW и RST-challenge не включаются одновременно для Minecraft.
## Верификация
`scripts/xdp_ci.sh` + e2e-тест в `tests/edge_e2e.rs`; ручная проверка `tcpdump`
на dev-ноде.

View file

@ -0,0 +1,37 @@
# v0.6 — BGP Anycast
| | |
|---|---|
| Milestone | v0.6 |
| Status | idea |
| Priority | P3 |
| Depends on | несколько edge-площадок |
## Цель
Анонс защищаемого префикса (`/24` + AS) с нескольких edge-площадок, чтобы
атакующий трафик распределялся, а клиент попадал на ближайшую ноду.
## Зачем
Это инфраструктурный уровень защиты, который сейчас закрывают только провайдеры.
Для одиночного VDS не нужен, но без него нельзя называться «платформой».
## Non-goals
- Собственная BGP-реализация с нуля: используем зрелый демон (BIRD/FRR) и
управляем им.
- Автоматический анонс при атаке без оператора.
## Approach
1. Исследовать: BIRD/FRR + health-check, при котором withdraw происходит при
деградации ноды.
2. Написать интеграцию (генерация конфига, health-скрипт), а не демон.
3. Лабораторный стенд: два netns с BGP-сессией, проверка withdraw/failover.
## Критерии приёмки
- [ ] Failover проверен в лаборатории, время withdraw задокументировано.
- [ ] Конфиг генерируется из одного источника (manager inventory).
- [ ] Есть runbook на случай анонса «плохого» префикса.

View file

@ -0,0 +1,39 @@
# v0.6 — Bloom filter для blacklist
| | |
|---|---|
| Milestone | v0.6 |
| Status | idea |
| Priority | P3 |
| Depends on | — |
## Цель
Дешёвая предварительная проверка «адреса точно нет в blacklist», чтобы не
трогать LPM-трию и не брать лок на каждый пакет.
## Зачем
Blacklist lookup в XDP уже LPM, но при росте списка до сотен тысяч записей
память и стоимость lookup растут. Bloom-фильтр даёт negative lookup за один
memory access.
## Non-goals
- Точная проверка без false positive: Bloom только отсеивает, финальное слово за
картой blacklist.
- Замена существующих карт: фильтр — дополнение.
## Approach
1. Сначала измерить: при каких размерах списка LPM lookup становится узким местом
(bench + `bpftool map show`).
2. Если выигрыш есть — Bloom в отдельной карте, обновление при ban/unban,
периодическая пересборка из источника правды.
3. Тесты: false-negative == 0, память в лимитах, поведение при переполнении.
## Критерии приёмки
- [ ] Бенчмарк до/после на списке ≥ 100k.
- [ ] Ноль false negative на property-тестах.
- [ ] Деградация при переполнении описана и безопасна (fail-open к точной карте).

View file

@ -0,0 +1,46 @@
# v0.6 — HTTP поверх XDP (BPF hook)
| | |
|---|---|
| Milestone | v0.6 |
| Status | idea |
| Priority | P1 |
| Depends on | v0.4-xdp-ci-harness, v0.5-rst-challenge-ga |
## Цель
Первый реальный BPF-протокол-хук: разбор начала HTTP-запроса в XDP и rate-limit
по L7-признакам до того, как соединение дойдёт до userspace.
## Зачем
Сейчас `xdp/hooks/hook_api.h` — контракт без потребителя, а HTTP-фильтрация
происходит только в userspace: под флудом соединений CPU тратится на accept и
чтение заголовков. Хук в ядре снимет основную часть нагрузки на дорогие атаки.
## Scope
- Ограниченный парсер: метод, путь, Host, User-Agent — с жёсткими лимитами.
- Tail-call цепочка из основной программы в hook (без роста сложности
`universal_filter.c`).
- Политика: drop/rate-limit по пути и User-Agent; конфиг в `.rodata`.
- Тесты в netns-стенде + fuzz-цель на тех же байтах, что и userspace-парсер.
## Non-goals
- Полный HTTP-парсер в BPF (TLS, body, chunked).
- Замена userspace HTTP-плагина: хук — быстрый предфильтр, финальное решение
остаётся за `ProtocolHandler`.
## Approach
1. Прототип отдельной BPF-программы с `test_run` на сохранённых пакетах.
2. Сравнить pps/CPU с текущим userspace-путём на `deploy/test/stress/`.
3. Только при выигрыше — интегрировать в загрузчик и конфиг.
## Критерии приёмки
- [ ] Хук не меняет вердикты userspace-фильтра (property-тесты на одних байтах).
- [ ] Бенчмарк показывает измеримый выигрыш на HTTP-flood.
- [ ] Верификатор проходит на kernel ≥ 5.10, размер программы в лимитах.
- [ ] Фича выключена по умолчанию и не ломает сборку без неё.

View file

@ -0,0 +1,37 @@
# v0.6 — io_uring runtime
| | |
|---|---|
| Milestone | v0.6 |
| Status | idea |
| Priority | P3 |
| Depends on | бенчмарк relay-пути |
## Цель
Опциональный io_uring-транспорт для relay: меньше syscall и копий на горячем
пути пересылки.
## Зачем
Фича `io-uring` и зависимость `tokio-splice` объявлены, но не используются. На
relay-пути доминируют `read`/`write` и копии; `splice`/io_uring могут снизить CPU
на высоких pps.
## Non-goals
- Замена tokio целиком: только транспорт relay-соединений.
- Требование io_uring для работы edge: feature опционален, дефолт — текущий путь.
## Approach
1. Замерить текущий relay: `perf`/`samply` на нагрузочном стенде, найти долю
syscall.
2. Прототип `RelayTransport` на `tokio-splice`, сравнить на 1/10/100k соединений.
3. Оставить фичу только если выигрыш воспроизводим и код не разрастается.
## Критерии приёмки
- [ ] Замеры до/после с методологией в `docs/research/benchmark.md`.
- [ ] `--features io-uring` собирается и тестируется в CI.
- [ ] Поведение при недоступном io_uring — прозрачный fallback.

View file

@ -0,0 +1,39 @@
# v0.6 — ML anomaly detection
| | |
|---|---|
| Milestone | v0.6 |
| Status | idea |
| Priority | P3 |
| Depends on | собранный датасет атак |
## Цель
Детектор аномалий (Isolation Forest или проще) поверх текущих сигналов EWMA,
репутации и prefix-статистики: ловить медленные, «человеческие» атаки, которые
пороговые правила пропускают.
## Зачем
Пороги легко обходятся медленным ramp-up. Но ML без данных — гадание, поэтому
задача стоит после того, как накопим воспроизводимые датасеты с нагрузочного
стенда.
## Non-goals
- Онлайн-обучение в проде.
- Замена детерминированных порогов: ML — дополнительный сигнал, не единственный.
## Approach
1. Собрать датасеты: нормальная нагрузка + 3–5 типов атак из `deploy/test/stress/`.
2. Офлайн-прототип на Python, метрики precision/recall, сравнение с текущим
`AttackDetector`.
3. Если выигрыш доказан — перенос в Rust с фиксированной моделью и
детерминированным инференсом.
## Критерии приёмки
- [ ] Датасет и методология опубликованы в `docs/research/`.
- [ ] Ложноположительные на нормальной нагрузке ≤ текущего детектора.
- [ ] Инференс не добавляет аллокаций в hot path (замер).

View file

@ -10,7 +10,7 @@
# ── ШАГ 1: Подтвердить атаку ──
# Метрики edge ноды
curl -s http://EDGE_IP:9090/metrics | grep -E "rampart_(connections|rate_limit|attack_status)"
curl -s http://EDGE_IP:9090/metrics | grep -E "rampart_(connections_total|rate_limit_hits|attack_status)"
# rampart_attack_status: 0 = normal, 1 = suspicious, 2 = under_attack
# (детектор по порогу pps, см. src/traffic/intel/detector.rs)
@ -50,7 +50,7 @@ iptables -A INPUT -p tcp --dport 25565 -j DROP
# ── ШАГ 5: После атаки ──
# События атак пишутся в ClickHouse (если настроен clickhouse_url):
clickhouse-client --query "SELECT count() FROM rampart.events WHERE event_type='attack'"
clickhouse-client --query "SELECT count() FROM rampart_events WHERE event_type='attack'"
# Написать post-mortem
```
@ -66,9 +66,9 @@ clickhouse-client --query "SELECT count() FROM rampart.events WHERE event_type='
| Метрика / лог | Что значит | Что делать |
|---------------|-----------|------------|
| `rampart_connections_total{result="overloaded"}` | исчерпан глобальный бюджет соединений (4×workers×max_connections_per_ip) | проверить, не атака ли; при легитимной нагрузке — поднять `max_connections_per_ip`/`workers.count` |
| `rampart_xdp_dropped_total` растёт, `passed_total` — нет | XDP дропает всё | проверить `protected_port_start/end`, баны и `xdp_feature_*`; смотреть `stats_map` через `bpftool` |
| `rampart_xdp_dropped` растёт, `rampart_xdp_passed` — нет | XDP дропает всё | проверить `protected_port_start/end`, баны и счётчики `stats_map` (список — [architecture.md](architecture.md) §6); смотреть через `bpftool` |
| `rampart_clickhouse_dropped_total` > 0 | события не успевают уходить в ClickHouse | проверить доступность/латентность ClickHouse; события потеряны, защита работает |
| `rampart_xdp_whitelist_total` растёт | трафик от whitelist-адресов | норма, но если это неожиданно — проверить `whitelist` в конфиге |
| `rampart_xdp_whitelist` растёт | трафик от whitelist-адресов | норма, но если это неожиданно — проверить `whitelist` в конфиге |
| лог `global connection budget exhausted` | то же, что `overloaded` | см. выше |
| лог `accept error ... backing off` | кончились fd (`EMFILE`) или память под сокеты | поднять `ulimit -n`, проверить утечки соединений |
| лог `XDP filter attached ... (mode: generic (skb))` | драйвер не умеет native XDP | ожидаемо для virtio/veth; generic дороже по CPU |
@ -86,7 +86,7 @@ ip link show eth0 | grep xdp # пусто
> Команды `emergency`, `drain` и `config set` пока не реализованы и завершатся
> явной ошибкой вместо изменения состояния.
## 2. Edge нода не стартует
## 3. Edge нода не стартует
```bash
systemctl status rampart
@ -112,7 +112,7 @@ journalctl -u rampart | grep -i xdp
# Временное решение: [xdp] enabled = false в config.toml
```
## 3. XDP не загружается
## 4. XDP не загружается
```bash
systemd-detect-virt # openvz/lxc → XDP не работает, нужен KVM
@ -120,13 +120,14 @@ uname -r # нужно 5.10+
ethtool -i eth0 | grep driver
# Проверить компиляцию BPF-программы:
clang -O2 -g -target bpf -c xdp/core/universal_filter.c -o /tmp/universal_filter.o
clang -O2 -g -target bpf -I"/usr/include/$(gcc -print-multiarch)" \
-c xdp/core/universal_filter.c -o /tmp/universal_filter.o
# Отключить XDP:
# [xdp] enabled = false → systemctl restart rampart
```
## 4. Клиенты не могут подключиться
## 5. Клиенты не могут подключиться
```bash
curl -s http://EDGE_IP:9090/metrics | grep rampart_connections
@ -138,7 +139,7 @@ dig +short your.domain # DNS указывает на edge?
# NAT: много клиентов за одним IP упираются в max_connections_per_ip — увеличь.
```
## 5. Высокая нагрузка на edge
## 6. Высокая нагрузка на edge
```bash
htop -p $(pgrep -d',' rampart)
@ -149,15 +150,15 @@ iftop -i eth0 # pps/bandwidth
# чтобы дропать мусор раньше, и ужесточи rate limit.
```
## 6. ClickHouse переполнен
## 7. ClickHouse переполнен
```bash
df -h /var/lib/clickhouse
clickhouse-client --query "ALTER TABLE rampart.events MODIFY TTL ts + INTERVAL 90 DAY"
clickhouse-client --query "ALTER TABLE rampart_events MODIFY TTL timestamp + INTERVAL 90 DAY"
# Временное отключение записи: закомментируй clickhouse_url в config.toml, рестарт.
```
## 7. Краткий справочник команд
## 8. Краткий справочник команд
```bash
rampart-cli status # Общее состояние системы
@ -171,4 +172,4 @@ rampart-cli blacklist list
---
*Версия: 2.0 | Август 2026*
*Версия: 3.0 | Ноябрь 2026*

View file

@ -12,14 +12,20 @@ cargo test --test config_parse
cargo test -- --nocapture # с выводом
```
Существующие наборы (tests/):
Существующие наборы (39 файлов в `tests/`):
| Тест | Что покрывает |
|------|---------------|
| `config_parse` | Парсинг и валидация единого конфига (src/config) |
| `filter_logic` | Blacklist, rate limit, geo-фильтры |
| `pow_roundtrip` | Выдача/решение/проверка PoW challenge |
| `protocol_registry` | Реестр протокольных плагинов |
| Группа | Тесты |
|--------|-------|
| Конфиг и запуск | `config_parse`, `app_shutdown` |
| Фильтры и лимиты | `filter_logic`, `connection_limits`, `proxy_identity` |
| Протоколы | `protocol_registry`, `protocol_registry_contract`, `http_protocol`, `protocol_http_parser`, `protocol_http_handler`, `proxy_v2_parser` |
| PoW и challenge | `pow_roundtrip`, `pow_difficulty` |
| Детекция | `subnet_detection`, `traffic_hook`, `traffic_intel`, `traffic_prefix_stats`, `traffic_profile_alert`, `traffic_profile_profiler` |
| Manager API | `manager_api`, `manager_auth`, `manager_heartbeat`, `manager_security` |
| Хранилища | `redis_backoff`, `clickhouse_writer` |
| TUI | `tui_metrics`, `tui_prometheus` |
| XDP | `xdp_attach_smoke`, `xdp_ban_clock`, `xdp_ban_keys`, `xdp_ban_v6`, `xdp_diagnostics`, `xdp_events`, `xdp_globals`, `xdp_loader`, `xdp_object_maps`, `xdp_services`, `xdp_whitelist_keys` |
| End-to-end | `edge_e2e` |
---
@ -42,7 +48,9 @@ cargo test --all-features --test edge_e2e
XDP: smoke-check компиляции BPF-программы:
```bash
clang -O2 -g -target bpf -c xdp/core/universal_filter.c -o /tmp/universal_filter.o
mkdir -p target/xdp
clang -O2 -g -target bpf -I"/usr/include/$(gcc -print-multiarch)" \
-c xdp/core/universal_filter.c -o target/xdp/universal_filter.o
```
Функциональные проверки на реальном ядре (нужен root: CAP_BPF + CAP_NET_ADMIN,
@ -68,6 +76,10 @@ TCP-payload по `ip->tot_len`), VLAN/QinQ-теги и фрагменты — з
`scripts/xdp_netns_smoke.sh` дополнительно гоняет реальный бинарь `rampart` end-to-end
(требует `hping3`).
Единая точка входа для CI появится в v0.4 (`scripts/xdp_ci.sh`, см.
[roadmap/v0.4-xdp-ci-harness.md](roadmap/v0.4-xdp-ci-harness.md)); до этого
скрипты выше запускаются вручную.
---
## 3. Fuzzing
@ -110,16 +122,22 @@ cargo bench --all-features --bench hot_paths
Замеряются: `RateLimiter::check`, exact/CIDR/miss lookup в `Blacklist`, `SubnetDetector::evaluate`
на окне из 256 префиксов и разбор HTTP request-head. Сравнивай медианы до/после изменения на
одной машине; абсолютные числа зависят от CPU. Порядок величин на dev-машине (2 vCPU):
одной машине; абсолютные числа зависят от CPU. Порядок величин на dev-машине (2 vCPU,
релизный профиль с `lto = "thin"`):
| Бенчмарк | Медиана |
|----------|---------|
| `rate_limiter/check` | ~110 ns |
| `blacklist/is_blocked_exact` | ~70 ns |
| `blacklist/is_blocked_cidr` | ~220 ns |
| `subnet_detector/evaluate_256` | ~2.6 µs |
| `rate_limiter/check` | ~120 ns |
| `blacklist/is_blocked_exact` | ~80 ns |
| `blacklist/is_blocked_cidr` | ~230 ns |
| `blacklist/is_blocked_miss` | ~230 ns |
| `subnet_detector/evaluate_256` | ~2.8 µs |
| `http_parser/evaluate` | ~280 ns |
Для сравнения с сохранённым прогоном: `cargo bench --all-features --bench hot_paths --
--save-baseline before` до изменения, затем `--baseline before` после; criterion покажет
дельту и её значимость.
---
## 5. Локальный integration-стенд (Docker)
@ -173,4 +191,4 @@ curl -s http://localhost:9090/metrics | grep rampart_
---
*Версия: 2.0 | Август 2026*
*Версия: 3.0 | Ноябрь 2026*

View file

@ -14,7 +14,8 @@ dpkg -l | grep libbpf # libbpf-dev нужен при сборке
journalctl -u rampart | grep -i "xdp\|ebpf\|bpf"
# Проверить компиляцию BPF-программы вручную:
clang -O2 -g -target bpf -c xdp/core/universal_filter.c -o /tmp/uf.o
clang -O2 -g -target bpf -I"/usr/include/$(gcc -print-multiarch)" \
-c xdp/core/universal_filter.c -o /tmp/uf.o
# Не помогло — отключи XDP в config.toml ([xdp] enabled = false) и рестарт.
```
@ -166,4 +167,4 @@ rampart-cli status # краткий статус
---
*Версия: 2.0 | Август 2026*
*Версия: 3.0 | Ноябрь 2026*

View file

@ -1,7 +1,7 @@
# VDS Compatibility - Rampart
> Совместимость VDS провайдеров с XDP/eBPF.
> Обновляется: Август 2026
> Обновляется: Ноябрь 2026
---
@ -34,8 +34,10 @@ ethtool -i eth0 | grep driver
# 3. Версия ядра (нужно 5.10+)
uname -r
# 4. XDP доступность
sudo ip link set dev eth0 xdp off 2>&1 || echo "XDP не поддерживается"
# 4. Диагностика окружения (XDP, BTF, драйвер, режим attach)
rampart-cli doctor
# Строка про XDP: native (drv) — лучший режим, generic (skb) — работает, но дороже.
# Если XDP недоступен совсем — используй userspace-фильтр (XDP опционален).
```
---
@ -69,4 +71,4 @@ sudo ip link set dev eth0 xdp off 2>&1 || echo "XDP не поддерживае
---
*Версия: 2.0 | Август 2026*
*Версия: 3.0 | Ноябрь 2026*