airtop

htop per le onde radio — un dashboard RF 802.11 (Wi-Fi) live nel tuo terminale.

airtop trasforma il traffico Wi-Fi intorno a te in un dashboard live per terminale — uno spettro di frequenze dei punti di accesso vicini, tracce del segnale per stazione, un feed di attività per tipo di frame, un istogramma RSSI e un elenco scorrevole delle reti scoperte — disegnato con grafica braille e blocchi su eBPF.

[!TIP] Niente modalità monitor, niente socket raw. airtop collega programmi eBPF a mac80211/cfg80211 e legge i frame 802.11 mentre fluiscono attraverso lo stack Wi-Fi del kernel, quindi viene eseguito sulla tua interfaccia normale e connessa senza interrompere il collegamento.

Quick start

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

Per uno screenshot condivisibile, anonimizza SSID e MAC (la tua rete e quelle dei vicini vengono rinominati network-01, station-02, …):

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

Viene eseguito fino a Ctrl-C. Ridimensiona il terminale e il layout si riadatta; minimo 80×24.

Per visualizzare le reti vicine, il kernel ha bisogno dei risultati della scansione. Il tuo sistema operativo esegue scansioni periodicamente da solo, oppure forzane una:

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

Un primer 802.11 in 60 secondi

Il Wi-Fi è la famiglia di standard IEEE 802.11. Il modello mentale:

Tutto è un frame. Il tuo laptop, telefono e router scambiano brevi pacchetti radio chiamati frame. Ogni frame trasporta indirizzi MAC, e uno di essi (il BSSID) identifica il punto di accesso a cui appartiene.

Tre classi di frame:

I punti di accesso beaconano. Un AP si annuncia circa 10 volte al secondo con un frame beacon che trasporta il nome della rete (SSID) e BSSID. È così che la lista Wi-Fi del tuo telefono viene popolata, e come airtop scopre gli AP.

Canali e frequenza. Il Wi-Fi vive in bande (2.4 GHz, 5 GHz, 6 GHz), ciascuna suddivisa in canali, e ogni canale è una frequenza centrale in MHz (canale 6 ≈ 2437 MHz, canale 161 ≈ 5805 MHz). Una radio ascolta un canale alla volta, motivo per cui vedi principalmente traffico sul tuo canale.

Intensità del segnale (RSSI) è misurata in dBm. I valori sono sempre negativi, e più vicini a zero sono più forti:

Casi d'uso comuni

Principalmente utenti domestici che risolvono problemi di Wi-Fi instabile e amministratori di rete che scelgono i canali prima di un evento.

• La tua videochiamata balbetta. Il tuo canale è congestionato?
• Un ospite non riesce a connettersi. L'AP sta inviando beacon?
• Scegliere un canale per una demo. Com'è l'ambiente RF?
• I frame Deauth aumentano. Attacco o router malfunzionante?

Cosa stai guardando

Ogni pannello mappa i concetti sopra:

Intestazione — uptime, frame totali visti, stazioni live, AP scoperti, conteggio beacon, conteggio deauth (rosso se diverso da zero) e il tuo canale corrente. Il contatore deauth è quello da tenere d'occhio; le reti sane hanno zero.

Spettro di frequenze — ogni AP scoperto disegnato come una "gobba" di segnale posizionata alla sua frequenza centrale reale su un asse in MHz. Altezza e colore mostrano l'RSSI; l'etichetta è SSID + dBm. Gobbe sovrapposte rivelano congestione co-canale — la classica vista dell'analizzatore Wi-Fi, e la risposta a "perché il mio Wi-Fi è lento?"

RSSI × tempo — un grafico a linee braille per ogni stazione live che traccia il suo segnale negli ultimi secondi. Osserva un collegamento affievolirsi mentre un dispositivo si allontana dall'AP, o saltare quando qualcuno sposta il laptop.

Feed dei frame — una mappa di calore dei tipi di frame nel tempo; il colore della cella = quanti di quel tipo sono arrivati per fetta. Un'inondazione di deauth illumina quella riga istantaneamente, che è il modello di avviso che vuoi davvero.

Istogramma del segnale — distribuzione dei frame ricevuti per RSSI. La "forma" del tuo ambiente RF: un picco stretto intorno a −50 dBm significa che sei vicino a un AP forte, una macchia da −60 a −80 indica un ambiente affollato.

Punti di accesso — SSID scoperti con canale, indicatore del segnale e dBm, ordinati dal più forte.

