4.9 WiFi Spectrum Suite

Wi-Fi Spectrum Suite

Wi-Fi Spectrum Suite is designed to work seamlessly with Minino, a portable GPS-enabled device for wireless network scanning and wardriving.

Developed by: Electronic Cats - Dr. h. c. César A. Peregrino Rodríguez

Original Repository: WiFi-Spectrum-Suite by DarkAlguty

Wi-Fi Spectrum Suite is a comprehensive Python tool designed to analyze Wi-Fi scanned data, particularly from wardriving activities. It provides the following functionalities:

• Repairing CSV files with date format issues
• Analyzing Wi-Fi channel interference
• Generating geospatial visualizations (heatmaps, location maps)
• Detecting evil twin and spoofing attempts
• Creating detailed reports and advanced graphics

This tool is aimed at:

• Wardrivers: Individuals who scan for Wi-Fi networks while moving (e.g., in a car) to map coverage and security.
• Security Auditors: Professionals assessing Wi-Fi security and interference in specific areas.
• Community Mappers: Contributors to platforms like Wigle.net who want to visualize and analyze their wardriving data.

Main features

Feature	Description
Date Repair	Detects and fixes 7+ date format inconsistencies in CSV files
Fault-Tolerant Loading	5-strategy CSV parser handles malformed, encoded, or partially corrupt files
Channel Interference Analysis	Identifies congested and overlapping Wi-Fi channels with optimization recommendations
RSSI Signal Classification	5-tier quality classification (Excellent → Very Weak) with color-coded console output
Interactive RSSI Heatmap	Folium/OpenStreetMap heatmap weighted by signal strength
Geographic Location Map	Network markers grouped by SSID with popup signal stats
Advanced Wardriving Plots	6-panel analysis: channel boxplot, temporal evolution, auth distribution, spatial hexbin, and RSSI histogram
Security Analysis	Detects OPEN, WEP, WPA, WPA2 networks and flags insecure configurations
Evil Twin / Spoofing Detection	Identifies SSIDs with multiple MACs using mixed security — potential evil twin attacks
Spoofing CSV Report	Exports suspected spoofing entries with SSID, MAC, AuthMode, and alert classification
Rich Console UX	Color-coded output, progress feedback, and ASCII banner with random WiFi-themed phrases
Full Pipeline Command	Single command to run debug → interference → wardriving in sequence
File Size Guard	Rejects files over 500 MB to prevent memory exhaustion
Shell Tab Completion	Native tab completion for bash, zsh, and fish — auto-detects shell and installs with one command

Directory Structure

WiFiSpectrumSuite/
├── generatedFiles/        # Folder for generated outputs (maps, reports, graphs)
├── __init__.py
├── Legacy/                # Original scripts by Dr. h. c. César A. Peregrino Rodríguez
├── modules/               # Contains the main modules of the suite
│   ├── cli.py             # Click-based command-line interface
│   ├── __init__.py
│   ├── core/              # Core analysis functionalities
│   │   ├── csv_debugger.py
│   │   ├── __init__.py
│   │   ├── interference.py
│   │   └── wardriving.py
│   ├── utils/             # Shared utility functions
│   │   ├── file_utils.py
│   │   ├── __init__.py
│   │   ├── output.py
│   │   └── validators.py
│   └── visualization/     # Output generation (charts and maps)
│       ├── __init__.py
│       ├── maps.py
│       └── plots.py
├── pytest.ini
├── README.md
├── requirements.txt
├── setup.py
├── tests/
│   ├── conftest.py
│   ├── test_completion.py
│   ├── test_csv_debugger.py
│   ├── test_file_utils.py
│   ├── test_interference.py
│   ├── test_validators.py
│   └── test_wardriving.py
└── wifi_spectrum.py

Main Components

