airtop

htop para las ondas — un panel RF 802.11 (Wi-Fi) en vivo en tu terminal.

airtop convierte el tráfico Wi-Fi a tu alrededor en un panel de terminal en vivo — un espectro de frecuencia de los puntos de acceso cercanos, trazas de señal por estación, un feed de actividad por tipo de trama, un histograma de RSSI y una lista dinámica de redes descubiertas — dibujado con gráficos braille y de bloques sobre eBPF.

[!TIP] Sin modo monitor, sin raw sockets. airtop adjunta programas eBPF a mac80211/cfg80211 y lee las tramas 802.11 mientras fluyen a través de la pila Wi-Fi del kernel, por lo que se ejecuta en tu interfaz normal y conectada sin interrumpir tu enlace.

Inicio rápido

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

Para una captura de pantalla que se pueda compartir, anonimiza los SSID y las MAC (tu red y las de tus vecinos se renombran como network-01, station-02, …):

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

Se ejecuta hasta Ctrl-C. Redimensiona la terminal y el diseño se reajusta; mínimo 80×24.

Para que aparezcan las redes vecinas, el kernel necesita resultados de escaneo. Tu sistema operativo escanea periódicamente por su cuenta, o fuerza uno:

nmcli dev wifi rescan        # or: iw dev <iface> scan

Una introducción de 60 segundos a 802.11

Wi-Fi es la familia de estándares IEEE 802.11. El modelo mental:

Todo es una trama. Tu portátil, teléfono y router intercambian paquetes de radio cortos llamados tramas. Cada trama lleva direcciones MAC, y una de ellas (el BSSID) identifica el punto de acceso al que pertenece.

Tres clases de trama:

Los puntos de acceso emiten balizas. Un AP se anuncia ~10 veces por segundo con una trama de baliza que lleva su nombre de red (SSID) y BSSID. Así se llena la lista Wi-Fi de tu teléfono, y así descubre airtop los AP.

Canales y frecuencia. Wi-Fi vive en bandas (2,4 GHz, 5 GHz, 6 GHz), cada una dividida en canales, y cada canal es una frecuencia central en MHz (canal 6 ≈ 2437 MHz, canal 161 ≈ 5805 MHz). Una radio escucha un canal a la vez, por eso ves principalmente tráfico en tu canal.

La intensidad de señal (RSSI) se mide en dBm. Los valores siempre son negativos, y cuanto más cerca de cero, más fuerte:

Casos de uso comunes

Principalmente usuarios domésticos depurando un Wi-Fi inestable, y administradores de red eligiendo canales antes de un evento.

• ¿Tu videollamada se entrecorta? ¿Está congestionado tu canal?
• Un invitado no puede conectarse. ¿Está el AP siquiera emitiendo balizas?
• Elegir un canal para una demo. ¿Cómo es el entorno RF?
• Picos de tramas Deauth. ¿Ataque o router con mal comportamiento?

Lo que estás viendo

Cada panel se corresponde con los conceptos anteriores:

Cabecera — tiempo de actividad, total de tramas vistas, estaciones activas, AP descubiertos, cantidad de balizas, cantidad de deauth (en rojo si alguno es distinto de cero) y tu canal actual. El contador de deauth es el que hay que vigilar; las redes sanas tienen cero.

Espectro de frecuencia — cada AP descubierto se dibuja como una "joroba" de señal posicionada en su frecuencia central real sobre un eje de MHz. La altura y el color muestran la RSSI; la etiqueta es el SSID + dBm. Las jorobas superpuestas revelan congestión en el mismo canal — la clásica vista de analizador de Wi-Fi, y la respuesta a "por qué mi Wi-Fi va lento".

RSSI × tiempo — un gráfico de líneas en braille por cada estación activa que traza su señal durante los últimos segundos. Observa cómo un enlace se desvanece cuando un dispositivo se aleja del AP, o cómo salta cuando alguien mueve su portátil.

Feed de tramas — un mapa de calor de tipos de trama a lo largo del tiempo; color de la celda = cuántas de ese tipo llegaron por franja. Una ráfaga de deauth ilumina esa fila al instante, que es el patrón de alerta que realmente quieres.

Histograma de señal — distribución de las tramas recibidas por RSSI. La "forma" de tu entorno RF: un pico estrecho alrededor de −50 dBm significa que estás cerca de un AP fuerte; una mancha entre −60 y −80 significa un entorno saturado.

