DOCSEARCHbyAlgolia
Submit Docs

KillerBee Framework

repository·develop·Indexed 21 days ago

https://github.com/riverloopsec/killerbee

A framework and toolkit for testing and auditing ZigBee and IEEE 802.15.4 networks. It includes a Python library for developers and a suite of command-line tools for sniffing, injecting, and analyzing wireless traffic. Supported hardware includes the River Loop ApiMote, Atmel RZ RAVEN USB Stick, MoteIV Tmote Sky, TelosB mote, Sewino Sniffer, and Silicon Labs Node Test hardware.

Tokens
3.7K
Snippets
14
Records
23
Agent score
74%

What's inside KillerBee

  1. Organize tool scripts by target audience

    develop

    KillerBee uses two main directories for scripts to distinguish between general-purpose tools and internal helpers:

    • tools/: Intended for scripts designed for common end-user use.
    • scripts/: Intended for tailored helper scripts or internal tools that are not yet ready for general release.

  2. Naming conventions for KillerBee tools

    develop

    When developing new tools for the project, use specific prefixes in the filename to indicate the tool's purpose:

    • Use the zb prefix for tools that operate on IEEE 802.15.4 or ZigBee RF, PCAP files, etc.
    • Use the kb prefix for tools designed to setup or configure the KillerBee framework itself.

    All tools must implement standard command line flag parsing using the argparse module. For reference on expected flag implementation, examine the zbdump tool.

  3. Understand the KillerBee architecture and components

    develop

    KillerBee is organized into several functional layers that allow users to interact with ZigBee radio peripherals.

    • Core: The fundamental library for radio interaction. It provides low-level methods like pnext(), inject(), set_channel(), and sniffer_on()/off().
    • Drivers: Device-specific implementations of the core functionality (e.g., dev_*.py files).
    • Utilities: A collection of convenience functions categorized by purpose:
      • pcap: Packet capture utilities (planned migration to Scapy).
      • device: Device discovery and identification (e.g., devlist(), is_[device]()).
      • zigbee: ZigBee-specific logic (e.g., makeFCS(), randmac(), extractkey()).
      • crypto: Cryptographic operations (e.g., encrypt_ccm(), decrypt_ccm(), hash_mmo()).
      • rf4ce: RF4CE specific logic (e.g., derivekey()).
      • home-automation: High-level automation commands (e.g., disarm(), sensor_trigger(), tamper()).
    • Scapy Extension: A wrapper layer that integrates Core and Utilities with Scapy, allowing users to use commands like kbsend() and kbsniff() as if they were native Scapy functions.
    • Tools:
      • Simple tools: Script wrappers for specific tasks (e.g., zbcat, zbdump, zbwireshark, zbid, zbcrypto).
      • Fully-featured tools: Complex standalone tools (e.g., zbwardrive, openear).

  4. Hardware Support for KillerBee

    develop

    KillerBee supports multiple hardware devices. Currently supported devices include:

    • River Loop ApiMote
    • Atmel RZ RAVEN USB Stick
    • MoteIV Tmote Sky
    • TelosB mote
    • Sewino Sniffer
    • Various hardware running Silicon Labs Node Test firmware

    Note: Support for Freaklab's Freakduino and Zigduino boards is available but unmaintained. To use them, you must manually enable them in killerbee/config.py and reinstall KillerBee. For details on firmware programming, see firmware/README.md.

  6. Flash ApiMote v4beta firmware

    develop

    ApiMote v4beta devices typically come preloaded and do not require reflashing for basic use (sniffing, injection, and jamming). If you need to flash the device, plug it in and execute the flash_apimote.sh script. Note that if the first attempt fails to synchronize and times out, a second attempt may be required.

    ./flash_apimote.sh

  7. Install KillerBee on Ubuntu

    develop

    To install KillerBee on Ubuntu, you must first install the required system dependencies using apt-get. After the dependencies are installed, use the Python setup.py script to perform the installation.

    Note: This platform is intended for advanced analysts and developers. Familiarity with the ZigBee protocol and Python is recommended.

    # Install dependencies
