twelve36

In macOS and prior most functionality found in the GUI can also be performed from the command line. One of those is the “airport” command which allows users to scan, sniff, connect, and disconnect from Wireless routers.

If you are not comfortable with the command line, I have a previous post here on Mac Built-in Wireless Tools accessible in the GUI.

Getting Started

The airport command is found in the following directory:

/System/Library/PrivateFrameworks/Apple80211.framework/Versions/Current/Resources/airport

The easiest way to use the airport command is by creating a Symbolic link.

sudo ln -s /System/Library/PrivateFrameworks/Apple80211.framework/Versions/Current/Resources/airport /usr/local/bin/airport

Scan

Perform a wireless scan of available Wireless networks by using the -s or –scan option. Example:

$ airport -s
                            SSID BSSID             RSSI CHANNEL HT CC SECURITY (auth/unicast/group)
              TheCenturionLounge 6c:f3:7f:58:3X:XX -77  1       Y  US NONE
                    WiFi Printer 28:cf:e9:82:eX:XX -91  149,+1  Y  US WPA2(PSK/AES/AES) 
  HP-Print-A5-Officejet Pro 8610 58:20:b1:5f:eX:XX -67  1       N  -- NONE
                   McCarran WiFi 40:e3:d6:f8:0X:XX -58  11      Y  -- NONE
                            Ji6S 3a:71:de:d3:6X:XX -78  11      Y  US WPA2(PSK/AES/AES) 
                            TCLO 6c:f3:7f:58:3X:XX -80  52,+1   Y  US WPA2(PSK/AES/AES) 
                        icandy 2 30:46:9a:3e:dX:XX -64  6       Y  -- WEP
 DIRECT-41-HP OfficeJet Pro 8730 72:5a:0f:f1:1X:XX -49  6       Y  -- WPA2(PSK/AES/AES) 

Sniff

When sniffing, you will need to define your WLAN interface. A channel number can be specified as well.

$sudo airport en0 sniff
Password:
Capturing 802.11 frames on en0.
^CSession saved to /tmp/airportSniffDiGthp.cap.

Status

Using the -I option will view the current wireless status information such as signal, BSSID, Authentication, etc. Example:

$ airport -I
     agrCtlRSSI: -66
     agrExtRSSI: 0
    agrCtlNoise: -95
    agrExtNoise: 0
          state: running
        op mode: station 
     lastTxRate: 174
        maxRate: 289
lastAssocStatus: 0
    802.11 auth: open
      link auth: none
          BSSID: 70:3a:e:21:eX:XX
           SSID: McCarran WiFi
            MCS: 8
        channel: 165 

Disconnect

WLAN Disconnect

If you want to disconnect from your existing WLAN you can use the -z option.

$ sudo airport -z

Disconnect After Logout

sudo airport en0 prefs DisconnectOnLogout=Yes

Output Information

Capture

When performing a Sniff it saves a .cap file to the /tmp directory.
Wireshark (tshark) and tcpdump are great options for analyzing the 802.11 frames quickly.

Read the captured packets in tcpdump.

tcpdump -r /tmp/airportSniffDiGthp.cap

Read the captured packets in tshark.

tshark -r /tmp/airportSniffDiGthp.cap

XML

Print info as XML by using the -x option. Example:

$ airport -I -x 
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>AUTH_LOWER</key>
	<integer>1</integer>
	<key>AUTH_UPPER</key>
	<integer>8</integer>
	<key>CHANNEL</key>
	<integer>36</integer>
	<key>CHANNEL_FLAGS</key>
	<integer>18</integer>
	<key>NOISE_CTL_AGR</key>
	<integer>-98</integer>
	<key>NOISE_UNIT</key>
	<integer>0</integer>
	<key>RSSI_CTL_AGR</key>
	<integer>-54</integer>
	<key>RSSI_CTL_LIST</key>
	<array>
		<integer>-51</integer>
		<integer>-53</integer>
		<integer>-60</integer>
	</array>
	<key>RSSI_EXT_AGR</key>
	<integer>0</integer>
	<key>RSSI_EXT_LIST</key>
	<array>
		<integer>0</integer>
		<integer>0</integer>
		<integer>0</integer>
	</array>
	<key>RSSI_UNIT</key>
	<integer>0</integer>
</dict>
</plist>

Save the XML info to a file.

$ airport -I -x >> /Users/UserName/Desktop/wifi.xml

Using the plutil we can convert a plist or xml file from one format to another.
Convert it to JSON format.

plutil -convert json wifi.xml -o wifi.json

File example:

