Catnip is a unified development environment 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, divided into:

   • 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 tool will automatically create a new directory following the pattern: release_board-v3.x-vX.X.X/

This directory stores downloaded 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.