Sparrow-WiFi

Overview

Sparrow-WiFi is a sophisticated spectrum analysis and wireless reconnaissance tool combining WiFi/Bluetooth scanning with GPS mapping, signal strength visualization, and security assessment. Provides real-time spectrum awareness, helps identify rogue access points, unauthorized devices, and RF interference patterns.

Installation

Linux (Debian/Ubuntu)

# Install dependencies
sudo apt-get update
sudo apt-get install python3 python3-pip git
sudo apt-get install libssl-dev libffi-dev

# Clone repository
git clone https://github.com/Krelith/sparrow-wifi.git
cd sparrow-wifi

# Install Python dependencies
pip3 install -r requirements.txt

# Run Sparrow-WiFi
python3 sparrow.py

Linux (Fedora/RHEL)

# Install dependencies
sudo dnf install python3 python3-pip gcc python3-devel
sudo dnf install openssl-devel libffi-devel

# Clone and install
git clone https://github.com/Krelith/sparrow-wifi.git
cd sparrow-wifi
pip3 install -r requirements.txt
python3 sparrow.py

macOS

# Install Homebrew dependencies
brew install python3 git

# Clone repository
git clone https://github.com/Krelith/sparrow-wifi.git
cd sparrow-wifi

# Install Python dependencies
pip3 install -r requirements.txt

# Run application
python3 sparrow.py

Docker

# Build Docker image
docker build -t sparrow-wifi .

# Run with X11 forwarding
docker run -it --rm \
  -v /tmp/.X11-unix:/tmp/.X11-unix \
  -e DISPLAY=$DISPLAY \
  sparrow-wifi

Kali Linux

# Pre-installed or install via
sudo apt install sparrow-wifi

# Or build from source
git clone https://github.com/Krelith/sparrow-wifi.git
cd sparrow-wifi && python3 sparrow.py

Hardware Requirements

WiFi Adapters

# Supported chipsets
# - Realtek RTL8812AU/RTL8814AU
# - Atheros AR9XXX
# - Intel Wireless 3160/3165/8260/8265
# - Qualcomm/Broadcom WLAN adapters

# Check supported devices
lsusb | grep -i wireless

# Monitor mode capability
iwconfig
ip link show

GPS Devices

# USB GPS receivers
# - Garmin eTrex
# - u-blox ZED-F9P
# - GlobalSat BU-353-S4

# GPSD daemon setup
sudo apt install gpsd gpsd-clients
sudo gpsd -n /dev/ttyUSB0

# Test GPS connection
cgps -s

Basic Operation

Starting Sparrow-WiFi

# Launch GUI application
python3 sparrow.py

# Specify config file
python3 sparrow.py --config config.json

# Headless mode
python3 sparrow.py --headless

# Verbose logging
python3 sparrow.py -v --debug

Interface Setup

# Enable monitor mode on wireless adapter
sudo iwconfig wlan0 mode Monitor

# Set channel
sudo iwconfig wlan0 channel 6

# Verify monitor mode
iwconfig wlan0 | grep Mode

# Using airmon-ng for automation
sudo airmon-ng start wlan0

# Check active monitors
sudo airmon-ng

WiFi Network Discovery

Network Scanning

# Start WiFi enumeration
# In GUI: Select adapter and start scanning

# Scan specific channels
# CLI: sparrow-cli --channel 1-13

# Full spectrum scan (2.4 GHz)
# Scans channels 1-14 for 802.11b/g/n

# 5 GHz spectrum scan
# UNII bands: 36-165 channels

# WiFi 6E (6 GHz)
# Additional channels available on newer hardware

Network Information Extraction

# SSID discovery
# Displays all visible networks

# BSSID (MAC address) mapping
# Identifies access point hardware addresses

# Signal strength (RSSI)
# Real-time dBm measurements

# Channel analysis
# Frequency and bandwidth information

# Security protocols
# WEP, WPA, WPA2, WPA3 detection

# Network type classification
# Infrastructure, Ad-hoc, Mesh identification

Signal Strength and Analysis

RSSI Visualization

# Real-time signal graph
# Displays network signal strength over time

# Per-network RSSI tracking
# Multiple networks simultaneously

