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
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 (замер).
|
||||
Loading…
Add table
Add a link
Reference in a new issue