20260219 sentinel

Cargo.toml

@@ -34,6 +34,7 @@ opt-level = 3
 
 [dependencies]
 torrust-index-located-error = { version = "3.0.0-develop", path = "packages/located-error" }
+torrust-sentinel = { version = "3.0.0-develop", path = "packages/sentinel" }
 
 anyhow = "1"
 argon2 = "0"
@@ -101,23 +102,23 @@ tempfile = "3"
 which = "6"
 
 [package.metadata.cargo-machete]
-ignored = ["futures"]
+ignored = ["futures", "torrust-sentinel"]
 
 [lints]
 workspace = true
 
 [workspace.lints.rust]
-warnings = { level = "deny", priority = -1 }
+deprecated-safe = { level = "deny", priority = -1 }
 future-incompatible = { level = "deny", priority = -1 }
 let-underscore = { level = "deny", priority = -1 }
 nonstandard-style = { level = "deny", priority = -1 }
 rust-2018-compatibility = { level = "deny", priority = -1 }
 rust-2018-idioms = { level = "deny", priority = -1 }
 rust-2021-compatibility = { level = "deny", priority = -1 }
 rust-2024-compatibility = { level = "warn", priority = -1 }
-unused = { level = "deny", priority = -2 }
-deprecated-safe = { level = "deny", priority = -1 }
 unsafe-code = "warn"
+unused = { level = "deny", priority = -2 }
+warnings = { level = "deny", priority = -1 }
 
 [workspace.lints.clippy]
 all = { level = "deny", priority = -1 }

packages/sentinel/Cargo.toml

@@ -0,0 +1,34 @@
+[package]
+description = "Hierarchical online subspace anomaly spectrometer for network traffic."
+keywords = ["anomaly-detection", "network", "traffic", "svd"]
+name = "torrust-sentinel"
+readme = "README.md"
+
+authors.workspace = true
+documentation.workspace = true
+edition.workspace = true
+homepage.workspace = true
+license.workspace = true
+publish.workspace = true
+repository.workspace = true
+rust-version.workspace = true
+version.workspace = true
+
+[lints]
+workspace = true
+
+[features]
+serde = ["dep:serde"]
+
+[dependencies]
+faer = "0"
+rand = "0"
+serde = { version = "1", features = ["derive"], optional = true }
+tracing = "0"
+
+[dev-dependencies]
+criterion = { version = "0.5", features = ["html_reports"] }
+
+[[bench]]
+name = "sentinel"
+harness = false

packages/sentinel/benches/sentinel.rs

