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:
parent
b64c329125
commit
a8a3057719
104 changed files with 2155 additions and 1030 deletions
|
|
@ -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]);
|
||||
|
|
|
|||
|
|
@ -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);
|
||||
|
|
|
|||
|
|
@ -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;
|
||||
|
|
|
|||
|
|
@ -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()
|
||||
|
|
|
|||
|
|
@ -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};
|
||||
|
|
|
|||
|
|
@ -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))),
|
||||
},
|
||||
|
|
|
|||
|
|
@ -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;
|
||||
|
|
|
|||
|
|
@ -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")
|
||||
}
|
||||
|
|
|
|||
|
|
@ -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(),
|
||||
|
|
|
|||
|
|
@ -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;
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue