docs: per-task roadmap, architecture and changelog

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

View file

@ -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

100
CHANGELOG.md Normal file
View file

@ -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.

View file

@ -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.

View file

@ -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

446
TODO.md
View file

@ -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<u8>`.
| | |
|---|---|
| Версия | `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*

View file

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

View file

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

212
docs/architecture.md Normal file
View file

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

View file

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

View file

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

116
docs/development.md Normal file
View file

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

View file

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

View file

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

View file

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

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

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

View file

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

View file

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

View file

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

View file

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

View file

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

View file

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

View file

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

View file

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

View file

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

View file

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

View file

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

View file

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

View file

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

View file

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

View file

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

View file

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

View file

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

47
scripts/check_docs_links.sh Executable file
View file

@ -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

View file

@ -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

View file

@ -10,7 +10,7 @@ pub async fn run(key: Option<String>, value: Option<String>) -> anyhow::Result<(
(None, Some(_)) | (None, None) => {
println!("Configuration");
println!("=============\n");
println!("Use: rampart config <key> [value]");
println!("Use: rampart-cli config <key> [value]");
println!();
println!("Example keys:");
println!(" workers.count");

View file

@ -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(())
}

View file

@ -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<Str
let claims = Claims {
sub: "rampart-admin".to_string(),
aud: audience.to_string(),
role: "admin".to_string(),
exp: now + expiration as usize,
iat: now,
};

View file

@ -14,7 +14,6 @@ fn create_verify_roundtrip_passes() {
let claims = verify_token(&token, &secret, "rampart").expect("verification should succeed");
assert_eq!(claims.sub, "rampart-admin");
assert_eq!(claims.aud, "rampart");
assert_eq!(claims.role, "admin");
assert!(claims.exp > claims.iat);
}