1. wifi_spectrum.py (Entry Point): Main script that exposes all system functionalities through structured CLI commands via the wifi-spectrum-suite entry point.
2. modules/ (Application Core)
   1. core/. Contains the three main analysis engines:
      • csv_debugger.py: Detects and repairs date format inconsistencies in CSV files. Supports ISO 8601, US, EU, and compact date formats. Processes files line-by-line for memory efficiency (up to 500 MB).
      • interference.py: Analyzes WiFi channel congestion, RSSI metrics, overlapping channels, and generates optimization recommendations.
      • wardriving.py: The WardrivingAnalyzer class. Loads wardriving data with multi-strategy parsing, normalizes column aliases, calculates metrics, detects security anomalies (evil twins, spoofing), and drives all output generation.
   2. utils/. Shared helpers used across modules:
      • validators.py: Date pattern detection (looks_like_date) and single-field date repair (repair_date_field). Handles non-date sentinel values (WPA2, WEP, OPEN, N/A, NULL).
      • file_utils.py: Fault-tolerant CSV loading (robust_csv_loader) with five fallback strategies and data cleaning (clean_and_validate_data).
      • output.py: Rich console helpers (print_success, print_warning, print_error, print_info) and RSSI-based color coding (rssi_color).
   3. visualization/. Generates all visual output:
      • plots.py: PNG chart generation using matplotlib and seaborn. Produces the 4-subplot interference chart and the 6-subplot wardriving analysis.
      • maps.py: Interactive HTML map generation using folium. Produces RSSI heatmaps and network location marker maps.

Output Files

File	Description
*_fixed.csv	Repaired CSV with corrected dates
*_report.txt	Interference analysis report with recommendations
*_analysis.png	4-subplot interference analysis chart
heat_map_*.html	Interactive RSSI intensity heatmap (folium)
location_map_*.html	Interactive network location map (folium)
advanced_plots_*.png	6-subplot wardriving analysis chart
*_spoofing.csv	Suspected evil twin and multi-MAC spoofing alerts

All files are saved to the generatedFiles/ directory.

Output Interpretation

RSSI Heatmap

• Intense red color → Very strong signal (−40 dBm)
• Yellow color → Moderate signal (−70 dBm)
• Light blue color → Weak signal (−90 dBm)

Wardriving Graphics

1. Network Distribution by Channel - Measures traffic congestion.
2. Average Signal Strenght by Channel - Measures signal strength of the channels
3. Signal Quality Distribution - Circle graphic indicating the signal quality of the read networks distribution
4. Networks by SSID (Top 8) - Top 8 networks detected with higher strenght
5. RSSI Distribution by Channel - Boxplot showing signal variability per channel
6. Average RSSI by Channel - Mean intensity with color coding
7. Temporal Signal Evolution - Signal change during scanning session
8. Authentication Methods - Security protocol distribution (pie chart)
9. Network Density and Singal Strenght (Hexbin) - Geographic concentration and signal strength
10. Signal Strenght Distribution - Overall intensity distribution

RSSI Metrics Interpretation

RSSI (dBm)	Quality	Recommendation
−30 to −50	Excellent	Optimal
−50 to −60	Very Good	Normal
−60 to −70	Good	Acceptable
−70 to −80	Fair	Consider repeater
−80 to −90	Weak	Poor coverage
< −90	Very Weak	Unusable

Interference Report

• Total networks detected
• Unique networks by SSID
• Channels used
• Channel distribution
• Problematic channels (overlapping with non-optimal channels)
• Strategic recommendations (2.4 GHz optimization, 5 GHz migration, QoS)

Spoofing Report

The *_spoofing.csv file contains:

• SSID - Network name flagged for analysis
• MAC - MAC address associated with the SSID
• AuthMode - Observed authentication method
• Alert - Classification: evil_twin (mixed security across MACs) or multi_mac (corporate/mesh networks with multiple MACs)

Note

Multi-MAC entries are not necessarily malicious — they may indicate mesh networks or enterprise APs. Review evil_twin alerts first.

Debug/Verbose

The suite prints detailed progress at each phase:

• Lines processed
• Errors detected
• Generated files
• Analysis statistics

Installation

Prerequisites:

• Python 3.12 or higher
• Git is installed on the system

Installing the Wi-Fi Spectrum Suite is recommended to be installed in a virtual environment to avoid conflicts with other Python dependencies on the system.

1. Download the WiFiSpectrumSuite tool or clone the whole Minino project by using the command:

