airtop

htop para as ondas de rádio — um painel RF 802.11 (Wi-Fi) ao vivo no seu terminal.

O airtop transforma o tráfego Wi-Fi ao seu redor em um painel de terminal ao vivo — um espectro de frequência dos pontos de acesso próximos, rastros de sinal por estação, um feed de atividade por tipo de frame, um histograma de RSSI e uma lista rolante de redes descobertas — desenhados com gráficos em braille e blocos sobre eBPF.

[!TIP] Sem monitor mode, sem raw sockets. O airtop anexa programas eBPF a mac80211/cfg80211 e lê os frames 802.11 conforme eles passam pela pilha Wi-Fi do kernel. Assim, ele roda na sua interface normal e conectada sem derrubar o link.

Início rápido

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

Para um screenshot compartilhável, anonimize SSIDs e MACs (sua rede e as dos vizinhos são renomeadas para network-01, station-02, …):

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

Roda até Ctrl-C. Redimensione o terminal e o layout se reorganiza; mínimo 80×24.

Para revelar redes vizinhas, o kernel precisa de resultados de scan. Seu SO faz scans periodicamente por conta própria, ou force um:

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

Uma introdução de 60 segundos ao 802.11

Wi-Fi é a família de padrões IEEE 802.11. O modelo mental:

Tudo é um frame. Seu laptop, celular e roteador trocam pacotes de rádio curtos chamados frames. Todo frame carrega endereços MAC, e um deles (o BSSID) identifica o ponto de acesso ao qual pertence.

Três classes de frame:

Pontos de acesso fazem beacon. Um AP se anuncia cerca de 10 vezes por segundo com um frame beacon que carrega o nome da rede (SSID) e o BSSID. É assim que a lista de Wi-Fi do seu celular é preenchida, e como o airtop descobre APs.

Canais e frequência. O Wi-Fi vive em bandas (2,4 GHz, 5 GHz, 6 GHz), cada uma dividida em canais, e cada canal é uma frequência central em MHz (canal 6 ≈ 2437 MHz, canal 161 ≈ 5805 MHz). Um rádio escuta um canal por vez, e é por isso que você vê principalmente tráfego no seu canal.

Intensidade do sinal (RSSI) é medida em dBm. Os valores são sempre negativos, e quanto mais perto de zero, mais forte:

Casos de uso comuns

Principalmente usuários domésticos depurando Wi-Fi instável e administradores de rede escolhendo canais antes de um evento.

• Sua chamada de vídeo engasga. Seu canal está congestionado?
• Um convidado não consegue conectar. O AP está sequer fazendo beacon?
• Escolhendo um canal para uma demo. Como está o ambiente de RF?
• Picos de frames Deauth. Ataque ou roteador com comportamento estranho?

O que você está vendo

Cada painel corresponde aos conceitos acima:

Cabeçalho — uptime, total de frames vistos, estações ativas, APs descobertos, contagem de beacons, contagem de deauth (em vermelho se qualquer uma for diferente de zero) e seu canal atual. O contador de deauth é o que você deve ficar de olho; redes saudáveis têm zero.

Espectro de frequência — cada AP descoberto desenhado como uma "elevação" de sinal posicionada na sua frequência central real em um eixo de MHz. Altura e cor mostram o RSSI; o rótulo é o SSID + dBm. Elevações sobrepostas revelam congestão no mesmo canal — a visão clássica de analisador de Wi-Fi e a resposta para "por que meu Wi-Fi está lento."

RSSI × tempo — um gráfico de linhas em braille por estação ativa plotando o sinal ao longo dos últimos segundos. Veja um link enfraquecer conforme um dispositivo se afasta do AP, ou saltar quando alguém move o laptop.

Feed de frames — um mapa de calor dos tipos de frame ao longo do tempo; cor da célula = quantos daquele tipo chegaram por fatia. Uma enxurrada de deauth acende essa linha na hora, que é o padrão de alerta que você realmente quer.

