- 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.
13 KiB
Configuration — Rampart
Единый конфиг edge-ноды (
config.toml) и переменные окружения Manager. Источник правды:src/config/mod.rsиsrc/config/sections/. Меняешь поле — правь эту таблицу в том же PR.
1. Edge (config.toml)
Путь по умолчанию — /etc/rampart/config.toml, переопределяется переменной
RAMPART_CONFIG. Все секции опциональны; при отсутствии используются дефолты из
таблиц ниже. Валидация выполняется до bind сокета: неверное значение — отказ
старта с внятной ошибкой.
1.1 Корень и входящий трафик
# Корневые поля должны стоять до первой TOML-секции.
whitelist = ["127.0.0.1", "::1"]
[bind]
address = "0.0.0.0"
port = 25565
[backend]
upstreams = ["127.0.0.1:25566"]
[workers]
count = 4
[limits]
handshake_timeout_secs = 5
max_connections_per_ip = 10
rate_limit_pps = 5.0
rate_limit_burst = 10.0
relay_idle_timeout_secs = 300
[ban]
ban_duration_secs = 3600
| Поле | По умолчанию | Ограничения и смысл |
|---|---|---|
whitelist |
[] |
Только IP-адреса (без CIDR). Обходят все фильтры, throttle и баны; адрес из whitelist никогда не банится |
bind.address |
0.0.0.0 |
Адрес прослушивания (IPv4 или IPv6) |
bind.port |
25565 |
Защищаемый TCP-порт |
backend.upstreams |
["127.0.0.1:25566"] |
addr:port; список не пуст, каждый адрес валиден; Minecraft требует ровно один |
workers.count |
4 |
Accept-loop'ы с SO_REUSEPORT; ≥ 1 |
limits.handshake_timeout_secs |
5 |
Таймаут handshake/connect (slowloris-защита) |
limits.max_connections_per_ip |
10 |
Одновременные соединения с одного IP; > 0 |
limits.rate_limit_pps |
5.0 |
Новые соединения/с с одного IP; конечно и > 0 |
limits.rate_limit_burst |
10.0 |
Burst token bucket; ≥ 1 |
limits.relay_idle_timeout_secs |
300 |
Простой relay до разрыва; 1..=86400 |
ban.ban_duration_secs |
3600 |
Длительность бана; 1..=31_536_000 (год) |
1.2 PROXY protocol и PoW
[proxy_protocol]
ingress_enabled = false
trusted_cidrs = []
ingress_timeout_ms = 750
max_header_bytes = 512
[pow]
enabled = false
difficulty = 4
| Поле | По умолчанию | Ограничения и смысл |
|---|---|---|
proxy_protocol.ingress_enabled |
false |
Принимать PROXY v2 от внешнего TCP-прокси; требует непустой trusted_cidrs и protocol.minecraft.enabled |
proxy_protocol.trusted_cidrs |
[] |
Точные адреса/CIDR самих прокси, не «весь DC» |
proxy_protocol.ingress_timeout_ms |
750 |
1..=5000 |
proxy_protocol.max_header_bytes |
512 |
52..=4096 |
pow.enabled |
false |
Hashcash-challenge поверх любого TCP; несовместим с protocol.minecraft.enabled |
pow.difficulty |
4 |
Стартовая и минимальная сложность; 1..=10, растёт под нагрузкой |
trusted_cidrs — это адреса самих прокси, а не клиентов: IP из заголовка
используется для per-IP лимитов, репутации и банов, поэтому любой хост внутри
trusted_cidrs может назвать себя кем угодно. Заголовок с адресом из
trusted_cidrs, а также unspecified/loopback/link-local/multicast/broadcast
отклоняется: клиентом считается transport peer (событие пишется в debug один раз
на соединение). Адреса из trusted_cidrs не банятся локально, в Redis и XDP.
1.3 XDP
[xdp]
enabled = false
interface = "eth0"
protected_port_start = 1
protected_port_end = 65535
udp_policy = "pass"
udp_rate_hit_count = 100
udp_rate_window_ms = 1000
throttle_enabled = true
events_enabled = true
auto_ban_enabled = false
auto_ban_duration_secs = 60
auto_ban_conn_drop_fails = 3
syn_challenge_enabled = false
challenge_secret_hex = "" # обязателен при syn_challenge_enabled
challenge_timeout_ms = 3000
| Поле | По умолчанию | Что делает |
|---|---|---|
enabled |
false |
Загрузить и приаттачить программу; требует сборки --features xdp |
interface |
eth0 |
Интерфейс; сначала native XDP, при отказе драйвера — generic (skb) |
protected_port_start / _end |
1 / 65535 |
Порт-гейт: трафик вне диапазона не фильтруется |
udp_policy |
pass |
pass, drop или rate-limit (окно по source-IP) |
udp_rate_hit_count / udp_rate_window_ms |
100 / 1000 |
Порог и окно для rate-limit |
throttle_enabled |
true |
SYN-throttle и авто-бан по connection_throttle (IPv4) |
events_enabled |
true |
Ringbuf-события в userspace (IPv4) |
auto_ban_enabled |
false |
OPT-IN: баны по событиям ringbuf |
auto_ban_duration_secs |
60 |
Длительность авто-бана |
auto_ban_conn_drop_fails |
3 |
Порог conn->fails для бана по EVENT_CONN_DROP |
syn_challenge_enabled |
false |
RST-challenge (Oubliette-style liveness proof), IPv4 |
challenge_secret_hex |
— | 128-битный hex-секрет (openssl rand -hex 8); placeholder запрещён |
challenge_timeout_ms |
3000 |
TTL pending-challenge |
Поведение фильтра:
- Stateless-фильтр, не firewall. Conntrack ведётся только для TCP-соединений, начатых с SYN; пакет без состояния (non-SYN) пропускается, чтобы фильтр не рвал ответы на исходящие соединения демона и keep-alive health-check'ов.
- VLAN/QinQ (802.1Q и 802.1ad, до двух тегов) разбираются; фрагменты
проверяются по source-IP в blacklist и пропускаются, счётчик —
fragment_bypass. - Whitelist загружается в
whitelist_map/whitelist6_mapпри attach и обходит state machine, throttle и баны. - CIDR-баны матчатся LPM-трией; userspace — диапазонами, поэтому
/24и/64покрывают всю подсеть. - Оценка числа источников в префиксе: XDP ведёт 64-битный bitmap хешей source-адресов, userspace считает popcount (spoof-gate работает и на XDP-пути). Счётчики префиксов сбрасываются при чтении, окно = интервал опроса монитора.
Покрытие семейств:
- IPv4: blacklist, SYN-throttle, conntrack, RST-challenge, ringbuf-события,
udp_policy(включаяrate-limit), prefix-статистика. - IPv6: blacklist, whitelist,
udp_policy(включаяrate-limitс 128-битным ключом), детект TCP-bypass, prefix-статистика. Пока нет: conntrack, SYN-throttle, RST-challenge, ringbuf-события и unban — для v6 только счётчики.
1.4 Детекция и алерты
[detect.prefix]
enabled = false
syn_threshold = 500
window_secs = 10
min_unique_sources = 16
[detect.autoban]
enabled = false
reputation_threshold = -50
[detect.alert]
webhook_url = ""
| Поле | По умолчанию | Смысл |
|---|---|---|
detect.prefix.enabled |
false |
Детектор атак на уровне подсети (/24, /64) |
detect.prefix.syn_threshold |
500 |
Порог соединений на префикс в окне; при enabled обязан быть > 0 |
detect.prefix.window_secs |
10 |
Окно детектора |
detect.prefix.min_unique_sources |
16 |
Минимум уникальных источников (spoof-gate) |
detect.autoban.enabled |
false |
Авто-бан по score репутации |
detect.autoban.reputation_threshold |
-50 |
Порог score; TTL — ban.ban_duration_secs |
detect.alert.webhook_url |
— | Webhook на переход состояния атаки |
1.5 Протоколы, логи, метрики, хранилища
[protocol.http]
max_header_bytes = 8192
timeout_secs = 5
blocked_paths = ["/wp-login.php"]
require_user_agent = false
[protocol.minecraft]
enabled = true
max_frame_bytes = 8192
timeout_secs = 5
send_proxy_protocol = false
[logging]
level = "info"
format = "text"
[metrics]
enabled = true
port = 9090
[store]
redis_url = ""
blacklist_cache_ttl_secs = 300
clickhouse_url = ""
| Поле | По умолчанию | Смысл |
|---|---|---|
protocol.http.max_header_bytes |
8192 |
Лимит request-head; > 0 |
protocol.http.timeout_secs |
5 |
Таймаут чтения заголовков; > 0 |
protocol.http.blocked_paths |
[] |
Точные пути, которые отклоняются |
protocol.http.require_user_agent |
false |
Отклонять запросы без User-Agent |
protocol.minecraft.enabled |
true при сборке без protocol-http |
Активный MC-handler |
protocol.minecraft.max_frame_bytes |
8192 |
Лимит кадра; > 0 |
protocol.minecraft.timeout_secs |
5 |
Таймаут handshake; > 0 |
protocol.minecraft.send_proxy_protocol |
false |
Отправлять PROXY v2 на Paper; alias — proxy_protocol |
logging.level |
info |
trace, debug, info, warn, error |
logging.format |
text |
text или json |
metrics.enabled |
true |
Prometheus endpoint |
metrics.port |
9090 |
Порт метрик |
store.redis_url |
— | Пусто = синхронизация банов выключена |
store.blacklist_cache_ttl_secs |
300 |
TTL локального кеша blacklist |
store.clickhouse_url |
— | Пусто = запись событий выключена |
[protocol.http] существует только при сборке с protocol-http,
[protocol.minecraft] — только с protocol-minecraft; секция без
соответствующей фичи игнорируется. Для HTTP удали [protocol.minecraft].
2. Manager (переменные окружения)
| Переменная | Обязательна | По умолчанию | Описание |
|---|---|---|---|
REDIS_URL |
нет | redis://127.0.0.1:6379/0 |
Хранилище состояния |
JWT_SECRET |
да | — | Минимум 32 непробельных байта |
JWT_AUDIENCE |
нет | rampart |
Audience JWT |
JWT_EXPIRATION_SECS |
нет | 86400 |
Время жизни токена |
API_PASSWORD |
да | — | Пароль для /api/v1/auth/login, минимум 16 символов; changeme запрещён |
CORS_ORIGIN |
нет | — | * — разрешить всё; список origin'ов через запятую; пусто — cross-origin запрещён |
MANAGER_TRUSTED_PROXIES |
нет | — | Сети reverse-прокси через запятую. X-Forwarded-For учитывается только для запросов из этих сетей; опечатка/пустая запись → отказ старта |
Manager всегда слушает 0.0.0.0:8080.
3. Feature flags сборки
| Feature | По умолчанию | Что включает |
|---|---|---|
store-redis |
✅ | Redis-клиент и синхронизация blacklist |
geoip |
❌ | GeoIP lookup (maxminddb; реализация — roadmap v0.5) |
xdp |
❌ | Загрузка XDP-программы через libbpf-rs |
io-uring |
❌ | splice/io_uring I/O (реализация — roadmap v0.6) |
protocol-http |
❌ | HTTP/1.1 handler |
protocol-minecraft |
❌ | Minecraft Java handshake и проксирование |
cargo build --release --features xdp,protocol-http --bin rampart
4. BPF/XDP программа
Исходник — xdp/core/universal_filter.c. Smoke-check компиляции:
mkdir -p target/xdp
clang -O2 -g -target bpf -I"/usr/include/$(gcc -print-multiarch)" \
-c xdp/core/universal_filter.c -o target/xdp/universal_filter.o
-I с multiarch нужен, потому что -target bpf не ищет
/usr/include/<triple> по умолчанию. Полный прогон на реальном ядре —
scripts/xdp_ci.sh (см. testing.md).
Версия: 3.0 | Ноябрь 2026