feat(xdp): IPv6 UDP rate limit, working loader; English comments and docs

XDP behaviour:
- udp_rate_limit6 (LRU, full 128-bit source key) plus throttle_hit6, so
  udp_policy = "rate-limit" applies to native IPv6 as well.
- scripts/xdp_ipv6_smoke.sh: phase 4 patches .rodata before load and
  verifies policy=2 on a real kernel (3 pass / 3 rate-limited).

Loader (XDP could never load before this):
- .rodata is one struct rampart_config with frozen offsets enforced by
  _Static_assert; XdpGlobals is #[repr(C)] and the image is built with
  offset_of!. Before, a 96-byte image was written into a 76-byte map at
  offsets clang had reordered, so load() failed with EINVAL.
- patch_rodata fails loudly when the map size and image size diverge.
- build.rs tracks xdp/core and xdp/hooks, not just universal_filter.c.
- build_ringbuf looked for "events_map"; the map is "events_ringbuf".
- tests/xdp_object_maps.rs checks map names and .rodata size without root.

Docs and style:
- Code comments are English, JavaDoc/Rustdoc style, without emoji or
  banners (new project rule, TODO §0.8).
- README rewritten bilingual: Russian first, English below, nav buttons,
  compact TOC and copy-paste quick start.
- docs/README.md: documentation index and maintenance rules;
  configuration.md documents the whole [xdp] section and IPv4/IPv6
  coverage; testing.md covers the real-kernel smoke; stale links removed.
This commit is contained in:
Loki 2026-11-15 23:50:52 +01:00
parent b64c329125
commit a8a3057719
Signed by: boba
GPG key ID: 6CDE87BC9A778D97
104 changed files with 2155 additions and 1030 deletions

View file

