NetSentinel watches the devices on your network and the way they talk, learns what ordinary looks like, and raises the alarm the moment something behaves like an attacker: an unknown device slipping onto the Wi‑Fi, someone poisoning ARP to sit in the middle of your traffic and eavesdrop, a port scan, or a device quietly exfiltrating data and beaconing to a command‑and‑control server.
Local‑first · no cloud · a live SOC‑style dashboard · runs a full attack demo out of the box
You can't keep an up‑to‑date blocklist of every rogue device, every attacker's laptop, every malware C2 server. But you don't have to. Almost every intrusion behaves in ways your normal devices never do:
- your phone doesn't answer ARP for the router's IP — an attacker doing a man‑in‑the‑middle attack does;
- your smart bulb doesn't knock on 20 different ports of your NAS — a scanner does;
- your laptop doesn't ship 12 MB to a random host in Eastern Europe every night on a perfect 3‑second heartbeat — an implant does.
NetSentinel ignores what a device is and watches what it does, so it can flag threats it has never seen before — the network‑layer sibling of behavior‑based malware defense.
| Detection | Signal it keys on | Severity |
|---|---|---|
| 🕵️ Unknown device | A MAC address that wasn't there during baseline learning (a "hidden user") | High |
| 🎭 ARP spoofing / MITM | An IP — especially the gateway — resolving to a new MAC, or one MAC claiming many IPs | Critical |
| 🔍 Port scan | One source touching many ports on a host in seconds | High |
| 🌐 Host sweep | One source contacting many internal hosts at once | High |
| 📤 Data exfiltration | A large outbound transfer, far above the device's normal | High |
| 📡 C2 beaconing | Clockwork‑regular check‑ins to a fixed external host (low jitter) | High |
| 📈 Traffic anomaly | A device running many times hotter than its learned baseline | Medium |
No single signal is trusted blindly — each contributes weighted evidence to one threat score (0–100) that rises with severity and decays over time, so the whole dashboard visibly cools off once an attack stops.
The default mode simulates a believable home/office network — a router, phones, laptops, a TV, some IoT — then stages a full intrusion on a timeline so you can watch NetSentinel react in real time. It's 100% synthetic and safe (nothing touches a real network or needs privileges):
00:00— the network is profiled; every device is learned as known.~+10s🕵️ a cheap ESP32 board (esp32-a1b2) joins the network → Unknown device.~+25s🎭 it poisons ARP, impersonating the gateway to intercept traffic → Critical: MITM.~+35s🔍 it sweeps and port‑scans the NAS and router → Recon.~+45s📤 it exfiltrates ~13 MB to a suspicious host and 📡 beacons to its C2 → Exfil + Beaconing.
Then it goes quiet, the threat score decays, and the cycle re‑arms — so the demo keeps telling the story for as long as you leave it running.
A dark, security‑operations‑center dashboard (default http://127.0.0.1:8899), with zero external dependencies — no fonts, CDNs, or build step:
- a live network map on
<canvas>— the gateway at the centre, every device orbiting it, animated packets flowing along the links, and threats glowing red; - a streaming threat feed with severity, evidence and a recommended action for every alert (click to expand);
- a device inventory — status, IP, MAC, vendor (offline OUI lookup), traffic and a per‑device risk bar;
- headline stat tiles and a threat gauge that recolors the entire UI as the situation escalates.
git clone https://github.com/CasperRoot/NetSentinel.git
cd NetSentinel
pip3 install -r requirements.txt
python3 run.py # opens the dashboard and runs the attack demoThat's it — the demo needs nothing but Flask. Your browser opens on the dashboard and the story starts within a few seconds.
Point NetSentinel at your actual LAN. This needs scapy and
elevated privileges (to open the interface in promiscuous mode):
pip3 install scapy
sudo python3 run.py --live --interface en0 # macOS
sudo python3 run.py --live --interface wlan0 # LinuxNetSentinel spends the first ~20 seconds learning which devices and gateway are
normal (saved to baseline.json), then arms every detector. On the next run it
already knows your household, so a brand‑new device stands out immediately.
Find your interface with
ifconfig(macOS) orip link(Linux). Omit--interfaceto let scapy pick the default.
Everything has sensible defaults. To tune it, copy the example and edit:
cp config.example.json config.json
python3 run.py -c config.jsonCommon flags:
| Flag | Meaning |
|---|---|
--live / --demo |
monitor a real interface / run the simulation (default) |
-i, --interface |
NIC for live capture (en0, wlan0, …) |
--port |
dashboard port (default 8899) |
--learn SEC |
baseline learning window |
--speed |
demo traffic speed multiplier |
--no-browser |
don't auto‑open the dashboard |
Detection thresholds (scan sensitivity, exfil floor, beacon jitter, …) all live in the config so tuning never means editing detector code.
python3 tests/test_detectors.py # standalone runner (no pytest needed)
# or
python3 -m pytest tests/Each detector is exercised in isolation with hand‑crafted events — fast and deterministic, no threads or sockets.
See docs/architecture.md for the full pipeline,
threading model, and a diagram. In short: a swappable capture source (live or
simulated) emits normalized Events onto a queue; an engine thread drains it,
updates a shared state, learns a baseline, and fans each event out to
independent detectors; a Flask app serves the state to the dashboard.
netsentinel/
├── models.py Event · Device · Alert · Severity
├── engine.py capture → state → detectors
├── state.py live devices, alerts, decaying threat score
├── baseline.py learned "normal" (persisted)
├── capture/ live.py (scapy) · simulator.py (the demo)
├── detectors/ arp_spoof · new_device · port_scan · exfiltration · traffic_anomaly
└── web/ Flask API + the SOC dashboard
NetSentinel is a defensive tool for networks you own or are authorized to monitor. Passive monitoring of your own LAN is fine; capturing traffic on networks you don't control may be illegal. The bundled "attacker" is entirely simulated — NetSentinel never attacks, scans, or transmits anything on a real network; live mode only listens and sends standard ARP discovery requests.
MIT — see LICENSE. Built by CasperRoot.