guard/TODO.md
loki5512344 08b7292ac4
test: fuzz the HTTP and PROXY v2 parsers, make PROXY parsing pure
- PROXY v2 header parsing is now the pure, total function
  `parse_v2_header(buf, limit) -> (SocketAddr, consumed)`; the async reader
  only reads bytes and delegates. This makes the parser reachable from tests
  and fuzz targets and keeps every index bounds-checked.
- tests/proxy_v2_parser.rs: valid v4/v6 headers, bad signature, non-PROXY
  command, TLVs, every truncated prefix, oversized header, unsupported
  family, short address block, and a deterministic sweep over family/length.
- fuzz/: cargo-fuzz targets `http_head` (scan_head + evaluate) and `proxy_v2`
  with invariants (no panic, no out-of-buffer consumption, family matches the
  header). Seeds for the HTTP head keep coverage useful; `make fuzz` runs
  60 s per target. Both targets ran clean (7M and 3M executions).
- docs/testing.md documents the fuzz workflow; .gitignore covers the
  generated corpus/artifacts.
2026-11-16 12:47:25 +01:00

424 lines
36 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Rampart — Development TODO & Roadmap
> Живой документ. Философия: **KISS → DRY → SOLID → YAGNI**.
>
> v0.3.0-dev — big-bang редизайн: из Minecraft-специфичной защиты в **универсальную
> L3/L4/L7 платформу сетевой защиты**. MC-код, Java-плагины и dashboard удалены
> (доступны в git-истории до тега v0.2.0).
---
## 0. Принципы разработки
### KISS
- Не добавляй абстракцию до третьего повторения.
- **Функция ≤ 60 строк, файл ≤ 250 строк, ≤ 4 .rs-файлов на папку** (жёсткий лимит;
больше — декомпозиция или группировка доменами с ре-экспортами в mod.rs).
Гейт: `scripts/check_module_size.sh` + ratchet-базлайн `.module_size_baseline`
(легаси — WARN, новые нарушения — FAIL; после рефакторинга `--update-baseline`).
- Не используй generics где хватит `&str` и `Vec<u8>`.
### DRY
- Повтор > 2 раз → выноси, но лучше копипаста чем неправильная абстракция.
### SOLID (Rust)
- **S**: один файл = одна ответственность
- **O**: расширяй через трейты (`ProtocolHandler`, `Filter`, `StateStore`)
- **L**: `dyn Filter` — любая реализация без side effects
- **I**: маленькие трейты вместо одного God-trait
- **D**: core зависит от trait-ов, не от Redis/ClickHouse напрямую
### YAGNI
- Не пиши BGP до v0.6, WASM-плагины до стабилизации compile-time API.
- Не добавляй feature flag если фича не готова.
### Rust-специфичные
1. `unwrap()` — только в main() и тестах
2. `unsafe` — только в xdp/, комментарий `// SAFETY:` обязателен
3. `clone()` осознанно, профилируй hot path
4. Блокирующие операции → `spawn_blocking`
5. Логи: `tracing::info!` / `debug!` / `error!`
6. Метрики: register один раз при старте, инкремент в hot path
7. **Тесты отдельно от кода**: в .rs-файлах с кодом НЕТ `#[cfg(test)]`-модулей —
тесты живут в `tests/` (нужный хелпер делай `pub` с реальным вызовом-потребителем).
Существующие инлайн-тесты — легаси, мигрировать постепенно (см. бэклог).
### §0.8 Комментарии в коде (все языки)
- **Все комментарии и doc-комментарии — на английском.** Русский остаётся только в
пользовательских текстах: `docs/`, README, TODO, логи (`tracing::*!`), сообщения CLI/ошибок.
- **JavaDoc/Rustdoc-стиль.** C: `/** ... */` над функцией/структурой/картой/глобалом с
`@param`/`@return`, когда они есть. Rust: `//!` для модуля (что он владеет), `///` для
элемента; сохраняй секции `# Errors` / `# Panics` / `# Safety`.
- **Без эмодзи, ASCII-баннеров (`═══`, `───`), CAPS-акцентов** и декоративных разделителей.
Для группировки — обычный короткий комментарий.
- Инлайн-комментарий объясняет **почему**, а не пересказывает код. Комментарий-шум удаляй.
- Правишь файл — переводи комментарии в нём целиком (смесь языков запрещена), но **не трогай
строковые литералы, идентификаторы и логику**.
- `// SAFETY:` — префикс обязателен, текст по-английски.
---
## 1. Целевая структура (v0.3)
```
guard/
├── Cargo.toml # ОДИН пакет rampart, features = ["protocol-http", ...]
├── scripts/ # check_module_size.sh (гейт 250/4), check_default_secrets.sh
├── src/
│ ├── bin/{rampart, rampart-manager, rampart-cli, rampart-tui}.rs # тонкие, логика в lib
│ ├── app/ # thin-main: runtime wiring, services (spawn-циклы)
│ ├── engine/ # listener, tunnel; challenge/ (pow+difficulty), subnet/ (tracker+monitor)
│ ├── filter/ # blacklist, rate_limit, geo — trait Filter
│ ├── traffic/ # hook + prefix/ (key+stats) + intel/ (ewma,detector,reputation) + profile/ (profiler,alert)
│ ├── store/ # redis (+ trait StateStore)
│ ├── manager/ # api/ (+ api/inventory/), auth/, sync/
│ ├── cli/ # команды; commands/node/ (status,drain,emergency)
│ ├── config/ # config + sections/{edge,platform,detect}
│ ├── tui/ # app/state/ui + metrics/ (prometheus,fetch)
│ ├── protocol/ # trait ProtocolHandler + registry; http/ под фичей
│ └── xdp/ # filter/ (attach,maps), probe/ (diagnostics/,stats,metrics), globals, noop
├── xdp/
│ ├── core/ # universal_filter.c + maps/stats/config/common.h + prefix_stats/syn_challenge
│ └── hooks/hook_api.h # контракт подключаемых BPF-протокол-хуков
├── tests/ # интеграционные (вне гейта 4-файлов: cargo требует 1 файл = 1 бинарь)
└── docs/ # kb/ (knowledge base) + research/ + ops-доки
```
## 1a. Статус после редизайна (2026-08-24)
| Что | Статус |
|-----|--------|
| plugins/ velocity+paper, dashboard/ | ✅ удалены (git-история) |
| crates/* → единый пакет `rampart` + src/bin | ✅ сделано |
| MC-код (handshake, death_code, varint, hostname-HMAC) | ✅ удалён полностью |
| PoW как универсальный hashcash (`engine/challenge.rs`) | ✅ сохранён |
| XDP: universal L3/L4 фильтр + hooks API | ✅ код готов, clang build OK |
| IPv6 баг в XDP (daddr→saddr) | ✅ исправлен |
| Knowledge Base docs/kb (attacks, defense-levels, practice) | ✅ написана, двуязычная |
| README + architecture.md под новую концепцию | ✅ переписаны |
| cargo build / clippy -D warnings / test | ✅ зелёные |
---
## 2. Ближайшие задачи (v0.3)
### Subnet-level detection (ботнет с ротацией IP) — ✅ готово (2026-08/09)
- [x] **XDP**: карта `prefix_stats` (LRU_HASH, ключ /24 v4 | /64 v6) — счётчики SYN/pps
per-префикс (xdp/core/prefix_stats.h, трафик-слой: src/traffic/prefix/).
- [x] **Detector**: превышение порога префиксом при IP под лимитом → флаг подсети
(src/traffic/intel/detector.rs, src/engine/subnet/).
- [x] **Мягкая эскалация**: monitor → strict_limit → challenge → block
(SubnetVerdict-лестница; блок /24 идёт через ban_cidr, не слепой hard-ban).
- [x] Блок подсети через `blacklist_map` (LPM trie) — `XdpFilter::ban_cidr`.
### Движок без протоколов — сделать полезным — ✅ готово
- [x] **Первый протокол-плагин**: `protocol-http` — HTTP/1.1 request-head анализ
(src/protocol/http/, tests/http_protocol.rs).
- [x] **Minecraft Java TCP MVP**: ограниченный handshake status/login, передача исходных
байтов backend и опциональный PROXY protocol v2 (`protocol-minecraft`).
- [x] **TCP-proxy режим**: tunnel.rs + ProtocolHandler интегрированы в listener/app wiring.
- [x] **Fail-fast сообщение** при пустом registry (`ProtocolRegistry::primary()`).
### Подключение мёртвого интеллекта (правило: «мёртвый код = баг») — ✅ готово
- [x] Traffic Intel в hot path: AttackDetector/IpReputation → метрики + auto-ban
(src/traffic/hook.rs, src/engine/tunnel.rs, src/app/services.rs).
- [x] Blacklist: `clear_expired()` по таймеру (src/app/).
- [x] RateLimiter: TTL-эвикция idle bucket'ов.
### Безопасность — ✅ кроме ролей
- [x] Rate limiter на login endpoint manager API (per-IP, tests в api/auth.rs).
- [x] JWT: audience-валидация, secret ≥ 32 байт fail-fast (rampart-manager.rs).
- [ ] JWT-роли: сейчас единственный hardcoded `admin`; RBAC-ролей нет — либо убрать поле,
либо делать роли (решение отложить до второго потребителя).
- [x] Redis: `KEYS` → `SCAN` (scan_options), pubsub-подписчик — честный reconnect
с экспоненциальным backoff (src/store/redis.rs).
### XDP
- [x] Verifier-проверка на реальном ядре (live-тест 2026-09: два бага RST-challenge найдены и
исправлены, d6bcae5).
- [x] Rust loader (`src/xdp/filter/`): open/load/attach, patch глобалов G_* из config.toml
(src/xdp/globals.rs), CString-safe if_nametoindex, реальный detach по fd прогрессы.
- [x] Ringbuf events → blacklist: opt-in `auto_ban` ([xdp] config, default OFF) —
EVENT_RATE_LIMIT всегда, EVENT_CONN_DROP при fails>=порога; EVENT_BAN/POLICY_DROP не
банят (ядро уже отработало / статик-политика без аккумуляции). Парсер 24-байтного
`struct xdp_event` с фиксом endianness (IP — сетевой порядок, скаляры — host),
метрика `rampart_xdp_autobans_total`, tests/xdp_events.rs (10 тестов).
- [ ] Smoke-test attach в CI (VM runner с CAP_BPF) + netns+veth харнесс — вывод №7 из
конкурентного анализа, приоритет v0.4.
### Документация
- [x] docs/deployment.md, configuration.md, runbook.md — старых крейтов/MC не упоминают (grep чисто).
- [x] docs/kb/README.md — индекс KB со ссылками.
- [x] `docs/README.md` — единый индекс документации (начало работы, how-to, reference,
протоколы, теория/research) + правила ведения: русский язык, один документ = одна
задача, reference правится в том же PR, что и код, плоская структура, kebab-case.
- [x] `README.md` — двуязычный: русская часть сверху, английская снизу, общая шапка/бейджи/
переключатель языка, ряд кнопок-навигации (docs, quick start, config, API, license);
секции по конвенции (обзор → возможности → требования → установка → быстрый старт →
конфигурация → плагины → производительность → документация → разработка → лицензия),
компактный TOC строкой, копируемые команды, ссылки на docs/README.md.
- [x] `docs/configuration.md` — полная таблица `[xdp]` (включая `udp_policy`) и покрытие IPv4/IPv6;
`docs/testing.md` — реальные XDP-smoke'и, а не только clang-проверка.
- [x] TUI (ratatui): live-метрики из Prometheus endpoint — готово (src/tui/, 564613b).
## 2a. Раунд 2026-09-15 — исправлено по итогам ревью
- **unsafe-баги XDP-лоадера** (src/xdp/filter/): `&str.as_ptr()` без NUL в `if_nametoindex` → `CString`;
фиктивный `borrow_raw(-1)`-fd в `unload()` → реальный detach по fd прогрессы с propagatable ошибкой;
`unsafe impl Send` получил `// SAFETY:`; `saturating_mul` в expiry. +5 юнит-тестов.
- **Redis**: fake-reconnect pubsub (sleep+return) → настоящий reconnect-loop с backoff;
`KEYS` → `SCAN` в heartbeat.
- **CI**: `cargo test --all-features` (раньше тесты фич не гонялись); job `repo-gates`:
гейт 250/4 + grep дефолтных секретов; Makefile `ci` обновлён.
- **README**: несуществующие `rampart-core`/`rampart config init` → реальные команды;
таблица компонентов/плагинов приведена к коду (http готов, minecraft удалён, добавлен rampart-tui).
- **Рефакторинг под новые лимиты 250/4** без изменения поведения: app/, challenge/, subnet/,
prefix/, intel/, profile/, commands/node/, api/inventory/, tui/metrics/, filter/, probe/;
bin-файлы тонкие (rampart.rs: 330 → 6 строк).
### Новые найденные проблемы (чинить в v0.4)
- [x] Redis blacklist: срок/причина сохраняются; edge восстанавливает снимок после reconnect;
локальные autoban-события публикуются в Redis с retry и absolute expiry.
- [ ] Minecraft Java: Velocity modern forwarding, игровые netns smoke-тесты и нагрузочная проверка.
- [x] Принимать client IP от внешнего DDoS-прокси через доверенные CIDR и ограниченный PROXY v2 parser.
- [x] `cargo check --no-default-features` починен (2026-09-15, раунд 2): redis-код в
manager/sync/api/store/app закрыт `#[cfg(feature = "store-redis")]`, менеджер без фичи fail-fast'ит на старте;
CI теперь гоняет `cargo check --no-default-features --all-targets` гейтом.
- [x] `src/app/runtime.rs`: `#[allow(clippy::exit)]` убран — `app::run()` возвращает
`RunExit`, единственный `process::exit` теперь в `main` бина (clippy там не срабатывает).
- [x] Флакающий тест `pow_roundtrip::verifier_rejects_garbage_and_replay` (p≈1/16 из-за
случайного токена) — сидирован, 50 прогонов до (3 fail) / после (0 fail).
- [x] IPv6-паритет XDP (вывод №8) — сделано (2026-11-15):
- [x] **C**: `struct lpm_key6 { u32 prefixlen; u8 addr[16]; }` в `common.h`;
`blacklist6_map` (LPM_TRIE, 20-байтный ключ, value `u64` expiry, 100000, NO_PREALLOC) в `maps.h`;
в `universal_filter.c` non-mapped IPv6 больше не возвращает PASS раньше времени: общий L4-парсинг +
порт-гейт, затем блок `if (native_v6)`: `is_blacklisted6` (lookup `prefixlen=128`,
expiry-cleanup как у v4) → DROP; UDP при `G_UDP_POLICY==1` → DROP; `detect_tcp_bypass` → DROP;
TCP → `prefix_key_from_v6` + `update_prefix_stats` (оживило мёртвый код, замкнуло
детектор подсетей на v6); иначе PASS. Ringbuf-события для v6 не шлём (ABI `src_ip` u32).
- [x] **Rust**: `pub fn blacklist6_key(prefix_len: u8, &[u8;16]) -> [u8;20]` (prefixlen LE в 0..4,
addr network order в 4..20); `blacklist6_update`; `ban_cidr` матчит V4/V6;
`gateway.rs::xdp_ban` → `ban_cidr(ip, 32|128, dur)` для обоих семейств; `ban_ip` удалён
(после перевода gateway вызовов не осталось — «мёртвый код = баг»), `noop.rs` синхронизирован.
- [x] **Тесты**: `tests/xdp_ban_v6.rs` (layout ключа `/64` и `/128`, network order);
`scripts/xdp_ipv6_smoke.sh` — реальный netns+verifier smoke (без бана pass → с баном
blacklist+drop → после снятия снова pass), проверен на ядре 7.3.4.
- [x] **UDP rate-limit (`policy==2`) для native v6** (2026-11-15): `udp_rate_limit6` (LRU_HASH,
16-байтный ключ `struct in6_addr`, value `struct throttle_entry`) + `throttle_hit6` в
`universal_filter.c` (та же семантика окна/порога, что у v4); ветка UDP в `native_v6`
теперь `switch (G_UDP_POLICY)`: 1 → DROP, 2 → `throttle_hit6` → DROP при превышении,
иначе PASS. Ringbuf-события для v6 по-прежнему не шлём (ABI `src_ip` u32) — только счётчики.
Проверка: фаза 4 в `scripts/xdp_ipv6_smoke.sh` (патч `.rodata` до загрузки: policy=2,
hits=3 → 3 pass, 3 rate-limit).
- Non-goals (позже): conntrack/throttle/RST-challenge для нативного v6
(нужны 128-битные flow/throttle-ключи); whitelist6 (у `whitelist_map` нет писателя даже для v4);
ringbuf-события для v6; unban v6.
- [x] **Expiry бана из userspace не работал в ядре** (найден и починен 2026-11-15, касался v4 и v6):
`blacklist_expiry_ns` писал `SystemTime` (epoch ns ≈ 1.7e18), а C сравнивает с
`bpf_ktime_get_ns()` (monotonic ≈ uptime) — бан жил до перезагрузки. Теперь userspace пишет
`CLOCK_MONOTONIC`-ns (`xdp::monotonic_ns`), регрессия — `tests/xdp_ban_clock.rs` и expiry-фаза
в `scripts/xdp_ipv6_smoke.sh`.
- [x] **Короткий L4-хвост обходил blacklist** (найден и починен 2026-11-15, v4 и v6):
`universal_filter.c` требовал `sizeof(struct tcphdr)` (20 байт) для всех протоколов, иначе
ранний `XDP_PASS` — UDP-датаграмма короче 20 байт не доходила до порт-гейта и blacklist.
Теперь минимум считается по протоколу (`sizeof(struct udphdr)` для UDP); регрессия —
«короткая датаграмма» в `scripts/xdp_ipv6_smoke.sh`. TCP-путь не изменился: там по-прежнему
требуется полный `struct tcphdr`.
- [x] **XDP-загрузчик не мог загрузить программу вообще** (найден и починен 2026-11-15).
Три независимых бага, каждый из которых валил `load()` до verifier'а:
1. `.rodata`-раскладка: `build_rodata_image` писал 96-байтный образ в 76-байтную карту
(`EINVAL`) и по неверным смещениям — clang переставляет отдельные `static volatile const`
глобалы (UDP-политика лежала в 4, а не в 49). Теперь в `config.h` один
`struct rampart_config` (layout фиксирован C-структурой + `_Static_assert` на каждый
offset и размер), `XdpGlobals` получил `#[repr(C)]`, образ строится через `offset_of!`,
а `patch_rodata` падает с внятным сообщением при расхождении размера.
2. `build.rs` отслеживал только `universal_filter.c` — правка `config.h`/`common.h` оставляла
стухший объект в `OUT_DIR` (и старое `.rodata`). Теперь `rerun-if-changed` на `xdp/core`
и `xdp/hooks`.
3. `build_ringbuf` искал карту `events_map`, а в C она `events_ringbuf` —
`load()` падал после успешного verifier'а.
Регрессии: `tests/xdp_object_maps.rs` (имена всех карт, которые ищет загрузчик, и
`value_size` `.rodata` == `RODATA_SIZE`, без root) + перезапуск реального бинаря в netns
(attach подтверждён), плюс весь `scripts/xdp_ipv6_smoke.sh`.
## 2b. Ревью 2026-11-16 — качество и надёжность
Четыре независимых ревью (XDP/загрузчик, data-path, фильтры/хранилища, API/конфиг/CI)
и один раунд фиксов. Гейты после раунда: fmt, clippy `-D warnings`, `cargo test
--all-features` (258 тестов), `--no-default-features` + тесты с `protocol-http`,
module-size, secrets, `cargo deny`, rustdoc без warning'ов, clang+verifier,
`xdp_ipv6_smoke.sh`, `xdp_pkt_test.sh`, живой attach в netns (native и generic).
### Исправлено
- XDP: длина TCP-payload по `ip->tot_len`/`payload_len` — на реальном NIC паддинг больше не
ломает `expected_seq` (было: каждое соединение умирало на 4-м сегменте). Регрессия —
`scripts/xdp_pkt_test.sh`.
- XDP: чтение map-значения до `bpf_map_delete_elem` (UAF), сброс `fails`, TFO в `expected_seq`,
исправленный v6 SYN-ACK, `inc_drop()` на всех DROP-путях, per-CPU инкремент без atomic.
- XDP: VLAN/QinQ до L3, фрагменты проверяются по blacklist, неизвестный non-SYN поток → PASS
(«stateless-фильтр, не firewall»), `whitelist6_map`, whitelist до state machine.
- XDP spoof-gate: в `prefix_stats` добавлен 64-битный bitmap хешей source-адресов, userspace
считает popcount и сбрасывает счётчики при чтении → `Block` работает и на XDP-пути, а окно
детектора стало честным (раньше счётчики были кумулятивными и со временем «банили» всё).
- XDP: протухшие префиксные баны удаляются userspace-reaper'ом раз в 60 с (пакетный путь
больше не пытается удалить `/24` ключом `/32`).
- Загрузчик: запоминается фактический attach-флаг (native/skb) и проверяется detach;
`DetachGuard` откатывает attach при ошибке; whitelist из конфига грузится в карты;
`ban_cidr` валидирует и маскирует префикс; статистика знает все 13 счётчиков.
- Security: `API_PASSWORD` не пустой и ≥16 символов, `JWT_SECRET` ≥32 непробельных,
`syn_challenge_enabled` требует свой `challenge_secret_hex`, compose без публичных
Redis/ClickHouse и без дефолтных паролей, пустой `CORS_ORIGIN` → deny.
- Storage: ClickHouse с таймаутами и без lock через `.await` (bounded-буфер, метрика дропов),
Redis на `ConnectionManager` с таймаутами и реконнектом, баны из pubsub клампятся,
TOCTOU в blacklist, атомарный `replace_redis`.
- Data path: backoff на `accept()`, корректный `shutdown.changed() == Err`, глобальный бюджет
соединений, rate-limit **до** PoW, whitelist не банится, таймауты connect/handshake/relay,
idle-таймаут relay.
- Детекция: score считается до обновления baseline + гистерезис выхода из `UnderAttack`
(атака больше не «затухает» через тик); реальный cap и инкрементальная эвикция в
rate-limiter и репутации; IPv4-mapped ключи совпадают.
- Blacklist: CIDR-баны хранятся диапазонами — `/24`/`/64` покрывают всю подсеть;
нормализация IPv4-mapped на входе и на lookup.
- CI: джоба `cargo test --no-default-features --features protocol-http`, `make ebpf` больше
не глотает ошибки, secrets-гейт ловит слабые compose-дефолты.
- `doctor` не дёргает защищённые ручки без токена и возвращает ненулевой код при провале.
- Инлайн-тесты: 25 → 10 файлов (остальные — в следующих итерациях).
### Осталось
- [ ] Monitor (`add_cidr`) и `traffic/hook` autoban не сверяются с `trusted_cidrs`: если
доверенный прокси физически живёт в банимой подсети, его адрес может попасть под
префиксный бан. Нужна общая проверка перед любым баном.
### Сделано в этом раунде
- [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)*