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

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*