docs: per-task roadmap, architecture and changelog

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

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

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

View file

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

View file

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

View file

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

View file

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

View file

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

View file

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

View file

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

View file

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

View file

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

View file

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

View file

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

View file

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

View file

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