Histograma de sinal — distribuição dos frames recebidos por RSSI. O "formato" do seu ambiente de RF: um pico estreito em torno de −50 dBm significa que você está perto de um AP forte; um borrão de −60 a −80 significa um ambiente cheio.

Pontos de acesso — SSIDs descobertos com canal, medidor de sinal e dBm, ordenados do mais forte para o mais fraco.

Como funciona

Um único objeto BPF (airtop.bpf.c) anexa dois programas fentry e transmite eventos para o userspace via ring buffers:

O painel roda no runtime V8 do yeet, assinando esses ring buffers e renderizando a interface de 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 com BTF: CONFIG_DEBUG_INFO_BTF=y e CONFIG_DEBUG_INFO_BTF_MODULES=y. Padrão no Arch, Fedora, Ubuntu e Debian 12+ atuais. CO-RE significa que não é preciso recompilar para cada kernel.

• Uma interface Wi-Fi usando a pilha padrão cfg80211/mac80211 (qualquer placa Wi-Fi normal no Linux).
• O daemon yeet, que cuida do carregamento privilegiado do BPF. curl -fsSL https://yeet.cx | sh o instala.

Ressalvas honestas

[!NOTE] O que o airtop não faz:

• Uma interface conectada só ouve o próprio canal, além do que scans breves tocarem; então o espectro e a lista de APs se preenchem conforme os scans rodam, e o tráfego ao vivo por frame é majoritariamente do seu canal. Uma varredura de banda completa exigiria monitor mode + channel hopping.
• Ele conta frames, não bytes. "Atividade" é contagem de frames, não tempo de ar (airtime).
• Taxa de TX e retransmissões não são capturadas. Isso é um hook tx_status separado.
• Os alvos fentry são estáveis na prática, mas não são uma ABI do kernel; os dados exatos dependem do driver Wi-Fi.

Perguntas da comunidade

Isso precisa de monitor mode? Não. Essa é a ideia. O airtop engancha na pilha Wi-Fi do kernel por dentro, então funciona na sua interface normal e conectada.

Isso vai derrubar minha conexão? Não. Não há troca de modo; sua interface continua associada ao que já estava associada. O airtop está apenas observando o que o kernel já está fazendo.

Por que só vejo uma ou duas redes? Porque seu rádio está ouvindo um canal (o próprio) na maior parte do tempo. Redes vizinhas aparecem quando seu SO faz scans periódicos, ou quando você força um com nmcli dev wifi rescan / iw dev <iface> scan. Uma varredura de banda completa exige monitor mode + channel hopping, o que é uma ferramenta diferente.

Isso é legal? Observar passivamente frames 802.11 no ar ao seu redor é legal na maioria das jurisdições; seu rádio já os recebe, e o airtop apenas mostra o que está lá. Interferência ativa (o painel de deauth detecta ataques, não os executa) é outra história. Se você estiver em uma rede corporativa, consulte sua AUP.

Como isso é diferente do Kismet, airodump-ng ou Wireshark? Essas ferramentas vão além com monitor mode: captura completa por frame, exportação PCAP, descriptografia. O airtop roda na sua interface normal e dá um painel de relance. Para pentest, use o airodump-ng. Para descobrir por que sua chamada caiu, use este.

Compilando a partir do código-fonte

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

Precisa de clang (alvo BPF) e bpftool; o libbpf / libbpf-dev da sua distro para os cabeçalhos. O include/vmlinux.h e bin/ gerados estão no .gitignore.

Gravando a demo

O GIF é produzido com VHS a partir de assets/airtop.tape:

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

Ele inicia o airtop fora da câmera para que o GIF abra já no painel ao vivo. Dispare scans de Wi-Fi em outro shell enquanto grava para preencher o espectro e a lista de APs.

Licença

O programa BPF é GPL (SEC("license") = "GPL"), conforme exigido pelos helpers do kernel que ele usa.

Construído por yeet. O yeet é um runtime Linux para escrever programas eBPF e painéis de sistema ao vivo em JavaScript.