Catnip is a unified development enviroment designed for research and analysis of communication protocols in the Internet of Things (IoT). This tool centralizes in a single command-line interface (CLI) all the functionalities needed to work with CatSniffer V3 hardware, eliminating the need to use multiple independent scripts.

The system automates complex processes such as firmware management, hardware configuration, and radio traffic capture, allowing users to focus on security analysis and protocol development.

Catnip is aimed at:

• Security researchers analyzing vulnerabilities in IoT devices.
• Firmware developers working with wireless communication protocols.
• Network engineers specializing in Zigbee, Thread, LoRa, and BLE technologies.
• Pentesting professionals assessing the security of IoT ecosystems.

1. catnip.py : this is the main script and the entry point, providing access to all system functionalities through structured commands.

2. modules/ : this is the application code, devidied on:

   • cli.py: Defines the user-available command interface.
   • flasher.py: Manages download, SHA256 verification, and flashing of firmware to the CC1352 chip.
   • catnip.py: Implements automatic serial port detection logic and hardware communication.
   • bridge.py: Establishes the serial communication bridge with devices.
   • cc2538.py: Provides low-level control for the CC2538 chip.
   • pipes.py: Creates data pipes that transmit captured packets in PCAP format to Wireshark.
   • verify.py: Runs self-diagnostic tests to validate hardware operation.
   • cativity/: Submodule dedicated to monitoring activity on 802.15.4 channels (Zigbee/Thread).
   • meshtastic/: Submodule for Meshtastic protocol integration and capture.
   • sx1262/: Submodule for SX1262 radio spectrum analysis.

3. protocol/: contains specific implementations for each radio chip family.

   • sniffer_ti.py: Driver for Texas Instruments chips (Zigbee, Thread, 802.15.4).
   • sniffer_sx.py: Driver for Semtech SX1262 chips (LoRa).
   • common.py: Functions shared across all protocols.

4. Auto-generated firmware directory

When you run Catnip for the first time, the tol will automatically creates a new directory following the pattern: release_board-v3.x-vX.X.X/

This directory stores dowloaded firmware files (.hex, .uf2) from the official GitHub repository.

1. Unified All-in-One Environment

   • Single CLI interface replacing multiple independent scripts.
   • Simplifies firmware management, flashing, and protocol capture.

2. Automatic Firmware Management

   • Automatic detection of available versions.
   • Download from official GitHub repositories.
   • Integrity verification via SHA256

3. Automatic Device Detection

   • Identification of connected CatSniffer devices.
   • Sequential ID assignment for multi-device configurations.
   • Optional manual selection for environments with multiple units.

4. Multi-Protocol Support

   • LoRa: SX1262 radio for long-range communications.
   • Zigbee: IEEE 802.15.4 protocol for sensor networks.
   • Thread: Mesh protocol for residential IoT.
   • BLE: Bluetooth Low Energy via Sniffle firmware.
   • Meshtastic: Open source long-range communication protocol.
   • AirTag: Apple Find My network detection and tracking.

5. Spectrum Analysis

   • SX1262-based spectrum analyzer for LoRa frequencies.
   • Real-time frequency scanning and visualization.
   • Channel activity detection.

6. IQ Activity Monitor (Cativity)

   • Real-time visualization of 802.15.4 channel activity.
   • Network topology discovery for Zigbee/Thread networks.
   • Protocol filtering (Zigbee/Thread).
   • Channel hopping analysis.

7. Automatic On-Demand Flashing

   • Minimizes manual user intervention.
   • Detects if required firmware is present.
   • Automatically flashes before starting capture sessions.

8. Native Wireshark Integration

   • Extcap support for real-time captures.
   • Custom dissectors for specialized protocols.
   • Integrated workflow without manual configuration.

9. Cross-Platform Compatibility

   • Full support for Linux.
   • Functionality on macOS.
   • Windows compatibility.

