Squall — Wireless Deauthentication Flood Detector

Ships as the deauthguard CLI/library — see below.

Overview

The original version is a hands-on 802.11 deauthentication-attack lab performed against the team's own router ("PTCL FLASH FIBER," explicitly the group's own equipment used for simulation) using Kali Linux and the Aircrack-ng suite, with both broadcast and targeted attack modes verified in Wireshark.

New addition: deauthguard/ — a real, passive 802.11 deauthentication/disassociation flood detector: the defensive counterpart the original never had. It analyzes a live monitor-mode interface or an offline PCAP, correlates disconnect bursts by BSSID and client using Kismet/Cisco-precedented rate heuristics, and emits explainable, severity-ranked alerts — turning the same subject matter (802.11 management frames, monitor mode, the Aircrack-ng ecosystem) from "how to attack" into "how to detect." See deauthguard/README.md.

Problem Statement

Demonstrate, against equipment the team actually owns and controls, how trivially exploitable unauthenticated 802.11 management frames (deauth) are, and evaluate what actually defends against it. (New: and build the detection side of that evaluation as working, tested software rather than a comparison table alone.)

Objectives

(original)

• Perform broadcast and targeted deauthentication attacks against an owned router.
• Verify disconnects and captured WPA2 handshakes in Wireshark.
• Compare the effectiveness of available defense mechanisms.

(this addition)

• Build a minimal, explainable passive WIDS for exactly the attack class the original lab demonstrated, grounded in real prior art (Kismet, Cisco WIDS signatures) rather than an invented threshold.
• Treat detection as rate/behavior-based, never a single-frame or single-reason-code trigger — and document why, since both the claimed transmitter address and the reason code are attacker-controllable when PMF is absent.
• Validate against a labeled, synthetic PCAP corpus with an offline pytest suite, so CI can actually run it — no hardware, no monitor mode, no root required.

Tools and Technologies

(original) Kali Linux; Aircrack-ng suite (airmon-ng, airodump-ng, aireplay-ng); Wireshark; ALFA AWUS036NHA (monitor-mode-capable wireless adapter)

(this addition) Python 3.12, Scapy 2.7 (802.11 parsing, live sniff and offline PCAP replay), pytest, Ruff, PyYAML, GitHub Actions

Features

(original) N/A — this is a lab report, not a coded tool.

(this addition — see deauthguard/README.md for full detail)

• Four independent, explainable detection rules: disconnect-burst, targeted-disconnect-burst, broadcast-disconnect, victim-sweep.
• Works identically against a live monitor-mode interface or an offline PCAP (same parser, same detection engine, PCAP capture timestamps used instead of processing speed).
• Conservative radio-retry deduplication that never collapses a genuine flood.
• Alert coalescing (detected → updated → recovered) instead of one alert per matching frame.
• A deauthguard explain-reason <code> command that surfaces 802.11 reason codes along with the caveat that they're attacker-suppliable, not proof.
• 24 pytest tests against committed, synthetic (reserved-MAC) PCAP fixtures — fully offline, runnable in CI.

Methodology

(original)

1. Put the wireless adapter into monitor mode (airmon-ng).
2. Scan for the target (own) network (airodump-ng).
3. Run a broadcast deauth attack (aireplay-ng --deauth 1000).
4. Run a targeted deauth attack against a specific client (aireplay-ng --deauth 100 -c [client]).
5. Verify both attacks in Wireshark using the wlan.fc.type_subtype == 0x0c filter.
6. Compare defense mechanisms (802.11w/PMF, WPA3, WIDS, firmware updates, VPN, MAC filtering).

(this addition) 7. Design a detection engine around real WIDS precedent (Kismet's DEAUTHFLOOD/BCASTDISCON alerts, Cisco's management-frame flood signatures) rather than an arbitrary threshold — see PROJECT_NOTES.md for the full research writeup and citations. 8. Generate labeled synthetic PCAP fixtures (normal traffic, a targeted flood, a broadcast flood, a multi-client sweep, radio retries, a slow below-threshold trickle) and pin exact sliding-window boundary behavior with pytest. 9. Exercise the CLI end-to-end against every fixture and confirm the rendered alerts match the expected rule, severity, and evidence.

How It Works

Repository Structure

squall/
  README.md, PROJECT_NOTES.md, CHANGELOG.md, project.yaml
  deauthguard/                  NEW: the passive disconnect-flood detector
    README.md                  design writeup, rules table, limitations
    src/deauthguard/            parser, sources, dedup, detector, cli, reasons
    config/default.yaml         Kismet-inspired defaults, documented as such
    tests/                      24 pytest tests + tests/pcaps/ synthetic fixtures
    tools/generate_test_pcaps.py   regenerates the fixtures
    validation/README.md        honest status of real-capture validation
  docs/network-security-deauthentication-report.docx (+ .pdf)   original, untouched
  references/references.md
  screenshots/
  .github/workflows/deauthguard-ci.yml   NEW: lint + full offline pytest run

