This is KillerBee - Framework and Tools for Attacking ZigBee and IEEE 802.15.4 networks.
REQUIREMENTSKillerBee is developed and tested on Linux systems. OS X usage is possible but not supported.
We have striven to use a minimum number of software dependencies, however, it is necessary to install the following Python modules before installation:
- serial
- usb
- crypto (for some functions)
- pygtk (for use of tools that have GUIs)
- cairo (for use of tools that have GUIs)
- scapy (for some tools which utilize 802.15.4 Scapy extensions)
On Ubuntu systems, you can install the needed dependencies with the following commands:
# apt-get install python-gtk2 python-cairo python-usb python-crypto python-serial python-dev libgcrypt-dev
# git clone https://github.com/secdev/scapy
# cd scapy
# python setup.py install
The python-dev and libgcrypt are required for the Scapy Extension Patch.
Also note that this is a fairly advanced and un-friendly attack platform. This is not Cain & Abel. It is intended for developers and advanced analysts who are attacking ZigBee and IEEE 802.15.4 networks. I recommend you gain some understanding of the ZigBee protocol (the book
ZigBee Wireless Networks and Transceivers by Shahin Farahani is reasonable, though still not great) and familiarity with the Python language before digging into this framework.
INSTALLATIONKillerBee uses the standard Python 'setup.py' installation file. Install KillerBee with the following command:
# python setup.py install
DIRECTORIESThe directory structure for the KillerBee code is described as follows:
- doc - HTML documentation on the KillerBee library, courtesy of epydoc.
- firmware - Firmware for supported KillerBee hardware devices.
- killerbee - Python library source.
- sample - Sample packet captures, referenced below.
- scripts - Shell scripts used in development.
- tools - ZigBee and IEEE 802.15.4 attack tools developed using this framework.
REQUIRED HARDWAREThe KillerBee framework is being expanded to support multiple devices. Currently there is support for the River Loop ApiMote, Atmel RZ RAVEN USB Stick, MoteIV Tmote Sky, TelosB mote, and Sewino Sniffer.
Support for Freaklab's Freakduino with added hardware and the Dartmouth arduino sketch, Zigduino, and Sewio Sniffer board is available but are not listed below as they are not maintained.
ApiMote v4beta (and v3):The devices typically come preloaded and do not need to be reflashed for basic use.
The hardware is open-source at
https://github.com/riverloopsec/apimote. It is available assembled by contacting team at riverloopsecurity dot com.
This is currently supported for beta, and supports sniffing, injection, and jamming.Texas Instruments CC2530/1 EMK:This USB dongle is produced by Texas Instruments and is sold as an evaluation kit for their CC2530 or CC2531 integrated circuit.
It can be purchased from electronics distributors, or directly from them
here.
This is currently supported for beta, and supports sniffing only.MoteIV Tmote Sky or TelosB mode:This device can be loaded with firmware via USB. Attach the device, and then within killerbee/firmware, run:
$ ./flash_telosb.sh
These boards can be obtained via multiple distributors, however
this vendor has stated that their "clone" of the original hardware is compatible. We have not tested nor do we endorse any specific "clone".
Atmel RZ RAVEN USB Stick:See
http://www.atmel.com/tools/RZUSBSTICK.aspx. This hardware is convenient as the base firmware is open source with a freely-available IDE. The KillerBee firmware for the RZ RAVEN included in the
firmware/
directory is a modified version of the stock firmware
distributed by Atmel to include attack functionality.
The RZ RAVEN USB Stick is available from common electronics resellers for approximately $40/USD:
The stock firmware shipped with this hardware allows you to leverage the passive functionality included in the KillerBee tools and framework (such as receiving frames), but does not allow you to do packet injection, or to impersonate devices on the network.
In order to get the full functionality included in KillerBee, the RZ RAVEN USB Stick must be flashed with the custom firmware included in the
firmware/
directory.
See firmware/README.md
for details.TOOLSKillerBee includes several tools designed to attack ZigBee and IEEE 802.15.4 networks, built using the KillerBee framework. Each tool has its own usage instructions documented by running the tool with the "-h" argument, and summarized below.
Additional tools, that are for special cases or are not stable, are stored in the Api-Do project repository:
http://code.google.com/p/zigbee-security/ and at
https://github.com/riverloopsec/beekeeperwids.
FRAMEWORKKillerBee is designed to simplify the process of sniffing packets from the air interface or a supported packet capture file (libpcap or Daintree SNA), and for injecting arbitrary packets. Helper functions including IEEE 802.15.4, ZigBee NWK and ZigBee APS packet decoders are available as well.
The KillerBee API is documented in epydoc format, with HTML documentation in the doc/ directory of this distribution. If you have epydoc installed, you can also generate a convenient PDF for printing, if desired, as shown:
$ cd killerbee
$ mkdir pdf
$ epydoc --pdf -o pdf killerbee/
The pdf/ directory will have a file called "api.pdf" which includes the framework documentation.
To get started using the KillerBee framework, take a look at the included tools (zbdump and zbreplay are good examples to get started) and the simple test cases in the t/ directory.
Since KillerBee is a Python library, it integrates well with other Python software as well. For example, the Sulley library is a fuzzing framework written in Python by Pedram Amini. Using the Sulley mutation features and KillerBee's
packet injection features, it is staightforward to build a mechanism for generating and transmitting malformed ZigBee data to a target.