# Historical data logging
# Export signal measurements

# Interference detection
# Adjacent channel interference identification

# Signal quality estimation
# SNR and connection quality metrics

Channel Analysis

# Channel utilization
# Displays occupied channels and interference

# Channel recommendations
# Auto-suggest least congested channels

# Frequency overlap detection
# Identifies overlapping 2.4 GHz networks

# 5 GHz channel spacing
# Non-overlapping channel identification

# DFS channels monitoring
# Radar detection and channel switching

GPS and Mapping Features

GPS Configuration

# Connect GPS device
# Settings → GPS → Enable GPS
# Select /dev/ttyUSB0 or appropriate port

# NMEA data format
# Standard GPS coordinate output

# Automatic waypoint logging
# Saves coordinates with signal data

# Route tracking
# Records movement history

# Geolocation mapping
# Visual representation on map

Mapping and Visualization

# Access point location mapping
# Plots networks on geographic map

# Signal heat map
# Visualizes coverage areas

# Strength gradient display
# Color-coded RSSI visualization

# Access point clustering
# Groups nearby networks

# Route replay
# Playback of scanning path

# Export map data
# KML, GPX format output

Bluetooth Scanning

Bluetooth Discovery

# Enable Bluetooth scanning
# Settings → Bluetooth → Enable BLE scanning

# Bluetooth device enumeration
# Discovers nearby BLE devices

# MAC address tracking
# Identifies device manufacturers

# Signal strength monitoring
# BLE RSSI measurements

# Advertising packet analysis
# Examines beacon contents

# Device classification
# Categorizes by device type

Bluetooth Security Analysis

# Legacy pairing detection
# Identifies vulnerable devices

# Unpaired device discovery
# Finds unprotected Bluetooth

# MAC randomization monitoring
# Tracks privacy-enabled devices

# Advertising data inspection
# Analyzes transmitted information

# Power level assessment
# TX power classifications

# Device fingerprinting
# Unique signature identification

Security Assessment

Vulnerability Detection

# Open network identification
# Networks broadcasting SSID with no encryption

# WEP detection and flagging
# Deprecated encryption alert

# WPA/WPA2/WPA3 monitoring
# Protocol version identification

# Key reuse detection
# Identifies potential shared credentials

# Evil twin detection
# Suspicious access point identification

# Deauth attack detection
# Monitors for 802.11w violations

Rogue Access Point Detection

# Same SSID, different BSSID
# Identifies duplicate networks

# Unusual RSSI patterns
# Detects spoofed networks

# Geolocation anomalies
# Access point location inconsistencies

# Signal strength irregularities
# Abnormal power levels

# Suspicious encryption changes
# WPA downgrade detection

# Unauthorized extension discovery
# Networks using enterprise SSIDs

Data Export and Reporting

Export Formats

# CSV export
# Network details and measurements

# KML export
# Geographic mapping data

# JSON export
# Structured data format

# GPX export
# GPS track information

# PCAP export
# Packet capture files

# PDF report generation
# Professional assessment documentation

Report Generation

# Standard scan report
# Summary of discovered networks

# Security assessment report
# Vulnerability findings

# Coverage map report
# Signal strength visualization

# Detailed signal analysis
# RSSI and interference data

# Compliance report
# Security standards assessment

# Custom report building
# Selective data inclusion

Advanced Features

Packet Inspection

# Frame capture display
# Raw packet information

# Beacon frame analysis
# AP capabilities examination

# Probe request monitoring
# Client-side device detection

# Association tracking
# Connected device monitoring

# Deauthentication monitoring
# Network disruption detection

# Management frame analysis
# 802.11 control frame inspection

Geofencing and Alerts

# Define boundary areas
# Geographic scanning limits

# Alert on network appearance
# Notification on SSID discovery

# RSSI threshold alerts
# Signal strength thresholds

# Location-based triggers
# Actions based on GPS location

# Unauthorized network alerts
# Custom blocklist enforcement

# Device presence notification
# Known device tracking

Workflow Examples

Site Survey and Coverage Assessment

# 1. Configure GPS device
Settings → GPS → Enable
Verify GPS lock (3+ satellites)