Setup Instructions

Original: N/A — no test/attack scripts were included with the submission beyond the documented Aircrack-ng commands.

New (deauthguard/):

cd deauthguard
python -m venv .venv && source .venv/bin/activate   # or .venv\Scripts\activate on Windows
pip install -e ".[dev]"

Usage

Original: N/A.

New:

cd deauthguard
deauthguard analyze tests/pcaps/broadcast_flood.pcap
deauthguard monitor wlan0mon   # requires a monitor-mode interface
deauthguard explain-reason 7

How to Review

1. Start with this README, then docs/network-security-deauthentication-report.docx for the original.
2. Review screenshots/ (7 images) for the original attack setup, execution, and Wireshark verification.
3. New: read deauthguard/README.md, then PROJECT_NOTES.md for the full research writeup (Kismet/Cisco precedent, the reason-code/PMF caveats, and the alert-coalescing design).
4. Run cd deauthguard && pytest -q and deauthguard analyze tests/pcaps/broadcast_flood.pcap to see it work firsthand.

Screenshots

See screenshots/ — includes adapter/monitor-mode setup, network scanning, attack execution, and Wireshark verification of captured deauth frames and handshakes (original, unchanged).

Results

Original: both broadcast and targeted deauthentication attacks successfully disconnected the target client; Wireshark confirmed the deauth frames and captured a WPA2 4-way handshake. The report includes a defense-mechanism comparison table: 802.11w/PMF and WPA3 rated High effectiveness, WIDS Medium-High, firmware updates Medium, VPN (protects traffic but doesn't stop deauth), and MAC filtering Low (trivially spoofable).

New: DeauthGuard's 24-test pytest suite passes cleanly (offline, synthetic PCAP fixtures) and Ruff reports zero issues. Run against the committed fixtures, it correctly stays silent on normal and slow below-threshold disconnect traffic, and correctly raises high/critical alerts with accurate evidence on the targeted-flood, broadcast-flood, and multi-client-sweep fixtures — see deauthguard/README.md "Detection rules" for the exact thresholds. Real-capture validation against the original lab's own traffic is not yet available — see deauthguard/validation/README.md for why, and what's needed to close that gap honestly rather than fabricate a result.

Limitations

(original)

• Lab-only, single-router scope; no evaluation of enterprise WIDS/WIPS deployments.
• Findings apply to unprotected 802.11 management frames generally, not to networks already running 802.11w/WPA3.

(this addition — see deauthguard/README.md "Limitations" for full detail)

• Single-channel visibility only (one monitor-mode radio watches one channel at a time).
• Does not currently detect PMF/802.11w state itself, though an alert under PMF still has meaning (an attempted, not necessarily successful, disruption).
• No cross-BSSID correlation across a rotating-BSSID attacker.
• No validation yet against a real (non-synthetic) capture — see deauthguard/validation/README.md.

Future Enhancements

(original)

• (none stated in the source report)

(this addition)

• Derive PMF/RSN state from beacon/probe-response frames instead of static config.
• A real authorized-capture validation run, once/if one becomes available.
• Multi-radio or channel-hopping coverage.

Safety and Privacy

• The original attack was performed only against the team's own router, explicitly for simulation.
• The report states an intent to redact "sensitive identifiers such as MAC addresses where necessary." One network-scan screenshot in this project (screenshots/04-network-scanning-packet-capture.png, also embedded in the DOCX/PDF report) shows unredacted BSSIDs/SSIDs of real neighboring Wi-Fi networks picked up incidentally during the scan — only the target row is blacked out. This was reviewed and kept as originally submitted; see PROJECT_NOTES.md for the full note on this.
• deauthguard/'s test fixtures use only synthetic, locally-administered (reserved-range) MAC addresses — no real network or client identifiers are present anywhere in the new code.

Ethical Notice

This project is intended strictly for personal learning and authorized security research. The original attack lab was performed only against equipment the team owns and controls, for simulation purposes. Deauthentication attacks against networks you do not own or have explicit authorization to test are illegal in most jurisdictions and must not be performed.

deauthguard/ is purely passive and defensive — it never transmits an 802.11 frame. It only listens (live) or replays a file (offline) and reports what it observes; running it against any network, owned or not, carries none of the original lab's authorization concerns.