Puntos de acceso — SSID descubiertos con canal, indicador de señal y dBm, ordenados de más fuerte a más débil.

Cómo funciona

Un único objeto BPF (airtop.bpf.c) adjunta dos programas fentry y transmite eventos al espacio de usuario a través de ring buffers:

El panel se ejecuta en el runtime V8 de yeet, suscribiéndose a esos ring buffers y renderizando la UI de la terminal:

main.js       entry: tty size, render loop, BPF bind/subscribe
state.js      live data + frame/scan ingest
render.js     ANSI, color ramps, braille canvas/charts (pure)
dashboard.js  panels + layout (renderDashboard)

Requisitos

[!IMPORTANT] Linux con BTF: CONFIG_DEBUG_INFO_BTF=y y CONFIG_DEBUG_INFO_BTF_MODULES=y. Viene activado por defecto en Arch, Fedora, Ubuntu y Debian 12+ actuales. CO-RE significa que no es necesario recompilar para cada kernel.

• Una interfaz Wi-Fi que use la pila estándar cfg80211/mac80211 (cualquier tarjeta Wi-Fi normal en Linux).
• El daemon de yeet, que se encarga de la carga privilegiada de BPF. curl -fsSL https://yeet.cx | sh lo instala.

Advertencias honestas

[!NOTE] Lo que airtop no hace:

• Una interfaz conectada solo escucha su propio canal más lo que toquen los escaneos breves, así que el espectro y la lista de AP se completan a medida que se ejecutan los escaneos, y el tráfico vivo por trama es principalmente de tu canal. Un estudio de banda completa requeriría modo monitor + salto de canal.
• Cuenta tramas, no bytes. "Actividad" es el número de tramas, no tiempo de aire.
• La tasa TX y los reintentos no se capturan. Ese es un hook tx_status aparte.
• Los objetivos fentry son estables en la práctica pero no son una ABI del kernel; los datos exactos dependen de tu driver Wi-Fi.

Preguntas de la comunidad

¿Esto necesita modo monitor? No. Ese es el punto. airtop engancha la pila Wi-Fi del kernel desde dentro, así que funciona en tu interfaz normal conectada.

¿Caerá mi conexión? No. No hay cambio de modo; tu interfaz permanece asociada a lo que ya está asociada. airtop está observando lo que el kernel ya está haciendo.

¿Por qué solo veo una o dos redes? Porque tu radio está escuchando un solo canal (el suyo) la mayor parte del tiempo. Las redes vecinas aparecen cuando tu sistema operativo hace escaneos periódicos, o cuando fuerzas uno con nmcli dev wifi rescan / iw dev <iface> scan. Un estudio de banda completa requiere modo monitor + salto de canal, lo cual es otra herramienta.

¿Es legal? Observar pasivamente tramas 802.11 en el aire a tu alrededor es legal en la mayoría de las jurisdicciones; tu radio ya las está recibiendo, y airtop solo te muestra lo que hay. La interferencia activa (el panel de deauth detecta ataques, no los ejecuta) es otra historia. Si estás en una red corporativa, revisa tu AUP.

¿En qué se diferencia esto de Kismet, airodump-ng o Wireshark? Esas herramientas hacen más con el modo monitor: captura completa trama por trama, exportación PCAP, descifrado. airtop se ejecuta en tu interfaz normal y te da un panel de un vistazo. Para pentesting, usa airodump-ng. Para averiguar por qué se cayó tu llamada, usa esto.

Compilar desde el código fuente

make          # generates include/vmlinux.h, builds bin/airtop.bpf.o
make vmlinux  # force-refresh the kernel type header
make clean

Necesita clang (target BPF) y bpftool; el libbpf / libbpf-dev de tu distribución para los encabezados. El include/vmlinux.h y bin/ generados están en gitignore.

Grabación de la demo

El GIF se produce con VHS a partir de assets/airtop.tape:

vhs assets/airtop.tape    # -> assets/airtop.gif

Lanza airtop fuera de cámara para que el GIF se abra en el panel en vivo. Inicia escaneos Wi-Fi en otra shell mientras grabas para llenar el espectro y la lista de AP.

Licencia

El programa BPF es GPL (SEC("license") = "GPL"), como exigen los helpers del kernel que utiliza.

Construido por yeet. yeet es un runtime de Linux para escribir programas eBPF y paneles de sistema en vivo en JavaScript.