guard/docs
loki5512344 14dcaccdbf
fix(xdp): correct payload length, attach/detach, whitelist and ban upkeep
BPF program (the first two made the filter wrong on real hardware):
- Compute the TCP payload length from ip->tot_len (IPv4) / payload_len
  (IPv6) instead of data_end. Ethernet padding on a real NIC added 6 bogus
  payload bytes, broke expected_seq and dropped every connection after the
  fourth segment. scripts/xdp_pkt_test.sh reproduces it on synthetic frames
  and fails against the old code.
- Read map values (conn->fails, sent_at) before bpf_map_delete_elem; the LRU
  element is freed by the delete.
- Parse up to two VLAN/QinQ tags before L3; fragments are checked against the
  blacklist and passed instead of bypassing all filtering; first fragments are
  no longer dropped.
- Unknown non-SYN flows PASS: the program is a stateless filter fed by the
  conntrack state machine, not a firewall, so spoofed SYNs cannot evict
  established flows into a drop and replies to the daemon's own outbound TCP
  keep working.
- Reset conn->fails on in-order segments, honour SYN payload (TFO), fix the
  IPv6 SYN-ACK address swap, count every DROP path, drop SYN with IP options.
- Expired prefix bans are no longer deleted with the wrong LPM key; userspace
  reaps them with the exact key.

Loader:
- Remember the effective attach flags (native vs generic) and use them for
  detach/query, verifying the interface is clean afterwards. The old code
  always detached the native slot, leaving a generic program attached after
  shutdown.
- DetachGuard rolls back the attach if anything after it fails.
- ban_cidr validates the prefix length and masks host bits.
- Whitelist maps (v4 and the new v6 LPM trie) are populated from the config at
  startup and fail fast on error.
- Stats read all 13 counters, and a test asserts every map's key/value size
  against the Rust encodings.

Tests: xdp_pkt_test (padding, VLAN/QinQ, fragments), xdp_loader (attach flags,
rollback, detach), xdp_ban_keys, xdp_whitelist_keys, xdp_services, live
xdp_attach_smoke (ignored, needs root).
2026-11-16 12:06:05 +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 feat(xdp): IPv6 UDP rate limit, working loader; English comments and docs 2026-11-15 23:50:52 +01:00
deployment.md Update links to the new GitHub account 2026-10-25 19:14:54 +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 и проверь, что цели существуют.