WiFi Guardian

WiFi Guardian is a local network observability tool. It discovers devices on the current LAN, measures local IP traffic, and reports sustained TCP port-scan patterns in a browser dashboard.

Use it only on networks you own or are authorized to administer. Packet capture and ARP discovery require elevated network permissions.

What it does

• Discovers currently visible LAN devices with arp-scan.
• Captures IP traffic with Scapy and reports upload/download totals per local IP.
• Retains a bounded, payload-free packet metadata history for filtering by IP, protocol, direction, and port.
• Raises a port-scan alert only after a configurable number of distinct TCP SYN ports are contacted within a time window.
• Offers REST snapshots and live Socket.IO updates.

The application is intentionally in-memory: restarting it clears device, traffic, and alert history.

Run locally

sudo apt-get install arp-scan libpcap-dev
./install.sh
./run.sh

Open http://127.0.0.1:5000.

Copy .env.example to .env to change settings. Keep the default local bind unless the dashboard is protected by an authentication-enabled reverse proxy. CORS_ALLOWED_ORIGINS is optional; when set, it is a comma-separated allow-list for browser origins.

MAX_PACKET_HISTORY controls the number of recent packet metadata entries held in memory. The application never retains packet payloads.

Run with Docker

Docker needs the host network to see and capture the LAN. On Linux:

docker compose up --build

The compose configuration grants only NET_ADMIN and NET_RAW, not full privileged access. The dashboard remains available on http://127.0.0.1:5000 by default. Local and Docker launches use Gunicorn with one worker so the in-memory monitor state has one owner.

Development and checks

python3 -m unittest discover -s tests -v
python3 -m compileall -q app.py config.py moniwifi

The complete HTTP and Socket.IO API is documented in API.md.