Come funziona

Un singolo oggetto BPF (airtop.bpf.c) collega due programmi fentry e invia eventi in spazio utente tramite buffer ad anello:

Il dashboard viene eseguito nel runtime V8 di yeet, sottoscrivendo quei ring buffer e renderizzando l'UI del terminale:

main.js       entry: dimensione tty, ciclo di rendering, bind/sottoscrizione BPF
state.js      dati live + ingestione frame/scansione
render.js     ANSI, rampe di colore, canvas braille/grafici (puro)
dashboard.js  pannelli + layout (renderDashboard)

Requisiti

[!IMPORTANT] Linux con BTF: CONFIG_DEBUG_INFO_BTF=y e CONFIG_DEBUG_INFO_BTF_MODULES=y. Predefinito sulle attuali Arch, Fedora, Ubuntu e Debian 12+. CO-RE significa nessuna ricompilazione per kernel.

• Un'interfaccia Wi-Fi che utilizza lo stack standard cfg80211/mac80211 (qualsiasi normale scheda Wi-Fi su Linux).
• Il demone yeet, che gestisce il caricamento privilegiato di BPF. curl -fsSL https://yeet.cx | sh lo installa.

Avvertenze oneste

[!NOTE] Cosa non fa airtop:

• Un'interfaccia connessa sente solo il proprio canale più qualsiasi scansione breve tocca, quindi lo spettro e l'elenco AP si riempiono man mano che le scansioni vengono eseguite, e il traffico live per frame è principalmente il tuo canale. Un'indagine a banda piena richiederebbe la modalità monitor + hopping dei canali.
• Conta i frame, non i byte. "Attività" è il conteggio dei frame, non il tempo di trasmissione.
• Il tasso di TX e i ritrasmissioni non vengono catturati. Questo è un hook tx_status separato.
• I target fentry sono stabili in pratica ma non sono un ABI del kernel; i dati esatti dipendono dal driver Wi-Fi.

Domande della community

Serve la modalità monitor? No. Questo è il punto. airtop si aggancia allo stack Wi-Fi del kernel dall'interno, quindi funziona sulla tua normale interfaccia connessa.

Farà cadere la mia connessione? No. Non c'è cambio di modalità; la tua interfaccia rimane associata a ciò a cui è associata. airtop osserva ciò che il kernel sta già facendo.

Perché vedo solo una o due reti? Perché la tua radio ascolta un canale (il suo) la maggior parte del tempo. Le reti vicine appaiono quando il tuo sistema operativo esegue scansioni periodiche, o quando ne forzi una con nmcli dev wifi rescan / iw dev <iface> scan. Un'indagine a banda piena richiede modalità monitor + hopping dei canali, che è un altro strumento.

È legale? Osservare passivamente i frame 802.11 nell'aria intorno a te è legale nella maggior parte delle giurisdizioni; la tua radio li sta già ricevendo, e airtop ti mostra solo ciò che c'è. L'interferenza attiva (il pannello deauth rileva attacchi, non li esegue) è un'altra storia. Se sei su una rete aziendale, controlla la tua AUP.

In cosa è diverso da Kismet, airodump-ng o Wireshark? Questi strumenti fanno di più con la modalità monitor: cattura completa per frame, esportazione PCAP, decrittazione. airtop viene eseguito sulla tua interfaccia normale e ti fornisce un dashboard a colpo d'occhio. Per i penetration test, usa airodump-ng. Per scoprire perché la tua chiamata è caduta, usa questo.

Build dal sorgente

make          # genera include/vmlinux.h, build bin/airtop.bpf.o
make vmlinux  # forza l'aggiornamento dell'header del tipo kernel
make clean

Necessita di clang (target BPF) e bpftool; i pacchetti libbpf / libbpf-dev della tua distribuzione per gli header. I file generati include/vmlinux.h e bin/ sono in gitignore.

Registrazione della demo

Il GIF è prodotto con VHS da assets/airtop.tape:

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

Avvia airtop fuori campo in modo che il GIF si apra sul dashboard live. Avvia scansioni Wi-Fi in un'altra shell durante la registrazione per riempire lo spettro e l'elenco AP.

Licenza

Il programma BPF è GPL (SEC("license") = "GPL"), come richiesto dagli helper del kernel che utilizza.

Realizzato da yeet. yeet è un runtime Linux per scrivere programmi eBPF e dashboard di sistema live in JavaScript.