diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index fca20d4..400ee5d 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -70,6 +70,8 @@ jobs: run: bash scripts/check_module_size.sh - name: Default secrets gate run: bash scripts/check_default_secrets.sh + - name: Documentation links gate + run: bash scripts/check_docs_links.sh rust-deny: name: Rust — cargo-deny diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..a20f035 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,100 @@ +# Changelog + +Все значимые изменения проекта. Формат — [Keep a Changelog](https://keepachangelog.com/ru/1.1.0/), +версии — [Semantic Versioning](https://semver.org/lang/ru/). + +--- + +## [Unreleased] + +### Added + +- `docs/architecture.md` — текущее устройство системы (процессы, путь трафика, + слои, хранилища, метрики). +- `docs/development.md` — принципы, лимиты, гейты, Definition of Done. +- `docs/roadmap/` — по одному файлу на задачу; `TODO.md` стал тонким индексом. +- `CHANGELOG.md` — этот файл. + +### Changed + +- `[profile.release]`: `lto = "thin"`, `codegen-units = 1`. Релизный бинарь с + `protocol-http` уменьшился с 12.3 МБ до 9.7 МБ (−21%); `http_parser/evaluate` + в criterion — 314 нс → 278 нс (−12%), остальные бенчмарки в пределах шума. +- CI: экшены обновлены до node24-версий, раннер закреплён на `ubuntu-24.04`. + +### Fixed + +- Docker edge image: в сборку добавлен `benches/`, без него Cargo не парсил + манифест и образ не собирался (exit 101). +- `rampart-cli status` подсказывал неверный бинарь (`rampart doctor` вместо + `rampart-cli doctor`). +- Документация приведена в соответствие с кодом: дефолты `[xdp]`/`[detect]`, + имена метрик XDP, таблица ClickHouse (`rampart_events`), восстановление Redis + из RDB, путь к схеме конфига, команда сборки BPF с multiarch-инклюдом. + +### Removed + +- Неиспользуемое поле `role` в JWT claims (RBAC не реализован; вернуть вместе с + реальными ролями). + +--- + +## [0.3.0-dev] — 2026-11-16 + +Big-bang редизайн: из Minecraft-специфичной защиты в универсальную L3/L4/L7 +платформу. + +### Added + +- Единый пакет `rampart` с бинарями `rampart`, `rampart-manager`, `rampart-cli`, + `rampart-tui`; Java-плагины и dashboard удалены. +- Протокол-плагины: `protocol-http` (HTTP/1.1 request-head) и + `protocol-minecraft` (handshake/list/login, один upstream, PROXY v2). +- XDP: universal-фильтр для IPv4/IPv6, LPM blacklist/whitelist, SYN-throttle, + UDP policy (pass/drop/rate-limit), prefix-статистика, RST-challenge, + ringbuf-события и opt-in auto-ban. +- Subnet-level detection: prefix-статистика `/24` и `/64`, оценка числа + источников по bitmap, лестница вердиктов strict → challenge → block. +- Traffic Intel в горячем пути: EWMA-детектор, репутация, авто-баны, webhook + алерты на переход состояния. +- Manager API: pagination/`SCAN` вместо `KEYS`, rate-limit мутаций, body limit + и таймауты, graceful shutdown, backfill метаданных blacklist, `X-Forwarded-For` + только от `MANAGER_TRUSTED_PROXIES`. +- PROXY protocol v2 на входе: строгая валидация адреса, доверенные CIDR, + запрет бана доверенных сетей. +- TUI-дашборд live-метрик; Prometheus `/metrics`. +- Инфраструктура: fuzz-цели `http_head` и `proxy_v2`, criterion-бенчмарки + горячего пути, e2e-тест edge на loopback, netns-скрипты XDP. + +### Changed + +- IPv6-паритет XDP: blacklist, UDP rate-limit, prefix-статистика, whitelist. +- Expiry банов переведён на монотонные часы; просроченные префиксные баны + удаляет userspace-reaper. +- Тесты вынесены из `src/` в `tests/` (правило «тесты отдельно от кода»). + +### Fixed + +- XDP: длина TCP-payload по `ip->tot_len` (Ethernet-паддинг), VLAN/QinQ до L3, + фрагменты по blacklist, чтение map до `bpf_map_delete_elem` (UAF), `.rodata` + раскладка и имена карт в загрузчике. +- Data path: backoff на `accept()`, корректный shutdown, глобальный бюджет, + rate-limit до PoW, таймауты connect/handshake/relay. +- Blacklist: CIDR-баны диапазонами, нормализация IPv4-mapped, TOCTOU, + атомарный `replace_redis`. +- Manager: auth bypass, утечки и зависания, найденные ревью. + +### Security + +- `API_PASSWORD` ≥ 16 символов и не `changeme`; `JWT_SECRET` ≥ 32 непробельных + байт; audience-валидация. +- `syn_challenge_enabled` требует собственный секрет, placeholder отклоняется. +- Compose без публичных Redis/ClickHouse и без дефолтных паролей; пустой + `CORS_ORIGIN` → cross-origin запрещён. + +--- + +## [0.2.0] — 2026-07-20 + +- Первый публичный релиз: 6-слойный Minecraft-стек (XDP → PoW → Rust core → + Velocity → Paper agent → Traffic Intel), Java-плагины и dashboard. diff --git a/Cargo.toml b/Cargo.toml index fffefa1..e177b55 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -37,8 +37,8 @@ store-redis = ["dep:redis"] geoip = ["dep:maxminddb"] xdp = ["dep:libbpf-rs", "dep:libc"] io-uring = ["dep:tokio-splice"] -# HTTP/1.1 protocol handler: парсинг request-head, verdict Allow/Reject, -# туннелирование на upstream (см. src/protocol/http/ и [protocol.http] в конфиге). +# HTTP/1.1 protocol handler: request-head parsing, Allow/Reject verdict, +# upstream tunnelling (see src/protocol/http/ and [protocol.http] in the config). protocol-http = [] protocol-minecraft = [] @@ -87,3 +87,12 @@ criterion = { version = "0.5", features = ["html_reports"] } name = "hot_paths" harness = false required-features = ["protocol-http"] + +[profile.release] +# Thin LTO plus one codegen unit: the edge data path is latency-sensitive, and +# cross-crate inlining is worth the extra build time. +lto = "thin" +codegen-units = 1 +# `panic = "abort"` is deliberately NOT set: `store/redis/sync.rs` relies on +# `catch_unwind` to isolate a malformed pub/sub message, and a panic in one +# tokio task must not take down the whole edge node. diff --git a/README.md b/README.md index 6ee69fe..68c41b2 100644 --- a/README.md +++ b/README.md @@ -147,30 +147,35 @@ Rampart не спасёт уже забитый домашний канал: п | Маскированный flood с 100 IP (5 pps/IP) | **99.6% заблокировано**, легитимные клиенты работают | | SYN flood без XDP | обрабатывается ядром | -Полный набор бенчмарков — в работе. +Полный набор микробенчмарков горячего пути (criterion) — `cargo bench --all-features +--bench hot_paths`; медианы и методология — [docs/testing.md](docs/testing.md) §4. ### Документация | Раздел | Где | |--------|-----| | Индекс всей документации | [docs/README.md](docs/README.md) | +| Архитектура системы | [docs/architecture.md](docs/architecture.md) | | Деплой | [docs/deployment.md](docs/deployment.md) | | Конфигурация | [docs/configuration.md](docs/configuration.md) | | Эксплуатация (runbook) | [docs/runbook.md](docs/runbook.md) | | Диагностика | [docs/troubleshooting.md](docs/troubleshooting.md) | | Тестирование | [docs/testing.md](docs/testing.md) | | API manager'а | [docs/api.md](docs/api.md) | +| Roadmap и планы задач | [docs/roadmap/](docs/roadmap/README.md) | +| История изменений | [CHANGELOG.md](CHANGELOG.md) | | База знаний (атаки, защита, практика) | [docs/kb/](docs/kb/) | | Research: архитектура, eBPF, DDoS | [docs/research/](docs/research/) | ### Разработка -- Правила кода и Definition of Done — [TODO.md](TODO.md) (§0). -- Комментарии в коде — только по-английски, JavaDoc/Rustdoc-стиль (§0.8). +- Правила кода, гейты и Definition of Done — [docs/development.md](docs/development.md). +- Комментарии в коде — только по-английски, Rustdoc/Javadoc-стиль. - Тесты живут в `tests/`, без `#[cfg(test)]` в файлах с кодом. - Перед PR: `cargo fmt`, `cargo clippy -D warnings`, `cargo test --all-features`. -Трекер идей и статус задач — [TODO.md](TODO.md), issues и PR — во вкладках репозитория. +Текущий статус — [TODO.md](TODO.md), планы задач — [docs/roadmap/](docs/roadmap/README.md), +история — [CHANGELOG.md](CHANGELOG.md). Issues и PR — во вкладках репозитория. ### Лицензия @@ -306,31 +311,36 @@ Confirmed numbers only — VDS stress test, edge-only on loopback, 2 vCPU | Masked 100-IP handshake flood (5 pps/IP) | **99.6% blocked**, legitimate clients unaffected | | SYN flood without XDP | handled by the kernel | -The full benchmark suite is in progress. +The hot-path microbenchmarks (criterion) run with `cargo bench --all-features --bench +hot_paths`; medians and methodology live in [docs/testing.md](docs/testing.md) §4. ### Documentation | Topic | Where | |-------|-------| | Documentation index | [docs/README.md](docs/README.md) | +| System architecture | [docs/architecture.md](docs/architecture.md) | | Deployment | [docs/deployment.md](docs/deployment.md) | | Configuration | [docs/configuration.md](docs/configuration.md) | | Operations runbook | [docs/runbook.md](docs/runbook.md) | | Troubleshooting | [docs/troubleshooting.md](docs/troubleshooting.md) | | Testing | [docs/testing.md](docs/testing.md) | | Manager API | [docs/api.md](docs/api.md) | +| Roadmap and task plans | [docs/roadmap/](docs/roadmap/README.md) | +| Changelog | [CHANGELOG.md](CHANGELOG.md) | | Knowledge base | [docs/kb/](docs/kb/) | | Research notes | [docs/research/](docs/research/) | ### Development -- Coding rules and Definition of Done: [TODO.md](TODO.md) (§0). -- Code comments are English only, JavaDoc/Rustdoc style (§0.8). +- Coding rules, gates and Definition of Done: [docs/development.md](docs/development.md). +- Code comments are English only, Rustdoc/Javadoc style. - Tests live in `tests/`; no `#[cfg(test)]` modules in code files. - Before a PR: `cargo fmt`, `cargo clippy -D warnings`, `cargo test --all-features`. -Roadmap and task status live in [TODO.md](TODO.md); issues and PRs are in the -repository tabs. +Current status lives in [TODO.md](TODO.md), task plans in +[docs/roadmap/](docs/roadmap/README.md), history in [CHANGELOG.md](CHANGELOG.md). +Issues and PRs are in the repository tabs. ### License diff --git a/TODO.md b/TODO.md index 7fe63b7..697dfcb 100644 --- a/TODO.md +++ b/TODO.md @@ -1,425 +1,47 @@ -# Rampart — Development TODO & Roadmap +# Rampart — TODO -> Живой документ. Философия: **KISS → DRY → SOLID → YAGNI**. -> -> v0.3.0-dev — big-bang редизайн: из Minecraft-специфичной защиты в **универсальную -> L3/L4/L7 платформу сетевой защиты**. MC-код, Java-плагины и dashboard удалены -> (доступны в git-истории до тега v0.2.0). +> Этот файл — только статус и ссылки. Планы задач живут в [docs/roadmap/](docs/roadmap/README.md), +> история изменений — в [CHANGELOG.md](CHANGELOG.md), правила разработки — +> в [docs/development.md](docs/development.md), устройство системы — +> в [docs/architecture.md](docs/architecture.md). --- -## 0. Принципы разработки +## 1. Сейчас -### KISS -- Не добавляй абстракцию до третьего повторения. -- **Функция ≤ 60 строк, файл ≤ 250 строк, ≤ 4 .rs-файлов на папку** (жёсткий лимит; - больше — декомпозиция или группировка доменами с ре-экспортами в mod.rs). - Гейт: `scripts/check_module_size.sh` + ratchet-базлайн `.module_size_baseline` - (легаси — WARN, новые нарушения — FAIL; после рефакторинга `--update-baseline`). -- Не используй generics где хватит `&str` и `Vec`. +| | | +|---|---| +| Версия | `0.3.0-dev` | +| Milestone | **v0.4 — надёжность и воспроизводимость** | +| CI | зелёный: fmt, clippy, тесты, deny, Docker, module-size, secrets | +| Следующий релиз | v0.4 после закрытия трёх задач ниже | -### DRY -- Повтор > 2 раз → выноси, но лучше копипаста чем неправильная абстракция. +## 2. Активные задачи (v0.4) -### SOLID (Rust) -- **S**: один файл = одна ответственность -- **O**: расширяй через трейты (`ProtocolHandler`, `Filter`, `StateStore`) -- **L**: `dyn Filter` — любая реализация без side effects -- **I**: маленькие трейты вместо одного God-trait -- **D**: core зависит от trait-ов, не от Redis/ClickHouse напрямую +| Задача | Приоритет | Статус | План | +|--------|-----------|--------|------| +| XDP netns+veth harness в CI | P0 | planned | [v0.4-xdp-ci-harness.md](docs/roadmap/v0.4-xdp-ci-harness.md) | +| Startup-диагностика окружения | P1 | planned | [v0.4-startup-diagnostics.md](docs/roadmap/v0.4-startup-diagnostics.md) | +| Anti-lockout и баны по порту | P1 | planned | [v0.4-anti-lockout.md](docs/roadmap/v0.4-anti-lockout.md) | -### YAGNI -- Не пиши BGP до v0.6, WASM-плагины до стабилизации compile-time API. -- Не добавляй feature flag если фича не готова. +Статусы и правила ведутся в [docs/roadmap/README.md](docs/roadmap/README.md); +при изменении статуса правятся оба места (файл задачи и эта таблица). -### Rust-специфичные -1. `unwrap()` — только в main() и тестах -2. `unsafe` — только в xdp/, комментарий `// SAFETY:` обязателен -3. `clone()` осознанно, профилируй hot path -4. Блокирующие операции → `spawn_blocking` -5. Логи: `tracing::info!` / `debug!` / `error!` -6. Метрики: register один раз при старте, инкремент в hot path -7. **Тесты отдельно от кода**: в .rs-файлах с кодом НЕТ `#[cfg(test)]`-модулей — - тесты живут в `tests/` (нужный хелпер делай `pub` с реальным вызовом-потребителем). - Существующие инлайн-тесты — легаси, мигрировать постепенно (см. бэклог). +## 3. Дальше -### §0.8 Комментарии в коде (все языки) -- **Все комментарии и doc-комментарии — на английском.** Русский остаётся только в - пользовательских текстах: `docs/`, README, TODO, логи (`tracing::*!`), сообщения CLI/ошибок. -- **JavaDoc/Rustdoc-стиль.** C: `/** ... */` над функцией/структурой/картой/глобалом с - `@param`/`@return`, когда они есть. Rust: `//!` для модуля (что он владеет), `///` для - элемента; сохраняй секции `# Errors` / `# Panics` / `# Safety`. -- **Без эмодзи, ASCII-баннеров (`═══`, `───`), CAPS-акцентов** и декоративных разделителей. - Для группировки — обычный короткий комментарий. -- Инлайн-комментарий объясняет **почему**, а не пересказывает код. Комментарий-шум удаляй. -- Правишь файл — переводи комментарии в нём целиком (смесь языков запрещена), но **не трогай - строковые литералы, идентификаторы и логику**. -- `// SAFETY:` — префикс обязателен, текст по-английски. +| Версия | Содержание | Индекс | +|--------|------------|--------| +| v0.5 | RST-challenge GA, pinned maps + OpenAPI, GeoIP/ASN, gRPC | [docs/roadmap/README.md#5-v05--продуктовые-фичи](docs/roadmap/README.md#5-v05--продуктовые-фичи) | +| v0.6 | HTTP-over-XDP, Bloom, io_uring, ML, BGP | [docs/roadmap/README.md#6-v06--исследования](docs/roadmap/README.md#6-v06--исследования) | +| icebox | Minecraft Velocity forwarding | [icebox-minecraft-velocity.md](docs/roadmap/icebox-minecraft-velocity.md) | + +## 4. Открытые решения + +| Вопрос | Статус | Где | +|--------|--------|-----| +| JWT-роли (RBAC) | поле `role` удалено как мёртвое; RBAC — только при втором потребителе | CHANGELOG Unreleased | +| Rider: self-hosted runner для XDP | решается в дизайне v0.4-xdp-ci-harness | [план](docs/roadmap/v0.4-xdp-ci-harness.md) | --- -## 1. Целевая структура (v0.3) - -``` -guard/ -├── Cargo.toml # ОДИН пакет rampart, features = ["protocol-http", ...] -├── scripts/ # check_module_size.sh (гейт 250/4), check_default_secrets.sh -├── src/ -│ ├── bin/{rampart, rampart-manager, rampart-cli, rampart-tui}.rs # тонкие, логика в lib -│ ├── app/ # thin-main: runtime wiring, services (spawn-циклы) -│ ├── engine/ # listener, tunnel; challenge/ (pow+difficulty), subnet/ (tracker+monitor) -│ ├── filter/ # blacklist, rate_limit, geo — trait Filter -│ ├── traffic/ # hook + prefix/ (key+stats) + intel/ (ewma,detector,reputation) + profile/ (profiler,alert) -│ ├── store/ # redis (+ trait StateStore) -│ ├── manager/ # api/ (+ api/inventory/), auth/, sync/ -│ ├── cli/ # команды; commands/node/ (status,drain,emergency) -│ ├── config/ # config + sections/{edge,platform,detect} -│ ├── tui/ # app/state/ui + metrics/ (prometheus,fetch) -│ ├── protocol/ # trait ProtocolHandler + registry; http/ под фичей -│ └── xdp/ # filter/ (attach,maps), probe/ (diagnostics/,stats,metrics), globals, noop -├── xdp/ -│ ├── core/ # universal_filter.c + maps/stats/config/common.h + prefix_stats/syn_challenge -│ └── hooks/hook_api.h # контракт подключаемых BPF-протокол-хуков -├── tests/ # интеграционные (вне гейта 4-файлов: cargo требует 1 файл = 1 бинарь) -└── docs/ # kb/ (knowledge base) + research/ + ops-доки -``` - -## 1a. Статус после редизайна (2026-08-24) - -| Что | Статус | -|-----|--------| -| plugins/ velocity+paper, dashboard/ | ✅ удалены (git-история) | -| crates/* → единый пакет `rampart` + src/bin | ✅ сделано | -| MC-код (handshake, death_code, varint, hostname-HMAC) | ✅ удалён полностью | -| PoW как универсальный hashcash (`engine/challenge.rs`) | ✅ сохранён | -| XDP: universal L3/L4 фильтр + hooks API | ✅ код готов, clang build OK | -| IPv6 баг в XDP (daddr→saddr) | ✅ исправлен | -| Knowledge Base docs/kb (attacks, defense-levels, practice) | ✅ написана, двуязычная | -| README + architecture.md под новую концепцию | ✅ переписаны | -| cargo build / clippy -D warnings / test | ✅ зелёные | - ---- - -## 2. Ближайшие задачи (v0.3) - -### Subnet-level detection (ботнет с ротацией IP) — ✅ готово (2026-08/09) -- [x] **XDP**: карта `prefix_stats` (LRU_HASH, ключ /24 v4 | /64 v6) — счётчики SYN/pps - per-префикс (xdp/core/prefix_stats.h, трафик-слой: src/traffic/prefix/). -- [x] **Detector**: превышение порога префиксом при IP под лимитом → флаг подсети - (src/traffic/intel/detector.rs, src/engine/subnet/). -- [x] **Мягкая эскалация**: monitor → strict_limit → challenge → block - (SubnetVerdict-лестница; блок /24 идёт через ban_cidr, не слепой hard-ban). -- [x] Блок подсети через `blacklist_map` (LPM trie) — `XdpFilter::ban_cidr`. - -### Движок без протоколов — сделать полезным — ✅ готово -- [x] **Первый протокол-плагин**: `protocol-http` — HTTP/1.1 request-head анализ - (src/protocol/http/, tests/http_protocol.rs). -- [x] **Minecraft Java TCP MVP**: ограниченный handshake status/login, передача исходных - байтов backend и опциональный PROXY protocol v2 (`protocol-minecraft`). -- [x] **TCP-proxy режим**: tunnel.rs + ProtocolHandler интегрированы в listener/app wiring. -- [x] **Fail-fast сообщение** при пустом registry (`ProtocolRegistry::primary()`). - -### Подключение мёртвого интеллекта (правило: «мёртвый код = баг») — ✅ готово -- [x] Traffic Intel в hot path: AttackDetector/IpReputation → метрики + auto-ban - (src/traffic/hook.rs, src/engine/tunnel.rs, src/app/services.rs). -- [x] Blacklist: `clear_expired()` по таймеру (src/app/). -- [x] RateLimiter: TTL-эвикция idle bucket'ов. - -### Безопасность — ✅ кроме ролей -- [x] Rate limiter на login endpoint manager API (per-IP, tests в api/auth.rs). -- [x] JWT: audience-валидация, secret ≥ 32 байт fail-fast (rampart-manager.rs). -- [ ] JWT-роли: сейчас единственный hardcoded `admin`; RBAC-ролей нет — либо убрать поле, - либо делать роли (решение отложить до второго потребителя). -- [x] Redis: `KEYS` → `SCAN` (scan_options), pubsub-подписчик — честный reconnect - с экспоненциальным backoff (src/store/redis.rs). - -### XDP -- [x] Verifier-проверка на реальном ядре (live-тест 2026-09: два бага RST-challenge найдены и - исправлены, d6bcae5). -- [x] Rust loader (`src/xdp/filter/`): open/load/attach, patch глобалов G_* из config.toml - (src/xdp/globals.rs), CString-safe if_nametoindex, реальный detach по fd прогрессы. -- [x] Ringbuf events → blacklist: opt-in `auto_ban` ([xdp] config, default OFF) — - EVENT_RATE_LIMIT всегда, EVENT_CONN_DROP при fails>=порога; EVENT_BAN/POLICY_DROP не - банят (ядро уже отработало / статик-политика без аккумуляции). Парсер 24-байтного - `struct xdp_event` с фиксом endianness (IP — сетевой порядок, скаляры — host), - метрика `rampart_xdp_autobans_total`, tests/xdp_events.rs (10 тестов). -- [ ] Smoke-test attach в CI (VM runner с CAP_BPF) + netns+veth харнесс — вывод №7 из - конкурентного анализа, приоритет v0.4. - -### Документация -- [x] docs/deployment.md, configuration.md, runbook.md — старых крейтов/MC не упоминают (grep чисто). -- [x] docs/kb/README.md — индекс KB со ссылками. -- [x] `docs/README.md` — единый индекс документации (начало работы, how-to, reference, - протоколы, теория/research) + правила ведения: русский язык, один документ = одна - задача, reference правится в том же PR, что и код, плоская структура, kebab-case. -- [x] `README.md` — двуязычный: русская часть сверху, английская снизу, общая шапка/бейджи/ - переключатель языка, ряд кнопок-навигации (docs, quick start, config, API, license); - секции по конвенции (обзор → возможности → требования → установка → быстрый старт → - конфигурация → плагины → производительность → документация → разработка → лицензия), - компактный TOC строкой, копируемые команды, ссылки на docs/README.md. -- [x] `docs/configuration.md` — полная таблица `[xdp]` (включая `udp_policy`) и покрытие IPv4/IPv6; - `docs/testing.md` — реальные XDP-smoke'и, а не только clang-проверка. -- [x] TUI (ratatui): live-метрики из Prometheus endpoint — готово (src/tui/, 564613b). - -## 2a. Раунд 2026-09-15 — исправлено по итогам ревью - -- **unsafe-баги XDP-лоадера** (src/xdp/filter/): `&str.as_ptr()` без NUL в `if_nametoindex` → `CString`; - фиктивный `borrow_raw(-1)`-fd в `unload()` → реальный detach по fd прогрессы с propagatable ошибкой; - `unsafe impl Send` получил `// SAFETY:`; `saturating_mul` в expiry. +5 юнит-тестов. -- **Redis**: fake-reconnect pubsub (sleep+return) → настоящий reconnect-loop с backoff; - `KEYS` → `SCAN` в heartbeat. -- **CI**: `cargo test --all-features` (раньше тесты фич не гонялись); job `repo-gates`: - гейт 250/4 + grep дефолтных секретов; Makefile `ci` обновлён. -- **README**: несуществующие `rampart-core`/`rampart config init` → реальные команды; - таблица компонентов/плагинов приведена к коду (http готов, minecraft удалён, добавлен rampart-tui). -- **Рефакторинг под новые лимиты 250/4** без изменения поведения: app/, challenge/, subnet/, - prefix/, intel/, profile/, commands/node/, api/inventory/, tui/metrics/, filter/, probe/; - bin-файлы тонкие (rampart.rs: 330 → 6 строк). - -### Новые найденные проблемы (чинить в v0.4) -- [x] Redis blacklist: срок/причина сохраняются; edge восстанавливает снимок после reconnect; - локальные autoban-события публикуются в Redis с retry и absolute expiry. -- [ ] Minecraft Java: Velocity modern forwarding, игровые netns smoke-тесты и нагрузочная проверка. -- [x] Принимать client IP от внешнего DDoS-прокси через доверенные CIDR и ограниченный PROXY v2 parser. -- [x] `cargo check --no-default-features` починен (2026-09-15, раунд 2): redis-код в - manager/sync/api/store/app закрыт `#[cfg(feature = "store-redis")]`, менеджер без фичи fail-fast'ит на старте; - CI теперь гоняет `cargo check --no-default-features --all-targets` гейтом. -- [x] `src/app/runtime.rs`: `#[allow(clippy::exit)]` убран — `app::run()` возвращает - `RunExit`, единственный `process::exit` теперь в `main` бина (clippy там не срабатывает). -- [x] Флакающий тест `pow_roundtrip::verifier_rejects_garbage_and_replay` (p≈1/16 из-за - случайного токена) — сидирован, 50 прогонов до (3 fail) / после (0 fail). -- [x] IPv6-паритет XDP (вывод №8) — сделано (2026-11-15): - - [x] **C**: `struct lpm_key6 { u32 prefixlen; u8 addr[16]; }` в `common.h`; - `blacklist6_map` (LPM_TRIE, 20-байтный ключ, value `u64` expiry, 100000, NO_PREALLOC) в `maps.h`; - в `universal_filter.c` non-mapped IPv6 больше не возвращает PASS раньше времени: общий L4-парсинг + - порт-гейт, затем блок `if (native_v6)`: `is_blacklisted6` (lookup `prefixlen=128`, - expiry-cleanup как у v4) → DROP; UDP при `G_UDP_POLICY==1` → DROP; `detect_tcp_bypass` → DROP; - TCP → `prefix_key_from_v6` + `update_prefix_stats` (оживило мёртвый код, замкнуло - детектор подсетей на v6); иначе PASS. Ringbuf-события для v6 не шлём (ABI `src_ip` u32). - - [x] **Rust**: `pub fn blacklist6_key(prefix_len: u8, &[u8;16]) -> [u8;20]` (prefixlen LE в 0..4, - addr network order в 4..20); `blacklist6_update`; `ban_cidr` матчит V4/V6; - `gateway.rs::xdp_ban` → `ban_cidr(ip, 32|128, dur)` для обоих семейств; `ban_ip` удалён - (после перевода gateway вызовов не осталось — «мёртвый код = баг»), `noop.rs` синхронизирован. - - [x] **Тесты**: `tests/xdp_ban_v6.rs` (layout ключа `/64` и `/128`, network order); - `scripts/xdp_ipv6_smoke.sh` — реальный netns+verifier smoke (без бана pass → с баном - blacklist+drop → после снятия снова pass), проверен на ядре 7.3.4. - - [x] **UDP rate-limit (`policy==2`) для native v6** (2026-11-15): `udp_rate_limit6` (LRU_HASH, - 16-байтный ключ `struct in6_addr`, value `struct throttle_entry`) + `throttle_hit6` в - `universal_filter.c` (та же семантика окна/порога, что у v4); ветка UDP в `native_v6` - теперь `switch (G_UDP_POLICY)`: 1 → DROP, 2 → `throttle_hit6` → DROP при превышении, - иначе PASS. Ringbuf-события для v6 по-прежнему не шлём (ABI `src_ip` u32) — только счётчики. - Проверка: фаза 4 в `scripts/xdp_ipv6_smoke.sh` (патч `.rodata` до загрузки: policy=2, - hits=3 → 3 pass, 3 rate-limit). - - Non-goals (позже): conntrack/throttle/RST-challenge для нативного v6 - (нужны 128-битные flow/throttle-ключи); whitelist6 (у `whitelist_map` нет писателя даже для v4); - ringbuf-события для v6; unban v6. -- [x] **Expiry бана из userspace не работал в ядре** (найден и починен 2026-11-15, касался v4 и v6): - `blacklist_expiry_ns` писал `SystemTime` (epoch ns ≈ 1.7e18), а C сравнивает с - `bpf_ktime_get_ns()` (monotonic ≈ uptime) — бан жил до перезагрузки. Теперь userspace пишет - `CLOCK_MONOTONIC`-ns (`xdp::monotonic_ns`), регрессия — `tests/xdp_ban_clock.rs` и expiry-фаза - в `scripts/xdp_ipv6_smoke.sh`. -- [x] **Короткий L4-хвост обходил blacklist** (найден и починен 2026-11-15, v4 и v6): - `universal_filter.c` требовал `sizeof(struct tcphdr)` (20 байт) для всех протоколов, иначе - ранний `XDP_PASS` — UDP-датаграмма короче 20 байт не доходила до порт-гейта и blacklist. - Теперь минимум считается по протоколу (`sizeof(struct udphdr)` для UDP); регрессия — - «короткая датаграмма» в `scripts/xdp_ipv6_smoke.sh`. TCP-путь не изменился: там по-прежнему - требуется полный `struct tcphdr`. -- [x] **XDP-загрузчик не мог загрузить программу вообще** (найден и починен 2026-11-15). - Три независимых бага, каждый из которых валил `load()` до verifier'а: - 1. `.rodata`-раскладка: `build_rodata_image` писал 96-байтный образ в 76-байтную карту - (`EINVAL`) и по неверным смещениям — clang переставляет отдельные `static volatile const` - глобалы (UDP-политика лежала в 4, а не в 49). Теперь в `config.h` один - `struct rampart_config` (layout фиксирован C-структурой + `_Static_assert` на каждый - offset и размер), `XdpGlobals` получил `#[repr(C)]`, образ строится через `offset_of!`, - а `patch_rodata` падает с внятным сообщением при расхождении размера. - 2. `build.rs` отслеживал только `universal_filter.c` — правка `config.h`/`common.h` оставляла - стухший объект в `OUT_DIR` (и старое `.rodata`). Теперь `rerun-if-changed` на `xdp/core` - и `xdp/hooks`. - 3. `build_ringbuf` искал карту `events_map`, а в C она `events_ringbuf` — - `load()` падал после успешного verifier'а. - Регрессии: `tests/xdp_object_maps.rs` (имена всех карт, которые ищет загрузчик, и - `value_size` `.rodata` == `RODATA_SIZE`, без root) + перезапуск реального бинаря в netns - (attach подтверждён), плюс весь `scripts/xdp_ipv6_smoke.sh`. - -## 2b. Ревью 2026-11-16 — качество и надёжность - -Четыре независимых ревью (XDP/загрузчик, data-path, фильтры/хранилища, API/конфиг/CI) -и один раунд фиксов. Гейты после раунда: fmt, clippy `-D warnings`, `cargo test ---all-features` (258 тестов), `--no-default-features` + тесты с `protocol-http`, -module-size, secrets, `cargo deny`, rustdoc без warning'ов, clang+verifier, -`xdp_ipv6_smoke.sh`, `xdp_pkt_test.sh`, живой attach в netns (native и generic). - -### Исправлено - -- XDP: длина TCP-payload по `ip->tot_len`/`payload_len` — на реальном NIC паддинг больше не - ломает `expected_seq` (было: каждое соединение умирало на 4-м сегменте). Регрессия — - `scripts/xdp_pkt_test.sh`. -- XDP: чтение map-значения до `bpf_map_delete_elem` (UAF), сброс `fails`, TFO в `expected_seq`, - исправленный v6 SYN-ACK, `inc_drop()` на всех DROP-путях, per-CPU инкремент без atomic. -- XDP: VLAN/QinQ до L3, фрагменты проверяются по blacklist, неизвестный non-SYN поток → PASS - («stateless-фильтр, не firewall»), `whitelist6_map`, whitelist до state machine. -- XDP spoof-gate: в `prefix_stats` добавлен 64-битный bitmap хешей source-адресов, userspace - считает popcount и сбрасывает счётчики при чтении → `Block` работает и на XDP-пути, а окно - детектора стало честным (раньше счётчики были кумулятивными и со временем «банили» всё). -- XDP: протухшие префиксные баны удаляются userspace-reaper'ом раз в 60 с (пакетный путь - больше не пытается удалить `/24` ключом `/32`). -- Загрузчик: запоминается фактический attach-флаг (native/skb) и проверяется detach; - `DetachGuard` откатывает attach при ошибке; whitelist из конфига грузится в карты; - `ban_cidr` валидирует и маскирует префикс; статистика знает все 13 счётчиков. -- Security: `API_PASSWORD` не пустой и ≥16 символов, `JWT_SECRET` ≥32 непробельных, - `syn_challenge_enabled` требует свой `challenge_secret_hex`, compose без публичных - Redis/ClickHouse и без дефолтных паролей, пустой `CORS_ORIGIN` → deny. -- Storage: ClickHouse с таймаутами и без lock через `.await` (bounded-буфер, метрика дропов), - Redis на `ConnectionManager` с таймаутами и реконнектом, баны из pubsub клампятся, - TOCTOU в blacklist, атомарный `replace_redis`. -- Data path: backoff на `accept()`, корректный `shutdown.changed() == Err`, глобальный бюджет - соединений, rate-limit **до** PoW, whitelist не банится, таймауты connect/handshake/relay, - idle-таймаут relay. -- Детекция: score считается до обновления baseline + гистерезис выхода из `UnderAttack` - (атака больше не «затухает» через тик); реальный cap и инкрементальная эвикция в - rate-limiter и репутации; IPv4-mapped ключи совпадают. -- Blacklist: CIDR-баны хранятся диапазонами — `/24`/`/64` покрывают всю подсеть; - нормализация IPv4-mapped на входе и на lookup. -- CI: джоба `cargo test --no-default-features --features protocol-http`, `make ebpf` больше - не глотает ошибки, secrets-гейт ловит слабые compose-дефолты. -- `doctor` не дёргает защищённые ручки без токена и возвращает ненулевой код при провале. -- Инлайн-тесты: 25 → 10 файлов (остальные — в следующих итерациях). - -### Осталось - -- [x] Monitor (`add_cidr`) и `traffic/hook` autoban сверяются с `trusted_cidrs`: бан - подавляется, если префикс пересекается с доверенной сетью (`TrustedProxyCidr::overlaps_prefix`), - о чём пишется warn. Тесты: `tests/subnet_detection.rs`, `tests/traffic_intel.rs`, - `tests/proxy_identity.rs`. - -### Сделано в этом раунде - -- [x] API manager'а: `SCAN`+`MGET` вместо `KEYS`/N+1, 503 вместо `200 []`, пагинация - `limit`/`offset` (100 по умолчанию, 1000 максимум), GET без записи (бэкфилл метаданных - вынесен в стартовую задачу), `DefaultBodyLimit` 8 КиБ, `TimeoutLayer` 10 с, rate-limit - на все мутирующие ручки, graceful shutdown с SIGTERM и join heartbeat, эвикция - login-лимитера, `MANAGER_TRUSTED_PROXIES` для `X-Forwarded-For`. Тесты — - `tests/manager_api.rs` (9) и `tests/manager_security.rs` (23). -- [x] PROXY-header IP валидируется (loopback/link-local/multicast/broadcast/unspecified и - адреса из `trusted_cidrs` отклоняются, mapped-IPv4 нормализуется), баны для адресов из - `trusted_cidrs` подавляются; невалидный заголовок → transport-peer. -- [x] IPv6 bind в listener (парсинг `IpAddr`, домен по семейству, dual-stack для `::`). -- [x] `limits.relay_idle_timeout_secs` (300 по умолчанию, 1..=86400) и семафор бюджета полем - `Gateway` вместо `OnceLock`. -- [x] Инлайн-тесты мигрированы: `grep -rn "#\[cfg(test)\]" src/` пуст, 41 тест переехал в - 10 новых сюит (`manager_auth`, `manager_heartbeat`, `protocol_http_*`, `traffic_*`, - `tui_prometheus`); счётчик тестов не изменился. - -## 3. Backlog - -- [x] Мигрировать существующие инлайн-тесты (`#[cfg(test)]` в src/) в `tests/` — - правило §0.7; при миграции хелперы, нужные тестам, получают `pub` с потребителем. - Сделано 2026-11-16: в `src/` не осталось ни одного `#[cfg(test)]`. -- [ ] protocol-gRPC plugin (после http) -- [ ] BPF hook #1 реальный: HTTP поверх XDP (rate-limit до userspace) -- [ ] GeoIP/ASN reputation (enum есть, реализации нет) -- [ ] Bloom filter для blacklist -- [ ] io_uring runtime (feature flag) -- [ ] ML anomaly detection (Isolation Forest) -- [x] Fuzzing парсеров (`cargo-fuzz`): цели `http_head` и `proxy_v2` в `fuzz/`, сиды в - `fuzz/seeds/`, запуск `make fuzz` (nightly); PROXY v2-парсер стал чистой функцией - `parse_v2_header` + 10 интеграционных тестов на обрезку/TLV/семейства. -- [ ] BGP Anycast (AS + /24) - ---- - -## 3a. Бенчмарк-конкуренты: чем превзойти - -> Все репо склонированы в `ref/` (gitignored). Анализ issues/PRs проведён 2026-08-24 -> через gh по трекерам конкурентов. Ниже — выжимка «что у них болит и что берём». - -### Карта конкурентов - -| Проект | Что это | Похож на Rampart тем, что | Что взять | -|--------|---------|---------------------------|-----------| -| [eBPFsentinel](https://github.com/ebpfsentinel/ebpfsentinel) | Rust, один бинарник: firewall+IDS+DDoS через XDP/TC/uprobe | Ближайший аналог, та же архитектура | Rootless BPF token (kernel 6.9+); tail-call цепочки; MITRE-теги алертов; Swagger UI | -| [CrabShield](https://github.com/aleksgrim/crab-shield) | Rust + XDP, гибрид L7→L3 | «Умный юзерспейс, кара в ядре» | Static musl бинарник; reaper истекающих банов; (log-tailing НЕ брать — хрупко) | -| [lnvps_fw](https://github.com/LNVPS/api) | XDP+TC защита VDS | Прямо наша ниша | ⭐ SYN-proxy в XDP; port learning из TC egress; лестница PORT_FILTER→SYN_PROXY→SOURCE_BLOCK + spoof gate; netns+veth harness | -| [Oubliette](https://f0o.dev/projects/2026/04/oubliette/) | Linerate scrubber | Решает нашу боль с PoW | ⭐ RST-challenge: SYN-ACK с неверным ACK → спуф молчит, живой клиент шлёт RST → whitelist. Совместимо с любым клиентом | -| [Couic](https://github.com/fcsc-fr/couic) (CERT Франции) | XDP-фаервол + REST API | Наш manager API | Anti-lockout; теги+TTL записей; OpenAPI spec; синк инстансов; fail2ban-интеграция | -| [gamemann/XDP-Firewall](https://github.com/gamemann/XDP-Firewall) (~830★) | Классический C XDP-фаервол | Референс по XDP | Pinned maps для внешнего управления; их issues = карта граблей верификатора | -| [gen0sec/synapse](https://github.com/gen0sec/synapse) | NDR: eBPF + JA4-фингерпринты + ratatui TUI | TUI как наш план | JA4+/JA4T фингерпринтинг (бан по отпечатку); fallback-цепочка XDP→nftables→iptables | - -### Топ-10 выводов из их issues/PRs (приоритет) - -1. **Диагностика окружения при старте** — проверять ядро/BTF/driver NIC до загрузки, - человекочитаемый вердикт. ≈80% issues XDP-Firewall — про attach на неподдерживаемом - окружении (#70/#71/#9/#44). Печатать режим (native/generic) честно. -2. **Эскалационная лестница защиты** (lnvps_fw): pass-all steady state → PORT_FILTER → - SYN_PROXY (tail-call, keyed cookie, ротация секрета) → SOURCE_BLOCK только со spoof-gate. -3. **RST-challenge** (Oubliette) вместо мёртвого текстового PoW — универсально совместимо. -4. **REST API + OpenAPI + pinned maps**: динамические IP-списки без перекомпиляции — - самый частый feature request (#79/#77/#78 у gamemann); web-панель так и не сделана автором = свободная ниша. -5. **Anti-lockout + per-port баны**: слепой XDP_DROP по IP = self-lockout по SSH - (crab-shield docs). Whitelist обязателен, но не единственная защита. -6. **LRU во всех data-path maps** — иначе silent default-deny под атакой (netshield DD-003). - Per-src-IP rate limit не работает против spoofed flood 50–100 Mpps (gamemann #45) — - нужны per-port/per-subnet/flow агрегаты. -7. **netns+veth тестовый харнесс** + eBPF test_run тесты в CI (подтверждено в 2 проектах, - отсутствует у всех) — наше конкурентное преимущество в надёжности. -8. **IPv6-паритет с первого дня** + VLAN/QinQ парсинг (issue #75 висит годами). -9. **Rootless BPF token как опция**, fallback CAP_BPF для ядер 5.15+ — не повторять жёсткий - floor 6.9+ (ebpfsentinel отсёк enterprise) и не требовать root (crab-shield). -10. **События атак наружу с первого дня**: poll-and-persist, дедуп алертов на переходе - состояния (урок LNVPS #331 — отложили = дыра в продукте). - -### Наши козыри (чем превзошли уже) - -- Двуязыная Knowledge Base (docs/kb/) — educational killer-feature, нет ни у одного конкурента -- Один Rust-бинарник без C-зависимостей сборки (класс сегфолтов/libbpf-hell gamemann исключён) -- Честные бенчмарки: цифры только с отчётами, методология опубликована -- Модульный лимит ≤300 строк + no-dead-code политика в CI - ---- - -## 4. Anti-Regression — правила приёмки - -1. **No dead code**: каждый `pub` имеет вызова вне `#[cfg(test)]`. -2. **Config field = потребитель**: нет поля без использования. -3. **Метрика регистрируется → обновляется**: единственный writer на каждую метрику. -4. **Feature flag = сборка в CI**: `--all-features` зелёный, иначе фичи нет. -5. **По умолчанию безопасно**: нет дефолтных секретов; отсутствие обязательного env = fail-fast. -6. **Интеграционный тест на слой**: config parse, filter logic, registry fail-fast (есть); - новый слой = новый тест. -7. **Файл ≤ 250 строк, папка ≤ 4 .rs**: CI-гейт `scripts/check_module_size.sh` - (ratchet-базлайн `.module_size_baseline`: легаси — WARN, новые нарушения — FAIL). -8. **CI guardrails**: `cargo clippy --all-targets -- -D warnings`, `cargo test`, - clang-build xdp/core/universal_filter.c, grep на `changeme`. -9. **README/TODO не врут**: каждое число имеет ссылку на тест или отчёт. - -## 5. Definition of Done - -``` -☐ cargo check / cargo test проходят -☐ cargo clippy --all-targets -- -D warnings — 0 warnings -☐ cargo fmt --check проходит -☐ Ни один файл не превышает 250 строк; ни в одной папке src/ больше 4 .rs-файлов -☐ Unit тесты покрывают happy path + 2+ error cases -☐ Нет мёртвого кода: pub без вызовов, конфиг-поле без потребителя, метрика без writer -☐ Нет дефолтных секретов -☐ README соответствует коду -☐ Документация обновлена -☐ CI зелёный -``` - -## 6. Anti-Patterns - -``` -❌ Тесты после кода. Пиши вместе. -❌ Файл > 250 строк или > 4 .rs в папке — сигнал декомпозировать/сгруппировать немедленно. -❌ TODO в коде без issue. -❌ Мёртвый код: pub без вызовов, конфиг-поле без потребителя, метрика без writer. -❌ «Бумажный слой»: фича описана, но не вызывается. -❌ Дефолтный секрет. -❌ Парсер за «один read» — TCP-поток приходит фрагментами. -❌ Feature flag, который не собирается в CI. -``` - ---- - -*Версия: 5.0 | Обновлён: 2026-09-15 (bug-fix раунд: XDP unsafe, Redis reconnect/SCAN, CI-гейты, лимиты 250/4)* +*Версия: 6.0 | Ноябрь 2026* diff --git a/docs/README.md b/docs/README.md index 73af69c..de07183 100644 --- a/docs/README.md +++ b/docs/README.md @@ -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* diff --git a/docs/api.md b/docs/api.md index cdd73fb..0976aac 100644 --- a/docs/api.md +++ b/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 ` существует, но + завершается явной ошибкой «not implemented»); - webhooks, metrics summary, challenge management; - регистрации нод через `POST /api/v1/nodes`. @@ -157,4 +159,4 @@ Edge подписывается на Pub/Sub перед загрузкой сн --- -*Версия: 2.0 | Август 2026* +*Версия: 2.1 | Ноябрь 2026* diff --git a/docs/architecture.md b/docs/architecture.md new file mode 100644 index 0000000..e948693 --- /dev/null +++ b/docs/architecture.md @@ -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* diff --git a/docs/configuration.md b/docs/configuration.md index c3cd4bf..d0b8c9b 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -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/` по умолчанию. Полный прогон на реальном ядре — +`scripts/xdp_ci.sh` (см. [testing.md](testing.md)). --- -*Версия: 2.1 | Октябрь 2026* +*Версия: 3.0 | Ноябрь 2026* diff --git a/docs/deployment.md b/docs/deployment.md index 19db2ee..d4e1bf6 100644 --- a/docs/deployment.md +++ b/docs/deployment.md @@ -145,4 +145,4 @@ redis_url = "redis://:PASSWORD@redis:6379/0" --- -*Версия: 2.1 | Октябрь 2026* +*Версия: 3.0 | Ноябрь 2026* diff --git a/docs/development.md b/docs/development.md new file mode 100644 index 0000000..dd34349 --- /dev/null +++ b/docs/development.md @@ -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* diff --git a/docs/disaster_recovery.md b/docs/disaster_recovery.md index f49c69d..4393224 100644 --- a/docs/disaster_recovery.md +++ b/docs/disaster_recovery.md @@ -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* diff --git a/docs/research/README.md b/docs/research/README.md index 157dca6..9a6590c 100644 --- a/docs/research/README.md +++ b/docs/research/README.md @@ -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 diff --git a/docs/research/architecture.md b/docs/research/architecture.md index a6d7436..13bc061 100644 --- a/docs/research/architecture.md +++ b/docs/research/architecture.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 --- diff --git a/docs/roadmap/README.md b/docs/roadmap/README.md new file mode 100644 index 0000000..73d765d --- /dev/null +++ b/docs/roadmap/README.md @@ -0,0 +1,79 @@ +# Roadmap — Rampart + +> Индекс планов по версиям. `TODO.md` в корне — только статус и ссылки сюда; +> детали каждой задачи живут в отдельном файле этой папки. + +--- + +## 1. Правила + +1. **Одна задача = один файл.** Имя: `-.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* diff --git a/docs/roadmap/icebox-minecraft-velocity.md b/docs/roadmap/icebox-minecraft-velocity.md new file mode 100644 index 0000000..c3d0758 --- /dev/null +++ b/docs/roadmap/icebox-minecraft-velocity.md @@ -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 +задач. diff --git a/docs/roadmap/v0.4-anti-lockout.md b/docs/roadmap/v0.4-anti-lockout.md new file mode 100644 index 0000000..19ffe24 --- /dev/null +++ b/docs/roadmap/v0.4-anti-lockout.md @@ -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`), + 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-процедура воспроизводится с нуля. diff --git a/docs/roadmap/v0.4-startup-diagnostics.md b/docs/roadmap/v0.4-startup-diagnostics.md new file mode 100644 index 0000000..8f961fc --- /dev/null +++ b/docs/roadmap/v0.4-startup-diagnostics.md @@ -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`. diff --git a/docs/roadmap/v0.4-xdp-ci-harness.md b/docs/roadmap/v0.4-xdp-ci-harness.md new file mode 100644 index 0000000..557ac78 --- /dev/null +++ b/docs/roadmap/v0.4-xdp-ci-harness.md @@ -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` отдельно. diff --git a/docs/roadmap/v0.5-geoip-asn.md b/docs/roadmap/v0.5-geoip-asn.md new file mode 100644 index 0000000..01bb66c --- /dev/null +++ b/docs/roadmap/v0.5-geoip-asn.md @@ -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 обновлён. +- [ ] Лицензия базы и ограничения описаны в документации. diff --git a/docs/roadmap/v0.5-grpc-plugin.md b/docs/roadmap/v0.5-grpc-plugin.md new file mode 100644 index 0000000..00539cd --- /dev/null +++ b/docs/roadmap/v0.5-grpc-plugin.md @@ -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). diff --git a/docs/roadmap/v0.5-pinned-maps-openapi.md b/docs/roadmap/v0.5-pinned-maps-openapi.md new file mode 100644 index 0000000..c72777c --- /dev/null +++ b/docs/roadmap/v0.5-pinned-maps-openapi.md @@ -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 и тест. diff --git a/docs/roadmap/v0.5-rst-challenge-ga.md b/docs/roadmap/v0.5-rst-challenge-ga.md new file mode 100644 index 0000000..dcd7ea6 --- /dev/null +++ b/docs/roadmap/v0.5-rst-challenge-ga.md @@ -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-ноде. diff --git a/docs/roadmap/v0.6-bgp-anycast.md b/docs/roadmap/v0.6-bgp-anycast.md new file mode 100644 index 0000000..873763a --- /dev/null +++ b/docs/roadmap/v0.6-bgp-anycast.md @@ -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 на случай анонса «плохого» префикса. diff --git a/docs/roadmap/v0.6-bloom-filter.md b/docs/roadmap/v0.6-bloom-filter.md new file mode 100644 index 0000000..a8e9600 --- /dev/null +++ b/docs/roadmap/v0.6-bloom-filter.md @@ -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 к точной карте). diff --git a/docs/roadmap/v0.6-http-over-xdp.md b/docs/roadmap/v0.6-http-over-xdp.md new file mode 100644 index 0000000..f88d095 --- /dev/null +++ b/docs/roadmap/v0.6-http-over-xdp.md @@ -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, размер программы в лимитах. +- [ ] Фича выключена по умолчанию и не ломает сборку без неё. diff --git a/docs/roadmap/v0.6-io-uring.md b/docs/roadmap/v0.6-io-uring.md new file mode 100644 index 0000000..971bd37 --- /dev/null +++ b/docs/roadmap/v0.6-io-uring.md @@ -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. diff --git a/docs/roadmap/v0.6-ml-anomaly.md b/docs/roadmap/v0.6-ml-anomaly.md new file mode 100644 index 0000000..bd889de --- /dev/null +++ b/docs/roadmap/v0.6-ml-anomaly.md @@ -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 (замер). diff --git a/docs/runbook.md b/docs/runbook.md index 7c0c1ce..0269bfb 100644 --- a/docs/runbook.md +++ b/docs/runbook.md @@ -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* diff --git a/docs/testing.md b/docs/testing.md index 5c3b685..26fed51 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -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* diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 0b366e7..6f63ec0 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -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* diff --git a/docs/vds_compatibility.md b/docs/vds_compatibility.md index 5ec5fa4..26353e0 100644 --- a/docs/vds_compatibility.md +++ b/docs/vds_compatibility.md @@ -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* diff --git a/scripts/check_docs_links.sh b/scripts/check_docs_links.sh new file mode 100755 index 0000000..e101f13 --- /dev/null +++ b/scripts/check_docs_links.sh @@ -0,0 +1,47 @@ +#!/usr/bin/env bash +# Verifies that every relative Markdown link in the tracked documentation points +# at an existing file. External links are not fetched: CI must stay offline and +# deterministic, and a dead third-party URL is not a repo defect. +# +# Usage: bash scripts/check_docs_links.sh +set -euo pipefail + +repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" +cd "$repo_root" + +python3 - <<'PY' +import pathlib +import re +import sys + +ROOTS = ["README.md", "TODO.md", "CHANGELOG.md"] +ROOTS += [str(p) for p in pathlib.Path("docs").rglob("*.md")] +ROOTS += [str(p) for p in pathlib.Path("deploy").rglob("*.md")] + +LINK = re.compile(r"\]\(([^)]+)\)") +SKIP_PREFIX = ("http://", "https://", "mailto:", "#") + +missing = [] +for name in sorted(set(ROOTS)): + path = pathlib.Path(name) + if not path.is_file(): + continue + base = path.parent + for match in LINK.finditer(path.read_text(encoding="utf-8")): + target = match.group(1).strip() + # Drop the anchor and an optional title: ](file.md "title") + target = target.split("#", 1)[0].split(" ", 1)[0] + if not target or target.startswith(SKIP_PREFIX): + continue + resolved = (base / target).resolve() + if not resolved.exists(): + missing.append(f"{name}: {match.group(1)}") + +if missing: + print("Broken documentation links:", file=sys.stderr) + for item in missing: + print(f" {item}", file=sys.stderr) + sys.exit(1) + +print(f"Documentation links OK ({len(set(ROOTS))} files)") +PY diff --git a/scripts/check_module_size.sh b/scripts/check_module_size.sh index 2581499..9f6fa97 100755 --- a/scripts/check_module_size.sh +++ b/scripts/check_module_size.sh @@ -2,7 +2,7 @@ # # check_module_size.sh — module size ratchet. # -# Project standard (TODO.md §4): max 250 lines per .rs file; max 4 .rs files +# Project standard (docs/development.md §2): max 250 lines per .rs file; max 4 .rs files # per source directory (top level, non-recursive, mod.rs included). # # Rationale — ratchet pattern: the gate blocks regressions immediately while diff --git a/src/cli/commands/config.rs b/src/cli/commands/config.rs index 17db4c6..ef766df 100644 --- a/src/cli/commands/config.rs +++ b/src/cli/commands/config.rs @@ -10,7 +10,7 @@ pub async fn run(key: Option, value: Option) -> anyhow::Result<( (None, Some(_)) | (None, None) => { println!("Configuration"); println!("=============\n"); - println!("Use: rampart config [value]"); + println!("Use: rampart-cli config [value]"); println!(); println!("Example keys:"); println!(" workers.count"); diff --git a/src/cli/commands/node/status.rs b/src/cli/commands/node/status.rs index 2bfdf7d..77dd763 100644 --- a/src/cli/commands/node/status.rs +++ b/src/cli/commands/node/status.rs @@ -20,6 +20,6 @@ pub async fn run() -> anyhow::Result<()> { } println!(); - println!("To check individual components, run: rampart doctor"); + println!("To check individual components, run: rampart-cli doctor"); Ok(()) } diff --git a/src/manager/auth.rs b/src/manager/auth.rs index c9d9153..f7ea6a7 100644 --- a/src/manager/auth.rs +++ b/src/manager/auth.rs @@ -12,7 +12,6 @@ use std::sync::Arc; pub struct Claims { pub sub: String, pub aud: String, - pub role: String, pub exp: usize, pub iat: usize, } @@ -22,7 +21,6 @@ pub fn create_token(secret: &str, expiration: u64, audience: &str) -> Result claims.iat); }