guard/docs/configuration.md
loki5512344 280284667f
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.
2026-11-16 14:51:50 +01:00

13 KiB
Raw Blame History

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