docs: per-task roadmap, architecture and changelog
- Split TODO into a thin status index plus docs/roadmap/ with one file per task (v0.4 reliability, v0.5 product, v0.6 research, icebox). - Add docs/architecture.md (current processes, packet/data path, layers, storage, metrics) and docs/development.md (rules, gates, DoD). - Add CHANGELOG.md reconstructed from history; move round details out of TODO. - Align docs with the code: config defaults and missing [detect]/ [protocol.http] sections, XDP metric names, ClickHouse table and TTL, Redis RDB restore, multiarch clang include, CLI binary name. - Add scripts/check_docs_links.sh and run it in CI. - release profile: thin LTO + one codegen unit. Binary 12.3 MB -> 9.7 MB, http parser bench 314 ns -> 278 ns; panic=abort stays off for catch_unwind in the Redis subscriber. - Drop the unused JWT role claim; fix 'rampart doctor' hints in the CLI.
This commit is contained in:
parent
1b3ae5e546
commit
280284667f
38 changed files with 1582 additions and 623 deletions
2
.github/workflows/ci.yml
vendored
2
.github/workflows/ci.yml
vendored
|
|
@ -70,6 +70,8 @@ jobs:
|
||||||
run: bash scripts/check_module_size.sh
|
run: bash scripts/check_module_size.sh
|
||||||
- name: Default secrets gate
|
- name: Default secrets gate
|
||||||
run: bash scripts/check_default_secrets.sh
|
run: bash scripts/check_default_secrets.sh
|
||||||
|
- name: Documentation links gate
|
||||||
|
run: bash scripts/check_docs_links.sh
|
||||||
|
|
||||||
rust-deny:
|
rust-deny:
|
||||||
name: Rust — cargo-deny
|
name: Rust — cargo-deny
|
||||||
|
|
|
||||||
100
CHANGELOG.md
Normal file
100
CHANGELOG.md
Normal 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.
|
||||||
13
Cargo.toml
13
Cargo.toml
|
|
@ -37,8 +37,8 @@ store-redis = ["dep:redis"]
|
||||||
geoip = ["dep:maxminddb"]
|
geoip = ["dep:maxminddb"]
|
||||||
xdp = ["dep:libbpf-rs", "dep:libc"]
|
xdp = ["dep:libbpf-rs", "dep:libc"]
|
||||||
io-uring = ["dep:tokio-splice"]
|
io-uring = ["dep:tokio-splice"]
|
||||||
# HTTP/1.1 protocol handler: парсинг request-head, verdict Allow/Reject,
|
# HTTP/1.1 protocol handler: request-head parsing, Allow/Reject verdict,
|
||||||
# туннелирование на upstream (см. src/protocol/http/ и [protocol.http] в конфиге).
|
# upstream tunnelling (see src/protocol/http/ and [protocol.http] in the config).
|
||||||
protocol-http = []
|
protocol-http = []
|
||||||
protocol-minecraft = []
|
protocol-minecraft = []
|
||||||
|
|
||||||
|
|
@ -87,3 +87,12 @@ criterion = { version = "0.5", features = ["html_reports"] }
|
||||||
name = "hot_paths"
|
name = "hot_paths"
|
||||||
harness = false
|
harness = false
|
||||||
required-features = ["protocol-http"]
|
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.
|
||||||
|
|
|
||||||
28
README.md
28
README.md
|
|
@ -147,30 +147,35 @@ Rampart не спасёт уже забитый домашний канал: п
|
||||||
| Маскированный flood с 100 IP (5 pps/IP) | **99.6% заблокировано**, легитимные клиенты работают |
|
| Маскированный flood с 100 IP (5 pps/IP) | **99.6% заблокировано**, легитимные клиенты работают |
|
||||||
| SYN flood без XDP | обрабатывается ядром |
|
| 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/README.md](docs/README.md) |
|
||||||
|
| Архитектура системы | [docs/architecture.md](docs/architecture.md) |
|
||||||
| Деплой | [docs/deployment.md](docs/deployment.md) |
|
| Деплой | [docs/deployment.md](docs/deployment.md) |
|
||||||
| Конфигурация | [docs/configuration.md](docs/configuration.md) |
|
| Конфигурация | [docs/configuration.md](docs/configuration.md) |
|
||||||
| Эксплуатация (runbook) | [docs/runbook.md](docs/runbook.md) |
|
| Эксплуатация (runbook) | [docs/runbook.md](docs/runbook.md) |
|
||||||
| Диагностика | [docs/troubleshooting.md](docs/troubleshooting.md) |
|
| Диагностика | [docs/troubleshooting.md](docs/troubleshooting.md) |
|
||||||
| Тестирование | [docs/testing.md](docs/testing.md) |
|
| Тестирование | [docs/testing.md](docs/testing.md) |
|
||||||
| API manager'а | [docs/api.md](docs/api.md) |
|
| API manager'а | [docs/api.md](docs/api.md) |
|
||||||
|
| Roadmap и планы задач | [docs/roadmap/](docs/roadmap/README.md) |
|
||||||
|
| История изменений | [CHANGELOG.md](CHANGELOG.md) |
|
||||||
| База знаний (атаки, защита, практика) | [docs/kb/](docs/kb/) |
|
| База знаний (атаки, защита, практика) | [docs/kb/](docs/kb/) |
|
||||||
| Research: архитектура, eBPF, DDoS | [docs/research/](docs/research/) |
|
| Research: архитектура, eBPF, DDoS | [docs/research/](docs/research/) |
|
||||||
|
|
||||||
### Разработка
|
### Разработка
|
||||||
|
|
||||||
- Правила кода и Definition of Done — [TODO.md](TODO.md) (§0).
|
- Правила кода, гейты и Definition of Done — [docs/development.md](docs/development.md).
|
||||||
- Комментарии в коде — только по-английски, JavaDoc/Rustdoc-стиль (§0.8).
|
- Комментарии в коде — только по-английски, Rustdoc/Javadoc-стиль.
|
||||||
- Тесты живут в `tests/`, без `#[cfg(test)]` в файлах с кодом.
|
- Тесты живут в `tests/`, без `#[cfg(test)]` в файлах с кодом.
|
||||||
- Перед PR: `cargo fmt`, `cargo clippy -D warnings`, `cargo test --all-features`.
|
- Перед 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 |
|
| Masked 100-IP handshake flood (5 pps/IP) | **99.6% blocked**, legitimate clients unaffected |
|
||||||
| SYN flood without XDP | handled by the kernel |
|
| 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
|
### Documentation
|
||||||
|
|
||||||
| Topic | Where |
|
| Topic | Where |
|
||||||
|-------|-------|
|
|-------|-------|
|
||||||
| Documentation index | [docs/README.md](docs/README.md) |
|
| Documentation index | [docs/README.md](docs/README.md) |
|
||||||
|
| System architecture | [docs/architecture.md](docs/architecture.md) |
|
||||||
| Deployment | [docs/deployment.md](docs/deployment.md) |
|
| Deployment | [docs/deployment.md](docs/deployment.md) |
|
||||||
| Configuration | [docs/configuration.md](docs/configuration.md) |
|
| Configuration | [docs/configuration.md](docs/configuration.md) |
|
||||||
| Operations runbook | [docs/runbook.md](docs/runbook.md) |
|
| Operations runbook | [docs/runbook.md](docs/runbook.md) |
|
||||||
| Troubleshooting | [docs/troubleshooting.md](docs/troubleshooting.md) |
|
| Troubleshooting | [docs/troubleshooting.md](docs/troubleshooting.md) |
|
||||||
| Testing | [docs/testing.md](docs/testing.md) |
|
| Testing | [docs/testing.md](docs/testing.md) |
|
||||||
| Manager API | [docs/api.md](docs/api.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/) |
|
| Knowledge base | [docs/kb/](docs/kb/) |
|
||||||
| Research notes | [docs/research/](docs/research/) |
|
| Research notes | [docs/research/](docs/research/) |
|
||||||
|
|
||||||
### Development
|
### Development
|
||||||
|
|
||||||
- Coding rules and Definition of Done: [TODO.md](TODO.md) (§0).
|
- Coding rules, gates and Definition of Done: [docs/development.md](docs/development.md).
|
||||||
- Code comments are English only, JavaDoc/Rustdoc style (§0.8).
|
- Code comments are English only, Rustdoc/Javadoc style.
|
||||||
- Tests live in `tests/`; no `#[cfg(test)]` modules in code files.
|
- Tests live in `tests/`; no `#[cfg(test)]` modules in code files.
|
||||||
- Before a PR: `cargo fmt`, `cargo clippy -D warnings`, `cargo test --all-features`.
|
- 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
|
Current status lives in [TODO.md](TODO.md), task plans in
|
||||||
repository tabs.
|
[docs/roadmap/](docs/roadmap/README.md), history in [CHANGELOG.md](CHANGELOG.md).
|
||||||
|
Issues and PRs are in the repository tabs.
|
||||||
|
|
||||||
### License
|
### License
|
||||||
|
|
||||||
|
|
|
||||||
446
TODO.md
446
TODO.md
|
|
@ -1,425 +1,47 @@
|
||||||
# Rampart — Development TODO & Roadmap
|
# Rampart — TODO
|
||||||
|
|
||||||
> Живой документ. Философия: **KISS → DRY → SOLID → YAGNI**.
|
> Этот файл — только статус и ссылки. Планы задач живут в [docs/roadmap/](docs/roadmap/README.md),
|
||||||
>
|
> история изменений — в [CHANGELOG.md](CHANGELOG.md), правила разработки —
|
||||||
> v0.3.0-dev — big-bang редизайн: из Minecraft-специфичной защиты в **универсальную
|
> в [docs/development.md](docs/development.md), устройство системы —
|
||||||
> L3/L4/L7 платформу сетевой защиты**. MC-код, Java-плагины и dashboard удалены
|
> в [docs/architecture.md](docs/architecture.md).
|
||||||
> (доступны в git-истории до тега v0.2.0).
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 0. Принципы разработки
|
## 1. Сейчас
|
||||||
|
|
||||||
### KISS
|
| | |
|
||||||
- Не добавляй абстракцию до третьего повторения.
|
|---|---|
|
||||||
- **Функция ≤ 60 строк, файл ≤ 250 строк, ≤ 4 .rs-файлов на папку** (жёсткий лимит;
|
| Версия | `0.3.0-dev` |
|
||||||
больше — декомпозиция или группировка доменами с ре-экспортами в mod.rs).
|
| Milestone | **v0.4 — надёжность и воспроизводимость** |
|
||||||
Гейт: `scripts/check_module_size.sh` + ratchet-базлайн `.module_size_baseline`
|
| CI | зелёный: fmt, clippy, тесты, deny, Docker, module-size, secrets |
|
||||||
(легаси — WARN, новые нарушения — FAIL; после рефакторинга `--update-baseline`).
|
| Следующий релиз | v0.4 после закрытия трёх задач ниже |
|
||||||
- Не используй generics где хватит `&str` и `Vec<u8>`.
|
|
||||||
|
|
||||||
### DRY
|
## 2. Активные задачи (v0.4)
|
||||||
- Повтор > 2 раз → выноси, но лучше копипаста чем неправильная абстракция.
|
|
||||||
|
|
||||||
### SOLID (Rust)
|
| Задача | Приоритет | Статус | План |
|
||||||
- **S**: один файл = одна ответственность
|
|--------|-----------|--------|------|
|
||||||
- **O**: расширяй через трейты (`ProtocolHandler`, `Filter`, `StateStore`)
|
| XDP netns+veth harness в CI | P0 | planned | [v0.4-xdp-ci-harness.md](docs/roadmap/v0.4-xdp-ci-harness.md) |
|
||||||
- **L**: `dyn Filter` — любая реализация без side effects
|
| Startup-диагностика окружения | P1 | planned | [v0.4-startup-diagnostics.md](docs/roadmap/v0.4-startup-diagnostics.md) |
|
||||||
- **I**: маленькие трейты вместо одного God-trait
|
| Anti-lockout и баны по порту | P1 | planned | [v0.4-anti-lockout.md](docs/roadmap/v0.4-anti-lockout.md) |
|
||||||
- **D**: core зависит от trait-ов, не от Redis/ClickHouse напрямую
|
|
||||||
|
|
||||||
### YAGNI
|
Статусы и правила ведутся в [docs/roadmap/README.md](docs/roadmap/README.md);
|
||||||
- Не пиши BGP до v0.6, WASM-плагины до стабилизации compile-time API.
|
при изменении статуса правятся оба места (файл задачи и эта таблица).
|
||||||
- Не добавляй feature flag если фича не готова.
|
|
||||||
|
|
||||||
### Rust-специфичные
|
## 3. Дальше
|
||||||
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` с реальным вызовом-потребителем).
|
|
||||||
Существующие инлайн-тесты — легаси, мигрировать постепенно (см. бэклог).
|
|
||||||
|
|
||||||
### §0.8 Комментарии в коде (все языки)
|
| Версия | Содержание | Индекс |
|
||||||
- **Все комментарии и doc-комментарии — на английском.** Русский остаётся только в
|
|--------|------------|--------|
|
||||||
пользовательских текстах: `docs/`, README, TODO, логи (`tracing::*!`), сообщения CLI/ошибок.
|
| v0.5 | RST-challenge GA, pinned maps + OpenAPI, GeoIP/ASN, gRPC | [docs/roadmap/README.md#5-v05--продуктовые-фичи](docs/roadmap/README.md#5-v05--продуктовые-фичи) |
|
||||||
- **JavaDoc/Rustdoc-стиль.** C: `/** ... */` над функцией/структурой/картой/глобалом с
|
| v0.6 | HTTP-over-XDP, Bloom, io_uring, ML, BGP | [docs/roadmap/README.md#6-v06--исследования](docs/roadmap/README.md#6-v06--исследования) |
|
||||||
`@param`/`@return`, когда они есть. Rust: `//!` для модуля (что он владеет), `///` для
|
| icebox | Minecraft Velocity forwarding | [icebox-minecraft-velocity.md](docs/roadmap/icebox-minecraft-velocity.md) |
|
||||||
элемента; сохраняй секции `# Errors` / `# Panics` / `# Safety`.
|
|
||||||
- **Без эмодзи, ASCII-баннеров (`═══`, `───`), CAPS-акцентов** и декоративных разделителей.
|
## 4. Открытые решения
|
||||||
Для группировки — обычный короткий комментарий.
|
|
||||||
- Инлайн-комментарий объясняет **почему**, а не пересказывает код. Комментарий-шум удаляй.
|
| Вопрос | Статус | Где |
|
||||||
- Правишь файл — переводи комментарии в нём целиком (смесь языков запрещена), но **не трогай
|
|--------|--------|-----|
|
||||||
строковые литералы, идентификаторы и логику**.
|
| JWT-роли (RBAC) | поле `role` удалено как мёртвое; RBAC — только при втором потребителе | CHANGELOG Unreleased |
|
||||||
- `// SAFETY:` — префикс обязателен, текст по-английски.
|
| Rider: self-hosted runner для XDP | решается в дизайне v0.4-xdp-ci-harness | [план](docs/roadmap/v0.4-xdp-ci-harness.md) |
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 1. Целевая структура (v0.3)
|
*Версия: 6.0 | Ноябрь 2026*
|
||||||
|
|
||||||
```
|
|
||||||
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)*
|
|
||||||
|
|
|
||||||
|
|
@ -1,7 +1,8 @@
|
||||||
# Документация Rampart
|
# Документация 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'а |
|
| [deployment.md](deployment.md) | Первый деплой edge-ноды и manager'а |
|
||||||
| [configuration.md](configuration.md) | Настройка `config.toml`, секция `[xdp]`, переменные manager'а |
|
| [configuration.md](configuration.md) | Все поля `config.toml` и переменные окружения Manager |
|
||||||
| [runbook.md](runbook.md) | Ежедневная эксплуатация и типовые операции |
|
| [development.md](development.md) | Правила кода, тестов, гейты и Definition of Done |
|
||||||
|
|
||||||
## 2. Эксплуатация (how-to)
|
## 2. Эксплуатация (how-to)
|
||||||
|
|
||||||
|
|
@ -26,41 +28,63 @@
|
||||||
|
|
||||||
| Документ | О чём |
|
| Документ | О чём |
|
||||||
|----------|-------|
|
|----------|-------|
|
||||||
| [configuration.md](configuration.md) | Все поля конфига и значения по умолчанию |
|
| [configuration.md](configuration.md) | Все поля конфига, границы и значения по умолчанию |
|
||||||
| [api.md](api.md) | HTTP API manager'а: аутентификация, эндпоинты |
|
| [api.md](api.md) | HTTP API manager'а: аутентификация, эндпоинты, лимиты |
|
||||||
| [vds_compatibility.md](vds_compatibility.md) | Ограничения окружений и ядер |
|
| [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 |
|
| [minecraft-java.md](minecraft-java.md) | Minecraft-edge: Paper, PROXY protocol, закрытый backend |
|
||||||
|
|
||||||
## 5. Теория и исследования
|
## 6. Теория и исследования
|
||||||
|
|
||||||
| Раздел | О чём |
|
| Раздел | О чём |
|
||||||
|--------|-------|
|
|--------|-------|
|
||||||
| [kb/](kb/README.md) | База знаний: анатомия атак, уровни защиты, практика (двуязычная) |
|
| [kb/](kb/README.md) | База знаний: анатомия атак, уровни защиты, практика (двуязычная) |
|
||||||
| [research/](research/README.md) | Глубокие разборы: архитектура, eBPF, DDoS, Rust-производительность, конкуренты |
|
| [research/](research/README.md) | Глубокие разборы: архитектура, eBPF, DDoS, Rust-производительность, конкуренты |
|
||||||
|
|
||||||
`kb/` отвечает на вопрос «как это работает и как защищаться», `research/` — на вопрос
|
`kb/` отвечает на вопрос «как это работает и как защищаться», `research/` — на
|
||||||
«какое решение выбрать и почему». Статус проекта не живёт ни там, ни там — только в
|
вопрос «какое решение выбрать и почему». Статус проекта не живёт ни там, ни там —
|
||||||
[TODO.md](../TODO.md).
|
только в [TODO.md](../TODO.md) и [roadmap/](roadmap/README.md).
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 6. Как вести документацию
|
## 7. Как вести документацию
|
||||||
|
|
||||||
1. **Язык.** `docs/` — русский. Исключение: [docs/kb/](kb/README.md), где статьи
|
1. **Язык.** `docs/` — русский. Исключение: [docs/kb/](kb/README.md), где статьи
|
||||||
двуязычные (`## English` / `## Русский`). Комментарии в коде — английский (TODO §0.8).
|
двуязычные (`## English` / `## Русский`). Комментарии в коде — английский
|
||||||
2. **Один документ = одна задача.** How-to начинается с цели («что получится в конце»),
|
([development.md](development.md) §5).
|
||||||
содержит копируемые команды и заканчивается проверкой результата.
|
2. **Один документ = одна задача.** How-to начинается с цели («что получится в
|
||||||
3. **Reference синхронизируется с кодом в том же PR.** Меняешь поле конфига, флаг CLI
|
конце»), содержит копируемые команды и заканчивается проверкой результата.
|
||||||
или эндпоинт — правишь `configuration.md` / `api.md` там же. Расхождение = баг.
|
3. **Reference синхронизируется с кодом в том же PR.** Меняешь поле конфига, флаг
|
||||||
4. **Новый документ** кладётся в подходящую категорию (2–4) и сразу добавляется в эту
|
CLI или эндпоинт — правишь `configuration.md` / `api.md` там же. Расхождение =
|
||||||
таблицу; если он является точкой входа — ссылка добавляется и в корневой README.
|
баг.
|
||||||
5. **Не размножай папки.** Плоская структура `docs/*.md` — норма; подпапка нужна только
|
4. **Планы не растут в TODO.** Новая задача — новый файл в
|
||||||
для серии документов (`kb/`, `research/`).
|
[roadmap/](roadmap/README.md); в `TODO.md` добавляется только строка-ссылка.
|
||||||
6. **Имена файлов** — kebab-case, `.md`, без дат в имени; дата и версия — внутри документа.
|
5. **Новый документ** кладётся в подходящую категорию (1–6) и сразу добавляется в
|
||||||
7. **Никаких битых ссылок.** Перед коммитом: `grep -o '](\.\?[^)]*)' docs/*.md` и проверь,
|
эту таблицу; если он является точкой входа — ссылка добавляется и в корневой
|
||||||
что цели существуют.
|
README.
|
||||||
|
6. **Не размножай папки.** Плоская структура `docs/*.md` — норма; подпапка нужна
|
||||||
|
только для серии документов (`kb/`, `research/`, `roadmap/`).
|
||||||
|
7. **Имена файлов** — kebab-case, `.md`, без дат в имени; дата и версия — внутри
|
||||||
|
документа.
|
||||||
|
8. **Никаких битых ссылок.** Перед коммитом: `bash scripts/check_docs_links.sh`
|
||||||
|
(этот же скрипт работает в CI).
|
||||||
|
9. **Не дублируй архитектуру.** Схемы и описания слоёв живут в
|
||||||
|
[architecture.md](architecture.md); остальные документы ссылаются на него.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
*Версия: 3.0 | Ноябрь 2026*
|
||||||
|
|
|
||||||
10
docs/api.md
10
docs/api.md
|
|
@ -3,8 +3,9 @@
|
||||||
> REST API управления. Base URL: `http://MANAGER:8080`
|
> REST API управления. Base URL: `http://MANAGER:8080`
|
||||||
> Авторизация: Bearer JWT (получить через `/api/v1/auth/login`).
|
> Авторизация: Bearer JWT (получить через `/api/v1/auth/login`).
|
||||||
|
|
||||||
Реализованные маршруты — см. src/bin/rampart-manager.rs. Это полный список:
|
Реализованные маршруты — см. `src/manager/api/guard/router.rs` (единственное место
|
||||||
ничего сверх перечисленного здесь API не предоставляет.
|
сборки роутера, включая тесты). Это полный список: ничего сверх перечисленного
|
||||||
|
здесь API не предоставляет.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|
@ -142,7 +143,8 @@ Edge подписывается на Pub/Sub перед загрузкой сн
|
||||||
|
|
||||||
Честно, на текущий момент в API **нет**:
|
Честно, на текущий момент в API **нет**:
|
||||||
|
|
||||||
- drain нод через API или CLI;
|
- drain нод через API (CLI-команда `rampart-cli drain <node>` существует, но
|
||||||
|
завершается явной ошибкой «not implemented»);
|
||||||
- webhooks, metrics summary, challenge management;
|
- webhooks, metrics summary, challenge management;
|
||||||
- регистрации нод через `POST /api/v1/nodes`.
|
- регистрации нод через `POST /api/v1/nodes`.
|
||||||
|
|
||||||
|
|
@ -157,4 +159,4 @@ Edge подписывается на Pub/Sub перед загрузкой сн
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
*Версия: 2.0 | Август 2026*
|
*Версия: 2.1 | Ноябрь 2026*
|
||||||
|
|
|
||||||
212
docs/architecture.md
Normal file
212
docs/architecture.md
Normal file
|
|
@ -0,0 +1,212 @@
|
||||||
|
# Architecture — Rampart
|
||||||
|
|
||||||
|
> Текущее устройство системы: процессы, путь пакета и соединения, слои фильтрации,
|
||||||
|
> хранилища и наблюдаемость. Планы — в [roadmap/](roadmap/README.md); правила
|
||||||
|
> разработки — в [development.md](development.md); исследования и обоснования —
|
||||||
|
> в [research/](research/architecture.md).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. Назначение
|
||||||
|
|
||||||
|
Rampart отбрасывает атакующий трафик до того, как он дойдёт до сервиса. Одна
|
||||||
|
платформа защищает TCP-сервис любого типа: веб-приложение, API, игровой сервер.
|
||||||
|
Логика конкретного протокола вынесена в compile-time плагины, поэтому ядро не
|
||||||
|
знает о Minecraft или HTTP ничего.
|
||||||
|
|
||||||
|
Модель угроз: распределённый флуд соединениями (SYN/connection flood), мусорные
|
||||||
|
L7-handshake, медленные клиенты (slowloris), ботнет с ротацией адресов внутри
|
||||||
|
подсети, повторные попытки с уже забаненных адресов. Rampart — stateless-фильтр
|
||||||
|
и не заменяет firewall или WAF: он не хранит тело запроса и не анализирует
|
||||||
|
шифрованный трафик.
|
||||||
|
|
||||||
|
## 2. Процессы
|
||||||
|
|
||||||
|
| Бинарь | Роль | Порты |
|
||||||
|
|--------|------|-------|
|
||||||
|
| `rampart` | edge-нода: XDP → PoW → userspace → плагин → upstream | `bind.port` (25565), metrics `[metrics].port` (9090) |
|
||||||
|
| `rampart-manager` | REST API и инвентарь | `0.0.0.0:8080` |
|
||||||
|
| `rampart-cli` | клиент manager API (`status`, `doctor`, `blacklist`, …) | — |
|
||||||
|
| `rampart-tui` | live-дашборд по Prometheus | — |
|
||||||
|
|
||||||
|
Edge и manager — независимые процессы. Связь только через Redis (баны, инвентарь,
|
||||||
|
heartbeat); без Redis edge продолжает работать автономно.
|
||||||
|
|
||||||
|
## 3. Путь трафика edge
|
||||||
|
|
||||||
|
```
|
||||||
|
client → eth0 → [XDP/eBPF] → kernel TCP → accept → Gateway → plugin → upstream
|
||||||
|
│ │
|
||||||
|
└─ ringbuf events → autoban └─ Redis/ClickHouse
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3.1 XDP (C, `xdp/core/`)
|
||||||
|
|
||||||
|
Stateless-фильтр на входе интерфейса. Разбирает Ethernet (VLAN/QinQ), IPv4/IPv6,
|
||||||
|
L4; порт-гейт `[xdp] protected_port_start/end` отсекает нецелевой трафик до
|
||||||
|
фильтра.
|
||||||
|
|
||||||
|
| Механизм | IPv4 | IPv6 |
|
||||||
|
|----------|------|------|
|
||||||
|
| Blacklist LPM (`/32`, `/128`, префиксы) | да | да |
|
||||||
|
| Whitelist LPM | да | да |
|
||||||
|
| TCP conntrack, SYN-throttle | да | нет |
|
||||||
|
| RST-challenge (liveness proof) | да | нет |
|
||||||
|
| UDP policy: pass/drop/rate-limit | да | да |
|
||||||
|
| Prefix-статистика (`/24`, `/64`) | да | да |
|
||||||
|
| Ringbuf-события | да | нет (только счётчики) |
|
||||||
|
|
||||||
|
Карты (`xdp/core/maps.h`): `blacklist_map`, `blacklist6_map`, `whitelist_map`,
|
||||||
|
`whitelist6_map`, `connection_map`, `throttle_map`, `prefix_stats`, `stats_map`,
|
||||||
|
`events_ringbuf`, `syn_challenge`-карты. Значение бана — монотонное время
|
||||||
|
истечения (`bpf_ktime_get_ns`), просроченные записи чистит userspace-reaper.
|
||||||
|
|
||||||
|
### 3.2 Gateway (Rust, `src/engine/tunnel/gateway/`)
|
||||||
|
|
||||||
|
Порядок фильтров на одно соединение (важен для безопасности и стоимости):
|
||||||
|
|
||||||
|
1. Whitelist — доверенный адрес обходит все проверки и никогда не банится.
|
||||||
|
2. Blacklist (local + Redis).
|
||||||
|
3. Subnet tracker: запись источника для детектора подсетей.
|
||||||
|
4. Per-IP rate limit (token bucket) — до PoW, чтобы несолвенный клиент не занимал
|
||||||
|
задачу.
|
||||||
|
5. Глобальный бюджет соединений — защита от перегрузки accept-loop.
|
||||||
|
6. Per-IP лимит одновременных соединений.
|
||||||
|
7. PoW-гейт (опционально; несовместим с Minecraft).
|
||||||
|
8. Handshake плагина с таймаутом.
|
||||||
|
9. Connect к upstream, отправка preamble (например, PROXY v2), relay с idle-таймаутом.
|
||||||
|
|
||||||
|
Соединения принимает `src/engine/listener.rs`: несколько воркеров с
|
||||||
|
`SO_REUSEPORT`, backoff на `accept()` при `EMFILE`/`ENOMEM`, graceful shutdown
|
||||||
|
через `watch`-канал. Ingress PROXY v2 (`[proxy_protocol]`) принимается только от
|
||||||
|
`trusted_cidrs`; адрес из заголовка валидируется и не может быть loopback/
|
||||||
|
link-local/multicast/broadcast или адресом самого прокси.
|
||||||
|
|
||||||
|
### 3.3 Протокол-плагины (`src/protocol/`)
|
||||||
|
|
||||||
|
`ProtocolHandler` — трейт: разобрать handshake, вернуть upstream и байты,
|
||||||
|
которые нужно отправить в backend до relay. Плагины включаются feature-флагами:
|
||||||
|
|
||||||
|
- `protocol-http` — HTTP/1.1 request-head: allow/reject, лимит заголовков,
|
||||||
|
blocked paths, обязательный User-Agent.
|
||||||
|
- `protocol-minecraft` — Minecraft Java handshake/list/login, один upstream,
|
||||||
|
опциональный PROXY v2 к Paper.
|
||||||
|
|
||||||
|
Реестр (`ProtocolRegistry`) выбирает активный плагин; пустой реестр — fail-fast
|
||||||
|
при старте с подсказкой про фичи.
|
||||||
|
|
||||||
|
### 3.4 Detection и реакция (`src/traffic/`, `src/engine/subnet/`)
|
||||||
|
|
||||||
|
- `AttackDetector` — EWMA baseline по pps/cps, состояния normal → suspicious →
|
||||||
|
under_attack с гистерезисом.
|
||||||
|
- `IpReputation` — score источника; хорошие соединения повышают, плохие понижают.
|
||||||
|
- `SubnetDetector` — превышение порога префиксом при адресах под per-IP лимитом;
|
||||||
|
лестница вердиктов: strict limit → challenge → block префикса (через `ban_cidr`,
|
||||||
|
не слепой hard-ban).
|
||||||
|
- `TrafficHook` — единая точка авто-бана; сверяется с `trusted_cidrs` и
|
||||||
|
подавляет бан доверенной сети.
|
||||||
|
- `AlertDispatcher` — алерт только на переход состояния, опционально webhook.
|
||||||
|
|
||||||
|
## 4. Manager API
|
||||||
|
|
||||||
|
`src/manager/` — axum-роутер, JWT (HS256, audience, `JWT_SECRET` ≥ 32 байт),
|
||||||
|
per-IP лимиты (5 login/мин, 30 мутаций/мин), тело ≤ 8 КиБ, таймаут 10 с,
|
||||||
|
CORS только по явному `CORS_ORIGIN`.
|
||||||
|
|
||||||
|
| Маршрут | Доступ | Источник |
|
||||||
|
|---------|--------|----------|
|
||||||
|
| `GET /api/v1/health` | публичный | процесс |
|
||||||
|
| `POST /api/v1/auth/login` | публичный | `API_PASSWORD` |
|
||||||
|
| `GET /api/v1/servers` | JWT | Redis `rampart:servers:*` |
|
||||||
|
| `GET/POST/DELETE /api/v1/blacklist` | JWT | Redis set + metadata hash + pub/sub |
|
||||||
|
| `GET /api/v1/nodes` | JWT | Redis `rampart:nodes:*` (heartbeat) |
|
||||||
|
|
||||||
|
Мутации публикуют событие в `rampart:blacklist:events`; edge подписывается до
|
||||||
|
загрузки снимка, поэтому события во время загрузки не теряются. Полный контракт —
|
||||||
|
[api.md](api.md).
|
||||||
|
|
||||||
|
## 5. Хранилища
|
||||||
|
|
||||||
|
| Хранилище | Что хранит | Без него |
|
||||||
|
|-----------|------------|----------|
|
||||||
|
| Redis | blacklist set + metadata, pub/sub событий, инвентарь нод и серверов | edge автономен, кросс-нодовые баны не работают |
|
||||||
|
| ClickHouse | события атак и соединений (`rampart_events`) | запись событий выключена |
|
||||||
|
| Prometheus | метрики edge | дашборд/TUI без данных |
|
||||||
|
|
||||||
|
Redis-клиент работает через `ConnectionManager` с таймаутами и реконнектом;
|
||||||
|
снимок банов восстанавливается после переподключения с оставшимся TTL.
|
||||||
|
|
||||||
|
## 6. Наблюдаемость
|
||||||
|
|
||||||
|
`GET /metrics` на edge (Prometheus text format).
|
||||||
|
|
||||||
|
| Метрика | Тип | Смысл |
|
||||||
|
|---------|-----|-------|
|
||||||
|
| `rampart_connections_total{result}` | counter | allowed / blocked / overloaded |
|
||||||
|
| `rampart_rate_limit_hits{action}` | counter | срабатывания лимитов |
|
||||||
|
| `rampart_pow_challenges_total{result}` | counter | выдан/решён/отклонён |
|
||||||
|
| `rampart_pow_current_difficulty` | gauge | текущая сложность |
|
||||||
|
| `rampart_attack_status` | gauge | 0 normal, 1 suspicious, 2 under attack |
|
||||||
|
| `rampart_subnet_verdicts_total{verdict}` | counter | вердикты детектора подсетей |
|
||||||
|
| `rampart_auto_bans_total{reason}` | counter | авто-баны userspace |
|
||||||
|
| `rampart_intel_cps` | gauge | новые соединения/с в окне |
|
||||||
|
| `rampart_intel_rate_limit_drops_total` | counter | дропы по репутации |
|
||||||
|
| `rampart_intel_alerts_total` | counter | алерты на переход состояния |
|
||||||
|
| `rampart_xdp_*` | gauge | счётчики `stats_map`: `total`, `tcp`, `udp`, `whitelist`, `blacklist`, `syn_throttle`, `rate_limit`, `passed`, `dropped`, `challenge_sent`, `challenge_verified`, `challenge_failed`, `fragment_bypass` |
|
||||||
|
| `rampart_xdp_autobans_total` | counter | авто-баны из ringbuf |
|
||||||
|
| `rampart_clickhouse_dropped_total` | counter | потерянные события ClickHouse |
|
||||||
|
|
||||||
|
TUI (`src/tui/`) читает те же метрики через Prometheus HTTP.
|
||||||
|
|
||||||
|
## 7. Конфигурация
|
||||||
|
|
||||||
|
Единый `config.toml` для edge; manager настраивается переменными окружения.
|
||||||
|
Все секции опциональны, значения по умолчанию — в `src/config/sections/`;
|
||||||
|
семантическая валидация выполняется до bind. Полная таблица полей, границ и
|
||||||
|
дефолтов — [configuration.md](configuration.md).
|
||||||
|
|
||||||
|
Ключевые инварианты:
|
||||||
|
|
||||||
|
- `proxy_protocol.ingress_enabled` требует непустой `trusted_cidrs` и
|
||||||
|
`protocol.minecraft`.
|
||||||
|
- `xdp.syn_challenge_enabled` требует свой `challenge_secret_hex` (placeholder
|
||||||
|
отклоняется).
|
||||||
|
- `backend.upstreams` не пуст и валиден; для Minecraft — ровно один upstream.
|
||||||
|
- `ban.ban_duration_secs` ∈ `1..=31_536_000`, `pow.difficulty` ∈ `1..=10`,
|
||||||
|
`workers.count ≥ 1`.
|
||||||
|
- `limits.relay_idle_timeout_secs` ∈ `1..=86_400`.
|
||||||
|
|
||||||
|
## 8. Карта модулей
|
||||||
|
|
||||||
|
```
|
||||||
|
src/
|
||||||
|
├── app/ сборка рантайма, фоновые задачи, graceful shutdown
|
||||||
|
├── bin/ тонкие точки входа (логика в lib)
|
||||||
|
├── cli/ команды rampart-cli
|
||||||
|
├── config/ Config + sections/ + trusted CIDR
|
||||||
|
├── engine/ listener, tunnel/gateway|proxy, challenge, subnet
|
||||||
|
├── filter/ blacklist, rate_limit, connection_limit, geo
|
||||||
|
├── manager/ axum API, auth, sync/heartbeat
|
||||||
|
├── metrics.rs Prometheus registry и scrape endpoint
|
||||||
|
├── protocol/ трейт ProtocolHandler, реестр, http, minecraft
|
||||||
|
├── store/ redis (+sync), clickhouse
|
||||||
|
├── traffic/ hook, prefix, intel (ewma/detector/reputation), profile
|
||||||
|
├── tui/ ratatui-дашборд
|
||||||
|
└── xdp/ загрузчик, globals, probe/diagnostics, noop
|
||||||
|
xdp/
|
||||||
|
├── core/ universal_filter.c + maps/stats/config/common/prefix/syn_challenge
|
||||||
|
└── hooks/ hook_api.h — контракт BPF-хуков
|
||||||
|
```
|
||||||
|
|
||||||
|
## 9. Ограничения и деградация
|
||||||
|
|
||||||
|
- XDP выключен или недоступен → защита работает в userspace; логируется честный
|
||||||
|
режим (native/generic/none).
|
||||||
|
- Redis недоступен → edge автономен, manager отдаёт `503` на inventory/blacklist.
|
||||||
|
- ClickHouse недоступен → события теряются, защита работает; счётчик дропов растёт.
|
||||||
|
- Перегрузка → глобальный бюджет отклоняет соединения (`overloaded`), а не
|
||||||
|
копит задачи в памяти.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
*Версия: 1.0 | Ноябрь 2026*
|
||||||
|
|
@ -1,9 +1,19 @@
|
||||||
# Configuration - Rampart
|
# Configuration — Rampart
|
||||||
|
|
||||||
> Единый конфиг edge-ноды (`config.toml`) и переменные окружения Manager.
|
> Единый конфиг 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
|
||||||
# Корневые поля должны стоять до первой TOML-секции.
|
# Корневые поля должны стоять до первой TOML-секции.
|
||||||
|
|
@ -14,88 +24,203 @@ address = "0.0.0.0"
|
||||||
port = 25565
|
port = 25565
|
||||||
|
|
||||||
[backend]
|
[backend]
|
||||||
# Список TCP-бэкендов (addr:port). Для Minecraft нужен ровно один backend.
|
|
||||||
upstreams = ["127.0.0.1:25566"]
|
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]
|
[protocol.minecraft]
|
||||||
enabled = true
|
enabled = true
|
||||||
max_frame_bytes = 8192
|
max_frame_bytes = 8192
|
||||||
timeout_secs = 5
|
timeout_secs = 5
|
||||||
send_proxy_protocol = false
|
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]
|
[logging]
|
||||||
level = "info" # trace, debug, info, warn, error
|
level = "info"
|
||||||
format = "text" # text или json
|
format = "text"
|
||||||
|
|
||||||
[metrics]
|
[metrics]
|
||||||
enabled = true
|
enabled = true
|
||||||
port = 9090
|
port = 9090
|
||||||
|
|
||||||
[pow]
|
[store]
|
||||||
enabled = false # PoW challenge, OFF по умолчанию
|
redis_url = ""
|
||||||
difficulty = 4
|
blacklist_cache_ttl_secs = 300
|
||||||
|
clickhouse_url = ""
|
||||||
# Входящий PROXY v2 от известного TCP DDoS-прокси; включай только если
|
|
||||||
# прокси действительно отправляет этот заголовок.
|
|
||||||
[proxy_protocol]
|
|
||||||
ingress_enabled = false
|
|
||||||
trusted_cidrs = []
|
|
||||||
ingress_timeout_ms = 750
|
|
||||||
max_header_bytes = 512
|
|
||||||
|
|
||||||
```
|
```
|
||||||
|
|
||||||
Этот пример выбирает 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` | — | Пусто = запись событий выключена |
|
||||||
|
|
||||||
Все секции опциональны — при отсутствии используются дефолты из таблицы выше.
|
`[protocol.http]` существует только при сборке с `protocol-http`,
|
||||||
Для ingress PROXY v2 укажи сети именно прокси в `trusted_cidrs`; включение без
|
`[protocol.minecraft]` — только с `protocol-minecraft`; секция без
|
||||||
доверенной сети отклоняется при чтении конфига.
|
соответствующей фичи игнорируется. Для HTTP удали `[protocol.minecraft]`.
|
||||||
|
|
||||||
`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.
|
|
||||||
|
|
||||||
## 2. Manager (переменные окружения)
|
## 2. Manager (переменные окружения)
|
||||||
|
|
||||||
|
|
@ -106,75 +231,40 @@ unspecified/loopback/link-local/multicast/broadcast адресом отклон
|
||||||
| `JWT_AUDIENCE` | нет | `rampart` | Audience JWT |
|
| `JWT_AUDIENCE` | нет | `rampart` | Audience JWT |
|
||||||
| `JWT_EXPIRATION_SECS` | нет | `86400` | Время жизни токена |
|
| `JWT_EXPIRATION_SECS` | нет | `86400` | Время жизни токена |
|
||||||
| `API_PASSWORD` | да | — | Пароль для `/api/v1/auth/login`, минимум 16 символов; `changeme` запрещён |
|
| `API_PASSWORD` | да | — | Пароль для `/api/v1/auth/login`, минимум 16 символов; `changeme` запрещён |
|
||||||
| `CORS_ORIGIN` | нет | — (CORS выключен) | `*` — разрешить все источники; список через запятую; пусто/не задано — запретить cross-origin |
|
| `CORS_ORIGIN` | нет | — | `*` — разрешить всё; список origin'ов через запятую; пусто — cross-origin запрещён |
|
||||||
| `MANAGER_TRUSTED_PROXIES` | нет | — (никому не доверяем) | Сети reverse-прокси через запятую (`10.0.0.0/8,2001:db8::/32`). `X-Forwarded-For` учитывается только для запросов, пришедших с адреса из этих сетей; иначе клиентом считается TCP peer. Пусто/не задано — заголовок игнорируется полностью. Опечатка или пустая запись в списке не даёт менеджеру стартовать |
|
| `MANAGER_TRUSTED_PROXIES` | нет | — | Сети reverse-прокси через запятую. `X-Forwarded-For` учитывается только для запросов из этих сетей; опечатка/пустая запись → отказ старта |
|
||||||
|
|
||||||
Manager всегда слушает `0.0.0.0:8080`.
|
Manager всегда слушает `0.0.0.0:8080`.
|
||||||
|
|
||||||
## 3. Feature flags сборки (Cargo.toml)
|
## 3. Feature flags сборки
|
||||||
|
|
||||||
| Feature | По умолчанию | Что включает |
|
| Feature | По умолчанию | Что включает |
|
||||||
|---------|--------------|--------------|
|
|---------|--------------|--------------|
|
||||||
| `store-redis` | ✅ | Redis-клиент и синхронизация блэклиста |
|
| `store-redis` | ✅ | Redis-клиент и синхронизация blacklist |
|
||||||
| `geoip` | ❌ | GeoIP lookup (maxminddb) |
|
| `geoip` | ❌ | GeoIP lookup (maxminddb; реализация — roadmap v0.5) |
|
||||||
| `xdp` | ❌ | Загрузка XDP-программы через libbpf-rs |
|
| `xdp` | ❌ | Загрузка XDP-программы через libbpf-rs |
|
||||||
| `io-uring` | ❌ | splice/io_uring I/O |
|
| `io-uring` | ❌ | splice/io_uring I/O (реализация — roadmap v0.6) |
|
||||||
| `protocol-http` | ❌ | HTTP/1.1 handler; включай только для HTTP upstream |
|
| `protocol-http` | ❌ | HTTP/1.1 handler |
|
||||||
| `protocol-minecraft` | ❌ | Minecraft Java TCP handshake и проксирование |
|
| `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 программа
|
## 4. BPF/XDP программа
|
||||||
|
|
||||||
Исходник: `xdp/core/universal_filter.c`. Smoke-check компиляции:
|
Исходник — `xdp/core/universal_filter.c`. Smoke-check компиляции:
|
||||||
|
|
||||||
```bash
|
```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`):
|
`-I` с multiarch нужен, потому что `-target bpf` не ищет
|
||||||
|
`/usr/include/<triple>` по умолчанию. Полный прогон на реальном ядре —
|
||||||
| Поле | По умолчанию | Что делает |
|
`scripts/xdp_ci.sh` (см. [testing.md](testing.md)).
|
||||||
|------|--------------|------------|
|
|
||||||
| `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`.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
*Версия: 2.1 | Октябрь 2026*
|
*Версия: 3.0 | Ноябрь 2026*
|
||||||
|
|
|
||||||
|
|
@ -145,4 +145,4 @@ redis_url = "redis://:PASSWORD@redis:6379/0"
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
*Версия: 2.1 | Октябрь 2026*
|
*Версия: 3.0 | Ноябрь 2026*
|
||||||
|
|
|
||||||
116
docs/development.md
Normal file
116
docs/development.md
Normal file
|
|
@ -0,0 +1,116 @@
|
||||||
|
# Development — правила разработки Rampart
|
||||||
|
|
||||||
|
> Как мы пишем код, тесты и коммиты. Планы задач — в [roadmap/](roadmap/README.md),
|
||||||
|
> устройство системы — в [architecture.md](architecture.md).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. Принципы
|
||||||
|
|
||||||
|
**KISS → DRY → SOLID → YAGNI.**
|
||||||
|
|
||||||
|
- Не добавляй абстракцию до третьего повторения.
|
||||||
|
- Повтор > 2 раз выноси, но лучше копипаста, чем неправильная абстракция.
|
||||||
|
- S: один файл = одна ответственность. O: расширение через трейты (`ProtocolHandler`,
|
||||||
|
`Filter`). I: маленькие трейты вместо God-trait. D: core зависит от трейтов, не от
|
||||||
|
Redis/ClickHouse напрямую.
|
||||||
|
- Не пиши BGP до v0.6, WASM-плагины до стабилизации compile-time API. Feature flag
|
||||||
|
только для готовой фичи.
|
||||||
|
|
||||||
|
## 2. Ограничения размера
|
||||||
|
|
||||||
|
- **Функция ≤ 60 строк, файл ≤ 250 строк, ≤ 4 `.rs`-файлов на папку.**
|
||||||
|
- Больше — декомпозиция по доменам с реэкспортами в `mod.rs`.
|
||||||
|
- Гейт: `scripts/check_module_size.sh` + ratchet-базлайн `.module_size_baseline`
|
||||||
|
(легаси — WARN, новое нарушение — FAIL; после рефакторинга
|
||||||
|
`--update-baseline`).
|
||||||
|
- `tests/` вне лимита: Cargo требует один файл = один бинарь.
|
||||||
|
|
||||||
|
## 3. Rust-правила
|
||||||
|
|
||||||
|
1. `unwrap()` — только в `main()` и тестах; в коде — `?` или явная обработка.
|
||||||
|
2. `unsafe` — только в `xdp/`, обязателен комментарий `// SAFETY:` с предусловиями.
|
||||||
|
3. `clone()` осознанно: горячий путь профилируется, а не «на всякий случай».
|
||||||
|
4. Блокирующие операции — в `spawn_blocking`.
|
||||||
|
5. Логи — `tracing::{info,debug,warn,error}`; `print_*` запрещён clippy-линтом.
|
||||||
|
6. Метрика регистрируется один раз при старте, инкремент — в горячем пути.
|
||||||
|
7. `panic`, `dbg!`, `exit` запрещены линтами; выход процесса — только в `main`.
|
||||||
|
|
||||||
|
## 4. Тесты
|
||||||
|
|
||||||
|
- Тесты живут в `tests/`, не в `src/`: `#[cfg(test)]`-модулей в коде нет.
|
||||||
|
- Хелпер, нужный тесту, становится `pub` только при наличии реального потребителя.
|
||||||
|
- На новый слой — интеграционный тест на слой (config parse, filter logic,
|
||||||
|
registry fail-fast).
|
||||||
|
- Для бага сначала красный тест, потом фикс.
|
||||||
|
- Feature-gated код обязан собираться и тестироваться в CI
|
||||||
|
(`--all-features` и `--no-default-features`).
|
||||||
|
|
||||||
|
## 5. Комментарии
|
||||||
|
|
||||||
|
- **Все комментарии и doc-комментарии — на английском.** Русский остаётся в
|
||||||
|
`docs/`, README, TODO, логах (`tracing::*!`) и сообщениях CLI/ошибок.
|
||||||
|
- Rustdoc-стиль: `//!` для модуля (что он владеет), `///` для элемента; секции
|
||||||
|
`# Errors` / `# Panics` / `# Safety` сохраняются.
|
||||||
|
- C: `/** ... */` над функцией/структурой/картой/глобалом, с `@param`/`@return`,
|
||||||
|
когда они есть.
|
||||||
|
- Без эмодзи, ASCII-баннеров и декоративных разделителей.
|
||||||
|
- Инлайн-комментарий объясняет **почему**, а не пересказывает код.
|
||||||
|
- Правишь файл — переводи комментарии в нём целиком; не трогай строковые
|
||||||
|
литералы, идентификаторы и логику.
|
||||||
|
|
||||||
|
## 6. Рабочий процесс
|
||||||
|
|
||||||
|
1. Новая функциональность → сначала дизайн (что и зачем, альтернативы), потом план.
|
||||||
|
2. Баг → сначала корневая причина, потом фикс; симптомные заплатки запрещены.
|
||||||
|
3. Любая правка кода → тест (сначала падающий) → реализация.
|
||||||
|
4. Перед «готово» — свежий прогон гейтов и вывод, а не воспоминания.
|
||||||
|
|
||||||
|
## 7. Гейты
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cargo fmt --all --check
|
||||||
|
cargo clippy --all-targets --all-features -- -D warnings
|
||||||
|
cargo test --all-features
|
||||||
|
cargo test --no-default-features --features protocol-http
|
||||||
|
cargo deny check
|
||||||
|
bash scripts/check_module_size.sh
|
||||||
|
bash scripts/check_default_secrets.sh
|
||||||
|
bash scripts/check_docs_links.sh
|
||||||
|
```
|
||||||
|
|
||||||
|
Плюс `make ebpf` (clang BPF) и `make fuzz` (nightly, 60 с на цель).
|
||||||
|
XDP-путь на реальном ядре — `scripts/xdp_ci.sh` (задача v0.4).
|
||||||
|
|
||||||
|
## 8. Definition of Done
|
||||||
|
|
||||||
|
```
|
||||||
|
☐ cargo check / cargo test проходят
|
||||||
|
☐ clippy --all-targets --all-features -- -D warnings — 0 warnings
|
||||||
|
☐ cargo fmt --check проходит
|
||||||
|
☐ ни один файл > 250 строк; ни в одной папке src/ > 4 .rs-файлов
|
||||||
|
☐ тесты покрывают happy path + 2+ error case
|
||||||
|
☐ нет мёртвого кода: pub без вызовов, конфиг-поле без потребителя, метрика без writer
|
||||||
|
☐ нет дефолтных секретов
|
||||||
|
☐ README/docs соответствуют коду; план задачи обновлён
|
||||||
|
☐ CHANGELOG обновлён
|
||||||
|
☐ CI зелёный
|
||||||
|
```
|
||||||
|
|
||||||
|
## 9. Anti-patterns
|
||||||
|
|
||||||
|
```
|
||||||
|
❌ Тесты после кода.
|
||||||
|
❌ Файл > 250 строк или > 4 .rs в папке.
|
||||||
|
❌ TODO в коде без ссылки на план.
|
||||||
|
❌ Мёртвый код: pub без вызовов, конфиг-поле без потребителя, метрика без writer.
|
||||||
|
❌ «Бумажный слой»: фича описана, но не вызывается.
|
||||||
|
❌ Дефолтный секрет.
|
||||||
|
❌ Парсер за «один read» — TCP-поток приходит фрагментами.
|
||||||
|
❌ Feature flag, который не собирается в CI.
|
||||||
|
❌ Документ, описывающий несуществующую команду.
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
*Версия: 1.0 | Ноябрь 2026*
|
||||||
|
|
@ -29,11 +29,11 @@ Edge нода упала:
|
||||||
|
|
||||||
### Симптомы
|
### Симптомы
|
||||||
- Edge перестал синхронизировать блэклист
|
- Edge перестал синхронизировать блэклист
|
||||||
- Manager API отдаёт пустые списки nodes/servers/blacklist
|
- Manager API отвечает `503` на `/nodes`, `/servers` и `/blacklist`
|
||||||
|
|
||||||
### Влияние
|
### Влияние
|
||||||
- **Edge:** работает с локальным кэшем; новые баны не распространяются между нодами.
|
- **Edge:** работает с локальным кэшем; новые баны не распространяются между нодами.
|
||||||
- **Manager:** данные из Redis недоступны.
|
- **Manager:** Redis-зависимые эндпоинты отвечают `503`.
|
||||||
|
|
||||||
### Действия
|
### Действия
|
||||||
|
|
||||||
|
|
@ -92,7 +92,7 @@ journalctl -u rampart -n 50 --no-pager
|
||||||
dmesg | grep -i "oom\|rampart" # OOM kill?
|
dmesg | grep -i "oom\|rampart" # OOM kill?
|
||||||
systemctl restart rampart
|
systemctl restart rampart
|
||||||
|
|
||||||
# Не стартует — проверь конфиг и логи (см. runbook.md §2)
|
# Не стартует — проверь конфиг и логи (см. runbook.md §3)
|
||||||
```
|
```
|
||||||
|
|
||||||
### Предотвращение
|
### Предотвращение
|
||||||
|
|
@ -123,8 +123,13 @@ df -h /var/lib/clickhouse # диск полон?
|
||||||
# 1. Поднять Manager на новой VDS
|
# 1. Поднять Manager на новой VDS
|
||||||
docker compose up -d redis && cargo run --release --bin rampart-manager
|
docker compose up -d redis && cargo run --release --bin rampart-manager
|
||||||
|
|
||||||
# 2. Восстановить Redis из бэкапа
|
# 2. Восстановить Redis из RDB-бэкапа. `redis-cli --pipe` для этого не подходит:
|
||||||
redis-cli --pipe < /backup/rampart-redis-$(date +%Y-%m-%d).rdb
|
# он принимает 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 ноды переподключатся автоматически
|
# 3. Edge ноды переподключатся автоматически
|
||||||
|
|
||||||
|
|
@ -146,4 +151,8 @@ ss -s | grep TCP
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
*Версия: 2.0 | Август 2026*
|
Готовый список остальных проверок — в [troubleshooting.md](troubleshooting.md) и
|
||||||
|
[runbook.md](runbook.md); план развития диагностики — в
|
||||||
|
[roadmap/v0.4-startup-diagnostics.md](roadmap/v0.4-startup-diagnostics.md).
|
||||||
|
|
||||||
|
*Версия: 3.0 | Ноябрь 2026*
|
||||||
|
|
|
||||||
|
|
@ -3,7 +3,8 @@
|
||||||
> Это исследовательская документация. Здесь живут глубокие разборы технологий,
|
> Это исследовательская документация. Здесь живут глубокие разборы технологий,
|
||||||
> эксперименты и идеи для версий v0.4+.
|
> эксперименты и идеи для версий v0.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 |
|
| [ddos.md](./ddos.md) | Векторы атак L3/L4/L7, методы защиты, AI-боты | v0.1 |
|
||||||
| [ebpf.md](./ebpf.md) | XDP/eBPF фильтр, BPF maps, ringbuf, verifier | v0.4 |
|
| [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 |
|
| [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
|
→ architecture.md + ddos.md
|
||||||
Хочу добавить защиту от ботов
|
Хочу добавить защиту от ботов
|
||||||
→ anti-bot.md
|
→ anti-bot.md
|
||||||
|
|
|
||||||
|
|
@ -1,7 +1,8 @@
|
||||||
# Architecture — Rampart
|
# Architecture — Rampart (design rationale, v0.3)
|
||||||
|
|
||||||
> Relevant for: v0.3+ (universal redesign)
|
> 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
|
> Language: English (research notes) — see [RU summary](#russian-summary) at the end
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
|
||||||
79
docs/roadmap/README.md
Normal file
79
docs/roadmap/README.md
Normal file
|
|
@ -0,0 +1,79 @@
|
||||||
|
# Roadmap — Rampart
|
||||||
|
|
||||||
|
> Индекс планов по версиям. `TODO.md` в корне — только статус и ссылки сюда;
|
||||||
|
> детали каждой задачи живут в отдельном файле этой папки.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. Правила
|
||||||
|
|
||||||
|
1. **Одна задача = один файл.** Имя: `<version>-<topic>.md`, kebab-case, без дат.
|
||||||
|
2. **Файл создаётся, когда задача попадает в план**, а не когда её начинают.
|
||||||
|
Пока задача не начата, достаточно цели, объёма и критериев приёмки.
|
||||||
|
3. **Статус меняется в двух местах одновременно:** в шапке файла задачи и в
|
||||||
|
таблице `TODO.md`. Расхождение = баг документации.
|
||||||
|
4. **Завершённая задача** получает `Status: done`, ссылку на коммит(ы) и остаётся
|
||||||
|
в папке до релиза; после релиза её содержимое переносится в
|
||||||
|
[CHANGELOG.md](../../CHANGELOG.md), а файл удаляется.
|
||||||
|
5. **Не плоди версии.** Если задача не влезает в текущий milestone, она едет в
|
||||||
|
`icebox-*.md`, а не в «v0.7».
|
||||||
|
6. **Планы не врут.** Команды и пути в плане проверяются по коду в том же PR.
|
||||||
|
|
||||||
|
## 2. Статусы
|
||||||
|
|
||||||
|
| Статус | Значение |
|
||||||
|
|--------|----------|
|
||||||
|
| `idea` | сформулирована, не оценена |
|
||||||
|
| `planned` | есть цель, объём и критерии приёмки, можно брать |
|
||||||
|
| `design` | идёт обсуждение дизайна (brainstorming) |
|
||||||
|
| `ready` | дизайн утверждён, есть пошаговый план |
|
||||||
|
| `in-progress` | реализуется |
|
||||||
|
| `blocked` | ждёт внешнего решения или зависимости |
|
||||||
|
| `done` | готова, влита, отражена в CHANGELOG |
|
||||||
|
| `dropped` | решено не делать; причина в файле |
|
||||||
|
|
||||||
|
## 3. Milestones
|
||||||
|
|
||||||
|
| Версия | Тема | Критерий выхода |
|
||||||
|
|--------|------|-----------------|
|
||||||
|
| v0.4 | Надёжность и воспроизводимость | XDP проверяется в CI, старт даёт честный вердикт об окружении, нет self-lockout |
|
||||||
|
| v0.5 | Продуктовые фичи | RST-challenge доведён до GA, внешние списки и API пригодны для интеграций, GeoIP/ASN, gRPC |
|
||||||
|
| v0.6 | Исследования | решения из backlog с доказанной пользой; каждая фича начинается с бенчмарка/прототипа |
|
||||||
|
| icebox | Отложено | без даты; берётся только при явном запросе |
|
||||||
|
|
||||||
|
## 4. v0.4 — надёжность
|
||||||
|
|
||||||
|
| Задача | Приоритет | Статус | План |
|
||||||
|
|--------|-----------|--------|------|
|
||||||
|
| XDP netns+veth harness в CI | P0 | planned | [v0.4-xdp-ci-harness.md](v0.4-xdp-ci-harness.md) |
|
||||||
|
| Startup-диагностика окружения | P1 | planned | [v0.4-startup-diagnostics.md](v0.4-startup-diagnostics.md) |
|
||||||
|
| Anti-lockout и баны по порту | P1 | planned | [v0.4-anti-lockout.md](v0.4-anti-lockout.md) |
|
||||||
|
|
||||||
|
## 5. v0.5 — продуктовые фичи
|
||||||
|
|
||||||
|
| Задача | Приоритет | Статус | План |
|
||||||
|
|--------|-----------|--------|------|
|
||||||
|
| RST-challenge: довести до GA | P0 | planned | [v0.5-rst-challenge-ga.md](v0.5-rst-challenge-ga.md) |
|
||||||
|
| Pinned maps + OpenAPI | P1 | idea | [v0.5-pinned-maps-openapi.md](v0.5-pinned-maps-openapi.md) |
|
||||||
|
| GeoIP/ASN reputation | P1 | idea | [v0.5-geoip-asn.md](v0.5-geoip-asn.md) |
|
||||||
|
| gRPC protocol plugin | P2 | idea | [v0.5-grpc-plugin.md](v0.5-grpc-plugin.md) |
|
||||||
|
|
||||||
|
## 6. v0.6 — исследования
|
||||||
|
|
||||||
|
| Задача | Приоритет | Статус | План |
|
||||||
|
|--------|-----------|--------|------|
|
||||||
|
| HTTP поверх XDP (BPF hook) | P1 | idea | [v0.6-http-over-xdp.md](v0.6-http-over-xdp.md) |
|
||||||
|
| Bloom filter для blacklist | P3 | idea | [v0.6-bloom-filter.md](v0.6-bloom-filter.md) |
|
||||||
|
| io_uring runtime | P3 | idea | [v0.6-io-uring.md](v0.6-io-uring.md) |
|
||||||
|
| ML anomaly detection | P3 | idea | [v0.6-ml-anomaly.md](v0.6-ml-anomaly.md) |
|
||||||
|
| BGP Anycast | P3 | idea | [v0.6-bgp-anycast.md](v0.6-bgp-anycast.md) |
|
||||||
|
|
||||||
|
## 7. Icebox
|
||||||
|
|
||||||
|
| Задача | Почему отложена | План |
|
||||||
|
|--------|-----------------|------|
|
||||||
|
| Minecraft Velocity forwarding | нужен только если MC-сегмент остаётся целевым | [icebox-minecraft-velocity.md](icebox-minecraft-velocity.md) |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
*Версия: 1.0 | Ноябрь 2026*
|
||||||
32
docs/roadmap/icebox-minecraft-velocity.md
Normal file
32
docs/roadmap/icebox-minecraft-velocity.md
Normal file
|
|
@ -0,0 +1,32 @@
|
||||||
|
# Icebox — Minecraft Velocity forwarding
|
||||||
|
|
||||||
|
| | |
|
||||||
|
|---|---|
|
||||||
|
| Milestone | icebox |
|
||||||
|
| Status | dropped |
|
||||||
|
| Priority | — |
|
||||||
|
| Depends on | решение о приоритете MC-сегмента |
|
||||||
|
|
||||||
|
## Цель
|
||||||
|
|
||||||
|
Поддержка Velocity modern forwarding в `protocol-minecraft`, чтобы edge мог
|
||||||
|
работать перед Velocity, а не только перед Paper.
|
||||||
|
|
||||||
|
## Почему отложено
|
||||||
|
|
||||||
|
v0.3 сознательно ушёл от Minecraft-специфичности к универсальной платформе.
|
||||||
|
Функция нужна только если MC-сегмент остаётся целевым; при этом современный
|
||||||
|
forwarding требует HMAC-секрета и меняет модель доверия между edge и прокси.
|
||||||
|
|
||||||
|
## Что нужно, если браться
|
||||||
|
|
||||||
|
- Разбор `login_start` с forwarding-полями и проверка HMAC.
|
||||||
|
- Конфиг с секретом (fail-fast, без дефолта) и ротацией.
|
||||||
|
- Игровые netns smoke-тесты и нагрузочная проверка (сейчас есть только
|
||||||
|
TCP-handshake тесты).
|
||||||
|
- Документация: схема edge → Velocity → Paper, кто кому доверяет.
|
||||||
|
|
||||||
|
## Критерии возврата из icebox
|
||||||
|
|
||||||
|
Явный запрос пользователя + подтверждение, что MC-трафик — приоритетнее v0.5/v0.6
|
||||||
|
задач.
|
||||||
56
docs/roadmap/v0.4-anti-lockout.md
Normal file
56
docs/roadmap/v0.4-anti-lockout.md
Normal file
|
|
@ -0,0 +1,56 @@
|
||||||
|
# v0.4 — Anti-lockout и баны по порту
|
||||||
|
|
||||||
|
| | |
|
||||||
|
|---|---|
|
||||||
|
| Milestone | v0.4 |
|
||||||
|
| Status | planned |
|
||||||
|
| Priority | P1 |
|
||||||
|
| Depends on | — |
|
||||||
|
|
||||||
|
## Цель
|
||||||
|
|
||||||
|
Админ не может заблокировать сам себя, а бан применяется к конкретному
|
||||||
|
защищаемому порту, когда это возможно, вместо всего IP.
|
||||||
|
|
||||||
|
## Зачем
|
||||||
|
|
||||||
|
Слепой `XDP_DROP` по IP отрезает SSH и мониторинг вместе с атакой — это известная
|
||||||
|
проблема crab-shield и типовая причина отказов от XDP-фильтров. `whitelist` уже
|
||||||
|
есть и обходит фильтры, но он не защищает от ошибки в конфиге или от бана
|
||||||
|
динамически добавленного админа.
|
||||||
|
|
||||||
|
## Scope
|
||||||
|
|
||||||
|
- Защита от самоблокировки: при старте проверять, что текущие SSH-сессии и
|
||||||
|
админские сети не попадут под blacklist/ban; предупреждать и (по флагу)
|
||||||
|
добавлять их в whitelist.
|
||||||
|
- Per-port баны в userspace и, где позволяет формат, в XDP (сейчас ключ бана —
|
||||||
|
только IP/CIDR).
|
||||||
|
- Документированная процедура восстановления, если нода всё-таки заблокирована.
|
||||||
|
|
||||||
|
## Non-goals
|
||||||
|
|
||||||
|
- Полный port-knocking.
|
||||||
|
- Замена firewall: Rampart остаётся stateless-фильтром, а не заменой nftables.
|
||||||
|
|
||||||
|
## Approach
|
||||||
|
|
||||||
|
1. Сначала — дешёвая часть: startup-проверка `ss -tnp`/`/proc/net/tcp` на активные
|
||||||
|
SSH-сессии и предупреждение, если адрес не в whitelist.
|
||||||
|
2. Per-port бан: расширить внутренний тип бана (`IpOrCidr` + `Option<u16>`),
|
||||||
|
XDP-путь — только если ABI карты допускает без удвоения памяти; иначе
|
||||||
|
оставить userspace-путь и зафиксировать это в документации.
|
||||||
|
3. Тесты: `tests/connection_limits.rs`/`tests/filter_logic.rs` + новый тест на
|
||||||
|
сериализацию ключа бана.
|
||||||
|
|
||||||
|
## Критерии приёмки
|
||||||
|
|
||||||
|
- [ ] Edge при старте пишет `WARN`, если SSH-клиент не в whitelist.
|
||||||
|
- [ ] Бан по порту не блокирует остальные порты того же IP.
|
||||||
|
- [ ] Recovery-процедура проверена в netns и описана в runbook.
|
||||||
|
- [ ] Нет изменений ABI XDP без теста в `tests/xdp_ban_keys.rs`.
|
||||||
|
|
||||||
|
## Верификация
|
||||||
|
|
||||||
|
netns-стенд: забаненный источник теряет доступ к 25565, но сохраняет SSH-порт;
|
||||||
|
runbook-процедура воспроизводится с нуля.
|
||||||
60
docs/roadmap/v0.4-startup-diagnostics.md
Normal file
60
docs/roadmap/v0.4-startup-diagnostics.md
Normal file
|
|
@ -0,0 +1,60 @@
|
||||||
|
# v0.4 — Startup-диагностика окружения
|
||||||
|
|
||||||
|
| | |
|
||||||
|
|---|---|
|
||||||
|
| Milestone | v0.4 |
|
||||||
|
| Status | planned |
|
||||||
|
| Priority | P1 |
|
||||||
|
| Depends on | — |
|
||||||
|
|
||||||
|
## Цель
|
||||||
|
|
||||||
|
Edge при старте сам говорит, что с окружением: kernel, BTF, драйвер NIC,
|
||||||
|
поддержка native/generic XDP, доступные capabilities — и падает с внятной
|
||||||
|
причиной, если XDP включён, но загрузиться не сможет.
|
||||||
|
|
||||||
|
## Зачем
|
||||||
|
|
||||||
|
Диагностика уже есть в `rampart-cli doctor` (`src/xdp/probe/`, `EnvironmentReport`),
|
||||||
|
но демон её не использует. У конкурентов ~80% issues про XDP — это attach на
|
||||||
|
неподдерживаемом окружении (OpenVZ/LXC, старый kernel, отсутствие BTF), при этом
|
||||||
|
сообщение появляется уже после неудачного `load()`.
|
||||||
|
|
||||||
|
## Scope
|
||||||
|
|
||||||
|
- Переиспользовать `EnvironmentReport`/`FilesystemProbe` при старте edge, а не
|
||||||
|
писать второй детектор.
|
||||||
|
- Один структурированный лог-вердикт: `kernel`, `virt`, `interface`, `driver`,
|
||||||
|
`native|generic|none`, причина отказа.
|
||||||
|
- Fail-fast только когда `[xdp] enabled = true` и загрузка невозможна; иначе —
|
||||||
|
предупреждение и работа без XDP (текущее поведение сохраняется).
|
||||||
|
- Код возврата/сообщение для systemd: человек читает `journalctl` и понимает, что
|
||||||
|
делать, без чтения исходников.
|
||||||
|
|
||||||
|
## Non-goals
|
||||||
|
|
||||||
|
- Автоматическое лечение окружения (загрузка модулей, смена драйвера).
|
||||||
|
- Полноценный `doctor` в демоне: интерактивные проверки остаются в CLI.
|
||||||
|
|
||||||
|
## Approach
|
||||||
|
|
||||||
|
1. Вынести общий «вердикт» в `src/xdp/probe/`, чтобы CLI и демон печатали одно и
|
||||||
|
то же.
|
||||||
|
2. В `app::runtime` перед `start_xdp` логировать отчёт; при ошибке attach —
|
||||||
|
приложить вердикт к ошибке.
|
||||||
|
3. Тесты: чистая функция форматирования отчёта (без root), плюс существующие
|
||||||
|
`tests/xdp_diagnostics.rs`.
|
||||||
|
4. Документация: раздел в `docs/troubleshooting.md` и `docs/runbook.md` со
|
||||||
|
ссылкой на тот же вердикт.
|
||||||
|
|
||||||
|
## Критерии приёмки
|
||||||
|
|
||||||
|
- [ ] На kernel без BTF/в LXC лог содержит причину и рекомендацию.
|
||||||
|
- [ ] В KVM с virtio вывод честно говорит `generic (skb)`, а не «XDP works».
|
||||||
|
- [ ] `rampart-cli doctor` и edge используют один код формирования отчёта.
|
||||||
|
- [ ] `cargo clippy --all-targets --all-features -- -D warnings` чистый.
|
||||||
|
|
||||||
|
## Верификация
|
||||||
|
|
||||||
|
Прогон в двух окружениях: обычный хост и контейнер без `CAP_BPF`; вывод
|
||||||
|
сравнивается с `docs/troubleshooting.md`.
|
||||||
65
docs/roadmap/v0.4-xdp-ci-harness.md
Normal file
65
docs/roadmap/v0.4-xdp-ci-harness.md
Normal file
|
|
@ -0,0 +1,65 @@
|
||||||
|
# v0.4 — XDP netns+veth harness в CI
|
||||||
|
|
||||||
|
| | |
|
||||||
|
|---|---|
|
||||||
|
| Milestone | v0.4 |
|
||||||
|
| Status | planned |
|
||||||
|
| Priority | P0 |
|
||||||
|
| Depends on | — |
|
||||||
|
|
||||||
|
## Цель
|
||||||
|
|
||||||
|
Каждый PR проверяет XDP-программу на реальном ядре: загрузка через verifier,
|
||||||
|
attach в netns, баны, whitelist, expiry — без ручных шагов на живой ноде.
|
||||||
|
|
||||||
|
## Зачем
|
||||||
|
|
||||||
|
Сейчас `scripts/xdp_ipv6_smoke.sh`, `xdp_pkt_test.sh` и `xdp_netns_smoke.sh`
|
||||||
|
запускаются вручную. Регрессии ловятся только на реальном сервере, а раунд
|
||||||
|
2026-11 показал, что именно там ломается (UAF при чтении map, `.rodata`-раскладка,
|
||||||
|
имена карт в загрузчике). В конкурентном анализе (вывод №7) такой харнесс
|
||||||
|
отсутствует у всех — это наше преимущество в надёжности.
|
||||||
|
|
||||||
|
## Scope
|
||||||
|
|
||||||
|
- Единая точка входа `scripts/xdp_ci.sh`: поднимает netns+veth, собирает BPF через
|
||||||
|
`build.rs`, грузит программу, гоняет фазы v4/v6/ban/whitelist/expiry/udp.
|
||||||
|
- Формат вывода и код возврата, пригодные для CI (без интерактивных шагов).
|
||||||
|
- CI-job: либо self-hosted runner с `CAP_BPF`/`CAP_NET_ADMIN`, либо hosted
|
||||||
|
`ubuntu-24.04` с `sudo` и проверкой, что kernel ≥ 5.10 и программа реально
|
||||||
|
загрузилась (не только скомпилировалась).
|
||||||
|
- Документация: как запустить локально и что делать, если в окружении нет прав.
|
||||||
|
|
||||||
|
## Non-goals
|
||||||
|
|
||||||
|
- Нагрузочный тест на 1M pps: это `deploy/test/stress/`, отдельный стенд.
|
||||||
|
- Проверка на всех драйверах: native/generic режимы достаточно проверить на veth.
|
||||||
|
|
||||||
|
## Approach
|
||||||
|
|
||||||
|
1. Обернуть существующие скрипты общим хелпером (создание netns/veth, cleanup
|
||||||
|
через trap) — сейчас логика дублируется.
|
||||||
|
2. Добавить `--ci` режим: короткие таймауты, машиночитаемые PASS/FAIL строки.
|
||||||
|
3. Job в `.github/workflows/ci.yml`; при отсутствии прав — честный `SKIP`, а не
|
||||||
|
зелёный тест.
|
||||||
|
4. Регрессионный тест на загрузчик: `tests/xdp_object_maps.rs` уже проверяет имена
|
||||||
|
карт без root, оставить его обязательным.
|
||||||
|
|
||||||
|
## Критерии приёмки
|
||||||
|
|
||||||
|
- [ ] `sudo bash scripts/xdp_ci.sh` проходит на kernel ≥ 5.10 с `bpftool`.
|
||||||
|
- [ ] CI-job падает при регрессе в `universal_filter.c`, `config.h`, `maps.h`.
|
||||||
|
- [ ] Нет root-прав — job выдаёт `SKIP` с причиной, а не ложный успех.
|
||||||
|
- [ ] README/testing.md и docs/testing.md описывают один и тот же путь запуска.
|
||||||
|
|
||||||
|
## Верификация
|
||||||
|
|
||||||
|
`sudo bash scripts/xdp_ci.sh` на dev-машине + прогон job в PR с намеренно
|
||||||
|
сломанным заголовком `config.h` (должен упасть).
|
||||||
|
|
||||||
|
## Риски
|
||||||
|
|
||||||
|
- GitHub-hosted runner может не дать `CAP_BPF`; тогда нужен self-hosted runner.
|
||||||
|
Решение принимается на этапе дизайна, до реализации.
|
||||||
|
- veth не воспроизводит offload-поведение реального NIC; паддинг и VLAN
|
||||||
|
покрываются `xdp_pkt_test.sh` отдельно.
|
||||||
47
docs/roadmap/v0.5-geoip-asn.md
Normal file
47
docs/roadmap/v0.5-geoip-asn.md
Normal file
|
|
@ -0,0 +1,47 @@
|
||||||
|
# v0.5 — GeoIP/ASN reputation
|
||||||
|
|
||||||
|
| | |
|
||||||
|
|---|---|
|
||||||
|
| Milestone | v0.5 |
|
||||||
|
| Status | idea |
|
||||||
|
| Priority | P1 |
|
||||||
|
| Depends on | — |
|
||||||
|
|
||||||
|
## Цель
|
||||||
|
|
||||||
|
Фильтрация и репутация по стране/ASN: блокировка нежелательных регионов,
|
||||||
|
понижение репутации хостинговых ASN, белый список «домашних» сетей.
|
||||||
|
|
||||||
|
## Зачем
|
||||||
|
|
||||||
|
Feature-флаг `geoip` и `maxminddb` в зависимостях есть, но реализации нет —
|
||||||
|
«мёртвый код = баг» по правилам проекта. Для VDS-ниши страна/ASN — базовый
|
||||||
|
фильтр, который конкуренты либо не дают, либо дают только в платной версии.
|
||||||
|
|
||||||
|
## Scope
|
||||||
|
|
||||||
|
- Загрузка MaxMind MMDB (страна, ASN) при старте; hot-reload файла по SIGHUP или
|
||||||
|
таймеру.
|
||||||
|
- Конфиг: список разрешённых/запрещённых стран и ASN, режим (`drop`/`challenge`).
|
||||||
|
- Метрики: вердикты по странам/ASN, ошибки чтения базы.
|
||||||
|
- XDP-путь не трогаем: GeoIP — userspace-фильтр на этапе `Gateway`.
|
||||||
|
|
||||||
|
## Non-goals
|
||||||
|
|
||||||
|
- Собственная GeoIP-база.
|
||||||
|
- Блокировка по городу/координатам.
|
||||||
|
|
||||||
|
## Approach
|
||||||
|
|
||||||
|
1. Абстракция `GeoLookup` (trait) + реализация на `maxminddb`, чтобы тесты не
|
||||||
|
требовали бинарной базы.
|
||||||
|
2. Интеграция в `Gateway::handle_client` после blacklist, до PoW.
|
||||||
|
3. Fail-fast: `geoip` включён, база не читается → отказ старта с понятной ошибкой.
|
||||||
|
4. Тесты: фикстура MMDB в `tests/fixtures/` (маленькая, с явной лицензией).
|
||||||
|
|
||||||
|
## Критерии приёмки
|
||||||
|
|
||||||
|
- [ ] Конфиг валидируется: неизвестная страна/ASN — ошибка, а не тихий пропуск.
|
||||||
|
- [ ] Нет базы — фича выключена, edge работает.
|
||||||
|
- [ ] Метрики покрыты тестами; docs/configuration.md обновлён.
|
||||||
|
- [ ] Лицензия базы и ограничения описаны в документации.
|
||||||
45
docs/roadmap/v0.5-grpc-plugin.md
Normal file
45
docs/roadmap/v0.5-grpc-plugin.md
Normal file
|
|
@ -0,0 +1,45 @@
|
||||||
|
# v0.5 — gRPC protocol plugin
|
||||||
|
|
||||||
|
| | |
|
||||||
|
|---|---|
|
||||||
|
| Milestone | v0.5 |
|
||||||
|
| Status | idea |
|
||||||
|
| Priority | P2 |
|
||||||
|
| Depends on | стабильный `ProtocolHandler` API |
|
||||||
|
|
||||||
|
## Цель
|
||||||
|
|
||||||
|
Плагин, который понимает gRPC поверх HTTP/2: валидирует префикс запроса, умеет
|
||||||
|
отклонять мусор до upstream, поддерживает multiplexing без потери соединений.
|
||||||
|
|
||||||
|
## Зачем
|
||||||
|
|
||||||
|
После HTTP/1.1 логичный следующий протокол: gRPC — стандарт для внутренних API, а
|
||||||
|
его handshake (HTTP/2 preface + SETTINGS) дешёво проверяется в userspace. Даёт
|
||||||
|
кейс «защитить внутренний сервис», а не только публичный сайт.
|
||||||
|
|
||||||
|
## Scope
|
||||||
|
|
||||||
|
- Разбор HTTP/2 preface и первых фреймов (SETTINGS/HEADERS) с лимитами.
|
||||||
|
- Решение Allow/Reject и туннелирование на upstream без буферизации всего потока.
|
||||||
|
- Конфиг `[protocol.grpc]`: лимиты заголовков, таймауты, разрешённые пути.
|
||||||
|
- Тесты на фрагментацию (парсер обязан переживать «один read»).
|
||||||
|
|
||||||
|
## Non-goals
|
||||||
|
|
||||||
|
- Полноценный HTTP/2-прокси с приоритетами и flow control.
|
||||||
|
- gRPC-рефлексия и десериализация сообщений.
|
||||||
|
|
||||||
|
## Approach
|
||||||
|
|
||||||
|
1. Переиспользовать HTTP/1.1-парсер там, где применимо; HTTP/2 preface —
|
||||||
|
отдельная маленькая стейт-машина.
|
||||||
|
2. Новый feature `protocol-grpc`, регистрация в `ProtocolRegistry`.
|
||||||
|
3. Fuzz-цель `http2_preface` рядом с существующими.
|
||||||
|
4. Документация: `docs/configuration.md` + отдельный пример конфига.
|
||||||
|
|
||||||
|
## Критерии приёмки
|
||||||
|
|
||||||
|
- [ ] `--features protocol-grpc` собирается и покрыт тестами в CI.
|
||||||
|
- [ ] Парсер не выходит за буфер на произвольных байтах (fuzz 60 с в `make fuzz`).
|
||||||
|
- [ ] Нет регрессии латентности HTTP/1.1-пути (bench hot_paths).
|
||||||
53
docs/roadmap/v0.5-pinned-maps-openapi.md
Normal file
53
docs/roadmap/v0.5-pinned-maps-openapi.md
Normal file
|
|
@ -0,0 +1,53 @@
|
||||||
|
# v0.5 — Pinned maps и OpenAPI
|
||||||
|
|
||||||
|
| | |
|
||||||
|
|---|---|
|
||||||
|
| Milestone | v0.5 |
|
||||||
|
| Status | idea |
|
||||||
|
| Priority | P1 |
|
||||||
|
| Depends on | — |
|
||||||
|
|
||||||
|
## Цель
|
||||||
|
|
||||||
|
Динамические списки и состояние XDP доступны снаружи без перекомпиляции и без
|
||||||
|
прямого доступа к памяти: pinned maps через bpffs + описанный OpenAPI контракт
|
||||||
|
manager API.
|
||||||
|
|
||||||
|
## Зачем
|
||||||
|
|
||||||
|
Самый частый запрос у XDP-фаерволов — управлять списками на лету; у gamemann это
|
||||||
|
issues #79/#77/#78, web-панель так и не сделана. Наш manager API уже умеет
|
||||||
|
blacklist, но контракт не описан машинно, а XDP-карты не pin-ятся.
|
||||||
|
|
||||||
|
## Scope
|
||||||
|
|
||||||
|
- `bpftool`-совместимые pinned maps (blacklist, whitelist, stats) с фиксированными
|
||||||
|
именами и документированной раскладкой ключей.
|
||||||
|
- OpenAPI 3.1 spec для существующих маршрутов (`/health`, `/auth/login`,
|
||||||
|
`/servers`, `/blacklist`, `/nodes`), генерация из одного источника или
|
||||||
|
ручной файл + тест соответствия роутеру.
|
||||||
|
- Swagger UI — опционально, отдельным бинарём/фичей, не в основном edge.
|
||||||
|
|
||||||
|
## Non-goals
|
||||||
|
|
||||||
|
- Web-панель (UI) — отдельный продукт.
|
||||||
|
- Изменение ABI существующих карт без теста совместимости.
|
||||||
|
|
||||||
|
## Approach
|
||||||
|
|
||||||
|
1. Выбрать: pin-ить карты в загрузчике (`libbpf-rs` pin path) или отдельной
|
||||||
|
утилитой. Проверить, что pin не мешает перезапуску/cleanup.
|
||||||
|
2. OpenAPI: начать с ручного `docs/openapi.yaml`, добавить тест, что каждый
|
||||||
|
маршрут из `router.rs` присутствует в спецификации.
|
||||||
|
3. Документация: как читать/писать карты, какие значения, какие ограничения.
|
||||||
|
|
||||||
|
## Критерии приёмки
|
||||||
|
|
||||||
|
- [ ] `bpftool map show pin` видит карты после старта edge.
|
||||||
|
- [ ] OpenAPI валидируется в CI и покрывает 100% маршрутов.
|
||||||
|
- [ ] README/api.md ссылаются на спецификацию, а не дублируют её.
|
||||||
|
|
||||||
|
## Риски
|
||||||
|
|
||||||
|
Pinned maps усложняют graceful detach и могут оставить «висящие» карты после
|
||||||
|
краша — нужен reaper и тест.
|
||||||
58
docs/roadmap/v0.5-rst-challenge-ga.md
Normal file
58
docs/roadmap/v0.5-rst-challenge-ga.md
Normal file
|
|
@ -0,0 +1,58 @@
|
||||||
|
# v0.5 — RST-challenge: довести до GA
|
||||||
|
|
||||||
|
| | |
|
||||||
|
|---|---|
|
||||||
|
| Milestone | v0.5 |
|
||||||
|
| Status | planned |
|
||||||
|
| Priority | P0 |
|
||||||
|
| Depends on | v0.4-xdp-ci-harness (регрессии на реальном ядре) |
|
||||||
|
|
||||||
|
## Цель
|
||||||
|
|
||||||
|
RST-challenge (Oubliette-style liveness proof) работает для IPv4 и IPv6, включён
|
||||||
|
документированным способом и заменяет текстовый PoW там, где PoW несовместим с
|
||||||
|
протоколом.
|
||||||
|
|
||||||
|
## Зачем
|
||||||
|
|
||||||
|
В коде уже есть `xdp/core/syn_challenge.h` и `[xdp] syn_challenge_enabled`
|
||||||
|
(IPv4, SYN-ACK с неверным ACK → RST от живого клиента → verified). Это
|
||||||
|
универсальная проверка liveness, совместимая с любым TCP-клиентом, в отличие от
|
||||||
|
userspace PoW, который ломает протоколы с собственным handshake (Minecraft).
|
||||||
|
Осталось довести до продакшена и убрать расхождение «фича есть в C, но не в
|
||||||
|
документации/дефолтах».
|
||||||
|
|
||||||
|
## Scope
|
||||||
|
|
||||||
|
- IPv6-паритет: 128-битные flow-ключи для pending-challenge и verified-состояния.
|
||||||
|
- Метрики: выданные challenge, прошедшие/просроченные, доля verified-источников.
|
||||||
|
- Заменить/дополнить PoW: описать матрицу «протокол → PoW / RST-challenge / оба»,
|
||||||
|
обновить `[pow]` и `[xdp]` в configuration.md.
|
||||||
|
- Интеграционные тесты: живой клиент проходит, спуф не проходит; TTL challenge.
|
||||||
|
- Docs: отдельный раздел про challenge в architecture.md и runbook.
|
||||||
|
|
||||||
|
## Non-goals
|
||||||
|
|
||||||
|
- RST-challenge для UDP.
|
||||||
|
- Хранение verified-состояния в Redis между нодами (сейчас локально в XDP).
|
||||||
|
|
||||||
|
## Approach
|
||||||
|
|
||||||
|
1. Аудит текущего C-кода и ABI: ключи, таймауты, взаимодействие с conntrack.
|
||||||
|
2. v6: расширить `flow_key` или добавить `flow_key6`; проверить размер карт.
|
||||||
|
3. Userspace: метрики и переключатель; логировать причину отказа без секретов.
|
||||||
|
4. Тесты: `tests/xdp_ban_keys.rs` рядом, `scripts/xdp_ci.sh` из v0.4.
|
||||||
|
5. Документация и дефолты: решение «включать по умолчанию» принимается только
|
||||||
|
после нагрузочного стенда.
|
||||||
|
|
||||||
|
## Критерии приёмки
|
||||||
|
|
||||||
|
- [ ] IPv4 и IPv6: живой клиент проходит после одного RST, спуф — нет.
|
||||||
|
- [ ] Метрики challenge видны в `/metrics` и описаны в docs.
|
||||||
|
- [ ] Нет дефолтного секрета: placeholder отклоняется при старте (уже есть).
|
||||||
|
- [ ] PoW и RST-challenge не включаются одновременно для Minecraft.
|
||||||
|
|
||||||
|
## Верификация
|
||||||
|
|
||||||
|
`scripts/xdp_ci.sh` + e2e-тест в `tests/edge_e2e.rs`; ручная проверка `tcpdump`
|
||||||
|
на dev-ноде.
|
||||||
37
docs/roadmap/v0.6-bgp-anycast.md
Normal file
37
docs/roadmap/v0.6-bgp-anycast.md
Normal file
|
|
@ -0,0 +1,37 @@
|
||||||
|
# v0.6 — BGP Anycast
|
||||||
|
|
||||||
|
| | |
|
||||||
|
|---|---|
|
||||||
|
| Milestone | v0.6 |
|
||||||
|
| Status | idea |
|
||||||
|
| Priority | P3 |
|
||||||
|
| Depends on | несколько edge-площадок |
|
||||||
|
|
||||||
|
## Цель
|
||||||
|
|
||||||
|
Анонс защищаемого префикса (`/24` + AS) с нескольких edge-площадок, чтобы
|
||||||
|
атакующий трафик распределялся, а клиент попадал на ближайшую ноду.
|
||||||
|
|
||||||
|
## Зачем
|
||||||
|
|
||||||
|
Это инфраструктурный уровень защиты, который сейчас закрывают только провайдеры.
|
||||||
|
Для одиночного VDS не нужен, но без него нельзя называться «платформой».
|
||||||
|
|
||||||
|
## Non-goals
|
||||||
|
|
||||||
|
- Собственная BGP-реализация с нуля: используем зрелый демон (BIRD/FRR) и
|
||||||
|
управляем им.
|
||||||
|
- Автоматический анонс при атаке без оператора.
|
||||||
|
|
||||||
|
## Approach
|
||||||
|
|
||||||
|
1. Исследовать: BIRD/FRR + health-check, при котором withdraw происходит при
|
||||||
|
деградации ноды.
|
||||||
|
2. Написать интеграцию (генерация конфига, health-скрипт), а не демон.
|
||||||
|
3. Лабораторный стенд: два netns с BGP-сессией, проверка withdraw/failover.
|
||||||
|
|
||||||
|
## Критерии приёмки
|
||||||
|
|
||||||
|
- [ ] Failover проверен в лаборатории, время withdraw задокументировано.
|
||||||
|
- [ ] Конфиг генерируется из одного источника (manager inventory).
|
||||||
|
- [ ] Есть runbook на случай анонса «плохого» префикса.
|
||||||
39
docs/roadmap/v0.6-bloom-filter.md
Normal file
39
docs/roadmap/v0.6-bloom-filter.md
Normal file
|
|
@ -0,0 +1,39 @@
|
||||||
|
# v0.6 — Bloom filter для blacklist
|
||||||
|
|
||||||
|
| | |
|
||||||
|
|---|---|
|
||||||
|
| Milestone | v0.6 |
|
||||||
|
| Status | idea |
|
||||||
|
| Priority | P3 |
|
||||||
|
| Depends on | — |
|
||||||
|
|
||||||
|
## Цель
|
||||||
|
|
||||||
|
Дешёвая предварительная проверка «адреса точно нет в blacklist», чтобы не
|
||||||
|
трогать LPM-трию и не брать лок на каждый пакет.
|
||||||
|
|
||||||
|
## Зачем
|
||||||
|
|
||||||
|
Blacklist lookup в XDP уже LPM, но при росте списка до сотен тысяч записей
|
||||||
|
память и стоимость lookup растут. Bloom-фильтр даёт negative lookup за один
|
||||||
|
memory access.
|
||||||
|
|
||||||
|
## Non-goals
|
||||||
|
|
||||||
|
- Точная проверка без false positive: Bloom только отсеивает, финальное слово за
|
||||||
|
картой blacklist.
|
||||||
|
- Замена существующих карт: фильтр — дополнение.
|
||||||
|
|
||||||
|
## Approach
|
||||||
|
|
||||||
|
1. Сначала измерить: при каких размерах списка LPM lookup становится узким местом
|
||||||
|
(bench + `bpftool map show`).
|
||||||
|
2. Если выигрыш есть — Bloom в отдельной карте, обновление при ban/unban,
|
||||||
|
периодическая пересборка из источника правды.
|
||||||
|
3. Тесты: false-negative == 0, память в лимитах, поведение при переполнении.
|
||||||
|
|
||||||
|
## Критерии приёмки
|
||||||
|
|
||||||
|
- [ ] Бенчмарк до/после на списке ≥ 100k.
|
||||||
|
- [ ] Ноль false negative на property-тестах.
|
||||||
|
- [ ] Деградация при переполнении описана и безопасна (fail-open к точной карте).
|
||||||
46
docs/roadmap/v0.6-http-over-xdp.md
Normal file
46
docs/roadmap/v0.6-http-over-xdp.md
Normal file
|
|
@ -0,0 +1,46 @@
|
||||||
|
# v0.6 — HTTP поверх XDP (BPF hook)
|
||||||
|
|
||||||
|
| | |
|
||||||
|
|---|---|
|
||||||
|
| Milestone | v0.6 |
|
||||||
|
| Status | idea |
|
||||||
|
| Priority | P1 |
|
||||||
|
| Depends on | v0.4-xdp-ci-harness, v0.5-rst-challenge-ga |
|
||||||
|
|
||||||
|
## Цель
|
||||||
|
|
||||||
|
Первый реальный BPF-протокол-хук: разбор начала HTTP-запроса в XDP и rate-limit
|
||||||
|
по L7-признакам до того, как соединение дойдёт до userspace.
|
||||||
|
|
||||||
|
## Зачем
|
||||||
|
|
||||||
|
Сейчас `xdp/hooks/hook_api.h` — контракт без потребителя, а HTTP-фильтрация
|
||||||
|
происходит только в userspace: под флудом соединений CPU тратится на accept и
|
||||||
|
чтение заголовков. Хук в ядре снимет основную часть нагрузки на дорогие атаки.
|
||||||
|
|
||||||
|
## Scope
|
||||||
|
|
||||||
|
- Ограниченный парсер: метод, путь, Host, User-Agent — с жёсткими лимитами.
|
||||||
|
- Tail-call цепочка из основной программы в hook (без роста сложности
|
||||||
|
`universal_filter.c`).
|
||||||
|
- Политика: drop/rate-limit по пути и User-Agent; конфиг в `.rodata`.
|
||||||
|
- Тесты в netns-стенде + fuzz-цель на тех же байтах, что и userspace-парсер.
|
||||||
|
|
||||||
|
## Non-goals
|
||||||
|
|
||||||
|
- Полный HTTP-парсер в BPF (TLS, body, chunked).
|
||||||
|
- Замена userspace HTTP-плагина: хук — быстрый предфильтр, финальное решение
|
||||||
|
остаётся за `ProtocolHandler`.
|
||||||
|
|
||||||
|
## Approach
|
||||||
|
|
||||||
|
1. Прототип отдельной BPF-программы с `test_run` на сохранённых пакетах.
|
||||||
|
2. Сравнить pps/CPU с текущим userspace-путём на `deploy/test/stress/`.
|
||||||
|
3. Только при выигрыше — интегрировать в загрузчик и конфиг.
|
||||||
|
|
||||||
|
## Критерии приёмки
|
||||||
|
|
||||||
|
- [ ] Хук не меняет вердикты userspace-фильтра (property-тесты на одних байтах).
|
||||||
|
- [ ] Бенчмарк показывает измеримый выигрыш на HTTP-flood.
|
||||||
|
- [ ] Верификатор проходит на kernel ≥ 5.10, размер программы в лимитах.
|
||||||
|
- [ ] Фича выключена по умолчанию и не ломает сборку без неё.
|
||||||
37
docs/roadmap/v0.6-io-uring.md
Normal file
37
docs/roadmap/v0.6-io-uring.md
Normal file
|
|
@ -0,0 +1,37 @@
|
||||||
|
# v0.6 — io_uring runtime
|
||||||
|
|
||||||
|
| | |
|
||||||
|
|---|---|
|
||||||
|
| Milestone | v0.6 |
|
||||||
|
| Status | idea |
|
||||||
|
| Priority | P3 |
|
||||||
|
| Depends on | бенчмарк relay-пути |
|
||||||
|
|
||||||
|
## Цель
|
||||||
|
|
||||||
|
Опциональный io_uring-транспорт для relay: меньше syscall и копий на горячем
|
||||||
|
пути пересылки.
|
||||||
|
|
||||||
|
## Зачем
|
||||||
|
|
||||||
|
Фича `io-uring` и зависимость `tokio-splice` объявлены, но не используются. На
|
||||||
|
relay-пути доминируют `read`/`write` и копии; `splice`/io_uring могут снизить CPU
|
||||||
|
на высоких pps.
|
||||||
|
|
||||||
|
## Non-goals
|
||||||
|
|
||||||
|
- Замена tokio целиком: только транспорт relay-соединений.
|
||||||
|
- Требование io_uring для работы edge: feature опционален, дефолт — текущий путь.
|
||||||
|
|
||||||
|
## Approach
|
||||||
|
|
||||||
|
1. Замерить текущий relay: `perf`/`samply` на нагрузочном стенде, найти долю
|
||||||
|
syscall.
|
||||||
|
2. Прототип `RelayTransport` на `tokio-splice`, сравнить на 1/10/100k соединений.
|
||||||
|
3. Оставить фичу только если выигрыш воспроизводим и код не разрастается.
|
||||||
|
|
||||||
|
## Критерии приёмки
|
||||||
|
|
||||||
|
- [ ] Замеры до/после с методологией в `docs/research/benchmark.md`.
|
||||||
|
- [ ] `--features io-uring` собирается и тестируется в CI.
|
||||||
|
- [ ] Поведение при недоступном io_uring — прозрачный fallback.
|
||||||
39
docs/roadmap/v0.6-ml-anomaly.md
Normal file
39
docs/roadmap/v0.6-ml-anomaly.md
Normal file
|
|
@ -0,0 +1,39 @@
|
||||||
|
# v0.6 — ML anomaly detection
|
||||||
|
|
||||||
|
| | |
|
||||||
|
|---|---|
|
||||||
|
| Milestone | v0.6 |
|
||||||
|
| Status | idea |
|
||||||
|
| Priority | P3 |
|
||||||
|
| Depends on | собранный датасет атак |
|
||||||
|
|
||||||
|
## Цель
|
||||||
|
|
||||||
|
Детектор аномалий (Isolation Forest или проще) поверх текущих сигналов EWMA,
|
||||||
|
репутации и prefix-статистики: ловить медленные, «человеческие» атаки, которые
|
||||||
|
пороговые правила пропускают.
|
||||||
|
|
||||||
|
## Зачем
|
||||||
|
|
||||||
|
Пороги легко обходятся медленным ramp-up. Но ML без данных — гадание, поэтому
|
||||||
|
задача стоит после того, как накопим воспроизводимые датасеты с нагрузочного
|
||||||
|
стенда.
|
||||||
|
|
||||||
|
## Non-goals
|
||||||
|
|
||||||
|
- Онлайн-обучение в проде.
|
||||||
|
- Замена детерминированных порогов: ML — дополнительный сигнал, не единственный.
|
||||||
|
|
||||||
|
## Approach
|
||||||
|
|
||||||
|
1. Собрать датасеты: нормальная нагрузка + 3–5 типов атак из `deploy/test/stress/`.
|
||||||
|
2. Офлайн-прототип на Python, метрики precision/recall, сравнение с текущим
|
||||||
|
`AttackDetector`.
|
||||||
|
3. Если выигрыш доказан — перенос в Rust с фиксированной моделью и
|
||||||
|
детерминированным инференсом.
|
||||||
|
|
||||||
|
## Критерии приёмки
|
||||||
|
|
||||||
|
- [ ] Датасет и методология опубликованы в `docs/research/`.
|
||||||
|
- [ ] Ложноположительные на нормальной нагрузке ≤ текущего детектора.
|
||||||
|
- [ ] Инференс не добавляет аллокаций в hot path (замер).
|
||||||
|
|
@ -10,7 +10,7 @@
|
||||||
# ── ШАГ 1: Подтвердить атаку ──
|
# ── ШАГ 1: Подтвердить атаку ──
|
||||||
|
|
||||||
# Метрики edge ноды
|
# Метрики 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
|
# rampart_attack_status: 0 = normal, 1 = suspicious, 2 = under_attack
|
||||||
# (детектор по порогу pps, см. src/traffic/intel/detector.rs)
|
# (детектор по порогу pps, см. src/traffic/intel/detector.rs)
|
||||||
|
|
@ -50,7 +50,7 @@ iptables -A INPUT -p tcp --dport 25565 -j DROP
|
||||||
# ── ШАГ 5: После атаки ──
|
# ── ШАГ 5: После атаки ──
|
||||||
|
|
||||||
# События атак пишутся в ClickHouse (если настроен clickhouse_url):
|
# События атак пишутся в 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
|
# Написать 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_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_clickhouse_dropped_total` > 0 | события не успевают уходить в ClickHouse | проверить доступность/латентность ClickHouse; события потеряны, защита работает |
|
||||||
| `rampart_xdp_whitelist_total` растёт | трафик от whitelist-адресов | норма, но если это неожиданно — проверить `whitelist` в конфиге |
|
| `rampart_xdp_whitelist` растёт | трафик от whitelist-адресов | норма, но если это неожиданно — проверить `whitelist` в конфиге |
|
||||||
| лог `global connection budget exhausted` | то же, что `overloaded` | см. выше |
|
| лог `global connection budget exhausted` | то же, что `overloaded` | см. выше |
|
||||||
| лог `accept error ... backing off` | кончились fd (`EMFILE`) или память под сокеты | поднять `ulimit -n`, проверить утечки соединений |
|
| лог `accept error ... backing off` | кончились fd (`EMFILE`) или память под сокеты | поднять `ulimit -n`, проверить утечки соединений |
|
||||||
| лог `XDP filter attached ... (mode: generic (skb))` | драйвер не умеет native XDP | ожидаемо для virtio/veth; generic дороже по CPU |
|
| лог `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` пока не реализованы и завершатся
|
> Команды `emergency`, `drain` и `config set` пока не реализованы и завершатся
|
||||||
> явной ошибкой вместо изменения состояния.
|
> явной ошибкой вместо изменения состояния.
|
||||||
|
|
||||||
## 2. Edge нода не стартует
|
## 3. Edge нода не стартует
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
systemctl status rampart
|
systemctl status rampart
|
||||||
|
|
@ -112,7 +112,7 @@ journalctl -u rampart | grep -i xdp
|
||||||
# Временное решение: [xdp] enabled = false в config.toml
|
# Временное решение: [xdp] enabled = false в config.toml
|
||||||
```
|
```
|
||||||
|
|
||||||
## 3. XDP не загружается
|
## 4. XDP не загружается
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
systemd-detect-virt # openvz/lxc → XDP не работает, нужен KVM
|
systemd-detect-virt # openvz/lxc → XDP не работает, нужен KVM
|
||||||
|
|
@ -120,13 +120,14 @@ uname -r # нужно 5.10+
|
||||||
ethtool -i eth0 | grep driver
|
ethtool -i eth0 | grep driver
|
||||||
|
|
||||||
# Проверить компиляцию BPF-программы:
|
# Проверить компиляцию 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:
|
||||||
# [xdp] enabled = false → systemctl restart rampart
|
# [xdp] enabled = false → systemctl restart rampart
|
||||||
```
|
```
|
||||||
|
|
||||||
## 4. Клиенты не могут подключиться
|
## 5. Клиенты не могут подключиться
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
curl -s http://EDGE_IP:9090/metrics | grep rampart_connections
|
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 — увеличь.
|
# NAT: много клиентов за одним IP упираются в max_connections_per_ip — увеличь.
|
||||||
```
|
```
|
||||||
|
|
||||||
## 5. Высокая нагрузка на edge
|
## 6. Высокая нагрузка на edge
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
htop -p $(pgrep -d',' rampart)
|
htop -p $(pgrep -d',' rampart)
|
||||||
|
|
@ -149,15 +150,15 @@ iftop -i eth0 # pps/bandwidth
|
||||||
# чтобы дропать мусор раньше, и ужесточи rate limit.
|
# чтобы дропать мусор раньше, и ужесточи rate limit.
|
||||||
```
|
```
|
||||||
|
|
||||||
## 6. ClickHouse переполнен
|
## 7. ClickHouse переполнен
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
df -h /var/lib/clickhouse
|
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, рестарт.
|
# Временное отключение записи: закомментируй clickhouse_url в config.toml, рестарт.
|
||||||
```
|
```
|
||||||
|
|
||||||
## 7. Краткий справочник команд
|
## 8. Краткий справочник команд
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
rampart-cli status # Общее состояние системы
|
rampart-cli status # Общее состояние системы
|
||||||
|
|
@ -171,4 +172,4 @@ rampart-cli blacklist list
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
*Версия: 2.0 | Август 2026*
|
*Версия: 3.0 | Ноябрь 2026*
|
||||||
|
|
|
||||||
|
|
@ -12,14 +12,20 @@ cargo test --test config_parse
|
||||||
cargo test -- --nocapture # с выводом
|
cargo test -- --nocapture # с выводом
|
||||||
```
|
```
|
||||||
|
|
||||||
Существующие наборы (tests/):
|
Существующие наборы (39 файлов в `tests/`):
|
||||||
|
|
||||||
| Тест | Что покрывает |
|
| Группа | Тесты |
|
||||||
|------|---------------|
|
|--------|-------|
|
||||||
| `config_parse` | Парсинг и валидация единого конфига (src/config) |
|
| Конфиг и запуск | `config_parse`, `app_shutdown` |
|
||||||
| `filter_logic` | Blacklist, rate limit, geo-фильтры |
|
| Фильтры и лимиты | `filter_logic`, `connection_limits`, `proxy_identity` |
|
||||||
| `pow_roundtrip` | Выдача/решение/проверка PoW challenge |
|
| Протоколы | `protocol_registry`, `protocol_registry_contract`, `http_protocol`, `protocol_http_parser`, `protocol_http_handler`, `proxy_v2_parser` |
|
||||||
| `protocol_registry` | Реестр протокольных плагинов |
|
| 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-программы:
|
XDP: smoke-check компиляции BPF-программы:
|
||||||
|
|
||||||
```bash
|
```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,
|
Функциональные проверки на реальном ядре (нужен 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
|
`scripts/xdp_netns_smoke.sh` дополнительно гоняет реальный бинарь `rampart` end-to-end
|
||||||
(требует `hping3`).
|
(требует `hping3`).
|
||||||
|
|
||||||
|
Единая точка входа для CI появится в v0.4 (`scripts/xdp_ci.sh`, см.
|
||||||
|
[roadmap/v0.4-xdp-ci-harness.md](roadmap/v0.4-xdp-ci-harness.md)); до этого
|
||||||
|
скрипты выше запускаются вручную.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 3. Fuzzing
|
## 3. Fuzzing
|
||||||
|
|
@ -110,16 +122,22 @@ cargo bench --all-features --bench hot_paths
|
||||||
|
|
||||||
Замеряются: `RateLimiter::check`, exact/CIDR/miss lookup в `Blacklist`, `SubnetDetector::evaluate`
|
Замеряются: `RateLimiter::check`, exact/CIDR/miss lookup в `Blacklist`, `SubnetDetector::evaluate`
|
||||||
на окне из 256 префиксов и разбор HTTP request-head. Сравнивай медианы до/после изменения на
|
на окне из 256 префиксов и разбор HTTP request-head. Сравнивай медианы до/после изменения на
|
||||||
одной машине; абсолютные числа зависят от CPU. Порядок величин на dev-машине (2 vCPU):
|
одной машине; абсолютные числа зависят от CPU. Порядок величин на dev-машине (2 vCPU,
|
||||||
|
релизный профиль с `lto = "thin"`):
|
||||||
|
|
||||||
| Бенчмарк | Медиана |
|
| Бенчмарк | Медиана |
|
||||||
|----------|---------|
|
|----------|---------|
|
||||||
| `rate_limiter/check` | ~110 ns |
|
| `rate_limiter/check` | ~120 ns |
|
||||||
| `blacklist/is_blocked_exact` | ~70 ns |
|
| `blacklist/is_blocked_exact` | ~80 ns |
|
||||||
| `blacklist/is_blocked_cidr` | ~220 ns |
|
| `blacklist/is_blocked_cidr` | ~230 ns |
|
||||||
| `subnet_detector/evaluate_256` | ~2.6 µs |
|
| `blacklist/is_blocked_miss` | ~230 ns |
|
||||||
|
| `subnet_detector/evaluate_256` | ~2.8 µs |
|
||||||
| `http_parser/evaluate` | ~280 ns |
|
| `http_parser/evaluate` | ~280 ns |
|
||||||
|
|
||||||
|
Для сравнения с сохранённым прогоном: `cargo bench --all-features --bench hot_paths --
|
||||||
|
--save-baseline before` до изменения, затем `--baseline before` после; criterion покажет
|
||||||
|
дельту и её значимость.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 5. Локальный integration-стенд (Docker)
|
## 5. Локальный integration-стенд (Docker)
|
||||||
|
|
@ -173,4 +191,4 @@ curl -s http://localhost:9090/metrics | grep rampart_
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
*Версия: 2.0 | Август 2026*
|
*Версия: 3.0 | Ноябрь 2026*
|
||||||
|
|
|
||||||
|
|
@ -14,7 +14,8 @@ dpkg -l | grep libbpf # libbpf-dev нужен при сборке
|
||||||
journalctl -u rampart | grep -i "xdp\|ebpf\|bpf"
|
journalctl -u rampart | grep -i "xdp\|ebpf\|bpf"
|
||||||
|
|
||||||
# Проверить компиляцию 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) и рестарт.
|
# Не помогло — отключи XDP в config.toml ([xdp] enabled = false) и рестарт.
|
||||||
```
|
```
|
||||||
|
|
@ -166,4 +167,4 @@ rampart-cli status # краткий статус
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
*Версия: 2.0 | Август 2026*
|
*Версия: 3.0 | Ноябрь 2026*
|
||||||
|
|
|
||||||
|
|
@ -1,7 +1,7 @@
|
||||||
# VDS Compatibility - Rampart
|
# VDS Compatibility - Rampart
|
||||||
|
|
||||||
> Совместимость VDS провайдеров с XDP/eBPF.
|
> Совместимость VDS провайдеров с XDP/eBPF.
|
||||||
> Обновляется: Август 2026
|
> Обновляется: Ноябрь 2026
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|
@ -34,8 +34,10 @@ ethtool -i eth0 | grep driver
|
||||||
# 3. Версия ядра (нужно 5.10+)
|
# 3. Версия ядра (нужно 5.10+)
|
||||||
uname -r
|
uname -r
|
||||||
|
|
||||||
# 4. XDP доступность
|
# 4. Диагностика окружения (XDP, BTF, драйвер, режим attach)
|
||||||
sudo ip link set dev eth0 xdp off 2>&1 || echo "XDP не поддерживается"
|
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
47
scripts/check_docs_links.sh
Executable 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
|
||||||
|
|
@ -2,7 +2,7 @@
|
||||||
#
|
#
|
||||||
# check_module_size.sh — module size ratchet.
|
# 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).
|
# per source directory (top level, non-recursive, mod.rs included).
|
||||||
#
|
#
|
||||||
# Rationale — ratchet pattern: the gate blocks regressions immediately while
|
# Rationale — ratchet pattern: the gate blocks regressions immediately while
|
||||||
|
|
|
||||||
|
|
@ -10,7 +10,7 @@ pub async fn run(key: Option<String>, value: Option<String>) -> anyhow::Result<(
|
||||||
(None, Some(_)) | (None, None) => {
|
(None, Some(_)) | (None, None) => {
|
||||||
println!("Configuration");
|
println!("Configuration");
|
||||||
println!("=============\n");
|
println!("=============\n");
|
||||||
println!("Use: rampart config <key> [value]");
|
println!("Use: rampart-cli config <key> [value]");
|
||||||
println!();
|
println!();
|
||||||
println!("Example keys:");
|
println!("Example keys:");
|
||||||
println!(" workers.count");
|
println!(" workers.count");
|
||||||
|
|
|
||||||
|
|
@ -20,6 +20,6 @@ pub async fn run() -> anyhow::Result<()> {
|
||||||
}
|
}
|
||||||
|
|
||||||
println!();
|
println!();
|
||||||
println!("To check individual components, run: rampart doctor");
|
println!("To check individual components, run: rampart-cli doctor");
|
||||||
Ok(())
|
Ok(())
|
||||||
}
|
}
|
||||||
|
|
|
||||||
|
|
@ -12,7 +12,6 @@ use std::sync::Arc;
|
||||||
pub struct Claims {
|
pub struct Claims {
|
||||||
pub sub: String,
|
pub sub: String,
|
||||||
pub aud: String,
|
pub aud: String,
|
||||||
pub role: String,
|
|
||||||
pub exp: usize,
|
pub exp: usize,
|
||||||
pub iat: usize,
|
pub iat: usize,
|
||||||
}
|
}
|
||||||
|
|
@ -22,7 +21,6 @@ pub fn create_token(secret: &str, expiration: u64, audience: &str) -> Result<Str
|
||||||
let claims = Claims {
|
let claims = Claims {
|
||||||
sub: "rampart-admin".to_string(),
|
sub: "rampart-admin".to_string(),
|
||||||
aud: audience.to_string(),
|
aud: audience.to_string(),
|
||||||
role: "admin".to_string(),
|
|
||||||
exp: now + expiration as usize,
|
exp: now + expiration as usize,
|
||||||
iat: now,
|
iat: now,
|
||||||
};
|
};
|
||||||
|
|
|
||||||
|
|
@ -14,7 +14,6 @@ fn create_verify_roundtrip_passes() {
|
||||||
let claims = verify_token(&token, &secret, "rampart").expect("verification should succeed");
|
let claims = verify_token(&token, &secret, "rampart").expect("verification should succeed");
|
||||||
assert_eq!(claims.sub, "rampart-admin");
|
assert_eq!(claims.sub, "rampart-admin");
|
||||||
assert_eq!(claims.aud, "rampart");
|
assert_eq!(claims.aud, "rampart");
|
||||||
assert_eq!(claims.role, "admin");
|
|
||||||
assert!(claims.exp > claims.iat);
|
assert!(claims.exp > claims.iat);
|
||||||
}
|
}
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue