SentinelMesh Simulator

SentinelMesh is an exploratory simulation framework designed to evaluate the efficacy of decentralized, quorum-based intrusion detection systems (IDS) in resource-constrained mesh networks. Its primary purpose is to mathematically validate whether lightweight, edge-deployed IDS nodes can successfully coordinate to detect distributed, fragmented attacks (like slow-and-low reconnaissance or multi-origin DoS) that slip past individual node heuristics.

SentinelMesh tests the hypothesis that decentralized gossip protocols combined with a simple scoring heuristic can match the detection capabilities of a centralized SIEM, but with orders of magnitude less bandwidth overhead. It achieves this by simulating the UNSW-NB15 dataset over virtualized mesh topologies.

🚀 Quick Start & Project Overview

SentinelMesh is a decentralized anomaly correlation framework designed for distributed network intrusion sensing. Modern network defense typically relies on centralized Security Information and Event Management (SIEM) pipelines, which create latency bottlenecks, incur massive bandwidth costs, and introduce a single point of failure.

SentinelMesh replaces the centralized aggregator with a lightweight, decentralized gossip-based correlation mechanism. Independent IDS nodes exchange compact anomaly summaries via an epidemic protocol, utilizing a quorum consensus rule to collectively escalate "low-and-slow" attacks (e.g., distributed port scans, credential stuffing) that appear statistically normal to any single edge node.

🎯 Purpose & Capabilities

• Resilient Intrusion Sensing: Detects highly fragmented, structured volumetric campaigns that deliberately evade single-node detection boundaries.
• Matched Counterfactual Evaluation: The simulation engine features a mathematically rigorous pipeline that isolates genuine structured campaign signals from ambient mesh noise using exact-round matched resampling.
• High-Performance Simulation: A fully optimized $O(N \times R)$ discrete-event simulator written in Go capable of sweeping massive parameter grids (mesh size $N$, fanout $f$, fragmentation $k$, quorum $q$) in seconds.
• Multi-Track Validation: Independent tracks for simulation (Go), cross-check machine learning baseline validation (Python), and visual exploration (Next.js).

---

🔍 Validation & Deep-Dive

For a detailed technical retrospective on the metrics pipeline validation, structural bugs resolved, and the matched counterfactual control architecture that isolates genuine propagation signal from ambient mesh noise, please see the Bug Post-Mortem.

---

🏛 Architecture

System Topology

graph TD
    subgraph "SentinelMesh (Decentralized Gossip)"
    N1((Node 1)) <-->|Constant-Size Digest| N2((Node 2))
    N2 <-->|Constant-Size Digest| N3((Node 3))
    N3 <-->|Constant-Size Digest| N1
    N4((Node 4)) <-->|Constant-Size Digest| N2
    N1 <-->|Constant-Size Digest| N4
    end

    subgraph "Traditional SIEM (Centralized)"
    E1((Edge 1)) -->|Raw Logs/Flows| Agg[SIEM Aggregator]
    E2((Edge 2)) -->|Raw Logs/Flows| Agg
    E3((Edge 3)) -->|Raw Logs/Flows| Agg
    E4((Edge 4)) -->|Raw Logs/Flows| Agg
    end

Loading

Node Workflow

sequenceDiagram
    participant Traffic as Network Traffic
    participant Local as Local Scorer (Node i)
    participant Cache as Digest Cache
    participant Peers as Network Peers

    Traffic->>Local: Ingest local flow partition
    Local->>Local: Compute O(1) EWMA z-score & tag category
    Local->>Cache: Store self digest 
    
    loop Every Gossip Round
        Local->>Peers: Push Digest to f random peers
        Peers-->>Cache: Receive incoming peer digests
        Cache->>Cache: Retain latest digest per peer in window W
        
        alt |{peers with score > \tau_{local}}| \ge q
            Cache->>Cache: Trigger Collective Alert (Quorum Escalation)!
        end
    end

Loading

---

📂 Project Structure (Multi-Track Monorepo)

This repository is organized into three parallel tracks to support simulation, machine-learning validation, and data visualization.

• simulator/ (Track 1 - Go): The core discrete-event simulation engine. Handles the parsing of the UNSW-NB15 dataset, pseudo-random node partitioning, $O(1)$ EWMA scoring, epidemic push-gossip exchange, and the quorum escalation rule.
• ml-crosscheck/ (Track 2 - Python): Independent scorer validation. Uses models like Isolation Forests and Autoencoders to cross-check the Go scorer's escalations and generate validation summaries.
• dashboard/ (Track 3 - Next.js): A frontend web application for interactive sweep result exploration. Visualizes metrics such as recall, bandwidth overhead, and convergence latency across variables like mesh size ($N$) and fanout ($f$).

Supporting directories include data/ (datasets and fetch scripts), docs/ (architecture & progress tracking), results/ (shared output contract), and paper/ (LaTeX sources).

---

🚀 Quickstart

1. Fetch the Dataset

The simulation utilizes the standard UNSW-NB15 dataset. Download it using the provided script:

./data/scripts/fetch_dataset.sh

2. Run the Simulator

2. Run the Full Grid Sweep

Navigate to the simulator directory. You can run the optimized Go simulator directly, or use the Python orchestrator to run the full cross-seed sweep and generate the aggregated master grid:

cd simulator
go build -o simulate cmd/simulate/main.go

# Option A: Run a single seed directly
./simulate --data ../data/raw/UNSW_NB15_testing-set.csv --config configs/sweep_default.yaml --seed 42

# Option B: Run the full 3-seed automated grid orchestrator
python3 scripts/run_full_grid.py

3. View Results

Aggregated master results are written to results/full_grid/master_grid.csv. To view the interactive web visualization, start the dashboard:

cd dashboard
npm install
npm run dev
# Open http://localhost:3000

Then copy results into the dashboard's public directory:

cp -r results/sweep/*.csv dashboard/public/data/
cp -r results/crosscheck/* dashboard/public/data/

---

🧪 Testing

Test Stats

Track	Language	Tests / Build	Details
Core Simulator	Go	41 tests	10 packages
ML Crosscheck	Python	49 tests	3 test files
Dashboard	TypeScript	Builds	2 routes, 2 chart components
Total		90 tests + clean build

Track 1 — Simulator (Go)

41 tests across the following packages:

Package	Tests	Focus
dataset	3	CSV parsing, flow extraction, error handling
fragment	3	Node partitioning, fragmentation, count preservation
scorer	5	EWMA z-score, bounds, repeatability
node	4	Node logic, digest cache, flow ingestion
gossip	4	Epidemic push, peer selection, stale eviction
quorum	5	Escalation rule, thresholds, multi-category, window
baseline	3	Independent/centralized runs, no-alert cases
metrics	5	Recall, bandwidth, latency, edge cases
sweep	3	Config loading, sweep execution
tests (integration)	3	Full pipeline, sweep E2E, baseline comparison

cd simulator && go test ./... -count=1

Track 2 — ML Crosscheck (Python)

49 tests across 3 files:

File	Tests	Focus
test_dataset.py	23	Data loading, labeling, features, split, normalize, partition
test_models.py	15	Isolation Forest, Autoencoder, Go EWMA replica, score bounds
test_integration.py	11	Full pipeline, per-category metrics, CSV/JSON report output

cd ml-crosscheck && pytest tests/ -v
# or from project root:
python -m pytest tests/ml-crosscheck/ -v

Track 3 — Dashboard (Next.js)

Clean build with no lint errors. Two routes:

• / — Sweep overview: recall chart, bandwidth chart, raw results table
• /crosscheck — ML crosscheck comparison view with overall + per-category tables

cd dashboard
npm run build

Test Data

A small synthetic CSV dataset at simulator/testdata/testdata.csv with 15 flows across 7 attack categories (analysis, backdoor, dos, exploits, fuzzers, generic, reconnaissance) plus normal traffic. Used by both Go and Python test suites.

---

📊 Evaluation Goals & Mathematical Rigor

Based on discrete-event simulation using partitioned UNSW-NB15 traffic, this framework rigorously measures:

• Detection Recall: The system's ability to recover detection capability for fragmented reconnaissance against baseline isolated edge nodes, utilizing a robust Matched Counterfactual Control (MCC) mechanism to perfectly subtract out spurious noise.
• Bandwidth Overhead: The reduction in peak single-point load compared to a centralized SIEM, explicitly tracking the $1/N$ dilution constraint.
• Convergence Latency: The scaling behavior of gossip propagation across varying mesh sizes, measured via rigorous True Positive Flow escalation time (averaging escRound - r).