airtop

airtop is an innovative terminal-based dashboard that provides real-time insights into Wi-Fi traffic in the surrounding environment, fundamentally transforming how users can monitor wireless networks.

Key Features

• Live 802.11 RF Dashboard: Displays the frequency spectrum of nearby access points (APs), per-station signal traces, a frame-type activity feed, an RSSI histogram, and a dynamic list of discovered networks — all represented using braille and block graphics over eBPF.
• Effortless Operation: airtop functions without requiring monitor mode or raw sockets. Instead, it attaches eBPF programs to mac80211/cfg80211, enabling it to read 802.11 frames seamlessly through the kernel's Wi-Fi stack. This ensures the tool runs on a connected interface without interrupting the network connection.
• User-Friendly Interface: The dashboard is accessible and responsive, allowing users to interact with live data. It includes features such as resizing the terminal, automatic layout adjustments, and the ability to display neighboring networks by initiating periodic scans.

Usage Examples

To get started, simply run:

curl -fsSL https://yeet.cx | sh
yeet run https://github.com/yeet-src/airtop

For a screenshot that anonymizes SSIDs and MAC addresses, use:

yeet run https://github.com/yeet-src/airtop -- --anonymize

This tool runs continuously until manually stopped (with Ctrl-C), providing an evolving view of the Wi-Fi landscape.

Understanding Wi-Fi Traffic

• Frame Structure: All devices in a Wi-Fi network communicate using radio packets, known as frames, which carry essential information such as MAC addresses and the BSSID, identifying the AP.
• Frame Classes: airtop categorizes frames into three main classes: Management (e.g., Beacon, Probe), Control (e.g., ACK), and Data (user traffic). Understanding these classes is crucial for analyzing network behavior.

Common Use Cases

• Diagnose fluctuations in video calls due to channel congestion.
• Verify whether an access point is actively beaconing for guest connections.
• Assess the RF environment to select the most suitable channel before an event.
• Identify potential attacks or issues based on deauthentication frame spikes.

Architecture

Based on BPF technology, airtop comprises a single BPF object (airtop.bpf.c) linking various components, capturing events as they happen. It processes this data in a live rendering loop, providing insights directly in the terminal.

Requirements

To run airtop, ensure your system meets the following requirements:

• Linux with BTF configurations: CONFIG_DEBUG_INFO_BTF=y and CONFIG_DEBUG_INFO_BTF_MODULES=y.
• A compatible Wi-Fi interface utilizing the cfg80211/mac80211 stack.
• Installation of the yeet daemon for handling BPF loading privileges.

How airtop Stands Out

Unlike tools like Kismet or airodump-ng, which typically require monitor mode for comprehensive data capture, airtop is designed for functionality on a standard connected interface, delivering real-time visualizations for immediate actionable insights without disrupting the network connection.

For more information and to join the community, visit yeet, the underlying runtime supporting this tool.