Skip to content

04. Catnip Protocol Sniffing

Jump to bottom Edit New page
Carlos Alatorre edited this page May 14, 2026 · 4 revisions

Protocol sniffing

The sniffing module allows capturing radio traffic in real-time and sending it to analysis tools like Wireshark.

Bluetooth Low Energy (BLE)

CatSniffer uses Sniffle firmware for BLE traffic capture.

Usage:

catnip sniff ble <OPTIONS>
Argument <OPTIONS> Description
--help Display the help menu and available <OPTIONS>
--device, or -d INTEGER Device ID (for multiple CatSniffers). If not specified, the first device will be selected
--wireshark, or -ws Open Wireshark with Sniffle extcap plugin
--channel, or -c BLE advertising channel (37, 38, 39)
--mode, or -m Sniffle mode

BLE configuration parameters

1.Advertising Channels (--channel)

BLE uses three dedicated channels for advertising:

  • Channel 37: Frequency 2402 MHz
  • Channel 38: Frequency 2426 MHz
  • Channel 39: Frequency 2480 MHz

2.Sniffle Modes (--mode)

  • conn_follow: Follows established BLE connections

    • Useful for analyzing communication between already paired devices
    • Captures all traffic of the active connection

  • passive_scan: Passive advertising scan

    • Does not send packets, only listens
    • Lower energy consumption
    • Not detectable by BLE devices

  • active_scan: Active scan

    • Sends scan requests (SCAN_REQ)
    • Obtains more information from devices
    • Detectable by BLE devices

Wireshark integration

The integration with Wireshark grants a real-time visual analysis. Opening Wireshark right away after sending the command in catnip and decoding the BLE packets using Sniffle dissectors. For more information refer to section Wireshark Integration.

Usage example:

catnip sniff ble --wireshark --channel 38 --mode conn_follow

Usage example of the catnip-Wireshark integration
Usage example of the catnip-Wireshark integration

AirTag Scanner

The AirTag Scanner is a specialized firmware that allows CatSniffer to detect and monitor Apple AirTags and Find My network devices. This tool is useful for security research, privacy auditing, and understanding the Apple Find My ecosystem.

An Apple AirTag is a tracking device that uses Bluetooth Low Energy (BLE) to communicate with nearby Apple devices, which then relay the AirTag's location to iCloud. The Find My network is a crowdsourced network of Apple devices that helps locate lost items.

Important

The AirTag Scanner firmware operates in a different mode than other sniffers. It does not create PCAP files or integrate with Wireshark. All output is displayed through the serial console.

Usage:

catnip sniff airtag_scanner <OPTIONS>
Argument <OPTIONS> Description
--help Display the help menu and available <OPTIONS>
--putty, or -d Open PuTTY with serial configuration
--device, or -d INTEGER Device ID (for multiple CatSniffers). If not specified, the first device will be selected

The AirTag Scanner operates differently from other sniffing modes. Instead of creating a PCAP file, it outputs detection information directly to the serial console.

PuTTY integration

For convenience, Catnip includes automatic PuTTY integration that configures the serial terminal with the correct parameters.

What happens:

  1. Verifies AirTag Scanner firmware is installed (flashes if needed)
  2. Detects PuTTY installation on your system
  3. Launches PuTTY with the correct serial configuration:
    • Port: Detected CatSniffer bridge port
    • Baud rate: 9600
    • Data bits: 8
    • Parity: None
    • Stop bits: 1
    • Flow control: None

Note

The --putty option works across different operating systems

If you prefer using a different serial terminal (e.g., screen, minicom, ect), you can connect manually:

Using screen (Linux/macOS):

# Start the firmware
catnip sniff airtag_scanner

# In another terminal, connect with screen
screen /dev/ttyACMX 9600

Using minicom (Linux):

# Configure minicom
minicom -D /dev/ttyACMX -b 9600

Using Windows Serial Terminal:

# Use any serial terminal (PuTTY, TeraTerm, etc.)
# Configure: COM port (check Device Manager), 9600 baud, 8N1

Tip

For automated logging, redirect the serial output to a file using your serial terminal's logging feature or tools like screen -L.

IQ Activity Monitor (Cativity)

Cativity is a specialized tool for analyzing 802.15.4 networks (Zigbee and Thread) that provides real-time visualization of radio channel activity and network topology discovery.

IEEE 802.15.4 is the physical and data link layer standard used by:

  • Zigbee: Mesh network protocol for IoT (smart home, industrial automation)
  • Thread: IPv6 over mesh networks (Google Nest, Matter)

The standard defines 16 channels in the 2.4 GHz band:

