guard/TODO.md

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 строк, модуль ≤ 300 строк (жёсткий лимит; больше — декомпозиция).
• Не используй 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

---

1. Целевая структура (v0.3)

guard/
├── Cargo.toml                  # ОДИН пакет rampart, features = ["protocol-http", ...]
├── src/
│   ├── bin/{rampart, rampart-manager, rampart-cli}.rs
│   ├── engine/                 # listener, tunnel (generic TCP proxy), challenge (PoW)
│   ├── filter/                 # blacklist, rate_limit, geo — trait Filter
│   ├── traffic/                # EWMA, detector, profiler, reputation, alert
│   ├── store/                  # redis (+ trait StateStore)
│   ├── manager/                # api/, auth/, sync/
│   ├── cli/                    # команды CLI
│   └── protocol/               # trait ProtocolHandler + registry (реализаций пока 0)
├── xdp/
│   ├── core/                   # universal_filter.c + maps/stats/config/common.h
│   └── hooks/hook_api.h        # контракт подключаемых BPF-протокол-хуков
├── tests/                      # интеграционные
└── 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)

• XDP: карта prefix_stats (LRU_HASH, ключ /24 v4 | /64 v6) — счётчики SYN/pps per-префикс рядом с per-IP (референс: caddy-mitigator CIDR promotion, lnvps_fw carpet-bomb).
• Detector: префикс превышает порог при том что отдельные IP под лимитом → распределённая атака → флаг подсети.
• Мягкая эскалация для подсетей: monitor → strict limits → challenge → блок. Хард-бан /24 только через challenge (CGNAT: за одним /24 легитимно живут сотни людей).
• Блок самой подсети — уже умеем: blacklist_map это LPM trie (CIDR из коробки).

Движок без протоколов — сделать полезным

• Первый протокол-плагин: protocol-http (feature) — минимальный HTTP/1.1 handshake-анализ (request line, заголовки, размер), чтобы edge-нода заработала для веб-сервисов.
• TCP-proxy режим: generic upstream forwarding за ProtocolHandler (tunnel.rs уже generic — проверить интеграцию).
• Fail-fast сообщение при пустом registry — улучшить текст подсказки сборки.

Подключение мёртвого интеллекта (правило: «мёртвый код = баг»)

• Layer Traffic Intel подключить в hot path: AttackDetector/IpReputation → метрики + auto-ban (сейчас не вызывается).
• Blacklist: clear_expired() по таймеру.
• RateLimiter: TTL-эвикция idle bucket'ов + cap карты.

Безопасность (перенос из аудита v0.3, актуальное)

• Rate limiter на login endpoint manager API (5/60с).
• JWT: валидация ролей/audience, secret ≥ 32 байт.
• Redis: KEYS → SCAN, reconnect pubsub-подписчика.

XDP

• Verifier-проверка на реальном ядре (в контейнере нет CAP_BPF — компиляция OK, загрузка не проверялась).
• Rust loader (src/xdp/): пути к xdp/core/universal_filter.c, patch глобалов G_* из config.toml, ringbuf events → blacklist.
• Smoke-test attach в CI (VM runner с CAP_BPF).

Документация

• docs/deployment.md, configuration.md, runbook.md — переписать под новую структуру (сейчас упоминают старые крейты/MC).
• docs/kb/README.md — индекс KB со ссылками на все статьи.
• TUI (ratatui): live-метрики из Prometheus endpoint (planned, v0.4).

3. Backlog

• 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)
• Fuzzing парсеров (cargo-fuzz)
• BGP Anycast (AS + /24)

---

3a. Бенчмарк-конкуренты: чем превзойти

Все репо склонированы в ref/ (gitignored). Анализ issues/PRs проведён 2026-08-24 через gh по трекерам конкурентов. Ниже — выжимка «что у них болит и что берём».

Карта конкурентов

Проект	Что это	Похож на Rampart тем, что	Что взять
eBPFsentinel	Rust, один бинарник: firewall+IDS+DDoS через XDP/TC/uprobe	Ближайший аналог, та же архитектура	Rootless BPF token (kernel 6.9+); tail-call цепочки; MITRE-теги алертов; Swagger UI
CrabShield	Rust + XDP, гибрид L7→L3	«Умный юзерспейс, кара в ядре»	Static musl бинарник; reaper истекающих банов; (log-tailing НЕ брать — хрупко)
lnvps_fw	XDP+TC защита VDS	Прямо наша ниша	⭐ SYN-proxy в XDP; port learning из TC egress; лестница PORT_FILTER→SYN_PROXY→SOURCE_BLOCK + spoof gate; netns+veth harness
Oubliette	Linerate scrubber	Решает нашу боль с PoW	⭐ RST-challenge: SYN-ACK с неверным ACK → спуф молчит, живой клиент шлёт RST → whitelist. Совместимо с любым клиентом
Couic (CERT Франции)	XDP-фаервол + REST API	Наш manager API	Anti-lockout; теги+TTL записей; OpenAPI spec; синк инстансов; fail2ban-интеграция
gamemann/XDP-Firewall (~830★)	Классический C XDP-фаервол	Референс по XDP	Pinned maps для внешнего управления; их issues = карта граблей верификатора
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. Модуль ≤ 300 строк: CI-гейт через grep/wc скрипт или ревью.
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 проходит
☐ Ни один модуль не превышает 300 строк
☐ Unit тесты покрывают happy path + 2+ error cases
☐ Нет мёртвого кода: pub без вызовов, конфиг-поле без потребителя, метрика без writer
☐ Нет дефолтных секретов
☐ README соответствует коду
☐ Документация обновлена
☐ CI зелёный

6. Anti-Patterns

❌ Тесты после кода. Пиши вместе.
❌ Модуль > 300 строк — сигнал декомпозировать немедленно.
❌ TODO в коде без issue.
❌ Мёртвый код: pub без вызовов, конфиг-поле без потребителя, метрика без writer.
❌ «Бумажный слой»: фича описана, но не вызывается.
❌ Дефолтный секрет.
❌ Парсер за «один read» — TCP-поток приходит фрагментами.
❌ Feature flag, который не собирается в CI.

---

Версия: 4.0 | Обновлён: 2026-08-24 (universal redesign)