@@ -0,0 +1,283 @@
+//! Criterion benchmarks for the Spectral Sentinel.
+//!
+//! Run with:
+//!
+//! ```sh
+//! cargo bench -p torrust-sentinel
+//! ```
+
+use criterion::{black_box, criterion_group, criterion_main, BenchmarkId, Criterion, Throughput};
+use torrust_sentinel::config::SentinelConfig;
+use torrust_sentinel::observation::{CentredBits, ObservationBatch};
+use torrust_sentinel::sentinel::{NoiseParams, SpectralSentinel};
+
+// ─── Helpers ────────────────────────────────────────────────
+
+/// Lightweight config for micro-benchmarks: few depths, small rank.
+fn bench_config() -> SentinelConfig {
+    SentinelConfig {
+        max_rank: 4,
+        forgetting_factor: 0.95,
+        rank_update_interval: 10,
+        campus_bits: 4,
+        prefix_depths: vec![8, 16],
+        energy_threshold: 0.90,
+        eps: 1e-6,
+        per_sample_scores: false,
+        cusum_allowance_sigmas: 0.5,
+        cusum_slow_decay: 0.999,
+        cusum_meta_slow_decay: 0.999,
+    }
+}
+
+/// Realistic config with default depths and higher rank.
+fn realistic_config() -> SentinelConfig {
+    SentinelConfig {
+        max_rank: 16,
+        forgetting_factor: 0.99,
+        rank_update_interval: 100,
+        campus_bits: 8,
+        prefix_depths: vec![8, 16, 24, 32, 48, 64, 96, 128],
+        energy_threshold: 0.90,
+        eps: 1e-6,
+        per_sample_scores: false,
+        cusum_allowance_sigmas: 0.5,
+        cusum_slow_decay: 0.999,
+        cusum_meta_slow_decay: 0.999,
+    }
+}
+
+/// Generate `count` sequential values in a single campus.
+fn single_campus_values(count: usize) -> Vec<u128> {
+    (0..count).map(|i| (0xAB_u128 << 120) | (i as u128 + 1)).collect()
+}
+
+/// Generate `count` values spread across many campuses.
+fn multi_campus_values(count: usize) -> Vec<u128> {
+    (0..count)
+        .map(|i| {
+            let campus = (i % 16) as u128;
+            (campus << 124) | (i as u128 + 1)
+        })
+        .collect()
+}
+
+/// Create a warmed sentinel ready for steady-state benchmarking.
+///
+/// Kept deliberately cheap — just enough to get past the cold EWMA
+/// path and into the warm steady-state code.  The full warm-up
+/// (many noise rounds, many batches) is what `bench_inject_noise`
+/// measures; the other benchmarks only need a sentinel whose
+/// baselines are non-cold.
+fn warmed_sentinel(cfg: &SentinelConfig) -> SpectralSentinel {
+    let mut s = SpectralSentinel::new(cfg.clone()).unwrap();
+
+    // Seed a few campuses.
+    let seed: Vec<u128> = (0..4_u128)
+        .flat_map(|campus| (0..4_u128).map(move |i| (campus << 124) | (i + 1)))
+        .collect();
+    s.ingest(&seed);
+
+    // Minimal noise injection — just enough to warm baselines.
+    s.inject_noise(&NoiseParams {
+        rounds: 3,
+        batch_size: 4,
+        seed: Some(42),
+    });
+
+    // One real batch to enter the warm code path.
+    let batch: Vec<u128> = (0..4_u128)
+        .flat_map(|campus| (0..4_u128).map(move |i| (campus << 124) | (i + 100)))
+        .collect();
+    s.ingest(&batch);
+
+    s
+}
+
+// ─── Observation encoding ───────────────────────────────────
+
+fn bench_centred_bits(c: &mut Criterion) {
+    c.bench_function("CentredBits::from_u128", |b| {
+        b.iter(|| CentredBits::from_u128(black_box(0xDEAD_BEEF_CAFE_BABE_1234_5678_9ABC_DEF0)));
+    });
+}
+
+fn bench_observation_batch(c: &mut Criterion) {
+    let mut group = c.benchmark_group("ObservationBatch::from_values");
+
+    for count in [16, 64, 256] {
+        let values = single_campus_values(count);
+        group.throughput(Throughput::Elements(count as u64));
+        group.bench_with_input(BenchmarkId::new("single_campus", count), &values, |b, vals| {
+            b.iter(|| ObservationBatch::from_values(black_box(vals), 4));
+        });
+    }
+
+    for count in [16, 64, 256] {
+        let values = multi_campus_values(count);
+        group.throughput(Throughput::Elements(count as u64));
+        group.bench_with_input(BenchmarkId::new("multi_campus", count), &values, |b, vals| {
+            b.iter(|| ObservationBatch::from_values(black_box(vals), 4));
+        });
+    }
+
+    group.finish();
+}
+
+// ─── Ingest (core hot path) ─────────────────────────────────
+
+fn bench_ingest_cold(c: &mut Criterion) {
+    let mut group = c.benchmark_group("ingest_cold");
+
+    for batch_size in [1, 8, 32] {
+        let values = single_campus_values(batch_size);
+        group.throughput(Throughput::Elements(batch_size as u64));
+        group.bench_with_input(BenchmarkId::new("single_campus", batch_size), &values, |b, vals| {
+            b.iter_with_setup(
+                || SpectralSentinel::new(bench_config()).unwrap(),
+                |mut s| s.ingest(black_box(vals)),
+            );
+        });
+    }
+
+    group.finish();
+}
+
+fn bench_ingest_warm(c: &mut Criterion) {
+    let mut group = c.benchmark_group("ingest_warm");
+    let cfg = bench_config();
+
+    for batch_size in [1, 8, 32, 64] {
+        let values = single_campus_values(batch_size);
+        group.throughput(Throughput::Elements(batch_size as u64));
+        group.bench_with_input(BenchmarkId::new("single_campus", batch_size), &values, |b, vals| {
+            b.iter_with_setup(|| warmed_sentinel(&cfg), |mut s| s.ingest(black_box(vals)));
+        });
+    }
+
+    // Multi-campus: triggers coordination tier.
+    for batch_size in [16, 64] {
+        let values = multi_campus_values(batch_size);
+        group.throughput(Throughput::Elements(batch_size as u64));
+        group.bench_with_input(BenchmarkId::new("multi_campus", batch_size), &values, |b, vals| {
+            b.iter_with_setup(|| warmed_sentinel(&cfg), |mut s| s.ingest(black_box(vals)));
+        });
+    }
+
+    group.finish();
+}
+
+// ─── Ingest at realistic scale ──────────────────────────────
+
+fn bench_ingest_realistic(c: &mut Criterion) {
+    let mut group = c.benchmark_group("ingest_realistic");
+    let cfg = realistic_config();
+
+    for batch_size in [16, 64, 256] {
+        let values = multi_campus_values(batch_size);
+        group.throughput(Throughput::Elements(batch_size as u64));
+        group.bench_with_input(BenchmarkId::new("multi_campus", batch_size), &values, |b, vals| {
+            b.iter_with_setup(|| warmed_sentinel(&cfg), |mut s| s.ingest(black_box(vals)));
+        });
+    }
+
+    group.finish();
+}
+
+// ─── Noise injection ────────────────────────────────────────
+
+fn bench_inject_noise(c: &mut Criterion) {
+    let mut group = c.benchmark_group("inject_noise");
+    let cfg = bench_config();
+
+    for rounds in [10, 50] {
+        let params = NoiseParams {
+            rounds,
+            batch_size: 16,
+            seed: Some(42),
+        };
+        group.bench_with_input(BenchmarkId::new("rounds", rounds), &params, |b, params| {
+            b.iter_with_setup(
+                || {
+                    let mut s = SpectralSentinel::new(cfg.clone()).unwrap();
+                    // Need at least one campus for noise to do anything.
+                    s.ingest(&single_campus_values(4));
+                    s
+                },
+                |mut s| s.inject_noise(black_box(params)),
+            );
+        });
+    }
+
+    group.finish();
+}
+
+// ─── Health / inspection ────────────────────────────────────
+
+fn bench_health(c: &mut Criterion) {
+    let cfg = bench_config();
+    let s = warmed_sentinel(&cfg);
+
+    c.bench_function("health", |b| {
+        b.iter(|| s.health());
+    });
+}
+
+// ─── Per-sample scoring overhead ────────────────────────────
+
+fn bench_per_sample_overhead(c: &mut Criterion) {
+    let mut group = c.benchmark_group("per_sample_scores");
+
+    let batch_size = 32;
+    let values = single_campus_values(batch_size);
+
+    for enabled in [false, true] {
+        let cfg = SentinelConfig {
+            per_sample_scores: enabled,
+            ..bench_config()
+        };
+
+        group.throughput(Throughput::Elements(batch_size as u64));
+        group.bench_with_input(BenchmarkId::new("enabled", enabled), &values, |b, vals| {
+            b.iter_with_setup(|| warmed_sentinel(&cfg), |mut s| s.ingest(black_box(vals)));
+        });
+    }
+
+    group.finish();
+}
+
+// ─── Depth scaling ──────────────────────────────────────────
+
+fn bench_depth_scaling(c: &mut Criterion) {
+    let mut group = c.benchmark_group("depth_scaling");
+    let batch_size = 16;
+    let values = single_campus_values(batch_size);
+
+    for num_depths in [1, 2, 4, 8] {
+        let depths: Vec<u8> = [8, 16, 24, 32, 48, 64, 96, 128].into_iter().take(num_depths).collect();
+
+        let cfg = SentinelConfig {
+            prefix_depths: depths,
+            ..bench_config()
+        };
+
+        group.throughput(Throughput::Elements(batch_size as u64));
+        group.bench_with_input(BenchmarkId::new("num_depths", num_depths), &values, |b, vals| {
+            b.iter_with_setup(|| warmed_sentinel(&cfg), |mut s| s.ingest(black_box(vals)));
+        });
+    }
+
+    group.finish();
+}
+
+// ─── Registration ───────────────────────────────────────────
+
+criterion_group!(encoding, bench_centred_bits, bench_observation_batch,);
+
+criterion_group!(ingest, bench_ingest_cold, bench_ingest_warm, bench_ingest_realistic,);
+
+criterion_group!(auxiliary, bench_inject_noise, bench_health,);
+
+criterion_group!(scaling, bench_per_sample_overhead, bench_depth_scaling,);
+
+criterion_main!(encoding, ingest, auxiliary, scaling);