A comprehensive network analysis tool for macOS that provides deep insights into network interfaces, performance, quality, and connectivity.
- Comprehensive Interface Analysis: Detailed information about all network interfaces
- WiFi Diagnostics: Signal strength, channel analysis, SNR, interference detection
- Network Performance: Speed tests, latency measurements, packet loss analysis
- iperf3 Bandwidth Testing: Upload and download throughput via iperf3 server
- Health Assessment: Automated network health scoring with recommendations
- Dual Mode Operation: Works both offline (no internet) and online (with internet)
- Professional UI: Rich terminal interface with color-coded tables and panels
- Detailed Logging: Structured JSON and human-readable logs with optional comment annotation
- macOS 12.0+ (macOS 12.1+ recommended for speed testing)
- Python 3.11 or higher
-
Clone or download this repository
-
Create a virtual environment:
python3 -m venv venv source venv/bin/activate -
Install dependencies:
pip install -r requirements.txt
-
Make the main script executable:
chmod +x main.py
Simply run the tool without arguments to interactively select an interface:
python main.pypython main.py --interface en0
python main.py -i en0python main.py --all# Force offline mode (skip internet tests)
python main.py -i en0 --mode offline
# Force online mode
python main.py -i en0 --mode onlinepython main.py -i en0 --no-wifi-scanDNS reliability testing is enabled by default in online mode. It tests 100 highly reliable domains:
# DNS test runs automatically
python main.py -i en0
# Skip DNS test to save time
python main.py -i en0 --skip-dns-testThe DNS test shows:
- Success rate (percentage of successful DNS lookups across 100 domains)
- Average, minimum, and maximum response times
- List of failed domains (if any)
Note: This test takes 1-2 minutes as it queries 100 different domains to provide a comprehensive reliability assessment.
Run a full upload and download bandwidth test against an iperf3 server:
python main.py -i en0 --iperf3 192.168.1.100
python main.py -i en0 --iperf3 192.168.1.100 --mode onlineRequires an iperf3 server running on the target IP (default port 5201). Runs in online mode automatically. Results show upload Mbps, download Mbps, and TCP retransmits.
Append a label to log filenames and embed the full comment in the log headers:
python main.py -i en0 --comment "HomeNetwork"
python main.py -i en0 --comment "test run after router reboot"The first word of the comment is appended to all log filenames (e.g., network_analysis_20260220_143022_HomeNetwork.log). The full comment text is written into the log file header.
python main.py -i en0 --output ~/Desktop/network_analysis.log| Option | Description |
|---|---|
-i, --interface |
Specific interface to analyze (e.g., en0) |
-a, --all |
Analyze all active interfaces |
--mode |
Operating mode: offline, online, or auto (default: auto) |
--no-wifi-scan |
Skip WiFi network scanning (faster) |
--skip-dns-test |
Skip DNS reliability test (runs by default in online mode, saves 1-2 min) |
--iperf3 IP |
Run iperf3 upload+download bandwidth test against the specified server |
--comment TEXT |
Annotate logs with a comment; first word is appended to log filenames |
--output |
Custom log file path |
-v, --version |
Show version and exit |
- Status: Active/Inactive status with color coding
- MAC Address: Hardware (Ethernet) address
- IP Addresses: IPv4 and IPv6 addresses
- MTU: Maximum Transmission Unit size
- Media Type: Connection type and speed
- Packets In/Out: Total packets transmitted
- Bytes In/Out: Total data transferred (human-readable format)
- Errors: Network errors (color-coded: green < 0.1%, yellow < 1%, red > 1%)
- Collisions: Network collisions detected
-
Signal Strength (RSSI):
- Excellent: -30 to -50 dBm (green)
- Good: -50 to -60 dBm (cyan)
- Fair: -60 to -70 dBm (yellow)
- Weak: -70 to -80 dBm (orange)
- Very Weak: < -80 dBm (red)
-
SNR (Signal-to-Noise Ratio):
- Excellent: > 40 dB (green)
- Good: 30-40 dB (yellow)
- Poor: < 30 dB (red)
-
Channel: WiFi channel and frequency band (2.4GHz/5GHz/6GHz)
-
TX Rate: Current transmission rate in Mbps
-
PHY Mode: WiFi standard (802.11ac = WiFi 5, 802.11ax = WiFi 6)
-
Security: Authentication and encryption type
- Packet Loss: Percentage of lost packets (green = 0%, yellow < 1%, red > 1%)
- Min/Avg/Max: Minimum, average, and maximum round-trip time
- Jitter: Network stability indicator (green < 10ms, yellow < 20ms, red > 20ms)
- Download/Upload: Measured in Mbps
- Latency: Network latency under load
- Responsiveness: Round-trips per minute (RPM)
- Upload: Measured in Mbps (sender direction)
- Download: Measured in Mbps (reverse mode)
- Retransmits: TCP retransmit count per direction (indicator of packet loss/congestion)
-
Overall Score: 0-100 scale
- Excellent: 90-100 (green)
- Good: 75-89 (cyan)
- Fair: 60-74 (yellow)
- Poor: 40-59 (orange)
- Critical: 0-39 (red)
-
Warnings/Errors: Specific issues detected
-
Recommendations: Actionable suggestions to improve network performance
The tool provides comprehensive WiFi diagnostics:
- Signal Quality Assessment: RSSI measurement with quality grading
- Interference Detection: SNR calculation and noise floor measurement
- Channel Analysis: Current channel, width, and band detection
- Network Scanning: View all nearby WiFi networks with signal strength
- Performance Testing: WiFi-specific speed and latency tests
- Standards Detection: Identify WiFi generation (WiFi 4/5/6/6E)
- Stability Monitoring: Jitter and packet loss for real-time applications
This command requires macOS 12.1 or later. The tool will automatically skip speed tests on older versions.
Some commands may require elevated privileges. Try running with sudo:
sudo python main.py -i en0Ensure you're running on macOS and have network interfaces configured. Check with:
ifconfig -aVerify the interface is actually a WiFi interface:
/System/Library/PrivateFrameworks/Apple80211.framework/Versions/Current/Resources/airport -IThe networkQuality test can take 30-90 seconds. If it consistently hangs, use --mode offline to skip online tests.
Logs are saved in the ./logs/ directory with timestamped filenames:
network_analysis_YYYYMMDD_HHMMSS.log- Structured debug/info lognetwork_analysis_YYYYMMDD_HHMMSS_output.txt- Plain-text mirror of all console outputnetwork_analysis_YYYYMMDD_HHMMSS.json- Structured JSON data
When --comment is used, the first word of the comment is appended to all filenames:
network_analysis_YYYYMMDD_HHMMSS_HomeNetwork.lognetwork_analysis_YYYYMMDD_HHMMSS_HomeNetwork_output.txtnetwork_analysis_YYYYMMDD_HHMMSS_HomeNetwork.json
python main.py -i en0Check the WiFi signal strength, SNR, and channel congestion in the scan results.
python main.py -i en0 --mode onlineIncludes download/upload speed test and global latency measurements.
python main.py -i en0 --skip-dns-testSkips the DNS reliability test to save 1-2 minutes. By default, DNS testing is enabled and tests your configured DNS server by performing lookups on 100 highly reliable domains (major tech companies, cloud providers, news sites, etc.) to calculate success rate and average response times.
python main.py --allUseful for comparing WiFi vs Ethernet performance.
python main.py -i en0 --no-wifi-scanFaster analysis when you don't need to see nearby networks.
python main.py -i en0 --output ~/network_logs/test_$(date +%Y%m%d_%H%M%S).logRun periodically to track network performance trends.
python main.py -i en0 --iperf3 192.168.1.100Requires an iperf3 server running on the target: iperf3 -s
python main.py -i en0 --comment "after_firmware_update"Creates log files like network_analysis_..._after.log with the full comment in the header.
Common interface names on macOS:
en0- Usually the primary WiFi interface on MacBooksen1- Often Ethernet on MacBooks (via adapter)en4,en5, etc. - Additional Ethernet or Thunderbolt interfacesbridge0- Thunderbolt Bridgeawdl0- Apple Wireless Direct Link (AirDrop)
To list all interfaces:
networksetup -listallhardwareportsOr use the tool's interactive mode to see all available interfaces.
Offline Mode:
networksetup -listallhardwareports- Interface enumerationifconfig -a- Interface details and statisticsnetstat -i- Network statisticsnetstat -rn- Routing tablescutil --dns- DNS configurationairport -I- WiFi detailsairport -s- WiFi network scanarp -a- ARP cacheping- Latency testing
Online Mode:
networkQuality- Native macOS speed testiperf3- Bandwidth testing (optional, requires server)dig- DNS resolution testing- External APIs for public IP and geolocation
main.py # Entry point and orchestration
├── network_analyzer/
│ ├── models.py # Data structures
│ ├── utils.py # Utilities and health assessment
│ ├── logger.py # Logging system
│ ├── ui.py # Rich terminal UI
│ ├── collectors/
│ │ ├── offline.py # Local system data collection
│ │ └── online.py # Internet-based tests
│ └── parsers/
│ ├── ifconfig.py # Parse ifconfig output
│ ├── netstat.py # Parse netstat output
│ ├── airport.py # Parse WiFi data
│ └── system_profiler.py # Parse system data
This project is open source and available for personal and educational use.
Contributions are welcome! Please ensure:
- Code follows PEP 8 style guidelines
- Type hints are used for function signatures
- New features include appropriate error handling
- Documentation is updated for user-facing changes
- Added
--iperf3 IPparameter for upload/download bandwidth testing via iperf3 - Added
--comment TEXTparameter for log file annotation and filename labeling - Added
_output.txtplain-text log mirroring all console output
- Initial release
- Comprehensive interface analysis
- WiFi diagnostics and scanning
- Speed testing (macOS 12.1+)
- Health assessment with recommendations
- Dual mode operation (offline/online)
- Structured logging
WWWIEBUSCH | IT- & EVENT-SOLUTIONS
- Website: wwwiebusch.com
- Email: support@wwwiebusch.com
- Contact: wwwiebusch.com/kontakt
- Legal Notice: wwwiebusch.com/impressum
MIT License - Copyright (c) 2026 WWWIEBUSCH | IT- & EVENT-SOLUTIONS (Lauritz Wiebusch)
See LICENSE file for details.
Made by WWWIEBUSCH
WWWIEBUSCH | IT- & EVENT-SOLUTIONS