guard/TODO.md

Rampart — Development TODO & Roadmap

Живой документ. Философия: KISS → DRY → SOLID → YAGNI.

---

0. Принципы разработки

KISS

• Не добавляй абстракцию до третьего повторения.
• Функция ≤ 60 строк, модуль ≤ 500 строк.
• Не используй generics где хватит &str и Vec<u8>.

DRY

• Повтор > 2 раз → выноси, но лучше копипаста чем неправильная абстракция.

SOLID (Rust)

• S: один файл = одна ответственность
• O: расширяй через трейты
• L: dyn Filter — любая реализация без side effects
• I: маленькие трейты вместо одного ShieldTrait
• D: core зависит от trait StateStore, не от Redis

YAGNI

• Не пиши BGP до v0.6, K8s Operator до v0.5
• Не добавляй feature flag если фича не готова

Rust-специфичные

1. unwrap() — только в main() и тестах
2. unsafe — только в xdp/, комментарий обязателен
3. clone() осознанно, профилируй hot path
4. Блокирующие операции → spawn_blocking
5. Логи: tracing::info! / debug! / error!
6. Метрики: register один раз при старте, инкремент в hot path

---

1. Текущее состояние (v0.2+)

✅ Готово

Компонент	Статус
rampart-core (Rust Edge)	~85% — работает: TCP listener, handshake parse, HMAC sign, rate limit, death code (8 паттернов), blacklist (DashMap + TTL), Redis sync, Prometheus metrics, graceful shutdown
rampart-manager (Rust API)	~80% — работает: JWT auth, CRUD blacklist, servers/nodes list, heartbeat мониторинг
rampart-cli (Rust CLI)	~40% — 3/6 команд (status, doctor, blacklist list/add)
velocity-plugin (Java)	~90% — domain whitelist, HMAC verify (constant-time), Redis server registry (delta-sync), TPS-aware load balancer (circuit breaker < 12 TPS)
paper-plugin (Java)	~90% — Redis heartbeat (TPS/online/sec), auto-registration, graceful shutdown
dashboard (React/TS)	~85% — login, Servers/Blacklist/Nodes таблицы, auto-refresh, dark theme
CI/CD	GitHub Actions (Rust check+test+clippy+deny + Java build + Dashboard build + Docker), Makefile, deny.toml
Docs	~80% — architecture, anti-bot, ebpf, ddos, deployment, configuration
Ref analysis	Проанализированы Sonar, LimboFilter, AtomGuard, Infrarust, MC-XDP-eBPF, PowGo
ref/ в .gitignore	Добавлено

❌ Не начато / частично

Компонент	Статус
xdp/xdp_filter.c	0% — пустой каталог
PoW Challenge (Layer 2)	0% — нужно писать
GeoIP/ASN reputation	0% — enum есть, реализации нет
Velocity physics (falling + protocol + vehicle)	0%
Traffic Intelligence (Layer 6)	0% — EWMA, 168h profiling
ClickHouse + Grafana	0%
Bloom filter blacklist	0%

---

2. 6-слойная архитектура (план)

Layer 1: XDP/eBPF (C)        TCP state machine, SYN throttle, blacklist, UDP drop
Layer 2: PoW Challenge (Rust) SHA256 hashcash, dynamic difficulty
Layer 3: Rust Core (Rust)     MC handshake, HMAC sign, rate limit, death code
Layer 4: Velocity (Java)      Domain whitelist, HMAC verify, physics, CAPTCHA
Layer 5: Paper Agent (Java)   Redis heartbeat, auto-registration
Layer 6: Traffic Intel (Rust) EWMA thresholds, 168h profiling, reputation

---

3. Этапы разработки

Этап 4: XDP/eBPF — Layer 1 (сейчас)

Цель: Написать полноценный XDP фильтр с TCP state machine, исправив баги Minecraft-XDP-eBPF.

• Изучен reference Minecraft-XDP-eBPF:

  • Найден TCP handshake deadlock (pure ACK drop)
  • Найден VarInt sign extension UB
  • Найдена stale conntrack на RST/FIN
  • Найден IPv6 bypass
  • Найдена отсутствие LRU на player map

• xdp/xdp_filter.c — TCP state machine (465 строк):

  • AWAIT_ACK → AWAIT_MC_HANDSHAKE → AWAIT_LOGIN → VERIFIED
  • Исправление: pure ACK → PASS, не DROP
  • Исправление: RST/FIN → удалять conntrack entry