Channel Center Frequency Bandwidth
11 2405 MHz 2 MHz
12 2410 MHz 2 MHz
... ... ...
26 2480 MHz 2 MHz

Cativity monitors all these channels to detect network activity.

Usage:

catnip cativity <OPTIONS>
Argument <OPTIONS> Description
--help Display the help menu and available <OPTIONS>
--device, or -d INTEGER Device ID (for multiple CatSniffers). If not specified, the first device will be selected
--channel, or -c Define a fixed channel (11-26) for the CatSniffer to scan
--topology, or -t Show network topology
--protocol, or -p Protocol filter, you can use all, zigbee, or thread

Cativity default mode visualizes packet activity on all 802.15.4 channels through automatic channel hopping.

Real-time Visualization:

                    Channel Activity
┏━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┓
┃ Current ┃ Channel ┃ Activity                ┃ Packets ┃
┡━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━┩
│         │ 11      │                         │ 0       │
│         │ 12      │                         │ 0       │
│         │ 13      │                         │ 0       │
│         │ 14      │                         │ 0       │
│         │ 15      │ ❚❚                      │ 2       │
│         │ 16      │                         │ 0       │
│         │ 17      │                         │ 0       │
│         │ 18      │                         │ 0       │
│         │ 19      │ ❚                       │ 1       │
│         │ 20      │                         │ 0       │
│         │ 21      │ ❚                       │ 1       │
│         │ 22      │                         │ 0       │
│         │ 23      │                         │ 0       │
│         │ 24      │                         │ 0       │
│         │ 25      │ ❚❚❚❚❚❚❚❚❚❚❚❚❚❚❚❚❚❚❚❚❚❚❚     │ 23      │
│ ---->   │ 26      │ ❚                       │ 1       │
└─────────┴─────────┴─────────────────────────┴─────────┘
                Channel Hopping Activity

Interpretation:

  • Current: Indicates the channel currently being monitored (marked with ----->)
  • Channel: 802.15.4 channel number (11-26)
  • Activity: Graphical representation of traffic intensity (each ❚ represents an activity)
  • Packets: Cumulative packet count on that channel

If a channel is fixed, Cativity will continuously monitor this specific channel.

Command example:

catnip cativity --channel 15

Output:

