airtop

전파를 위한 htop — 터미널에서 보는 실시간 802.11(Wi-Fi) RF 대시보드.

airtop은 주변의 Wi-Fi 트래픽을 실시간 터미널 대시보드로 바꿉니다 — 주변 액세스 포인트의 주파수 스펙트럼, 스테이션별 신호 추적, 프레임 유형 활동 피드, RSSI 히스토그램, 그리고 발견된 네트워크의 최신 목록 — eBPF 기반의 점자 및 블록 그래픽으로 그려집니다.

[!TIP] 모니터 모드 불필요, raw 소켓 불필요. airtop은 eBPF 프로그램을 mac80211/cfg80211에 연결하고 커널의 Wi-Fi 스택을 통과하는 802.11 프레임을 읽으므로, 링크를 끊지 않고 일반적인 연결 인터페이스에서 실행됩니다.

빠른 시작

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

공유용 스크린샷을 위해 SSID와 MAC을 익명화합니다(내 네트워크와 이웃 네트워크는 network-01, station-02, …로 다시 라벨링됩니다):

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

Ctrl-C를 누를 때까지 실행됩니다. 터미널 크기를 조정하면 레이아웃이 다시 흐르며, 최소 80×24입니다.

주변 네트워크를 표시하려면 커널에 스캔 결과가 필요합니다. OS가 주기적으로 자체 스캔을 수행하거나, 직접 강제로 실행할 수 있습니다:

nmcli dev wifi rescan        # 또는: iw dev <iface> scan

60초 802.11 입문

Wi-Fi는 IEEE 802.11 표준 패밀리입니다. 핵심 모델은 다음과 같습니다:

모든 것은 프레임입니다. 노트북, 휴대폰, 라우터는 프레임이라 부르는 짧은 무선 패킷을 교환합니다. 모든 프레임에는 MAC 주소가 포함되며, 그중 하나(BSSID)는 해당 프레임이 속한 액세스 포인트를 식별합니다.

세 가지 프레임 클래스:

액세스 포인트가 비콘을 보냅니다. AP는 네트워크 이름(SSID)과 BSSID를 담은 비콘 프레임으로 초당 약 10회 자신을 알립니다. 이것이 휴대폰의 Wi-Fi 목록이 채워지는 방식이자 airtop이 AP를 발견하는 방식입니다.

채널과 주파수. Wi-Fi는 대역(2.4 GHz, 5 GHz, 6 GHz)에 존재하며, 각 대역은 채널로 나뉘고, 각 채널은 MHz 단위의 중심 주파수를 가집니다(채널 6 ≈ 2437 MHz, 채널 161 ≈ 5805 MHz). 라디오는 한 번에 하나의 채널만 수신하므로, 대부분 자기 채널의 트래픽만 보게 됩니다.

신호 강도(RSSI) 는 dBm 단위로 측정됩니다. 값은 항상 음수이며, 0에 가까울수록 강합니다:

일반적인 사용 사례

주로 불안정한 Wi-Fi를 디버깅하는 일반 사용자와 이벤트 전에 채널을 선택하는 네트워크 관리자를 위한 도구입니다.

• 화상 통화가 끊깁니다. 내 채널이 혼잡한가요?
• 손님이 연결할 수 없습니다. AP가 비콘을 보내고 있긴 한가요?
• 데모용 채널을 고르는 중. RF 환경이 어떤가요?
• Deauth 프레임이 급증합니다. 공격일까요, 오작동하는 라우터일까요?

지금 보는 화면

각 패널은 위 개념과 연결됩니다:

헤더 — 업타임, 총 수신 프레임 수, 활성 스테이션, 발견된 AP, 비콘 수, deauth 수(0이 아니면 빨간색), 현재 채널. deauth 카운터가 가장 주목해야 할 값이며, 정상적인 네트워크는 0입니다.

주파수 스펙트럼 — 발견된 모든 AP가 MHz 축의 실제 중심 주파수에 배치된 신호 "언덕"으로 그려집니다. 높이와 색상은 RSSI를 나타내고, 라벨은 SSID + dBm입니다. 겹치는 언덕은 동일 채널 혼잡을 드러냅니다 — 고전적인 Wi-Fi 분석기 뷰이자 "Wi-Fi가 왜 느리지?"에 대한 답입니다.

RSSI × 시간 — 활성 스테이션별로 지난 몇 초간 신호를 그리는 점자 선 그래프입니다. 기기가 AP에서 멀어지면 링크가 약해지는 것을, 누군가 노트북을 옮기면 튀는 것을 볼 수 있습니다.

프레임 피드 — 시간에 따른 프레임 유형 히트맵; 셀 색상 = 구간별로 도착한 해당 유형의 수. Deauth 홍수가 발생하면 해당 행이 즉시 밝아지며, 이것이 실제로 원하는 경보 패턴입니다.

