WiFi Security Monitor v1: A Comprehensive Network Security Toolkit

Detect deauth attacks and monitor network devices with advanced behavioral analysis

I’m excited to announce the release of WiFi Security Monitor v1, a Python-based security toolkit designed to protect your wireless networks from attacks and unauthorized access. This project combines two powerful tools into one comprehensive security solution.

The longer version of this lives next door. The project page, WiFi Security Monitor, is a setup walkthrough rather than an announcement: it goes through every key in both JSON config files with the value the shipped example actually carries, attributes each threat-score weight to the line of deauth_detector.py that adds it, and reproduces the README’s troubleshooting list. Read this post for what the two programs are and what it takes to start them; go there when you are sitting in front of the config file.

🎯 What Is WiFi Security Monitor?

WiFi Security Monitor is an open-source network security toolkit that helps you monitor and protect your wireless networks. It consists of two main components:

1. Deauth Attack Detector - Identifies and analyzes WiFi deauthentication attacks in real-time
2. Network Device Monitor - Tracks all devices on your network and detects suspicious activity

🛡️ Deauth Attack Detection

One of the most common WiFi attacks is the deauthentication (deauth) attack, where an attacker sends spoofed management frames to disconnect devices from a network. If you want the bare mechanics first — a one-line tcpdump filter, a short standard-library Python detector, and a downloadable sample capture to test both offline — see how to detect a Wi-Fi deauth attack with tcpdump or a short Python script; this project is the fuller detector you graduate to. The Deauth Attack Detector uses advanced behavioral analysis to identify these attacks:

• 🔍 Dual-Band Monitoring — Hops between 2.4GHz and 5GHz channels to cover both bands
• 🧠 Behavioral Analysis — Detects attacks through timing patterns, RSSI variations, and sequence anomalies
• 🎭 MAC Spoofing Detection — Identifies attackers impersonating legitimate routers
• 📊 Smart Threat Scoring — Differentiates legitimate router behavior from malicious activity (0-100 scale)
• 📝 Forensic Logging — Detailed evidence collection for investigation and analysis

Example Attack Detection Output:

🚨 ATTACK #5 DETECTED - 2025-12-21 22:15:30 ⚠️ ATTACKING YOUR NETWORK!
   THREAT LEVEL: 🔴 CRITICAL (85/100)
   
⚠️  ATTACKER IDENTIFICATION:
    Packet Source:     aa:bb:cc:dd:ee:ff (UnknownVendor)
    🔴 LEGITIMACY:     15% - LIKELY SPOOFED!
    
📡 SIGNAL ANALYSIS:
    Signal Strength:   -65 dBm
    Est. Distance:     ~12m

📡 Network Device Monitoring

The Network Device Monitor component tracks all devices connected to your network, helping you identify unauthorized access and IoT security risks:

• 👀 Real-Time Device Tracking — Monitor all devices on your network as they connect and disconnect
• 🔧 IoT Device Detection — Automatically identifies ESP32, cameras, smart home devices, and other IoT hardware
• 📊 Persistent Database — Tracks total connection time and historical data for all devices
• ⚠️ Suspicious Device Alerts — Immediately alerts you when unknown or new devices appear
• 🏠 Smart Device Recognition — Learns which devices “belong here” based on connection patterns
• 📈 Connection Statistics — Detailed analytics showing which devices are always present vs. occasional visitors

🔬 How It Works: Behavioral Fingerprinting

Unlike traditional security tools that rely on hardware MAC addresses (which most adapters don’t expose), WiFi Security Monitor uses advanced behavioral fingerprinting to detect threats:

• Timing Analysis: Legitimate routers have consistent timing patterns; attack tools show irregular behavior
• RSSI Tracking: Sudden signal strength changes indicate device switching or spoofing
• Sequence Number Analysis: Duplicate or anomalous sequence numbers reveal packet injection
• Transmission Rate Analysis: Attack tools often use unusual transmission rates
• Multi-Factor Legitimacy Scoring: Combines all metrics to determine if a device is genuine

This approach makes the tool highly effective even with commodity WiFi adapters that don’t support advanced features. Most adapters don’t expose hardware MAC addresses at all, which is not a footnote — it is the reason the behavioral analysis exists.

What the printed score is made of