apt-get install python-usb python-crypto python-serial python-dev libgcrypt-dev

# Install KillerBee
python3 setup.py install

  8. Flash KillerBee firmware to RZUSBSTICK using Atmel-ICE Basic (Windows)

    develop

    This method uses AtmelStudio and an Atmel-ICE Basic hardware debugger.

    1. Connect Atmel-ICE Basic to the USB port and the 10-pin connector to the RZUSBstick.
    2. In AtmelStudio, go to Tools > Device Programming.
    3. Configure settings:
      • Tools: Atmel-ICE
      • Device: AT90USB1287
      • Interface: JTAG
    4. Click Apply. If an error occurs, flip the 10-pin connector.
    5. In the Memories tab, select the KillerBee .hex file from the firmware/ directory.
    6. Check Erase device before programming and Verify Flash after programming.
    7. Click Program and wait for the success message.

  9. Flash KillerBee firmware to RZUSBSTICK using OpenOCD and Bus Pirate (Linux)

    develop

    This method uses a Dangerous Prototypes Bus Pirate and OpenOCD to flash the RZUSBSTICK.

    1. Install OpenOCD with Bus Pirate support

    sudo apt-get install git
git clone git://git.code.sf.net/p/openocd/code
sudo apt-get install libtool autoconf texinfo libusb-dev libftdi-dev pkg-config libusb-1.0.0
cd code
./bootstrap
./configure --enable-maintainer-mode --disable-werror --enable-buspirate
make
sudo make install

    2. Configure and Flash

    1. Obtain firmware/kb-rzusbstick-006.hex.
    2. Download an OpenOCD configuration file for the DP buspirate and edit the _FIRMWARE_LOCATION variable to point to your .hex file: set _FIRMWARE_LOCATION /path/to/kb-rzusbstick-006.hex
    3. Connect the Bus Pirate to the RZ Raven (GND to GND, TCK to CLK, TDO to MISO, TMS to CS, TDI to MOSI, SRCT to AUX).
    4. Run OpenOCD:
    openocd -f openocd_bp.cfg
    openocd -f openocd_bp.cfg

  10. Install KillerBee on macOS

    develop

    To install KillerBee on macOS, use brew for system libraries and pip3 for Python modules. Note that macOS usage is possible but not officially supported.

    # Install dependencies
brew install libusb libgcrypt
pip3 install pyusb scapy

# Install KillerBee
python3 setup.py install

  11. Generate KillerBee API Documentation (PDF)

    develop

    If you have epydoc installed, you can generate a PDF version of the KillerBee framework documentation by navigating to the killerbee directory and running the following commands:

    ```bash
$ cd killerbee
$ mkdir pdf
$ epydoc --pdf -o pdf killerbee/

    The resulting documentation will be located at pdf/api.pdf.

  12. Flash KillerBee firmware to RZUSBSTICK using AVR Dragon (Windows/Linux)

    develop

    This method uses an Atmel AVR Dragon On-Chip Programmer and requires specific hardware (JTAG Standoff Adapter, header, and ribbon cable).

    Windows Driver Setup:

    1. Use libusb-win32's inf-wizard.exe to install drivers for the AVR Dragon (Vendor ID: 0x03EB, Product ID: 0x2107).
    2. Accept the prompt to "Install This Driver Software Anyway".

    Flashing Procedure:

    1. Copy the desired firmware (e.g., kb-rzusbstick-006.hex) to your AVRDUDE directory.
    2. Connect the hardware as described in the documentation.
    3. Run the avrdude command. Use kb-rzusbstick-006.hex for newer models, or kb-rzusbstick-001.hex for older models.

    Note: Ensure the header is inserted into the RZUSBSTICK with pin 1 closest to the LEDs.

    avrdude -P usb -c dragon_jtag -p usb1287 -B 10 -U flash:w:kb-rzusbstick-006.hex