Metadata-Version: 2.4
Name: wifilyzer
Version: 5.1.0
Summary: Complete WiFi 4/5/6/7 packet analysis platform
Home-page: https://github.com/nireshshanmugam/wifilyzer
Author: Niresh Shanmugam
Author-email: Niresh Shanmugam <niresh.shanmugam@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/nireshshanmugam/wifilyzer
Project-URL: Documentation, https://github.com/nireshshanmugam/wifilyzer#readme
Project-URL: Repository, https://github.com/nireshshanmugam/wifilyzer
Project-URL: Issues, https://github.com/nireshshanmugam/wifilyzer/issues
Keywords: wifi,network-analysis,packet-analysis,security,802.11
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Topic :: System :: Networking :: Monitoring
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: scapy>=2.5.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: flake8>=6.0; extra == "dev"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# WiFi Feature Detector

[![Python Version](https://img.shields.io/badge/python-3.13%2B-blue)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Version](https://img.shields.io/badge/version-5.1.0-green)]()

> **Complete WiFi 4/5/6/7 Analysis Platform** - Comprehensive packet analysis with 24 detection categories including security threats, beamforming, RRM features, QoS, power management, bandwidth analysis, and more.

---

## Table of Contents
- [Quick Start](#quick-start)
- [What's New in v5.1](#whats-new-in-v51)
- [Installation](#installation)
- [Usage](#usage)
- [Analysis Capabilities](#analysis-capabilities)
- [Use Cases](#use-cases)
- [Wireshark Filters](#wireshark-filters)
- [Architecture](#architecture)
- [Sample Output](#sample-output)
- [Performance](#performance)
- [Troubleshooting](#troubleshooting)
- [Contributing](#contributing)

---

## Quick Start

```bash
# Install dependencies
pip install scapy>=2.5.0

# Analyze a PCAP file
python wifilyzer.py capture.pcap

# View the report
cat capture_analysis_YYYYMMDD_HHMMSS.txt
```

**Output:**
- Text report: 700+ lines with 24 comprehensive sections
- JSON report: Complete structured data for programmatic access

---

## What's New in v5.1

### 🆕 NEW: Bandwidth & Throughput Analysis (Section 24)

**Per-Client Analysis:**
- Total data volume (bytes/KB/MB) per WiFi client
- TX/RX bandwidth (uplink/downlink separation)
- Average throughput (Kbps/Mbps) per client
- Data rate distribution (min/max/avg)
- MCS (Modulation and Coding Scheme) values
- Packet size statistics
- Associated APs tracking

**Per-AP Analysis:**
- Total bandwidth per Access Point
- TX/RX traffic separation
- Connected client count and list
- SSID and channel identification
- Average throughput metrics
- Data rate statistics

**Application/Protocol Traffic Identification:**
- Video Streaming: YouTube, Netflix, Hulu, Amazon Prime, Disney+, HBO, Twitch, TikTok
- Social Media: Facebook, Instagram, Twitter, Snapchat, WhatsApp, Telegram
- VoIP/Conferencing: Zoom, Skype, Teams, WebEx, Google Meet, Discord, Slack
- Voice: SIP, RTP, RTSP protocols
- Gaming: Xbox Live, PlayStation Network
- File Transfer: FTP, SFTP, SMB
- Email: SMTP, POP3, IMAP
- Port-based identification (HTTP/HTTPS, DNS, DHCP, etc.)
- TLS SNI (Server Name Indication) domain extraction
- QUIC protocol detection

**Traffic Direction Analysis:**
- Uplink traffic (Client → AP)
- Downlink traffic (AP → Client)
- Peer-to-peer/WDS traffic
- Percentage distribution by bytes and packets

**Protocol Distribution:**
- TCP, UDP, ICMP, ARP, DNS, DHCP, EAPOL breakdown
- Bandwidth consumption per protocol
- Packet count per protocol

**Multicast/Broadcast Traffic Analysis:**
- Multicast group detection and tracking
- IGMP (Internet Group Management Protocol) activity monitoring
- Per-client multicast bandwidth and throughput
- Video streaming multicast identification (RTP/UDP)
- Multicast group membership (joins/leaves)
- Broadcast traffic measurement
- Per-group statistics (clients, throughput, data volume)
- Streaming group identification and analysis

**Use Cases:**
- Identify bandwidth-heavy clients
- Detect which applications consume most bandwidth
- Monitor per-AP load and throughput
- Analyze traffic patterns for capacity planning
- Identify streaming vs. background traffic
- QoS troubleshooting and optimization
- Monitor IPTV and multicast video delivery
- Track multicast group membership
- Measure per-client multicast streaming performance
- Identify multicast bandwidth consumption

---

### 🎯 8 New Advanced Detection Modules (v5.0)

**Medium Priority Features:**
1. **Beamforming Analysis** - NDPA/NDP frames, MU-MIMO grouping, sounding frequency
2. **Spatial Reuse (BSS Coloring)** - WiFi 6 color detection, OBSS PD, collision detection
3. **Channel Interference** - Co-channel, hidden nodes, retry analysis, noise floor
4. **Client Capabilities** - WiFi generation, vendor ID (40+ OUIs), capability mismatches

**High Priority Features:**
5. **Security Analysis** - Deauth attacks, rogue APs, evil twins, weak encryption, KRACK indicators
6. **RRM Features (802.11k/v/r)** - Radio management, BSS transition, fast roaming
7. **QoS & WMM** - Traffic prioritization, EDCA, frame aggregation, AC distribution
8. **Power Save** - Legacy PS, U-APSD, TWT (WiFi 6), power management tracking

### 🏗️ Key Improvements
- ✅ **23 analysis sections**
- ✅ **Modular architecture** with 5 external detection modules
- ✅ **748-line reports** with detailed insights
- ✅ **Complete security threat detection suite**
- ✅ **RRM optimization analysis** (802.11k/v/r)
- ✅ **Power management analysis** (including WiFi 6 TWT)

---

## Installation

### Requirements
- Python 3.13 or higher
- Scapy 2.5.0 or higher
- WiFi adapter with monitor mode support (for captures)

### Setup

```bash
# Clone the repository
git clone <repository-url>
cd wifi-scripts

# Install Scapy
pip install scapy>=2.5.0

# Verify installation
python wifilyzer.py --help
```

### Capturing WiFi Traffic

**Linux (with monitor mode):**
```bash
# Enable monitor mode
sudo airmon-ng start wlan0

# Capture packets
sudo tshark -i wlan0mon -w capture.pcap

# Analyze
python wifilyzer.py capture.pcap
```

**Windows (with compatible adapter):**
```powershell
# Capture with tshark (Wireshark)
tshark -i "Wi-Fi" -w capture.pcap

# Analyze
python wifi6_feature_detector.py capture.pcap
```

---

## Usage

### Basic Analysis
```bash
python wifilyzer.py capture.pcap
```

### Advanced Capture Filtering
```bash
# Security monitoring (management frames only)
tshark -i wlan0 -f "wlan type mgt" -w security.pcap

# Beamforming analysis (control frames)
tshark -i wlan0 -f "wlan type ctl" -w beamform.pcap

# QoS analysis (data frames)
tshark -i wlan0 -f "wlan type data" -w qos.pcap

# RRM features (action frames)
tshark -i wlan0 -f "wlan type mgt subtype action" -w rrm.pcap
```

### Automated Testing Script
```bash
#!/bin/bash
INTERFACE="wlan0mon"
DURATION=60
OUTPUT="test_$(date +%Y%m%d_%H%M%S).pcap"

# Capture WiFi traffic
timeout $DURATION tshark -i $INTERFACE -w $OUTPUT

# Run analysis
python wifilyzer.py $OUTPUT

# Check for security issues
grep -E "ATTACK|WEAK|ROGUE" ${OUTPUT%.pcap}_analysis_*.txt
```

---

## Analysis Capabilities

### Complete Feature Set (24 Sections)

#### Core Analysis (Sections 1-15)
1. **File Information** - PCAP metadata, packet counts, duration
2. **WiFi Generation Detection** - WiFi 4/5/6/7 identification
3. **WiFi 6 Features** - HE capabilities, BSS Color, TWT, OFDMA
4. **Channel & PHY Layer** - Channel usage, widths, frequency
5. **Data Rates & Throughput** - MCS rates, throughput calculation
6. **Spatial Streams (MIMO)** - MIMO configuration, stream counts
7. **Network Topology** - APs and clients identification
8. **Management Frames** - Beacons, probes, auth, assoc
9. **Security Configuration** - Encryption types, authentication
10. **WiFi 7 Features** - EHT capabilities, MLO, 320MHz channels
11. **Roaming Analysis** - Handoff detection, reassociation
12. **DFS Channels** - Radar detection, DFS compliance
13. **Auto Channel Selection** - Channel switching, optimization
14. **Airtime Fairness** - Client airtime distribution
15. **Issues & Recommendations** - Problems detected, suggestions

#### ⭐ Advanced Features (Sections 16-24)

**16. Beamforming Analysis**
- Explicit/Implicit beamforming detection
- NDPA (Null Data Packet Announcement) frame analysis
- NDP (Null Data Packet) detection
- MU-MIMO grouping indicators
- Sounding frequency calculation
- SU/MU beamformer capabilities (VHT/HE)

**17. Spatial Reuse (BSS Coloring)**
- BSS Color detection (WiFi 6 feature)
- Spatial Reuse Parameter Set analysis
- OBSS PD (Overlapping BSS Packet Detect) thresholds
- Color collision identification
- Per-AP color tracking

**18. Channel Interference**
- Co-channel interference detection (multiple APs, same channel)
- Adjacent channel conflicts (±1, ±5 channel overlap)
- Hidden node detection (RTS/CTS frame ratio analysis)
- Noise floor measurement (from RadioTap)
- Retry rate analysis per client

**19. Client Capabilities**
- WiFi generation per client (WiFi 4/5/6/7)
- OUI-based vendor identification (40+ vendors: Apple, Intel, Cisco, Samsung, etc.)
- Capability mismatch detection (WiFi 6 client on WiFi 7 AP)
- PHY rate distribution analysis
- HT/VHT/HE/EHT capability parsing

**20. 🔒 Security Analysis**
- **Attack Detection:**
  - Deauthentication attacks (threshold: ≥10 frames)
  - Disassociation attacks
  - KRACK vulnerability indicators (EAPOL replay)
- **Rogue Device Detection:**
  - Rogue AP identification (multiple BSSIDs per SSID)
  - Evil twin detection (same SSID, different encryption/BSSID)
- **Encryption Analysis:**
  - WEP network detection (critical vulnerability)
  - Weak encryption alerts (WPA1)
  - Open network identification
  - RSN IE and WPA IE parsing

**21. 🔄 RRM Features (802.11k/v/r)**
- **802.11k (Radio Resource Management):**
  - RRM Enabled Capabilities IE detection
  - Neighbor Report Request/Response
  - Beacon Report Request/Response
  - Radio Measurement action frames
- **802.11v (BSS Transition Management):**
  - Extended Capabilities IE parsing
  - WNM action frames detection
  - BSS Transition Management Request/Response
- **802.11r (Fast Transition):**
  - Mobility Domain IE detection
  - Fast BSS Transition IE parsing
  - FT Authentication (algorithm 2)
  - FT Reassociation tracking
- **Client Steering:** AP-directed client movement
- **Load Balancing:** Client distribution optimization

**22. ⚡QoS & WMM Analysis**
- **QoS Detection:**
  - QoS Data frame identification (type=2, QoS bit)
  - WMM/QoS capability parsing
- **Access Category Distribution:**
  - VO (Voice): TID 6,7 - Highest priority
  - VI (Video): TID 4,5 - High priority
  - BE (Best Effort): TID 0,3 - Normal priority
  - BK (Background): TID 1,2 - Lowest priority
- **EDCA Parameters:**
  - AIFSN (Arbitration Inter-Frame Space Number)
  - CWmin/CWmax (Contention Window)
  - TXOP (Transmission Opportunity)
- **TSPEC:** Traffic specification detection
- **Frame Aggregation:**
  - A-MPDU (Aggregated MAC Protocol Data Unit)
  - A-MSDU (Aggregated MAC Service Data Unit)
- **Retry Analysis:** Per-AC retry rates

**23. 🔋Power Save Features**
- **Legacy Power Save:**
  - PS-Poll frames (type=1, subtype=0x0a)
  - TIM IE (Traffic Indication Map, ID 5)
  - DTIM (Delivery TIM) broadcast tracking
- **U-APSD (Unscheduled APSD):**
  - WMM Info Element detection
  - U-APSD bit parsing
  - Trigger-enabled ACs
- **TWT (Target Wake Time - WiFi 6):**
  - TWT IE detection (ID 255, Ext 216)
  - TWT agreements tracking
  - Protected HE action frames (category 22)
  - Individual/Broadcast TWT sessions
- **Power Management:**
  - Power Management bit tracking (FCfield & 0x10)
  - Clients in power save mode
  - Power efficiency calculation

**24. 📊 Bandwidth & Throughput Analysis**
- **Per-Client Metrics:**
  - Total data volume (bytes/KB/MB)
  - TX/RX bandwidth separation (uplink/downlink)
  - Average throughput (Kbps/Mbps)
  - Data rate distribution (min/max/avg)
  - MCS values and packet size statistics
  - Associated APs tracking
- **Per-AP Metrics:**
  - Total bandwidth per Access Point
  - TX/RX traffic analysis
  - Connected client count and identification
  - SSID, channel, and throughput metrics
- **Application/Protocol Identification:**
  - Video Streaming (YouTube, Netflix, etc.)
  - Social Media (Facebook, Instagram, etc.)
  - VoIP/Conferencing (Zoom, Teams, etc.)
  - Gaming, File Transfer, Email protocols
  - Port-based and TLS SNI domain analysis
  - QUIC and RTP stream detection
- **Traffic Analysis:**
  - Uplink/Downlink/P2P separation
  - Protocol distribution (TCP/UDP/etc.)
  - Top bandwidth consumers
  - Application-level traffic breakdown
- **Multicast/Broadcast Analysis:**
  - Multicast group detection and tracking
  - IGMP membership monitoring (joins/leaves/queries)
  - Per-client multicast bandwidth and throughput
  - Video streaming multicast identification
  - Per-group statistics (clients, throughput, sources)
  - Broadcast traffic measurement
  - Streaming group analysis with client counts
  - Average throughput (Kbps/Mbps)
  - Data rate distribution (min/max/avg)
  - MCS values and packet size statistics
  - Associated APs tracking
- **Per-AP Metrics:**
  - Total bandwidth per Access Point
  - TX/RX traffic analysis
  - Connected client count and identification
  - SSID, channel, and throughput metrics
- **Application/Protocol Identification:**
  - Video Streaming (YouTube, Netflix, etc.)
  - Social Media (Facebook, Instagram, etc.)
  - VoIP/Conferencing (Zoom, Teams, etc.)
  - Gaming, File Transfer, Email protocols
  - Port-based and TLS SNI domain analysis
  - QUIC and RTP stream detection
- **Traffic Analysis:**
  - Uplink/Downlink/P2P separation
  - Protocol distribution (TCP/UDP/etc.)
  - Top bandwidth consumers
  - Application-level traffic breakdown

---

## Use Cases

### 1. 🔒Security Audit
**Command:**
```bash
python wifilyzer.py audit.pcap
# Check Section 20: Security Analysis
```

**Detects:**
- ✅ Deauthentication attacks (≥10 frames = attack)
- ✅ Rogue access points (multiple BSSIDs per SSID)
- ✅ Evil twin networks (same SSID, different encryption)
- ✅ WEP networks (critical vulnerability)
- ✅ Weak encryption (WPA1)
- ✅ Open networks (no encryption)
- ✅ KRACK indicators (EAPOL replay attacks)

**Sample Output:**
```
⚠ DEAUTH ATTACK DETECTED!
  Total Deauth Frames: 45
  Attacker: 06:90:4c:00:00:00 (15 frames)

⚠ WEAK ENCRYPTION DETECTED!
  [Critical] NetworkName: WEP

⚠ ROGUE AP INDICATORS!
  SSID 'CoffeeShop': 3 different BSSIDs
```

---

### 2. WiFi 6/7 Validation
**Command:**
```bash
python wifilyzer.py wifi6_test.pcap
# Check Sections 3, 4, 10, 16, 17, 23
```

**Validates:**
- ✅ HE capabilities (WiFi 6)
- ✅ EHT capabilities (WiFi 7)
- ✅ BSS Color implementation
- ✅ TWT (Target Wake Time) support
- ✅ Beamforming capabilities
- ✅ Spatial Reuse parameters
- ✅ OFDMA usage
- ✅ Multi-Link Operation (MLO)

**Sample Output:**
```
✓ WiFi 6 Detected: 7,763 packets
  HE Capabilities: Present
  BSS Color: 52
  TWT Agreements: 3
  Beamforming: Detected (7,769 occurrences)
  Spatial Reuse: Enabled
```

---

### 3. Performance Troubleshooting
**Command:**
```bash
python wifilyzer.py performance.pcap
# Check Sections 18, 22 for interference and QoS
```

**Analyzes:**
- ✅ Channel interference (co-channel, adjacent)
- ✅ Hidden nodes (RTS/CTS ratio)
- ✅ Retry rates (per client and AC)
- ✅ QoS/WMM configuration
- ✅ Frame aggregation efficiency
- ✅ Noise floor levels

**Sample Output:**
```
⚠ Co-Channel Interference: 9 APs on channel 36
⚠ Hidden Nodes Detected: RTS/CTS ratio 0.98
⚠ High Retry Rate: 44.87%
✓ QoS Detected: WMM enabled
  VO: 120 frames (35%)
  VI: 80 frames (23%)
```

---

### 4. Roaming Optimization
**Command:**
```bash
python wifilyzer.py roaming.pcap
# Check Sections 11, 21 for roaming and RRM
```

**Evaluates:**
- ✅ 802.11k (Radio Resource Management)
- ✅ 802.11v (BSS Transition Management)
- ✅ 802.11r (Fast Transition/Fast Roaming)
- ✅ Client steering events
- ✅ Roaming behavior patterns
- ✅ Handoff timing

**Sample Output:**
```
✓ 802.11k Detected
  Neighbor Reports: 12
✓ 802.11v Detected
  BSS Transition Events: 7,764
✓ 802.11r Detected
  FT Authentication: 8
  Fast Roaming: Enabled
```

---

### 5. Client Device Profiling
**Command:**
```bash
python wifilyzer.py clients.pcap
# Check Section 19: Client Capabilities
```

**Profiles:**
- ✅ WiFi generation per device (4/5/6/7)
- ✅ Vendor identification (Apple, Intel, Samsung, etc.)
- ✅ Capability mismatches (WiFi 6 client on WiFi 7 AP)
- ✅ PHY rate distribution
- ✅ Device compatibility issues

**Sample Output:**
```
Client Capabilities:
  WiFi 6: 127 clients
  WiFi 5: 18 clients

Vendor Distribution:
  Apple: 45 clients
  Intel: 32 clients
  Samsung: 28 clients

⚠ Capability Mismatches: 16 detected
  Client aa:bb:cc:dd:ee:ff: WiFi 6 on WiFi 7 AP
  Impact: Cannot utilize advanced features
```

---

### 6. Power Management Analysis
**Command:**
```bash
python wifi6_feature_detector.py power.pcap
# Check Section 23: Power Save Features
```

**Analyzes:**
- ✅ Legacy Power Save (PS-Poll, TIM)
- ✅ U-APSD deployment
- ✅ TWT agreements (WiFi 6)
- ✅ Clients in power save mode
- ✅ Power efficiency metrics

**Sample Output:**
```
✓ Legacy Power Save Detected
  PS-Poll Frames: 10
  TIM Broadcasts: 7,564

✓ TWT (WiFi 6) Detected
  TWT Agreements: 5
  Clients Using TWT: 23

Clients in Power Save: 201
Power Management Frames: 1,422
```

---

## Wireshark Filters

### Security Analysis
```bash
# Deauthentication frames
wlan.fc.type_subtype == 0x0c

# Disassociation frames
wlan.fc.type_subtype == 0x0a

# WEP encrypted frames
wlan.wep.key

# WPA2/WPA3 (RSN IE)
wlan.rsn.version == 1

# EAPOL (4-way handshake)
eapol

# Open networks (no privacy bit)
wlan.fc.type_subtype == 0x08 && wlan.fixed.capabilities.privacy == 0
```

### WiFi 6/7 Features
```bash
# HE Capabilities (WiFi 6)
wlan.ext_tag.number == 35

# HE Operation (BSS Color)
wlan.ext_tag.number == 36

# EHT Capabilities (WiFi 7)
wlan.ext_tag.number == 108

# TWT IE (WiFi 6)
wlan.ext_tag.number == 216
```

### Beamforming
```bash
# NDPA frames (control subtype 5)
wlan.fc.type_subtype == 0x15

# VHT SU beamformer capability
wlan.vht.capabilities.beamformercap == 1

# VHT MU beamformer capability
wlan.vht.capabilities.mubeamformer == 1
```

### Spatial Reuse (BSS Color)
```bash
# HE Operation IE (contains BSS Color)
wlan.ext_tag.number == 36

# Spatial Reuse Parameter Set
wlan.ext_tag.number == 39
```

### RRM (802.11k/v/r)
```bash
# RRM Enabled Capabilities IE
wlan.tag.number == 70

# Radio Measurement action frames (802.11k)
wlan.fixed.category_code == 5

# WNM action frames (802.11v)
wlan.fixed.category_code == 10

# Mobility Domain IE (802.11r)
wlan.tag.number == 54

# Fast BSS Transition IE (802.11r)
wlan.tag.number == 55

# FT Authentication
wlan.auth.alg == 2
```

### QoS/WMM
```bash
# QoS Data frames
wlan.fc.type_subtype == 0x28

# Voice traffic (TID 6,7)
wlan.qos.priority == 6 || wlan.qos.priority == 7

# Video traffic (TID 4,5)
wlan.qos.priority == 4 || wlan.qos.priority == 5

# Best Effort (TID 0,3)
wlan.qos.priority == 0 || wlan.qos.priority == 3

# Background (TID 1,2)
wlan.qos.priority == 1 || wlan.qos.priority == 2

# WMM Parameter Element
wlan.wfa.ie.type == 2
```

### Power Save
```bash
# PS-Poll frames
wlan.fc.type_subtype == 0x1a

# Power Management bit set
wlan.fc.pwrmgt == 1

# TIM IE (Traffic Indication Map)
wlan.tag.number == 5

# TWT IE (WiFi 6)
wlan.ext_tag.number == 216

# U-APSD (check WMM Info Element)
wlan.wfa.ie.type == 0
```

### Channel Interference
```bash
# RTS frames (hidden node detection)
wlan.fc.type_subtype == 0x1b

# CTS frames
wlan.fc.type_subtype == 0x1c

# Retry bit set
wlan.fc.retry == 1

# Filter by specific channel
wlan_radio.channel == 36
```

### Frame Type Filters
```bash
# Management frames
wlan.fc.type == 0

# Control frames
wlan.fc.type == 1

# Data frames
wlan.fc.type == 2

# Beacons
wlan.fc.type_subtype == 0x08

# Probe Request
wlan.fc.type_subtype == 0x04

# Probe Response
wlan.fc.type_subtype == 0x05

# Authentication
wlan.fc.type_subtype == 0x0b

# Association Request
wlan.fc.type_subtype == 0x00

# Association Response
wlan.fc.type_subtype == 0x01

# Reassociation Request
wlan.fc.type_subtype == 0x02

# Action frames
wlan.fc.type_subtype == 0x0d
```

---

## Architecture

### Main Tool
```
wifilyzer.py (3,200+ lines)
├── Core detection (Sections 1-15)
├── Inline detection (beamforming, spatial reuse, interference)
├── Module integration (5 external modules)
├── Report generation (23 sections)
└── JSON/Text export
```

### Modular Design

```
detection_modules/
├── __init__.py                     # Module initialization
├── client_capabilities.py  (220 lines)
│   ├── OUI database (40+ vendors)
│   ├── WiFi generation detection
│   ├── Capability mismatch analysis
│   └── PHY rate distribution
│
├── security_analysis.py    (190 lines)
│   ├── Deauth/disassoc attack detection
│   ├── Rogue AP identification
│   ├── Evil twin detection
│   ├── Weak encryption alerts
│   └── KRACK indicators
│
├── rrm_features.py         (150 lines)
│   ├── 802.11k detection
│   ├── 802.11v detection
│   ├── 802.11r detection
│   └── Client steering
│
├── qos_analysis.py         (145 lines)
│   ├── WMM/QoS frame detection
│   ├── EDCA parameter extraction
│   ├── AC distribution
│   ├── Frame aggregation
│   └── Retry analysis
│
└── power_save.py           (120 lines)
    ├── Legacy PS (PS-Poll, TIM)
    ├── U-APSD detection
    ├── TWT (WiFi 6) detection
    └── Power management tracking
```

### Integration Flow

1. **Packet Loading** → Scapy reads PCAP file
2. **Core Detection** → WiFi generation, channels, management frames
3. **Inline Detection** → Beamforming, spatial reuse, interference
4. **Module Detection** → 5 external modules process packets
5. **Report Generation** → 23 sections formatted and exported
6. **JSON Export** → Structured data for programmatic access

---

## Sample Output

### Report Structure

```
╔══════════════════════════════════════════════════════════════╗
║              SECTION 1: FILE INFORMATION                      ║
╚══════════════════════════════════════════════════════════════╝

  PCAP File: capture.pcap
  File Size: 2.5 MB
  Total Packets: 15,053
  Duration: 120 seconds
  Capture Date: 2024-11-28

╔══════════════════════════════════════════════════════════════╗
║         SECTION 16: BEAMFORMING ANALYSIS                      ║
╚══════════════════════════════════════════════════════════════╝

  ┌─ 16.1 Beamforming Detection
  │
  │   ✓ Explicit Beamforming: DETECTED
  │      Count: 7,769 occurrences
  │      Details:
  │        Packet #1: HE - SU:False, MU:True
  │        Packet #2: HE - SU:False, MU:True
  │
  │   ✗ NDPA Frames: NOT DETECTED
  │   ✓ MU-MIMO Grouping: 54,040 indicators

╔══════════════════════════════════════════════════════════════╗
║          SECTION 20: SECURITY ANALYSIS                        ║
╚══════════════════════════════════════════════════════════════╝

  ┌─ 20.1 Security Status
  │
  │   ⚠ DEAUTH ATTACK DETECTED!
  │      Total Deauth Frames: 45
  │        da:d8:e5:ff:ce:c2: 13 deauth frames
  │        06:90:4c:00:00:00: 15 deauth frames
  │
  │   ⚠ WEAK ENCRYPTION DETECTED!
  │      [Critical] ETIFFCECA-5G: WEP
  │
  │   ⚠ WEP Networks: 23
  │
  │   ⚠ POTENTIAL EVIL TWIN DETECTED!
  │      Suspicious networks: 0
  │
  │   ⚠ Rogue AP Indicators: 1
  │      SSID 'ETIFFCECA-5G': 2 BSSIDs

╔══════════════════════════════════════════════════════════════╗
║      SECTION 21: RRM FEATURES (802.11k/v/r)                   ║
╚══════════════════════════════════════════════════════════════╝

  ┌─ 21.1 802.11k (Radio Resource Management)
  │
  │   ✓ 802.11k Detected
  │      Neighbor Reports: 0
  │      Beacon Reports: 0
  │
  ┌─ 21.2 802.11v (BSS Transition Management)
  │
  │   ✓ 802.11v Detected
  │      BSS Transition Events: 7,764
  │
  ┌─ 21.3 802.11r (Fast Transition)
  │
  │   ✗ 802.11r: NOT DETECTED

╔══════════════════════════════════════════════════════════════╗
║        SECTION 22: QoS AND WMM ANALYSIS                       ║
╚══════════════════════════════════════════════════════════════╝

  ┌─ 22.1 WMM/QoS Detection
  │
  │   ✓ WMM/QoS Detected: 39 QoS frames
  │      Access Category Distribution:
  │        BE: 1 (2.6%)
  │
  │   ✓ EDCA Parameters: 3 detected
  │   ✓ Frame Aggregation (A-MPDU): 15,052
  │   Retry Rate: 6.36%

╔══════════════════════════════════════════════════════════════╗
║          SECTION 23: POWER SAVE FEATURES                      ║
╚══════════════════════════════════════════════════════════════╝

  ┌─ 23.1 Power Save Detection
  │
  │   ✓ Legacy Power Save Detected
  │      PS-Poll Frames: 10
  │      TIM Broadcasts: 7,564
  │
  │   ✗ U-APSD: NOT DETECTED
  │   ✗ TWT: NOT DETECTED
  │
  │   Clients in Power Save: 201
  │      Power Management Frames: 1,422

════════════════════════════════════════════════════════════════
                          END OF REPORT
════════════════════════════════════════════════════════════════
```

### JSON Export Sample

```json
{
  "file_info": {
    "filename": "capture.pcap",
    "total_packets": 15053,
    "duration": 120.5
  },
  "beamforming": {
    "explicit_beamforming": {
      "detected": true,
      "count": 7769
    },
    "mu_mimo_grouping": {
      "detected": true,
      "count": 54040
    }
  },
  "security_analysis": {
    "deauth_attacks": {
      "detected": true,
      "total_deauth": 45,
      "by_ap": {
        "06:90:4c:00:00:00": 15
      }
    },
    "weak_encryption": {
      "detected": true,
      "networks": [
        {
          "ssid": "NetworkName",
          "encryption": "WEP",
          "severity": "Critical"
        }
      ]
    }
  },
  "rrm_features": {
    "802.11k": {
      "detected": true,
      "neighbor_reports": 0
    },
    "802.11v": {
      "detected": true,
      "bss_transition": 7764
    }
  }
}
```

---

## Performance

### Processing Speed

| Packet Count | Processing Time | Memory Usage | Report Size |
|--------------|----------------|--------------|-------------|
| 10,000       | ~1 second      | 150 MB       | ~650 lines  |
| 50,000       | ~5 seconds     | 300 MB       | ~750 lines  |
| 100,000      | ~15 seconds    | 500 MB       | ~800 lines  |
| 500,000      | ~90 seconds    | 1.5 GB       | ~850 lines  |

### Optimization Tips

```bash
# Capture only relevant frames
tshark -i wlan0 -f "wlan type mgt or wlan type ctl" -w capture.pcap

# Limit capture duration
timeout 60 tshark -i wlan0 -w capture.pcap

# Filter by time window
editcap -A "2024-11-28 10:00:00" -B "2024-11-28 10:05:00" \
  full.pcap filtered.pcap

# Process large files in chunks
split -l 50000 large.pcap chunk_
for f in chunk_*; do python wifi6_feature_detector.py "$f"; done
```

---

## Troubleshooting

### Module Import Errors
```bash
# Ensure detection_modules/ exists with all files
ls detection_modules/
# Should show: __init__.py, client_capabilities.py, security_analysis.py,
#              rrm_features.py, qos_analysis.py, power_save.py

# Check Python path
python -c "import sys; print(sys.path)"
```

### Scapy Version Issues
```bash
# Upgrade to latest Scapy (2.5.0+)
pip install --upgrade scapy

# Verify version
python -c "import scapy; print(scapy.__version__)"
```

### Empty Analysis Sections
**Cause:** PCAP doesn't contain relevant frame types
**Solution:**
- Capture longer duration
- Use monitor mode for complete frame visibility
- Check JSON output to see raw detection counts
- Verify capture includes management/control frames

### Permission Denied (Linux)
```bash
# Run with sudo for monitor mode
sudo python wifilyzer.py capture.pcap

# Or change permissions
sudo chmod +x wifilyzer.py
```

### High Memory Usage
```bash
# Process in streaming mode for large files
# Split file first
tcpdump -r large.pcap -w chunk_ -C 100

# Process each chunk
for file in chunk_*; do
  python wifilyzer.py "$file"
done
```

### Wireshark Filter Not Working
**Problem:** Filter syntax differs between Wireshark versions

**Solution for Wireshark 4.2.0+:**
- Use `wlan_radio.*` for RadioTap fields
- Use `wlan.ext_tag.number` for Extension IEs
- Check version: `Help → About Wireshark`

**For older versions (3.x):**
- Use `radiotap.*` for RadioTap fields
- Use `wlan.tag.number` for standard IEs

---

## Contributing

Contributions welcome! Here's how to add new detection modules:

### Adding a New Module

1. **Create module file:**
```python
# detection_modules/new_feature.py
def detect_new_feature(packets):
    """Detect new WiFi feature"""
    results = {
        'detected': False,
        'count': 0,
        'details': []
    }

    for pkt in packets:
        # Your detection logic here
        if meets_criteria(pkt):
            results['detected'] = True
            results['count'] += 1

    return results
```

2. **Add import to main file:**
```python
from detection_modules.new_feature import detect_new_feature
```

3. **Add wrapper method:**
```python
def detect_new_feature_wrapper(self):
    """Wrapper for new feature detection"""
    return detect_new_feature(self.packets)
```

4. **Update run_analysis():**
```python
print("[*] Detecting new feature...")
self.results['new_feature'] = self.detect_new_feature_wrapper()
```

5. **Add report section:**
```python
def _print_new_feature_section(self):
    """Print Section XX: New Feature"""
    feature = self.results.get('new_feature', {})
    print("\n╔" + "=" * 98 + "╗")
    print("║" + " " * 30 + "SECTION XX: NEW FEATURE" + " " * 45 + "║")
    print("╚" + "=" * 98 + "╝\n")
    # Your formatting here
```

### Development Guidelines
- Follow PEP 8 style guide
- Include docstrings for all functions
- Add type hints where appropriate
- Write tests for new features
- Update documentation
- Add Wireshark filters for new detections

---

## Repository Structure

```
wifilyzer/
│
├── wifilyzer.py                       # Main analysis tool (3,200+ lines)
│
├── detection_modules/                  # External detection modules
│   ├── __init__.py
│   ├── client_capabilities.py         # 220 lines
│   ├── security_analysis.py           # 190 lines
│   ├── rrm_features.py                # 150 lines
│   ├── qos_analysis.py                # 145 lines
│   └── power_save.py                  # 120 lines
│
├── README.md                           # This file (comprehensive guide)
├── requirements.txt                    # Python dependencies
├── LICENSE                             # MIT License
├── .gitignore                          # Git exclusions
│
├── captures/                           # PCAP capture files
│   └── wifi61.pcap                    # Sample capture (15K packets)
│
├── reports/                            # Generated analysis reports
│   ├── wifi61_analysis_*.txt          # Text reports (748 lines)
│   └── wifi61_analysis_*.json         # JSON exports
│
├── Supporting Documentation/
│   ├── CODE_OF_CONDUCT.md             # Community guidelines
│   ├── CONTRIBUTING.md                # Contribution guide
│   ├── SECURITY.md                    # Security policy
│   ├── SUPPORT.md                     # Support information
│   ├── SCAPY_LIMITATIONS.md           # Known Scapy issues
│   └── PUBLISHING.md                  # PyPI publishing guide
│
└── archive/                            # Historical files
    ├── Old version docs
    ├── Legacy scripts
    └── Previous test files
```

---

## License

MIT License - Free to use, modify, and distribute.

See [LICENSE](LICENSE) file for full details.

---

## Resources

### Standards & Specifications
- [IEEE 802.11 Working Group](https://www.ieee802.org/11/) - WiFi standards
- [WiFi Alliance](https://www.wi-fi.org) - WiFi certification and specs
- [IEEE 802.11ax (WiFi 6)](https://standards.ieee.org/standard/802_11ax-2021.html)
- [IEEE 802.11be (WiFi 7)](https://www.ieee802.org/11/Reports/tgbe_update.htm)

### Tools & Software
- [Wireshark](https://www.wireshark.org/) - Network protocol analyzer
- [Scapy](https://scapy.net/) - Packet manipulation library
- [tshark](https://www.wireshark.org/docs/man-pages/tshark.html) - CLI packet analyzer
- [aircrack-ng](https://www.aircrack-ng.org/) - WiFi security auditing

### Related Projects
- **kismet** - Wireless network detector and IDS
- **wifite** - Automated WiFi auditing tool
- **bettercap** - Network attack and monitoring framework

---

## Support

### Documentation
- Check **[VERSION_5.0_FEATURES.md](VERSION_5.0_FEATURES.md)** for detailed technical documentation
- Review **Troubleshooting** section above
- Examine JSON output for raw detection data

### Testing
- Use included sample: `wifi61.pcap` (15K packets)
- Verify all 23 sections generate
- Check module imports are successful

### Community
- Report issues on GitHub
- Share use cases and findings
- Contribute new detection modules

---

## Quick Command Reference

```bash
# Basic analysis
python wifilyzer.py capture.pcap

# View text report
cat *_analysis_*.txt

# View JSON (pretty print)
python -m json.tool *_analysis_*.json | less

# Search for security issues
grep -E "⚠|ATTACK|WEAK|ROGUE" *_analysis_*.txt

# Find specific section
grep "SECTION 20" *_analysis_*.txt

# Count all detections
grep -c "✓.*DETECTED" *_analysis_*.txt

# Extract beamforming info
grep -A 10 "SECTION 16" *_analysis_*.txt

# List all warnings
grep "⚠" *_analysis_*.txt

# Show WiFi generations
grep "WiFi [4567]" *_analysis_*.txt
```

---

## Version History

### v1.0.0 (2024-11-28) ⭐ Current Release

**Major Features:**
- ✅ Added 8 new detection modules (beamforming, security, RRM, QoS, power save)
- ✅ Modular architecture with 5 external modules (825 lines)
- ✅ Complete security analysis suite (deauth, rogue AP, evil twin detection)
- ✅ RRM features (802.11k/v/r) for optimized roaming
- ✅ QoS/WMM comprehensive analysis with AC distribution
- ✅ Power save mechanism detection (Legacy PS, U-APSD, TWT)
- ✅ 23 total analysis sections (up from 15)
- ✅ 748-line reports (up from 592)
- ✅ Enhanced client profiling with vendor ID and capability mismatches

**Technical Changes:**
- Created `detection_modules/` directory structure
- 5 new module files (~825 lines total)
- 8 new wrapper methods in main class
- Updated report generation with 8 new sections
- Enhanced JSON output structure
- Added 20+ Wireshark filters

- WiFi 6/7 generation detection
- Roaming behavior analysis
- DFS channel detection
- Auto channel selection
- Airtime fairness
- 15 analysis sections

---

## Educational Use

Perfect for:
- 🎓 **Network Engineers** - WiFi troubleshooting, optimization, capacity planning
- 🔒 **Security Professionals** - WiFi security auditing, threat detection, compliance
- 📚 **Students** - Learning WiFi protocols, 802.11 standards, network analysis
- 🔬 **Researchers** - Analyzing WiFi behavior, performance studies, protocol research
- 💼 **IT Departments** - Validating deployments, troubleshooting user issues
- 🏢 **Enterprise Networks** - Large-scale WiFi health monitoring and optimization

---

## Acknowledgments

**Contributors:**
- Niresh Shanmugam (niresh.shanmugam@gmail.com)

**Built With:**
- [Scapy](https://scapy.net/) - Packet manipulation framework
- [Python](https://www.python.org/) - Core language

**Standards:**
- IEEE 802.11 working group - WiFi standards
- WiFi Alliance - Certification specifications

**Inspired By:**
- Real-world WiFi troubleshooting challenges
- Enterprise network optimization needs
- Security auditing requirements

---

**WiFi Feature Detector v5.0 - Your Complete WiFi Analysis Solution** 🚀

*Made with ❤️ for WiFi enthusiasts, network engineers, and security researchers*

*Last Updated: November 28, 2024*

