feat: subnet-level attack detection (prefix_stats)

- XDP: prefix_stats LRU map, per-/24 (v4) and /64 (v6) SYN/packet counters,
  incremented post-blacklist/throttle (xdp/core/prefix_stats.h)
- userspace: SubnetDetector escalation ladder Monitor->StrictLimit->Challenge->Block
  with spoof-gate (Block requires >= min_unique_sources, CGNAT-safe)
- config: [detect.prefix] section (enabled=false by default)
- fallback without XDP: engine SubnetTracker aggregates connections per-prefix
- fix: PrefixStatsVal::from_bytes for xdp feature build; prefix_len 24 vs 64

cargo build/clippy(-D warnings, all features)/test green: 83 tests
This commit is contained in:
Loki 2026-08-24 09:47:21 +02:00
parent 08e26df73f
commit 5d7cdc24e3
Signed by: boba
GPG key ID: 6CDE87BC9A778D97
14 changed files with 1044 additions and 11 deletions

View file

@ -3,5 +3,6 @@
pub mod alert;
pub mod detector;
pub mod ewma;
pub mod prefix;
pub mod profiler;
pub mod reputation;

296
src/traffic/prefix.rs Normal file
View file

@ -0,0 +1,296 @@
//! Subnet-level (prefix) детектор распределённых атак.
//!
//! Источник данных — трейт [`PrefixStatsSource`]: карта XDP `prefix_stats`
//! (feature `xdp`) либо юзерспейс-агрегатор [`crate::engine::subnet_tracker`].
//! Контракт с XDP-агентом: [`PrefixKey`] / [`PrefixStatsVal`] должны совпадать
//! побайтово со структурами ядра.
use anyhow::Result;
use std::future::Future;
use std::net::{IpAddr, Ipv4Addr, Ipv6Addr};
/// `family` для IPv4-префиксов (/24).
pub const PREFIX_FAMILY_V4: u8 = 4;
/// `family` для IPv6-префиксов (/64).
pub const PREFIX_FAMILY_V6: u8 = 6;
/// Ключ карты `prefix_stats` (`BPF_MAP_TYPE_LRU_HASH`, max_entries 65536).
#[repr(C)]
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
pub struct PrefixKey {
pub family: u8,
pub pad: [u8; 7],
pub addr: [u8; 16],
}
/// Значение карты `prefix_stats`.
#[repr(C)]
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
pub struct PrefixStatsVal {
pub syn_count: u64,
pub pkt_count: u64,
pub last_seen_ns: u64,
}
impl PrefixStatsVal {
/// Разбирает сырые 24 байта значения карты.
#[must_use]
pub fn from_bytes(bytes: [u8; 24]) -> Self {
let read_u64 =
|range: std::ops::Range<usize>| u64::from_le_bytes(bytes[range].try_into().expect("8-byte field"));
Self {
syn_count: read_u64(0..8),
pkt_count: read_u64(8..16),
last_seen_ns: read_u64(16..24),
}
}
/// Сериализует значение в сырые 24 байта карты.
#[must_use]
pub fn to_bytes(self) -> [u8; 24] {
let mut out = [0u8; 24];
out[0..8].copy_from_slice(&self.syn_count.to_le_bytes());
out[8..16].copy_from_slice(&self.pkt_count.to_le_bytes());
out[16..24].copy_from_slice(&self.last_seen_ns.to_le_bytes());
out
}
}
impl PrefixKey {
/// Строит ключ префикса для адреса (v4 → /24 в первых 4 байтах, v6 → /64).
#[must_use]
pub fn new(ip: IpAddr) -> Self {
let mut key = Self::default();
match ip {
IpAddr::V4(v4) => {
key.family = PREFIX_FAMILY_V4;
key.addr[..4].copy_from_slice(&masked_v4(v4).octets());
},
IpAddr::V6(v6) => {
key.family = PREFIX_FAMILY_V6;
key.addr.copy_from_slice(&masked_v6_segments(v6));
},
}
key
}
/// Префикс как IP-адрес (маскированный).
#[must_use]
pub fn to_prefix(self) -> Option<IpAddr> {
match self.family {
PREFIX_FAMILY_V4 => Some(IpAddr::V4(Ipv4Addr::new(
self.addr[0],
self.addr[1],
self.addr[2],
self.addr[3],
))),
PREFIX_FAMILY_V6 => Some(IpAddr::V6(Ipv6Addr::from(self.addr))),
_ => None,
}
}
#[must_use]
pub fn from_bytes(bytes: [u8; 24]) -> Self {
Self {
family: bytes[0],
pad: bytes[1..8].try_into().expect("7 pad bytes"),
addr: bytes[8..24].try_into().expect("16 addr bytes"),
}
}
#[must_use]
pub fn to_bytes(self) -> [u8; 24] {
let mut out = [0u8; 24];
out[0] = self.family;
out[1..8].copy_from_slice(&self.pad);
out[8..24].copy_from_slice(&self.addr);
out
}
}
/// Агрегат по одному префиксу за окно детекции.
///
/// `unique_sources == 0` означает, что источник не считает уникальные адреса
/// (XDP-путь); spoof-gate в этом случае Block не подтверждает.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
pub struct PrefixSnapshot {
pub syn_count: u64,
pub pkt_count: u64,
pub last_seen_ns: u64,
pub unique_sources: u64,
}
/// Источник агрегатов по префиксам. Позволяет тестам работать без ядра.
pub trait PrefixStatsSource {
/// Снимок агрегатов за текущее окно.
///
/// # Errors
/// Ошибка чтения источника (карта не загружена, BPF-сбой и т.п.).
fn snapshot(&self) -> impl Future<Output = Result<Vec<(IpAddr, PrefixSnapshot)>>> + Send;
}
/// Возвращает префикс адреса: IPv4 и IPv4-mapped → /24, IPv6 → /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.
Some(v4) => IpAddr::V4(masked_v4(v4)),
None => IpAddr::V6(Ipv6Addr::from(masked_v6_segments(v6))),
},
}
}
fn masked_v4(ip: Ipv4Addr) -> Ipv4Addr {
let o = ip.octets();
Ipv4Addr::new(o[0], o[1], o[2], 0)
}
fn masked_v6_segments(ip: Ipv6Addr) -> [u8; 16] {
let mut segs = ip.octets();
segs[8..].fill(0);
segs
}
/// Эскалация вердиктов subnet-level детектора.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum SubnetVerdict {
Monitor,
StrictLimit,
Challenge,
Block,
}
/// Вердикт по одному префиксу.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct PrefixVerdict {
pub prefix: IpAddr,
pub verdict: SubnetVerdict,
pub snapshot: PrefixSnapshot,
}
/// Детектор распределённых атак по префиксам.
///
/// Лестница эскалации по `syn_count` за окно: `< threshold` → Monitor,
/// `< 2×threshold` → StrictLimit, иначе Challenge; Block только при
/// `≥ 4×threshold` И прохождении spoof-gate (≥ `min_unique_sources`
/// уникальных IP — защита от ложного бана CGNAT/спуфинга).
#[derive(Debug, Clone)]
pub struct SubnetDetector {
syn_threshold: u64,
min_unique_sources: u64,
}
impl SubnetDetector {
#[must_use]
pub fn new(syn_threshold: u64, min_unique_sources: u64) -> Self {
Self {
syn_threshold: syn_threshold.max(1),
min_unique_sources,
}
}
#[must_use]
pub fn from_config(config: &crate::config::DetectPrefixConfig) -> Self {
Self::new(config.syn_threshold, config.min_unique_sources)
}
/// Оценивает снимок и возвращает вердикты по активным префиксам.
#[must_use]
pub fn evaluate(&self, snapshots: &[(IpAddr, PrefixSnapshot)]) -> Vec<PrefixVerdict> {
snapshots
.iter()
.filter(|(_, snap)| snap.syn_count > 0)
.map(|(prefix, snap)| PrefixVerdict {
prefix: *prefix,
verdict: self.verdict_for(snap),
snapshot: *snap,
})
.collect()
}
#[must_use]
fn verdict_for(&self, snap: &PrefixSnapshot) -> SubnetVerdict {
let t = self.syn_threshold;
if snap.syn_count < t {
return SubnetVerdict::Monitor;
}
if snap.syn_count < t.saturating_mul(2) {
return SubnetVerdict::StrictLimit;
}
let extreme = snap.syn_count >= t.saturating_mul(4);
if extreme && self.spoof_gate_passed(snap) {
return SubnetVerdict::Block;
}
SubnetVerdict::Challenge
}
#[must_use]
fn spoof_gate_passed(&self, snap: &PrefixSnapshot) -> bool {
// gate отключён (min_unique_sources == 0) либо подтверждено разнообразие.
self.min_unique_sources == 0 || snap.unique_sources >= self.min_unique_sources
}
}
/// Реализация [`PrefixStatsSource`] поверх XDP-фильтра (feature `xdp`).
/// Читает карту `prefix_stats`; уникальные источники ядро не считает,
/// поэтому spoof-gate на этом пути Block не подтверждает.
#[cfg(feature = "xdp")]
pub struct XdpPrefixStats {
filter: std::sync::Arc<std::sync::Mutex<crate::xdp::XdpFilter>>,
}
#[cfg(feature = "xdp")]
impl XdpPrefixStats {
#[must_use]
pub fn new(filter: std::sync::Arc<std::sync::Mutex<crate::xdp::XdpFilter>>) -> Self {
Self { filter }
}
/// Блокирует мьютекс фильтра (для kernel-enforcement вердиктов).
///
/// # Panics
/// Если мьютекс отравлен (паника в другом потоке во время удержания).
pub fn filter_lock(&self) -> std::sync::MutexGuard<'_, crate::xdp::XdpFilter> {
self.filter.lock().expect("xdp lock poisoned")
}
}
#[cfg(feature = "xdp")]
impl PrefixStatsSource for XdpPrefixStats {
async fn snapshot(&self) -> Result<Vec<(IpAddr, PrefixSnapshot)>> {
let raw = self.filter_lock().read_prefix_stats()?;
Ok(raw
.into_iter()
.filter_map(|(key, val)| {
let prefix = key.to_prefix()?;
Some((
prefix,
PrefixSnapshot {
syn_count: val.syn_count,
pkt_count: val.pkt_count,
last_seen_ns: val.last_seen_ns,
unique_sources: 0,
},
))
})
.collect())
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn stats_val_roundtrip() {
let val = PrefixStatsVal {
syn_count: 42,
pkt_count: 100,
last_seen_ns: 1_234_567_890,
};
assert_eq!(PrefixStatsVal::from_bytes(val.to_bytes()), val);
assert_eq!(size_of::<PrefixStatsVal>(), 24);
}
}