1.Download the installer catnip-x.x.x.x.exe from the releases section of the CatSniffer Tools repository.

2.Run the installer and follow the the installation wizard. Allow the installation of the USB driver if prompted.

3.Complete the installation by click the "Finish" button to exit the installer.

Catnip is now available system wide and as an app in your start menu and desktop if you these two options were checked during the installation.

• System requirements:
  • macOS 11 (Big Sur) or newer
  • Intel or Apple Silicon (M1, M2, M3) Mac
  • At least 100 MB free disk space

You need to verify the architecture of your MAC with the command:

uname -m

The command will return any of the following depending on the mac architecture

• arm64 = Apple Silicon (M1/M2/M3)
• x86_64 = Intel

Once you know your architecture continue with the instructions according to your variant.

1.Download the installer catnip-x.x.x.x-x86_64.pkg from the from the releases section of the CatSniffer Tools repository.

2.Open a new terminal session in the path where the installer is located.

3.Run the command.

sudo installer -allowUntrusted -pkg catnip-x.x.x.x-x86_64.pkg -target /

Replace the Catnip name to match the actual name of the Catnip installer file.

1.Download the installer catnip-x.x.x.x-arm64.pkg from the from the releases section of the CatSniffer Tools repository.

2.Open a new terminal session in the path where the installer is located.

3.Run the command.

sudo installer -allowUntrusted -pkg catnip-x.x.x.x-arm64.pkg -target /

Replace the Catnip name to match the actual name of the Catnip installer file.

After installation, you may need to run the follwoing commands to allow your user access the serial ports:

1.Add your user to the necessary groups.

sudo dseditgroup -o edit -a $(whoami) -t user dialout

2.Install udev-like rules (for serial port access).

sudo catnip setup-env

• System Requirements
  • Debian 11+ or Ubuntu 20.04+
  • sudo privileges
  • At least 100 MB free disk space

1.Download the installer catnip-x.x.x.x.deb from the from the releases section of the CatSniffer Tools repository.

2.Open a new Terminal session in the installer file location.

3.Run the command.

sudo dpkg -i catnip-x.x.x.x.deb

Replace the Catnip name to match the actual name of the Catnip installer file.

4.Install the dependencies if any are missing by running the command.

sudo apt-get install -f

catnip --version

• System Requirements
  • Arch Linux (or derivates like manjaro)
  • sudo privileges
  • Base-devel packafe group (for building from source)

1.Download the latest version of the installer package.