git clone https://github.com/ElectronicCats/Minino.git

2. Open the folder that contains the WiFiSpectrumSuite tool, if using the terminal:

cd tools/WiFiSpectrumSuite

3. Create a virtual environment:

python -m venv .venv

4. Activate the virtual environment:

source .venv/bin/activate

• On Windows:

.venv\Scripts\Activate

5. Install the project and its dependencies in the virtual environment

pip install -e .

Autocompletion Installation

Wi-Fi Spectrum Suite supports native tab completion for bash, zsh, and fish on Unix-based systems (Linux and macOS).

To install it, follow the instructions below:

Important

Run once from the project directory with the virtual environment active. If you run the pip install -e . command as indicated in the tool installation instructions, it is not necessary to reinstall the autocompletion.

1. Run the script for the autocompletion installation:

   • Auto detect shell (recommended)

   python wifi_spectrum.py completion install

   • Specify the shell explicitly

     python wifi_spectrum.py completion install --shell zsh
     python wifi_spectrum.py completion install --shell bash
     python wifi_spectrum.py completion install --shell fish

After installation, open a new terminal (or source your rc file) to activate it.

Suite Functionality

1. CSV Debugger

Automatically detects and repairs common CSV file issues:

• Inconsistent date formats
• Empty or invalid field values
• Non-date sentinel values in date columns (WPA2, OPEN, N/A, NULL → replaced with timestamp)
• Damaged column structures

Supports multiple date formats:

• ISO 8601: 2024-01-15 10:30:00
• US: 01/15/2024 10:30:00
• EU: 15/01/2024 10:30:00
• Compact: 20240115103000

2. Interference Analyzer

Analyzes Wi-Fi channel patterns and interference:

• Network distribution by channel
• Channel overlap detection (non-overlapping: 1, 6, 11 in 2.4 GHz)
• Average signal strength calculation per channel
• Weak signal network identification (RSSI ≤ −80 dBm)
• Channel optimization recommendations
• Statistical interference graphs (4 subplots)

Signal quality classification:

• Excellent: ≥ −50 dBm
• Good: −60 to −50 dBm
• Fair: −70 to −60 dBm
• Weak: −80 to −70 dBm
• Very Weak: < −80 dBm

3. Wardriving Analyzer

Transforms scan data into geospatial visualizations:

• RSSI Heatmaps: Visualizes signal intensity by location
• Location Maps: Markers for each network with detailed info
• Advanced Graphics: Temporal analysis, channel distribution, histograms
• Security Analysis: Detection of OPEN, WEP, WPA, WPA2 networks
• Evil Twin Detection: Identifies SSIDs with multiple MACs and mixed security profiles
• Spoofing Report: CSV export flagging suspect networks with alert classification
• HTML Reports: Interactive maps based on Folium/OpenStreetMap

---

Usage

To start using Wi-Fi Spectrum Suite, you can use the command in a terminal session after creating and enabling the virtual environment:

wifi-spectrum-suite --help

Expected output:

╭─ Electronic Cats & Dr. h. c. César A. Peregrino Rodríguez ───────────────────────────────────────────────────────────╮
│                                                                                                                      │
│        :=--             --=-       |                                                                                 │
│        -====-         -=====       |                                                                                 │
│        :===================-       |                                                                                 │
│         ===================:       |                                                                                 │
│    -   :==--===========--==-   -   |  WiFi Spectrum Suite                                                            │
│   -===:===-   :=====-   -==-.-=--  |  v1.1.0.0                                                                       │
│  --    ====-   :===-   -====    -- |  Channel 6 is always crowded.                                                   │
│  -=:   :===================-   .=- |                                                                                 │
│   ---=-- -===============-  -=---  |                                                                                 │
│   ---       --=======--        --  |                                                                                 │
│                                                                                                                      │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
Usage: wifi-spectrum [OPTIONS] COMMAND [ARGS]...

  WiFi Spectrum Suite — Complete WiFi analysis suite.

  Use ``wifi-spectrum <subcommand> --help`` for more information.

Options:
  --version   Show the version and exit.
  -h, --help  Show this message and exit.

