AirShark

Terminal Wi-Fi monitor for macOS. Puts the interface into monitor mode, hops channels, with support for WPA/WPA2 decryption.

[!NOTE] Currently in early development. Only been tested on Apple Silicon (M1) with Wi-Fi 5.

• Capture: dumpcap the interface is in monitor mode and captures raw frames, which are piped into tshark (-T ek) to generate JSON, that is then fed into a background thread for the TUI to read off of.
• Channel hopping: Implemented using CoreWLAN via PyObjC. The interface is disassociated once at startup to allow raw packet capture.
• UI: Textual.

Requirements

• macOS
• Python 3.10+
• Wireshark / tshark
  During install, make sure to enable the ChmodBPF capture permissions. This allows AirShark to capture packets entirely without sudo.

Installation

pip install airshark

Or clone from source and install in editable mode:

git clone https://github.com/Chiroyce1/airshark
cd airshark
pip install -e .

Configuration

Credentials for decryption can come from the CLI or a .env file:

SSID="YourNetworkName"
PASSWORD="YourPassphrase"

CLI flags (-s/-k) can override .env.

Usage

# Monitor channel 6
airshark -i en0 -c 6

# Hop 2.4 GHz, 0.5 s per channel
airshark -i en0 --band 2.4 --dwell 0.5

# 5 GHz hop + live decryption
airshark -i en0 --band 5 -s HomeNet -k s3cr3t

Keybindings while running:

Troubleshooting

If SSIDs show as <Hidden> on macOS: Apple's privacy protections (TCC) classify Wi-Fi SSIDs as location data. If you install via pip, macOS may block the pip wrapper from reading SSIDs by redacting them.

1. Go to System Settings > Privacy & Security > Location Services and ensure your terminal (e.g., Ghostty, iTerm2, Terminal.app) is toggled ON.
2. If it still fails, run the module directly via Python so it inherits the correct permissions:

   python3 -m airshark
   

Known Limitations

EAPOL (4-Way Handshake) Capture

For reliable EAPOL capture (and subsequent WPA decryption), it is recommended to lock AirShark to the target AP's specific channel (e.g., airshark -c 60) rather than sweeping an entire band, or use the h keybind and select the channel using , and . keys.

Multi-Band Hopping (2.4 + 5 GHz + 6 GHz)

The macOS CoreWLAN framework imposes hardware limitations that prevent the Wi-Fi radio from transparently hopping across different frequency bands. If attempted, the initial cross-band hop may succeed, but subsequent hops are silently ignored by the macOS Wi-Fi driver. Therefore, AirShark restricts channel hopping to a single band at a time (e.g., 2.4 GHz, 5 GHz, or 6 GHz). Refer to this post on the Apple developer forums for additional technical context.

Named pipe support

You can stream packets from AirShark to other tools like Wireshark using Unix named pipes.

1. Create the named pipe:

   mkfifo /tmp/airshark.pipe
   

2. Start Wireshark reading from the pipe first:

   wireshark -k -i /tmp/airshark.pipe &
   

3. Run AirShark and output to the pipe:

   airshark --band 5 -o /tmp/airshark.pipe
   

CLI Reference

capture:
  -i IFACE, --interface   Wireless interface (default: en0)
  -I, --monitor           Enable monitor mode (default: on)
  -o FILE, --output       Output PCAP file or named pipe (default: airshark_capture.pcap)
  -c N, --channel         Channel for single mode (default: 6)
  --band BAND             Band to sweep: single | 2.4 | 5 | 6
  --dwell SECS            Seconds per channel when hopping (default: 0.75)

decryption:
  -s, -S, --ssid SSID     Network SSID for WPA decryption
  -k PASSPHRASE, --key    WPA/WPA2 passphrase