Deauth Detector

A lightweight Python and Scapy-based defensive monitoring utility for detecting bursts of IEEE 802.11 deauthentication frames.

Deauthentication frames are a normal part of Wi-Fi management traffic, but unusually large bursts can also indicate deauthentication attacks or other suspicious wireless activity.

Deauth Detector monitors a wireless interface in monitor mode, tracks deauthentication activity over time, and generates alerts when configurable thresholds are exceeded.

---

Features

• IEEE 802.11 deauthentication frame detection
• Configurable wireless interface
• Burst-based detection
• Configurable detection threshold
• Sliding time window
• Per-transmitter / BSSID tracking
• Alert cooldown
• MAC address reporting
• Target address reporting
• 802.11 reason code reporting
• Optional verbose packet monitoring
• Persistent alert logging
• Custom log file support
• Graceful Ctrl+C shutdown
• Interface validation
• Capture error handling

---

Detection Logic

A single deauthentication frame does not necessarily indicate an attack.

Instead of alerting on every frame, Deauth Detector tracks how many deauthentication frames are observed from the same transmitter and BSSID during a configurable time window.

Default detection rule:

8 deauthentication frames
within
10 seconds

If that threshold is reached, an alert is generated.

A default cooldown of:

30 seconds

prevents the same transmitter from continuously generating duplicate alerts.

---

Example Detection

POTENTIAL DEAUTHENTICATION BURST DETECTED

Time:        2026-08-10T20:00:00+03:00
Interface:   wlan0mon
Frames:      8 within 10s
Transmitter: aa:bb:cc:dd:ee:ff
BSSID:       aa:bb:cc:dd:ee:ff
Last target: ff:ff:ff:ff:ff:ff
Reason code: 7

The detection should be treated as an investigation signal rather than definitive proof of an attack.

---

Requirements

• Python 3
• Scapy
• Linux
• Wireless adapter capable of monitor mode
• Wireless interface already configured for monitor-mode capture

Install Scapy:

pip install scapy

---

Usage

Run the detector by specifying a wireless monitor interface:

sudo python3 deauthDetecter.py \
    --interface wlan0mon

Short form:

sudo python3 deauthDetecter.py \
    -i wlan0mon

---

Detection Threshold

Change the number of frames required for an alert:

sudo python3 deauthDetecter.py \
    -i wlan0mon \
    --threshold 5

Default:

8 frames

---

Detection Window

Change the sliding detection window:

sudo python3 deauthDetecter.py \
    -i wlan0mon \
    --window 15

Default:

10 seconds

---

Alert Cooldown

Change the minimum delay between repeated alerts for the same source:

sudo python3 deauthDetecter.py \
    -i wlan0mon \
    --cooldown 60

Default:

30 seconds

Disable the cooldown:

sudo python3 deauthDetecter.py \
    -i wlan0mon \
    --cooldown 0

---

Verbose Mode

Print every captured deauthentication frame:

sudo python3 deauthDetecter.py \
    -i wlan0mon \
    --verbose

Example:

[DEAUTH] source=aa:bb:cc:dd:ee:ff bssid=aa:bb:cc:dd:ee:ff target=ff:ff:ff:ff:ff:ff reason=7

---

Logging

Alerts are written by default to:

infoAboutAttacker.txt

The file is stored in the same directory as the Python script.

Use a custom log file:

sudo python3 deauthDetecter.py \
    -i wlan0mon \
    --log-file deauth_alerts.log

Disable logging:

sudo python3 deauthDetecter.py \
    -i wlan0mon \
    --no-log

---

How It Works

The detector uses Scapy to capture IEEE 802.11 frames.

Wireless Interface
        │
        ▼
Monitor Mode Capture
        │
        ▼
802.11 Frames
        │
        ▼
Dot11Deauth?
        │
        ├── No ──► Ignore
        │
        ▼
       Yes
        │
        ▼
Track transmitter + BSSID
        │
        ▼
Sliding time window
        │
        ▼
Threshold reached?
        │
        ├── No ──► Continue monitoring
        │
        ▼
       Yes
        │
        ▼
Generate Alert

---

Captured Information

For each detected deauthentication frame, the detector can identify:

Transmitter
BSSID
Target
Reason Code
Timestamp

When the configured threshold is exceeded, these values are included in the alert.

---

Why Burst Detection?

Deauthentication frames are part of legitimate IEEE 802.11 operation.

Normal Wi-Fi activity can therefore contain occasional deauthentication frames.

Alerting on every individual frame would create unnecessary false positives.

Deauth Detector instead looks for repeated activity within a short period of time.

This provides a more useful defensive signal while still keeping the implementation lightweight.

---

Limitations

This project is a lightweight wireless monitoring utility rather than a complete wireless intrusion detection system.

Important limitations include:

• Deauthentication frames can be spoofed.
• MAC addresses alone do not identify the physical attacker.
• Legitimate wireless activity can sometimes generate bursts of management frames.
• Detection depends on the wireless adapter, driver, channel, and monitor-mode configuration.
• The detector only sees frames captured by the selected interface.
• A threshold alert should be investigated rather than automatically treated as proof of an attack.

---

What This Project Demonstrates

The project demonstrates practical knowledge of:

• Python
• Scapy
• IEEE 802.11
• Wireless security
• Packet sniffing
• Deauthentication frames
• Sliding-window detection
• Defensive monitoring
• Event aggregation
• Alert throttling
• Linux wireless interfaces

---

Security & Responsible Use

Deauth Detector is a passive defensive monitoring tool.

It does not transmit deauthentication packets or interfere with wireless networks.

Use it only to monitor networks and wireless environments that you own or are authorized to inspect.

---

Author

Cyber Worm

GitHub: @bellurm