Commands:
  debug         Detects and repairs date format issues in a CSV FILE.
  full          Executes the complete pipeline: debug → interference →...
  interference  Analyzes WiFi channel interference in a CSV FILE.
  wardriving    Executes wardriving analysis on a CSV FILE.

1. Partial Analysis

Usage:

wifi-spectrum-suite debug <Your_Warfi_file.csv> --validate -o <Warfi_file_fixed.csv>

• Detects date format issues
• Generates Warfi_file_fixed.csv
• Repairs dates and validates the result

2. Analyze Interface Only

Usage:

wifi-spectrum-suite interference <Warfi_file_fixed.csv>

Output:

• *_fixed_analysis.png - Graphs
  • *_report.txt - Report

3. Heatmap generation

Usage:

wifi-spectrum-suite wardriving <Warfi_file_fixed.csv> --heat-map

Generates:

• heat_map_wardriving_data_fixed.html (interactive map)

4. Location map generation

Usage:

wifi-spectrum-suite wardriving <Warfi_file_fixed.csv> --location-map

Generates:

• location_map_wardriving_data_fixed.html (network markers)

5. Graphics generation

Usage:

wifi-spectrum-suite wardriving <Warfi_file_fixed.csv> --plots

Generates:

• advanced_plots_wardriving_data_fixed.png (advanced analysis graphs)

6. Wardriving report generation

Usage:

wifi-spectrum-suite wardriving <Warfi_file_fixed.csv> --report

• Prints a complete analysis to the terminal.

7. Complete Analysis

7.1 Total Integrated Analysis (Recommended)

Usage:

wifi-spectrum-suite full <Your_Warfi_file.csv> --validate

1. Date repair → *_fixed.csv
2. Interference analysis → graphs and report
3. Complete wardriving (maps, graphs, report)

Output:

• *_fixed.csv - Repaired CSV
• *_report.txt - Interference report
• *_fixed_analysis.png - Interference graphs
• heat_map_*_fixed.html - RSSI intensity map
• location_map_*_fixed.html - Network location map
• advanced_plots_*_fixed.png - Temporal and distribution analysis
• *_fixed_spoofing.csv - Evil twin/spoofing alerts

7.2 All Wardriving options

Usage:

wifi-spectrum-suite wardriving <Your_Warfi_file.csv> --all

Warfi fixed file required. See Partial Analysis

Output:

• Detailed report
• Heatmap
• Location map
• Advanced graphics

Minino + WiFi Spectrum Suite Workflow

Prerequisites:

• Minino is running the latest firmware version. See How to update your Minino.
• microSD card.
• Wi-Fi Spectrum Suite installed. Refer to section Installation
• A computer with a microSD reader or microSD adapter for extracting the data.

---

1. Connect the antennas to your Minino, insert a microSD and turn it on.

2. Enable the GPS in your Minino by going to: Settings > System > GPS > Enable/Disable.

3. Set the correct time zone in your Minino according to your region. You can set this by going to: Settings > System > GPS > Time Zone

4. Move to an open space or near a window to make sure you have a strong GPS signal.

5. Start a wardriving session by going to: Applications > GPS > Wardrive > AP Start.

6. Stop the wardriving session when needed. Data is automatically saved as a CSV file on the microSD card.

7. Turn off Minino and remove the microSD from it.

8. Copy the Warfi_YYYY-MM-DD_hh-mm-ss.csv file to your computer. The file is under warfi/ folder for Wi-Fi.

Important

You need to create and/or activate your virtual environment on each session.

source .venv/bin/activate

• On Windows:

.venv\Scripts\Activate

9. Repair and validate the Warfi_YYYY-MM-DD_hh-mm-ss.csv file using the command:

wifi-spectrum-suite debug Warfi_YYYY-MM-DD_hh-mm-ss.csv --validate

10. Analyze interference using the command:

wifi-spectrum-suite interference Warfi_YYYY-MM-DD_hh-mm-ss_fixed.csv

11. Generate a complete wardriving visualization using the command:

wifi-spectrum-suite wardriving Warfi_YYYY-MM-DD_hh-mm-ss_fixed.csv --all