{
	"RSSI_UNIT": 0,
	"AUTH_LOWER": 1,
	"NOISE_UNIT": 0,
	"CHANNEL_FLAGS": 532,
	"RSSI_CTL_AGR": -58,
	"CHANNEL": 149,
	"NOISE_CTL_AGR": -95,
	"RSSI_CTL_LIST": [-56, -62, -56],
	"AUTH_UPPER": 8,
	"RSSI_EXT_AGR": 0,
	"RSSI_EXT_LIST": [0, 0, 0]
}

You can use PlistBuddy command to read and write values to the file.

$/usr/libexec/PlistBuddy

Under Wireless Diagnostics in macOS, you can find additional tools for scanning, sniffing, and monitoring Wireless 802.11.

All these hidden tools are helpful when trying to analyze channels, coverage, or even troubleshoot connectivity issues.

I include some quick tutorials to manipulate the output information like captures and log files.

Launching Wireless Diagnostics

You can open the Wireless Diagnostics menu bar from the instructions below or by Spotlight.

Instructions:

1. On your Mac’s menu bar you’ll find the Wi-Fi icon, Push down the Option key ⌥ on your keyboard, and click the icon.
2. You should see a long menu appear, and near the top, you’ll see a menu item called ‘Open Wireless Diagnostics.’
3. Click “Open Wireless Diagnostics,” and now you can access the tools from the Wireless Diagnostics menu bar.

Spotlight:

Hit “Command-Space” from the keyboard to bring up Spotlight and type in “Wireless Diagnostics.”

Overview: Info, Performance, and Monitor

• Info: Gathers vital details about your current network connection.
• Performance: Uses three live graphs to show the performance of your Wi-Fi connection:
  • Rate: Gives the transmission rate over time in megabits per second.
  • Quality: Gives the signal-to-noise ratio over time.
  • Signal: shows both signal (RSSI) and noise measurements over time.
• Monitor: Displays a small window with one graph showing signal (RSSI) and noise measurements over time, and another showing transmission rate over time.

Below is a deeper dive on Scan, Sniffer, and logs.

Scan

Scan can survey, locate, and list wireless routers in your vicinity, it also shows details about them.

Some information it discovers:

• The Network Name or SSID
• The MAC address of Access Point (BSSID)
• Wireless security protocol in use
• 802.11 protocol in use
• Signal strength

You also get an overall summary which may allow you to make changes to your Wireless router configuration.

Sniffer

Sniffer captures traffic on your Wi-Fi connection giving you the ability to intercept and look at the packets afterward. The Sniffer is useful with:

• Diagnosing or investigating potential network problems
• Identifying configuration issues
• Monitoring network usage and activity
• Discovering possible network abuse, malware, and attacks

Start using the sniffer by selecting a Channel, Width, and clicking the “Start” button. When you click “Stop”, a capture file (.wcap) is saved to the /var/tmp/ directory on your Mac.

Capture File info

• The .wcap file extension is a Wireless Diagnostics captured packet
• Once saved they have a timestamp naming convention

Use Capture File

Copy all the capture files to a folder on your Desktop to easily access it.

sudo mkdir /Users/NameHere/Desktop/wifi && cp -R /var/tmp/*wcap wifi

You can rename the .wcap file extension to .pcap to open in third-party traffic analyzers like Wireshark or tcpdump.

sudo mv 2017.03.14_11-00-33-EDT.wcap 2017.03.14_11-00-33-EDT.pcap

Use tcpdump for analysis since it’s already available on Mac.

Read the captured packets.

tcpdump -r 2017.03.14_11-00-33-EDT.pcap

Read captured packets and print with link level header in hex along with ASCII.

tcpdump -XXr 2017.03.14_11-00-33-EDT.pcap

logs

When launching this tool, it enables logging in the background for Wireless and other parts of macOS. The results get saved to a log file (wifi.log) in the /private/var/log/ directory.

When you click the “Show” button, it will show the wifi.log file itself in the log directory.

Note: logging continues even when you quit the app or restart your Mac, so remember to disable logging after your finished.

Use Wifi log

I put together a few things below for viewing, monitoring, and handling the file.

Copy the log file to a folder on your Desktop to easily access it.

sudo mkdir /Users/NameHere/Desktop/wifi_logs && cp -R /private/var/log/wifi.log wifi_logs

Follow the wifi log file and filter out Bluetooth messages.

tail -f /private/var/log/wifi.log | grep -v 'Bluetooth'

Follow the wifi log file and view messages related to link quality like RSSI.

tail -f /private/var/log/wifi.log | grep 'link quality'