guard/src/traffic/profile/alert.rs
loki5512344 918e561a61
feat(xdp): IPv6 UDP rate limit, working loader; English JavaDoc comments
XDP behaviour:
- udp_rate_limit6 (LRU, 128-bit source key) + throttle_hit6, so
  udp_policy = "rate-limit" now 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).

XDP loader (was completely broken, never reached the verifier):
- .rodata is now one struct rampart_config with frozen offsets enforced by
  _Static_assert; XdpGlobals is #[repr(C)] and the image is built with
  offset_of!. Previously 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 the 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: verifies map names and .rodata size without root;
  the real binary was confirmed to attach in a netns.

Docs and style:
- Code comments are English, JavaDoc/Rustdoc style, without emoji or
  decorative banners (new project rule, TODO §0.8).
- README rewritten bilingual: Russian first, English below, 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 describes the real-kernel smoke; stale research links removed.
2026-11-15 23:44:07 +01:00

174 lines
4.7 KiB
Rust

use std::fmt;
use std::net::Ipv4Addr;
use std::sync::Mutex;
use std::time::{Duration, Instant};
use crate::traffic::detector::AttackStatus;
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum AlertLevel {
Info,
Warning,
Critical,
}
impl fmt::Display for AlertLevel {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
AlertLevel::Info => write!(f, "INFO"),
AlertLevel::Warning => write!(f, "WARNING"),
AlertLevel::Critical => write!(f, "CRITICAL"),
}
}
}
#[derive(Debug, Clone, PartialEq)]
pub struct Alert {
pub level: AlertLevel,
pub message: String,
pub ip: Option<Ipv4Addr>,
pub pps: f64,
pub timestamp: Instant,
}
impl Alert {
pub fn new(level: AlertLevel, message: String, ip: Option<Ipv4Addr>, pps: f64) -> Self {
Self {
level,
message,
ip,
pps,
timestamp: Instant::now(),
}
}
}
impl fmt::Display for Alert {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match &self.ip {
Some(ip) => write!(
f,
"[{}] {} | IP: {} | PPS: {:.2}",
self.level, self.message, ip, self.pps
),
None => write!(f, "[{}] {} | PPS: {:.2}", self.level, self.message, self.pps),
}
}
}
/// 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>>,
}
impl AlertDispatcher {
pub fn new() -> Self {
Self::default()
}
/// 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) {
return None;
}
let was_under_attack = *previous == Some(AttackStatus::UnderAttack);
*previous = Some(status);
match (was_under_attack, status) {
(false, AttackStatus::UnderAttack) => {
Some(Alert::new(AlertLevel::Critical, "attack started".into(), None, 0.0))
},
(true, _) => Some(Alert::new(AlertLevel::Info, "attack ended".into(), None, 0.0)),
_ => None,
}
}
}
/// Delivers an alert to a webhook (fire-and-forget, with a timeout).
///
/// 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(),
"message": alert.message,
"pps": alert.pps,
});
let client = reqwest::Client::builder().timeout(Duration::from_secs(5)).build();
let client = match client {
Ok(c) => c,
Err(e) => {
tracing::warn!("webhook client build failed: {e}");
return;
},
};
if let Err(e) = client.post(url).json(&payload).send().await {
tracing::warn!("webhook delivery failed: {e}");
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn test_alert_display_with_ip() {
let alert = Alert::new(
AlertLevel::Critical,
"possible attack".into(),
Some(Ipv4Addr::new(192, 168, 1, 1)),
100500.0,
);
let s = alert.to_string();
assert!(s.contains("CRITICAL"));
assert!(s.contains("192.168.1.1"));
}
#[test]
fn test_alert_display_without_ip() {
let alert = Alert::new(AlertLevel::Info, "traffic spike".into(), None, 5000.0);
let s = alert.to_string();
assert!(s.contains("INFO"));
assert!(s.contains("traffic spike"));
}
#[test]
fn test_dispatcher_two_transitions_two_alerts() {
let dispatcher = AlertDispatcher::new();
assert_eq!(dispatcher.on_status(AttackStatus::Normal), None);
assert_eq!(dispatcher.on_status(AttackStatus::Suspicious), None);
let started = dispatcher.on_status(AttackStatus::UnderAttack);
assert_eq!(dispatcher.on_status(AttackStatus::UnderAttack), None);
assert_eq!(dispatcher.on_status(AttackStatus::UnderAttack), None);
let ended = dispatcher.on_status(AttackStatus::Normal);
assert_eq!(dispatcher.on_status(AttackStatus::Normal), None);
assert!(started.is_some());
assert!(ended.is_some());
assert!(
started.expect("started alert").message.contains("attack started")
&& ended.expect("ended alert").message.contains("attack ended")
);
}
#[test]
fn test_dispatcher_suspicious_does_not_flap_alerts() {
let dispatcher = AlertDispatcher::new();
for status in [
AttackStatus::Normal,
AttackStatus::Suspicious,
AttackStatus::Normal,
AttackStatus::Suspicious,
] {
assert_eq!(dispatcher.on_status(status), None);
}
}
}