- 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.
212 lines
12 KiB
Markdown
212 lines
12 KiB
Markdown
# 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*
|