• xdp/maps.h — 6 BPF maps:

  • conntrack_map (LRU_HASH, 16384)
  • player_connection_map (LRU_HASH, 65535) — LRU, не plain HASH
  • connection_throttle (LRU_HASH, 65535) — SYN throttle per-IP
  • blacklist_map (LPM_TRIE, 100000) — CIDR blacklist
  • whitelist_map (LPM_TRIE, 1000) — CIDR whitelist
  • stats_map (PERCPU_ARRAY) — счетчики для Prometheus

• xdp/protocol.h — парсеры Minecraft на C

• xdp/varint.h — VarInt (без sign extension UB)

• xdp/config.h — Runtime-конфигурация (volatile const)

• Rust loader (crates/rampart-core/src/xdp/mod.rs):

  • Загрузка .o через libbpf-rs
  • Attach XDP к интерфейсу через bpf_xdp_attach
  • ban_ip / unban_ip / get_stats методы

• build.rs — компиляция .c → .o (clang -target bpf)

• Пропатчить глобальные переменные из config.toml

• Чтение ringbuf → blacklist events

• BPF stats → Prometheus интеграция

• Тесты:

  • hping3 -S --flood → XDP дропает, CPU < 30%
  • iperf3 UDP flood → XDP дропает
  • TCP handshake проверка: Minecraft клиент коннектится без задержки

DoD: SYN flood 1M pps дропается в XDP, TCP handshake без deadlock, CPU < 30%, CI собирает xdp_filter.o

---

Этап 2b: PoW Challenge — Layer 2 (после XDP)

• Challenge generator: случайный token + timestamp + difficulty
• Dynamic difficulty: 4 (спокойно) → 12 (атака) по CPS
• Nonce verification: SHA256(challenge + nonce) prefix check
• Одноразовый challenge (token + timestamp, max 30 сек)
• Интеграция в rampart-core: PoW перед HMAC handshake
• Тесты: PoW solver timing, nonce replay защита, dynamic adjustment

DoD: Edge требует PoW перед handshake, бот не может флудить >50 handshake/сек

---

Этап 4b: Velocity Physics — Layer 4 (после PoW)

• Falling check (pre-computed cache: (0.98^t-1)*3.92, 128 ticks)
  • Исправление: checkY() без fast-forward, сброс ignoredTicks
• Protocol check (Transaction, SetHeldItem, ArmAnimation)
• Vehicle check (Boat gravity + Minecart gravity)
• CAPTCHA (Map item или PoW как fallback)
• HMAC fingerprint (не hashCode!) для verified DB
• Idempotent finishVerification() (нет race condition)

---

Этап 6: Traffic Intelligence — Layer 6

• 168-hour traffic profiling (per-hour-slot baseline)
• EWMA adaptive thresholds (правильная variance формула)
• Z-Score anomaly detection (3 consecutive minutes)
• Attack detection (CPS/PPS thresholds)
• Reputation system (IP score -100..+100)
• Discord webhook на атаки

---

Этап 5: Observability

• ClickHouse writer (batch, раз в сек, буфер 1000)
• Grafana dashboard JSON
• Страница Attack Log в dashboard

---

Этап 6b: Scale + HA

• NATS JetStream (blacklist, drain, audit)
• mTLS между всеми компонентами (rustls)
• Auto-discovery edge нод
• rampart-cli: drain, wg sync, add-node

---

Этап 7: Polish

• io_uring runtime (feature flag)
• Zero-copy splice после handshake
• SLSA Level 3: signed releases, reproducible builds
• secret rotation (dual-key HMAC)

---

4. Backlog

• Bedrock / RakNet (UDP модуль)
• Plugin API через WASM (как Infrarust)
• BGP Anycast (требует AS + /24)
• ML anomaly detection (Isolation Forest — многомерный, не univariate)
• Fuzzing для handshake parser (cargo-fuzz)
• Chaos engineering (random node kills)

---

5. Definition of Done

☐ cargo check / cargo test проходят
☐ cargo clippy -- -D warnings — 0 warnings
☐ cargo fmt --check проходит
☐ Unit тесты покрывают happy path + 2+ error cases
☐ Интеграционный тест проходит
☐ Документация обновлена
☐ CI зелёный

---

6. Anti-Patterns

❌ Тесты после кода. Пиши до (TDD) или вместе.
❌ Коммиты в main напрямую. Только PR.
❌ TODO в коде без issue. TODO = баг.
❌ Оптимизация без профиля.
❌ Зависимость ради 1 функции.
❌ async где хватит sync.
❌ Секреты в репозитории. Используй .env + SOPS.
❌ Игнор compiler warnings.

---

Версия: 2.0 | Обновлён: июль 2026