@ -1,7 +1,7 @@
//! Traffic Intelligence в hot path: репутация → авто-бан → метрики окна.
//! Traffic Intelligence in the hot path: reputation, auto-ban and window metrics.
//!
//! Все вызовы из accept-пути дешёвые (DashMap/атомики), блокирующего
//! ввода-вывода нет.
//! Every call reachable from the accept path is cheap (DashMap/atomics) and
//! performs no blocking I/O.
use crate::config::DetectAutobanConfig;
use crate::filter::blacklist::Blacklist;
@ -15,10 +15,10 @@ use std::time::Duration;
const BAN_REASON_LOW_REPUTATION: &str = "low_reputation";
const BAN_REASON_ATTACK: &str = "attack_detector";
/// Точка входа Traffic Intelligence для сетевого пути.
/// Entry point of Traffic Intelligence on the network path.
///
/// События: новое соединение (`on_accept`), завершение обработки соединения
/// (`on_connection_end`), эскалация детектора атак (`ban_offenders`).
/// Events: a new connection (`on_accept`), a finished connection
/// (`on_connection_end`) and attack-detector escalation (`ban_offenders`).
pub struct TrafficHook {
reputation: Arc<IpReputation>,
blacklist: Arc<Blacklist>,
@ -43,13 +43,18 @@ impl TrafficHook {
}
}
/// Новое соединение принято accept-loop'ом. Только счётчик окна cps.
/// A new connection was accepted by the accept loop.
///
/// Only bumps the cps window counter; the counter is drained by
/// [`Self::take_cps`] once per second.
pub fn on_accept(&self) {
self.conn_window.fetch_add(1, Ordering::Relaxed);
}
/// Соединение обработано. Если источник попал под rate-limit (репутация
/// упала до порога) — авто-бан с TTL из конфига.
/// A connection finished processing.
///
/// If the source was pushed down to the reputation threshold, it is banned
/// with the TTL taken from the config.
pub fn on_connection_end(&self, ip: IpAddr) {
if !self.autoban.enabled || self.blacklist.is_blocked(ip) {
return;
@ -57,8 +62,10 @@ impl TrafficHook {
self.autoban_if_toxic(ip, BAN_REASON_LOW_REPUTATION);
}
/// Эскалация детектора атак: бан всех источников ниже порога репутации.
/// Вызывается один раз на переход в `UnderAttack`, не на каждый тик.
/// Attack-detector escalation: bans every source below the reputation
/// threshold and returns how many bans were issued.
///
/// Called once on the transition into `UnderAttack`, not on every tick.
pub fn ban_offenders(&self) -> usize {
if !self.autoban.enabled {
return 0;
@ -75,7 +82,7 @@ impl TrafficHook {
banned
}
/// Забирает накопленное окно новых соединений за секунду (cps).
/// Takes the accumulated one-second window of new connections (cps).
pub fn take_cps(&self) -> u64 {
self.conn_window.swap(0, Ordering::Relaxed)
}
@ -206,7 +213,7 @@ mod tests {
enabled: true,
reputation_threshold: -50,
},
// Короткий TTL как мок времени: бан жив, потом истекает.
// Zero TTL as a time mock: the ban must be dead on arrival.
0,
);
let target = ip([10, 3, 0, 1]);

View file

@ -28,8 +28,12 @@ impl AttackDetector {
}
}
/// Анализирует окно метрик (пакеты/с и новые соединения/с) относительно
/// накопленных профилей. Аномалией считается всплеск любой из метрик.
/// Analyses one metrics window (packets/s and new connections/s) against
/// the accumulated profiles.
///
/// A spike in either metric counts as an anomaly. Three consecutive
/// anomalous windows escalate to [`AttackStatus::UnderAttack`]; a single
/// one above the suspicious score yields [`AttackStatus::Suspicious`].
pub fn analyze(&mut self, pps: f64, cps: f64) -> AttackStatus {
self.pps_profiler.record(pps);
self.cps_profiler.record(cps);

View file

@ -1,4 +1,7 @@
//! Интеллект трафика: EWMA-сглаживание, детектор атак и репутация IP.
//! Traffic intelligence: EWMA smoothing, attack detector and per-IP reputation.
//!
//! Owns the scoring primitives consumed by [`crate::traffic::hook`]; the
//! modules are also re-exported at `traffic::{ewma, detector, reputation}`.
pub mod detector;
pub mod ewma;
pub mod reputation;

View file

@ -33,7 +33,10 @@ impl IpReputation {
self.scores.get(&ip).map(|v| *v).unwrap_or(0)
}
/// Возвращает источники со скором не выше `threshold` (нарушители).
/// Returns the sources scored at or below `threshold` (the offenders).
///
/// The result is a snapshot copy, so it is safe to ban from it while other
/// threads keep recording events.
pub fn offenders_below(&self, threshold: i32) -> Vec<IpAddr> {
self.scores
.iter()

View file

@ -1,11 +1,15 @@
//! Профилирование трафика, детектор атак и репутация IP.
//! Traffic profiling, attack detection and per-IP reputation.
//!
//! Owns the state the edge node feeds from the accept path: [`hook::TrafficHook`]
//! wires reputation, auto-ban and window metrics together, while the `intel`,
//! `prefix` and `profile` submodules hold the detectors themselves.
pub mod hook;
pub mod intel;
pub mod prefix;
pub mod profile;
// Совместимость путей после группировки: домены `intel/` и `profile/`
// остаются доступны по прежним путям `traffic::{detector, ewma, ...}`.
// Re-exported under the old paths (`traffic::{detector, ewma, ...}`) so the
// grouping into `intel/` and `profile/` stays source-compatible.
pub use intel::{detector, ewma, reputation};
pub use profile::{alert, profiler};

View file

@ -1,11 +1,11 @@
use std::net::{IpAddr, Ipv4Addr, Ipv6Addr};
/// `family` для IPv4-префиксов (/24).
/// `family` tag for IPv4 prefixes (/24).
pub const PREFIX_FAMILY_V4: u8 = 4;
/// `family` для IPv6-префиксов (/64).
/// `family` tag for IPv6 prefixes (/64).
pub const PREFIX_FAMILY_V6: u8 = 6;
/// Ключ карты `prefix_stats` (`BPF_MAP_TYPE_LRU_HASH`, max_entries 65536).
/// Key of the `prefix_stats` map (`BPF_MAP_TYPE_LRU_HASH`, 65536 entries).
#[repr(C)]
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
pub struct PrefixKey {
@ -15,7 +15,8 @@ pub struct PrefixKey {
}
impl PrefixKey {
/// Строит ключ префикса для адреса (v4 → /24 в первых 4 байтах, v6 → /64).
/// Builds the prefix key for an address (v4 maps to /24 in the first four
/// bytes, v6 maps to /64).
#[must_use]
pub fn new(ip: IpAddr) -> Self {
let mut key = Self::default();
@ -32,7 +33,7 @@ impl PrefixKey {
key
}
/// Префикс как IP-адрес (маскированный).
/// The prefix as a masked IP address; `None` for an unknown `family` tag.
#[must_use]
pub fn to_prefix(self) -> Option<IpAddr> {
match self.family {
@ -66,13 +67,14 @@ impl PrefixKey {
}
}
/// Возвращает префикс адреса: IPv4 и IPv4-mapped → /24, IPv6 → /64.
/// Returns the prefix of an address: IPv4 and IPv4-mapped share /24, IPv6 uses /64.
#[must_use]
pub fn prefix_of(ip: IpAddr) -> IpAddr {
match ip {
IpAddr::V4(v4) => IpAddr::V4(masked_v4(v4)),
IpAddr::V6(v6) => match v6.to_ipv4_mapped() {
// ::ffff:a.b.c.d живёт в том же /24-пространстве, что и a.b.c.d.
// ::ffff:a.b.c.d must land in the same /24 bucket as a.b.c.d,
// otherwise a dual-stack client could escape its own ban.
Some(v4) => IpAddr::V4(masked_v4(v4)),
None => IpAddr::V6(Ipv6Addr::from(masked_v6_segments(v6))),
},

View file

@ -1,9 +1,9 @@
//! Subnet-level (prefix) детектор распределённых атак.
//! Subnet-level (prefix) distributed attack detector.
//!
//! Источник данных — трейт [`PrefixStatsSource`]: карта XDP `prefix_stats`
//! (feature `xdp`) либо юзерспейс-агрегатор [`crate::engine::subnet_tracker`].
//! Контракт с XDP-агентом: [`PrefixKey`] / [`PrefixStatsVal`] должны совпадать
//! побайтово со структурами ядра.
//! Data arrives through the [`PrefixStatsSource`] trait: either the XDP
//! `prefix_stats` map (feature `xdp`) or the user-space aggregator in
//! [`crate::engine::subnet_tracker`]. [`PrefixKey`] and [`PrefixStatsVal`] must
//! match the kernel structs byte for byte, hence the `repr(C)` layout.
mod key;
mod stats;

View file

@ -2,7 +2,7 @@ use anyhow::Result;
use std::future::Future;
use std::net::IpAddr;
/// Значение карты `prefix_stats`.
/// Value of the `prefix_stats` map.
#[repr(C)]
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
pub struct PrefixStatsVal {
@ -12,7 +12,7 @@ pub struct PrefixStatsVal {
}
impl PrefixStatsVal {
/// Разбирает сырые 24 байта значения карты.
/// Parses the raw 24-byte map value.
#[must_use]
pub fn from_bytes(bytes: [u8; 24]) -> Self {
let read_u64 =
@ -24,7 +24,7 @@ impl PrefixStatsVal {
}
}
/// Сериализует значение в сырые 24 байта карты.
/// Serialises the value into the raw 24-byte map layout.
#[must_use]
pub fn to_bytes(self) -> [u8; 24] {
let mut out = [0u8; 24];
@ -35,10 +35,10 @@ impl PrefixStatsVal {
}
}
/// Агрегат по одному префиксу за окно детекции.
/// Aggregated counters for one prefix over a detection window.
///
/// `unique_sources == 0` означает, что источник не считает уникальные адреса
/// (XDP-путь); spoof-gate в этом случае Block не подтверждает.
/// `unique_sources == 0` means the source does not count distinct addresses
/// (the XDP path), and the spoof gate then never confirms `Block`.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
pub struct PrefixSnapshot {
pub syn_count: u64,
@ -47,16 +47,17 @@ pub struct PrefixSnapshot {
pub unique_sources: u64,
}
/// Источник агрегатов по префиксам. Позволяет тестам работать без ядра.
/// Source of per-prefix aggregates; keeps tests independent of the kernel.
pub trait PrefixStatsSource {
/// Снимок агрегатов за текущее окно.
/// Snapshot of the aggregates for the current window.
///
/// # Errors
/// Ошибка чтения источника (карта не загружена, BPF-сбой и т.п.).
/// Returns an error when the source cannot be read (map not loaded, BPF
/// failure and similar).
fn snapshot(&self) -> impl Future<Output = Result<Vec<(IpAddr, PrefixSnapshot)>>> + Send;
}
/// Эскалация вердиктов subnet-level детектора.
/// Verdict escalation ladder of the subnet-level detector.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum SubnetVerdict {
Monitor,
@ -65,7 +66,7 @@ pub enum SubnetVerdict {
Block,
}
/// Вердикт по одному префиксу.
/// Verdict for a single prefix.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct PrefixVerdict {
pub prefix: IpAddr,
@ -73,12 +74,13 @@ pub struct PrefixVerdict {
pub snapshot: PrefixSnapshot,
}
/// Детектор распределённых атак по префиксам.
/// Detector for distributed attacks at prefix granularity.
///
/// Лестница эскалации по `syn_count` за окно: `< threshold` → Monitor,
/// `< 2×threshold` → StrictLimit, иначе Challenge; Block только при
/// `≥ 4×threshold` И прохождении spoof-gate (≥ `min_unique_sources`
/// уникальных IP — защита от ложного бана CGNAT/спуфинга).
/// Escalation ladder over the `syn_count` of one window: below `threshold` is
/// `Monitor`, below `2 x threshold` is `StrictLimit`, anything higher is
/// `Challenge`. `Block` requires at least `4 x threshold` *and* a passed spoof
/// gate (at least `min_unique_sources` distinct IPs), which guards against
/// false bans of CGNAT ranges and spoofed sources.
#[derive(Debug, Clone)]
pub struct SubnetDetector {
syn_threshold: u64,
@ -99,7 +101,7 @@ impl SubnetDetector {
Self::new(config.syn_threshold, config.min_unique_sources)
}
/// Оценивает снимок и возвращает вердикты по активным префиксам.
/// Evaluates a snapshot and returns verdicts for all active prefixes.
#[must_use]
pub fn evaluate(&self, snapshots: &[(IpAddr, PrefixSnapshot)]) -> Vec<PrefixVerdict> {
snapshots
@ -131,14 +133,15 @@ impl SubnetDetector {
#[must_use]
fn spoof_gate_passed(&self, snap: &PrefixSnapshot) -> bool {
// gate отключён (min_unique_sources == 0) либо подтверждено разнообразие.
// The gate is disabled (min_unique_sources == 0) or diversity is confirmed.
self.min_unique_sources == 0 || snap.unique_sources >= self.min_unique_sources
}
}
/// Реализация [`PrefixStatsSource`] поверх XDP-фильтра (feature `xdp`).
/// Читает карту `prefix_stats`; уникальные источники ядро не считает,
/// поэтому spoof-gate на этом пути Block не подтверждает.
/// [`PrefixStatsSource`] backed by the XDP filter (feature `xdp`).
///
/// Reads the `prefix_stats` map. The kernel does not track distinct source
/// addresses, so the spoof gate never confirms `Block` on this path.
#[cfg(feature = "xdp")]
pub struct XdpPrefixStats {
filter: std::sync::Arc<std::sync::Mutex<crate::xdp::XdpFilter>>,
@ -151,10 +154,11 @@ impl XdpPrefixStats {
Self { filter }
}
/// Блокирует мьютекс фильтра (для kernel-enforcement вердиктов).
/// Locks the filter mutex (needed for kernel enforcement of verdicts).
///
/// # Panics
/// Если мьютекс отравлен (паника в другом потоке во время удержания).
/// Panics if the mutex is poisoned, that is, if another thread panicked
/// while holding it.
pub fn filter_lock(&self) -> std::sync::MutexGuard<'_, crate::xdp::XdpFilter> {
self.filter.lock().expect("xdp lock poisoned")
}

View file

@ -56,9 +56,11 @@ impl fmt::Display for Alert {
}
}
/// Дедуплицирующий диспетчер алертов: алерт выдаётся только на переходе
/// состояния детектора (вход в `UnderAttack` и выход из него), не на каждом
/// тике. Логика — poll-and-persist (LNVPS issue #331).
/// Deduplicating alert dispatcher.
///
/// An alert is emitted only on a detector state transition (entering
/// `UnderAttack` and leaving it), never on every tick. The behaviour is
/// poll-and-persist: the previous status is kept as the baseline.
#[derive(Default)]
pub struct AlertDispatcher {
previous: Mutex<Option<AttackStatus>>,
@ -69,9 +71,11 @@ impl AlertDispatcher {
Self::default()
}
/// Возвращает `Some(Alert)` только при переходе через границу атаки:
/// вход в `UnderAttack` («attack started») или выход из него
/// («attack ended»). Первое наблюдение алерта не порождает.
/// Returns `Some(Alert)` only when the attack boundary is crossed: entering
/// `UnderAttack` ("attack started") or leaving it ("attack ended").
///
/// The first observation never produces an alert, so a node that starts up
/// during an attack does not report a transition it never saw.
pub fn on_status(&self, status: AttackStatus) -> Option<Alert> {
let mut previous = self.previous.lock().expect("alert dispatcher lock poisoned");
if *previous == Some(status) {
@ -89,9 +93,10 @@ impl AlertDispatcher {
}
}
/// Отправляет алерт на webhook (fire-and-forget, с таймаутом).
/// Delivers an alert to a webhook (fire-and-forget, with a timeout).
///
/// Вызывать следует из фоновых задач: сетевой ввод-вывод недопустим в hot path.
/// Call it from background tasks only: network I/O is not allowed on the hot
/// path.
pub async fn send_webhook(url: String, alert: Alert) {
let payload = serde_json::json!({
"level": alert.level.to_string(),

View file

@ -1,3 +1,6 @@
//! Профилирование трафика edge-ноды и алерты детектора атак.
//! Edge-node traffic profiling and attack-detector alerts.
//!
//! Owns the sliding EWMA profiler and the deduplicating alert dispatcher;
//! both are re-exported at `traffic::{profiler, alert}`.
pub mod alert;
pub mod profiler;