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:
parent
1b3ae5e546
commit
280284667f
38 changed files with 1582 additions and 623 deletions
|
|
@ -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*
|
||||
|
|
|
|||
10
docs/api.md
10
docs/api.md
|
|
@ -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
212
docs/architecture.md
Normal 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*
|
||||
|
|
@ -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*
|
||||
|
|
|
|||
|
|
@ -145,4 +145,4 @@ redis_url = "redis://:PASSWORD@redis:6379/0"
|
|||
|
||||
---
|
||||
|
||||
*Версия: 2.1 | Октябрь 2026*
|
||||
*Версия: 3.0 | Ноябрь 2026*
|
||||
|
|
|
|||
116
docs/development.md
Normal file
116
docs/development.md
Normal 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*
|
||||
|
|
@ -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*
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
79
docs/roadmap/README.md
Normal 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*
|
||||
32
docs/roadmap/icebox-minecraft-velocity.md
Normal file
32
docs/roadmap/icebox-minecraft-velocity.md
Normal 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
|
||||
задач.
|
||||
56
docs/roadmap/v0.4-anti-lockout.md
Normal file
56
docs/roadmap/v0.4-anti-lockout.md
Normal 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-процедура воспроизводится с нуля.
|
||||
60
docs/roadmap/v0.4-startup-diagnostics.md
Normal file
60
docs/roadmap/v0.4-startup-diagnostics.md
Normal 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`.
|
||||
65
docs/roadmap/v0.4-xdp-ci-harness.md
Normal file
65
docs/roadmap/v0.4-xdp-ci-harness.md
Normal 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` отдельно.
|
||||
47
docs/roadmap/v0.5-geoip-asn.md
Normal file
47
docs/roadmap/v0.5-geoip-asn.md
Normal 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 обновлён.
|
||||
- [ ] Лицензия базы и ограничения описаны в документации.
|
||||
45
docs/roadmap/v0.5-grpc-plugin.md
Normal file
45
docs/roadmap/v0.5-grpc-plugin.md
Normal 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).
|
||||
53
docs/roadmap/v0.5-pinned-maps-openapi.md
Normal file
53
docs/roadmap/v0.5-pinned-maps-openapi.md
Normal 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 и тест.
|
||||
58
docs/roadmap/v0.5-rst-challenge-ga.md
Normal file
58
docs/roadmap/v0.5-rst-challenge-ga.md
Normal 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-ноде.
|
||||
37
docs/roadmap/v0.6-bgp-anycast.md
Normal file
37
docs/roadmap/v0.6-bgp-anycast.md
Normal 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 на случай анонса «плохого» префикса.
|
||||
39
docs/roadmap/v0.6-bloom-filter.md
Normal file
39
docs/roadmap/v0.6-bloom-filter.md
Normal 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 к точной карте).
|
||||
46
docs/roadmap/v0.6-http-over-xdp.md
Normal file
46
docs/roadmap/v0.6-http-over-xdp.md
Normal 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, размер программы в лимитах.
|
||||
- [ ] Фича выключена по умолчанию и не ломает сборку без неё.
|
||||
37
docs/roadmap/v0.6-io-uring.md
Normal file
37
docs/roadmap/v0.6-io-uring.md
Normal 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.
|
||||
39
docs/roadmap/v0.6-ml-anomaly.md
Normal file
39
docs/roadmap/v0.6-ml-anomaly.md
Normal 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 (замер).
|
||||
|
|
@ -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*
|
||||
|
|
|
|||
|
|
@ -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*
|
||||
|
|
|
|||
|
|
@ -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*
|
||||
|
|
|
|||
|
|
@ -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*
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue