guard/docs
loki5512344 c1a076a4a3
fix(core): close auth bypass, hangs and memory leaks found by review
Security:
- An empty API_PASSWORD passed validation (only the literal "changeme" was
  rejected) and verify_password("", "") returned true, so a login with an
  empty password minted an admin token. Require >= 16 characters and >= 32
  non-whitespace bytes for JWT_SECRET; verify rejects an empty stored secret.
- syn_challenge_enabled required a real challenge_secret_hex: the public
  placeholder from config.h is now rejected in every spelling.
- docker-compose: Redis/ClickHouse/Grafana are loopback-only and every
  password uses ${VAR:?} instead of a default. An exposed Redis was a way to
  lift bans and publish unbans to the whole fleet with one redis-cli.
- Empty CORS_ORIGIN no longer means "allow any origin".
- ban_cidr / userspace blacklist validate and mask prefixes; CIDR bans are
  stored as ranges, so a /24 or /64 ban actually covers the subnet (before,
  only the network address was blocked).

Availability:
- ClickHouse client has connect/request timeouts and no mutex held across
  await: a hung analytics backend can no longer freeze the ban path. Events
  go through a bounded buffer with a drop counter.
- Redis uses a ConnectionManager with per-command timeouts; pubsub and
  reconcile reset the backoff after success; publish cannot block shutdown.
- Ban durations from pubsub are clamped and use checked_add; the sync task
  survives panics instead of silently dying.
- Blacklist TOCTOU (remove_if) and replace_redis no longer empties the table
  during a Redis reconnect.
- RateLimiter and reputation have hard caps with incremental eviction instead
  of an unbounded DashMap and a stop-the-world retain.
- The attack detector scores before updating its baseline and needs several
  quiet windows to leave UnderAttack, so a sustained flood keeps banning new
  offenders instead of ending after one tick.
- accept() backs off on EMFILE/ENFILE, shutdown Err is treated as shutdown,
  a global semaphore bounds in-flight connections, rate limiting runs before
  PoW, whitelisted IPs are never banned, and connect/handshake/relay have
  timeouts with an idle budget.
- PoW uses the configured difficulty as a floor, the clamp is enforced, and
  nonce framing survives split segments and coalesced handshake bytes.
- Subnet tracker memory is capped (prefixes and per-prefix sources) and the
  monitor bans with the configured TTL.

CI and docs:
- CI runs the test suite with --no-default-features --features protocol-http;
  make ebpf fails on errors; the secrets gate catches weak compose defaults.
- doctor skips protected endpoints without a token and exits non-zero on
  failure; a drain timeout returns exit code 1.
- TODO §2b records the review findings, what is fixed and what is deferred;
  configuration/testing docs describe the new XDP and secret semantics.
2026-11-16 12:06:23 +01:00
..
kb feat!: universal redesign — drop Minecraft stack, single-crate architecture 2026-08-24 01:50:22 +02:00
research feat(xdp): IPv6 UDP rate limit, working loader; English comments and docs 2026-11-15 23:50:52 +01:00
api.md fix: report unsupported CLI operations honestly 2026-10-16 23:15:33 +02:00
configuration.md fix(core): close auth bypass, hangs and memory leaks found by review 2026-11-16 12:06:23 +01:00
deployment.md fix(core): close auth bypass, hangs and memory leaks found by review 2026-11-16 12:06:23 +01:00
disaster_recovery.md feat: sync edge autobans across nodes 2026-10-16 23:09:26 +02:00
minecraft-java.md docs: clarify private network deployment 2026-10-16 23:16:20 +02:00
README.md feat(xdp): IPv6 UDP rate limit, working loader; English comments and docs 2026-11-15 23:50:52 +01:00
runbook.md docs: update protocol troubleshooting guidance 2026-10-16 23:20:42 +02:00
testing.md fix(xdp): correct payload length, attach/detach, whitelist and ban upkeep 2026-11-16 12:06:05 +01:00
troubleshooting.md docs: update protocol troubleshooting guidance 2026-10-16 23:20:42 +02:00
vds_compatibility.md feat!: universal redesign — drop Minecraft stack, single-crate architecture 2026-08-24 01:50:22 +02:00

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

Индекс всей документации проекта и правила её ведения. Точка входа — README.md; текущий статус и планы — TODO.md.


1. С чего начать

Документ Когда читать
deployment.md Первый деплой edge-ноды и manager'а
configuration.md Настройка config.toml, секция [xdp], переменные manager'а
runbook.md Ежедневная эксплуатация и типовые операции

2. Эксплуатация (how-to)

Документ О чём
runbook.md Метрики, рестарты, снятие банов, аварийные процедуры
troubleshooting.md Диагностика типовых проблем
disaster_recovery.md Восстановление после отказа Redis/ноды
testing.md Гейты, тесты, XDP-smoke на реальном ядре

3. Справочник (reference)

Документ О чём
configuration.md Все поля конфига и значения по умолчанию
api.md HTTP API manager'а: аутентификация, эндпоинты
vds_compatibility.md Ограничения окружений и ядер

4. Протоколы

Документ О чём
minecraft-java.md Minecraft-edge: Paper, PROXY protocol, закрытый backend

5. Теория и исследования

Раздел О чём
kb/ База знаний: анатомия атак, уровни защиты, практика (двуязычная)
research/ Глубокие разборы: архитектура, eBPF, DDoS, Rust-производительность, конкуренты

kb/ отвечает на вопрос «как это работает и как защищаться», research/ — на вопрос «какое решение выбрать и почему». Статус проекта не живёт ни там, ни там — только в TODO.md.


6. Как вести документацию

  1. Язык. docs/ — русский. Исключение: docs/kb/, где статьи двуязычные (## English / ## Русский). Комментарии в коде — английский (TODO §0.8).
  2. Один документ = одна задача. How-to начинается с цели («что получится в конце»), содержит копируемые команды и заканчивается проверкой результата.
  3. Reference синхронизируется с кодом в том же PR. Меняешь поле конфига, флаг CLI или эндпоинт — правишь configuration.md / api.md там же. Расхождение = баг.
  4. Новый документ кладётся в подходящую категорию (2–4) и сразу добавляется в эту таблицу; если он является точкой входа — ссылка добавляется и в корневой README.
  5. Не размножай папки. Плоская структура docs/*.md — норма; подпапка нужна только для серии документов (kb/, research/).
  6. Имена файлов — kebab-case, .md, без дат в имени; дата и версия — внутри документа.
  7. Никаких битых ссылок. Перед коммитом: grep -o '](\.\?[^)]*)' docs/*.md и проверь, что цели существуют.