ℹ Checking for Sniffer TI firmware...
✓ Sniffer TI firmware found (via metadata)!
ℹ [CatSniffer #1] Starting Cativity analysis...
                    Channel Activity
┏━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┓
┃ Current ┃ Channel ┃ Activity                ┃ Packets ┃
┡━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━┩
│ ---->   │ 25      │ ❚❚❚❚❚❚❚❚ (107) ❚❚❚❚❚❚❚❚    │ 107     │
└─────────┴─────────┴─────────────────────────┴─────────┘
                Channel Hopping Activity

You can also focus on a single protocol traffic, like Zigbee or Thread. Cativity firmware can differentiate the packets from Zigbee and Thread by the application support layer protocol field, the presence of IPv6 headers, and MLE (Mesh Link Establishment) characteristics.

Command example:

catnip cativity --protocol thread

Meshtastic Protocol Tools

Meshtastic is an open-source, long-range communication protocol that uses LoRa radio technology to create decentralized mesh networks. Catnip provides a comprehensive suite of tools for decoding, analyzing, and interacting with Meshtastic networks.

Meshtastic enables devices to communicate over long distances (kilometers) without cellular or Wi-Fi connectivity. It's commonly used for:

  • Emergency communication and disaster response
  • Outdoor adventures and hiking
  • Community mesh networks
  • IoT sensor data collection
  • Off-grid messaging

The protocol uses LoRa modulation with AES-256 encryption and operates primarily in the 868-915 MHz ISM bands.

Usage:

catnip meshtastic <OPTIONS> COMMAND
Argument <OPTIONS> Description
--help, or -h Show the help menu
Argument <COMMAND> Description
config Extract PSKs and config info from a Meshtastic JSONC configuration
dashboard Meshtastic Chat TUI
decode decrypt and decode previously captured Meshtastic packets
live Live Meshtastic decoder

Understanding the packet structure is essential for working with Meshtastic:

┌──────────┬──────────┬────────────┬───────┬─────────┬──────────┬─────────────┐
│ Dest     │ Sender   │ Packet ID  │ Flags │ Channel │ Reserved │ Payload     │
│ (4 bytes)│ (4 bytes)│ (4 bytes)  │ (1)   │ (1)     │ (2)      │ (Variable)  │
└──────────┴──────────┴────────────┴───────┴─────────┴──────────┴─────────────┘
  • Dest: Destination node ID (FFFFFFFF for broadcast)
  • Sender: Source node ID
  • Packet ID: Unique packet identifier
  • Flags: Contains hop limit, ACK requests, and routing information
  • Channel: Mesh channel number (0-7)
  • Payload: Encrypted protobuf message

Packet decoder

Usage:

catnip meshtastic decode <OPTIONS>
Argument <OPTIONS> Description
--input, or -i Hex-encoded payload (raw packet data starting with dest, sender, etc.), this is required
--key, or -k Base64-encoded AES key. Use 'ham' or 'nokey' for open channels

Meshtastic uses several standard keys that the decoder automatically tries:

Key Name Base64 Value
Default LongFast 1PG7OiApB1nwvP+rz05pAQ== Primary channel key
Secondary OEu8wB3AItGBvza4YSHh+5a3LlW/dCJ+nWr7SNZMsaE= Alternate channel
Tertiary 6IzsaoVhx1ETWeWuu0dUWMLqItvYJLbRzwgTAKCfvtY= Test networks
Quaternary TiIdi8MJG+IRnIkS8iUZXRU+MHuGtuzEasOWXp4QndU= Legacy networks

The decoder automatically identifies different Meshtastic message types:

  • Text Messages
[TEXT] !49ca27 -> ffffffff: Hello mesh network!
  • Position Updates:
[POSITION] !49ca27 -> ffffffff: 37.7749, -122.4194

Practical Examples

  • Example 1: decode a captured packet
catnip meshtastic decode \
  --input "fffffffff449ca27440287026300000048656c6c6f2065766572796f6e65"

Expected Output:

Decrypted raw (hex): 48656c6c6f2065766572796f6e65
[TEXT - UNENCRYPTED] f449ca27 -> ffffffff: Hello everyone
  • Example 2: Decode with custom key
catnip meshtastic decode \
  --input "fffffffff449ca27440287026300000041406aa0a81ef722d3a4598dc66326ace68cc3" \
  --key "1PG7OiApB1nwvP+rz05pAQ=="

Expected Output:

Decrypted raw (hex): 0801120f48656c6c6f20656e63727970746564
[TEXT] f449ca27 -> ffffffff: Hello encrypted
  • Example 2.1 Position with custom key
catnip meshtastic decode \
  --input "fffffffff449ca27440287026300000041426aa5ed3f7503aa913c259ea6" \
  --key "1PG7OiApB1nwvP+rz05pAQ=="

Expected Output:

Decrypted raw (hex): 0803120a0d44ee4d161500c63bb7
[POSITION] f449ca27 -> ffffffff: 37.420601999999995, -122.0819456
  • Example 3: Decode open channel (no encryption)
catnip meshtastic decode \
  --input "fffffffff449ca27440287026300000048656c6c6f2065766572796f6e65" \
  --key ham

Expected Output:

Decrypted raw (hex): 48656c6c6f2065766572796f6e65
[TEXT - UNENCRYPTED] f449ca27 -> ffffffff: Hello everyone

Live Decoder

The live decoder captures Meshtastic packets in real-time using the CatSniffer's LoRa port, automatically decrypting and displaying messages as they arrive. The live decoder automatically tries multiple known Meshtastic keys, making it effective for monitoring networks even without prior knowledge of the specific key.

What happens internally:

  • Packet is captured from the LoRa radio
  • Frame is extracted, and fields are parsed
  • Each known key is tried for decryption
  • First successful decryption is displayed
  • Protobuf is decoded based on the port number

Usage:

catnip meshtastic live <OPTIONS>
Argument <OPTIONS> Description
--help, or -h Show the help menu
--device, or -d INTEGER Device ID (for multiple CatSniffers). If not specified, the first device will be selected
--baudrate, or -baud INTEGER Baudrate (default: 115200)
--frequency, or -f FLOAT Frequency in MHz (default: 902.0)
--preset, or -ps CHAR Channel preset (default: LongFast)

Meshtastic uses specific LoRa radio configurations. The tool supports all standard --preset:

Preset Spreading Factor Bandwidth Coding Rate Description
defcon33 SF7 500 kHz 4/5 Short range, fastest speed, long preamble
ShortTurbo SF7 500 kHz 4/5 Short range, fastest speed
ShortSlow SF8 250 kHz 4/5 Short range, lower speed
ShortFast SF7 250 kHz 4/5 Short range, fastest speed
MediumSlow SF10 250 kHz 4/5 Medium range, moderate speed
MediumFast SF9 250 kHz 4/5 Medium range, good speed
LongSlow SF12 125 kHz 4/5 Maximum range, slowest speed
LongFast SF11 250 kHz 4/5 Default - Best range/speed balance
LongMod SF11 125 kHz 4/8 Long range, moderate speed, robust coding
VLongSlow SF11 125 kHz 4/8 Very long range, robust coding

Practical Examples

Command:

catnip meshtastic live --device 1 --frequency 906.875 --preset LongFast

Expected output:

ℹ Using device: CatSniffer #1
ℹ Configuring radio: 906.875 MHz (906875000 Hz), preset: LongFast
[*] Configuring radio via shell port /dev/ttyACM2
[*] Preset: LongFast, Freq: 906875000 Hz
  > lora_freq 906875000
  > lora_sf 11
  > lora_bw 8
  > lora_cr 5
  > lora_preamble 8
  > lora_syncword 0x2B
  > lora_apply
  > lora_mode stream
[*] Current LoRa configuration:
LoRa Configuration:
  Frequency: 906875000 Hz
  Spreading Factor: SF11
  Bandwidth: 250 kHz
  Coding Rate: 4/5
  TX Power: 20 dBm
  Preamble Length: 8
  IQ: Normal
  Sync Word: 0x2B (reg 0x24B4)
  Mode: Stream
[✓] Radio configured successfully
ℹ Starting capture... Press Ctrl+C to stop
[*] Capture started. Press Ctrl+C to stop.

============================================================
   Packet from 6c982bd0 to ffffffff
   Packet ID: b9850a47
   Channel: 8
   Flags: 0x63
     ├─ Hop limit: 3
     ├─ Want ACK:  0
     ├─ Via MQTT:  0
     └─ Hop Start: 3
      Decrypted with key #0

   Decrypted payload (hex):
   08 01 12 0A 48 65 6C 6C 6F 20 4D 65 73 68 48 00
[TEXT] d02b986c -> ffffffff: Hello Mesh

Chat Dashboard

The dashboard provides a beautiful terminal user interface (TUI) for monitoring Meshtastic networks in real-time, with features like channel filtering, message search, and automatic node name resolution.

Usage:

catnip meshtastic dashboard <OPTIONS>
Argument <OPTIONS> Description
--help, or -h Show the help menu
--device, or -d INTEGER Device ID (for multiple CatSniffers). If not specified, the first device will be selected
--baudrate, or -baud INTEGER Baudrate (default: 115200)
--frequency, or -f FLOAT Frequency in MHz (default: 902.0)
--preset, or -ps CHAR Channel preset (default: LongFast)

Chat Dashboard features:

  1. Channel Sidebar (Left)

    • Shows all channels (0-7) with message counts.
    • "All" shows total messages across all channels.
    • Actively updates as new messages arrive.
    • Selected channel is highlighted.

  2. Message Table (Right)

    • Time: Timestamp of the message.
    • Ch: Channel number (0-7).
    • From: Sender (node ID or resolved name).
    • Message: Decoded message content.

  3. Node Name Resolution. When node information packets are received, the dashboard automatically:

    • Stores node IDs and their friendly names.
    • Updates the display to show names instead of hex IDs.
    • Maintains a persistent registry during the session.
  • Keyboard Controls
Key Action Description
Q Quit Exit the dashboard
A All Channels Show messages from all channels
0-7 Channel N Filter to show only channel N
F Filter Text Search messages by text
C Clear Filter Remove text filter
↑/↓ Navigate Scroll through messages
PgUp/PgDn Page Scroll Jump by page

Practical Example

Command:

catnip meshtastic dashboard -d 1 -f 906.875 -ps LongFast

Initial screen:

┌─────────────────────────────────────────────────────────────────────────────┐
│ Meshtastic Chat TUI  Port: /dev/ttyACM1  Preset: LongFast  Freq: 906.875 MHz│
│                              — Press Q to quit, A for All, 0-7 for channel  │
├───────────────┬─────────────────────────────────────────────────────────────┤
│ Channels      │ Time     Ch  From                 Message                   │
├───────────────┼─────────────────────────────────────────────────────────────┤
│ All        1  │ 14:32:05 1   !49ca27              Hello mesh network!       │
│ Ch 0       1  │                                                             │
│ Ch 1       0  │                                                             │
│ Ch 2       0  │                                                             │
│ Ch 3       0  │                                                             │
│ Ch 4       0  │                                                             │
│ Ch 5       0  │                                                             │
│ Ch 6       0  │                                                             │
│ Ch 7       0  │                                                             │
└───────────────┴─────────────────────────────────────────────────────────────┘

Thank you for reading our Wiki!

CatSniffer

Catnip

CatSniffer and Kismet for Zigbee Network Analysis

Legacy Docummentation

CatSniffer V3.X

CatSniffer V1.X & V2.X

Clone this wiki locally