calculate_threat_level() in deauth_detector.py does not classify, it adds: each signal contributes a fixed number of points for the frame just seen plus the history held for that transmitter. The heaviest weights, all of them attributed to their own source line on the project page:

• +35 — the deauthentication frame is addressed to one of the MACs you listed in local_device_macs. An attack on your own gear outranks every other signal.
• +25 — the hardware transmitter address and the packet source MAC disagree: the MAC-spoofing case.
• +20 — the frame is a broadcast deauth addressed to ff:ff:ff:ff:ff:ff, an attempt to knock everyone off at once.
• +20 — the last four RSSI samples span more than 20 dBm, which a stationary transmitter does not do.
• +15 — sequence-number anomalies: duplicates, an oversized gap, or a suspiciously perfect run.

The total is clamped by min(score, 100), which is why the scale is exactly the 101 integers from 0 to 100.

There is one subtraction, and it is why a busy home network doesn’t alarm all evening. When a frame claims to come from a router, the adapter has not exposed a hardware MAC, and the behavioral legitimacy score is at least 70, the detector reduces the threat by int(legitimacy / 100 * threat_reduction_percentage). With the shipped threat_reduction_percentage of 80, a source scoring 90% legitimate loses 72 points. So a printed score is not a confidence level: it is the sum of the flags above, minus that discount where it applies.

That legitimacy percentage is a separate number, and it is shown only when a frame claims to be your router — 80-100% reads as genuine router behavior, 50-79% as uncertain and worth verifying manually, 0-49% as likely spoofed or malicious. A high legitimacy score is what triggers the threat discount, so the two numbers move against each other on purpose.

🚀 Technical Implementation

WiFi Security Monitor is built with Python 3.7+ and uses the Scapy library for packet manipulation and analysis. The tool supports any WiFi adapter capable of monitor mode, including:

• Alfa AWUS036NHA (Atheros AR9271) ✅
• Alfa AWUS036ACH (Realtek RTL8812AU) ✅
• TP-Link TL-WN722N v1 (Atheros AR9271) ✅
• Panda PAU09 (Ralink RT5372) ✅

Both tools can run simultaneously with two WiFi adapters, providing comprehensive network protection. The system works on any Linux distribution, with testing done on Raspberry Pi and Ubuntu systems.

Configuration is the first run, not a later step

Neither program takes command-line flags. Both read a JSON file from the working directory and refuse to start without it: the detector checks for config.json and calls sys.exit(1) when it is missing, and the device monitor does the same for its own monitor_config.json. Those two files have different shapes, which is easy to miss — the monitor wants a hostname_interface (eth0 in the example) alongside the monitor-mode interface, because that second, ordinary interface is how it captures hostnames. Its device history then lives in data/device_database.json, which survives restarts and accumulates first-seen time, connection count, total packets and total connection time per MAC.

Every key is read by direct lookup, so deleting a line from your copy raises a KeyError on startup rather than falling back to a sensible default. Edit values; never remove lines.

A monitor-mode radio hears one channel at a time

channel_hopper() sets a channel with iw dev <iface> set channel <n>, sleeps for the dwell time, then moves on. With the shipped example — five channels at 1.5 seconds — a full cycle is 7.5 seconds and the radio is on any given channel 20% of the time, so a short burst on a channel it is not currently tuned to is simply not captured. Two more things worth knowing before you read a quiet log as an all-clear:

• The example config lists "channels": [1,2,3,4,5], and the detector’s own band test is channel <= 14 means 2.4GHz. Out of the box this is a 2.4GHz-only setup until you edit that list — and 5GHz monitoring requires a 5GHz-capable adapter besides.
• Give it at least two channels. An empty list fails at import and a single-entry list fails at the startup banner, both before any packet is captured.

The per-key walkthrough of both files — dwell time, whitelists, the detection thresholds, the log paths — is on the project page, keyed to the values config.example.json ships.

📊 Threat Levels Explained

• 🟢 LOW (0-29) — Likely legitimate activity - normal router behavior
• 🟡 MEDIUM (30-49) — Suspicious activity - monitor closely and investigate
• 🟠 HIGH (50-69) — Persistent or broadcast attacks
• 🔴 CRITICAL (70-100) — Active attack detected - immediate action required

🎓 Use Cases

WiFi Security Monitor is perfect for:

• Home Network Security: Protect your family’s WiFi from attacks and unauthorized access
• Security Research: Study WiFi attack patterns and develop countermeasures
• Penetration Testing: Authorized security testing of wireless networks
• IoT Management: Keep track of all smart devices on your network
• Network Troubleshooting: Identify connectivity issues and interference

⚠️ Legal and Ethical Considerations

IMPORTANT: This tool is designed for authorized security testing only. You should only use it on networks you own or have explicit permission to test. Unauthorized network monitoring may be illegal in your jurisdiction. Always follow local laws and regulations.

🔮 Future Development

Version 1 is just the beginning! I have plans for future enhancements including:

• Web dashboard for real-time monitoring
• Email/SMS notifications for critical alerts
• Machine learning for improved threat detection
• Support for additional attack types (Evil Twin, WPS attacks, etc.)
• Integration with home automation systems
• Mobile app for remote monitoring

🚀 Get Started

WiFi Security Monitor is open source and available on GitHub under the Apache 2.0 license.

What you need before you start

• A WiFi adapter that supports monitor mode — this is the one part you cannot substitute. Built-in laptop WiFi typically doesn’t support monitor mode, so budget for a USB adapter; the four models above are the author’s confirmed-working set, not a complete list of what works.
• A second adapter, if you want the deauth detector and the device monitor running at the same time. Each program owns its interface and hops it independently, so they cannot share one.
• Linux, with root access. Testing is reported on Raspberry Pi and Ubuntu, and monitor mode needs sudo.
• Python 3.7 or higher, plus one dependency: requirements.txt pins scapy>=2.5.0 and lists nothing else.
• Your router’s MAC, and the MACs of the devices you care about. The router’s is on its label or from iwconfig while connected to it; your own device’s comes from ip link show. The whitelist and the ⚠️ ATTACKING YOUR NETWORK! targeting are both MAC lists you fill in yourself.

Install it and put the adapter in monitor mode

git clone https://github.com/nnxazolazuranikola/wifi-security-monitor.git
cd wifi-security-monitor
pip3 install -r requirements.txt

# monitor mode, on the adapter you are handing to the tool
sudo airmon-ng start wlan0

Run the two programs

# the deauth detector
cp config.example.json config.json
nano config.json                 # interface, channels, optional MACs
sudo python3 deauth_detector.py
tail -f attacker_evidence.log

# the device monitor, in a second terminal
cp monitor_config.example.json monitor_config.json
nano monitor_config.json         # interface, hostname_interface
sudo python3 network_monitor.py
tail -f network_devices.log
cat device_database.json         # device history

The startup banner is worth reading rather than scrolling past: it echoes the interface, the log path, the channel-hop pair and dwell time, whether any whitelist is in force, and the four threat levels. If the interface or channels in that banner are not what you expected, stop and fix the config before you trust anything that follows. Three failures account for most first runs — No such device means the interface name is wrong or monitor mode is not enabled, Operation not permitted means you are not root, and no detections at all usually means the channels don’t match your router’s frequency or something else is holding the adapter (sudo airmon-ng check kill).

One honest limit before you read too much into an alert: the estimated distance printed beside it is derived from RSSI using the tx_power_dbm and path_loss_exponent values from your config, so it assumes a path-loss model rather than measuring anything. Treat it as an order of magnitude and nothing finer.

Check out the repository for installation instructions, documentation, and examples:

• 📦 View on GitHub
• 📖 Project Details

If you are about to run this rather than read about it, go next door to WiFi Security Monitor: it carries the key-by-key walkthrough of both config files with the example’s shipped values, every threat-score weight attributed to the line of source that adds it, and the README’s troubleshooting list in full — the detail this post only summarises.

---

I’m excited to see how the community uses and improves WiFi Security Monitor. If you find it useful, please star the repository on GitHub and share it with others interested in network security!

Have questions or suggestions? Feel free to open an issue on GitHub — Issues is the repository’s only open channel, and Discussions is not enabled on it.

— DankDev

Tags: WiFi Security · Python · Network Monitoring · Cybersecurity · Open Source · Raspberry Pi

← Back to all posts

Follow new posts by RSS: paste dankdev.com/feed.xml into any feed reader. It is a plain XML file — no signup, no email address, no account. Posts land there the same day they go up, and there is nothing to unsubscribe from later.

Back to the top