신호 히스토그램 — RSSI에 따른 수신 프레임 분포. RF 환경의 "형태"를 보여줍니다: −50 dBm 부근의 뾰족한 피크는 강한 AP 하나 옆에 있다는 뜻이고, −60에서 −80에 걸쳐 넓게 퍼진 분포는 혼잡한 환경을 의미합니다.

액세스 포인트 — 발견된 SSID를 채널, 신호 게이지, dBm과 함께 신호가 강한 순서로 정렬해 표시합니다.

동작 방식

하나의 BPF 오브젝트(airtop.bpf.c)가 두 개의 fentry 프로그램을 연결하고 링 버퍼를 통해 이벤트를 사용자 공간으로 스트리밍합니다:

대시보드는 yeet의 V8 런타임에서 실행되며 해당 링 버퍼를 구독하고 터미널 UI를 렌더링합니다:

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)

요구 사항

[!IMPORTANT] BTF가 포함된 Linux: CONFIG_DEBUG_INFO_BTF=y 및 CONFIG_DEBUG_INFO_BTF_MODULES=y. 현재 Arch, Fedora, Ubuntu, Debian 12+에서 기본값입니다. CO-RE 덕분에 커널별 재컴파일이 필요 없습니다.

• 표준 cfg80211/mac80211 스택을 사용하는 Wi-Fi 인터페이스(Linux의 일반적인 Wi-Fi 카드).
• 권한 있는 BPF 로드를 처리하는 yeet 데몬. curl -fsSL https://yeet.cx | sh로 설치됩니다.

솔직한 한계

[!NOTE] airtop이 하지 못하는 것:

• 연결된 인터페이스는 자기 채널과 짧은 스캔이 닿는 범위만 수신하므로, 스펙트럼과 AP 목록은 스캔이 실행될 때 채워지고, 실시간 프레임별 트래픽은 대부분 내 채널입니다. 전체 대역 조사에는 모니터 모드 + 채널 호핑이 필요합니다.
• 프레임 수를 세지 바이트를 세지 않습니다. "활동"은 프레임 수이며 공중 점유 시간이 아닙니다.
• TX 속도와 재전송은 캡처되지 않습니다. 이는 별도의 tx_status 훅입니다.
• fentry 대상은 실무상 안정적이지만 커널 ABI는 아닙니다. 정확한 데이터는 Wi-Fi 드라이버에 따라 다릅니다.

커뮤니티 질문

모니터 모드가 필요한가요? 아니요. 그게 핵심입니다. airtop은 커널의 Wi-Fi 스택을 내부에서 훅하므로 일반적인 연결 인터페이스에서 동작합니다.

연결이 끊기나요? 아니요. 모드 전환이 없으므로 인터페이스는 기존 연결 상태를 유지합니다. airtop은 커널이 이미 수행 중인 작업을 관찰할 뿐입니다.

네트워크가 한두 개만 보이는 이유는? 라디오가 대부분 한 채널(자기 채널)만 수신하기 때문입니다. 주변 네트워크는 OS가 주기적 스캔을 수행하거나 nmcli dev wifi rescan / iw dev <iface> scan으로 직접 강제할 때 나타납니다. 전체 대역 조사에는 모니터 모드 + 채널 호핑이 필요하며, 이는 다른 도구의 영역입니다.

법적으로 문제없나요? 주변 공중의 802.11 프레임을 수동적으로 관찰하는 것은 대부분의 관할권에서 합법입니다. 라디오는 이미 해당 프레임을 수신하고 있으며, airtop은 그 내용을 보여줄 뿐입니다. 능동적 간섭(deauth 패널은 공격을 탐지할 뿐 수행하지 않습니다)은 별개입니다. 회사 네트워크를 사용 중이라면 AUP를 확인하세요.

Kismet, airodump-ng, Wireshark와 어떻게 다른가요? 그 도구들은 모니터 모드에서 더 많은 기능을 제공합니다: 전체 프레임별 캡처, PCAP 내보내기, 복호화. airtop은 일반 인터페이스에서 실행되며 한눈에 보는 대시보드를 제공합니다. 펜 테스트에는 airodump-ng을 사용하세요. 통화가 끊긴 이유를 찾으려면 이 도구를 사용하세요.

소스에서 빌드하기

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

필요한 것: clang(BPF 타깃)과 bpftool; 헤더용 배포판의 libbpf / libbpf-dev. 생성된 include/vmlinux.h와 bin/은 gitignore에 포함됩니다.

데모 녹화하기

GIF는 VHS를 사용해 assets/airtop.tape에서 생성됩니다:

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

카메라 밖에서 airtop을 실행해 GIF가 실시간 대시보드로 시작되도록 합니다. 녹화하는 동안 다른 셸에서 Wi-Fi 스캔을 실행하면 스펙트럼과 AP 목록이 채워집니다.

라이선스

BPF 프로그램은 사용하는 커널 헬퍼가 요구하는 대로 GPL(SEC("license") = "GPL")입니다.

yeet이(가) 만들었습니다. yeet은 JavaScript로 eBPF 프로그램과 실시간 시스템 대시보드를 작성하기 위한 Linux 런타임입니다.