Packet Sniffing using Extcap

Extcap is a plugin for Wireshark that allows it to use the Pyspinel binary as a capture interface. Wireshark is an open-source tool that can decode network protocols in the Thread stack, such as IEEE 802.15.4, 6LoWPAN, IPv6, MLE (Mesh Link Establishment), UDP, and CoAP. Extcap reduces the setup and configuration needed to sniff Thread packets using Wireshark, as it does not require writing to a capture file.

This guide covers how to configure extcap for Wireshark to sniff packets from a Thread network.

To use Pyspinel for packet sniffing without extcap, see Packet Sniffing with Pyspinel.

Requirements

Hardware:

  • A host machine to serve as an NCP and to run Pyspinel and Wireshark:
    • macOS — 64 bit OS X 10.6 or later
    • Linux
    • Windows — 10 or later
  • 1 OpenThread device flashed with an ot-ncp-ftd or ot-rcp build.

Software:

Verification

This guide was verified with the Zolertia Firefly (Texas Instruments CC2538 SoC, using our pre-built NCP firmware on the following host systems:

  • Debian 4.19.37 — Wireshark 3.0.4
  • macOS Mojave 10.14.6 — Wireshark 3.0.5
  • 64bit Windows 10 version 17134 — Wireshark 3.0.6

Install Wireshark

Linux

Open a terminal and run the following commands to download and install Wireshark:

sudo add-apt-repository ppa:wireshark-dev/stable
sudo apt-get update
sudo apt-get install wireshark

We recommend running Wireshark as a non-root user. To do so, reconfigure the package:

sudo dpkg-reconfigure wireshark-common

When you get the dialog asking "Should non-superusers be able to capture packets?", select Yes, then add the wireshark user and update file permissions:

sudo adduser $USER wireshark
sudo chmod +x /usr/bin/dumpcap

macOS

Download and install Wireshark for macOS.

Build and flash the sniffer

Build and flashing instructions vary based on platform.

See Zolertia Firefly for instructions on how to use the pre-built NCP firmware with the platform.

For other platforms, see How to build OpenThread.

Set up the sniffer environment

  1. Open Wireshark. Go to Help > About Wireshark and select the Folders tab. The Extcap path entry lists the extcap location. Make note of this location.
  2. Install dependencies:
    sudo apt install python3-pip
    pip3 install --user pyserial ipaddress
  3. Clone the Pyspinel repository:
    git clone https://github.com/openthread/pyspinel
  4. Install Pyspinel, using the extcap path from Wireshark:
    cd pyspinel
    python3 setup.py install --extcap-path=extcap-path

Alternatively, set up the environment by installing the pyspinel package:

pip3 install pyspinel --install-option="--extcap-path=extcap-path"

Wireshark configuration - Protocols

Wireshark must be configured to properly show Thread packets.

Select Preferences... in Wireshark and expand the Protocols section.

6LoWPAN

Select 6LoWPAN from the list of protocols and verify or change the following settings:

  1. Uncheck Derive ID according to RFC 4944.
  2. Update Context 0 with the Mesh Local Prefix for the target Thread network.
OT Sniffer Wireshark 6LoWPAN

Wireshark uses context configurations to parse the compressed IPv6 address and display the IPv6 source and destination addresses correctly.

To show the addresses for other on-mesh prefixes configured on the gateway, update other Context IDs with those prefixes.

To get the Context ID for a specific on-mesh prefix, view the Thread Network Data TLV in any MLE Data response message. For example:

Context 1: fd00:7d03:7d03:7d03::/64

CoAP

Select CoAP from the list of protocols and set CoAP UDP Port to 61631. This ensures TMF messages (like address solicit) are displayed.

IEEE 802.15.4

Select IEEE 802.15.4 from the list of protocols and verify or change the following settings:

  1. Set 802.15.4 Ethertype (in hex) to "0x809a".
  2. Set the Security Suite to "AES-128 Encryption, 32-bit Integrity Protection".
  3. Click the Edit... button next to Decryption Keys, which is where you add the Thread network Master Key for packet decryption.
    1. Click + to add a Decryption key.
    2. Enter the Thread network Master Key into the Decryption key column.
    3. Enter "1" as the Decryption key index.
    4. Select Thread hash from the Key hash column listbox.
    5. OT Sniffer Wireshark IEEE 802.15.4
    6. Click OK to save the decryption key.

Thread

Select Thread from the list of protocols and verify or change the following settings:

  1. Enter "00000000" for the Thread sequence counter.
  2. Uncheck Use PAN ID as first two octets of master key.
  3. Check Automatically acquire Thread sequence counter.

Click the OK button to save any protocol changes.

Some Thread traffic might be analyzed as the ZigBee protocol. To correctly display these two protocols, edit the enabled protocols in Wireshark:

  1. In Wireshark, go to Analyze > Enabled Protocols.
  2. Uncheck the following protocols:
    1. LwMesh
    2. ZigBee
    3. ZigBee Green Power

Wireshark configuration - RSSI

To display RSSI in Wireshark:

  1. Go to Preferences > Protocols > IEEE 802.15.4.
  2. Set the FCS Format:
    • If IEEE 802.15.4 TAP disabled: TI CC24xx metadata.
    • If IEEE 802.15.4 TAP enabled: ITU-T CRC-16.
  3. Click OK to save and return to the Preferences menu.
  4. From Preferences, select Appearance > Columns.
  5. Add a new entry:
    • Title: RSSI
    • Type: Custom
    • Fields: wpan.rssi
OT Sniffer Wireshark RSSI

Use the sniffer

The Wireshark capture screen is displayed when Wireshark is first launched. It should list hardware interfaces connected to an OpenThread sniffer.

Capture from a single interface

If this is your first time using an interface, click on the Options button to the left of the interface:

OT Sniffer Wireshark Extcap Capture

  1. Set the Channel to the desired value.
  2. Check IEEE 802.15.4 TAP to ensure that the channel information is included in the pcap output and can be displayed in the Wireshark GUI.
  3. Check Save parameters on capture start to ensure that these parameters are saved after the start of the capture, to avoid having to set it again the next time you use the interface (unless you need to change the channel).
  4. Click Start.

OT Sniffer Wireshark Extcap Options

If your parameters are already saved, start sniffing by selecting the hardware interface and clicking the Wireshark icon in the top left.

Capture from multiple interfaces

Select all hardware interfaces listed in the capture screen and click the Wireshark icon on the top left.

Use these fields to idenify individual sniffers when capturing from multiple interfaces:

  • Interface ID (frame.interface_id) — Interface Identifier used by Wireshark to identify a capture interface
  • Interface name (frame.interface_name) — Interface name used by Wireshark to identify a capture interface
  • Channel (wpan-tap.ch_num) — IEEE 802.15.4 capture channel (range: 11-26)

OT Sniffer Wireshark Extcap Packets

Troubleshooting

The OpenThread sniffer is not listed as a Wireshark interface

  1. If you have multiple Python interpreters installed, ensure that Python 3 interpreter is used by the extcap script. Pyspinel doesn't support Python 2.
  2. Check if the hardware is enumerated on USB and the drivers are loaded.
  3. Check that the correct firmware (NCP or RCP) has been flashed to the hardware.
  4. Verify that the Python script located in the extcap path is executable.
    • For OS X and Linux:
      1. Verify that the execute permission is present for the extcap_ot.py file:
        ls -l extcap_ot.py
      2. If the execute (x) permission is missing, modify the permissions:
        chmod +x extcap_ot.py
      3. Verify the interface is listed:
        extcap_ot.py --extcap-interfaces
    • For Windows:
      1. Verify the interface is listed:
        extcap_ot.bat --extcap-interfaces
      2. If this exits with a Python error, verify the Python version is 3.x:
        py -3 --version

Wireshark only allows the root user to capture packets

During Wireshark installation on Ubuntu the user will be prompted to choose one of the following options:

  1. Create the wireshark user group and allow all members of that group to capture packets.
  2. Only allow the root user to capture packets.

Using the Wireshark as the root user is strongly discouraged. If you chose that option, change the setting:

sudo dpkg-reconfigure wireshark-common

If Wireshark was configured to restrict the capture to members of the wireshark group, you may need to add the correct user to the group:

sudo usermod -a -G wireshark user

Also add the correct user to the dialout group:

sudo usermod -a -G dialout user

Close and restart Wireshark to apply the new user group settings.

Wireshark format error when capturing on multiple USB interfaces on Windows

This is a known issue for some old versions of Wireshark. Make sure you are using Wireshark 3.0.6 or later.