# 2. Start walking survey
Click Start Scan
Record position and RSSI

# 3. Create coverage map
Export → KML format
Import to Google Earth

# 4. Generate report
Export → PDF report
Include heat map visualization

# 5. Analysis
Identify weak signal areas
Recommend AP placement
Document channel congestion

Security Assessment Mission

# 1. Initial scanning
# Enable all scanning options
# Run full spectrum scan
# Document all networks

# 2. Threat identification
# Flag unencrypted networks
# Identify WEP networks
# Note suspicious SSIDs

# 3. Vulnerability assessment
# Check for evil twins
# Analyze signal patterns
# Document geolocation anomalies

# 4. Report generation
# Export detailed findings
# Include signal maps
# Provide recommendations

# 5. Remediation tracking
# Re-scan after fixes
# Verify improvement
# Document compliance

Rogue Access Point Hunting

# 1. Pre-survey baseline
# Document all authorized APs
# Record expected locations
# Note normal signal patterns

# 2. Active scanning
# Real-time RSSI monitoring
# Geolocation tracking
# Signal anomaly detection

# 3. Anomaly investigation
# Investigate unusual SSIDs
# Check unexpected BSSIDs
# Verify MAC addresses

# 4. Threat response
# Document findings
# Alert security team
# Generate evidence report

# 5. Follow-up
# Physical location search
# Device confiscation
# Network cleanup

Command-Line Tools

Alternative Usage Methods

# View help documentation
python3 sparrow.py --help

# List available adapters
python3 sparrow.py --list-adapters

# Scan specific adapter
python3 sparrow.py --adapter wlan0

# Set scan duration
python3 sparrow.py --duration 300

# Output to file
python3 sparrow.py --output results.csv

# Enable GPS logging
python3 sparrow.py --gps /dev/ttyUSB0

Troubleshooting

No Networks Detected

# Verify adapter in monitor mode
iwconfig | grep Monitor

# Enable monitor mode
sudo airmon-ng start wlan0

# Check regulatory domain
sudo iw reg get
sudo iw reg set US

# Verify adapter capabilities
iw phy phy0 info | grep -A 10 "Supported frequencies"

# Restart WiFi scanning
killall sparrow.py
python3 sparrow.py

GPS Not Connecting

# List available ports
ls -la /dev/tty*

# Start GPSD daemon
sudo systemctl start gpsd
sudo gpsd -D 3 /dev/ttyUSB0

# Verify GPS connection
cgps -s
gpspipe -r

# Check permissions
sudo usermod -a -G dialout $USER

High CPU Usage

# Reduce update frequency
# Settings → Performance
# Decrease refresh rate

# Limit channel scanning
# Select specific channels
# Reduce scan range

# Disable Bluetooth scanning
# Settings → Bluetooth → Disable

# Reduce map rendering
# Switch to list view

Best Practices

1. Authorization: Only scan networks and frequencies you’re authorized to assess
2. Legal Compliance: Verify WiFi scanning laws in your jurisdiction
3. GPS Accuracy: Allow GPS several minutes to achieve lock
4. Data Protection: Secure exported reports containing location data
5. Channel Respect: Avoid interference with legitimate networks
6. Documentation: Log all scans with timestamp and location

Related Tools

• Aircrack-ng: WiFi penetration testing suite
• Kismet: Advanced wireless network analyzer
• WiFi Analyzer: Android app for signal analysis
• NetSpot: Commercial site survey software
• inSSIDer: WLAN analysis tool
• Wireshark: Packet capture and analysis

Safety and Legal Considerations

• WiFi scanning is legal in most jurisdictions with proper authorization
• Jamming or interfering with networks is illegal
• Data capture from open networks may have privacy implications
• Always obtain written permission before security assessments
• Respect Do Not Disturb (DND) frequencies
• Document all scanning activities for compliance

References

• Sparrow-WiFi GitHub: https://github.com/Krelith/sparrow-wifi
• 802.11 Standards: IEEE 802.11 Specification
• GPS Standards: NMEA 0183 Protocol
• Bluetooth LE: Bluetooth SIG Specifications
• FCC Regulations: 47 CFR Part 15
• ISM Band Standards: International Frequency Allocations