URL=$(curl -s https://api.github.com/repos/ElectronicCats/catsniffer-tools/releases/latest | grep "browser_download_url.*pkg.tar.zst" | cut -d '"' -f 4) && wget "$URL"

2.Install the package by running the command.

sudo pacman -U catnip-x.x.x.x.pkg.tar.zst

Replace the Catnip name to match the actual name of the Catnip installer file.

catnip --version

If you prefer using an AUR helper:

# Using yay
yay -S catnip

# Using paru
paru -S catnip

1.Clone the repository.

git clone https://github.com/ElectronicCats/catsniffer-tools.git

2.Navigate to the catnip folder.

cd catsniffer-tools/catnip

3.Install the dependencies.

• Debian:

   sudo apt-get update
   sudo apt-get install python3 python3-pip python3-venv libusb-1.0-0 libmagic1

• Arch Linux:

  sudo pacman -S python python-pip python-virtualenv libusb file

4.Create and activate virtual environment (recommended).

python3 -m venv venv
source venv/bin/activate

5.Install Python dependencies.

pip install -r requirements.txt

6.Install the package in development mode.

pip install -e .

7.Make the script executable.

chmod +x catnip.py

8.Create a symlink (optional).

sudo ln -s $(pwd)/catnip.py /usr/local/bin/catnip

1.Run the setup command to configure udev rules and user permissions.

sudo catnip setup-env

This command will

• Install udev rules for CatSniffer devices
• Add your user to the dialout and bluetooth groups
• Configure permissions for serial ports

2.Log out and log back in for group changes to take effect.

Install tab completion for your shell (only available for macOS and Linux systtems).

1.Run the following command.

catnip completion install

catnip completion install --shell bash
catnip completion install --shell zsh
catnip completion install --shell fish

2.Restart your shell.

1.Check VHCI prerequisites.

catnip vhci check

2.Load kernel module.

sudo modprobe hci_vhci

3.Start VHCI bridge.

catnip vhci start

1.Go to Settings → Apps → CatSniffer → Uninstall.

Or run the installer again and select "Remove".

1.Remove the package receipts.

sudo pkgutil --forget com.electroniccats.catnip

2.Delete the installed files.

sudo rm -rf /usr/local/bin/catnip
sudo rm -rf /usr/local/lib/python3.*/dist-packages/catnip/
sudo rm -rf /usr/local/lib/python3.*/dist-packages/protocol/

1.Run the command in the Terminal.

sudo dpkg -r catnip

1.Run the command in the Terminal.

sudo pacman -R catnip

When running the tool for the first time from a clean environment, the system automatically performs:

1. Download of the latest official firmwares.
2. Integrity verification via SHA256 checksums.
3. Creation of working directories.

python catnip.py devices

To start using Catnip you can use the command in a terminal session:

catnip

You will see the main view of the CLI:

╭─ Flasher CLI - For sniffing the TI CC1352 device communication interfaces────╮
│                                                                              │
│        :-:              :--       |                                          │
│        ++++=.        .=++++       |                                          │
│        =+++++===++===++++++       |                                          │
│        -++++++++++++++++++-       |                                          │
│   .:   =++---++++++++---++=   :.  |  Module:  Catnip                         │
│   ::---+++.   -++++-   .+++---::  |  Version: X.X.X.X                        │
│  ::1..:-++++:   ++++   :++++-::.::|  Company: Electronic Cats - PWNLAB       │
│  .:...:=++++++++++++++++++=:...:. |                                          │
│   :---.  -++++++++++++++-  .---:  |                                          │
│   ..        .:------:.        ..  |                                          │
│                                                                              │
╰──────────────────────────────────────────────────────────────────────────────╯


[XX:XX:XX] [*] Looking for local releases
           [*] No Local release folder found!
           [*] Local release folder created: /path/to/release_board-v3.x-vX.X.X
           [*] Local metadata created
[XX:XX:XX] [*] Firmware airtag_scanner_CC1352P_7_vX.X.hex done.
           [*] airtag_scanner_CC1352P_7_vX.X.hex Checksum SHA256 verified
           [*] Firmware CC1352_sniffle_CC1352P_7_vX.X.X.hex done.
           [*] CC1352_sniffle_CC1352P_7_vX.X.X.hex Checksum SHA256 verified
           ...
[XX:XX:XX] [*] Current Release board-v3.x-vX.X.X - 20XX-XX-XXTXX:XX:XXZ

In this main view output you can check the following:

• Local release search: Checks if firmware has been previously downloaded.
• Firmware download: Retrieves each required file from the official repository.
• SHA256 verification: Validates the integrity of each downloaded firmware.
• Final confirmation: Shows the installed release version and its publication date.

Before performing any operation, it is recommended to verify that the system correctly detects the CatSniffer(s). To do this, run the command:

catnip devices

Each CatSniffer device exposes three serial ports with specific functions:

1. Cat-Bridge (CC1352): Main communication port.

   • Used for firmware flashing.
   • Data channel for protocol sniffing.
   • TI CC1352 chip control interface.

2. Cat-LoRa (SX1262): LoRa radio interface.

   • Communication with Semtech SX1262 chip.
   • LoRa packet capture.
   • Radio parameter configuration.

3. Cat-Shell (Config): Configuration port.

   • Bootloader access.
   • Advanced device configuration.
   • Interactive command shell.

Example of expected output when having multiple CatSniffer connected:

                          Found 2 CatSniffer device(s)
╭───────────────┬─────────────────────┬───────────────────┬────────────────────╮
│ Device        │ Cat-Bridge (CC1352) │ Cat-LoRa (SX1262) │ Cat-Shell (Config) │
├───────────────┼─────────────────────┼───────────────────┼────────────────────┤
│ CatSniffer #1 │ /dev/ttyACM3        │ /dev/ttyACM4      │ /dev/ttyACM5       │
│ CatSniffer #2 │ /dev/ttyACM0        │ /dev/ttyACM1      │ /dev/ttyACM2       │
╰───────────────┴─────────────────────┴───────────────────┴────────────────────╯

Where:

• CatSniffer #1: First detected device, accessible as --device 1
• CatSniffer #2: Second detected device, accessible as --device 2

After initialization, the tool displays available commands. Usage:

catnip <OPTIONS> <COMMAND>

Catnip completely automates the process of downloading, verifying, and installing firmware on the CC1352 chip.

Usage:

catnip flash <OPTIONS> <FIRMWARE>

Usage Examples:

In the following command we have selected a CatSniffer and flash the Texas Instrument multiprotocol sniffer to sniff Zigbee traffic.

catnip flash --device 1 zigbee

The system accepts four methods to specify which firmware to flash:

Aliases are short names assigned to each firmware. This is the most conveniente method. This method is easy to remember, require less typing and is less prone to typos.

Example:

catnip flash sniffle

Catnip can make partial matches of the firmware file name. This is useful when you do not remember the full name of the firmware, there is no need to remember specific aliases.

Example:

catnip flash sniffer_ti

Exaxt specification of the firmware file name. Useful in automated scripts.

Example:

catnip flash sniffer_ti_CC1352P_7_v1.0.hex

Catnip allows flashing custom firmware files that are not in the official repository, as long as they are placed in the release directory and follow the expected format or write the path there the custom firmware is located.

Example:

catnip flash --device 1 ~/PersonalProject/workspace/custom_firmware_v1.0.hex

Flashing workflow:

1. Device selection: Identifies the target CatSniffer.
2. Firmware resolution: Converts alias/partial name to complete file.
3. Integrity verification: Validates SHA256 before flashing.
4. Bootloader mode: Places the chip in programming mode.
5. Flash erasure: Clears existing flash memory.
6. Writing: Transfers the new firmware with progress indicator.
7. Post-write verification: Confirms data was written correctly.
8. Identification: Sends a command to confirm visual identification of the device.
9. Reset: Returns device to normal operating mode.

Catnip can run a verification tets to confirm that the CatSniffer hardware is working correctly. Runs fundamental communication and detection tests.

Command:

catnip verify <OPTIONS>

When verification fails, the system provides detailed infromation to diagnose the problem.

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

CatSniffer uses Sniffle firmware for BLE traffic capture.

Usage:

catnip sniff ble <OPTIONS>

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

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.

Usage example:

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

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.

Usage:

catnip sniff airtag_scanner <OPTIONS>

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

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 correct serial configuration:
   • Port: Detected CatSniffer bridge port
   • Baud rate: 9600
   • Data bits: 8
   • Parity: None
   • Stop bits: 1
   • Flow control: None

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

Using screen (Linux/macOS):

# Start the firmware
python catnip.py 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

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:

Cativity monitors all these channels to detect network activity.

Usage:

catnip cativity <OPTIONS>

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 activity)
• Packets: Cumulative packet count on that channel

If a channel is fixed, cativity will continuously monitors 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 slo focus on a single protocol traffic, like Zigbe or Thread. Cativity firmware can differentiate the packets from Zigbee and Thread by the application support layer protocol field, presence of IPV6 hreaders and MLE (Mesh Link Establishment) characteristics.

Command example:

catnip cativity --protocol thread

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 reponse
• 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

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

Usage:

catnip meshtastic decode <OPTIONS>