KillerBee
The Python framework for attacking IEEE 802.15.4 and Zigbee. Sniff, inject, replay, and recover a network key from a capture of a device joining.
KillerBee is the reference toolkit for IEEE 802.15.4 and Zigbee security work. It is a Python framework plus a set of command-line tools, and it does the three things the protocol requires: capture, inject, and extract keys.
The tools
zbid list attached capture hardware and their device strings
zbstumbler active scan: beacon-request across channels, map networks
zbdump capture to a pcap, like tcpdump for 802.15.4
zbreplay replay a previously captured frame
zbdsniff recover a network key from a capture of the key transport
zbwireshark live capture piped into Wireshark
zbconvert convert between capture formats
zbgoodfind search a memory dump for a key
A normal session is zbstumbler to find which channel the network is on, then zbdump on that channel, then Wireshark to read what came out.
Channels
802.15.4 in the 2.4 GHz band uses channels 11 to 26, and this is the first thing to get right. Most hardware listens to exactly one at a time, so scanning means hopping and dwelling. Channels 15, 20 and 25 are the ones that sit between Wi-Fi channels and are therefore preferred by installers, which is a useful prior when you are hunting.
The key attack
Zigbee's security rests entirely on the network key. KillerBee's most valuable capability is recovering it, and the reason it works is a design compromise in the joining process:
When a device joins, the trust centre sends it the network key. In many deployments that transport is encrypted with a default, publicly known trust-centre link key. zbdsniff reads a capture, finds the key transport frame, decrypts it with the known default, and prints the network key.
That turns the whole attack into a timing problem: you need a capture of a device joining. Either you wait for one, or you cause one, which is why forcing a rejoin is a standard step. With the key, Wireshark decrypts everything and you can issue any zcl command you like, because ZCL has no authentication of its own.
Hardware
KillerBee needs a radio it can put in promiscuous mode and, for injection, one that will transmit arbitrary frames. Support is per-device and firmware-dependent:
- nRF52840 dongle with the appropriate firmware. Cheap, current, widely available.
- ApiMote, purpose-built for KillerBee, best injection support, harder to obtain.
- CC2531 USB dongles with sniffer firmware. Very cheap, capture-oriented, injection support is limited.
- RZUSBstick, the historical reference, long out of production.
zbid is what tells you whether your device is actually recognised, and it is worth running before assuming a capture problem is a channel problem.
Pitfalls
- Not every device supports injection. Many sniffer firmwares are receive-only, and a
zbreplaythat appears to do nothing usually means exactly that. - Capture without the key is limited. You see addresses, frame counters, timing and topology; payloads stay opaque.
- Frame counters break naive replay. A stack that tracks the counter rejects a replayed frame, which is what
replay-attackis about. - KillerBee is Python 2 heritage. Use the maintained fork and expect some tooling friction.
- Transmitting on 2.4 GHz affects real networks around you. Keep it to your own devices and a controlled space.
What it pairs with
zigbee and zcl are the protocol, nrf52840-dongle the usual radio, wireshark the decoder, and replay-attack explains why a capture is not always enough.