GitHubLinkedIn

PiGuard WIDS

Source

Raspberry Pi Wi-Fi intrusion detection stack with Scapy capture, FastAPI automation, and a Svelte operations console.

Overview

PiGuard is a wireless intrusion detection system that runs on Raspberry Pi. It monitors Wi-Fi traffic for deauth attacks, SSID spoofing, and rogue access points. The system includes a Scapy-based packet capture engine, FastAPI control plane, and a Svelte dashboard.

Detection Pipeline

  • Sniffer: A Scapy capture loop pinned to monitor mode radios, running with libpcap filters so it only ingests beacon, deauth, and disassoc frames. Each packet is normalized with channel/band inference, RSSI, and optional RSN parsing before being buffered into SQLite for low-power durability.
  • Sensor: A stateful analyzer that sweeps recent events every few seconds. It looks for scoped deauth floods (per source and global thresholds), SSID spoofing, BSSID/channel drift, RSN capability mismatches, and even band-power variance anomalies to catch mobile rogue APs.
  • Alerts: Findings are persisted as first-class alerts, surfaced instantly over Server-Sent Events, and optionally pushed to Discord webhooks or SMTP for the on-call channel.

Operations Surface

  • FastAPI control plane: JSON endpoints to manage capture settings, defense policy, thresholds, and device interfaces. Everything is gated by API keys so you can script automations, Home Assistant hooks, or quick CLI tweaks without exposing the dashboard.
  • Svelte dashboard: A responsive console that ships with the Pi, providing Overview, Alerts, Defense, Device, Settings, and Logs tabs. It can restart systemd services, hot swap channel hopping modes, and live-edit alert thresholds without touching the terminal.
  • Installer: install.sh checks device prerequisites, builds the UI, provisions a Python venv, installs systemd units (piguard-api, piguard-sniffer, piguard-sensor), and walks the operator through SSID defense setup. Getting a fresh SD card online takes minutes instead of hours.

Hard-Won Engineering Bits

  • Tuned capture stack: BPF filters, SQLite WAL + PRAGMA tuning, and batched inserts keep packet loss near zero even on Pi 3 hardware.
  • Live configuration reloads: the sniffer and sensor processes watch /etc/piguard/wids.yaml, so UI edits propagate to long-running services without restarts.
  • Automation-friendly design: every UI action is backed by REST endpoints; CLI helpers (python -m wids sensor, python -m wids sniffer, etc.) make it trivial to integrate with existing ops scripts.
  • Misuse-resistant defaults: alert cooldowns, offender tracking, and power variance heuristics reduce false positives when the network is noisy.

What I Learned

The project required combining 802.11 packet capture with resource-constrained embedded systems. I learned how to optimize SQLite for high-throughput writes on limited hardware and how to design REST APIs that support both UI interactions and automation scripts.